gentle-pi 2.4.0 → 2.6.0

package/assets/orchestrator.md

@@ -41,7 +41,7 @@ Route work through the smallest harness that is safe. Three tiers:
 
 1. **Inline Direct** — small, mechanical, parent has context (typo, one-file edit, read-only check of 1-3 known files, bash for state). No SDD ceremony; stop when it is no longer small.
 2. **Simple Delegation** — generic non-SDD exploration → `gentle-ai-explore`; bounded implementation → `gentle-ai-worker`; command-running generic non-SDD verification → `gentle-ai-verify`. Try its package role; if missing/unusable, use native `Agent` under the same read-only mapping/verification constraints and report fallback. SDD roles stay inside SDD.
-3. **SDD (optional)** — selected only by an explicit request (`/gentle-sdd-new`/`/gentle-sdd-ff`/`/gentle-sdd-continue` or a direct ask) or an accepted proposal; size, file count, or risk alone never selects SDD. Suggest it organically when durable proposal/spec/design/tasks would materially reduce substantial ambiguity. Once selected, do not jump to implementation; create artifacts and gate for approval.
+3. **SDD (optional)** — selected only by an explicit request (`/gentle-sdd-new`/`/gentle-sdd-ff`/`/gentle-sdd-continue` or a direct ask) or an accepted proposal; size, file count, or risk alone never selects it. Suggest it when proposal/spec/design/tasks would meaningfully reduce ambiguity. Once selected, create artifacts and gate for approval before implementing.
 
 ## Delegation Rules
 
@@ -49,7 +49,7 @@ Core question: does this inflate parent context without need?
 
 Before launching bounded writer (`gentle-ai-worker` or `worker`), task/context needs nonempty `## Allowed edit surfaces`: narrow repository-relative paths/globs; never `.`, bare repo root, or absolute. Parent derives surfaces, maps unknown targets read-only, shows derived candidates only for genuine scope choices. Do not ask the human to author paths or globs.
 
-Mandatory Delegation Triggers — stop rules; once fired, delegate through the best available subagent runtime (prefer `subagent_run`, else Pi's native `Agent`):
+Mandatory Delegation Triggers — once fired, delegate through the best available runtime (prefer `subagent_run`, else native `Agent`):
 
 1. **4-file rule** — 4+ files to understand → delegate a scout/mapping task.
 2. **Multi-file write rule** — 2+ non-trivial files touched → delegate one writer.
@@ -59,7 +59,7 @@ Mandatory Delegation Triggers — stop rules; once fired, delegate through the b
 
 {{GENTLE_PI_BACKGROUND_POLICY}}; rules: the background-subagents block in the delegation contract.
 
-Full per-action table, Work Routing Ladder examples/model-routing detail, Cost and Context Balance, Canonical Workflows, and the mirrored gentle-ai canon (blocking-prompt relays, language, and delegation): `orchestrator-delegation.md`.
+Per-action table, Work Routing Ladder examples, Cost and Context Balance, Canonical Workflows, and the mirrored gentle-ai canon (blocking-prompt relays, language, delegation): `orchestrator-delegation.md`.
 
 ## SDD Workflow (lazy-loaded)
 
@@ -73,7 +73,7 @@ Hard preflight invariant: `openspec/config.yaml`, existing SDD changes, installe
 
 ## Memory Contract
 
-When memory is available, the parent selects context and subagents save discoveries before returning. Phase table, artifact keys, persistence: `orchestrator-memory.md`.
+When memory is available, the parent selects context and subagents save discoveries before returning. Phase table and artifact keys: `orchestrator-memory.md`.
 
 ## Skill Registry Protocol
 
@@ -89,7 +89,7 @@ This package injects the mirrored provider-bundle review execution contract into
 
 ## Safety
 
-- For a strictly closed single-select envelope (e.g. `gentle-ai.review-integration.consent/v3`), use `ask_user_choice` when the interactive TUI offers it, passing each label/description with the envelope-owned answer token as `value`, then run the exact provider-owned invocation for the selected answer; otherwise emit the complete envelope as plain chat and stop.
+- An eligible interactive Pi host may resolve `gentle-ai.review-integration.consent/v3` before the envelope reaches the model. Permission: host-owned. If `gentle_review` returns the envelope unresolved, it is still the original provider-owned two-choice contract. Use `ask_user_choice` exactly or relay losslessly and stop. Never add the host action to a decoded or relayed provider envelope.
 - Never commit unless the user explicitly asks.
 - Ask before destructive git operations, publishing, or irreversible file changes.
 - Keep writes single-threaded unless isolated worktrees are explicitly approved.

package/assets/sdd-orchestrator-workflow.md

@@ -22,22 +22,37 @@ proposal → design ┘
 
 ## Native SDD Dispatcher
 
-The user expresses intent; they should not have to administer phases manually. For natural-language SDD requests and `/gentle-sdd-continue`, the parent/orchestrator must use the native status engine as the state authority, decide the next phase, and delegate only the phase that status marks ready.
+`gentle-ai sdd-status --contract gentle-ai.sdd-status/v2` is the sole, read-only status authority for every store. The orchestrator carries its projection unchanged; it never reconstructs readiness, selects a replacement action, uses an Engram bypass, or launches a recommendation merely because status displayed it.
 
-Flow:
+`/gentle-sdd-status` only inspects and renders that projection. Only explicitly authorized `/gentle-sdd-continue` may call native `sdd-continue` to prepare a missing change-instance marker; this is not a status fallback and grants no source roots. If native status is unavailable, malformed, or mismatched, stop and report the failure.
 
-```text
-user intent → preflight/init guard → native status engine → phase decision → subagent gets status JSON + generated instructions → artifact/progress write → status recalculation → continue or stop
-```
+## Bounded Planning Routing
+
+For authoritative native status, route only by the bounded `nextRecommended` token and dependency states; never infer a route from prose. Keep genuine blockers in `blockedReasons` and non-blocking diagnostics in `notes`, never in `nextRecommended`, and report them without discarding them to enable a route.
+
+| `nextRecommended` | Planning route |
+| --- | --- |
+| `propose` | `sdd-proposal` |
+| `spec` | `sdd-spec` |
+| `design` | `sdd-design` |
+| `tasks` | `sdd-tasks` |
+
+Native unprefixed tokens are the only automatic planning routes. Prefixed or locally derived status tokens never authorize a phase.
 
-Rules:
+These planning routes remain runnable when missing planning artifacts leave `dependencies.apply: blocked`; do not require apply readiness to produce those artifacts. This is a planning-only exception, not permission to run apply or another blocked non-planning phase.
 
-- `/gentle-sdd-status` is a debug/status command, not the main UX.
-- `/gentle-sdd-continue` is the native dispatcher command: resolve status, choose the next ready phase, and carry status/instructions into the subagent prompt.
-- `sdd-apply`, `sdd-verify`, `sdd-sync`, and `sdd-archive` must obey parent-provided native status; they must not reconstruct readiness from prompt inference when status JSON is present.
-- Do not launch a phase when native status marks that dependency `blocked`.
-- `sdd-archive` cannot proceed unless native status says `dependencies.archive` is `ready` or `all_done` — UNLESS the store carve-out is active (`nextRecommended: "resolve-via-engram"`), in which case resolve archive readiness from Engram instead of treating `not_applicable` as a gate failure.
-- **Non-authoritative store carve-out:** when `nextRecommended: "resolve-via-engram"` is set, native status is **not authoritative**. This applies to `artifactStore: engram`, `artifactStore: none`, and `artifactStore: both` when the `openspec/` directory does not exist. For non-authoritative stores: resolve readiness 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`, `sdd/{change-name}/design`, `sdd/{change-name}/tasks`, etc.). Do **not** treat `blockedReasons` or `not_applicable` dependency states from the native engine as real blockers when the store carve-out is active.
+Before any planning launch, stop for ambiguous change selection, unresolved session preflight, or unsafe action context. Carry `actionContext` and prove planned writes are within the authoritative workspace or allowed edit roots; workspace-planning without allowed edit roots remains read-only. Planning does not bypass the init guard, pre-proposal gate, or phase approval requirements.
+
+## Bounded Execution Routing
+
+| Native `nextRecommended` | Pi executor |
+| --- | --- |
+| `apply` | `sdd-apply` |
+| `verify` | `sdd-verify` |
+| `remediate` | `sdd-remediate` |
+| `archive` | `sdd-archive` |
+
+Execute only the selected native action when its dependency and `actionContext` permit it. Unknown, malformed, blocked, or unsupported values stop before work; prose and local routing cannot replace them. `notes` is separate from `blockedReasons` and never gates: report a non-empty `notes` value as informational and proceed when the dependency and `blockedReasons` gates allow. Manual sdd-sync deliberately retains its local resolver and is never automatic native-status dispatch.
 
 ## SDD Status Contract
 
@@ -60,11 +75,11 @@ Do not ask SDD setup questions on session start. The first time the user initiat
 
 **Hard gate:** `openspec/config.yaml`, existing SDD changes, installed `.pi`/global SDD assets, or a todo named "preflight" are not session preflight. They are project context only. Do not mark SDD preflight complete, start `sdd-init`, launch SDD subagents/chains, or move to explore/proposal/spec/design/tasks until this session has an injected `## SDD Session Preflight` block or an equivalent resolution from the canonical authority order below.
 
-Resolve each field in this order: (1) explicit current user/session choice, (2) valid persisted preference, (3) capability or already-selected strategy constraint, (4) canonical documented default, and (5) ask only when the field is genuinely unresolved. If `/gentle:sdd-preflight` cannot be invoked, resolve the same order inline; do not recreate a four-question setup prompt. Missing Engram is a capability constraint that resolves the artifact store to `openspec` unless the user has made an incompatible explicit request, which remains a human decision.
+On the first SDD invocation of EACH new interactive session, confirm the preflight choices even when valid preferences are saved. Persisted preferences and canonical defaults are preselected suggestions, not current-session consent. Offer confirmation of the grouped suggestions or changes; cancellation leaves preflight unresolved. Explicit current-session choices take precedence and, once resolved, are reused throughout that session. If `/gentle:sdd-preflight` is unavailable, perform the same confirmation inline. The parent `subagent_run` dispatch boundary resolves this gate for every shipped SDD agent, prepends the exact rendered `## SDD Session Preflight` block to the existing child `context`, and blocks launch on cancellation or failure. An RPC child consumes that transport but never originates or persists defaults; missing or malformed transport fails closed before process spawn. Only a safely distinguishable standalone headless parent may retain canonical/persisted defaults without UI. Missing Engram constrains the artifact store to `openspec` unless an incompatible explicit request needs a human decision.
 
 Preflight canonical defaults are execution `auto`, artifact store `openspec`, delivery strategy `ask-on-risk`, and review budget `400`; capability and already-selected constraints may narrow them.
 
-Selectors/inputs appear only for genuinely unresolved fields. Defaulted and one-option fields do not prompt; persisted/session values are reused, and an explicit current choice overrides them when presented. `chain_strategy` remains deferred, and `exception-ok` requires explicit `size:exception` acceptance and is never inferred.
+The grouped session confirmation includes defaulted and capability-constrained suggestions. If changes are requested, preselect saved values and omit redundant one-option selectors. Never reinitialize project context merely because a new session needs confirmation. `chain_strategy` remains deferred, and `exception-ok` requires explicit `size:exception` acceptance and is never inferred.
 
 The exact `delivery_strategy` domain accepted by `sdd-tasks` and `sdd-apply` is `ask-on-risk`, `auto-chain`, `single-pr`, or `exception-ok`; above the review threshold, `auto-chain` resolves without asking again.
 
@@ -130,7 +145,9 @@ This gate is MANDATORY and applies in both execution modes; in interactive mode
 - The proposer receives a confirmed pre-proposal handoff and MUST NOT interview the user or infer consent.
 - Pi's native `gentle-pi.sdd-status` contract remains the sole status contract. Research and pre-proposal state are orchestrator-owned prose and artifacts (`sdd/{change}/research`, `sdd/{change}/preproposal`, `openspec/changes/{change}/research.md`) layered on top — never a native status field.
 
-Runtime note: this runtime declares no evidence grants (`documentation=[]; open-web=[]`), so a SELECTED research lane fail-closes to a `blocked` outcome and blocks proposal readiness until the user deselects research or evidence capability arrives. SDD chains treat research as unselected.
+Runtime mapping: use the injected `## SDD Research Capabilities` resolved from package-approved exact tool names intersected with active tools. Official documentation requires only `fetch_content`; open-web requires ALL FOUR tools: `web_search`, `source_check`, `fetch_content`, and `get_search_content`, each active and approved/reachable in the child. None is optional; inventory admission is not evidence of execution. Preserve explicit agent/source restrictions. The research child receives only reachable approved names in its CLI allowlist and rechecks child-local availability. Generic `mcp` and dynamic `mcp__context7` gateways do not imply authorization for arbitrary servers or remote methods; without a verified narrow route they grant nothing.
+
+Selected supported research MUST run and persist source-backed claims with exact tool calls, URLs, publisher/version, retrieval times, supporting excerpts and claim-to-source IDs. Tool inventory and search snippets are not evidence. Block only genuinely unavailable classes, retain partial results without unvalidated claims, and keep proposal readiness false until every selected class is complete. Never recommend skipping research because of a fictitious blanket restriction, invent citations, or substitute bash for missing tools. SDD chains treat research as unselected.
 
 ## Delivery Strategy
 
@@ -218,10 +235,10 @@ Never persist caller-authored attempt counters, tokens, or state in OpenSpec art
 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>
+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.
+Every settle field except `evidence-revision` is required: `cwd`, `change`, `token`, `request-id`, `outcome`, `diagnosis`, `harness-disposition`, `cleanup-evidence`, and `process-evidence`. For `failed` or `passed`, include `--evidence-revision` with the `sha256:...` evidence hash. For `interrupted`, omit the entire `--evidence-revision` flag. 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.
 
@@ -256,7 +273,25 @@ On Pi, phase model routing is user-owned and persisted, not prompt-passed: `/gen
 | 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                      |
+| default      | balanced       | SDD phase fallback; never a Judgment Day role |
+
+## Judgment Day fix routing
+
+Judgment Day phase roles are never generic fallbacks. If the generic writer chain is unavailable, use the documented native generic fallback or stop. Judgment Day is independent: it neither enables nor replaces ordinary review; a separately requested ordinary review remains independent. A standalone Judgment Day fix requires no graph-v1 or native review lineage. Launch `jd-fix-agent` only for an explicit Judgment Day fix batch with this exact runtime-accepted Markdown shape: `## Judgment Day activation` contains only `User explicitly requested Judgment Day.`. Replace the example ID, frozen ledger hash, row data, and surface with controller-authorized values. The correction batch contains only one round (`1 of 2` or `2 of 2`) and one lowercase SHA-256. The exact frozen finding rows are one JSON object per line, use only the canonical row fields, and exactly match the authorized IDs.
+
+```markdown
+## Judgment Day activation
+User explicitly requested Judgment Day.
+## Exact authorized severe IDs
+- `JD-A-001`
+## Judgment Day correction batch
+Round: 1 of 2.
+Frozen ledger SHA-256: `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`
+## Exact frozen finding rows
+{"id":"JD-A-001","lens":"judgment-day","location":"path/to/authorized-file.ts:1","severity":"CRITICAL","status_at_freeze":"open","evidence_class":"deterministic","evidence_claim":"Concrete user-impact claim supported by the frozen location."}
+## Allowed edit surfaces
+path/to/authorized-file.ts
+```
 
 ## Sub-Agent Launch Deduplication
 
@@ -310,9 +345,7 @@ 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.
+For every store, request a fresh native v2 status projection. Artifact reads may supply phase inputs only after native selection; they never re-derive readiness, replace status, or bypass native refusal. Manual sdd-sync keeps its separate local resolver.
 
 ## Provider Defect Handoff
 

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

@@ -15,94 +15,43 @@ Any phase that selects, continues, applies, verifies, syncs, or archives an SDD
 
 ## Native Engine
 
-- For file-backed `openspec` or `both` sessions with an `openspec/` directory, use Gentle Pi's local SDD status engine as the artifact-state authority. It resolves the local artifact graph without consulting RDD authority or receipts.
-- For non-authoritative stores (`engram`, `none`, and `both` without an `openspec/` directory), do not treat disk status 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.
+- `gentle-ai sdd-status --contract gentle-ai.sdd-status/v2` is the sole status authority for every store. It is read-only: inspect its native projection unchanged and never launch a phase, prepare consent, or grant roots while reading it.
+- If native status is unavailable, malformed, or does not select the requested change/workspace, stop and report that failure. Do not construct a local status, infer readiness from artifacts, substitute continuation, or bypass it through Engram.
+- `nextRecommended`, `dependencies`, `blockedReasons`, `actionContext`, and optional `phaseInstructions` are producer facts. Route only by their typed values, never by prose or a local lifecycle graph. A genuine blocker's human-readable explanation belongs in `blockedReasons`; a non-blocking diagnostic belongs in `notes`; neither belongs in `nextRecommended`.
+- Runtime-attempt authority is separate from status: runtime-bearing work uses the provider `sdd-attempt acquire|settle` flow and its `proceed`, `blocked`, or `complete` result.
+- Only an explicitly authorized `gentle-ai sdd-continue` may prepare a missing change-instance marker. `ensureChangeInstanceMarker` has no status caller; its sole production path is `PrepareChangeInstanceConsent` through `sdd-continue`.
+
+## Bounded Planning Routing
+
+For authoritative native status, route only by the bounded `nextRecommended` token and dependency states; never infer a route from prose. Keep genuine blockers in `blockedReasons` and non-blocking diagnostics in `notes`, never in `nextRecommended`, and report them without discarding them to enable a route.
+
+| `nextRecommended` | Planning route |
+| --- | --- |
+| `propose` | `sdd-proposal` |
+| `spec` | `sdd-spec` |
+| `design` | `sdd-design` |
+| `tasks` | `sdd-tasks` |
+
+Native unprefixed tokens are the only automatic planning routes. Prefixed or locally derived status tokens never authorize a phase.
+
+These planning routes remain runnable when missing planning artifacts leave `dependencies.apply: blocked`; do not require apply readiness to produce those artifacts. This is a planning-only exception, not permission to run apply or another blocked non-planning phase.
+
+Before any planning launch, stop for ambiguous change selection, unresolved session preflight, or unsafe action context. Carry `actionContext` and prove planned writes are within the authoritative workspace or allowed edit roots; workspace-planning without allowed edit roots remains read-only. Planning does not bypass the init guard, pre-proposal gate, or phase approval requirements.
+
+## Bounded Execution Routing
+
+| Native `nextRecommended` | Pi executor |
+| --- | --- |
+| `apply` | `sdd-apply` |
+| `verify` | `sdd-verify` |
+| `remediate` | `sdd-remediate` |
+| `archive` | `sdd-archive` |
+
+Execute only a native selected action whose dependency and `actionContext` permit it. Unknown, malformed, blocked, or unsupported actions stop before work; no local route, prefixed token, or prose can replace them. `notes` is separate from `blockedReasons` and never gates: report a non-empty `notes` value as informational and proceed when the dependency and `blockedReasons` gates allow. Manual `sdd-sync` remains its intentional local resolver and is never an automatic native-status dispatch.
 
 ## Status Schema
 
-Return status as markdown with these fields, or equivalent JSON when the host supports it:
-
-```yaml
-schemaName: spec-driven
-changeName: <change-name>
-artifactStore: openspec | engram | both | none
-planningHome:
-  root: <project-or-openspec-root>
-  changesDir: <openspec/changes or memory topic prefix>
-changeRoot: <openspec/changes/<change> or memory topic prefix>
-artifactPaths:
-  proposal: [<path-or-topic>]
-  specs: [<path-or-topic>]
-  design: [<path-or-topic>]
-  tasks: [<path-or-topic>]
-  applyProgress: [<path-or-topic>]
-  verifyReport: [<path-or-topic>]
-  syncReport: [<path-or-topic>]
-contextFiles:
-  proposal: [<concrete readable files/topics>]
-  specs: [<concrete readable files/topics>]
-  design: [<concrete readable files/topics>]
-  tasks: [<concrete readable files/topics>]
-  applyProgress: [<concrete readable files/topics>]
-  verifyReport: [<concrete readable files/topics>]
-  syncReport: [<concrete readable files/topics>]
-artifacts:
-  proposal: missing | done | partial
-  specs: missing | done | partial
-  design: missing | done | partial
-  tasks: missing | done | partial
-  applyProgress: missing | done | partial
-  verifyReport: missing | done | partial
-  syncReport: missing | done | partial
-taskProgress: # implementation-owned plus malformed unresolved rows
-  total: 0
-  complete: 0
-  remaining: 0
-  unchecked: []
-deferredParentActions:
-  total: 0
-  complete: 0
-  remaining: 0
-  unchecked: []
-taskArtifactErrors: []
-applyState: blocked | all_done | ready | not_applicable
-dependencies:
-  apply: blocked | ready | all_done | not_applicable
-  verify: blocked | ready | all_done | not_applicable
-  sync: blocked | ready | all_done | not_applicable
-  archive: blocked | ready | all_done | not_applicable
-actionContext:
-  mode: repo-local | workspace-planning
-  workspaceRoot: <absolute path>
-  allowedEditRoots: [<absolute paths>]
-  warnings: []
-nextRecommended: <bounded-machine-token>
-isNonAuthoritative: false  # boolean; true when the native engine is not authoritative for the store
-```
-
-## Task Ownership
-
-New task checkboxes end with the terminal marker `<!-- sdd-owner: implementation -->`. An unmarked legacy checkbox is implementation-owned. Supported legacy non-implementation rows are informational only. Any line containing `sdd-owner` that is unsupported, duplicated, or non-terminal is malformed: add its exact line to `taskArtifactErrors` and `blockedReasons`, and count it as unresolved implementation work even when checked. `taskProgress` reports implementation work.
-
-## Apply State
-
-- `blocked`: required apply artifacts are missing, task selection is ambiguous, malformed ownership markers exist, or action context makes edits unsafe.
-- `all_done`: tasks artifact exists and every implementation task is checked `[x]`.
-- `ready`: tasks artifact exists, at least one implementation task remains unchecked, and edit scope is safe.
-- `not_applicable`: emitted for non-authoritative stores (see Engine Authority by Store). This is NOT a blocker.
-
-## Dependency States
-
-- `apply` is `ready` only when specs, design, and tasks are available and task progress is not all done.
-- `verify` is ready after implementation completion when tasks are complete or apply-progress exists. RDD authority and receipts never gate the apply -> verify -> sync -> archive route. Unchecked implementation tasks remain CRITICAL blockers for full archive readiness.
-- `sync` is `ready` only when verify-report exists and has no unresolved `FAIL`, `BLOCKED`, `CRITICAL`, or verification blockers. `engram`/`none` modes may mark sync `not_applicable`.
-- `archive` is `ready` only when verify-report exists, sync is complete or not applicable, and implementation tasks are complete. CRITICAL verification issues have no override. Explicit recorded exceptions are limited to non-critical partial archives or stale-checkbox reconciliation when apply-progress/verify-report prove completion.
-- `not_applicable`: emitted for non-authoritative stores (engram, none, and both when no `openspec/` directory exists) when `nextRecommended: "resolve-via-engram"` is active. `not_applicable` is NOT a gate failure — readiness must be resolved from Engram instead of from these fields.
+Consume the native v2 projection (`schemaName: gentle-ai.sdd-status`, `schemaVersion: 2`) losslessly. Its producer-defined selection, artifact locators, task progress, seven dependencies, `actionContext`, `blockedReasons`, optional execution instructions, remediation state, and `nextRecommended` are status facts, not a Pi schema to recreate.
 
 ## Action Context Guard
 
@@ -112,11 +61,6 @@ The orchestrator MUST carry `actionContext` into any phase launch.
 - If `allowedEditRoots` is present, only edit or move files within those roots.
 - If a phase cannot prove a file is inside the authoritative workspace or allowed edit roots, stop and ask for clarification.
 
-## Engine Authority by Store
-
-- `openspec` and `both` (when `openspec/` directory exists): the local SDD 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 local 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.

package/contracts/telemetry/runtime-aggregate-v1.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "gentle-ai.telemetry-runtime-aggregate/v1",
+  "description": "Sanitized stdin for gentle-ai telemetry runtime send --json. Maximum UTF-8 input 16384 bytes. One best-effort send attempt, no client persistence or retry. Rows are independent observations, not a session composition. No caller identity is accepted.",
+  "type": "object", "additionalProperties": false,
+  "required": ["schema", "registry", "host", "rows"],
+  "properties": {
+    "schema": {"const": "gentle-ai.telemetry-runtime-aggregate/v1"},
+    "registry": {"const": 1},
+    "host": {"enum": ["claude-code", "opencode", "codex", "pi"]},
+    "rows": {"type": "array", "minItems": 1, "maxItems": 32, "items": {"$ref": "#/$defs/row"}}
+  },
+  "$defs": {
+    "metric": {"oneOf": [{"type": "integer", "minimum": 0, "maximum": 999999999999}, {"type": "null"}, {"const": "unsupported"}]},
+    "count": {"type": "integer", "minimum": 0, "maximum": 999999999999},
+    "token": {
+      "type": "object", "additionalProperties": false,
+      "required": ["reported", "unavailable", "unsupported", "sum"],
+      "properties": {
+        "reported": {"$ref": "#/$defs/count"}, "unavailable": {"$ref": "#/$defs/count"},
+        "unsupported": {"$ref": "#/$defs/count"}, "sum": {"$ref": "#/$defs/count"}
+      },
+      "if": {"properties": {"reported": {"const": 0}}},
+      "then": {"properties": {"sum": {"const": 0}}}
+    },
+    "duration": {
+      "type": "object", "additionalProperties": false, "required": ["kind", "measured_count", "sum_ms"],
+      "properties": {"kind": {}, "measured_count": {}, "sum_ms": {}},
+      "oneOf": [
+        {"properties": {"kind": {"const": "unavailable"}, "measured_count": {"const": 0}, "sum_ms": {"type": "null"}}},
+        {"properties": {"kind": {"enum": ["request", "message"]}, "measured_count": {"type": "integer", "minimum": 1, "maximum": 999999999999}, "sum_ms": {"type": "number", "minimum": 0, "maximum": 999999999999}}}
+      ]
+    },
+    "effort": {"enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max", "not_selected", "unknown", "custom", "unavailable", "unsupported"]},
+    "model": {
+      "type": "object", "additionalProperties": false, "required": ["provider", "id"],
+      "properties": {"provider": {"type": "string"}, "id": {"type": "string"}},
+      "oneOf": [
+        {"properties": {"provider": {"const": "anthropic"}, "id": {"enum": ["claude-opus-5", "claude-haiku-4-5", "claude-haiku-4-5-20251001", "claude-sonnet-5"]}}},
+        {"properties": {"provider": {"enum": ["openai", "openai-codex"]}, "id": {"enum": ["gpt-6-astra", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.3-codex-spark", "gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.2", "gpt-5.3-codex", "gpt-5.6"]}}},
+        {"properties": {"provider": {"const": "opencode"}, "id": {"const": "custom"}}},
+        {"properties": {"provider": {"const": "unknown"}, "id": {"const": "unknown"}}},
+        {"properties": {"provider": {"const": "custom"}, "id": {"const": "custom"}}}
+      ]
+    },
+    "row": {
+      "type": "object", "additionalProperties": false,
+      "required": ["model", "model_evidence", "agent_kind", "agent_class", "selected_effort", "effective_effort", "launches", "responses", "input_tokens", "output_tokens", "cache_read_tokens", "cache_creation_tokens", "reasoning_tokens", "total_tokens", "error_category", "duration"],
+      "properties": {
+        "reasoning_tokens": {"$ref": "#/$defs/token"},
+        "total_tokens": {"$ref": "#/$defs/token"},
+        "agent_class": {"enum": ["orchestrator", "worker", "explore", "verify", "unknown", "sdd-init", "sdd-explore", "sdd-research", "sdd-propose", "sdd-spec", "sdd-design", "sdd-tasks", "sdd-apply", "sdd-verify", "sdd-archive", "sdd-onboard", "sdd-status", "sdd-sync", "jd-judge-a", "jd-judge-b", "jd-fix-agent", "review-risk", "review-readability", "review-reliability", "review-resilience", "review-refuter", "review-validator"]},
+        "error_category": {"enum": ["none", "unknown", "auth", "output_length", "aborted", "api", "rate_limit", "server"]},
+        "duration": {"$ref": "#/$defs/duration"},
+        "model": {"$ref": "#/$defs/model"},
+        "model_evidence": {"enum": ["selected", "response", "unknown"]},
+        "agent_kind": {"enum": ["orchestrator", "built_in", "custom", "unknown"]},
+        "selected_effort": {"$ref": "#/$defs/effort"}, "effective_effort": {"$ref": "#/$defs/effort"},
+        "launches": {"$ref": "#/$defs/metric", "description": "Source-observed event count only; null when not observed. Never reconstructed from sessions."}, "responses": {"$ref": "#/$defs/metric", "description": "Source-observed response occurrence count, independent of token coverage and success."},
+        "input_tokens": {"$ref": "#/$defs/token"}, "output_tokens": {"$ref": "#/$defs/token"},
+        "cache_read_tokens": {"$ref": "#/$defs/token"}, "cache_creation_tokens": {"$ref": "#/$defs/token"}
+      }
+    }
+  }
+}

package/docs/delegated-verification.md

@@ -0,0 +1,25 @@
+# Delegated verification
+
+How the Gentle Pi orchestrator decides who verifies a bounded writer's work. The always-on parent prompt renders a `Receipt-driven development: on|off|unknown` line; the delegation overlay (`assets/orchestrator-delegation.md`, trigger 5) keys the verification rule on it. This page is package-owned; `docs/review-integration.md` mirrors the Gentle AI contract and must stay byte-identical to it.
+
+## Receipt-driven development on
+
+The bounded writer runs the exact commands the parent lists under `## Verification`, in the foreground, and reports each as `<command>: <observed result>`. That report is the verification of record and the native review is the independent check. `gentle-ai-verify` is on-demand: a `partial` or `blocked` writer, an expensive or external check the parent wants on a cheaper profile, or a parent spot check.
+
+This `on` path holds only while the native review actually reaches a terminal outcome for the current candidate (gentle-pi#668). A human decline of the consent envelope for this candidate (candidate-scoped, never the RDD kill switch), a clone-local RDD disable discovered mid-flow, or a refused START/STATUS all mean the review never ran, so the parent falls back to the exact risk-gated path below, as if RDD were `off` -- declining a review never lowers the bar below the RDD-off path. `gentle_review`'s `assess` operation accepts an optional `nativeReviewOutcome` (`closed`, `declined`, `unavailable`, or `unknown`) so the caller can state this directly. `closed` is never auto-derived: only a caller that itself just acknowledged the approved review for this exact candidate may pass it, right after that acknowledgement. When `nativeReviewOutcome` is omitted, `assess` only ever tries to auto-derive `declined`/`unavailable`, and only for the exact candidate the event was bound to -- keyed by that candidate's own target identity, never by repository alone, so one candidate's recorded outcome can never leak into a different candidate's `assess` call in the same clone. A missing or mismatched identity fails closed to `unknown`, verified exactly like `off`. The result's `outcome_source` (`explicit`, `derived`, or `unknown`) states which of these produced the value, so a stale or missing derivation is visible rather than silently indistinguishable from a real `unknown`.
+
+## Receipt-driven development off or unknown (gentle-pi#662)
+
+The host exposes one read-only native operation: `gentle-ai review assess --cwd <repo> [--base-ref <ref> --committed-only] --json` (gentle-ai#4295). It is decoded by `lib/review-risk-assessment.ts` and wired through `lib/native-review-cli.ts` exactly like the existing `reviewMode` STATUS reader -- a bounded subprocess with a typed decode, never a mutation. A non-zero exit, a failure envelope, or an older binary without the verb all fail closed to `high` risk.
+
+The `gentle_review` tool's `assess` operation (`extensions/gentle-ai.ts`) combines that assessment with the rendered `Receipt-driven development:` line to decide whether a delegated writer's change needs a separate `gentle-ai-verify` run, following this tier table:
+
+| Native risk tier | Verification when RDD is `off`/`unknown` |
+| --- | --- |
+| passive | structural readback by the parent; no separate verifier, no tests |
+| medium | writer self-verification stands; a separate `gentle-ai-verify` run is added only when the writer profile is a small model (mini or low effort) |
+| high | writer self-verification plus a separate `gentle-ai-verify` run, always |
+| unknown / assess failed | treated as high |
+
+When RDD is `on` and the native review closed for this candidate, the writer's own self-verification is the record and the closed native review is the independent check, except a passive-risk change, which still gets a structural readback instead; any other `nativeReviewOutcome` under `on` follows this same tier table instead (gentle-pi#668). The small-model bias raises the medium tier to high for verification purposes only; an unknown RDD line never lowers a tier below `off`. The parent's own spot check (re-running one reported command before delivery) stays required in every tier.
+

package/docs/telemetry.md

@@ -0,0 +1,94 @@
+# Telemetry
+
+Runtime usage telemetry is best effort: an available usage event gets at most one
+asynchronous attempt through `gentle-ai telemetry runtime send --json`. Busy,
+failed, disabled, or cancelled attempts are discarded silently. There is no
+metrics disk storage, outbox, retry, backoff, cooldown, daemon, or session reconstruction.
+
+The production encoder uses the byte-identical [native schema mirror](../contracts/telemetry/runtime-aggregate-v1.schema.json).
+[The synthetic fixture](../tests/fixtures/runtime-metrics-native-batches.json) pins its
+SHA-256 and exact one-shot stdin bytes. No old intake fallback is used. These are
+fake-subprocess tests, not a live collector or deployment verification.
+
+## Runtime usage flow
+
+1. A finalized primary assistant message or child completion supplies available usage.
+   Child-host extensions do not independently consume primary usage.
+2. Pi builds event-local sanitized rows, not cumulative session totals. An occupied
+   attempt slot discards the event; it never queues it for later.
+3. One cancellable immediate defers binary verification and subprocess launch beyond
+   the provider callback. The native command owns fresh policy and exactly one POST.
+4. Only `stored`, `duplicate`, `discarded`, or `disabled` results are recognized.
+   All are terminal. `stored` and `duplicate` reflect collector acknowledgement,
+   not client persistence; Pi retains nothing and never retries.
+
+There is no policy or capability subprocess before send, and no ingest or flush call.
+The packaged binary is verified; development overrides are refused for runtime usage.
+Missing binaries and unsupported commands discard without installation or fallback.
+
+Replacement and shutdown cancel an unstarted attempt or request termination of its
+child immediately, without a wait loop or final send. The process slot remains busy
+until actual close, preventing overlap even if a cancelled process is slow to exit.
+A one-second process timeout requests termination; it is not a retry timer or a hard
+bound on synchronous binary verification or event-loop stalls.
+
+## Data and source limits
+
+Wire fields are the schema/registry, host, public model with evidence, available
+selected/effective effort, orchestrator or known built-in subagent class, source
+launch/response occurrence coverage, six token coverages, explicitly reported typed
+duration, and a sanitized error category. Occurrences never represent sessions.
+Prompts, responses, code, paths, private names, source IDs, and raw errors never enter
+the payload. There is no `batch_id`; native creates the remote `delivery_id`.
+
+One event produces 1–32 rows within 16 KiB. Oversized or invalid events discard
+whole rather than splitting into multiple sends. Child launch selection is a separate
+row with zero response-token coverage, never substituted for per-response evidence.
+
+- Token coverage distinguishes reported, unavailable, and unsupported values. Pi's
+  SDK-positive counters are usable; zero defaults and absence do not prove reported zero.
+- Selected model/effort is captured at the request hook, separately from response
+  model and effective-effort evidence. Ambiguous request sequences discard selection.
+- Pi hooks do not correlate requests/retries reliably, so this adapter does not infer duration.
+- Child configuration classification uses packaged built-in definitions, not agent names.
+  Launch configuration is not proof of the model or selected effort of each child response.
+- Bounded live child observations remain in RAM until completion. No completed child
+  event is retained for forwarding. A completion without usage creates no usage send.
+- Primary object deduplication uses weak tombstones; copied objects are distinct.
+  Child completion tombstones are capped at 256 per extension session. Source IDs
+  stay local and are never exported. No session history is read or reconstructed.
+
+## What Gentle Pi does
+
+On activation of a primary session (never for a named agent or an SDD phase executor), Gentle Pi resolves the package-local `gentle-ai` binary (honoring a registered dev-binary override, same as every other native call) and spawns:
+
+```text
+gentle-ai telemetry trigger --json
+```
+
+- detached, with stdout/stderr discarded (`stdio: "ignore"`);
+- a 3 s deadline: a runaway process is killed, but Gentle Pi never waits for it to exit;
+- at most once per process, regardless of how many sessions or sub-agents run afterward.
+
+Rate limiting, enrollment, and every opt-out live entirely in `gentle-ai`; calling the trigger once per session start is safe by construction. A missing binary, an older binary without the `telemetry` verb (which prints `unknown telemetry command` and exits non-zero), or a spawn failure are all treated as "nothing to do" and never affect activation or surface an error to the user.
+
+Install counts for `gentle-pi` and `gentle-engram` come from npm download statistics; neither package emits an install event of its own.
+
+## The trigger contract
+
+`gentle-ai telemetry trigger --json` always exits `0` and prints one line of JSON:
+
+```json
+{"schema":"gentle-ai.telemetry-trigger/v1","decision":"enrolled|sent_install|sent_heartbeat|rate_limited|backoff|disabled","source":"<deciding source>"}
+```
+
+`gentle-ai telemetry status|enable|disable|preview [--json]` exist for the opt-out flow; `status --json` prints `gentle-ai.telemetry-status/v1`. Gentle Pi's `/gentle:telemetry` slash command runs these in the foreground (bounded to 5 s) through the same binary resolver and relays the result.
+
+## Opting out
+
+Any of the following disables the nudge or the underlying telemetry:
+
+- `/gentle:telemetry disable` — asks the local `gentle-ai` binary to disable telemetry. `/gentle:telemetry status` and `/gentle:telemetry preview` inspect it without leaving Pi.
+- `DO_NOT_TRACK=1` — Gentle Pi does not spawn the trigger at all; `gentle-ai` also honors this standard independently.
+- `GENTLE_AI_TELEMETRY=0` — same effect, `gentle-ai`'s own environment switch.
+- `CI=true` — Gentle Pi does not spawn the trigger in automated/CI runs, since they are not a real usage signal.

package/docs/windows-startup-console-visibility.md

@@ -0,0 +1,18 @@
+# Windows Startup Console Capture
+
+Use this protocol to validate the startup Git child processes on a real Windows desktop. Linux CI can verify spawn configuration but cannot observe Windows console windows.
+
+## Capture
+
+1. Start a Windows window-event trace before launching Pi. Capture `EVENT_OBJECT_SHOW`, its timestamp, HWND, owner PID, and owner session.
+2. Deliberately launch a known visible, short-lived console as a positive control. If its show event is absent, the capture is **INCONCLUSIVE**.
+3. Build or install the candidate Gentle Pi package and start `pi` from a repository whose path contains spaces. Leave it idle for at least 10 seconds so the startup identity lookups (`git rev-parse --show-toplevel` and `git rev-parse --git-common-dir`), branch lookup, initial shell scan, and repeated poll run.
+4. Correlate each show event with `GetWindowThreadProcessId`, then use its timestamp, host PID/session, and Procmon process-creation ancestry and command line to associate it with a Pi-launched Git invocation. The HWND can be owned by `conhost.exe`, OpenConsole, or Windows Terminal rather than `git.exe`.
+
+## Expected Result
+
+No `WS_VISIBLE` show event is associated with the Git invocation for the startup identity lookups, banner branch lookup, initial shell scan, or repeated shell polling. A visible show event proves window visibility, not that it was unobscured on screen. Process start alone is not visible-window evidence. If event-to-invocation association cannot be established, report **INCONCLUSIVE**, not pass.
+
+## Scope
+
+This protocol does not cover user-configured external editors. Their inherited-stdio launch is intentional and may open a visible window.