codex-orchestrator 2.0.3 → 2.0.5

package/internal-workflow/skills/spec-implementer/SKILL.md

@@ -5,193 +5,122 @@ description: "Executes approved specs continuously with honest checklist updates
 
 # Spec Implementer
 
-Execute an approved implementation spec. Your job is to carry out the chosen spec, keep its checklist honest, and stop at the right boundaries. Do not redesign the work unless the spec or repo reality proves a blocker.
-
-This skill is standalone by default: it executes only an approved spec that the
-user has chosen to run. `$tickets-orchestrator` may invoke it inline at root for
-an accepted compact or standard ticket spec inside user-authorized orchestration;
-that does not authorize unrelated specs or broader delivery scope.
-
-When a spec contains a Contract Test Ledger, treat it as part of the execution contract. The shared reference is `../../docs/agents/contract-test-ledger.md`.
-
-All implementation review checkpoints and final review gates use
-`../../docs/agents/implementation-review-loop.md` as their caller-facing owner.
-This skill must not create a per-slice review flow or retry loop.
-
-## Spec Modes
-
-- **Compact specs:** execute directly as one continuous implementation flow with lightweight phase checkpoints. `compact` describes document density, not implementation size or risk. Use review/signoff gates only when the spec, repo policy, or change risk requires them.
-- **Full specs:** execute the same phase flow, but treat `Risk Controls`, task-specific `Halt Conditions`, and validation proof as hard constraints. Do not invent extra process just because the spec is full.
-- **Multi-agent specs:** follow the integrator contract exactly. If write scopes are not perfectly disjoint, stop before spawning workers.
-
-## Core Rules
-
-1. Follow the spec literally. Do not broaden scope, add cleanup, or re-plan unless a blocker is proven.
-2. Treat the spec checklist as the execution ledger.
-3. Update checklist items during implementation. For compact specs, update at natural checkpoints and phase exits. For full specs, or when the spec says so, update completed leaf items immediately.
-4. Do not save all checklist updates only for the final response.
-5. Re-read the current phase before moving on and reconcile already-completed unchecked items.
-6. If a step is blocked, leave it unchecked and record one short `Blocked:` note with the concrete reason.
-7. Treat Preconditions as hard blockers. Do not start a phase until they are satisfied, explicitly not applicable, or blocked.
-8. If the saved spec contains unresolved template text, placeholders, alternative commands, or pseudo-paths, stop and escalate.
-9. Honor Protected Paths and Rejected Approaches exactly as written.
-10. Apply the `$codebase-design` lens only when ownership or a public Module Interface or Seam changes. For any new private helper, run the deletion test and keep it only if it improves locality or leverage, without activating architecture workflow.
-11. Do not add pass-through modules, one-adapter seams, or test-only helpers unless the spec explicitly approves them.
-12. Add comments/docblocks only where the spec explicitly requires them.
-
-## Before Editing
-
-- Read the complete frontmatter before announcing execution strategy. Confirm the spec path, status, `spec_mode`, `implementation_size`, `review_profile`, and `expected_repositories`; infer a missing classification from evidence without rewriting the approved design.
-- Identify whether it is compact, full, or multi-agent. Do not call a compact spec full or equate compact with small.
-- Check required services, env vars, fixtures, repo state, and prerequisite issues.
-- Confirm the first phase targets exist as described.
-- Confirm validation commands are executable or explicitly not applicable.
-- If the spec has a Contract Test Ledger, confirm each reached invariant has a first test/proof or a concrete blocked reason before implementation.
-- If the spec has `Review Checkpoints` or `Review Focus`, keep only checkpoints whose target becomes stable before later slices. If later work will touch the same files, owners, or contracts, fold that coverage into the final parallel review instead of reviewing an unstable slice.
-- Resolve the implementation review profile and plan mandatory final coverage before launching any reviewer. Do not manufacture an early checkpoint merely because the profile is high.
-- Do not write `## Implementation Review State` during ordinary preflight or implementation. Immediately before the first actual reviewer launch, persist the short Review Plan and pending launch required by the Module; then update it after every usable reviewer result, repair batch, closure, waiver, or terminal outcome.
-- If the spec has `Final Handoff Requirements`, treat them as the final response contract. For medium/high-risk specs without explicit requirements, prepare the standard Final Risk Handoff anyway.
-- For full specs, read `Risk Controls` before editing and translate each applicable control into a concrete execution constraint.
-- Use `Write Scope Summary` when present as an audit aid. If it is absent, rely on phase targets unless the write set is ambiguous.
-- Stop if exact execution would require guessing.
+Execute one approved implementation spec continuously. Keep its checklist
+truthful and stop only at a real authority, evidence, safety, or explicit pause
+boundary. Do not redesign approved scope.
+
+Read before editing:
+
+- the complete approved spec and applicable repository instructions;
+- `references/review-loop.md` for approved-spec review ownership;
+- `../../docs/agents/contract-test-ledger.md` only when the spec contains
+  material contract invariants.
+
+## Modes
+
+Compact and full specs use the same direct phase flow. `compact` describes
+document density, not implementation size or risk. Full mode adds only the
+concrete `Risk Controls`, stop conditions, validation, or coordination contract
+already present in the approved spec; it does not add review or reporting
+ceremony by itself.
+
+Use multiple agents only when the spec defines perfectly disjoint write scopes
+and one integrator. Otherwise execute single-agent.
+
+## Preflight
+
+1. Confirm `status`, `spec_mode`, `implementation_size`, `review_profile`,
+   repository count, authority, scope, and exclusions.
+2. Confirm first-phase targets, required services/env/data/fixtures, commands,
+   observable proof, protected paths, and rejected approaches.
+3. Stop if execution needs invented paths, symbols, contracts, commands, or
+   product decisions; if reality differs only in a bounded technical detail,
+   resolve it from repository evidence and record the adjustment.
+4. Keep an intermediate review checkpoint only when the spec explicitly names
+   a stable high-risk slice that later work will not invalidate. Move every
+   ordinary or unstable checkpoint to final review.
+5. Do not create `## Implementation Review State` yet.
+
+## Implementation
+
+For each phase:
+
+1. Re-read its scope and preconditions.
+2. Implement narrow vertical behavior slices through `$tdd` when applicable.
+3. Update reached checklist and Contract Test Ledger items at natural
+   checkpoints; never save all updates for the end.
+4. Run the phase's targeted exit proof.
+5. Record a short `Blocked:` note for any item that cannot complete.
+6. Continue immediately when the exit proof passes and no stop condition
+   applies.
+
+Do not add cleanup, comments, helpers, abstractions, retries, flags, fallbacks,
+or compatibility paths outside the spec. A small implementation adjustment is
+allowed only when it preserves approved behavior and is supported by current
+repository evidence.
 
 ## Git Checkpoints
 
-Default to `none` and begin implementation without checkpoint ceremony. Mention the strategy once only when it materially affects delivery. Invoking `$spec-implementer` does not by itself authorize commits.
+Default to no commits. `$spec-implementer` does not authorize Git writes.
 
-Choose `per-slice` only when commits are explicitly authorized by the user or approved spec, slice diffs are truly isolated, and checkpoints materially improve recovery or handoff safety. Valid reasons are:
+Use per-slice commits only when explicitly authorized and they materially help
+a disjoint multi-agent handoff, planned cross-session pause, or approved
+rollback boundary. Require a passed slice proof, stage only owned paths, follow
+`$commit`, and never push without separate authority. File/slice count and risk
+profile alone do not justify checkpoints.
 
-- a multi-agent merge/handoff boundary
-- an explicitly planned pause or continuation in another session
-- a destructive or rollback boundary whose isolated commit is part of the approved safety plan
+## Review And Validation
 
-Use `none` for ordinary single-agent execution, including compact/high specs, overlapping slices, and continuous work in one session. Slice count, file count, or review profile alone never justifies commits.
+Run targeted behavior tests and the smallest affected integration checks first.
+Use a full repository suite only when the spec or repository policy requires
+it, broad contract fan-out cannot be isolated, or the task is genuinely high.
 
-At each checkpoint:
+Run final `$code-review` only when the spec, repository policy, or
+`../../docs/agents/review-gates.md` applies. Ordinary medium work gets one
+`reviewer_standard` Full review on the settled diff. High gets two disjoint
+`reviewer_deep` lenses. Cleanup stays inside spec/standards review.
 
-- require a passed exit gate and applicable slice review, then reconcile and include tracked checklist/ledger updates
-- inspect the full diff, stage only slice-owned paths or hunks, follow `$commit` safety rules, and verify the hash
-- treat the applicable slice review as the pre-commit gate; final review still runs at the end
+Immediately before the first reviewer launch, create only the minimal
+`## Implementation Review State` required by `references/review-loop.md`.
+Reconcile a recorded live session before replacement after interruption.
 
-If isolation later becomes unsafe, skip and record the reason. Never commit RED state, failed validation, unresolved findings, discovery-only work, or a partial slice. Never amend a checkpoint commit; put later fixes in a new commit. Never push unless explicitly requested. Report the strategy and slice-to-commit mapping, or the reason no checkpoints were created.
+Repair compatible findings once and rerun affected validation. Coordinator
+verification closes ordinary medium/low behavior-preserving repairs. Use
+Closure only for critical/high, protected trust/data/concurrency/shared-contract
+impact, or invalidated mandatory coverage. Do not restart broad Full review
+unless the repair actually invalidated its coverage.
 
-## Phase Workflow
-
-For every phase:
-
-- Confirm phase dependencies and preconditions.
-- Execute only the steps assigned to that phase.
-- Update the spec checklist according to its mode.
-- Update any reached Contract Test Ledger rows as planned -> red -> green, or blocked with the missing seam/proof.
-- Run the phase exit gate.
-- If a `Review Checkpoint` applies after this phase, execute it through the
-  Module only when the target is settled and later slices do not invalidate its
-  files/contracts. Otherwise record that its lenses moved to final coverage and
-  continue without launching an unstable review.
-- Reconcile unchecked items for the current phase.
-- Re-check applicable `Risk Controls` before leaving the phase.
-- Check whether the phase introduced shallow modules, duplicated source-of-truth logic, or tests coupled to implementation details; fix only when inside approved scope, otherwise report it.
-- Run the repo architecture check when available, applicable, and required by the spec or repo policy.
-- If `per-slice` applies and this phase completes an implementation slice, create and verify its checkpoint commit before continuing.
-- Continue to the next phase only when the exit gate passes and no stop condition applies.
-- If the phase exit gate says `User Pause: Required`, stop and wait for the user's explicit command.
-
-## Review And Signoff
-
-Do not run a dedicated review subagent after every phase by default. Do run one at explicit `Review Checkpoints`; these are risk gates, not optional status updates.
-
-Before every reviewer launch, apply the Module's launch and reconciliation
-rules to the persisted `## Implementation Review State`; do not restate or
-replace those rules in this skill.
-
-Require final `$code-review` coverage when any of these apply:
-
-- the spec explicitly requires it
-- the repo policy requires it
-- the change is medium or large
-- the change touches multiple runtime files or shared behavior
-- the change touches API contracts, DTOs, schemas, persistence, auth, permissions, payments, caching, concurrency, background jobs, or shared state
-
-When `$code-review` is required for a checkpoint or final gate, keep orchestration at root so `$code-review` can launch the profile-selected reviewer topology. Invoking `$spec-implementer` authorizes that review; if the required role is unavailable, report the gate as unavailable/blocked instead of self-certifying it.
+## Stop Conditions
 
-Use one final `$code-review` wave after the implementation and validation settle.
-For `simple` and `medium`, one reviewer covers both lenses. For `high`, launch
-the correctness and spec/standards reviewers in parallel; the spec/standards
-lens includes bounded cleanup. Run separate `$cleanup-review` only when the
-user, approved source, or repo policy names a concrete evidenced reason that
-cannot fit that lens; size or risk labels alone are insufficient. Integrate safe
-fixes and rerun relevant validation before continuing.
-Before launching a fresh final reviewer, reconcile the settled revision against
-the Review Plan. Stop when an approved Full or Closure already covers every
-mandatory final lens; otherwise run `$code-review` only for the uncovered
-lenses. A `cleanup-only` result never substitutes for correctness or
-spec/standards coverage.
+Stop and report the exact blocker when:
 
-For compact low-risk specs, final validation plus checklist reconciliation is enough unless the spec says otherwise.
+- a precondition, source contract, required proof, or protected path differs
+  materially from the approved spec;
+- exact execution requires a new product, scope, ownership, or risky trade-off
+  decision;
+- required validation or reviewer is unavailable and no approved substitute
+  exists;
+- multi-agent scopes overlap or integration ownership is missing;
+- an explicit user pause or halt condition is reached.
 
-Treat review feedback as mandatory remediation when it is grounded in code or the spec. If review reveals ambiguity that cannot be resolved from the spec, code, or docs, pause and ask the user.
+Do not stop merely because the work is broad, review took time, or a medium/low
+finding required one repair.
 
-Apply the Module's convergence and stop rules after every usable result and
-before every new launch.
+## Completion
 
-## Multi-Agent Execution
+Complete only when reached checklist items are reconciled, affected proof and
+required review pass, protected paths and rejected approaches remain intact,
+and every unfinished item has a concrete status.
 
-- Use multiple agents only when the spec has explicit disjoint write scopes.
-- Keep one integrator responsible for merge sequencing, handoff checks, final validation, and checklist reconciliation.
-- Respect exclusive write scopes, handoff artifacts, forbidden overlap, and merge order exactly as written.
-- Never let two agents edit the same file, generated artifact, schema, source-of-truth rule, or shared contract at the same time.
-- If the spec lacks a clear integrator contract, execute single-agent or stop and ask for clarification.
+For ordinary medium work report only:
 
-## Stop Conditions
+- behavior/contract implemented;
+- review result and repaired/open findings;
+- affected validation;
+- skipped checks and residual risk;
+- changed files and any authorized commits.
 
-Stop immediately and escalate if:
-
-- a required precondition cannot be satisfied exactly
-- a required file, symbol, command, dependency, or interface differs from the spec
-- the saved spec contains unresolved template text or alternative commands
-- completing the task would require touching a Protected Path or using a Rejected Approach
-- validation cannot prove the intended behavior with available repo context
-- implementation would require unapproved scope, abstraction, migration, compatibility logic, or cleanup
-- a `Risk Controls` rule would be violated or is contradicted by repo reality
-- review exposes a real ambiguity that would require guessing
-- a user pause is required and the user has not explicitly said to proceed
-
-## Completion Standard
-
-Do not mark the task complete until:
-
-- completed checklist items are checked off according to the spec mode
-- every remaining unchecked item is blocked, intentionally unfinished, not applicable, or halted by an explicit stop condition
-- every reached phase exit gate has passed
-- applicable `Risk Controls` remained satisfied
-- reached Contract Test Ledger rows are green or explicitly blocked with evidence
-- validation commands and behavior proof have run, or skipped checks have a concrete reason
-- required review/signoff gates have run and grounded findings are fixed or blocked with evidence
-- the whole-spec Review Plan, review-pass history, and stable defect lifecycle remain
-  consistent with `implementation-review-loop.md`
-- protected paths remained untouched and rejected approaches were not used
-- required comments/docblocks were added only where the spec demanded them
-- the chosen Git checkpoint strategy was followed, and every created or skipped checkpoint was recorded
-- final user handoff is allowed by the spec
-
-## Final Risk Handoff
-
-For medium/high-risk specs, the final chat response must include a compact `Final Risk Handoff` block. Do not make the user ask for this separately, and do not replace it with a generic summary.
-
-Include:
-
-- **Contract implemented:** the one behavior/contract delivered, in user-facing terms.
-- **High-risk checkpoints:** each required checkpoint, review result, fixed findings, and any stop/continue decision.
-- **Main invariants proved:** the key Contract Test Ledger rows or equivalent proofs and their status.
-- **Code-review findings:** high/critical findings fixed, remaining medium/low findings, or `none`.
-- **Fixes after review:** concrete fixes made because of cleanup/code review, or `none`.
-- **Validation:** exact commands/proofs that passed.
-- **Skipped checks:** skipped or blocked checks with concrete reasons.
-- **Residual risks:** accepted remaining risks or `none`.
-- **Checkpoint commits:** slice-to-commit mapping or `none`; do not narrate hypothetical checkpoints that were never authorized or attempted.
-- **Implementation reviews:** profile, total review passes, Full/Closure count,
-  mandatory coverage, verified defect IDs, accepted-risk IDs with authority and
-  reason, and open defect IDs.
-- **Files by role:** state owner, orchestration, side effects, UI/projection, tests, docs/copy, as applicable.
-
-Only create a separate report file when the spec requires it or the work is broad enough that chat would lose important evidence, such as multi-agent execution, multiple review passes with findings, skipped live checks, production validation, or handoff to another person. Otherwise keep the spec checklist/ledger as the durable artifact and the final response as the concise decision packet.
+For high, actual Closure, accepted risk, interrupted recovery, or multi-agent
+delivery, add the relevant invariants, reviewer coverage, defect IDs, session
+recovery, and handoff ownership. Do not create a separate report file unless
+the spec or the complexity of that exceptional handoff requires it.

package/internal-workflow/skills/spec-implementer/evals/evals.json

@@ -0,0 +1,30 @@
+{
+  "schema_version": 1,
+  "skill": "spec-implementer",
+  "cases": [
+    {
+      "id": "state-created-at-launch",
+      "prompt": "Execute an approved medium spec whose final review has not started yet.",
+      "expected": ["do not create review state during implementation", "persist minimal state immediately before reviewer launch"],
+      "forbidden": ["create per-slice review bookkeeping"]
+    },
+    {
+      "id": "medium-one-final-review",
+      "prompt": "Execute a normal medium spec with several vertical slices and no stable high-risk checkpoint.",
+      "expected": ["implement continuously", "run one final reviewer_standard on the settled diff"],
+      "forbidden": ["review after every slice", "run a full repository suite from file count"]
+    },
+    {
+      "id": "closure-stays-affected",
+      "prompt": "Final review finds one high defect in a shared schema and several ordinary low findings.",
+      "expected": ["repair once", "Closure verifies only the affected high-risk contract"],
+      "forbidden": ["restart all Full reviewers"]
+    },
+    {
+      "id": "resume-live-reviewer",
+      "prompt": "Resume after a reviewer poll timed out while the recorded session is still live.",
+      "expected": ["reconcile the existing session"],
+      "forbidden": ["mark it failed from timeout alone", "launch a duplicate reviewer"]
+    }
+  ]
+}

package/internal-workflow/skills/spec-implementer/references/review-loop.md

@@ -0,0 +1,100 @@
+# Approved Spec Implementation Review Loop
+
+This reference owns review orchestration for `$spec-implementer`. Read it only
+when executing an approved implementation spec. Shared Full/Closure and defect
+mechanics live in `../../../docs/agents/review-protocol.md`.
+
+Direct work and deterministic issue delivery use normal TDD and review gates;
+they must not create Implementation Review State.
+
+## Authority
+
+Only an approved implementation spec may own `## Implementation Review State`.
+PRDs, tickets, architecture notes, and chat summaries are not review-state
+owners. A substantive spec change returns through artifact review before
+implementation continues.
+
+Use the spec's `review_profile`; if absent, infer it from current evidence:
+
+- `simple`: narrow change with direct proof;
+- `medium`: default for ordinary implementation;
+- `high`: material failure consequence (financial side effect,
+  unauthorized/cross-owner behavior, durable corruption, or materially false
+  production result) plus an uncertainty amplifier (concurrency or event
+  ordering, delayed/background callbacks, retry/idempotency/recovery,
+  ownership transitions, or shared state across consumers).
+
+Implementation evidence may raise but never lower the approved profile.
+Recheck the settled diff immediately before the first reviewer launch and
+persist any required raise before launching reviewers.
+
+## Default Review Shape
+
+Implement continuously through vertical slices. Validate each affected behavior
+and run one final review on the settled diff when the gate applies.
+
+- `simple`: one `reviewer_fast` when review is required.
+- `medium`: one `reviewer_standard`, one bounded final Full, no intermediate
+  checkpoint by default.
+- `high`: two parallel `reviewer_deep` Full reviews with disjoint correctness
+  and spec/standards lenses.
+
+Add an intermediate checkpoint only when the approved spec explicitly names a
+stable high-risk slice whose review will remain valid after later work. Do not
+review unstable intermediate diffs or create per-slice review cycles.
+
+Cleanup stays inside the spec/standards lens. A concrete simplification risk may
+amplify that lens; size and profile labels alone do not create another gate.
+
+## Minimal Durable State
+
+Do not create review state during preflight or implementation. Immediately
+before the first actual reviewer launch, persist:
+
+- profile, authority path, settled target revision, and assigned lenses;
+- launch ID, reviewer/session handle, lineage, and `pending | completed | failed`;
+- returned findings, repair revision, affected validation, and Closure need.
+
+Write `pending` before launch and reconcile that session before replacing it
+after interruption or resume. A usable result becomes `completed`; an explicit
+failure becomes `failed`. A poll timeout while the session remains live is not
+a failure and does not authorize duplicate review.
+
+Record extended lineage/session history only for `high`, a real intermediate
+checkpoint, actual Closure, accepted risk, or interrupted recovery. Normal
+medium execution does not keep epochs, pass thresholds, activation counters, or
+per-slice handoff bookkeeping.
+
+## Findings And Closure
+
+Root aggregates findings, repairs compatible defects once, and reruns only
+affected validation. Coordinator verification closes ordinary medium/low
+behavior-preserving findings after confirming the repair matches the failure.
+
+Use shared-protocol Closure only for critical/high defects, protected
+trust/data/concurrency/shared API impact, or invalidated mandatory coverage.
+Closure stays with the affected reviewer lineage and repaired targets. Start a
+new Full only when the repair invalidated mandatory-lens coverage.
+
+Do not repeat review without a material change in target, evidence, repair, or
+source decision. Stop and surface the actual decision or evidence blocker when
+no progress is possible.
+
+## Completion
+
+Run gates in this order:
+
+1. affected behavior and integration validation;
+2. applicable final code review;
+3. Closure only when triggered;
+4. repository architecture/build/smoke gates required by policy or the spec;
+5. delivery actions explicitly authorized by the user or workflow.
+
+Return `Approved` only for the final settled revision when mandatory lenses and
+validation are complete and shared protocol state is clear. `Waived` records
+skipped coverage but is not approval. `Blocked` requires a concrete authority,
+evidence, reviewer, or convergence blocker—not elapsed time or review count.
+
+For normal medium work report only profile, review result, repaired/open
+findings, affected validation, skipped checks, and residual risk. Add extended
+session/defect accounting only when the exceptional state above exists.

package/internal-workflow/skills/tdd/SKILL.md

@@ -1,19 +1,33 @@
 ---
 name: tdd
-description: Test-driven development policy gate for implementation, bugfix, and new feature work unless the user explicitly opts out. Use before planning or editing code to shape the first behavior proof, and when the user mentions red-green-refactor, integration tests, or test-first development.
+description: Test-driven development for changes that alter observable behavior, have a natural public test seam, and can produce a meaningful failing test before implementation. Use after the global TDD Fit Gate passes, or when the user explicitly requests red-green-refactor, test-first development, or TDD.
 ---
 
 # Test-Driven Development
 
 Use short vertical RED -> GREEN cycles. Make each test prove observable behavior through the same public seam real callers use.
 
+## Fit
+
+Use this skill only when the change alters observable behavior, a natural public
+seam exists, and the pre-change test will fail for the intended behavioral
+reason. If an implicit activation fails this gate, stop the TDD route and use
+existing regression tests plus affected validation. For mixed tasks, apply TDD
+only to the behavioral slice.
+
+Behavior-preserving cleanup, dead-code deletion, documentation, copy,
+formatting, generated assets, package maintenance, simple config, builds, and
+read-only work do not need TDD. Absence and architecture guards added after a
+cleanup are validation, not RED proofs.
+
 ## Core Contract
 
 - Lock expected behavior from the request, specification, design, bug report, or existing product behavior before changing implementation.
 - Derive expected values from an independent source, never from the production algorithm.
 - Prove RED on the old behavior for the same observable reason the user reported or requested.
 - Add only enough implementation to make the current test pass; do not anticipate later tests.
-- Keep tests stable across behavior-preserving refactors and refactor only while GREEN.
+- Keep tests stable across behavior-preserving refactors.
+- After sufficient GREEN, stop by default. Refactor only to reduce concrete complexity introduced by the change.
 
 Read [tests.md](tests.md) when choosing or reviewing test shape. Read [mocking.md](mocking.md) before introducing test doubles.
 
@@ -23,8 +37,8 @@ Read [tests.md](tests.md) when choosing or reviewing test shape. Read [mocking.m
 2. List the prioritized observable behaviors, not implementation steps.
 3. Select the public seam where callers observe each behavior.
 4. Ask the user only when the seam changes the public contract, product intent is unclear, or behavior priorities materially conflict.
-5. For contract-risk changes, create or update the shared [Contract Test Ledger](../../docs/agents/contract-test-ledger.md) and map each invariant to its first failing test or observable proof.
-6. If no natural public seam exists, consult [interface-design.md](interface-design.md) instead of testing internals.
+5. Use the shared [Contract Test Ledger](../../docs/agents/contract-test-ledger.md) only when its material-delta and missed-failure gate passes.
+6. If no natural public seam exists, stop the TDD route. Consult [interface-design.md](interface-design.md) only when changing the interface is itself required by the task.
 
 For UI behavior, define proof at the rendered seam: visible content and order, interaction result, semantics, or screenshot when layout direction or scrolling matters.
 
@@ -43,7 +57,7 @@ Handle reviewer repairs inside the same activation only under [bug workflow rout
 
 ## After GREEN
 
-Refactor as a separate review-stage activity, never while RED. Use [refactoring.md](refactoring.md) for candidates and rerun affected tests after each step.
+GREEN is a valid stopping point. If the current change created concrete local complexity, use [refactoring.md](refactoring.md) and rerun affected tests.
 
 ## Cycle Checklist
 
@@ -55,5 +69,5 @@ Refactor as a separate review-stage activity, never while RED. Use [refactoring.
 [ ] GREEN uses only the code needed for the current behavior
 [ ] Final outcome and relevant competing condition are proved
 [ ] Contract Test Ledger is current when applicable
-[ ] Refactoring starts only after GREEN
+[ ] Any refactor is local and reduces current-change complexity
 ```

package/internal-workflow/skills/tdd/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Test-Driven Development"
-  short_description: "Apply behavior-first red-green development"
-  default_prompt: "Use $tdd to define the public test seam and implement this behavior through red-green cycles."
+  short_description: "Use TDD only when its behavioral fit gate passes"
+  default_prompt: "Use $tdd after confirming an observable behavior change, a public test seam, and a meaningful pre-change failure."
 policy:
   allow_implicit_invocation: true

package/internal-workflow/skills/tdd/evals/evals.json

@@ -0,0 +1,18 @@
+{
+  "schema_version": 1,
+  "skill": "tdd",
+  "cases": [
+    {
+      "id": "green-can-stop",
+      "prompt": "The requested behavior is green and the changed code is already clear and local.",
+      "expected": ["stop after green", "keep the current structure"],
+      "forbidden": ["add helpers, classes, or value objects", "refactor unrelated code"]
+    },
+    {
+      "id": "no-test-only-seam",
+      "prompt": "A behavior test can use the existing public seam, but dependency injection would make mocking easier.",
+      "expected": ["use the existing public seam"],
+      "forbidden": ["add production dependency injection only for tests", "wrap an SDK only for mockability"]
+    }
+  ]
+}

package/internal-workflow/skills/tdd/mocking.md

@@ -15,45 +15,6 @@ Don't mock:
 
 ## Designing for Mockability
 
-At system boundaries, design interfaces that are easy to mock:
-
-**1. Use dependency injection**
-
-Pass external dependencies in rather than creating them internally:
-
-```typescript
-// Easy to mock
-function processPayment(order, paymentClient) {
-  return paymentClient.charge(order.total);
-}
-
-// Hard to mock
-function processPayment(order) {
-  const client = new StripeClient(process.env.STRIPE_KEY);
-  return client.charge(order.total);
-}
-```
-
-**2. Prefer SDK-style interfaces over generic fetchers**
-
-Create specific functions for each external operation instead of one generic function with conditional logic:
-
-```typescript
-// GOOD: Each function is independently mockable
-const api = {
-  getUser: (id) => fetch(`/users/${id}`),
-  getOrders: (userId) => fetch(`/users/${userId}/orders`),
-  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
-};
-
-// BAD: Mocking requires conditional logic inside the mock
-const api = {
-  fetch: (endpoint, options) => fetch(endpoint, options),
-};
-```
-
-The SDK approach means:
-- Each mock returns one specific shape
-- No conditional logic in test setup
-- Easier to see which endpoints a test exercises
-- Type safety per endpoint
+Use the existing public or system-boundary seam first. Add dependency injection,
+an adapter, or an SDK wrapper only when production ownership or the requested
+contract requires it—not only to make a test easier to mock.

package/internal-workflow/skills/tdd/refactoring.md

@@ -1,10 +1,8 @@
-# Refactor Candidates
+# Refactoring After GREEN
 
-After TDD cycle, look for:
+Stop when GREEN code is clear and local. Refactor only when the current change
+introduced concrete duplication, confusion, or misplaced ownership and the edit
+reduces total complexity.
 
-- **Duplication** → Extract function/class
-- **Long methods** → Break into private helpers (keep tests on public interface)
-- **Shallow modules** → Combine or deepen
-- **Feature envy** → Move logic to where data lives
-- **Primitive obsession** → Introduce value objects
-- **Existing code** the new code reveals as problematic
+Keep it local. Do not add helpers, classes, value objects, deeper modules, or
+unrelated cleanup from pattern preference alone. Rerun affected tests.