gentle-pi 3.7.0 → 4.1.0

package/skills/chained-pr/SKILL.md

@@ -9,45 +9,61 @@ metadata:
 
 ## Activation Contract
 
-Load this skill when a planned PR may exceed **400 changed lines**, SDD forecasts `400-line budget risk: High` or `Chained PRs recommended: Yes`, an ODD feature's forecast or running authored changed-line count from work-unit commits exceeds about 400, or the user asks for chained/stacked PRs, review slices, or reviewer-load control.
+Load this skill when a planned PR may exceed **400 changed lines**, an ODD feature's forecast or running authored changed-line count from work-unit commits exceeds about 400, or the user asks for chained/stacked PRs, review slices, or reviewer-load control. The per-task advisory 400 authored-line heuristic does not itself require a PR split.
 
 ## Hard Rules
 
-- Split PRs over **400 changed lines** unless a maintainer explicitly accepts `size:exception`.
+- Recommend slicing PRs over **400 changed lines**; offer the ordered oversized-delivery menu below and follow the user's selection subject to the destination repository's documented contribution/size policy.
+- `size:exception` is a Gentle-owned repository policy, not a universal label requirement. Never request, create, or add this label for generic users unless the destination policy uses it. Preserve that policy's maintainer acceptance gates and protected-label human authorization; selection alone grants neither.
 - The budget constrains how work is **sliced**, never the code itself. Never delete comments, blank lines, docs, or tests, and never compress or restyle code, to fit under the budget.
-- Slicing is bounded: make **one** honest slicing pass. If no cohesive split brings every slice within budget, stop iterating, keep the best cohesive split, and report the final line count with a `size:exception` recommendation.
+- Slicing is bounded: make **one** honest slicing pass. If no cohesive split brings every slice within budget, stop iterating, keep the best cohesive split, and report the final line count and rationale. Recommend a size exception only when the destination policy provides that route.
 - Keep each PR reviewable in about **≤60 minutes**.
-- Use one deliverable work unit per PR; keep tests/docs with the unit they verify.
+- In a chain, use one deliverable work unit per PR; keep tests/docs with the unit they verify. A selected single PR may contain multiple coherent work-unit commits.
 - State start, end, prior dependencies, follow-up work, and out-of-scope items in every chained PR.
 - Every child PR must include a dependency diagram marking the current PR with `📍`.
 - In Feature Branch Chain, create a draft/no-merge tracker PR; child PR #1 targets the tracker branch, later children target the immediate parent branch.
 - Treat polluted diffs as base bugs: retarget or rebase until only the current work unit appears.
 - Do not mix chain strategies after the user chooses one.
+- Before creating branches or PRs, verify the target repository's default branch; use it as the integration base, not an assumed `main`. `stacked-to-main` is the historical strategy token even when the default branch has another name.
+
+## Oversized Delivery Menu
+
+Offer exactly three choices in this semantic order; English examples are illustrative and localizable, not mandatory copy. Generate the complete user-facing question, every option label, description, and recommendation marker in the active user's conversation language (English for an English user, Spanish for a Spanish user, etc.). Machine strategy tokens remain unchanged and untranslated.
+
+1. **Feature/tracker branch chain** — `chain_strategy=feature-branch-chain`; review child slices before final feature integration.
+2. **Verified default/main branch chain** — `chain_strategy=stacked-to-main`; land independently reviewable slices in order on the verified default branch, whatever its name.
+3. **One single PR — least recommended** — `delivery_strategy=single-pr`; keep the entire change in one PR rather than a chain.
+
+The third choice overrides the pending chaining path: clear the chain choice as inapplicable and suppress later chain prompts. `single-pr` is not a `chain_strategy` token. Do not automatically select `exception-ok` or imply an accepted policy exception.
+
+The least recommended marker applies only to this oversized menu. An oversized single PR increases reviewer cognitive load, slows feedback, and couples rollback of otherwise separable work; a focused single PR within 400 changed lines remains reasonable. Delivery selection does not authorize push, PR creation, merge, or changes to review mode or candidate consent.
 
 ## Decision Gates
 
 | Condition | Action |
 |---|---|
 | PR ≤400 changed lines and focused | Keep single PR. |
-| PR >400, each slice can land independently | Use Stacked PRs to main. |
-| PR >400, feature must integrate before main | Use Feature Branch Chain with tracker. |
-| Generated/vendor/migration diff cannot split cleanly | Ask maintainer for `size:exception`. |
-| No cohesive split fits the budget after one slicing pass | Stop; deliver the best split, report the overage and why it cannot shrink further, and recommend `size:exception`. |
-| SDD provides `delivery_strategy` | Follow it before apply/PR creation. |
-| ODD provides `delivery_strategy` and `chain_strategy` | Follow them before the next work-unit commit or PR creation. |
+| PR >400, each slice can land independently | Recommend Stacked PRs to the verified default branch; respect the selected delivery strategy. |
+| PR >400, feature must integrate before the default branch | Recommend Feature Branch Chain with tracker; respect the selected delivery strategy. |
+| Generated/vendor/migration diff cannot split cleanly | Report the overage; follow destination policy for any required exception. |
+| No cohesive split fits the budget after one slicing pass | Stop slicing; report the best cohesive split and why it cannot shrink further, then apply the selected delivery strategy and destination policy. |
+| ODD `delivery_strategy` is `ask-on-risk` | When the budget is exceeded, ask once using the menu above for a chain strategy or single PR before the next work-unit commit. |
+| ODD `delivery_strategy` is `auto-chain` | Ask for a chain strategy only when missing; otherwise use the cached choice. |
+| ODD `delivery_strategy` is `single-pr` | Follow the destination repository's documented contribution/size policy for the overage; do not ask for a chain strategy. |
+| ODD `delivery_strategy` is `exception-ok` | Record the explicitly accepted exception under destination policy, including `size:exception` only where applicable; do not ask for a chain strategy. |
 
 ## Execution Steps
 
 1. Estimate changed lines and identify independent work units.
-2. Ask for a chain strategy when none is cached and the budget is exceeded.
-3. Create branches/PRs using the chosen strategy only.
-4. Add Chain Context to each PR without replacing the repo PR template.
+2. Apply the delivery-strategy gate above; offer the menu only on a chaining path that needs a choice. For `auto-chain`, use a cached chain strategy without prompting again; if missing, offer all three choices.
+3. Verify the target repository's default branch before creating branches/PRs; use the chosen strategy only.
+4. On chaining paths only, add Chain Context to each child PR without replacing the repo PR template.
 5. Verify each PR independently: CI/tests/docs/manual checks, rollback scope, and clean diff.
-6. Keep tracker PR draft/no-merge until all child PRs are reviewed and integrated.
+6. For Feature Branch Chain only, keep tracker PR draft/no-merge until all child PRs are reviewed and integrated.
 
 ## Output Contract
 
-Return the chosen strategy, PR order, current PR boundary, dependency diagram, review budget (`additions + deletions`), verification plan, and any `size:exception` rationale.
+Return the chosen delivery strategy, review budget (`additions + deletions`), scope, verification plan, and any destination-policy exception rationale. For chaining, also return PR order, current PR boundary, and dependency diagram. For `single-pr`, require no tracker, child dependency diagram, or Chain Context; use the destination PR template without chain-only artifacts.
 
 ## References
 

package/skills/chained-pr/references/chaining-details.md

@@ -2,19 +2,28 @@
 
 ## Strategy Notes
 
-| | Stacked PRs to main | Feature Branch Chain |
-|---|---|---|
-| Speed | Each slice can ship in order | Full feature waits for tracker merge |
-| Rollback | Revert individual main PRs | Revert/hold the whole feature branch |
-| Risk | Partial behavior may land | Nothing lands until the chain completes |
-| Complexity | Simpler retarget/rebase flow | Requires tracker and strict diff hygiene |
+Before creating branches or PRs, verify the target repository's default branch and use it as `<default branch>` throughout these examples. Do not infer it from the current local branch. The historical strategy token `stacked-to-main` means stacking onto that verified default branch, even when its name is not `main`.
+
+The oversized menu has exactly three outcomes in the order below. English examples are illustrative and localizable, not mandatory copy. Generate the complete user-facing question, every option label, description, and recommendation marker in the active user's conversation language (English for an English user, Spanish for a Spanish user, etc.). Machine strategy tokens remain unchanged and untranslated.
+
+| Ordered outcome | Feature/tracker branch chain | Default/main branch chain | One single PR — least recommended |
+|---|---|---|---|
+| Mapping | `chain_strategy=feature-branch-chain` | `chain_strategy=stacked-to-main` | `delivery_strategy=single-pr` |
+| Speed | Full feature waits for tracker merge | Each slice can ship in order | All feedback and delivery wait on one large review |
+| Rollback | Revert/hold the whole feature branch | Revert individual merged PRs | Revert the combined change |
+| Risk | Nothing lands until the chain completes | Partial behavior may land | Higher reviewer load and coupled scope |
+| Complexity | Requires tracker and strict diff hygiene | Retarget/rebase after parent merges | No chain artifacts, but harder review isolation |
+
+Selecting single PR overrides the pending chaining path: clear the chain choice as inapplicable and suppress later chain prompts. It is not a chain strategy and does not select `exception-ok`. Least recommended applies only to this oversized menu; focused ≤400-line single PRs remain reasonable. Use the destination PR template with scope, changed-line count, verification, and any applicable exception rationale; do not require a tracker, child dependency diagram, or Chain Context.
+
+Follow the destination repository's documented contribution/size policy. `size:exception` is a Gentle-owned repository policy, not a universal label requirement. Never request, create, or add the label for generic users unless the destination policy uses it. Preserve applicable maintainer acceptance and protected-label authorization. Delivery selection does not authorize push, PR creation, merge, or review-mode/consent changes.
 
 ## Feature Branch Chain
 
 Use when the feature branch accumulates the final integration while child PRs are reviewed as focused slices.
 
 ```text
-main
+<default branch>
  └── feat/my-feature              ← tracker/final integration branch
       ↑ PR #1 base: feat/my-feature
       └── feat/my-feature-01-core
@@ -26,27 +35,27 @@ main
 
 Steps:
 
-1. Create the feature/tracker branch from `main`.
-2. Open the tracker PR to `main`; mark it draft/no-merge.
+1. Create the feature/tracker branch from the verified `<default branch>`.
+2. Open the tracker PR to `<default branch>`; mark it draft/no-merge.
 3. Create PR #1 from a child branch and target it to the tracker branch.
 4. Create each later child branch from the previous PR branch and target it to that parent branch.
 5. Merge/integrate children in order; merge the tracker only after the chain is complete.
 
-## Stacked PRs to Main
+## Stacked PRs to Default Branch
 
-Use when each slice can land on `main` in order.
+Use when each slice can land on the verified `<default branch>` in order.
 
 ```text
-main <- PR 1: foundation
+<default branch> <- PR 1: foundation
           └── PR 2: feature slice built on PR 1
                 └── PR 3: docs/tests built on PR 2
 ```
 
-After a parent PR merges, rebase/retarget the next PR so GitHub shows only the current slice.
+Base PR #1 on the verified `<default branch>`; base each subsequent PR on its immediate parent until that parent merges. After a parent PR merges, rebase/retarget the next PR so GitHub shows only the current slice.
 
 ## Chain Context Section
 
-Append this section to the repo PR template; do not replace required issue/checklist sections.
+On chaining paths only, append this section to the repo PR template; do not replace required issue/checklist sections. Skip this entire section for a single PR.
 
 ```markdown
 ## Chain Context
@@ -66,7 +75,7 @@ Append this section to the repo PR template; do not replace required issue/check
 ### Chain Overview
 
 ```text
-main
+<default branch>
  └── #NNN Previous PR
       └── 📍 #NNN This PR
            └── #NNN Next PR
@@ -85,15 +94,17 @@ main
 
 ## Commands
 
+Before any remote read or PR creation, require explicit human authorization for the destination (exact host/repository), operation (PR read or creation), and credential/session. Do not probe credentials or remote targets to resolve ambiguity. Verify the target repository and its default branch using only the authorized session and destination; set `TARGET` to that verified host/repository. Stop if authorization or verification is missing. Each command below binds to that same verified target; the base branches must belong to it.
+
 ```bash
-gh pr view <PR_NUMBER> --json additions,deletions,changedFiles,title,url
-gh pr create --base feat/my-feature --title "feat(scope): focused slice" --body-file pr-body.md
-gh pr create --base feat/my-feature-01-core --title "feat(scope): next focused slice" --body-file pr-body.md
+gh pr view <PR_NUMBER> --repo "$TARGET" --json additions,deletions,changedFiles,title,url
+gh pr create --repo "$TARGET" --base feat/my-feature --title "feat(scope): focused slice" --body-file pr-body.md
+gh pr create --repo "$TARGET" --base feat/my-feature-01-core --title "feat(scope): next focused slice" --body-file pr-body.md
 ```
 
 ## Reviewer Guidance
 
-- Ask for a split when a PR exceeds 400 changed lines without `size:exception`.
-- Recommend Feature Branch Chain when work must integrate before `main`.
+- Recommend a split when a PR exceeds 400 changed lines; respect the selected delivery shape and enforce only the destination's documented size/exception policy.
+- Recommend Feature Branch Chain when work must integrate before the verified `<default branch>`.
 - Recommend stacked PRs when each slice can merge independently.
 - Review child PRs against immediate parent branches; a polluted diff is a branching bug.

package/skills/gentle-ai/SKILL.md

@@ -1,24 +1,24 @@
 ---
 name: gentle-ai
-description: "Use Gentle AI harness discipline for Pi work: clarify first, preserve OpenSpec artifacts, use strict TDD where available, delegate through subagents when useful, and protect review workload."
+description: "Use Gentle AI harness discipline for Pi work: clarify first, track ODD work, use applicable test-first development by default, delegate when useful, and protect review workload."
 ---
 
 # el Gentleman Harness
 
-Use this skill when work is non-trivial, risky, multi-step, or likely to benefit from SDD/OpenSpec artifacts.
+Use this skill for non-trivial, risky, or multi-step ODD work.
 
 ## Identity Rule
 
-When asked who or what you are, answer as el Gentleman: a Pi-specific coding-agent harness with senior architect persona, SDD/OpenSpec artifacts, and subagent coordination. Do not answer as a generic assistant.
+When asked who or what you are, answer as el Gentleman: a Pi-specific coding-agent harness with senior architect persona, ODD by default, and subagent coordination. Do not answer as a generic assistant.
 
 ## Compact Rules
 
 - Clarify scope, constraints, acceptance criteria, and non-goals before implementation.
-- Use OpenSpec-style artifacts for proposal, specs, design, tasks, apply progress, verify report, and archive notes.
-- If tests exist, follow strict TDD: RED, GREEN, TRIANGULATE, REFACTOR, and record evidence.
+- Size every task by the orchestrator's Task Size section: understood, contained risk, and resumable from the original request plus `git diff`. Counts of files, commands, tests, or fixes never decide it. Track only large work in its task document and mirror.
+- For behavior changes with applicable runnable deterministic tests and a clear expected outcome, use test-first by default: observe RED, GREEN, relevant alternate cases, then REFACTOR and record evidence. Test presence alone does not establish applicability. For passive documentation, non-testable changes, an unavailable runner, or no meaningful RED, state why and run proportionate ordinary functional or structural verification. Never invent RED/GREEN, skip checks, or require a chat/TUI toggle.
 - Keep one parent session responsible for orchestration; child subagents should receive concrete phase work and must not spawn more subagents.
-- Parent-only delegation triggers apply after complexity appears: 4+ files for understanding, 2+ non-trivial files to write, tooling/worktree incidents, or long sessions with accumulating complexity.
-- Keep writes single-threaded unless the user explicitly approves isolated parallel worktrees.
+- Parent-only delegation triggers fire one mechanism at a time: an open decision (ask), understanding beyond the evidence budget (explore), high risk (independent verifier), a large task (track), a writer reason (parallel units or context), tooling/worktree incidents, or a parent context past the context backstop.
+- Parallel writers only with disjoint Allowed edit surfaces (runtime-enforced) or isolated worktrees.
 - Forecast review workload before large changes; ask before producing oversized or multi-area diffs.
 - Keep dangerous-command safety independent and authoritative.
 - Never claim persistent memory is available because of el Gentleman itself; memory is provided by separate packages/tools when active.
@@ -30,29 +30,24 @@ When asked who or what you are, answer as el Gentleman: a Pi-specific coding-age
 Use the smallest safe harness:
 
 ```text
-small + known context      → inline direct
-unknown / context-heavy    → simple delegation
-large / ambiguous / risky  → SDD
+small task                 → inline direct, focused test and suite inline
+understanding is missing   → explore, then re-evaluate
+large authorized work      → track ODD tasks and implement by work unit
 ```
 
-For substantial changes:
+For large implementation with subagents:
 
 ```text
-clarify → explore → proposal → spec → design → tasks → apply → verify → archive
-```
-
-For bounded implementation with subagents:
-
-```text
-clarify → scout/context-builder when context-heavy → one worker → verify
+clarify → scout/context-builder when context-heavy → inline, or a writer only for a reason → verify
 ```
 
 Hard delegation triggers:
 
-- **4-file rule**: reading 4+ files to understand means delegate exploration.
-- **Multi-file write rule**: touching 2+ non-trivial files means use one worker.
+- **Evidence-budget rule**: read inline only when the evidence fits one parallel batch of at most 3 calls, ~10k tokens (grep and line ranges, never whole large files). When understanding needs more reading or more than ~5 sequential lookups, delegate one explorer that returns a handoff of at most ~2k tokens with `path:line` evidence. Never force delegation for a small targeted question; do not re-read what the handoff covered beyond one spot check.
+- **Writer rule**: a writer only for a reason (parallel units launched together, or context); size and file count never fire it.
+- **Verification rule**: a high-risk change gets an independent verifier; otherwise the change's own focused test and suite run inline.
 - **Incident rule**: after wrong cwd, accidental worktree/repo mutation, merge recovery, confusing test command, or environment workaround, diagnose separately.
-- **Long-session rule**: after roughly 20 tool calls, 5 exploratory reads, or 2 non-mechanical edits with no delegation and accumulating complexity, pause and choose a non-review subagent or justify not doing so.
+- **Context backstop**: when the parent context passes ~150k tokens, pause and delegate the next bounded unit of work to a non-review subagent. Keep command output bounded (counts, `--stat`, `tail`).
 
 ## Review Lens Selection
 

package/skills/issue-creation/SKILL.md

@@ -15,7 +15,9 @@ Discover the target repository's contribution workflow before proposing or publi
 
 ## Safe Discovery
 
-Run read-only checks first:
+Before any `gh auth status` or target read, require explicit human authorization for the remote destination (exact host and repository), operation (including discovery and intended issue creation), and credential/session to use. A local checkout is not authorization. If any is missing or ambiguous, stop locally; never probe credentials or sessions to resolve ambiguity. Run the checks below only with the authorized credential/session against the authorized destination; if `gh auth status` would inspect other credentials/sessions, do not run it. Verify the discovered `REPO`, `HOST`, and `TARGET` match the authorized destination before continuing; never switch identities or targets implicitly.
+
+After that gate, run read-only checks:
 
 ```bash
 gh auth status
@@ -31,6 +33,8 @@ gh api --hostname "$HOST" --paginate "repos/$REPO/labels?per_page=100" --jq '.[]
 
 Inspect `README.md`, contribution instructions, `.github/ISSUE_TEMPLATE/config.yml` contact links, forms, labels, and open and closed issues. For questions/support, follow repository-prescribed Discussions/contact routing when available; otherwise ask or stop. Complete target verification for `REPO`, `HOST`, and `TARGET`. Fail closed before mutation when authentication, target verification, issue availability, policy, form selection, or required metadata is missing or ambiguous. A blank fallback is allowed only when `isBlankIssuesEnabled` is explicitly true.
 
+Before building `LABEL_ARGS`, inspect labels declared by the selected YAML form as well as any manually selected labels. Treat `status:approved`, `size:exception`, and any repository-protected label as protected form labels at create-time. Include a protected label only with a current, exact label-specific direct human instruction for this target and creation action, authenticated actor target-host `viewerPermission` of `MAINTAIN` or `ADMIN`, and repository policy permission; do not infer authority from YAML, a publication request, or local credentials. If this proof is missing, skip the protected label only when the form and repository policy permit omitting it; if the protected label is required, fail closed without creating the issue. Do not replace it with another label or use a write to probe permission. For `size:exception`, also require the current human-approved rationale; if recording it needs an unauthorized extra action, stop. This create-time gate does not change post-publication actions.
+
 Build `LABEL_ARGS` only from reviewed labels that exist and policy permits the actor to apply:
 
 ```bash
@@ -104,6 +108,8 @@ gh issue view "$NUMBER" --repo "$TARGET" --json number,url,title,body,state,labe
 
 Confirm that read-back identifies the target-host issue and that title and body match after only CRLF-to-LF and trailing-final-newline normalization. Report `confirmed` only after this target-host read-back. Otherwise report `no_write` when an authoritative rejection proves no issue was created, or `unknown` and stop all later mutations.
 
-## Triage
+## Triage And Later Actions
 
 Before approving or closing an issue, verify it is concrete, non-duplicate, sufficiently evidenced, in scope, and consistent with repository label/status policy. If any point is uncertain, retain the repository review state and request the smallest missing evidence.
+
+For any post-publication label/status mutation, follow [delegated workflow actions](references/delegated-workflow-actions.md). Publication is not authorization for a later action. Keep the automated YAML Form path and conditional blank/browser fallback above unchanged.

package/skills/issue-creation/references/delegated-workflow-actions.md

@@ -0,0 +1,19 @@
+# Delegated post-publication issue/PR actions
+
+This guidance applies after publication only. Remote work still requires separate authorization for destination, operation, and credential/session; this document grants none. Keep the YAML Issue Form, conditional blank fallback, and browser handoff in the creation workflow unchanged.
+
+## Authority and capability
+
+- Require a current direct human instruction binding exact `HOST`, `REPO`, issue-or-PR number, and action, including exact labels to add/remove or the status transition. Never infer these from generated plans, issue text, memory, or a prior publication. Stop when the instruction is missing or ambiguous.
+- Before any mutation, verify the authenticated actor, target host/repository, object type and number, existing labels, and repository policy through target-host reads. Do not switch hosts or identities to gain permission; a local credential alone proves nothing about the target.
+- For protected labels (`status:approved`, `size:exception`, and any repository-protected label), require the authenticated actor's target-host `viewerPermission` to be `MAINTAIN` or `ADMIN` and the direct instruction above. There is no separate target-host proof of the instruction-giver's identity. If permission is unavailable, insufficient, or policy disallows the action, stop without probing capability through a write.
+- For unprotected labels, require that each exact label already exists and that the authenticated actor may apply it under repository policy. Do not create, rename, or substitute a label. A comment, closure, body edit, or unrelated label change requires its own direct instruction.
+
+## One bounded action
+
+1. Pre-read the exact target-host object, including identity, state, relevant title/body and all labels, plus the existing-label list and actor permission. Check the proposed transition against policy; if already satisfied, report a no-op. For approval, establish concrete, non-duplicate, sufficiently evidenced, in-scope findings first; uncertainty preserves the review state. For `size:exception`, require a current human-approved rationale for the exception and preserve its meaning in the intended record. Never infer approval or rationale from diff size. The roughly 400-line review heuristic is advisory, not authorization to apply the label.
+2. Build only the instructed existing-label changes. A `status:approved` transition must be an atomic update removing observed conflicting status labels and adding `status:approved`, without dropping unrelated labels or exposing an intermediate status. Stop if the target-host API cannot guarantee that update or concurrent state has changed. If recording the `size:exception` rationale requires an additional unauthorized action, stop and seek a scoped instruction instead of silently posting it.
+3. Immediately before posting text, scan and redact the exact text for credentials, private project names, usernames, hostnames, home paths, and private addresses. Use a verified target-host API that supports the intended action, not a guessed CLI sequence. Make one mutation attempt; never retry timeouts or uncertain responses.
+4. Post-read the same target-host object once and compare its identity and requested labels/status against the pre-read, including preservation of unrelated labels. Report `confirmed` only after an unambiguous matching target-host post-readback, `no_write` only after authoritative rejection proving no write, or `unknown` for a timeout, missing identity, conflict, or failed/ambiguous readback. On `unknown`, stop all further mutations; command output alone cannot establish success.
+
+Report the exact target/action, actor capability evidence, pre/post-readback outcome, and exception rationale when applicable without leaking private text. Operational checkboxes in the publication form may be marked only from retained agent evidence; personal, legal and user-consent declarations require explicit first-person user affirmation, never a delegated label action or the publication request. For implementation work leading to an issue or PR, retain the applicable ODD default and test-first checks; this action guide does not replace them.

package/skills/work-unit-commits/SKILL.md

@@ -30,7 +30,7 @@ Use it for:
 | Keep docs with the user-visible change | Docs belong with the feature or workflow they explain. |
 | Tell a story | A reviewer should understand why each commit exists from its diff and message. |
 | Future PR-ready | Each commit should be a candidate chained PR when the change grows. |
-| SDD workload guard | If SDD tasks forecast a >400-line change, group commits into chained PR slices before implementation. |
+| SDD workload guard | If SDD tasks forecast a >400-line change, honor the selected `delivery_strategy`. On chaining paths only, group commits into chained PR slices before implementation. For explicit `single-pr` or `exception-ok`, keep one PR, report the review load, and follow the destination repository's documented contribution/size policy; selection alone does not accept an exception. |
 | Budget is not code-golf | Never shrink a diff by deleting comments, blank lines, docs, or tests, or by compressing code, to fit the review budget (400 by default, or the session `review_budget_lines`). Slice by work unit or report the overage. |
 
 ## Work Unit Checklist
@@ -67,8 +67,9 @@ When `sdd-tasks` produces a Review Workload Forecast:
 
 - Low risk: keep work-unit commits inside one PR.
 - Medium risk: commit by work unit and monitor changed lines before PR creation.
-- High risk: follow SDD `delivery_strategy` — ask on `ask-on-risk`, auto-slice on `auto-chain`, require `size:exception` on over-budget `single-pr`, or record accepted `size:exception` on `exception-ok`.
-- Splitting is bounded: after one honest slicing pass, if no cohesive work-unit split fits the budget, stop and report the smallest honest count with a `size:exception` recommendation. Do not iterate shrinking the code to reach the number.
+- High risk: follow SDD `delivery_strategy` — ask on `ask-on-risk`, auto-slice with the cached chain choice on `auto-chain`, follow the destination repository's documented contribution/size policy on over-budget `single-pr`, or record an explicitly accepted policy exception on `exception-ok`. A single-PR selection does not itself accept an exception.
+- `size:exception` is a Gentle-owned repository policy, not a universal label requirement. Never request, create, or add the label for generic users unless the destination policy uses it; preserve its maintainer acceptance and protected-label authorization gates.
+- Splitting is bounded: after one honest slicing pass, if no cohesive work-unit split fits the budget, stop and report the smallest honest count and rationale. Recommend an exception only where destination policy provides it. Do not iterate shrinking the code to reach the number.
 
 Each SDD work unit should map cleanly to a commit or PR with:
 

package/tests/agent-home.test.ts

@@ -1,9 +1,10 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
-import { gentlePiConfigHome } from "../lib/agent-home.ts";
+import { bundledGentlePiAgentHome, gentlePiConfigHome } from "../lib/agent-home.ts";
+import { setBundledInstallForTesting } from "../lib/gentle-shell-bundled.ts";
 
 // The two Pi homes: `~/.pi/agent` holds Pi's own agent definitions and
 // `~/.pi/gentle-ai` holds everything the Gentle AI commands own. Both are resolved
@@ -15,7 +16,9 @@ function isolatedHome(t: test.TestContext): string {
 	const home = mkdtempSync(join(tmpdir(), "gentle-pi-config-home-"));
 	const previousHome = process.env.HOME;
 	const previousUserProfile = process.env.USERPROFILE;
-	// Isolation must cover POSIX and Windows, the way homedir() resolves each.
+	const previousConfigHome = process.env.GENTLE_PI_CONFIG_HOME;
+	// Clear the higher-priority config override as well as isolating both OS homes.
+	delete process.env.GENTLE_PI_CONFIG_HOME;
 	process.env.HOME = home;
 	process.env.USERPROFILE = home;
 	t.after(() => {
@@ -23,6 +26,8 @@ function isolatedHome(t: test.TestContext): string {
 		else process.env.HOME = previousHome;
 		if (previousUserProfile === undefined) delete process.env.USERPROFILE;
 		else process.env.USERPROFILE = previousUserProfile;
+		if (previousConfigHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previousConfigHome;
 		rmSync(home, { recursive: true, force: true });
 	});
 	return home;
@@ -41,6 +46,25 @@ test("gentlePiConfigHome honours GENTLE_PI_CONFIG_HOME and otherwise falls back
 	);
 });
 
+test("the isolated home restores defined and undefined config overrides", async (t) => {
+	const previousConfigHome = process.env.GENTLE_PI_CONFIG_HOME;
+	try {
+		for (const inherited of [undefined, "/synthetic-inherited-config"]) {
+			if (inherited === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+			else process.env.GENTLE_PI_CONFIG_HOME = inherited;
+			await t.test(`inherited override: ${inherited === undefined ? "unset" : "set"}`, (child) => {
+				const home = isolatedHome(child);
+				assert.equal(process.env.GENTLE_PI_CONFIG_HOME, undefined);
+				assert.equal(gentlePiConfigHome(), join(home, ".pi", "gentle-ai"));
+			});
+			assert.equal(process.env.GENTLE_PI_CONFIG_HOME, inherited);
+		}
+	} finally {
+		if (previousConfigHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previousConfigHome;
+	}
+});
+
 test("the config home ignores the Pi agent-home overrides", (t) => {
 	const home = isolatedHome(t);
 	// PI_CODING_AGENT_DIR and GENTLE_PI_AGENT_HOME move Pi's agent directory only.
@@ -50,3 +74,32 @@ test("the config home ignores the Pi agent-home overrides", (t) => {
 		join(home, ".pi", "gentle-ai"),
 	);
 });
+
+// S9: a bundled Gentle Shell keeps gentle-pi's config inside its prefix. It is
+// derived from this package's bundled install and the launcher's
+// GENTLE_SHELL_PREFIX, never exported (Gentle AI 4.0.0 reads
+// GENTLE_PI_CONFIG_HOME as a parent folder). The testing overlay stands in for
+// this package running from that install.
+function bundledInstall(t: test.TestContext): string {
+	const prefix = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-bundled-config-")));
+	setBundledInstallForTesting({ root: prefix });
+	t.after(() => {
+		setBundledInstallForTesting(undefined);
+		rmSync(prefix, { recursive: true, force: true });
+	});
+	return prefix;
+}
+
+test("a bundled install derives the config home inside its prefix and the agent home from Pi's", (t) => {
+	isolatedHome(t);
+	const prefix = bundledInstall(t);
+	const env = { GENTLE_SHELL_PREFIX: prefix, GENTLE_PI_CONFIG_HOME: "/home/ana/.pi/gentle-ai", PI_CODING_AGENT_DIR: "/agent" };
+	assert.equal(gentlePiConfigHome(env), join(prefix, "config", "gentle-ai"));
+	assert.equal(bundledGentlePiAgentHome(env), "/agent");
+	// Another prefix, or none, is not this install: everything stays as before.
+	for (const other of [{ GENTLE_PI_CONFIG_HOME: "/custom" }, { GENTLE_SHELL_PREFIX: join(prefix, "other"), GENTLE_PI_CONFIG_HOME: "/custom" }]) {
+		assert.equal(gentlePiConfigHome(other), "/custom");
+		assert.equal(bundledGentlePiAgentHome({ ...other, PI_CODING_AGENT_DIR: "/agent" }), undefined);
+	}
+	assert.equal(gentlePiConfigHome({ GENTLE_PI_CONFIG_HOME: "" }), join(homedir(), ".pi", "gentle-ai"));
+});

package/tests/agent-model-resolution.test.ts

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import test, { after } from "node:test";
+import { resolveAgentHomeDirectory, resolveEffectiveAgentModel, resolvePinnedAgentProfile } from "../lib/agent-model-resolution.ts";
+import type { AgentDefinition } from "../lib/agents-config.ts";
+
+// gentle-shell#1731 S3/AC3: the subagent launch and the harness model-routing
+// fact resolve the effective subagent model through one helper, so the fact
+// can never disagree with the model a launch would actually use.
+
+const root = mkdtempSync(join(tmpdir(), "gentle-pi-agent-model-resolution-"));
+after(() => rmSync(root, { recursive: true, force: true }));
+
+function fixture(name: string) {
+	const base = join(root, name);
+	const home = join(base, "home");
+	const agentHome = join(base, "agent-home");
+	const cwd = join(base, "project");
+	const commonDir = join(base, "git-common");
+	const configHome = join(base, "config");
+	for (const dir of [home, join(agentHome, "agents"), cwd, commonDir, configHome]) mkdirSync(dir, { recursive: true });
+	return {
+		roots: { cwd, home, agentHome },
+		cwd,
+		configHome,
+		resolveWorktree: () => ({ root: cwd, commonDir }),
+		writeAgent(agentName: string, model?: string) {
+			writeFileSync(join(agentHome, "agents", `${agentName}.md`), `---\nname: ${agentName}\ndescription: Test agent.\n${model === undefined ? "" : `model: ${model}\n`}---\nBody.\n`);
+		},
+		writeSubagents(config: Record<string, unknown>) {
+			writeFileSync(join(agentHome, "subagents.json"), JSON.stringify(config));
+		},
+		writePinnedProfile(profiles: Record<string, unknown>, pin: string) {
+			writeFileSync(join(configHome, "profiles.json"), JSON.stringify({ kind: "gentle-pi.agent_model_profiles", version: 1, profiles }));
+			mkdirSync(join(commonDir, "gentle-ai"), { recursive: true });
+			writeFileSync(join(commonDir, "gentle-ai", "profile-pin.json"), JSON.stringify({ kind: "gentle-pi.agent_model_profile_pin", version: 1, profile: pin }));
+		},
+	};
+}
+
+const orchestrator = { provider: "anthropic", id: "fable" };
+
+test("the effective worker model comes from the global subagent profile", () => {
+	const f = fixture("global-profile");
+	f.writeAgent("gentle-ai-worker");
+	f.writeSubagents({ model_profiles: { "gentle-ai-worker": { model: "anthropic/opus" } } });
+	assert.deepEqual(
+		resolveEffectiveAgentModel("gentle-ai-worker", { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree, fallback: orchestrator }),
+		{ agent: "gentle-ai-worker", model: { provider: "anthropic", id: "opus" }, inherited: false },
+	);
+});
+
+test("a repository profile pin replaces global routing for the effective worker model", () => {
+	const f = fixture("pinned-profile");
+	f.writeAgent("gentle-ai-worker");
+	f.writeSubagents({ model_profiles: { "gentle-ai-worker": { model: "anthropic/opus" } } });
+	f.writePinnedProfile({ cheap: { "gentle-ai-worker": { model: "openai/mini" } } }, "cheap");
+	assert.deepEqual(
+		resolveEffectiveAgentModel("gentle-ai-worker", { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree, fallback: orchestrator })?.model,
+		{ provider: "openai", id: "mini" },
+	);
+});
+
+test("the agent definition model applies when no profile routes the agent", () => {
+	const f = fixture("definition-model");
+	f.writeAgent("gentle-ai-worker", "openai/defined");
+	assert.deepEqual(
+		resolveEffectiveAgentModel("gentle-ai-worker", { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree, fallback: orchestrator })?.model,
+		{ provider: "openai", id: "defined" },
+	);
+});
+
+test("an unrouted agent inherits the fallback session model", () => {
+	const f = fixture("inherit");
+	f.writeAgent("gentle-ai-worker");
+	assert.deepEqual(
+		resolveEffectiveAgentModel("gentle-ai-worker", { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree, fallback: orchestrator }),
+		{ agent: "gentle-ai-worker", model: orchestrator, inherited: true },
+	);
+	assert.deepEqual(
+		resolveEffectiveAgentModel("gentle-ai-worker", { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree }),
+		{ agent: "gentle-ai-worker", model: undefined, inherited: true },
+	);
+});
+
+test("an undiscovered agent resolves to undefined", () => {
+	const f = fixture("missing-agent");
+	assert.equal(
+		resolveEffectiveAgentModel("gentle-ai-worker", { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree, fallback: orchestrator }),
+		undefined,
+	);
+});
+
+test("resolvePinnedAgentProfile returns the launch profile with its model and thinking", () => {
+	const f = fixture("launch-profile");
+	f.writePinnedProfile({ deep: { explore: { model: "openai/alpha", thinking: "minimal" } } }, "deep");
+	const agent: AgentDefinition = { name: "explore", description: "", filePath: "", scope: "global", instructions: "", model: undefined, thinking: undefined, mode: undefined, tools: [] };
+	const profile = resolvePinnedAgentProfile(agent, { roots: f.roots, pinCwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree });
+	assert.deepEqual(profile.model, { provider: "openai", id: "alpha" });
+	assert.equal(profile.thinking, "minimal");
+	assert.equal(profile.source.model, "profile");
+});
+
+test("resolveAgentHomeDirectory follows the environment, expands tildes, and keeps explicit overrides literal", () => {
+	const home = "/home/tester";
+	assert.equal(resolveAgentHomeDirectory({ env: { GENTLE_PI_AGENT_HOME: "/opt/agents" }, home }), resolve("/opt/agents"));
+	assert.equal(resolveAgentHomeDirectory({ env: { PI_CODING_AGENT_DIR: "~/pi-agent" }, home }), resolve(join(home, "pi-agent")));
+	assert.equal(resolveAgentHomeDirectory({ env: { GENTLE_PI_AGENT_HOME: "~" }, home }), resolve(home));
+	assert.equal(resolveAgentHomeDirectory({ env: { GENTLE_PI_AGENT_HOME: "/ignored" }, home, homeOverridden: true }), resolve(join(home, ".pi", "agent")));
+	assert.equal(resolveAgentHomeDirectory({ env: {}, home, agentHome: "/explicit" }), resolve("/explicit"));
+});

package/tests/agent-profiles.test.ts

@@ -437,6 +437,24 @@ test("normalizeProfilesFile drops an active marker that points nowhere", () => {
 	assert.equal(normalized?.drops.droppedProfiles.length, 0);
 });
 
+test("normalizeProfilesFile accepts effort as alias for thinking in profile entries (#1403)", () => {
+	const normalized = normalizeProfilesFile(
+		JSON.parse(
+			profilesText({
+				hybrid: {
+					"example-agent": { model: "anthropic/claude-sonnet-4", effort: "medium" },
+					"worker": { effort: "high" },
+				},
+			}),
+		),
+	);
+	assert.deepEqual(normalized?.file.profiles.hybrid, {
+		"example-agent": { model: "anthropic/claude-sonnet-4", thinking: "medium" },
+		"worker": { model: undefined, thinking: "high" },
+	});
+	assert.equal(normalized?.drops.droppedAgents.length, 0);
+});
+
 test("bootstrapProfilesFile seeds a current profile, active only when routing is non-empty", () => {
 	const empty = bootstrapProfilesFile({});
 	assert.deepEqual(empty, {
@@ -749,3 +767,15 @@ test("formatOrchestratorSelection separates set, inherit, and inherit-with-think
 		"nan/glm5.3 · max",
 	);
 });
+
+test("buildProfileListItems marks the session-bound profile ahead of the pinned one", () => {
+	const file = createProfile(createProfile(emptyProfilesFile(), "work", { worker: { model: "zai/glm-4.7" } }), "personal", { solo: { model: "openai/o4-mini" } });
+	const items = buildProfileListItems(file, "work", "personal");
+	assert.equal(items.find((item) => item.id === "personal")?.label, "personal (session)");
+	assert.equal(items.find((item) => item.id === "work")?.label, "work (pinned)");
+	assert.equal(items.find((item) => item.id === "personal")?.description, "1 role");
+	const both = buildProfileListItems(file, "work", "work");
+	assert.equal(both.find((item) => item.id === "work")?.label, "work (session)", "the session marker outranks the pin marker on the same profile");
+	const unbound = buildProfileListItems(file, "work");
+	assert.equal(unbound.find((item) => item.id === "personal")?.label, "personal", "no session marker without a binding");
+});