gentle-pi 2.1.2 → 2.2.0

package/README.md

@@ -58,7 +58,7 @@ Most coding-agent sessions fail for operational reasons, not model reasons:
 | **Skill creation workflow**    | Provides the `gentle-ai-skill-creator`/`gentle-ai-skill-improver` skills, `/skill-creation` prompt, and packaged style guide for LLM-first skills. |
 | **Delivery skills**            | Includes issue-first PRs, chained PRs, work-unit commits, cognitive docs, comment writing, and Judgment Day review.                           |
 | **Bounded native review**      | Freezes one candidate, dispatches only controller-selected lenses, records native authority, and reuses the same content-bound receipt at delivery gates. |
-| **Verified native runtime**    | Provisions the exact package-local Gentle AI v2.2.2 runtime: signed archives on Darwin/Linux and a Go SumDB-verified source build on Windows x64/arm64. It validates package-local integrity and rejects PATH, global, sibling, symlink, and mode fallbacks. |
+| **Verified native runtime**    | Provisions the exact package-local Gentle AI v2.4.0 runtime: signed archives on Darwin/Linux and a Go SumDB-verified source build on Windows x64/arm64. It validates package-local integrity and rejects PATH, global, sibling, symlink, and mode fallbacks. |
 | **Runtime safety**             | Blocks destructive shell commands, asks for confirmation for sensitive operations, and blocks direct read/write/edit access to sensitive paths. |
 
 ## Install
@@ -79,7 +79,7 @@ pi install npm:gentle-pi@0.14.0
 pi install npm:gentle-pi@latest
 ```
 
-The latest RDD package installs Gentle AI only into its private `.gentle-ai/` directory. Darwin and Linux use pinned signed archives with archive and executable SHA-256 verification. Windows x64 and arm64 build the exact `v2.2.2` source tag with a local Go 1.25.10+ toolchain, a sealed Go environment, `GOTOOLCHAIN=local`, and `GOSUMDB=sum.golang.org`; it does not download Go automatically. Windows provenance is Go-toolchain plus SumDB evidence and postinstall tamper detection, **not** Authenticode or protection against a malicious joint binary-and-manifest replacement. Package-private locks coordinate cooperative concurrent or crashed installers; their tombstones fail closed. A malicious same-user process with write access to package-private `node_modules` is outside that protocol because it can already replace package code, binary, or manifest, and portable Node has no pathname-delete CAS. It never uses `PATH` or a global `gentle-ai` installation. For development or offline installs only, set `GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1`; native review operations then fail closed with an actionable `package-local-binary-missing` error until the package is reinstalled normally.
+The latest RDD package installs Gentle AI only into its private `.gentle-ai/` directory. Darwin and Linux use pinned signed archives with archive and executable SHA-256 verification. Windows x64 and arm64 build the exact `v2.4.0` source tag with a local Go 1.25.10+ toolchain, a sealed Go environment, `GOTOOLCHAIN=local`, and `GOSUMDB=sum.golang.org`; it does not download Go automatically. Windows provenance is Go-toolchain plus SumDB evidence and postinstall tamper detection, **not** Authenticode or protection against a malicious joint binary-and-manifest replacement. Package-private locks coordinate cooperative concurrent or crashed installers; their tombstones fail closed. A malicious same-user process with write access to package-private `node_modules` is outside that protocol because it can already replace package code, binary, or manifest, and portable Node has no pathname-delete CAS. It never uses `PATH` or a global `gentle-ai` installation. For development or offline installs only, set `GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1`; native review operations then fail closed with an actionable `package-local-binary-missing` error until the package is reinstalled normally.
 
 Recommended companion packages:
 
@@ -107,9 +107,10 @@ pi
 /gentle:status          Check package, SDD assets, OpenSpec, and global model config.
 /gentle:doctor          Run read-only diagnostics for SDD assets, config, tools, and guards.
 /gentle:sdd-preflight   Run or reuse the session SDD preflight explicitly.
-/sdd-init                  Create or refresh openspec/config.yaml.
+/sdd-init                  Create or refresh openspec/config.yaml (openspec/both stores only).
 /gentle:models             Assign global model/effort routing to SDD/custom agents.
 /gentle:persona            Switch between gentleman and neutral persona modes.
+/gentle:background-subagents  Show or set the managed background-subagents policy, with its deciding source.
 /gentle:banner             Configure startup rose, text logo, and color preset.
 /gentle:commit-status      Inspect an unresolved durable commit transaction.
 /gentle:commit-abort       Abandon safe recovery state without changing HEAD or the index.
@@ -165,13 +166,13 @@ parent git/status + clarify → bind ordinary snapshot/route → one worker writ
 
 Review lenses are controller-selected transaction actors, not lifecycle hooks. `scout`/`context-builder` save parent context by compressing broad exploration. `worker` preserves a single writer thread. Commit, push, PR, and release validate receipts with zero actors.
 
-Review actors are dispatched only through parent `subagent_run` calls in `mode: "task"`. Before execution, the controller verifies every entry, content hash, mode, root, and index in one selected immutable candidate tree per requested lens, then appends one bounded controller-owned block containing only the Git-derived base-to-candidate changed scope. That compact scope groups present paths by exact candidate mode and lists deletions explicitly; it fails closed when the changed scope itself exceeds the dispatch bound. Mixed batches, unselected/missing/stale views, user-supplied candidate-view text, unsafe paths, and non-task dispatches fail closed; lean resources and actor tool allowlists remain unchanged.
+Review actors are dispatched only through parent `subagent_run` calls in `mode: "task"`. Before execution, the controller verifies every entry, content hash, mode, root, and index in one selected immutable candidate tree per requested lens, then appends one bounded controller-owned block containing only the Git-derived base-to-candidate changed scope. Readable scopes group paths by exact candidate mode and list deletions explicitly. Larger scopes use a canonical gzip/base64url manifest plus SHA-256; the read-only `gentle_review_scope` actor tool validates and paginates every changed path without traversing the ambient or full candidate tree. Oversized compressed transport, decompressed manifests, or response pages fail closed. Mixed batches, unselected/missing/stale views, user-supplied candidate-view text, unsafe paths, and non-task dispatches also fail closed; review actors retain no shell or mutation tools.
 
 ### Review authority recovery and reset safety
 
 Legacy pre-graph authority is never migrated. `gentle_review inspect` reports an exact repository-bound destructive reset challenge for legacy corruption; after that fresh interactive authorization, RESET and RECOVER_LOCK route to the audited native `gentle-ai review reclaim` operation and RECOVER routes to native `gentle-ai review recover`, so every destructive transition is executed and audited by the native authority store. Native inputs the request did not carry return a `native-input-required` envelope instead of being invented. Existing graph-v1 ordinary lineages remain readable and gate-validatable but are read-only; Judgment Day remains mutable on graph-v1.
 
-`gentle_review abandon`, `quarantine-legacy`, and `reconcile-authority` remain explicit v2.1.11 maintenance routes. Pi derives and displays the published six-line abandon binding only for a caller-specified compact lineage, revision, and snapshot identity; the native CLI re-derives pristine compact-v2 eligibility. Legacy quarantine accepts only `historical findings freeze changed unrelated transaction state` with disposition `quarantine-malformed-freeze-event` and uses its exact eight-line binding. Both require fresh interactive approval and fail closed headlessly.
+`gentle_review abandon`, `quarantine-legacy`, and `reconcile-authority` remain explicit v2.1.11 maintenance routes. Pi derives and displays the published nine-line `gentle-ai.review-abandon-authorization/v2` binding only for a caller-specified compact lineage, revision, snapshot identity, and discarded-work summary (captured lens results, findings presence, evidence-record presence); the native CLI re-derives non-terminal compact-v2 eligibility and the exact discarded work before accepting it. Legacy quarantine accepts only `historical findings freeze changed unrelated transaction state` with disposition `quarantine-malformed-freeze-event` and uses its exact eight-line binding. Both require fresh interactive approval and fail closed headlessly.
 
 `gentle_review reconcile-authority` accepts one predecessor lineage and revision, one successor lineage and revision, an actor, and a reason. Pi derives the exact seven-line `gentle-ai.review-reconcile-authorization/v1` binding, or appends exactly `anomalies=unchanged_target,malformed_recovery_authorization` for the published dual anomaly in that order. Native code re-derives every anomaly; malformed bindings, changed revisions, unavailable native support, cancellation, and native refusal fail closed through typed envelopes.
 
@@ -253,15 +254,15 @@ flowchart TD
 
 Lifecycle gates never launch review actors. They rederive Git and publication targets, validate the existing receipt, and authorize one exact command. Any target drift, stale evidence, malformed authority, or unprovable state blocks delivery instead of silently reopening review.
 
-Native contract pairing is exact: this adapter resolves only the integrity-verified package-local Gentle AI v2.1.11 executable, independently hashes it, then negotiates `gentle-ai.review-integration/v1` outside the repository. Capabilities are cached by that executable digest. Every START, target status, FINALIZE, validate, and BIND-SDD request passes the same contract identifier. Current protocol 1.0 envelopes decode exactly against the vendored schemas; `recover` routes only the provider-selected `action_disposition`, and optional additions require a future compatible schema/minor that the provider explicitly advertises and the consumer negotiates.
+Native contract pairing is exact: this adapter resolves only the integrity-verified package-local Gentle AI v2.4.0 executable, independently hashes it, then negotiates `gentle-ai.review-integration/v2` outside the repository. Capabilities are cached by that executable digest. Every START, target status, FINALIZE, validate, and BIND-SDD request passes the same contract identifier. Negotiated envelopes decode exactly against the vendored schemas; `recover` routes only the provider-selected `action_disposition`, and optional additions require a future compatible schema/minor that the provider explicitly advertises and the consumer negotiates.
 
-Gentle AI also publishes a second negotiated contract, `gentle-ai.review-integration/v2`, which replaces the Base64 `candidate_diff` reviewer transport with immutable `base_tree`/`candidate_tree` plus an ordered `changed_path_manifest` and never an inline patch. `gentle-pi` is migrating to `/v2` only, with no dual-lane fallback; the cutover is release-gated on the pinned runtime confirming it serves contract v2 (already true for the currently pinned v2.2.1) and lands as one atomic commit, tracked by the `migrate-review-integration-v2` change. This provider contract version is unrelated to Pi's own internal "compact-v2" review-authority naming used below — the shared digit is coincidental, not a version pairing.
+Contract `/v2` replaces the Base64 `candidate_diff` reviewer transport of `/v1` with immutable `base_tree`/`candidate_tree` plus an ordered `changed_path_manifest` and never an inline patch. `gentle-pi` negotiates `/v2` only, with no dual-lane fallback; the cutover landed as one atomic commit against gentle-ai v2.2.2 (tracked by the `migrate-review-integration-v2` change), and the `/v1` schemas stay packaged because the `/v2` schemas `$ref` into their fragments. This provider contract version is unrelated to Pi's own internal "compact-v2" review-authority naming used below — the shared digit is coincidental, not a version pairing.
 
 Target status owns `current_target`, `unrelated`, `ambiguous`, and `corrupted` applicability and returns one native action. Pi does not reconstruct ordinary authority from provider-private files or choose a lineage from repository-wide history. Restart recovery rebuilds only the derived candidate view from the native Git/content projection, including intended-untracked paths, symlinks, and immutable gitlink identities. Native failure envelopes retain their exact mutation outcome, replayability, required inputs, request digest, and next action. After an unknown or lost mutating result, Pi calls target status before any replay decision and returns only the provider-declared action.
 
 Direct authorized `git commit` commands use a durable recovery record under the Git common directory. The package runs the effective pre-commit hook once, captures the post-hook index, performs final native validation against that tree, suppresses only the already-completed pre-commit hook while preserving message/post hooks through proxies, and proves `HEAD^{tree}` before the tool result succeeds. Any unresolved, interrupted, failed, or mismatched transaction blocks push, PR, and release. Recovery never resets HEAD or the index automatically.
 
-Once the pinned gentle-ai runtime (currently v2.2.1) has written review authority, rollback MUST preserve every native store and receipt and MUST NOT run a downgraded binary against that repository. Disable the Pi route or roll forward to a compatible authority-aware release instead; deleting authority data or reinstalling an older binary is not a rollback path.
+Once the pinned gentle-ai runtime (currently v2.4.0) has written review authority, rollback MUST preserve every native store and receipt and MUST NOT run a downgraded binary against that repository. Disable the Pi route or roll forward to a compatible authority-aware release instead; deleting authority data or reinstalling an older binary is not a rollback path.
 
 ### FINALIZE wrapper input
 
@@ -334,7 +335,7 @@ SDD completion adds no review or Judgment Day pass.
 
 Review operations, validation, and SDD perform no push, PR creation, release, or publication. The separate durable commit runner may create exactly one local commit only after final native pre-commit validation and post-commit tree proof.
 
-`review-refuter` uses exactly `read`, `grep`, and `find` in a package-managed isolated installation. Project and user overrides may shadow the package asset; `gentle-pi` preserves those definitions and does not claim their effective permissions are package-compliant.
+Adversarial review roles (the refuter and the targeted validator) are never Pi-authored: the provider renders self-contained `review.capture-refuter` / `review.capture-validation` vectors and Go runs its own locked-down `pi` process on them. Package agent assets remain a package-managed isolated installation. Project and user overrides may shadow a package asset; `gentle-pi` preserves those definitions and does not claim their effective permissions are package-compliant.
 
 ## SDD/OpenSpec flow
 
@@ -594,11 +595,12 @@ Legacy string entries are still accepted and treated as `model`-only config.
 | `/gentle:doctor`              | Runs read-only diagnostics for SDD assets, model/persona config, memory tools, and safety guards. |
 | `/gentle:models`                 | Opens global model + effort assignment UI. Press `x` to export and `r` to restore saved routing. |
 | `/gentle:persona`                | Switches global persona mode, with project override support.        |
+| `/gentle:background-subagents`   | Shows or sets the managed background-subagents policy (`status\|enable\|disable`), naming the source that decided it. |
 | `/gentle:banner`                 | Configures startup banner rose, text logo, and color preset.        |
 | `/gentle:toggle-rose`            | Toggles the startup rose.                                           |
 | `/gentle:toggle-text-logo`       | Toggles the startup text logo.                                      |
 | `/gentle:banner-color`           | Selects a startup banner color preset.                              |
-| `/sdd-init`                      | Initializes or refreshes `openspec/config.yaml`.                    |
+| `/sdd-init`                      | Initializes or refreshes `openspec/config.yaml` (openspec/both stores only). |
 | `/gentle:install-sdd`         | Repairs missing global SDD runtime assets without overwriting files. |
 | `/gentle:install-sdd --force` | Force-refreshes installed global SDD assets.                         |
 | `/skill-registry:refresh`        | Regenerates `.atl/skill-registry.md`.                               |
@@ -606,6 +608,29 @@ Legacy string entries are still accepted and treated as `model`-only config.
 
 Package-owned global SDD runtime assets are also refreshed automatically on session start when `gentle-pi` changes. Project-local `.pi/agents` and `.pi/chains` remain manual overrides and are never overwritten by startup refresh.
 
+### Background subagents policy
+
+Background delegation is off unless you turn it on. The policy is user-owned: only an explicit `/gentle:background-subagents enable` or `disable` writes it, and Pi automation never toggles it.
+
+```text
+/gentle:background-subagents           Report the effective policy, the deciding source, and the resolved capability.
+/gentle:background-subagents enable    Write "on" to the global file.
+/gentle:background-subagents disable   Write "off" to the global file.
+```
+
+Four sources can decide the policy, and the first hit wins:
+
+| Priority | Source                                            | Notes                                                        |
+| -------- | ------------------------------------------------- | ------------------------------------------------------------ |
+| 1        | `<cwd>/.pi/gentle-ai/background-subagents.json`   | Project file. Outranks everything, including a global write.  |
+| 2        | `<configHome>/background-subagents.json`          | Global file, written by `enable`/`disable`. `configHome` honors `GENTLE_PI_CONFIG_HOME` and defaults to `~/.pi/gentle-ai`. |
+| 3        | `GENTLE_PI_BACKGROUND_SUBAGENTS`                  | Exactly `on` or `off`. Any other value is ignored.            |
+| 4        | Built-in default                                  | `off`.                                                        |
+
+Both files use the strict shape `{"schema":"gentle-pi.background-subagents/v1","policy":"on"}`. A file that is present but malformed fails closed to `off` and is **not** skipped in favor of a lower-priority source, so a typo in the project file disables background subagents rather than silently handing the decision to the global file. The command reports that case as a warning instead of an ordinary `off`.
+
+Because the project file outranks the global one, `enable` still writes the global file but reports plainly when a project file keeps the effective policy unchanged. The resolved capability (`ready` or `absent`) reports whether `subagent_run` is actually callable in this session; a policy of `on` with capability `absent` means the subagents package is not installed.
+
 Startup banner settings are global and default to the current pink rose + text logo. Supported color presets are `pink`, `cyan`, `yellow`, and `green`.
 
 Startup flag:
@@ -666,12 +691,16 @@ Memory contract for SDD delegation:
 | `extensions/startup-banner.ts` | Shows and configures the startup intro, color presets, compact runtime panel, and collaboration credit.     |
 | `extensions/sdd-init.ts`       | Registers `/sdd-init` for OpenSpec initialization.                                                         |
 | `extensions/skill-registry.ts` | Maintains `.atl/skill-registry.md` from project/user skills and closes file watchers on shutdown.          |
-| `assets/orchestrator.md`       | Parent-session orchestration contract.                                                                     |
+| `assets/orchestrator.md`       | Parent-session orchestration contract (always-on core).                                                    |
+| `assets/orchestrator-delegation.md` | Lazy-loaded delegation/routing/review detail, including the mirrored gentle-ai canon.                 |
+| `assets/orchestrator-memory.md` | Lazy-loaded SDD memory phase table, artifact keys, and lifecycle rule.                                    |
+| `assets/orchestrator-skills.md` | Lazy-loaded skill registry fallback semantics and intent-driven skill discovery.                          |
+| `assets/sdd-orchestrator-workflow.md` | Lazy-loaded SDD workflow surface for the parent orchestrator.                                       |
 | `assets/agents/`               | SDD agents installed as global Pi runtime assets.                                                          |
 | `assets/chains/`               | SDD chains installed as global Pi runtime assets.                                                          |
 | `assets/support/`              | Strict TDD support docs for apply/verify phases.                                                           |
 | `skills/`                      | Gentle AI delivery and collaboration skills.                                                               |
-| `prompts/`                     | Gentle-prefixed prompt templates, including `/skill-creation`.                                             |
+| `prompts/`                     | The `/skill-creation` prompt template.                                                                     |
 | `docs/skill-style-guide.md`    | Normative style guide used by the packaged skill creation/improvement skills.                              |
 | `docs/native-authority-architecture.md` | Post-U8 ownership boundary, reproducible slimming metrics, Windows evidence, exact #191 seam, and the `review-integration/v1`→`v2` migration status, including the "compact-v2" naming disambiguation.     |
 | `docs/review-integration.md`   | Negotiated provider/consumer contract and the current Gentle Pi adoption boundary.                         |
@@ -695,6 +724,35 @@ node --experimental-strip-types --check extensions/startup-banner.ts
 npm pack --dry-run
 ```
 
+### Running the cross-lane battery
+
+The cross-lane battery (`tests/crosslane/cross-lane.mjs`) validates the adapter against a real `gentle-ai` binary, end to end and out of CI on purpose. The pinned decoder lane only ever sees vendored fixtures, so new envelope schemas and full controller sequencing are never driven through a live lifecycle before merge; the battery closes that gap.
+
+```bash
+pnpm test:cross-lane                # requires the dev-binary override
+pnpm test:cross-lane --with-model   # adds the real Go-owned pi reviewer run (model spend)
+```
+
+What it checks, against live scratch repositories:
+
+- a low-risk lifecycle from START to a `pre-commit` gate allow;
+- the medium-risk `consent/v3` granted round-trip through the direct decoder lane;
+- controller sequencing: at every step the client's decoded offered next step must equal the native transition, including that correction evidence is collected before targeted validation is ever offered, through a full correction lifecycle to an approved receipt;
+- the audited abandon end to end, asserting the adapter builds the exact nine-line `gentle-ai.review-abandon-authorization/v2` discarded-work binding and the native gate commits the quarantine record;
+- forward-decoder freshness: every live envelope captured from the binary must decode without unknown-key rejection, the early warning that gentle-ai main grew a field gentle-pi lacks;
+- with `--with-model`, one real locked-down `pi` reviewer run captured through the native transport.
+
+Prerequisites:
+
+- A real `gentle-ai` binary selected through the dev-binary override; there is no PATH or pinned-binary fallback, and the battery refuses to run without one. Either export `GENTLE_PI_GENTLE_AI_DEV_BINARY=<absolute path>` for the session, or register a persistent override with `/gentle:dev-binary <absolute path>` (stored at `~/.pi/gentle-ai/dev-binary.json` with schema `gentle-pi.dev-binary/v1`; the environment variable takes precedence over the registration, and the binary is re-validated and re-hashed on every resolution). Any real build works: an installed release binary or a locally built gentle-ai main.
+- A Git checkout or worktree of this repository. The battery is a contributor tool wired to the repository layout and is excluded from `pnpm test` and CI by construction; run it from the repo, not from an installed Pi package.
+
+The battery creates throwaway scratch repositories under the OS temp directory and never touches the enclosing repository. The default run spends no model tokens; `--with-model` launches one real reviewer model run and costs model spend.
+
+It prints one PASS/FAIL/SKIP row per check plus a note, and exits non-zero when any check fails. Checks blocked by a known upstream class are reported with a `known-red` prefix instead of being hidden.
+
+Running this battery against new gentle-ai builds (release candidates or main) and reporting red checks is a valuable contribution. The sibling provider-side battery lives at `scripts/cross-lane-battery.sh` in [Gentleman-Programming/gentle-ai](https://github.com/Gentleman-Programming/gentle-ai).
+
 Publish npm through GitHub Actions only:
 
 ```bash

package/assets/agents/gentle-ai-worker.md

@@ -20,10 +20,10 @@ Use this agent only for scoped implementation work that is too large for the par
 Before repository work:
 
 1. Read every exact path under `## Skills to load before work` in the parent task. Do not rediscover the skill registry.
-2. Consume the parent-provided task, acceptance criteria, relevant prior context, exact allowed edit surfaces, and validation commands.
+2. Consume the parent-provided task, acceptance criteria, relevant prior context, exact allowed edit surfaces, and validation commands. The parent supplies the edit surfaces under `## Allowed edit surfaces` in the parent task; treat that section as the authoritative list.
 3. Inspect the working tree and preserve pre-existing changes. Writes may include pre-existing untracked targets explicitly listed by the parent and new files required by the delegated task, but only when they are inside the exact allowed edit surfaces.
 4. Preserve every unrelated tracked or untracked file. Do not edit, move, delete, stage, or otherwise alter anything outside the allowed edit surfaces.
-5. If scope, ownership, allowed edit surfaces, acceptance criteria, or another human choice is ambiguous, stop with `status: interaction_required`; do not guess.
+5. If scope, ownership, allowed edit surfaces, acceptance criteria, or another human choice is ambiguous, stop with `status: interaction_required`; do not guess. Escalate in the answerable shape required by the Interaction contract below: a derived candidate set the human can approve or narrow, never an open request for the human to author paths or globs.
 
 Do not read persistent memory for context. The parent selects and forwards relevant observations.
 
@@ -67,6 +67,10 @@ Run focused tests first. Broad suites, builds, formatters, or linters may run on
 
 When any human input is required, stop editing and return the full schema in the Return contract with `status: interaction_required` and the nested `interaction_required` payload completed. Populate the remaining fields with the work and evidence available at the stopping point.
 
+Every interaction must be answerable from the payload alone. State the concrete choices in `options` as a closed set the human can approve, decline, or select from, and never ask the human to author paths, globs, identifiers, or commands as free text.
+
+When the missing input is the allowed edit surface, derive the candidate set before stopping: put the exact repository-relative paths the delegated task would touch in `options`, and ask the human to approve that list or name which entries to drop. Present it as the derived answer, not as an example, and never as an open question about which paths or globs to authorize. If the delegated task gives no basis for even a candidate list, say that plainly in `reason` and name the missing evidence in `unblock_response`.
+
 Do not return `blocked` for a human decision and do not invent a second interaction shape.
 
 ## Return contract
@@ -92,7 +96,7 @@ skill_resolution: paths-injected | paths-invalid | none
 interaction_required: <include only when status is interaction_required>
   question: <same deterministic interaction question>
   reason: <same deterministic blocking reason>
-  options: <same meaningful choices and tradeoffs, when applicable>
+  options: <same closed set of concrete choices; for a missing edit surface, the derived candidate paths>
   unblock_response: <same exact context needed to continue>
 ```
 

package/assets/agents/jd-fix-agent.md

@@ -4,7 +4,7 @@ description: Judgment Day surgical fix agent for confirmed findings. Can edit co
 tools:
   - read
   - grep
-  - glob
+  - find
   - edit
   - write
   - bash

package/assets/agents/jd-judge-a.md

@@ -5,7 +5,7 @@ tools:
   - "*": false
   - read
   - grep
-  - glob
+  - find
   - bash
 ---
 
@@ -34,6 +34,8 @@ Initial discovery and scoped re-judgment are separate modes.
 
 During initial discovery, run exactly once against the supplied `initial_review_tree` and return candidate rows only.
 
+Sweep budget: run one exhaustive read-only sweep, then stop — at most two sweeps for a full-4R-scale target (hot auth/update/security/payments paths, or more than 400 changed lines). There is no loop-until-dry mechanism; the sweep budget is the entire discovery pass.
+
 During initial discovery, do not persist state, mutate claims, launch actors, request fixes, validate fixes, or deliver anything.
 
 On controller-requested scoped re-judgment, receive only requested frozen IDs, their exact hash-bound rows, and the fix diff.

package/assets/agents/jd-judge-b.md

@@ -5,7 +5,7 @@ tools:
   - "*": false
   - read
   - grep
-  - glob
+  - find
   - bash
 ---
 
@@ -34,6 +34,8 @@ Initial discovery and scoped re-judgment are separate modes.
 
 During initial discovery, run exactly once against the supplied `initial_review_tree` and return candidate rows only.
 
+Sweep budget: run one exhaustive read-only sweep, then stop — at most two sweeps for a full-4R-scale target (hot auth/update/security/payments paths, or more than 400 changed lines). There is no loop-until-dry mechanism; the sweep budget is the entire discovery pass.
+
 During initial discovery, do not persist state, mutate claims, launch actors, request fixes, validate fixes, or deliver anything.
 
 On controller-requested scoped re-judgment, receive only requested frozen IDs, their exact hash-bound rows, and the fix diff.

package/assets/agents/review-readability.md

@@ -5,9 +5,12 @@ tools:
   - "*": false
   - read
   - grep
-  - glob
+  - find
+  - gentle_review_scope
 ---
 
+> Manual/compat-lane only: the provider host-relay capture path never loads this agent definition; native lens capture materializes the Go-issued opaque prompt through the gentle-pi host relay.
+
 You are **R2 Readability**, a read-only reviewer. Find clarity problems; do not fix them.
 
 Rule sources: ai-course-2 slides `05-code-smells.md`, `06-safe-refactoring.md`, `07-advanced-refactoring.md`, `08-tech-debt.md`, `22-docs-as-code.md`, `25-executive-summary.md`.

package/assets/agents/review-reliability.md

@@ -5,9 +5,12 @@ tools:
   - "*": false
   - read
   - grep
-  - glob
+  - find
+  - gentle_review_scope
 ---
 
+> Manual/compat-lane only: the provider host-relay capture path never loads this agent definition; native lens capture materializes the Go-issued opaque prompt through the gentle-pi host relay.
+
 You are **R3 Reliability**, a read-only reviewer. Find test and behavior risks; do not fix them.
 
 Rule sources: ai-course-2 slides `01-testing-setup.md`, `02-tdd-implementation.md`, `03-integration-testing.md`, `04-e2e-testing.md`, `10-strategic-coverage.md`, `11-playwright-visibility.md`, `12-quality-gates-husky.md`, `23-apis-components.md`.

package/assets/agents/review-resilience.md

@@ -5,9 +5,12 @@ tools:
   - "*": false
   - read
   - grep
-  - glob
+  - find
+  - gentle_review_scope
 ---
 
+> Manual/compat-lane only: the provider host-relay capture path never loads this agent definition; native lens capture materializes the Go-issued opaque prompt through the gentle-pi host relay.
+
 You are **R4 Resilience**, a read-only reviewer. Find operational failure risks; do not fix them.
 
 Rule sources: ai-course-2 slides `09-essential-metrics.md`, `13-observability-strategy.md`, `14-sentry-implementation.md`, `15-sentry-errors.md`, `16-sentry-performance.md`, `17-sentry-alertas.md`, `29-performance-percibida.md`.

package/assets/agents/review-risk.md

@@ -5,9 +5,12 @@ tools:
   - "*": false
   - read
   - grep
-  - glob
+  - find
+  - gentle_review_scope
 ---
 
+> Manual/compat-lane only: the provider host-relay capture path never loads this agent definition; native lens capture materializes the Go-issued opaque prompt through the gentle-pi host relay.
+
 You are **R1 Risk**, a read-only reviewer. Find security risks; do not fix them.
 
 Rule sources: ai-course-2 slides `18-env-secrets.md`, `19-web-security.md`, `20-auth-tokens.md`, `21-owasp-top10.md`.

package/assets/agents/sdd-apply.md

@@ -4,7 +4,7 @@ description: Implement SDD tasks with strict TDD evidence and review workload gu
 tools:
   - read
   - grep
-  - glob
+  - find
   - edit
   - write
   - bash
@@ -146,3 +146,8 @@ Rules:
 - Before returning, re-read the persisted tasks artifact and ensure completed tasks are visibly marked `- [x]`; internal todos are not completion evidence.
 
 Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.
+
+
+## Key Learnings Closing
+
+Close your final report text with a `## Key Learnings` block (no trailing colon). Use 1–5 numbered items, each a standalone factual sentence of at least 20 characters and at least 4 words. This applies to final report text only — not intermediate tool output or saved artifact content. The Engram memory provider automatically extracts and persists these items as passive capture; you do not parse the block or invoke passive-capture tools yourself. Omit the block when there is genuinely no reusable learning; no filler or speculation. This closing block is separate from explicit `mem_save` artifact/decision persistence.

package/assets/agents/sdd-archive.md

@@ -4,7 +4,7 @@ description: Archive a verified SDD change into OpenSpec source specs.
 tools:
   - read
   - grep
-  - glob
+  - find
   - write
   - edit
   - bash
@@ -200,3 +200,8 @@ Include:
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
 
 Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.
+
+
+## Key Learnings Closing
+
+Close your final report text with a `## Key Learnings` block (no trailing colon). Use 1–5 numbered items, each a standalone factual sentence of at least 20 characters and at least 4 words. This applies to final report text only — not intermediate tool output or saved artifact content. The Engram memory provider automatically extracts and persists these items as passive capture; you do not parse the block or invoke passive-capture tools yourself. Omit the block when there is genuinely no reusable learning; no filler or speculation. This closing block is separate from explicit `mem_save` artifact/decision persistence.

package/assets/agents/sdd-design.md

@@ -4,7 +4,7 @@ description: Design the technical approach for an SDD change.
 tools:
   - read
   - grep
-  - glob
+  - find
   - write
   - edit
   - mem_search
@@ -38,3 +38,8 @@ Persist this phase's artifact to the active backend before returning (mandatory)
 - `none`: return the design inline.
 
 Never claim persistence you did not perform.
+
+
+## Key Learnings Closing
+
+Close your final report text with a `## Key Learnings` block (no trailing colon). Use 1–5 numbered items, each a standalone factual sentence of at least 20 characters and at least 4 words. This applies to final report text only — not intermediate tool output or saved artifact content. The Engram memory provider automatically extracts and persists these items as passive capture; you do not parse the block or invoke passive-capture tools yourself. Omit the block when there is genuinely no reusable learning; no filler or speculation. This closing block is separate from explicit `mem_save` artifact/decision persistence.

package/assets/agents/sdd-explore.md

@@ -4,10 +4,9 @@ description: Explore an SDD change idea before proposal.
 tools:
   - read
   - grep
-  - glob
+  - find
   - edit
   - write
-  - webfetch
   - mem_save
 ---
 
@@ -37,3 +36,8 @@ Persist this phase's artifact to the active backend before returning (mandatory)
 - `none`: return the exploration inline.
 
 Never claim persistence you did not perform.
+
+
+## Key Learnings Closing
+
+Close your final report text with a `## Key Learnings` block (no trailing colon). Use 1–5 numbered items, each a standalone factual sentence of at least 20 characters and at least 4 words. This applies to final report text only — not intermediate tool output or saved artifact content. The Engram memory provider automatically extracts and persists these items as passive capture; you do not parse the block or invoke passive-capture tools yourself. Omit the block when there is genuinely no reusable learning; no filler or speculation. This closing block is separate from explicit `mem_save` artifact/decision persistence.

package/assets/agents/sdd-init.md

@@ -5,7 +5,7 @@ model: openai-codex/gpt-5.3-codex
 tools:
   - read
   - grep
-  - glob
+  - find
   - write
   - edit
   - bash
@@ -24,21 +24,29 @@ Use your assigned executor/phase skill for this SDD phase. For project/user skil
 If skill paths are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `paths-injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should pass indexed paths next time.
 
 - Inspect the project stack, test runner, conventions, and existing docs.
-- If `openspec/config.yaml` is missing, create it automatically with project context, `strict_tdd`, phase rules, and testing runner details.
+- If the artifact store is `openspec` or `both` and `openspec/config.yaml` is missing, create it automatically with project context, `strict_tdd`, phase rules, and testing runner details. If the artifact store is `engram` or `none`, do not create `openspec/` files.
 - If `openspec/config.yaml` already exists, read it, summarize the current SDD/testing configuration, and do not block the caller. Update only safe derived context when explicitly necessary; never destructively rewrite user-maintained SDD configuration.
 - Ensure `.atl/skill-registry.md` exists when skill registry data is available, or report that it is missing.
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
 - Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.
+
 ## Memory Contract
 
 Read any existing project context directly from the active backend before bootstrapping; do not wait for the parent to inline it. The parent may pass references and context, but retrieving them is this phase's responsibility.
 
 Inputs to read (`engram`/`both`: use the injected Engram memory read tools for the topic key, then fetch the full observation; `openspec`: read the file under `openspec/`):
+
 - Existing project context (if re-initializing): `sdd-init/{project}`
 
 Persist this phase's artifact to the active backend before returning (mandatory):
+
 - `engram`/`both`: call the injected Engram save tool with title and `topic_key` `"sdd-init/{project}"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
 - `openspec`: write the project context file under `openspec/`.
 - `none`: return the project context inline.
 
 Never claim persistence you did not perform.
+
+
+## Key Learnings Closing
+
+Close your final report text with a `## Key Learnings` block (no trailing colon). Use 1–5 numbered items, each a standalone factual sentence of at least 20 characters and at least 4 words. This applies to final report text only — not intermediate tool output or saved artifact content. The Engram memory provider automatically extracts and persists these items as passive capture; you do not parse the block or invoke passive-capture tools yourself. Omit the block when there is genuinely no reusable learning; no filler or speculation. This closing block is separate from explicit `mem_save` artifact/decision persistence.

package/assets/agents/sdd-onboard.md

@@ -4,7 +4,7 @@ description: Guide a user through a complete SDD cycle on a small real project c
 tools:
   - read
   - grep
-  - glob
+  - find
   - write
   - edit
   - bash
@@ -41,3 +41,8 @@ Persist each demonstrated artifact to the active backend before moving on (manda
 - `none`: walk through the artifacts inline.
 
 Never claim persistence you did not perform.
+
+
+## Key Learnings Closing
+
+Close your final report text with a `## Key Learnings` block (no trailing colon). Use 1–5 numbered items, each a standalone factual sentence of at least 20 characters and at least 4 words. This applies to final report text only — not intermediate tool output or saved artifact content. The Engram memory provider automatically extracts and persists these items as passive capture; you do not parse the block or invoke passive-capture tools yourself. Omit the block when there is genuinely no reusable learning; no filler or speculation. This closing block is separate from explicit `mem_save` artifact/decision persistence.

package/assets/agents/sdd-proposal.md

@@ -4,7 +4,7 @@ description: Write an SDD proposal for an approved change idea.
 tools:
   - read
   - grep
-  - glob
+  - find
   - write
   - edit
   - mem_search
@@ -51,3 +51,8 @@ Persist this phase's artifact to the active backend before returning (mandatory)
 - `none`: return the proposal inline.
 
 Never claim persistence you did not perform.
+
+
+## Key Learnings Closing
+
+Close your final report text with a `## Key Learnings` block (no trailing colon). Use 1–5 numbered items, each a standalone factual sentence of at least 20 characters and at least 4 words. This applies to final report text only — not intermediate tool output or saved artifact content. The Engram memory provider automatically extracts and persists these items as passive capture; you do not parse the block or invoke passive-capture tools yourself. Omit the block when there is genuinely no reusable learning; no filler or speculation. This closing block is separate from explicit `mem_save` artifact/decision persistence.

package/assets/agents/sdd-spec.md

@@ -4,7 +4,7 @@ description: Write SDD delta specs with requirements and scenarios.
 tools:
   - read
   - grep
-  - glob
+  - find
   - write
   - edit
   - mem_search
@@ -181,3 +181,8 @@ Archive will copy this new domain spec into `openspec/specs/{domain}/spec.md`.
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
 
 Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.
+
+
+## Key Learnings Closing
+
+Close your final report text with a `## Key Learnings` block (no trailing colon). Use 1–5 numbered items, each a standalone factual sentence of at least 20 characters and at least 4 words. This applies to final report text only — not intermediate tool output or saved artifact content. The Engram memory provider automatically extracts and persists these items as passive capture; you do not parse the block or invoke passive-capture tools yourself. Omit the block when there is genuinely no reusable learning; no filler or speculation. This closing block is separate from explicit `mem_save` artifact/decision persistence.

package/assets/agents/sdd-status.md

@@ -4,7 +4,7 @@ description: Show read-only structured SDD status for an active change.
 tools:
   - read
   - grep
-  - glob
+  - find
   - bash
   - mem_search
   - mem_get_observation
@@ -113,3 +113,8 @@ If parent context reports `workspace-planning` and no `allowedEditRoots`, mark a
 ## Output
 
 Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution. Include the structured status block in `artifacts` or `executive_summary`.
+
+
+## Key Learnings Closing
+
+Close your final report text with a `## Key Learnings` block (no trailing colon). Use 1–5 numbered items, each a standalone factual sentence of at least 20 characters and at least 4 words. This applies to final report text only — not intermediate tool output or saved artifact content. The Engram memory provider automatically extracts and persists these items as passive capture; you do not parse the block or invoke passive-capture tools yourself. Omit the block when there is genuinely no reusable learning; no filler or speculation. This closing block is separate from explicit `mem_save` artifact/decision persistence.

package/assets/agents/sdd-sync.md

@@ -4,7 +4,7 @@ description: Sync verified SDD delta specs into OpenSpec canonical specs without
 tools:
   - read
   - grep
-  - glob
+  - find
   - write
   - edit
   - bash
@@ -135,3 +135,8 @@ Include:
 - Apply `rules.sync` from `openspec/config.yaml` when present.
 
 Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.
+
+
+## Key Learnings Closing
+
+Close your final report text with a `## Key Learnings` block (no trailing colon). Use 1–5 numbered items, each a standalone factual sentence of at least 20 characters and at least 4 words. This applies to final report text only — not intermediate tool output or saved artifact content. The Engram memory provider automatically extracts and persists these items as passive capture; you do not parse the block or invoke passive-capture tools yourself. Omit the block when there is genuinely no reusable learning; no filler or speculation. This closing block is separate from explicit `mem_save` artifact/decision persistence.

package/assets/agents/sdd-tasks.md

@@ -4,7 +4,7 @@ description: Break SDD design/specs into implementation tasks with review worklo
 tools:
   - read
   - grep
-  - glob
+  - find
   - write
   - edit
   - mem_search
@@ -98,3 +98,8 @@ Use `implementation` for RED/GREEN/TRIANGULATE/REFACTOR, code, tests, and apply-
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
 
 Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.
+
+
+## Key Learnings Closing
+
+Close your final report text with a `## Key Learnings` block (no trailing colon). Use 1–5 numbered items, each a standalone factual sentence of at least 20 characters and at least 4 words. This applies to final report text only — not intermediate tool output or saved artifact content. The Engram memory provider automatically extracts and persists these items as passive capture; you do not parse the block or invoke passive-capture tools yourself. Omit the block when there is genuinely no reusable learning; no filler or speculation. This closing block is separate from explicit `mem_save` artifact/decision persistence.

package/assets/agents/sdd-verify.md

@@ -4,7 +4,7 @@ description: Verify implementation against SDD specs, tasks, strict TDD evidence
 tools:
   - read
   - grep
-  - glob
+  - find
   - bash
   - write
   - edit
@@ -117,3 +117,8 @@ Write `openspec/changes/{change}/verify-report.md` with:
 Do NOT launch child subagents. Parent/orchestrator owns delegation. Do NOT fix issues; report them.
 
 Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.
+
+
+## Key Learnings Closing
+
+Close your final report text with a `## Key Learnings` block (no trailing colon). Use 1–5 numbered items, each a standalone factual sentence of at least 20 characters and at least 4 words. This applies to final report text only — not intermediate tool output or saved artifact content. The Engram memory provider automatically extracts and persists these items as passive capture; you do not parse the block or invoke passive-capture tools yourself. Omit the block when there is genuinely no reusable learning; no filler or speculation. This closing block is separate from explicit `mem_save` artifact/decision persistence.

package/assets/chains/4r-review.chain.md

@@ -3,6 +3,8 @@ name: 4r-review
 description: One-shot lens-only 4R discovery against a supplied initial review tree; the controller owns all authority.
 ---
 
+> Manual/compat-lane only: the provider host-relay capture path never loads this chain; it exists solely for explicit manual 4R invocation.
+
 ## review-risk
 
 output: review-risk-report.md

package/assets/chains/sdd-full.chain.md

@@ -13,7 +13,7 @@ output: init.md
 outputMode: file-only
 progress: true
 
-Initialize SDD context for {task} before any planning or implementation. If `openspec/config.yaml` is missing, inspect the project and create it automatically. If it already exists, read it, refresh only safe derived context when appropriate, and report the current SDD/testing configuration without blocking the chain.
+Initialize SDD context for {task} before any planning or implementation. If the artifact store is `openspec` or `both` and `openspec/config.yaml` is missing, inspect the project and create it automatically. If the artifact store is `engram` or `none`, skip OpenSpec file creation. If `openspec/config.yaml` already exists, read it, refresh only safe derived context when appropriate, and report the current SDD/testing configuration without blocking the chain.
 
 ## sdd-explore
 

package/assets/chains/sdd-plan.chain.md

@@ -13,7 +13,7 @@ output: init.md
 outputMode: file-only
 progress: true
 
-Initialize SDD context for {task} before planning. If `openspec/config.yaml` is missing, inspect the project and create it automatically. If it already exists, read it and report the current SDD/testing configuration without blocking the chain.
+Initialize SDD context for {task} before planning. If the artifact store is `openspec` or `both` and `openspec/config.yaml` is missing, inspect the project and create it automatically. If the artifact store is `engram` or `none`, skip OpenSpec file creation. If `openspec/config.yaml` already exists, read it and report the current SDD/testing configuration without blocking the chain.
 
 ## sdd-proposal