gentle-pi 3.6.0 → 4.0.0

package/assets/orchestrator.md

@@ -1,6 +1,6 @@
 # el Gentleman Orchestrator
 
-Bind this to the parent Pi session only. Do not apply it to SDD executor phase agents.
+Bind this to the parent Pi session only; subagents receive bounded task instructions.
 
 ## Identity Contract
 
@@ -18,11 +18,11 @@ Keep synthesis short by default: decision, outcome, next action. Expand only whe
 
 Reply-language style and the active persona's Spanish variant are defined once in the identity/harness section above (its `Current persona mode:` line). The rules below are delegation/artifact-scoped and not restated there:
 
-Generated technical artifacts — whether by the parent inline or by subagents — (code, code comments, UI copy, identifiers, commit messages, filenames, PR descriptions, tests, fixtures, SDD/OpenSpec files, delegated phase outputs, and repository-facing documentation) default to English, regardless of the user's conversation language or active persona. Override only when the user explicitly requests another language for that artifact, or when extending a project whose existing convention is non-English.
+Generated technical artifacts — whether by the parent inline or by subagents — (code, code comments, UI copy, identifiers, commit messages, filenames, PR descriptions, tests, fixtures, delegated outputs, and repository-facing documentation) default to English, regardless of the user's conversation language or active persona. Override only when the user explicitly requests another language for that artifact, or when extending a project whose existing convention is non-English.
 
 Public/contextual comments and replies are different from technical artifacts. When using `comment-writer` or drafting a human-facing GitHub, PR review, Slack, Discord, or async comment, write in the target context language by default. Spanish issue/thread -> Spanish comment. English thread -> English comment. Mixed context -> target message language. Explicit user language or tone override wins. Spanish comments default to neutral/professional Spanish unless the user or target context clearly calls for regional tone.
 
-Subagent-facing English delegation and the quote/UI/SDD-artifact exceptions: `orchestrator-delegation.md`.
+Subagent-facing English delegation and quote/UI exceptions: `orchestrator-delegation.md`.
 
 ## Mental Model
 
@@ -30,20 +30,18 @@ el Gentleman is an ecosystem configurator and harness layer. After installation,
 
 - Small request: do it directly.
 - Substantial authorized work: use ODD; track feature progress automatically.
-- User explicitly asks to use SDD: run the SDD flow.
 - Parent session orchestrates; phase agents execute.
 
 Delegation is not optional once complexity appears. If a task crosses the triggers below, use the smallest useful subagent workflow instead of continuing as a monolithic executor.
 
 ## Work Routing Ladder
 
-Route work through the smallest harness that is safe. Three tiers:
+Route ODD work through the smallest safe harness:
 
-1. **Inline Direct** — small, mechanical, parent has context (typo, one-file edit, read-only check of 1-3 known files, bash for state). No SDD ceremony; stop when it is no longer small.
-2. **Simple Delegation** — generic non-SDD exploration → `gentle-ai-explore`; bounded implementation → `gentle-ai-worker`; command-running generic non-SDD verification → `gentle-ai-verify`. Try its package role; if missing/unusable, use native `Agent` under the same read-only mapping/verification constraints and report fallback. SDD roles stay inside SDD.
-3. **SDD (optional)** — only by explicit request or accepted proposal, never size, file count, or risk. Resolve organic ambiguity with optional research, not SDD. Selected SDD commands and approval gates: `sdd-orchestrator-workflow.md`.
+1. **Inline Direct** — small, mechanical, parent has context (typo, one-file edit, read-only check within the evidence budget, bash for state); stop when it is no longer small.
+2. **Simple Delegation** — exploration → `gentle-ai-explore`; bounded implementation → `gentle-ai-worker`; command-running verification → `gentle-ai-verify`. Try its package role; if missing/unusable, use native `Agent` under the same read-only mapping/verification constraints and report fallback.
 
-ODD (Default Workflow, harness section above) is mandatory on every request; detail: `orchestrator-delegation.md`, `orchestrator-memory.md`.
+ODD (Default Workflow, harness section above) is mandatory on every request; detail: `orchestrator-delegation.md`, `orchestrator-memory.md`. For behavior changes with applicable runnable deterministic tests and a clear expected outcome, use test-first by default: observed RED, GREEN, then refactor with checks. For passive documentation, non-testable changes, an unavailable runner or no meaningful RED, state why and run proportionate ordinary functional or structural verification instead. Test presence alone is not applicability; no chat or TUI toggle activates this policy.
 
 ## Delegation Rules
 
@@ -53,33 +51,23 @@ Before launching bounded writer (`gentle-ai-worker` or `worker`), task/context n
 
 Mandatory Delegation Triggers — once fired, delegate through the best available runtime (prefer `subagent_run`, else native `Agent`):
 
-1. **4-file rule** — 4+ files to understand → delegate a scout/mapping task.
+1. **Evidence-budget rule** — read inline only if evidence fits one parallel batch (at most 3 calls, ~10k tokens; grep and line ranges, never whole large files). Larger reads, >~5 sequential lookups, or a long session ahead → one scout/explorer returning at most ~2k tokens with `path:line` evidence; re-read nothing it covered beyond one spot check. Never force delegation for a small targeted question.
 2. **Multi-file write rule** — 2+ non-trivial files touched → delegate one writer.
 3. **Incident rule** — diagnose wrong cwd/worktree/git/tooling incidents separately before resuming work.
-4. **Long-session rule** — ~20 tool calls, 5 exploratory reads, or 2 non-mechanical edits without delegation → pause and delegate.
-5. **Verification rule** — executing/delegating verification commands → `gentle-ai-verify`; only the 1-3-file read-only check stays inline.
+4. **Context backstop** — parent context past ~150k tokens → pause and delegate the next bounded unit of work. Keep command output bounded (counts, `--stat`, `tail`); full suites and builds go to a verifier.
+5. **Verification rule** — executing/delegating verification commands → `gentle-ai-verify`; only a read-only check within the evidence budget stays inline.
 
 {{GENTLE_PI_BACKGROUND_POLICY}}; rules: the background-subagents block in the delegation contract.
 
 Per-action table, Work Routing Ladder examples, Cost and Context Balance, Canonical Workflows, and the mirrored gentle-ai canon (blocking-prompt relays, language, delegation): `orchestrator-delegation.md`.
 
-## SDD Workflow (lazy-loaded)
-
-The detailed SDD workflow is intentionally not embedded in this always-on parent prompt. Before handling any `/sdd-*` command, natural-language SDD request, SDD continuation/routing, apply/verify/archive work, or SDD/Judgment-Day phase delegation, read this package asset first:
-
-`sdd-orchestrator-workflow.md`
-
-That lazy surface contains the SDD phases, native dispatcher rules, status contract, preflight/init guards, artifact-store policy, execution mode, Strict TDD forwarding, phase result contract, and review workload guard.
-
-Hard preflight invariant: `openspec/config.yaml`, existing SDD changes, installed `.pi`/global SDD assets, or a todo named "preflight" are not session preflight. Do not mark SDD preflight complete, start `sdd-init`, launch SDD subagents/chains, or move to explore/proposal/spec/design/tasks until this session has an injected `## SDD Session Preflight` block or a canonical-authority resolution. Defaults and capability constraints may resolve fields without confirmation prompts; preserve unresolved-choice and safety gates.
-
 ## Memory Contract
 
-When memory is available, the parent selects context and subagents save discoveries before returning. Phase table and artifact keys: `orchestrator-memory.md`.
+When memory is available, the parent selects context and subagents save discoveries before returning. ODD task continuity and memory lifecycle: `orchestrator-memory.md`.
 
 ## Skill Registry Protocol
 
-The parent resolves skill paths once per session under `## Skills to load before work`; subagents read those `SKILL.md` files first, or report unavailable paths. Fallback semantics (`paths-injected`/`fallback-registry`/`fallback-path`/`none`) and the SDD-executor distinction: `orchestrator-skills.md`.
+The parent resolves skill paths once per session under `## Skills to load before work`; subagents read those `SKILL.md` files first, or report unavailable paths. Fallback semantics (`paths-injected`/`fallback-registry`/`fallback-path`/`none`): `orchestrator-skills.md`.
 
 ## Intent-Driven Skill Discovery
 

package/assets/support/strict-tdd-verify.md

@@ -1,269 +1,7 @@
-# Strict TDD Module — Verify Phase
+# Applicable Test-First Development — ODD Verification
 
-> **This module is loaded ONLY when Strict TDD Mode is enabled AND a test runner is available.**
-> If you are reading this, the orchestrator already verified both conditions. Follow every instruction.
+This legacy filename is retained for package compatibility. It does not represent a Strict TDD switch.
 
-## TDD Verification Philosophy
+Assess applicability for each changed behavior: is there a runnable deterministic test with a clear expected outcome? Test existence alone does not establish applicability. For applicable behavior, inspect the reported observed RED (the intended failure before implementation), observed GREEN (focused passing execution after implementation), relevant alternate cases, and post-refactor checks. Do not infer RED from a test file existing or GREEN from a claim without execution. Report missing or contradictory evidence honestly; do not manufacture a lifecycle from the final diff.
 
-When Strict TDD Mode is active, verification goes beyond "does the code work?" to "was the code built correctly?" — meaning: was TDD actually followed? The apply phase reports TDD evidence; your job is to validate that evidence against reality.
-
-## Step 5a: TDD Compliance Check (includes Assertion Quality Audit)
-
-Read the `apply-progress` artifact and verify that TDD was actually followed:
-
-```
-Read apply-progress artifact:
-├── Find the "TDD Cycle Evidence" table
-├── FOR EACH task row:
-│   ├── RED column:
-│   │   ├── Must say "✅ Written"
-│   │   ├── Verify: test file EXISTS in the codebase
-│   │   └── Flag: CRITICAL if test file does not exist
-│   │
-│   ├── GREEN column:
-│   │   ├── Must say "✅ Passed"
-│   │   ├── Cross-reference with Step 5b test execution results:
-│   │   │   └── The test file listed must PASS when you run it
-│   │   └── Flag: CRITICAL if test fails now (was it really green?)
-│   │
-│   ├── TRIANGULATE column:
-│   │   ├── If "✅ N cases" → verify N test cases exist in the test file
-│   │   ├── If "➖ Single" → verify spec truly has only one scenario for this task
-│   │   └── Flag: WARNING if spec has multiple scenarios but only 1 test case
-│   │
-│   ├── SAFETY NET column:
-│   │   ├── If "✅ N/N" → existing tests were run before modification (good)
-│   │   ├── If "N/A (new)" → verify the file was actually NEW (not modified)
-│   │   └── Flag: WARNING if file was modified but safety net shows "N/A"
-│   │
-│   └── REFACTOR column:
-│       ├── Not strictly verifiable (subjective quality)
-│       └── Skip verification, trust the report
-│
-├── If NO "TDD Cycle Evidence" table found:
-│   └── Flag: CRITICAL — apply phase did not report TDD evidence
-│       (Strict TDD was enabled but apply did not follow the protocol)
-│
-└── Summary: "{N}/{total} tasks have complete TDD evidence"
-```
-
-## Step 5 Expanded: Test Layer Validation
-
-Classify ALL test files related to this change by their testing layer:
-
-```
-Scan test files created/modified by this change:
-├── Classify each test file:
-│   ├── Unit test: tests a single function/class in isolation
-│   │   └── Indicators: no render(), no page., no HTTP calls, mocked dependencies
-│   ├── Integration test: tests component interaction or user behavior
-│   │   └── Indicators: render(), screen., userEvent., testing-library imports
-│   ├── E2E test: tests full system through real browser/HTTP
-│   │   └── Indicators: page.goto(), playwright/cypress imports, browser context
-│   └── Unknown: cannot classify → report as-is
-│
-├── Report distribution:
-│   ├── Unit: {N} tests across {N} files
-│   ├── Integration: {N} tests across {N} files
-│   ├── E2E: {N} tests across {N} files
-│   └── Total: {N} tests
-│
-├── Cross-reference with capabilities:
-│   ├── If integration tests exist but tools not in capabilities → how?
-│   ├── If E2E tests exist but tools not in capabilities → how?
-│   └── Flag: WARNING if tests use tools not detected in capabilities
-│
-└── For each spec scenario: note which layer covers it
-    └── Flag: SUGGESTION if critical business logic only has unit tests
-        (only if integration/E2E tools are available)
-```
-
-## Step 5d Expanded: Changed File Coverage
-
-When coverage tool is available, report coverage for CHANGED files specifically:
-
-```
-IF coverage tool available (from cached capabilities):
-├── Run: {test_command} --coverage (or equivalent)
-├── Parse the coverage report
-├── Filter to ONLY files created or modified in this change
-│   (get file list from apply-progress "Files Changed" table)
-├── Report per-file:
-│   ├── File path
-│   ├── Line coverage %
-│   ├── Branch coverage % (if available)
-│   ├── Uncovered line ranges (specific lines, not just %)
-│   └── Flag per file:
-│       ├── ≥ 95% → ✅ Excellent
-│       ├── ≥ 80% → ⚠️ Acceptable
-│       └── < 80% → ⚠️ Low (list uncovered lines)
-├── Report aggregate:
-│   ├── Average coverage of changed files
-│   ├── Total uncovered lines in changed files
-│   └── Compare to threshold if configured
-└── Flag: WARNING if any changed file < 80% coverage
-
-IF coverage tool NOT available:
-└── Report: "Coverage analysis skipped — no coverage tool detected"
-    (NOT a failure — just not available)
-```
-
-## Step 5e: Quality Metrics (if tools available)
-
-Run quality checks ONLY on changed files, ONLY if tools are available:
-
-```
-Read quality tools from cached capabilities:
-
-IF linter available:
-├── Run linter on changed files only
-├── Report: errors and warnings
-└── Flag: WARNING for errors, SUGGESTION for warnings
-
-IF type checker available:
-├── Run type checker (usually whole-project, not per-file)
-├── Filter output to changed files
-├── Report: type errors in changed files
-└── Flag: WARNING for type errors
-
-IF neither available:
-└── Report: "Quality metrics skipped — no tools detected"
-```
-
-## Report Template Extension
-
-When Strict TDD Mode is active, your verification report MUST include these additional sections:
-
-```markdown
-### TDD Compliance
-| Check | Result | Details |
-|-------|--------|---------|
-| TDD Evidence reported | ✅ / ❌ | {Found in apply-progress / Missing} |
-| All tasks have tests | ✅ / ❌ | {N}/{total} tasks have test files |
-| RED confirmed (tests exist) | ✅ / ⚠️ | {N}/{total} test files verified |
-| GREEN confirmed (tests pass) | ✅ / ❌ | {N}/{total} tests pass on execution |
-| Triangulation adequate | ✅ / ⚠️ / ➖ | {N} tasks triangulated / {N} single-case |
-| Safety Net for modified files | ✅ / ⚠️ | {N}/{total} modified files had safety net |
-
-**TDD Compliance**: {N}/{total} checks passed
-
----
-
-### Test Layer Distribution
-| Layer | Tests | Files | Tools |
-|-------|-------|-------|-------|
-| Unit | {N} | {N} | {tool} |
-| Integration | {N} | {N} | {tool or "not installed"} |
-| E2E | {N} | {N} | {tool or "not installed"} |
-| **Total** | **{N}** | **{N}** | |
-
----
-
-### Changed File Coverage
-| File | Line % | Branch % | Uncovered Lines | Rating |
-|------|--------|----------|-----------------|--------|
-| `path/to/file.ext` | 95% | 90% | — | ✅ Excellent |
-| `path/to/other.ext` | 82% | 75% | L45-48, L62 | ⚠️ Acceptable |
-| `path/to/new.ext` | 100% | 100% | — | ✅ Excellent |
-
-**Average changed file coverage**: {N}%
-{or "Coverage analysis skipped — no coverage tool detected"}
-
----
-
-### Assertion Quality
-| File | Line | Assertion | Issue | Severity |
-|------|------|-----------|-------|----------|
-| ... | ... | ... | ... | ... |
-
-**Assertion quality**: {N} CRITICAL, {N} WARNING
-{or "✅ All assertions verify real behavior"}
-
----
-
-### Quality Metrics
-**Linter**: ✅ No errors / ⚠️ {N} warnings / ❌ {N} errors / ➖ Not available
-**Type Checker**: ✅ No errors / ❌ {N} errors / ➖ Not available
-```
-
-## Step 5f: Assertion Quality Audit (MANDATORY)
-
-Scan ALL test files created or modified by this change and check for trivial/meaningless assertions:
-
-```
-FOR EACH test file related to the change:
-├── Read the file content
-├── Scan for BANNED assertion patterns:
-│   ├── Tautologies: expect(true).toBe(true), assert True, expect(1).toBe(1)
-│   ├── Orphan empty checks: expect(result).toEqual([]) or assert len(result) == 0
-│   │   └── UNLESS there is a companion test with same setup that asserts NON-EMPTY
-│   ├── Type-only assertions used alone: toBeDefined(), not.toBeNull(), typeof checks
-│   │   └── These are OK if COMBINED with value assertions in the same test
-│   ├── Assertions that never call production code (no function call, no render, no request)
-│   ├── Ghost loops: assertions inside for/forEach over queryAll/filter results
-│   │   └── Check if the collection could be empty — if so, the assertions NEVER RUN
-│   │       Flag: CRITICAL — a loop over an empty array is a test that ALWAYS passes
-│   ├── Incomplete TDD cycle: test passes because preconditions prevent code from running
-│   │   └── e.g., testing behavior of a component that is never rendered due to state
-│   │       Flag: CRITICAL — test must set up conditions where the code path IS exercised
-│   ├── Smoke-test-only: render() + toBeInTheDocument() without behavioral assertions
-│   │   └── "Renders without crash" is NOT a valid test — it must assert WHAT was rendered
-│   │       Flag: WARNING — smoke tests do not count toward TDD coverage
-│   ├── Implementation detail coupling: assertions on CSS classes, internal state, mock call counts
-│   │   └── expect(el.className).toContain("text-xs") or expect(mock.calls.length).toBe(3)
-│   │       Flag: WARNING — tests must assert behavior, not implementation
-│   └── Mock/assertion ratio: count vi.mock() calls vs expect() calls per test file
-│       └── If mocks > 2× assertions → Flag: WARNING — "Mock-heavy test ({N} mocks, {N} assertions)"
-│           Recommend: extract logic to pure function or move to higher test layer
-│
-├── For each violation found:
-│   ├── Record: file, line number, the assertion, why it's trivial
-│   └── Classify:
-│       ├── CRITICAL: tautology (expect(true).toBe(true)) — test proves NOTHING
-│       ├── CRITICAL: assertion without production code call — test exercises nothing
-│       ├── CRITICAL: ghost loop — assertions inside loop over possibly-empty collection
-│       ├── WARNING: empty collection without companion non-empty test
-│       ├── WARNING: type-only assertion without value assertion
-│       ├── WARNING: smoke-test-only — render + toBeInTheDocument without behavioral check
-│       ├── WARNING: CSS class / implementation detail assertion
-│       └── WARNING: mock-heavy test (mocks > 2× assertions) — wrong test layer
-│
-├── Check triangulation quality:
-│   ├── Count distinct test cases per behavior
-│   ├── If only 1 test case exists for a behavior with multiple spec scenarios:
-│   │   └── Flag: WARNING — "Insufficient triangulation for {behavior}"
-│   ├── If all test cases assert the SAME type of value (e.g., all check empty arrays):
-│   │   └── Flag: WARNING — "No variance in test expectations — all assert empty/trivial"
-│   └── A well-triangulated behavior has tests asserting DIFFERENT expected values
-│
-└── Summary: "{N} trivial assertions found across {N} files"
-```
-
-### Assertion Quality Report Table
-
-Include this table in the verification report when any issues are found:
-
-```markdown
-### Assertion Quality
-| File | Line | Assertion | Issue | Severity |
-|------|------|-----------|-------|----------|
-| `path/test.ts` | 15 | `expect(true).toBe(true)` | Tautology — proves nothing | CRITICAL |
-| `path/test.ts` | 23 | `expect(result).toEqual([])` | Empty without companion non-empty test | WARNING |
-| `path/test.ts` | 31 | `expect(result).toBeDefined()` | Type-only — no value asserted | WARNING |
-
-**Assertion quality**: {N} CRITICAL, {N} WARNING
-```
-
-If zero issues found, report: "**Assertion quality**: ✅ All assertions verify real behavior"
-
-## Rules (Strict TDD Verify specific)
-
-- ALWAYS check the TDD Cycle Evidence table from apply-progress — it's the primary artifact
-- ALWAYS cross-reference reported test files against actual execution — don't trust the report blindly
-- ALWAYS run the Assertion Quality Audit (Step 5f) — trivial tests are WORSE than missing tests
-- If apply-progress has no TDD evidence table, flag as CRITICAL — the protocol was not followed
-- If tautology assertions are found (expect(true).toBe(true)), flag as CRITICAL — these MUST be rewritten
-- Coverage and quality metrics are informational, NOT blocking — only flag as WARNING, never CRITICAL
-- Test layer distribution is informational — SUGGESTION level only
-- DO NOT fix issues — only report. The orchestrator decides.
-- If coverage/quality tools are not available, say so cleanly and move on — never flag missing tools as failures
+For passive documentation, non-testable changes, an unavailable runner, or no meaningful RED, assess the stated exception and the proportionate ordinary functional or structural verification. Never demand a chat/TUI activation choice, and never skip all checks merely because test-first is inapplicable. Execute only exact commands authorized by the parent; report actual results, limitations and remaining uncertainty without editing code or overriding parent-owned RDD review.