@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/{implementation-planning → claude/implementation-planning}/SKILL.md

@@ -86,13 +86,10 @@ Consult `references/spec-tracing-guide.md` for the methodology and template.
 
 ```typescript
 exarchos_orchestrate({
-  action: "run_script",
-  script: "generate-traceability.sh",
-  args: [
-    "--design-file", "docs/designs/<feature>.md",
-    "--plan-file", "docs/plans/<date>-<feature>.md",
-    "--output", "docs/plans/<date>-<feature>-traceability.md"
-  ]
+  action: "generate_traceability",
+  designFile: "docs/designs/<feature>.md",
+  planFile: "docs/plans/<date>-<feature>.md",
+  output: "docs/plans/<date>-<feature>-traceability.md"
 })
 ```
 
@@ -179,13 +176,10 @@ exarchos_orchestrate({
 
 ```typescript
 exarchos_orchestrate({
-  action: "run_script",
-  script: "spec-coverage-check.sh",
-  args: [
-    "--plan-file", "docs/plans/<date>-<feature>.md",
-    "--repo-root", ".",
-    "--threshold", "80"
-  ]
+  action: "spec_coverage_check",
+  planFile: "docs/plans/<date>-<feature>.md",
+  repoRoot: ".",
+  threshold: 80
 })
 ```
 
@@ -224,10 +218,24 @@ action: "set", featureId: "<id>", phase: "<plan-review-phase>", updates: {
 }
 ```
 
+### Phase Transitions and Guards
+
+For the full transition table, consult `@skills/workflow-state/references/phase-transitions.md`.
+
+**Quick reference:** The `plan` → `plan-review` transition requires guard `plan-artifact-exists` — set `artifacts.plan` in the same `set` call as `phase`.
+
+### Schema Discovery
+
+Use `exarchos_workflow({ action: "describe", actions: ["set", "init"] })` for
+parameter schemas and `exarchos_workflow({ action: "describe", playbook: "feature" })`
+(or `"debug"`, `"refactor"`) for phase transitions, guards, and playbook guidance.
+Use `exarchos_orchestrate({ action: "describe", actions: ["check_plan_coverage", "check_provenance_chain"] })`
+for orchestrate action schemas.
+
 ## Completion Criteria
 
 - [ ] Design document read and understood
-- [ ] Spec traceability table created (`exarchos_orchestrate({ action: "run_script", script: "generate-traceability.sh" })`)
+- [ ] Spec traceability table created (`exarchos_orchestrate({ action: "generate_traceability" })`)
 - [ ] Scope declared (full or partial with rationale)
 - [ ] Tasks decomposed to 2-5 min granularity
 - [ ] Each task starts with failing test
@@ -236,19 +244,16 @@ action: "set", featureId: "<id>", phase: "<plan-review-phase>", updates: {
 - [ ] Plan verification passed — `exarchos_orchestrate({ action: "check_plan_coverage" })` returns passed: true
 - [ ] Provenance chain checked — `exarchos_orchestrate({ action: "check_provenance_chain" })` passed (blocking; gaps must be resolved before proceeding)
 - [ ] Task decomposition checked — `exarchos_orchestrate({ action: "check_task_decomposition" })` run (advisory; findings presented but non-blocking)
-- [ ] Spec coverage check passed — `exarchos_orchestrate({ action: "run_script", script: "spec-coverage-check.sh" })` passed: true
-- [ ] Coverage thresholds met — `exarchos_orchestrate({ action: "run_script", script: "check-coverage-thresholds.sh" })` passed: true:
+- [ ] Spec coverage check passed — `exarchos_orchestrate({ action: "spec_coverage_check" })` passed: true
+- [ ] Coverage thresholds met — `exarchos_orchestrate({ action: "check_coverage_thresholds" })` passed: true:
 
 ```typescript
 exarchos_orchestrate({
-  action: "run_script",
-  script: "check-coverage-thresholds.sh",
-  args: [
-    "--coverage-file", "coverage/coverage-summary.json",
-    "--line-threshold", "80",
-    "--branch-threshold", "70",
-    "--function-threshold", "100"
-  ]
+  action: "check_coverage_thresholds",
+  coverageFile: "coverage/coverage-summary.json",
+  lineThreshold: 80,
+  branchThreshold: 70,
+  functionThreshold: 100
 })
 ```
 
@@ -273,8 +278,8 @@ Phase transitions auto-emit `workflow.transition` events via `exarchos_workflow`
 | Issue | Cause | Resolution |
 |-------|-------|------------|
 | `check_plan_coverage` returns passed: false | Design sections not mapped to tasks | Add tasks for uncovered sections or add explicit deferral rationale |
-| `spec-coverage-check.sh` passed: false | Planned test files missing or failing | Create missing test stubs, verify file paths in plan match actual paths |
-| `generate-traceability.sh` passed: false | Design doc missing expected `##`/`###` headers | Verify design uses standard Markdown headings |
+| `spec_coverage_check` passed: false | Planned test files missing or failing | Create missing test stubs, verify file paths in plan match actual paths |
+| `generate_traceability` passed: false | Design doc missing expected `##`/`###` headers | Verify design uses standard Markdown headings |
 | Revision loop (3+ attempts) | Persistent gaps between design and plan | Set `planReview.revisionsExhausted = true`, suggest `/exarchos:ideate --redesign` |
 
 ## Performance Notes

package/skills/claude/implementation-planning/references/task-template.md

@@ -0,0 +1,63 @@
+# TDD Task Template
+
+## Task Format
+
+Each task follows this structure:
+
+```markdown
+### Task [N]: [Brief Description]
+
+**Phase:** [RED | GREEN | REFACTOR]
+**Test Layer:** [acceptance | integration | unit | property]
+**Acceptance Test Ref:** [Task ID of parent acceptance test, or omit]
+**Implements:** [DR-N identifiers]
+
+**TDD Steps:**
+1. [RED] Write test: `TestName_Scenario_ExpectedOutcome`
+   - File: `path/to/test.ts`
+   - Expected failure: [Specific failure reason]
+   - Run: `npm run test:run` - MUST FAIL
+
+2. [GREEN] Implement minimum code
+   - File: `path/to/implementation.ts`
+   - Changes: [Brief description]
+   - Run: `npm run test:run` - MUST PASS
+
+3. [REFACTOR] Clean up (optional)
+   - Apply: [SOLID principle or improvement]
+   - Run: `npm run test:run` - MUST STAY GREEN
+
+**Verification:**
+- [ ] Witnessed test fail for the right reason
+- [ ] Test passes after implementation
+- [ ] No extra code beyond test requirements
+
+**Dependencies:** [Task IDs this depends on, or "None"]
+**Parallelizable:** [Yes/No]
+```
+
+## Test Layer Selection
+
+Each task must declare its test layer. This determines the scope and style of testing:
+
+| Layer | Scope | When to use |
+|---|---|---|
+| `acceptance` | Feature-level behavior from user perspective | First task per feature or DR-N cluster. Uses real collaborators, no mocks. Remains RED until inner tasks complete. |
+| `integration` | Multiple components working together | **Default for most tasks.** Uses real collaborators, mocks only at infrastructure boundaries. |
+| `unit` | Single function/class in isolation | Complex algorithmic logic, pure functions, parsers. |
+| `property` | Invariants across input space | Transformations, state machines, serialization (auto-determined via testingStrategy). |
+
+**Acceptance Test Ref:** Inner tasks that implement toward an acceptance test should declare `**Acceptance Test Ref:** [Task ID]` linking to the parent acceptance test task. This creates the provenance chain: `DR-N → Acceptance Test → Inner Tests → Code`.
+
+## Characterization Testing
+
+When a task modifies existing code behavior, the planner should set `characterizationRequired: true` in the testingStrategy. The implementer captures current behavior as characterization tests before making changes, providing a safety net against unintended regressions.
+
+## Test Naming Convention
+
+Follow: `MethodName_Scenario_ExpectedOutcome`
+
+**Examples:**
+- `CreateUser_ValidInput_ReturnsUserId`
+- `CreateUser_EmptyEmail_ThrowsValidationError`
+- `GetUser_NonExistentId_ReturnsNull`

package/skills/{implementation-planning → claude/implementation-planning}/references/testing-strategy-guide.md

@@ -9,6 +9,8 @@ testingStrategy: {
   exampleTests: true;           // Always required (literal true)
   propertyTests: boolean;       // Property-based tests required?
   benchmarks: boolean;          // Performance benchmarks required?
+  testLayer: 'acceptance' | 'integration' | 'unit';  // Required (property is a separate axis via propertyTests)
+  characterizationRequired?: boolean;  // Pre-capture behavior before modifying existing code?
   properties?: string[];        // Guidance: which properties to verify
   performanceSLAs?: PerformanceSLA[]; // Guidance: performance targets
 }
@@ -79,9 +81,28 @@ When `benchmarks: true`, populate `performanceSLAs` with targets:
 }
 ```
 
+## Test Layer Selection (Testing Trophy Distribution)
+
+The planner MUST assign `testLayer` to each task. Follow the Testing Trophy distribution: **integration-heavy, unit-light**.
+
+| Layer | When to assign | Default? |
+|---|---|---|
+| `acceptance` | First task per feature or DR-N cluster with Given/When/Then criteria. Tests feature from user perspective with real collaborators. | No — explicitly assigned |
+| `integration` | Task tests multiple components working together. Uses real collaborators, mocks only at infrastructure boundaries. | **Yes — default layer** |
+| `unit` | Task involves isolated complex logic (parsers, algorithms, math). Pure functions with complex edge cases. | No — only for naturally isolated code |
+
+
+> **Note:** `propertyTests: true` can coexist with any `testLayer` value — it's an independent overlay, not a mutually exclusive layer.
+
+**Sociable test preference:** Default to using real collaborators (sociable tests). Mock only at infrastructure boundaries — external HTTP services, databases, filesystem. If a test requires >3 mocked dependencies, the task may be at the wrong test layer.
+
+## Characterization Testing
+
+Assign `characterizationRequired: true` when the task modifies existing code behavior (refactoring, fixing, enhancing). The implementer captures current behavior before making changes. Not applicable for new code creation.
+
 ## Auto-Determination
 
-The planner MUST auto-determine `propertyTests` and `benchmarks` for each task based on the category tables above. Do NOT leave these fields for the implementer to decide. Analyze each task's description and file paths to match against the categories. When uncertain, default to `false`.
+The planner MUST auto-determine `propertyTests`, `benchmarks`, and `testLayer` for each task based on the category tables above. Do NOT leave these fields for the implementer to decide. Analyze each task's description and file paths to match against the categories. When uncertain, default `testLayer` to `"integration"`, `propertyTests` to `false`, and `benchmarks` to `false`.
 
 ## Reference
 

package/skills/{implementation-planning → claude/implementation-planning}/references/worked-example.md

@@ -21,7 +21,7 @@ Agent reads design and extracts key sections:
 
 ## Step 1.5: Spec Tracing
 
-Agent runs `exarchos_orchestrate({ action: "run_script", script: "generate-traceability.sh" })` to pre-populate the traceability matrix, then fills in key requirements per section.
+Agent runs `exarchos_orchestrate({ action: "generate_traceability" })` to pre-populate the traceability matrix, then fills in key requirements per section.
 
 ## Step 2: Decompose into Tasks
 
@@ -67,7 +67,7 @@ exarchos_orchestrate({ action: "check_plan_coverage", ... })
 → passed: true — All design sections covered
 ```
 
-Agent runs `exarchos_orchestrate({ action: "run_script", script: "spec-coverage-check.sh" })` -- passed: true (no pre-existing tests expected at planning time).
+Agent runs `exarchos_orchestrate({ action: "spec_coverage_check", planFile: "docs/plans/2026-02-20-stream-compaction.md", repoRoot: "." })` -- passed: true (no pre-existing tests expected at planning time).
 
 ## Output