gentle-pi 4.0.0 → 4.2.0

package/assets/orchestrator-tracking.md

@@ -0,0 +1,53 @@
+# Orchestrator — ODD Tracking (lazy-loaded)
+
+Bind this to the parent Pi session only. Load it when a task is large (its resume test fails) or the user asks to track it; small tasks never need it (see `orchestrator.md` Task Size).
+
+### Organic Driven Development (ODD)
+
+These instructions apply to all development work. Preserve the existing direct/delegated topology and one parent owner; do not introduce an ODD CLI, specialized agent, or execution harness.
+
+#### Authorization and progress
+
+Investigation, explanation, review, comparison, and proposal-only requests remain read-only: no writer, apply, or implementation artifacts. Ambiguous or conditional change intent (unclear whether a change is authorized at all) requires one clarification; stop and wait. Hedged delivery wording (the user may stop you, review commits one at a time, or pick the work up later) asks for resumable notes and separate commits, not a stop; complete every authorized task in the current turn unless the user explicitly says to wait. Research findings and automatic execution pace never authorize mutations.
+
+Size every task by the always-on Task Size section (`orchestrator.md`); 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. Follow `orchestrator-memory.md` for the file and full Engram recovery copy, automatic updates, truthful checkoffs, and resume. Keep the parent responsible for reconciliation; bounded workers receive the document locator, task IDs, linked `S#`, authorized scope and checks, not authority over unrelated tasks; they read the document until `## Log` before edits and report which `S#` they covered. A rejected or resumed handoff is repaired and resent with the same content, never shortened. Reproduce a user-reported failure by running the reported example before deciding it already works; reading code is not reproduction. Close gate: before the final answer, if any tracked task in the feature document or `todo` is still pending, continue it or quote the exact user sentence that orders the stop. One **Needs your decision** result naming the open blockers or missing proof is also a valid stop.
+
+Use about 400 authored changed lines per ODD task only as a planning heuristic, counting additions plus deletions. Keep 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; follow repository policy.
+
+#### Research depth without a new phase
+
+Recommend optional research only for a named uncertainty. Establish the problem, intended outcome, constraints, and current evidence; inspect relevant code. Adapt depth to uncertainty and consequence: no 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 URLs or code locations; distinguish verified facts, assumptions, contradictions, freshness, and gaps. If tools are unavailable, disclose limitations without inventing access or evidence. If research is declined, continue within authorized scope only where safe without the missing evidence; pause only unsafe decisions dependent on it.
+
+Return concise findings, recommendation, tradeoffs, open questions, and implementation implications. Offer a concise proposal only when a real scope or product decision needs it. Neither research nor a proposal is mandatory. Forward these research instructions to an existing fresh general exploration/research worker through the existing delegation mechanism; do not create a specialized agent or create a new workflow. Research remains read-only and requires no 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 with this challenge.
+
+Before building, validate any consequential premise whose failure would invalidate the approach. Reuse relevant findings from sibling investigations instead of repeating the same exploration; verify only what is stale or materially different. During iteration, run focused checks for the behavior being changed, then run the applicable full suite at closure. This sequencing guides effort rather than imposing a token counter or skipping required checks.
+
+#### Checks and candidate consent
+
+For behavior changes with applicable runnable deterministic tests and a clear expected outcome, use test-first by default: observe RED before implementation, GREEN after minimum implementation, relevant alternate cases, then REFACTOR with focused checks still passing. Test or framework presence alone does not establish applicability. For passive documentation, non-testable changes, an unavailable runner, or no meaningful RED, state why and run proportionate ordinary functional or structural verification; never invent RED/GREEN or skip checks. No TUI toggle or per-task chat choice activates this policy. Forward this policy, the applicable exact runner and commands (when available), and any exception rationale on every implementation delegation; refresh on resume. Record observed evidence or the reason for fallback in the feature document.
+
+Run applicable functional checks per task; a TODO checkbox never triggers a review cycle. The native review candidate is a work-unit commit or a PR slice, never a TODO checkbox and never the accumulated feature branch, and native review runs at that work-unit commit or PR slice boundary, not every task update. Checklists grant no approval or receipt and never skip an existing delivery gate.
+
+#### Signaling the ODD phase to the Gentle prompt
+
+When the Gentle Shell prompt is active, its working label is inferred automatically from the primary session's tool activity: read-only tools show `exploring`, edits `implementing`, test/typecheck/lint/build runs and native review `checking`, user questions `deciding`, and `todo` or feature-document edits `planning`. `gentle_odd_phase` refines that label with phases tools cannot show (for example `authorizing`, `researching`, `deciding`, `closing`); an explicit report survives following read-only tool calls, while a stronger inferred phase (`deciding`, `planning`, `implementing`, `checking`) replaces it. Call `gentle_odd_phase` only when the primary session's own ODD phase actually changes, never per tool call, per thought, or on a fixed cadence; call it with `clear` only to leave the current phase before its turn ends. Its bounded vocabulary covers the ODD protocol steps above, not a strict one-to-one mapping: `authorizing` (1), `exploring` (2), `researching`/`deciding` (3), `deciding` again for step 4's classify decision (no dedicated label), `planning` (5), `implementing` (6), `checking`/`closing` (7). This is a best-effort UI label, not a source of truth: with no inferred or reported phase it falls back to a generic working indicator, unknown tools and ambiguous shell commands leave it unchanged, and an invalid token never clears an already-reported phase. Never call it from a subagent or background/child task; it reports only the primary session's own phase.
+
+When RDD is enabled, first use native candidate risk assessment through `gentle_review` with `{"operation":"assess"}`; after each work-unit commit, assess it with that same call and `{"baseRef":"<last reviewed boundary>","committedOnly":true}`. Passive/low: silent structural checks, no reviewer or consent ceremony, and the boundary advances. High, or an unavailable or failed assessment: the commit itself is the candidate; start native review on it right away at that base with `gentle_review` `{"operation":"start"}` and the same `baseRef`/`committedOnly: true` input. Medium: defer to the PR slice, the commits accumulated since the last reviewed boundary, bounded by the delivery budget of about 400 authored changed lines, and review at slice close; native review runs only on grant, and a decline continues under ordinary policy. The first boundary is the branch point, and every reviewed boundary becomes the next base. Record per task the assessed tier and outcome: granted, declined, passive, deferred to slice, or unavailable. Do not substitute model judgment, task size, or defect severity for prospective candidate risk; never infer low risk from a failed assessment. Follow the mirrored provider contract and native continuations; this paragraph introduces no lifecycle route. When RDD is disabled, do not start or prompt for RDD; ordinary checks remain. A checklist or assumption challenge never enables RDD, replaces its refuter, or answers consent. Raise a candidate you know is high risk with the assess `escalate` field (`orchestrator-verification.md`); never lower one.
+
+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 using the ordered oversized-delivery menu; `auto-chain` asks only for a missing chain strategy and slices automatically with a cached choice. When a choice is needed on either chaining path, offer exactly these three semantic outcomes in order:
+
+1. **Feature/tracker branch chain** — `chain_strategy=feature-branch-chain`.
+2. **Verified default/main branch chain** — `chain_strategy=stacked-to-main`; verify the destination's default branch rather than assuming its name.
+3. **One single PR — least recommended** — `delivery_strategy=single-pr`.
+
+Generate the complete user-facing question and every option label, description, and recommendation marker in the active user's conversation language (English for an English user, Spanish for a Spanish user, etc.). Machine strategy tokens remain unchanged and untranslated. These English examples are illustrative and localizable, not mandatory copy.
+
+The third choice overrides the pending chaining path: clear the chain choice as inapplicable and suppress later chain prompts. `single-pr` is not a `chain_strategy` token; do not automatically select `exception-ok`. Explain that an oversized single PR increases reviewer load, delays feedback, and couples rollback; least recommended applies only to this oversized menu, not focused ≤400-line single PRs. Follow the destination repository's documented contribution/size policy: `size:exception` is a Gentle-owned repository policy, not a universal label requirement. Never request or add it for generic users unless their destination policy uses it; preserve required maintainer acceptance and protected-label authorization. A single PR needs no tracker, child dependency diagram, or Chain Context. Shape selection does not authorize push, PR creation, merge, or review-mode/consent changes. Cache both choices, and record slice boundaries, which commits each pull request holds, in the feature document when chaining; for single PR, record the whole-PR scope instead. Resolve the `work-unit-commits` and `chained-pr` skills by registry name, never hardcode their paths.
+
+## Delivery strategy
+
+Use the ODD delivery strategy and work-unit boundaries under Checks and candidate consent above. Push, PR creation, and merge remain human decisions.

package/assets/orchestrator-verification.md

@@ -0,0 +1,28 @@
+# Orchestrator — Verification (lazy-loaded)
+
+Bind this to the parent Pi session only. Load it when the Verification rule fires (a high-risk change) or a delegated writer returns; the small path never needs it.
+
+## Verification rule (normative)
+
+5. **Verification rule** (gentle-pi#661/#662, verify-always-rdd-high S1; normative -- referenced, not restated, in the other orchestrator modules): The bounded writer always runs the exact parent-authorized commands under the delegated task's `## Verification` heading, synchronously and in the foreground, and reports each as `<command>: <observed result>` -- see `gentle-ai-worker`'s Verification contract for the exact rules, including how `## Known environmental failures` (exact pre-existing base failures) differs from any other failing required command, which still forces `status: partial`. Those foreground commands are live work, not silence: while a tool call is in flight the runner's stall watchdog uses `tool_stall_timeout_ms` (default 30 minutes) instead of the `stall_timeout_ms` idle budget. After the writer returns, call `gentle_review` with `{"operation":"assess"}` over the writer's diff and follow the returned plan, whatever the `Receipt-driven development:` line reads (`on`, `off`, or `unknown`), instead of judging non-triviality from the task description: the operation resolves the native risk tier and states exactly who verifies next. When the line reads `on`, the native review is an additional outside view of the change; it never replaces or skips the tier's verification, and the tier's verifier runs before review. Pass `nativeReviewOutcome` when the parent already knows it; ASSESS derives `closed` only from the native `candidate.consumed` fact for this exact candidate (gentle-pi#1175), so a caller-supplied `closed` is not authority and, without that fact, resolves to `unknown`; the outcome only explains the plan, never lowers it. The tier table (stated once, here):
+
+| Native risk tier | Verification (any RDD state) |
+|---|---|
+| 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 |
+
+The small-model bias raises the tier by one for verification purposes (medium becomes high); an unknown `Receipt-driven development:` line never lowers a tier below `off`. The parent spot check (re-running one reported command before delivery) stays required in every tier. ASSESS takes the writer profile from the runtime-recorded model and effort of the pending mutations for the root; caller `writerModelId`/`writerEffort` are only a fallback when no runtime evidence exists, and a missing model, a `mini` model token (`gemini` is not mini), or `low` effort keeps the conservative small-model bias. When native reports them, ASSESS also projects `reviewDue`, `reviewDueReason`, `candidate.consumed`, and the native continuation verbatim; relay that continuation unchanged and never rebuild it. A native code review is not a substitute for applicable functional checks: tests, builds, and functional verification such as browser checks for UI changes still run when applicable, and review outcomes never authorize delivery. The change's own focused test and suite run inline; a small task needs no separate verifier unless it is high risk.
+
+## Agent escalation (gentle-shell#1494)
+
+When the change touches a Task Size high-risk item and the native tier is passive or medium, pass `"escalate": {"item": <1-6>, "reason": "<one line>"}` in the same assess input: the tool raises the tier to high, keeps the native one as `nativeRisk`, returns `agentEscalation`, and never lowers a tier. Until the installed gentle-ai assess accepts it, the raise binds this verification plan only, not the native review tier.
+
+## Parallel review protocol (gentle-shell#1731)
+
+1. **Self-review**, required by each writer prompt, in its own session before returning: spec sections by reference (#1713), the request's authorized examples, tests, and typecheck; it fixes and continues (one correction per failing check, a second only if the same check still fails, then `partial`), reporting requirement by requirement. Low and medium risk need nothing else.
+2. **Independent verify per unit**, once, after its final self-review (never per worker cycle or retry), in parallel when several finish together, only when that unit is high risk: its Risk line, `assess` over its actual diff or the worker's own `escalate` (high-risk list in Task Size; small-model bias per the tier table), never inferred from the worker's summary alone. Assess per unit via its work-unit commit (`{"baseRef":"<previous>","committedOnly":true}`) or its own isolated worktree. Same-model inline code over several deliveries of one feature: one verify at the feature's end; smaller-model writer code stays per unit.
+3. **Seam check**: after parallel units finish, one inline full-suite command (the parent spot check) catches seams between units.
+4. **Verify handoff**: the whole feature document (every `S#`, never one task), the baseline commit, and the probe command forms (tests, CLI, typecheck) for probes on isolated state in a fresh `mktemp -d` scratch copy, never just "read-only"; `gentle-ai-verify` holds the checklist. Resolve every unmet item before closing; the writer commits its probes as regression tests.
+5. **One correction**: verify blockers get one correction batch that fixes every reported blocker, then one re-verify limited to those blockers, never a new full sweep. Blockers still open after that stop as one **Needs your decision**. Advisories never start a correction. A second correction runs automatically only when the recheck shows the same blocker still failing; a new finding never earns one. A `partial` or `blocked` writer report gets only this correction, never an extra verify run beyond the risk tier's verifier; partial, blocked, unavailable, or exhausted proof left after it becomes that one **Needs your decision**.

package/assets/orchestrator-writer.md

@@ -0,0 +1,38 @@
+# Orchestrator — Writer Handoff (lazy-loaded)
+
+Parent Pi session only. Load it when the Writer rule fires or an explicitly activated Judgment Day fix batch is dispatched; small tasks never need it. The Writer rule fires on a named reason (parallel units, the context backstop), never on size alone or a price ratio: a large task without a reason stays inline, following its logbook. Configured per-agent models (`subagents.json` `model_profiles`) still apply to every writer it launches. Each writer prompt requires the self-review of the Parallel review protocol in `orchestrator-verification.md`. A reason holds only when the launch delivers it:
+
+- **Parallelism**: with the Background subagent policy on, launch every disjoint unit in the same turn via `subagent_run` with `mode: "background"`, then wait for all completions before the Seam check; serial launches void the reason: if units cannot launch together, work inline.
+
+#### Allowed edit surfaces (MANDATORY)
+
+The bounded writer refuses to write outside the exact allowed edit surfaces and stops with `status: interaction_required` when they are missing. The parent derives them while planning the delegation; neither the writer nor the human supplies them.
+
+Before launching a bounded writer (`gentle-ai-worker`, a user-configured `worker`, or the native `Agent` fallback), derive the allowed edit surface from the delegated task — files the change must touch, plus directories where it authorizes new files — and pass it in the prompt under an `## Allowed edit surfaces` heading, in the exact-path form of `## Skills to load before work`:
+
+- exact repository-relative paths or narrow globs, one per line; never `.` and never a bare repository root; paths containing whitespace require whole-entry backticks (for example, ``- `Directory With Spaces/note.md` ``); a list marker alone does not permit whitespace;
+- the section ends only at the next canonical ATX Markdown heading of any level (zero to three leading ASCII spaces, one to six `#`, then an ASCII space); every non-empty line before that heading must be a valid surface entry, so put explanatory prose under a following heading;
+- pre-existing untracked targets the writer may write, listed explicitly;
+- nothing beyond the delegated task — a surface wider than the task is the same defect as no surface at all.
+
+If the surface genuinely cannot be derived, do not launch the writer or ask the human to author paths. Derive a candidate set first — the exact paths this task would touch — and present that enumerated list as an approve/decline choice under the Lossless Blocking Prompts rules in `orchestrator-prompts.md`. A free-text question asking which paths or globs to authorize is never a valid escalation: computing it is the parent's job.
+
+Relay a writer's `interaction_required` payload about edit surfaces the same way: present its derived candidate paths as the choice, and add or drop paths only on the human's explicit instruction.
+
+#### Judgment Day fix dispatch
+
+Use `jd-fix-agent` only for an explicitly activated Judgment Day fix batch, never as a lexical or generic-writer fallback. 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. Its dispatch carries 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
+```

package/assets/orchestrator.md

@@ -1,6 +1,6 @@
 # el Gentleman Orchestrator
 
-Bind this to the parent Pi session only; subagents receive bounded task instructions.
+Bind this to the parent Pi session only; subagents get bounded task instructions.
 
 ## Identity Contract
 
@@ -24,54 +24,57 @@ Public/contextual comments and replies are different from technical artifacts. W
 
 Subagent-facing English delegation and quote/UI exceptions: `orchestrator-delegation.md`.
 
-## Mental Model
+## Task Size
 
-el Gentleman is an ecosystem configurator and harness layer. After installation, the user should not memorize workflows or manually wire agents. The package should get out of the way:
+A task is **small** when all three hold:
 
-- Small request: do it directly.
-- Substantial authorized work: use ODD; track feature progress automatically.
-- Parent session orchestrates; phase agents execute.
+1. **Understood** — outcome, what and where to change known; no product or design decision is open; proven in one bounded read batch (at most 3 calls, ~10k tokens).
+2. **Contained risk** — no high-risk item below.
+3. **Resumable from the diff** — resume test: if the session stopped now, someone could finish from the original request and `git diff` alone.
 
-Delegation is not optional once complexity appears. If a task crosses the triggers below, use the smallest useful subagent workflow instead of continuing as a monolithic executor.
+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, external waits, separate deliverables, requirements compaction could lose); large tasks get ODD tracking and workers only by the Writer rule, else inline.
 
-## Work Routing Ladder
+Small path: inline (parent; `bash_background` policy); 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; `todo` optional. It needs no lazy asset.
 
-Route ODD work through the smallest safe harness:
+**High risk**: a mistake would be hard to detect, hard to undo, or reaches beyond the change: (1) data or irreversible effects (migrations, rewriting or deleting stored data, format changes, writing data without validation; not saving new records); (2) security (auth, permissions, credentials, secrets, guards, sandbox); (3) changing or removing contracts others already consume (public API, CLI flags, config formats, exports, mirrored prompts; not adding a flag, command or optional field; requested changes are not; unrequested breaks in shared code are); (4) concurrency; (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 and native assess returns a tier, that tier wins.
 
-1. **Inline Direct** — small, mechanical, parent has context (typo, one-file edit, read-only check within the evidence budget, bash for state); stop when it is no longer small.
-2. **Simple Delegation** — exploration → `gentle-ai-explore`; bounded implementation → `gentle-ai-worker`; command-running 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.
+**Risk line**: close every code change, small path or delegated, with `Risk: item N (reason)` or `Risk: none` per the list; any item → Verification rule.
 
-ODD (Default Workflow, harness section above) is mandatory on every request; detail: `orchestrator-delegation.md`, `orchestrator-memory.md`. For behavior changes with applicable runnable deterministic tests and a clear expected outcome, use test-first by default: observed RED, GREEN, then refactor with checks. For passive documentation, non-testable changes, an unavailable runner or no meaningful RED, state why and run proportionate ordinary functional or structural verification instead. Test presence alone is not applicability; no chat or TUI toggle activates this policy.
+ODD (Default Workflow, harness section above) is mandatory on every request, with the harness's applicable test-first policy (RED, GREEN, refactor); detail: `orchestrator-delegation.md`, `orchestrator-memory.md`.
 
 ## Delegation Rules
 
 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.
+Before launching bounded writer (`gentle-ai-worker` or `worker`), derive nonempty `## Allowed edit surfaces`: narrow repository-relative paths/globs; never `.`, bare repo root, or absolute. Do not ask the human to author paths or globs.
 
-Mandatory Delegation Triggers — once fired, delegate through the best available runtime (prefer `subagent_run`, else native `Agent`):
+## Mechanisms
 
-1. **Evidence-budget rule** — read inline only if evidence fits one parallel batch (at most 3 calls, ~10k tokens; grep and line ranges, never whole large files). Larger reads, >~5 sequential lookups, or a long session ahead → one scout/explorer returning at most ~2k tokens with `path:line` evidence; re-read nothing it covered beyond one spot check. Never force delegation for a small targeted question.
-2. **Multi-file write rule** — 2+ non-trivial files touched → delegate one writer.
-3. **Incident rule** — diagnose wrong cwd/worktree/git/tooling incidents separately before resuming work.
-4. **Context backstop** — parent context past ~150k tokens → pause and delegate the next bounded unit of work. Keep command output bounded (counts, `--stat`, `tail`); full suites and builds go to a verifier.
-5. **Verification rule** — executing/delegating verification commands → `gentle-ai-verify`; only a read-only check within the evidence budget stays inline.
+Mandatory Delegation Triggers — each mechanism turns on only by its own trigger and is then mandatory (prefer `subagent_run`; role missing/unusable: native `Agent`, same read-only constraints; report fallback). When it resolves, re-evaluate task size.
 
-{{GENTLE_PI_BACKGROUND_POLICY}}; rules: the background-subagents block in the delegation contract.
+1. **Ask** — open product or design decision → one focused question; stop and wait.
+2. **Evidence-budget rule** — understanding needs more than one read batch or >~5 sequential lookups → one `gentle-ai-explore`, handoff at most ~2k tokens with `path:line` evidence; one spot check only; never for reading before an inline write.
+3. **Verification rule** — high risk → independent `gentle-ai-verify` after the change's own checks (`orchestrator-verification.md`); otherwise checks run inline.
+4. **Track** — large task → feature document, Engram mirror, `todo`, work-unit commits (`orchestrator-tracking.md`, `orchestrator-memory.md`).
+5. **Writer rule** — never by file count or a large task alone; only for a reason (`orchestrator-writer.md`): 2+ independent units, disjoint files, each heavier than a subagent start, launched together in background, else inline; Context backstop.
+6. **Incident rule** — diagnose wrong cwd/worktree/git/tooling incidents separately before resuming.
+7. **Context backstop** — parent context past ~150k tokens → delegate the next bounded unit. Bound command output (counts, `--stat`, `tail`).
 
-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`.
+{{GENTLE_PI_BACKGROUND_POLICY}}; rules: delegation background-subagents block.
+
+Per-action table, Work Routing Ladder, Canonical Workflows: `orchestrator-delegation.md`; blocking-prompt relays and provider defects: `orchestrator-prompts.md`.
 
 ## Memory Contract
 
-When memory is available, the parent selects context and subagents save discoveries before returning. ODD task continuity and memory lifecycle: `orchestrator-memory.md`.
+With memory, the parent selects context; subagents save discoveries before returning. ODD task continuity and memory lifecycle: `orchestrator-memory.md`.
 
 ## Skill Registry Protocol
 
-The parent resolves skill paths once per session under `## Skills to load before work`; subagents read those `SKILL.md` files first, or report unavailable paths. Fallback semantics (`paths-injected`/`fallback-registry`/`fallback-path`/`none`): `orchestrator-skills.md`.
+The parent resolves skill paths once per session under `## Skills to load before work`; subagents read those `SKILL.md` files first (`paths-injected`) or report unavailable paths; fallbacks: `orchestrator-skills.md`.
 
 ## Intent-Driven Skill Discovery
 
-For skill-shaped requests, treat `<available_skills>` as a discovery aid only, never overriding a concrete ask. Discovery order and intent hints: `orchestrator-skills.md`.
+For skill-shaped requests, `<available_skills>` is a discovery aid only, never overriding a concrete ask. Discovery order and intent hints: `orchestrator-skills.md`.
 
 ## Gentle AI RDD ownership
 
@@ -82,5 +85,6 @@ This package injects the mirrored provider-bundle review execution contract into
 - 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.
+- Parallel writers only with disjoint Allowed edit surfaces (runtime-enforced) or isolated worktrees.
+- Keep session work inside the project root and registered same-clone worktrees; ask before any read or write outside it, naming the absolute path. Grants are per-target, per-session, never blanket: in-project scripts naming outside paths are not standing consent.
 - Preserve human control: user decisions beat agent momentum.

package/assets/sounds/LICENSE.md

@@ -0,0 +1,52 @@
+# Original notification tones
+
+`success.wav`, `error.wav`, and `attention.wav` are original synthetic sine tones,
+created for Gentle AI in 2026. No recording, sample library, audio API, or third-party
+composition was used. Mono PCM, 16-bit, 22050 Hz; amplitude 4000/32768, short fades.
+No platform listening verification has been performed; these are generated assets,
+not evidence of working playback. Linux/macOS adapters require manual verification;
+Windows playback is intentionally unavailable pending a safe native adapter.
+
+## Reproduction recipe (Python 3 standard library)
+
+Run from repository root. This reproduces only the three WAV assets:
+
+```python
+import math, struct, wave
+from pathlib import Path
+root = Path('assets/sounds')
+root.mkdir(parents=True, exist_ok=True)
+for name, frequencies in {'success': (660, 880), 'error': (330, 220), 'attention': (880, 880, 880)}.items():
+    samples = []
+    for frequency in frequencies:
+        count = 2646
+        for i in range(count):
+            envelope = min(1, i / 220, (count - 1 - i) / 440)
+            samples.append(round(4000 * envelope * math.sin(2 * math.pi * frequency * i / 22050)))
+        samples.extend([0] * 661)
+    with wave.open(str(root / (name + '.wav')), 'wb') as out:
+        out.setnchannels(1); out.setsampwidth(2); out.setframerate(22050)
+        out.writeframes(struct.pack('<' + 'h' * len(samples), *samples))
+```
+
+## MIT License
+
+Copyright (c) 2026 Gentle AI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/engram-guard

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Gentle Shell's Engram guard. A bundled Gentle Shell points ENGRAM_BIN here
+# when memory is disabled (unknown store compatibility or a missing bundled
+# core) and the user selected neither ENGRAM_BIN nor ENGRAM_URL. Providers reach
+# local Engram data only by running ENGRAM_BIN, so failing here stops them
+# before any store is opened, created or migrated. It never runs Engram and
+# never reads or writes Engram data; the notice is printed as data, not run.
+printf '%s\n' "${ENGRAM_STARTUP_NOTICE:-Engram memory disabled: Shell could not verify safe store or server reuse. Matching versions or updating alone do not prove compatibility. Reuse requires a server with verified /compatibility evidence or matching Shell-provisioned store identity. Back up existing Engram data before manual changes; do not delete it or bypass the safety check. Shell rechecks on every launch and remains usable without memory.}" >&2
+exit 78

package/bin/gentle-shell-install.mjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+import { spawn as spawnChild } from "node:child_process";
+import * as fsPromises from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, posix, resolve, win32 } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { collectInventory, planPreflight, pnpmGlobalBin, requirements } from "../scripts/installer-preflight.mjs";
+import { createProbes, hostAdapters, userEnvironment } from "../scripts/installer-probes.mjs";
+import { acquireGo } from "../scripts/installer-downloads.mjs";
+import { childEnvironment, goFirstEnvironment, lookPath, packageNativeGentleAi, pnpmInvocation, runStandardInstall, upgradeInvocation } from "../scripts/installer-runner.mjs";
+import { createInstallerServer } from "../scripts/installer-server.mjs";
+import { configHome, mainChannelAdapter, ownerManager, removeGlobalShell, runUpgrade } from "../scripts/main-channel.mjs";
+import { ensureWindowsPnpmHome, windowsWizardEnvironment } from "../scripts/installer-windows.mjs";
+import { pathEntryPlan, prefixLayout, prefixRoot } from "../scripts/bundled-install.mjs";
+import { DISTRIBUTION_RELEASES, bundledGate, bundledPlan, fetchDistribution, migrationGate, runBundledInstall, windowsPathRegistry } from "../scripts/bundled-wizard.mjs";
+
+// Browser installation wizard entry, started by the bootstrap with no argv.
+// Thin wiring only: real probes and adapters, the standard or bundled runner
+// and the loopback host. Exit 0 keeps the bootstrap's tools; nonzero removes them.
+
+/** Fixed per-platform browser opener for a local file, spawned with shell:false; null when none. */
+export function openerFor(platform, file, env) {
+	if (platform === "darwin") return { command: "/usr/bin/open", args: [file] };
+	if (platform === "linux") return { command: "xdg-open", args: [file] };
+	if (platform === "win32") {
+		// Absolute path: Windows would otherwise search the current directory first.
+		const systemRoot = env.SystemRoot ?? env.SYSTEMROOT;
+		if (typeof systemRoot !== "string" || !win32.isAbsolute(systemRoot)) return null;
+		return { command: win32.join(systemRoot, "System32", "rundll32.exe"), args: ["url.dll,FileProtocolHandler", file] };
+	}
+	return null;
+}
+
+function escapeHtml(value) {
+	return String(value).replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char]);
+}
+
+/** Static page that refreshes to the session URL; no script. */
+export function redirectPage(url) {
+	const href = escapeHtml(url);
+	return [
+		"<!doctype html>",
+		'<meta charset="utf-8">',
+		'<meta name="referrer" content="no-referrer">',
+		`<meta http-equiv="refresh" content="0;url=${href}">`,
+		"<title>Gentle Shell installation wizard</title>",
+		`<p><a href="${href}">Continue to the Gentle Shell installation wizard</a></p>`,
+		"",
+	].join("\n");
+}
+
+/**
+ * Writes the redirect page into a fresh private directory (0700, file 0600)
+ * under tempDir, so the one-time code never appears in the opener's argv.
+ * remove() is idempotent and best effort: it deletes the file, then the directory.
+ */
+export async function writeRedirect(url, { tempDir = tmpdir(), files = fsPromises } = {}) {
+	const dir = await files.mkdtemp(join(tempDir, "gentle-shell-install-"));
+	const file = join(dir, "open.html");
+	let removed = false;
+	const remove = async () => {
+		if (removed) return;
+		removed = true;
+		await files.unlink(file).catch(() => {});
+		await files.rmdir(dir).catch(() => {});
+	};
+	try {
+		await files.chmod(dir, 0o700);
+		await files.writeFile(file, redirectPage(url), { mode: 0o600, flag: "wx" });
+	} catch (error) {
+		await remove();
+		throw error;
+	}
+	return { dir, file, remove };
+}
+
+/**
+ * Opens url through a private redirect file with the fixed opener (shell:false,
+ * detached). Returns { file, remove } while the file exists, or null when nothing
+ * was opened; a failed opener removes the file. The printed URL stays the fallback.
+ */
+export async function openBrowser(url, { platform = process.platform, env = process.env, tempDir = tmpdir(), files = fsPromises,
+	spawn = spawnChild } = {}) {
+	// Resolve the opener first so no file is written when there is none.
+	if (openerFor(platform, "", env) === null) return null;
+	let redirect;
+	try {
+		redirect = await writeRedirect(url, { tempDir, files });
+	} catch {
+		return null;
+	}
+	const opener = openerFor(platform, redirect.file, env);
+	try {
+		const child = spawn(opener.command, opener.args, { shell: false, detached: true, stdio: "ignore", windowsHide: true });
+		child.once("error", () => {
+			void redirect.remove();
+		});
+		child.unref();
+	} catch {
+		await redirect.remove();
+		return null;
+	}
+	return { file: redirect.file, remove: redirect.remove };
+}
+
+/** 0 only for a completed installation; blocked, failed or none is 1. */
+export function exitCodeFor(outcome) {
+	return ["ready", "terminal-action-required"].includes(outcome?.outcome) ? 0 : 1;
+}
+
+/** The runner's environment: the user's real PATH, so a temporary bootstrap npm
+ * or node never counts as persistent and globalBin.onPath stays truthful. A
+ * POSIX bootstrap pnpm (passed only through PATH) comes first: the bootstrap
+ * acquired it because the user's pnpm is absent or incompatible, so the user's
+ * is never run. Windows passes pnpm through the GENTLE_INSTALL_PNPM_* handoff.
+ */
+export async function runnerEnvironment({ platform, env, fs }) {
+	const user = userEnvironment({ platform, env });
+	if (platform === "win32") return user;
+	const wizard = await pnpmInvocation(env, platform, fs);
+	if (wizard === null || wizard.prefix.length > 0 || (await pnpmInvocation(user, platform, fs))?.command === wizard.command) return user;
+	const rest = String(user.PATH ?? "").split(posix.delimiter).filter((entry) => entry.length > 0);
+	return { ...user, PATH: [posix.dirname(wizard.command), ...rest].join(posix.delimiter) };
+}
+
+/** An update's children: with a private Windows PNPM_HOME, the runner children's
+ * environment (pnpm's folders, TEMP and TMP inside it); a pinned Go first on PATH.
+ */
+export function upgradeEnvironment({ platform, env, pnpmHome, goPath }) {
+	const globalBin = platform === "win32" && pnpmHome?.source === "private" ? pnpmGlobalBin({ platform, env }) : null;
+	const base = globalBin ? childEnvironment(env, platform, globalBin, { privateHome: true }) : env;
+	return goPath ? goFirstEnvironment(base, platform, goPath) : base;
+}
+
+/** The wizard host's collectPlan and runInstall. Every plan starts from a fresh
+ * preflight. A new release installation whose release publishes the
+ * distribution assets gets the bundled plan (bundledGate) and the bundled
+ * runner; so does an existing Gentle Shell that a global pnpm or npm owns
+ * (migrationGate, S4), whose plan ends by removing that old package with its
+ * own manager. Everything else gets planPreflight and the standard runner, unchanged.
+ * `distributionBase`, `download` and `inventory` are trusted local overrides
+ * for tests and local checks.
+ */
+export function wizardHandlers({ platform, arch, env, run, fs, distributionBase = DISTRIBUTION_RELEASES, download, inventory: inventoryFor }) {
+	// Windows: the PNPM_HOME decision (S6) is made before any probe, on every
+	// preflight. The server re-collects right before an installation, so the
+	// installation uses the decision its consented plan was checked against.
+	let wizard = { env, pnpmHome: null };
+	// The distribution assets the latest bundled plan was made from; the bundled
+	// runner checks them against the consented plan's lockfile sha256.
+	let distribution = null;
+	const decide = () => (wizard = platform === "win32" ? windowsWizardEnvironment({ env }) : { env, pnpmHome: null });
+	// The user's own PATH and home (no bootstrap tools) for the bundled install's PATH entry and setup.
+	const user = userEnvironment({ platform, env });
+	const home = platform === "win32" ? env.USERPROFILE : env.HOME;
+	return {
+		collectPlan: async (channel) => {
+			const { env: wizardEnv, pnpmHome } = decide();
+			// Fresh probes every time: createProbes caches its global package listing.
+			const inventory = inventoryFor ? await inventoryFor(channel)
+				: await collectInventory({ platform, arch, probes: createProbes({ platform, env: wizardEnv, run, fs, pnpmHome }), pnpmHome });
+			// Only a new release installation, or one a global pnpm or npm owns, asks whether its release publishes the assets.
+			const owned = inventory.shell?.available === true && ["pnpm", "npm"].includes(inventory.shell.owner);
+			const assets = channel === "release" && (inventory.shell?.available === false || owned)
+				? await fetchDistribution({ version: requirements.shell, base: distributionBase, ...(download ? { download } : {}) }) : null;
+			const manager = migrationGate({ channel, inventory, distribution: assets, version: requirements.shell });
+			if (manager || bundledGate({ channel, inventory, distribution: assets, version: requirements.shell })) {
+				distribution = assets;
+				// The folder the claim will take (Windows may fall back to the profile), from read-only checks.
+				const layout = prefixLayout({ platform, env: user, home, root: prefixRoot({ platform, env: user }) });
+				return { inventory, plan: bundledPlan({ platform, distribution: assets, layout, path: pathEntryPlan(layout, { platform, env: user, home }),
+					...(manager ? { migrate: { manager, removal: "plan" } } : {}) }) };
+			}
+			return { inventory, plan: planPreflight(inventory, { channel }) };
+		},
+		runInstall: async (request, log) => {
+			const { env: wizardEnv, pnpmHome } = wizard;
+			// npm and pnpm as `gentle-shell upgrade` runs them (a pinned Go first on PATH when given). On
+			// Windows they are the bootstrap's handoff and run without cmd.exe.
+			const managers = (runnerEnv, goPath) => {
+				const upgradeEnv = upgradeEnvironment({ platform, env: runnerEnv, pnpmHome, goPath });
+				const invocation = upgradeInvocation({ platform, env: upgradeEnv, run, fs, handoff: true });
+				return {
+					fetch: globalThis.fetch,
+					fs: fsPromises,
+					which: (name) => lookPath(name, upgradeEnv, platform, fs),
+					...(invocation ? { invocation } : {}),
+					// stderrTail: a failed main build or extraction keeps its bounded stderr as the error's cause.
+					run: (command, argv, options = {}) => run(command, argv, { env: options.env ?? upgradeEnv, cwd: options.cwd, deadlineMs: options.deadlineMs ?? 20 * 60_000,
+						...(options.stderrTail === undefined ? {} : { stderrTail: options.stderrTail }) }),
+				};
+			};
+			const runnerContext = async () => {
+				const runnerEnv = await runnerEnvironment({ platform, env: wizardEnv, fs });
+				return { runnerEnv, ctx: { env: runnerEnv, home: runnerEnv.HOME ?? env.HOME ?? env.USERPROFILE } };
+			};
+			if (request?.plan?.bundled !== undefined) {
+				return runBundledInstall(request, { platform, arch, env: user, home, distribution, log,
+					...(platform === "win32" ? { registry: windowsPathRegistry(env) } : {}),
+					// The consented owner, found again now: the old gentle-pi is removed only with the manager that still owns it.
+					removeGlobal: async (name) => {
+						const located = await createProbes({ platform, env: wizardEnv, run, fs, pnpmHome }).locateShell();
+						if (located?.owner !== name) return false;
+						const { runnerEnv, ctx } = await runnerContext();
+						const adapters = managers(runnerEnv, null);
+						const manager = await ownerManager({ ctx, platform, packageRoot: located.root, adapters });
+						return manager.name === name && removeGlobalShell(manager, adapters.run);
+					} });
+			}
+			const { runnerEnv, ctx } = await runnerContext();
+			return runStandardInstall(request, {
+			platform,
+			nodePath: process.execPath,
+			env: runnerEnv,
+			run,
+			fs,
+			// An existing Gentle Shell: fresh probes find it, `gentle-shell upgrade`'s logic updates it.
+			locateShell: () => createProbes({ platform, env: wizardEnv, run, fs, pnpmHome }).locateShell(),
+			// An older Pi: fresh probes find it before its update and confirm it afterwards.
+			locatePi: () => createProbes({ platform, env: wizardEnv, run, fs, pnpmHome }).locatePi(),
+			// Only a plan with a private Windows PNPM_HOME: claimed, then walked again.
+			preparePnpmHome: (home) => ensureWindowsPnpmHome(home, runnerEnv),
+			// Only a plan that needs Go and found it missing, older or unchecked: verified go.dev
+			// bytes under <config home>/tools/go, used by path or child PATH only.
+			acquireGo: () => acquireGo({ root: join(configHome(ctx), "tools", "go"), platform, arch }),
+			// A pinned Go goes first on the PATH of the upgrade's children only.
+			upgradeShell: async ({ channel, packageRoot, currentVersion, goPath }) => (await runUpgrade({
+				args: ["--channel", channel],
+				ctx,
+				platform,
+				arch,
+				packageRoot,
+				currentVersion,
+				adapters: managers(runnerEnv, goPath),
+				out: () => {},
+			})) === 0,
+			verifyGentleAi: packageNativeGentleAi,
+			// Only a main plan uses it: network access and writes under ~/.pi/gentle-ai.
+			mainChannel: mainChannelAdapter({ fs: fsPromises }),
+			log,
+		});
+		},
+	};
+}
+
+async function main() {
+	const { platform, arch, env } = process;
+	const { run, fs } = hostAdapters();
+	// The redirect file is removed once the code is redeemed, or when the host closes.
+	let redeemed = false;
+	let redirect = null;
+	const host = createInstallerServer({
+		onRedeemed: () => {
+			redeemed = true;
+			void redirect?.remove();
+		},
+		assetsDir: fileURLToPath(new URL("../assets/install-wizard/", import.meta.url)),
+		...wizardHandlers({ platform, arch, env, run, fs }),
+	});
+	let started;
+	try {
+		started = await host.listen();
+	} catch {
+		console.error("The installation wizard could not start its local server. Nothing was installed.");
+		process.exitCode = 1;
+		return;
+	}
+	console.log("Gentle Shell installation wizard");
+	console.log(`Open this link in your browser (it works once and expires in 2 minutes):\n  ${started.url}`);
+	console.log("Press Ctrl+C to stop the wizard.");
+
+	let signalled = false;
+	const stop = () => {
+		signalled = true;
+		host.close("signal");
+	};
+	process.once("SIGINT", stop);
+	process.once("SIGTERM", stop);
+	const opening = openBrowser(started.url).then((opened) => {
+		redirect = opened;
+		// The printed URL may have been redeemed while the file was being written.
+		if (redeemed) void opened?.remove();
+		return opened;
+	});
+	const { reason, outcome } = await host.closed;
+	process.off("SIGINT", stop);
+	process.off("SIGTERM", stop);
+	await (await opening)?.remove();
+	const code = exitCodeFor(outcome);
+	if (outcome?.guidance) console.log(outcome.guidance);
+	else if (reason === "idle") console.log("The wizard closed after 30 minutes without activity. Nothing was installed.");
+	else console.log("The wizard closed without installing anything.");
+	if (signalled) process.exit(code);
+	process.exitCode = code;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+	main().catch(() => {
+		console.error("The installation wizard stopped unexpectedly.");
+		process.exitCode = 1;
+	});
+}