gentle-pi 0.11.3 → 0.12.0

package/README.md

@@ -55,7 +55,7 @@ Most coding-agent sessions fail for operational reasons, not model reasons:
 | **Reviewer protection**        | Surfaces review workload risk before a task turns into an oversized PR.                                                                       |
 | **Per-agent model assignment** | Pi-native modal for assigning stronger or cheaper models to specific SDD/custom agents.                                                       |
 | **Skill discovery registry**   | Maintains `.atl/skill-registry.md` from project and user skills so review/comment/PR workflows do not silently miss the right skill.          |
-| **Skill creation workflow**    | Provides the `skill-creator`/`skill-improver` skills, `/skill-creation` prompt, and packaged style guide for LLM-first skills.                 |
+| **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.                           |
 | **Runtime safety**             | Blocks destructive shell commands, asks for confirmation for sensitive operations, and blocks direct read/write/edit access to sensitive paths. |
 
@@ -311,9 +311,11 @@ Behavior:
 
 Skill discovery is a guardrail, not a workflow router: it helps Pi load the right skill without forcing extra ceremony.
 
-`gentle-pi` also ships package-owned `skill-creator` and `skill-improver` skills plus the `/skill-creation` prompt for creating or updating project skills. Both skills use `docs/skill-style-guide.md` as their normative style contract. The workflow checks for duplicates, keeps `SKILL.md` concise, uses one-line trigger-rich frontmatter, and reminds maintainers to refresh the registry after skill changes.
+`gentle-pi` also ships package-owned `gentle-ai-skill-creator` and `gentle-ai-skill-improver` skills plus the `/skill-creation` prompt for creating or updating project skills. Both skills use `docs/skill-style-guide.md` as their normative style contract. The workflow checks for duplicates, keeps `SKILL.md` concise, uses one-line trigger-rich frontmatter, and reminds maintainers to refresh the registry after skill changes.
 
-Packaged skills include `cognitive-doc-design`, `comment-writer`, `judgment-day`, `skill-creator`, `skill-improver`, and the other delivery/review skills under `skills/`. SDD init is installed as the packaged `sdd-init` runtime agent under `assets/agents/` and refreshed with the SDD assets.
+Packaged skills include `cognitive-doc-design`, `comment-writer`, `gentle-ai-judgment-day`, `gentle-ai-skill-creator`, `gentle-ai-skill-improver`, and the other delivery/review skills under `skills/`. SDD init is installed as the packaged `sdd-init` runtime agent under `assets/agents/` and refreshed with the SDD assets.
+
+Compatibility: the package keeps the existing skill folders (`skills/branch-pr`, `skills/judgment-day`, `skills/skill-creator`) but their exported frontmatter names are prefixed to avoid collisions with user/global skills. Treat former package names such as `branch-pr`, `judgment-day`, and `skill-creator` as legacy aliases in prose; runtime skill selection should use `gentle-ai-branch-pr`, `gentle-ai-judgment-day`, and `gentle-ai-skill-creator`.
 
 Delegation contract:
 
@@ -413,7 +415,7 @@ Legacy string entries are still accepted and treated as `model`-only config.
 | `/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`.                               |
-| `/skill-creation`                | Creates or updates an LLM-first skill using the packaged `skill-creator` contract and style guide. |
+| `/skill-creation`                | Creates or updates an LLM-first skill using the packaged `gentle-ai-skill-creator` contract and style guide. |
 
 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.
 
@@ -430,15 +432,15 @@ Use it when you want skills available normally but do not want Gentle AI to refr
 ## Included skills
 
 - `gentle-ai` — harness discipline for controlled Pi work.
-- `branch-pr` — issue-first PR preparation.
-- `chained-pr` — split oversized changes into reviewable PR chains.
+- `gentle-ai-branch-pr` — issue-first PR preparation.
+- `gentle-ai-chained-pr` — split oversized changes into reviewable PR chains.
 - `work-unit-commits` — commits as reviewable work units.
-- `judgment-day` — blind dual review, fixes, and re-judgment.
+- `gentle-ai-judgment-day` — blind dual review, fixes, and re-judgment.
 - `cognitive-doc-design` — documentation that reduces cognitive load.
 - `comment-writer` — concise, warm, postable collaboration comments.
-- `issue-creation` — issue workflow with checks before creation.
-- `skill-creator` — create LLM-first skills with valid frontmatter.
-- `skill-improver` — audit and upgrade existing LLM-first skills.
+- `gentle-ai-issue-creation` — issue workflow with checks before creation.
+- `gentle-ai-skill-creator` — create LLM-first skills with valid frontmatter.
+- `gentle-ai-skill-improver` — audit and upgrade existing LLM-first skills.
 
 ## Memory
 

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

@@ -20,3 +20,18 @@ Rules:
 - Add or update focused tests when the fix changes behavior.
 - Run the relevant tests when practical and report exact results.
 - Clearly list what was fixed, what was verified, and any remaining risks.
+
+## Review ledger contract (fix agent role)
+
+This agent does NOT run the exhaustive first-pass sweep and does NOT emit a findings ledger — that is the judge role's job, not this agent's.
+
+**Read the persisted ledger.** Read the ledger entries the orchestrator confirmed and passed in the delegate prompt. Apply only those confirmed fixes.
+
+**Update status, do not add rows.** After fixing a confirmed entry, set that entry's `status` to `fixed`. Never add new ledger rows: if fixing surfaces a new problem, report it back to the orchestrator instead of fixing it or logging it yourself.
+
+Valid enum values (same as the judge ledger schema, for reference only — this agent never emits ledger rows itself):
+- `severity`: BLOCKER \| CRITICAL \| WARNING \| SUGGESTION
+- `status`: open \| fixed \| verified \| wont-fix \| info
+- `lens`: risk \| readability \| reliability \| resilience \| judgment-day
+
+Fix execution-mode: jd-fix-agent applies only confirmed ledger findings and hands control back to the orchestrator, which runs the scoped re-judge.

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

@@ -18,3 +18,31 @@ Rules:
 - Do not coordinate with judge B before producing your review.
 - Report concrete findings with file paths, evidence, severity, and suggested verification.
 - If you find no confirmed issues, say so clearly.
+
+## Review ledger contract
+
+**Exhaustive first pass.** Loop until dry: sweep the diff repeatedly until N consecutive sweeps yield zero new findings, then stop; the loop MUST be finite. Default N = 2 consecutive dry sweeps. R2 Readability MAY use N = 1. Hard ceiling: 4 sweeps regardless of N.
+
+**Findings ledger.** Emit a findings ledger with this schema for every entry:
+
+| Field | Values |
+|-------|--------|
+| `id` | `{LENS}-{NNN}` (e.g. `R1-001`) |
+| `lens` | risk \| readability \| reliability \| resilience \| judgment-day |
+| `location` | `path/to/file.ext:line` or `:start-end` |
+| `severity` | BLOCKER \| CRITICAL \| WARNING \| SUGGESTION |
+| `status` | open \| fixed \| verified \| wont-fix \| info |
+| `evidence` | why it matters |
+
+If the first pass finds nothing, persist an empty ledger record rather than skip persistence.
+
+Persistence below is executed by the orchestrator after it merges your returned ledger rows; you never write ledger artifacts yourself.
+
+**Ledger persistence honors the artifact store.**
+- `openspec`: write `openspec/changes/{change-name}/review-ledger.md`.
+- `engram`: upsert topic `sdd/{change-name}/review-ledger` (ad-hoc judgment-day without a change: `review/{target-slug}/ledger`, where `target-slug` = `pr-{number}` when reviewing a PR, else the current branch name kebab-cased, else a kebab-case slug of the user-stated review target). If the engram upsert fails or the memory tool is unavailable, fall back to keeping the ledger inline in the response and explicitly report the degradation — never continue as if persistence succeeded.
+- `none`: keep the ledger inline in the response; do not write files or Engram artifacts — the ledger lives only in this conversation; complete the review → fix → re-review loop within the session because it is not persisted across compaction.
+
+**Scoped re-review.** A re-review pass takes the persisted ledger and the fix diff as input. It MUST verify each ledger finding's resolution and MUST review only fix-touched lines; it MUST NOT re-read the full original diff. A finding on an untouched line MUST be logged with status `info` as a first-pass quality signal and MUST NOT by itself trigger another full round.
+
+Subagent execution-mode: this agent runs its lens exhaustively as a dedicated Pi subagent and returns its own ledger rows in its Output; the orchestrator merges those ledger rows into the persisted ledger.

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

@@ -18,3 +18,31 @@ Rules:
 - Work independently from judge A and do not rely on judge A's conclusions.
 - Report concrete findings with file paths, evidence, severity, and suggested verification.
 - If you find no confirmed issues, say so clearly.
+
+## Review ledger contract
+
+**Exhaustive first pass.** Loop until dry: sweep the diff repeatedly until N consecutive sweeps yield zero new findings, then stop; the loop MUST be finite. Default N = 2 consecutive dry sweeps. R2 Readability MAY use N = 1. Hard ceiling: 4 sweeps regardless of N.
+
+**Findings ledger.** Emit a findings ledger with this schema for every entry:
+
+| Field | Values |
+|-------|--------|
+| `id` | `{LENS}-{NNN}` (e.g. `R1-001`) |
+| `lens` | risk \| readability \| reliability \| resilience \| judgment-day |
+| `location` | `path/to/file.ext:line` or `:start-end` |
+| `severity` | BLOCKER \| CRITICAL \| WARNING \| SUGGESTION |
+| `status` | open \| fixed \| verified \| wont-fix \| info |
+| `evidence` | why it matters |
+
+If the first pass finds nothing, persist an empty ledger record rather than skip persistence.
+
+Persistence below is executed by the orchestrator after it merges your returned ledger rows; you never write ledger artifacts yourself.
+
+**Ledger persistence honors the artifact store.**
+- `openspec`: write `openspec/changes/{change-name}/review-ledger.md`.
+- `engram`: upsert topic `sdd/{change-name}/review-ledger` (ad-hoc judgment-day without a change: `review/{target-slug}/ledger`, where `target-slug` = `pr-{number}` when reviewing a PR, else the current branch name kebab-cased, else a kebab-case slug of the user-stated review target). If the engram upsert fails or the memory tool is unavailable, fall back to keeping the ledger inline in the response and explicitly report the degradation — never continue as if persistence succeeded.
+- `none`: keep the ledger inline in the response; do not write files or Engram artifacts — the ledger lives only in this conversation; complete the review → fix → re-review loop within the session because it is not persisted across compaction.
+
+**Scoped re-review.** A re-review pass takes the persisted ledger and the fix diff as input. It MUST verify each ledger finding's resolution and MUST review only fix-touched lines; it MUST NOT re-read the full original diff. A finding on an untouched line MUST be logged with status `info` as a first-pass quality signal and MUST NOT by itself trigger another full round.
+
+Subagent execution-mode: this agent runs its lens exhaustively as a dedicated Pi subagent and returns its own ledger rows in its Output; the orchestrator merges those ledger rows into the persisted ledger.

package/assets/agents/review-readability.md

@@ -25,4 +25,32 @@ Rule sources: ai-course-2 slides `05-code-smells.md`, `06-safe-refactoring.md`,
 
 ## Output contract
 
-Report findings only. Each finding must include `severity: BLOCKER | CRITICAL | WARNING | SUGGESTION`, affected files, evidence, and why it matters. If clean, say exactly: `No findings.`
+Report findings only. Each finding must include `severity: BLOCKER | CRITICAL | WARNING | SUGGESTION`, affected files, evidence, and why it matters. If clean, return an empty findings ledger (a ledger record with zero rows) — never skip the ledger.
+
+## Review ledger contract
+
+**Exhaustive first pass.** Loop until dry: sweep the diff repeatedly until N consecutive sweeps yield zero new findings, then stop; the loop MUST be finite. Default N = 2 consecutive dry sweeps. R2 Readability MAY use N = 1. Hard ceiling: 4 sweeps regardless of N.
+
+**Findings ledger.** Emit a findings ledger with this schema for every entry:
+
+| Field | Values |
+|-------|--------|
+| `id` | `{LENS}-{NNN}` (e.g. `R1-001`) |
+| `lens` | risk \| readability \| reliability \| resilience \| judgment-day |
+| `location` | `path/to/file.ext:line` or `:start-end` |
+| `severity` | BLOCKER \| CRITICAL \| WARNING \| SUGGESTION |
+| `status` | open \| fixed \| verified \| wont-fix \| info |
+| `evidence` | why it matters |
+
+If the first pass finds nothing, persist an empty ledger record rather than skip persistence.
+
+Persistence below is executed by the orchestrator after it merges your returned ledger rows; you never write ledger artifacts yourself.
+
+**Ledger persistence honors the artifact store.**
+- `openspec`: write `openspec/changes/{change-name}/review-ledger.md`.
+- `engram`: upsert topic `sdd/{change-name}/review-ledger` (ad-hoc judgment-day without a change: `review/{target-slug}/ledger`, where `target-slug` = `pr-{number}` when reviewing a PR, else the current branch name kebab-cased, else a kebab-case slug of the user-stated review target). If the engram upsert fails or the memory tool is unavailable, fall back to keeping the ledger inline in the response and explicitly report the degradation — never continue as if persistence succeeded.
+- `none`: keep the ledger inline in the response; do not write files or Engram artifacts — the ledger lives only in this conversation; complete the review → fix → re-review loop within the session because it is not persisted across compaction.
+
+**Scoped re-review.** A re-review pass takes the persisted ledger and the fix diff as input. It MUST verify each ledger finding's resolution and MUST review only fix-touched lines; it MUST NOT re-read the full original diff. A finding on an untouched line MUST be logged with status `info` as a first-pass quality signal and MUST NOT by itself trigger another full round.
+
+Subagent execution-mode: this agent runs its lens exhaustively as a dedicated Pi subagent and returns its own ledger rows in its Output; the orchestrator merges those ledger rows into the persisted ledger.

package/assets/agents/review-reliability.md

@@ -26,4 +26,32 @@ Rule sources: ai-course-2 slides `01-testing-setup.md`, `02-tdd-implementation.m
 
 ## Output contract
 
-Report findings only. Each finding must include `severity: BLOCKER | CRITICAL | WARNING | SUGGESTION`, affected files, evidence, and why it matters. If clean, say exactly: `No findings.`
+Report findings only. Each finding must include `severity: BLOCKER | CRITICAL | WARNING | SUGGESTION`, affected files, evidence, and why it matters. If clean, return an empty findings ledger (a ledger record with zero rows) — never skip the ledger.
+
+## Review ledger contract
+
+**Exhaustive first pass.** Loop until dry: sweep the diff repeatedly until N consecutive sweeps yield zero new findings, then stop; the loop MUST be finite. Default N = 2 consecutive dry sweeps. R2 Readability MAY use N = 1. Hard ceiling: 4 sweeps regardless of N.
+
+**Findings ledger.** Emit a findings ledger with this schema for every entry:
+
+| Field | Values |
+|-------|--------|
+| `id` | `{LENS}-{NNN}` (e.g. `R1-001`) |
+| `lens` | risk \| readability \| reliability \| resilience \| judgment-day |
+| `location` | `path/to/file.ext:line` or `:start-end` |
+| `severity` | BLOCKER \| CRITICAL \| WARNING \| SUGGESTION |
+| `status` | open \| fixed \| verified \| wont-fix \| info |
+| `evidence` | why it matters |
+
+If the first pass finds nothing, persist an empty ledger record rather than skip persistence.
+
+Persistence below is executed by the orchestrator after it merges your returned ledger rows; you never write ledger artifacts yourself.
+
+**Ledger persistence honors the artifact store.**
+- `openspec`: write `openspec/changes/{change-name}/review-ledger.md`.
+- `engram`: upsert topic `sdd/{change-name}/review-ledger` (ad-hoc judgment-day without a change: `review/{target-slug}/ledger`, where `target-slug` = `pr-{number}` when reviewing a PR, else the current branch name kebab-cased, else a kebab-case slug of the user-stated review target). If the engram upsert fails or the memory tool is unavailable, fall back to keeping the ledger inline in the response and explicitly report the degradation — never continue as if persistence succeeded.
+- `none`: keep the ledger inline in the response; do not write files or Engram artifacts — the ledger lives only in this conversation; complete the review → fix → re-review loop within the session because it is not persisted across compaction.
+
+**Scoped re-review.** A re-review pass takes the persisted ledger and the fix diff as input. It MUST verify each ledger finding's resolution and MUST review only fix-touched lines; it MUST NOT re-read the full original diff. A finding on an untouched line MUST be logged with status `info` as a first-pass quality signal and MUST NOT by itself trigger another full round.
+
+Subagent execution-mode: this agent runs its lens exhaustively as a dedicated Pi subagent and returns its own ledger rows in its Output; the orchestrator merges those ledger rows into the persisted ledger.

package/assets/agents/review-resilience.md

@@ -25,4 +25,32 @@ Rule sources: ai-course-2 slides `09-essential-metrics.md`, `13-observability-st
 
 ## Output contract
 
-Report findings only. Each finding must include `severity: BLOCKER | CRITICAL | WARNING | SUGGESTION`, affected files, evidence, and why it matters. If clean, say exactly: `No findings.`
+Report findings only. Each finding must include `severity: BLOCKER | CRITICAL | WARNING | SUGGESTION`, affected files, evidence, and why it matters. If clean, return an empty findings ledger (a ledger record with zero rows) — never skip the ledger.
+
+## Review ledger contract
+
+**Exhaustive first pass.** Loop until dry: sweep the diff repeatedly until N consecutive sweeps yield zero new findings, then stop; the loop MUST be finite. Default N = 2 consecutive dry sweeps. R2 Readability MAY use N = 1. Hard ceiling: 4 sweeps regardless of N.
+
+**Findings ledger.** Emit a findings ledger with this schema for every entry:
+
+| Field | Values |
+|-------|--------|
+| `id` | `{LENS}-{NNN}` (e.g. `R1-001`) |
+| `lens` | risk \| readability \| reliability \| resilience \| judgment-day |
+| `location` | `path/to/file.ext:line` or `:start-end` |
+| `severity` | BLOCKER \| CRITICAL \| WARNING \| SUGGESTION |
+| `status` | open \| fixed \| verified \| wont-fix \| info |
+| `evidence` | why it matters |
+
+If the first pass finds nothing, persist an empty ledger record rather than skip persistence.
+
+Persistence below is executed by the orchestrator after it merges your returned ledger rows; you never write ledger artifacts yourself.
+
+**Ledger persistence honors the artifact store.**
+- `openspec`: write `openspec/changes/{change-name}/review-ledger.md`.
+- `engram`: upsert topic `sdd/{change-name}/review-ledger` (ad-hoc judgment-day without a change: `review/{target-slug}/ledger`, where `target-slug` = `pr-{number}` when reviewing a PR, else the current branch name kebab-cased, else a kebab-case slug of the user-stated review target). If the engram upsert fails or the memory tool is unavailable, fall back to keeping the ledger inline in the response and explicitly report the degradation — never continue as if persistence succeeded.
+- `none`: keep the ledger inline in the response; do not write files or Engram artifacts — the ledger lives only in this conversation; complete the review → fix → re-review loop within the session because it is not persisted across compaction.
+
+**Scoped re-review.** A re-review pass takes the persisted ledger and the fix diff as input. It MUST verify each ledger finding's resolution and MUST review only fix-touched lines; it MUST NOT re-read the full original diff. A finding on an untouched line MUST be logged with status `info` as a first-pass quality signal and MUST NOT by itself trigger another full round.
+
+Subagent execution-mode: this agent runs its lens exhaustively as a dedicated Pi subagent and returns its own ledger rows in its Output; the orchestrator merges those ledger rows into the persisted ledger.

package/assets/agents/review-risk.md

@@ -25,4 +25,32 @@ Rule sources: ai-course-2 slides `18-env-secrets.md`, `19-web-security.md`, `20-
 
 ## Output contract
 
-Report findings only. Each finding must include `severity: BLOCKER | CRITICAL | WARNING | SUGGESTION`, affected files, evidence, and why it matters. If clean, say exactly: `No findings.`
+Report findings only. Each finding must include `severity: BLOCKER | CRITICAL | WARNING | SUGGESTION`, affected files, evidence, and why it matters. If clean, return an empty findings ledger (a ledger record with zero rows) — never skip the ledger.
+
+## Review ledger contract
+
+**Exhaustive first pass.** Loop until dry: sweep the diff repeatedly until N consecutive sweeps yield zero new findings, then stop; the loop MUST be finite. Default N = 2 consecutive dry sweeps. R2 Readability MAY use N = 1. Hard ceiling: 4 sweeps regardless of N.
+
+**Findings ledger.** Emit a findings ledger with this schema for every entry:
+
+| Field | Values |
+|-------|--------|
+| `id` | `{LENS}-{NNN}` (e.g. `R1-001`) |
+| `lens` | risk \| readability \| reliability \| resilience \| judgment-day |
+| `location` | `path/to/file.ext:line` or `:start-end` |
+| `severity` | BLOCKER \| CRITICAL \| WARNING \| SUGGESTION |
+| `status` | open \| fixed \| verified \| wont-fix \| info |
+| `evidence` | why it matters |
+
+If the first pass finds nothing, persist an empty ledger record rather than skip persistence.
+
+Persistence below is executed by the orchestrator after it merges your returned ledger rows; you never write ledger artifacts yourself.
+
+**Ledger persistence honors the artifact store.**
+- `openspec`: write `openspec/changes/{change-name}/review-ledger.md`.
+- `engram`: upsert topic `sdd/{change-name}/review-ledger` (ad-hoc judgment-day without a change: `review/{target-slug}/ledger`, where `target-slug` = `pr-{number}` when reviewing a PR, else the current branch name kebab-cased, else a kebab-case slug of the user-stated review target). If the engram upsert fails or the memory tool is unavailable, fall back to keeping the ledger inline in the response and explicitly report the degradation — never continue as if persistence succeeded.
+- `none`: keep the ledger inline in the response; do not write files or Engram artifacts — the ledger lives only in this conversation; complete the review → fix → re-review loop within the session because it is not persisted across compaction.
+
+**Scoped re-review.** A re-review pass takes the persisted ledger and the fix diff as input. It MUST verify each ledger finding's resolution and MUST review only fix-touched lines; it MUST NOT re-read the full original diff. A finding on an untouched line MUST be logged with status `info` as a first-pass quality signal and MUST NOT by itself trigger another full round.
+
+Subagent execution-mode: this agent runs its lens exhaustively as a dedicated Pi subagent and returns its own ledger rows in its Output; the orchestrator merges those ledger rows into the persisted ledger.

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

@@ -9,7 +9,7 @@ output: review-risk-report.md
 outputMode: file-only
 progress: true
 
-Run R1 Risk review on the current diff. Report security, privilege boundary, data exposure, dependency, and merge-blocking vulnerability findings. If clean, say exactly: `No findings.`
+Run R1 Risk review on the current diff. Report security, privilege boundary, data exposure, dependency, and merge-blocking vulnerability findings. If the first pass finds nothing, persist an empty ledger record rather than skip persistence.
 
 ## review-readability
 
@@ -18,7 +18,7 @@ output: review-readability-report.md
 outputMode: file-only
 progress: true
 
-Run R2 Readability review on the current diff. Report naming, complexity, intention, maintainability, review size, and context clarity findings. If clean, say exactly: `No findings.`
+Run R2 Readability review on the current diff. Report naming, complexity, intention, maintainability, review size, and context clarity findings. If the first pass finds nothing, persist an empty ledger record rather than skip persistence.
 
 ## review-reliability
 
@@ -27,7 +27,7 @@ output: review-reliability-report.md
 outputMode: file-only
 progress: true
 
-Run R3 Reliability review on the current diff. Report behavior-first test coverage, edge case, determinism, contract, and regression findings. If clean, say exactly: `No findings.`
+Run R3 Reliability review on the current diff. Report behavior-first test coverage, edge case, determinism, contract, and regression findings. If the first pass finds nothing, persist an empty ledger record rather than skip persistence.
 
 ## review-resilience
 
@@ -36,4 +36,4 @@ output: review-resilience-report.md
 outputMode: file-only
 progress: true
 
-Run R4 Resilience review on the current diff. Report fallback, retry/backoff, graceful degradation, observability, load, rollback, and SLO risk findings. If clean, say exactly: `No findings.`
+Run R4 Resilience review on the current diff. Report fallback, retry/backoff, graceful degradation, observability, load, rollback, and SLO risk findings. If the first pass finds nothing, persist an empty ledger record rather than skip persistence.

package/assets/orchestrator-delegation.md

@@ -0,0 +1,183 @@
+# Orchestrator — Delegation Detail (lazy-loaded)
+
+Bind this to the parent Pi session only, on delegation/routing/review triggers. Not always-on; loaded on demand from `assets/orchestrator.md`'s `## Work Routing Ladder`, `## Delegation Rules`, `## Language Boundary`, and `## 4R Review Triggers` pointers.
+
+## Language Boundary — subagent-facing English + exceptions
+
+Subagent-facing prompts should be written in English by default, even when the user speaks Spanish. Translate the user's request into concise English before delegation. This keeps token usage lower and gives built-in/project subagents a consistent operating language without changing the user-facing persona.
+
+Exceptions:
+
+- Preserve exact user quotes, UI copy, error messages, filenames, commands, and domain terms in their original language when they are evidence.
+- Ask a subagent to produce Spanish only when its output is intended to be pasted directly to the user, a PR/comment/reply in Spanish, or Spanish-language product/documentation text.
+- SDD/OpenSpec artifact content may follow the project's established language, but phase task instructions to subagents should still be English.
+
+## Work Routing Ladder
+
+Route work through the smallest harness that is safe. "Smallest" means minimal safe coordination, not zero delegation by default.
+
+### 1. Inline Direct
+
+Use inline execution when the task is small, mechanical, and the parent already has enough context.
+
+Examples:
+
+- typo, rename, one-file mechanical edit;
+- small known bug with clear location;
+- focused verification over 1-3 files;
+- bash for state, e.g. `git status` or `gh issue view`.
+
+Do not add SDD ceremony. Do not delegate just to look sophisticated. But do not use this exception to avoid delegation after the task stops being small.
+
+### 2. Simple Delegation
+
+Delegate when the work would inflate parent context or requires focused exploration, validation, or multi-file implementation, but does not yet need a full SDD lifecycle.
+
+Examples:
+
+- understand an unfamiliar module;
+- inspect 4+ files;
+- investigate a failing test;
+- implement a bounded multi-file change;
+- run tests/builds and summarize results;
+- fresh-context review.
+
+Use the configured subagent runtime when available. Prefer the `subagent_*` tools (`subagent_run`, status/result helpers) when the Pi Subagents extension is installed, because they run the user's configured project/global subagent definitions and preserve history/background behavior.
+
+Choose subagent mode by orchestration dependency, not by task length:
+
+- Use `mode: "task"` when the parent must consume the result and continue the workflow, including SDD phases, implementation batches, verification, review gates, and any delegated work whose output determines the next action.
+- Use `mode: "background"` only for independent work where automatic parent continuation is not required. Background completion may notify the user and preserve history, but it is not a guarantee that the parent model will resume orchestration.
+
+If `subagent_*` tools are unavailable, fall back to Pi's native `Agent` tool or another available delegation mechanism. The delegation trigger remains mandatory; the fallback changes the runtime, not the requirement to delegate. If no delegation mechanism is available, stop the complex work and explain the blocker instead of silently continuing inline.
+
+### Pi Subagent Model Routing
+
+For generic Pi subagents (`delegate`, `worker`, `scout`, review lens agents, `context-builder`, `oracle`, `planner`, `researcher`, or other non-SDD agents), do not pass the `model` parameter by default. Let `pi-subagents` resolve model and thinking from `.pi/settings.json`, `.pi/subagents.json`, global subagent config, and runtime defaults.
+
+SDD model assignment tables apply only to SDD/Judgment-Day phase agents. They must not be used for generic Pi delegation.
+
+Only pass `model` for generic subagents when the user explicitly requests a model override for that launch.
+
+Default balanced pattern for bounded implementation:
+
+```text
+parent clarifies and checks git → scout/context-builder when context-heavy → one worker writes → selected review lens audits diff → parent validates and reports
+```
+
+Do not make every task SDD. Do make non-trivial tasks multi-agent at the narrowest useful point.
+
+### 3. SDD
+
+Use SDD for large, ambiguous, architectural, product-facing, multi-area, or high-review-risk work.
+
+Triggers:
+
+- unclear requirements or acceptance criteria;
+- architectural/product decisions;
+- cross-cutting behavior changes;
+- expected large diff or reviewer burden;
+- need for specs/design/tasks before safe implementation;
+- user explicitly asks to use SDD, or invokes `/sdd-new`, `/sdd-ff`, or `/sdd-continue`.
+
+If the request is large enough for SDD, do not jump directly to implementation. Calibrate context, create artifacts, and ask for approval at the appropriate gates.
+
+## Delegation Rules
+
+Core question: does this inflate parent context without need?
+
+| Action                                               | Inline |                Delegate |
+| ---------------------------------------------------- | -----: | ----------------------: |
+| Read to decide/verify 1-3 files                      |    yes |                      no |
+| Read to explore/understand 4+ files                  |     no |                     yes |
+| Read as preparation for multi-file writing           |     no |                     yes |
+| Write atomic one-file mechanical change              |    yes |                      no |
+| Write with analysis across multiple files            |     no |                     yes |
+| Bash for state, e.g. git status                      |    yes |                      no |
+| Bash for execution, e.g. tests/builds                |     no |                     yes |
+| Commit, push, or open PR after code changes          |     no | yes, fresh review first |
+| Recover from wrong cwd/worktree/git/tooling incident |     no |  yes, fresh audit first |
+
+### Mandatory Delegation Triggers
+
+These are parent-orchestrator stop rules. Once any trigger fires, the parent MUST delegate through the best available subagent runtime. Prefer `subagent_run` when present; otherwise use Pi's native `Agent` or another available delegation mechanism. Do not replace a required delegation with inline execution. Do not inject these as child-agent permission to spawn subagents; children receive concrete role work and must not orchestrate.
+
+1. **4-file rule**: if understanding requires reading 4+ files, launch `scout`, `context-builder`, or the closest read-only mapping subagent with fresh context and a narrow mapping task. State the fallback agent/runtime if the preferred one is unavailable.
+2. **Multi-file write rule**: if implementation will touch 2+ non-trivial files, delegate one writer; inline writing is allowed only for trivial/mechanical edits or when the parent explicitly records why no delegation runtime is available. A fresh review still follows delegated implementation.
+3. **PR rule**: before commit/push/PR for code changes, select a fresh-context review lens unless the diff is trivial docs/text-only.
+4. **Incident rule**: after wrong `cwd`, accidental repo/worktree mutation, failed merge recovery, confusing test command, or environment workaround, stop and run a fresh audit through the relevant review lens before continuing.
+5. **Long-session rule**: if accumulating work is no longer clearly local — roughly 20 tool calls, 5 exploratory file reads, or 2 non-mechanical edits without delegation — pause and delegate the remaining work instead of silently continuing monolithically.
+6. **Fresh review rule**: use fresh-context review lens subagents for adversarial review of diffs, conflicts, PR readiness, and incidents. Use continuity-oriented workers only for implementation work that needs inherited state.
+
+### Cost and Context Balance
+
+Prefer delegation when fresh context improves correctness more than token savings:
+
+- Use `scout`/`context-builder` to compress broad repo exploration into a short handoff instead of loading many files into the parent.
+- Use a single `worker` for one writer thread; do not run parallel writers unless isolated worktrees are explicitly approved.
+- Use fresh concrete review lens agents after implementation, conflict resolution, or incidents because their value is independence from the parent's assumptions. Do not call a generic `reviewer` subagent; choose from `review-risk`, `review-reliability`, `review-resilience`, `review-readability`, or the full 4R set.
+- Use `outputMode: "file-only"` for large child reports and summarize only decisions, blockers, and paths in the parent thread.
+- Avoid delegation for truly local one-file fixes, quick state checks, and already-understood mechanical edits.
+
+### Canonical Lightweight Workflows
+
+Bugfix with unfamiliar flow:
+
+```text
+parent git/status + clarify → scout fresh maps flow/files → parent decides → worker fork implements + tests → selected review lens audits diff → parent validates
+```
+
+Conflict or dependency-marker cleanup:
+
+```text
+parent reproduces/checks conflict → parent or worker resolves → selected review lens checks markers, package/lock consistency, and repo cleanliness → parent reports/pushes
+```
+
+After tooling/worktree incident:
+
+```text
+stop writes → parent captures git status → selected review lens audits affected repos/worktrees with no edits → parent applies only confirmed recovery steps
+```
+
+### Review Lens Selection
+
+`reviewer` is an intent, not an installed subagent name. The parent must select concrete review agents by risk profile:
+
+| Context | Review lens |
+| --- | --- |
+| Clear naming, structure, maintainability, small refactors | `review-readability` |
+| Behavior, state, tests, determinism, regressions | `review-reliability` |
+| Shell/process integration, partial failures, recovery, degraded dependencies | `review-resilience` |
+| Security, permissions, data exposure/loss, architecture, dependencies | `review-risk` |
+| Large PR, hot path, or >400 changed lines | Full 4R: `review-risk`, `review-resilience`, `review-readability`, `review-reliability` |
+
+If multiple rows match, run the narrow set that covers the risk. Example: shell integration that mutates live state should use `review-reliability` plus `review-resilience`, not `review-readability` by default.
+
+## 4R Review Triggers
+
+The extension (`extensions/gentle-ai.ts`) gates `bash` tool calls that look like git/gh workflow events. Gate semantics:
+
+- **pre-commit** (`git commit`): advisory only. The extension notifies the user to consider running `review-readability` but does NOT block. No orchestrator action needed.
+- **pre-push** (`git push`): advisory only. Same as pre-commit — notify, do not block.
+- **pre-pr** (`gh pr create`): **strong gate**. The extension blocks when any of these hold:
+  - Changed paths match hot globs: `**/auth/**`, `**/update/**`, `**/security/**`, `**/payments/**`
+  - Diff exceeds 400 changed lines (added + deleted)
+  - When blocked, the reason names all four agents to run first.
+- **post-sdd-phase** (design, apply): **strong gate** for the packaged `gentle-ai-judgment-day` skill. Handled separately by SDD phase orchestration, not this diff-based hook.
+
+When the extension blocks a `gh pr create` command, the orchestrator must launch the `4r-review` chain (or run the four agents individually) and wait for their reports before the user retries the PR command.
+
+Prohibition: do NOT configure the full 4R fan-out on `pre-commit` or `pre-push` with `always: true`. Everyday events must use a single advisory lens to keep development-loop cost low (spec G token-budget rule). The `validateTriggerRuleSet` function in `lib/review-triggers.ts` enforces this at config load time.
+
+### Review Execution Contract
+
+**Ledger persistence honors the artifact store.**
+- `openspec`: write `openspec/changes/{change-name}/review-ledger.md`.
+- `engram`: upsert topic `sdd/{change-name}/review-ledger` (ad-hoc judgment-day without a change: `review/{target-slug}/ledger`, where `target-slug` = `pr-{number}` when reviewing a PR, else the current branch name kebab-cased, else a kebab-case slug of the user-stated review target). If the engram upsert fails or the memory tool is unavailable, fall back to keeping the ledger inline in the response and explicitly report the degradation — never continue as if persistence succeeded.
+- `none`: keep the ledger inline in the response; do not write files or Engram artifacts — the ledger lives only in this conversation; complete the review → fix → re-review loop within the session because it is not persisted across compaction.
+
+If the first pass finds nothing, persist an empty ledger record rather than skip persistence.
+
+Subagent execution-mode: this agent runs its lens exhaustively as a dedicated Pi subagent and returns its own ledger rows in its Output; the orchestrator merges those ledger rows into the persisted ledger.
+
+Fix execution-mode: jd-fix-agent applies only confirmed ledger findings and hands control back to the orchestrator, which runs the scoped re-judge.

package/assets/orchestrator-memory.md

@@ -0,0 +1,32 @@
+# Orchestrator — Memory Detail (lazy-loaded)
+
+Bind this to the parent Pi session only, on SDD phase memory reads/writes. Not always-on; loaded on demand from `assets/orchestrator.md`'s `## Memory Contract` pointer.
+
+### SDD phases
+
+Each SDD phase subagent reads its own required inputs directly from the active backend; the parent passes artifact references (topic keys or file paths), NOT the content itself. Phase subagents persist their artifact before returning.
+
+| Phase          | Reads                                                   | Writes           |
+| -------------- | ------------------------------------------------------- | ---------------- |
+| `sdd-explore`  | nothing                                                 | `explore`        |
+| `sdd-proposal` | exploration (optional)                                  | `proposal`       |
+| `sdd-spec`     | proposal (required)                                     | `spec`           |
+| `sdd-design`   | proposal (required)                                     | `design`         |
+| `sdd-tasks`    | spec + design (required)                                | `tasks`          |
+| `sdd-apply`    | tasks + spec + design + `apply-progress` (if it exists) | `apply-progress` |
+| `sdd-verify`   | spec + tasks + `apply-progress`                         | `verify-report`  |
+| `sdd-sync`     | proposal + spec + design + tasks + `verify-report`      | `sync-report`    |
+| `sdd-archive`  | all artifacts                                           | `archive-report` |
+| `sdd-status`   | change artifacts (read-only)                            | nothing          |
+
+- SDD artifact keys: in memory/hybrid mode, phase artifacts use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, `sdd/<change>/verify-report`, `sdd/<change>/sync-report`, and `sdd/<change>/archive-report`.
+- If memory tools are unavailable, do not pretend persistence exists; return artifacts inline and/or write OpenSpec files.
+
+Memory lifecycle rule (when Engram exposes lifecycle metadata/tooling):
+
+- At session start or before architecture-sensitive work, call the injected Engram review tool with action `list` for the current project when the tool is available.
+- If the injected Engram review tool is unavailable, do not fail the task. Continue with the injected Engram context/search tools, and still apply lifecycle metadata from any returned observations when present.
+- `active` memories may be used normally.
+- `needs_review` memories are stale context, not trusted facts.
+- When a retrieved memory is marked `needs_review`, surface that stale context to the user and verify it against current evidence before relying on it.
+- Do NOT call the injected Engram review tool with action `mark_reviewed` automatically. Only call `mark_reviewed` after explicit user confirmation or through a dedicated memory maintenance command.

package/assets/orchestrator-skills.md

@@ -0,0 +1,49 @@
+# Orchestrator — Skills Detail (lazy-loaded)
+
+Bind this to the parent Pi session only, on skill resolution/discovery. Not always-on; loaded on demand from `assets/orchestrator.md`'s `## Skill Registry Protocol` and `## Intent-Driven Skill Discovery` pointers.
+
+## Skill Registry Protocol
+
+The parent resolves skills once per session or before first delegation:
+
+1. Read `.atl/skill-registry.md` if present.
+2. Match task context and target files against the `Trigger / description` column.
+3. Pass only matching `Path` values to subagents under `## Skills to load before work`.
+4. Tell subagents to read those exact `SKILL.md` files before reading, writing, reviewing, testing, or creating artifacts.
+5. If the registry is absent, continue but mention that project-specific skill paths were unavailable.
+
+Subagents should receive exact indexed paths. They should not have to rediscover the registry.
+
+Important distinction: SDD subagents still use their assigned executor/phase skill (for example `sdd-apply`, `sdd-design`, or `sdd-verify`). What they should not do during normal runtime is independently discover additional project/user `SKILL.md` files or the registry. The parent passes selected project/user skill paths explicitly.
+
+If a subagent reports `skill_resolution`, interpret it as project/user skill resolution:
+
+- `paths-injected`: parent supplied `## Skills to load before work` with exact `SKILL.md` paths.
+- `fallback-registry`: subagent self-loaded skill paths from the registry because parent paths were missing; degraded but auditable.
+- `fallback-path`: subagent loaded explicit skill paths because parent paths were missing; degraded but auditable.
+- `none`: no project/user skills were loaded.
+
+If any subagent reports a fallback instead of `paths-injected`, treat it as an orchestration gap and correct future delegations by passing exact indexed paths directly.
+
+## Intent-Driven Skill Discovery
+
+For skill-shaped requests, do not treat injected `<available_skills>` as complete. Use the registry and filesystem only as a discovery aid; do not let a trigger table override the user's concrete request or turn a small request into a larger workflow.
+
+Discovery order:
+
+1. Read `.atl/skill-registry.md` when present.
+2. If the registry suggests a specific skill, load the indexed `SKILL.md` path before acting.
+3. If the expected skill is absent from the registry but the request clearly names a known workflow, search common project/user skill dirs such as `./skills`, `.pi/skills`, `.agents/skills`, `~/.config/opencode/skills`, `~/.claude/skills`, and other configured skill roots.
+4. Prefer the most specific project skill over a global skill with the same intent.
+5. If no matching skill exists, continue with the smallest safe fallback and say which expected skill was unavailable.
+
+Common intent hints, not hard routing:
+
+| User intent                | Skill to check                         |
+| -------------------------- | -------------------------------------- |
+| PR review / GitHub PR URL  | project review skill, then `pr-review` |
+| Post-ready review comments | `comment-writer`                       |
+| Create/open/prepare PR     | `gentle-ai-branch-pr`                  |
+| Split/stack/large PR       | `gentle-ai-chained-pr`                 |
+
+Keep this lightweight: loading a skill should improve the immediate task, not force extra ceremony.