@hassangameryt/freeflow 0.2.0 → 0.4.0

package/skills/setup-freeflow/references/activation-contract.md

@@ -0,0 +1,120 @@
+# Activation Contract
+
+Freeflow uses layered checkout configuration. Shared repository activation, personal overrides, and runtime delivery are separate facts.
+
+## Repository Activation
+
+`.freeflow/config.json` is the required shared activation boundary. Minimal setup is:
+
+```json
+{
+  "defaultMode": "workflow"
+}
+```
+
+Supported defaults are `conversation`, `workflow`, and `strict-workflow`. Missing core keys use built-in defaults:
+
+- `enabled: true`
+- `interactionContract: true`
+- `skills.enabled: true`
+- `defaultMode: workflow`
+
+Repository config may also contain documented Output Router settings. Add optional settings only after an explicit request and preserve valid existing settings during idempotent setup.
+
+Do not add current mode, task state, phase, file inventories, plans, version metadata, activation paths, empty optional sections, host instruction copies, or generated workflow text.
+
+Missing or invalid repository config means repository activation is absent. A valid config with effective `enabled: false` remains configured but inactive.
+
+## Personal Overrides
+
+`.freeflow/local.json` is optional per-checkout state. It cannot activate Freeflow without a valid repository config.
+
+It may override these core values:
+
+```json
+{
+  "enabled": true,
+  "interactionContract": true,
+  "skills": {
+    "enabled": true
+  },
+  "defaultMode": "strict-workflow"
+}
+```
+
+Every field is optional. Omission inherits the repository value, then the built-in default. Local core precedence is property-level, not whole-file replacement.
+
+The local file may also contain documented local-only `processing` config. It must not contain repository-owned Output Router config.
+
+Keep local config untracked and ignored. In a Git checkout, prefer `.git/info/exclude` or an existing ignore rule over an unsolicited shared `.gitignore` edit. Refuse to write personal overrides to a tracked local file.
+
+A missing local file means full inheritance. An invalid existing local file blocks effective Freeflow and must not silently fall back to repository settings. Repair or removal requires authorization.
+
+## Effective Core State
+
+Resolve core values in this order:
+
+```text
+host session override -> personal override -> repository value -> built-in default
+```
+
+Host session overrides, where supported, may temporarily change Freeflow master enablement, Interaction Contract, Skills, and mode. They are host session state, not config, and cannot bypass missing or invalid repository activation.
+
+Effective Freeflow requires:
+
+1. valid repository config;
+2. missing or valid local config;
+3. session-resolved `enabled: true`.
+
+The Interaction Contract and Skills are independent resolved switches. When Skills are disabled, the configured mode remains visible as resolved state but no Freeflow mode is effective.
+
+Repository-owned Output Router settings remain independent capability config and take effect only while top-level Freeflow is enabled.
+
+## Mutation Authority By State
+
+Mode constrains agent-performed setup only when a mode is effective:
+
+- **Unconfigured:** missing or invalid repository config means no effective mode. An explicit setup request may create missing minimal activation; replacing invalid config requires specific authorization and source-conflict resolution.
+- **Configured but ineffective:** top-level disablement, dormant Skills, or invalid local config leaves no effective mode. An explicit request governs the selected enablement, configuration, or repair; any reported resolved mode remains dormant state only.
+- **Effective:** obey the reported mode. Conversation is read-only. Workflow and Strict Workflow allow only separately authorized setup or repair.
+
+A user operating native host settings changes host-managed state directly. That action is distinct from an agent editing `.freeflow/config.json` or `.freeflow/local.json`; verify the resulting source and effective state afterward.
+
+## Runtime Delivery
+
+Configuration does not prove runtime delivery.
+
+When effective, host adapters may deliver:
+
+- `runtime/interaction-contract.md` when the Interaction Contract switch is enabled;
+- one full `skills/workflow/SKILL.md` bootstrap when Skills are enabled;
+- compact active or dormant mode and capability state;
+- explicitly enabled capability context owned by that capability.
+
+The full Mode Contract and other workflow skills remain on demand. Adapters load context only; they do not enforce policy, block tools, grant permissions, or replace repo instructions.
+
+A setup report classifies automatic delivery as:
+
+- **confirmed:** trustworthy evidence shows the current host adapter ran;
+- **unavailable:** the adapter is absent, disabled, denied, untrusted, or unsupported;
+- **unconfirmed:** the host exposes no trustworthy execution evidence.
+
+For the setup turn itself, direct reads of newly effective context establish guidance only for that turn. Report those reads separately from lifecycle delivery.
+
+## Repo-Owned Instructions
+
+Do not create replacement Freeflow text in `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, or another repository instruction surface.
+
+Existing repo instructions remain live source truth within host precedence. Inspect conflicts and use Decision Gate rather than overwriting them to make Freeflow appear active.
+
+## Setup Invariants
+
+Setup is:
+
+- idempotent;
+- minimal by default;
+- explicit about shared versus personal state;
+- fail-closed for an invalid personal layer;
+- non-mutating toward repo-owned host instructions;
+- explicit about same-turn reads versus automatic runtime delivery;
+- free of generated replacement instructions and unrequested capability config.

package/skills/setup-freeflow/references/host-setup.md

@@ -0,0 +1,72 @@
+# Host Setup
+
+Host choice affects runtime delivery and settings controls, not the required repository activation shape.
+
+## Shared Checkout Shape
+
+Every host requires:
+
+```text
+.freeflow/config.json
+```
+
+Each checkout may also use:
+
+```text
+.freeflow/local.json
+```
+
+The repository file establishes shared activation. The local file supplies optional personal overrides and cannot activate Freeflow alone. Keep it untracked and ignored.
+
+Do not generate host-specific Freeflow instructions in `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, or another repo-owned instruction surface.
+
+## Pi
+
+The Pi extension reads both config layers before each agent turn. A valid repository config plus a missing or valid local layer is required before Freeflow can become effective.
+
+Pi provides these settings scopes:
+
+```text
+/freeflow settings          personal overrides
+/freeflow settings session  temporary session overrides
+/freeflow settings repo     shared repository settings
+/freeflow mode               direct temporary session mode
+```
+
+Session settings can temporarily inherit, enable, or disable Freeflow, Interaction Contract, and Skills, and can override mode. One reset action clears all four overrides. They persist in the active Pi session branch JSONL, never write `.freeflow/config.json` or `.freeflow/local.json`, and cannot bypass missing or invalid repository activation. Master or Skills changes reload Pi resources when supported.
+
+Personal settings use omission to inherit. The settings path refuses to overwrite invalid or tracked local config and establishes local Git exclusion when needed. These are user-operated host controls; they update state before the next model turn. Agent-performed file edits still follow Setup Freeflow's mutation-authority rules.
+
+When effective, Pi's `before_agent_start` path preserves the existing system prompt, adds current layered status and enabled model-facing context, and loads Workflow as one hidden persistent message while Skills are enabled. Interaction Contract delivery is independent from Skills. Mode Contract remains on demand.
+
+A config written during setup is visible to the available Pi adapter on the next agent turn. After first activation, tell the user to run `/reload` so Pi refreshes skills and resources fully. Without reload, the adapter can load core runtime context on the next agent turn, but resource discovery waits for reload. A session-mode command applies before the next model turn and does not require reload. For the remainder of the setup turn, read newly effective context directly after verification instead of claiming that another `before_agent_start` invocation already occurred.
+
+Confirm automatic delivery through current extension status or runtime evidence when available.
+
+## Codex And Claude
+
+The packaged lifecycle hook reads the same repository and local layers at supported session start, resume, clear, and compact boundaries.
+
+When top-level Freeflow is effective, the hook loads the Interaction Contract if enabled and the full Workflow bootstrap if Skills are enabled. It reports layered value sources and active or dormant mode state. Optional capabilities remain independently gated by valid repository config and top-level Freeflow.
+
+After first-time setup, tell the user to trigger the least disruptive supported host-native lifecycle boundary: resume, clear, compact, or a new session/startup as available. Name the exact control supported by the current host; do not prescribe Pi's `/reload`. Until that boundary runs, use same-turn direct reads without claiming automatic delivery.
+
+Classify delivery as:
+
+- **confirmed** when the current adapter invocation is evidenced;
+- **unavailable** when the plugin or hook is absent, disabled, denied, untrusted, or unsupported;
+- **unconfirmed** when the adapter may be installed and trusted but the host exposes no trustworthy evidence that it ran for the current lifecycle.
+
+Installed and trusted registration can establish availability for the next lifecycle action; it does not prove delivery already occurred.
+
+Do not compensate for unavailable or unconfirmed delivery by copying Freeflow text into repository instructions.
+
+## Optional Capabilities
+
+Do not ask a generic capability question during normal setup. If Output Router is explicitly requested, use `output-router-setup.md` and keep its config in the shared repository layer unless the documented setting is specifically local-only.
+
+Do not install repo-local hooks, CLI commands, lint rules, global standards, documentation inventories, or state files during setup.
+
+## Conflicts
+
+Repository instructions can conflict with Freeflow behavior even though they are not activation markers. Name the conflict and ask before changing setup or behavior when it would alter the next action.

package/skills/setup-freeflow/references/output-router-setup.md

@@ -0,0 +1,110 @@
+# Output Router Setup
+
+Use this only when repository setup or repair explicitly includes Output Router, observed routing, generated-path hints, native safety-net routing, vault, thresholds, script-transform adapters, or script-transform repository config.
+
+## Defaults
+
+- Minimal `/setup-freeflow` writes only repository `defaultMode`. `.freeflow/config.json` remains required for activation; a local override cannot activate Freeflow.
+- Output Router is repository-owned and disabled by default.
+- Missing optional sections mean built-in defaults, not setup failure.
+- Normal setup does not ask a generic capability question. If Output Router was not explicitly requested, do not write `outputRouter` config or install script adapters.
+- If the user explicitly opts into Output Router during setup, write `outputRouter.enabled: true` directly. Do not make them run another command afterward.
+- Observed routing is opt-in per producer/server. The user must choose persistence for each enabled entry before setup writes config.
+- Preserve unrelated valid repository and personal settings. Do not copy Output Router config into `.freeflow/local.json`; only documented local-only processing settings belong there.
+- Do not create a separate `setup-output-router` skill.
+
+If the user says only “set up the output router” with no requested knobs, explain that enabling Output Router is enough for the router tools/guidance, then ask which optional subfeatures, if any, they want persisted. Recommend no subfeature config unless they need observed routing, repo-specific hints, script transform setup, or native safety-net behavior.
+
+## Config Shape
+
+Write only keys the user explicitly requests. Do not dump defaults and do not create empty optional objects. Output-router-related config lives under `outputRouter`. Do not write removed `capture` or `providers` config.
+
+Supported shape:
+
+```json
+{
+  "defaultMode": "workflow",
+  "outputRouter": {
+    "enabled": true,
+    "postToolRouting": "safety-net",
+    "thresholds": {
+      "largeOutputBytes": 64000,
+      "largeOutputLines": 2000
+    },
+    "vault": {
+      "root": "~/.cache/freeflow-router/vault",
+      "retention": { "strategy": "ttl", "ttlDays": 7 }
+    },
+    "hints": {
+      "generatedPathGlobs": ["graphify-out/**"],
+      "noisyCommandPatterns": ["npm test"]
+    },
+    "observedRouting": {
+      "enabled": true,
+      "onRoutingFailure": "fail-open",
+      "mcp": {
+        "servers": {
+          "github": { "enabled": true, "persistence": "exact" },
+          "gmail": { "enabled": true, "persistence": "metadata-only" }
+        }
+      },
+      "web": { "enabled": true, "persistence": "exact" },
+      "fetch": { "enabled": true, "persistence": "exact" },
+      "codeSearch": { "enabled": true, "persistence": "exact" }
+    },
+    "scriptTransform": {
+      "enabled": true,
+      "sandbox": "auto",
+      "languages": ["javascript", "python", "jq"],
+      "network": "off",
+      "limits": {
+        "timeoutMs": 5000,
+        "maxInputBytes": 1048576,
+        "maxOutputBytes": 65536
+      },
+      "rawScriptPersistence": "disabled"
+    }
+  }
+}
+```
+
+Rules:
+
+- Top-level `enabled` and `skills.enabled` default to true after setup; write them only when the user explicitly wants to disable Freeflow or the skills layer.
+- `outputRouter.enabled` defaults to `false`; write `true` only when the user chooses Output Router.
+- `postToolRouting` defaults to `off`. Do not write `off`; use `safety-net` only when explicitly requested. Treat `strict` as reserved; ask before writing it.
+- `thresholds.largeOutputBytes`, `thresholds.largeOutputLines`, and `vault.retention.ttlDays` must be positive integers.
+- `vault.root` must be a non-empty string. Repo-local storage requires explicit user choice.
+- `hints.generatedPathGlobs` are broad-scan generated-path hints. Explicit file or directory retrieval must remain available.
+- `hints.noisyCommandPatterns` is parsed as hint config. Do not add it unless the user explicitly asks for command-pattern hints.
+- `observedRouting.enabled` defaults to `false`; write it only when the user chooses observed routing.
+- `observedRouting.onRoutingFailure` currently supports `fail-open`; omit it unless a caller needs an explicit non-default once supported.
+- `observedRouting.mcp.servers` must contain explicit server entries only. Setup may discover configured servers for selection, but must not persist a volatile inventory of every installed tool.
+- `observedRouting.web`, `observedRouting.fetch`, and `observedRouting.codeSearch` are Pi observed-routing producers. Enable only the producers the user chose.
+- Every enabled observed-routing entry needs a user-chosen persistence mode: `exact`, `metadata-only`, or `none`.
+- Recommend `exact` for public-ish evidence producers such as GitHub, web, fetch, and code search. Recommend `metadata-only` for sensitive or unknown producers such as Gmail, Slack, private customer systems, or likely-secret outputs.
+- Do not offer or write `redacted`; it is reserved for future work and currently falls back to `metadata-only` with a warning if hand-edited.
+- Pi public `freeflow_capture` and the separate `providers` setup surface have been removed. Do not write removed `capture` or `providers` config.
+- `scriptTransform.enabled` defaults to `false`; write `true` only after an explicit script-execution opt-in.
+- If the user opts into script transform setup and adapters are missing or unavailable, recommend installing global adapters. On consent, resolve `../../router/dist/setup/script-transform-adapters.js` relative to `skills/setup-freeflow/SKILL.md` and run `node <plugin-root>/router/dist/setup/script-transform-adapters.js install --config .freeflow/config.json`.
+- The installer uses `~/.cache/freeflow-script-adapters` by default, or `FREEFLOW_SCRIPT_TRANSFORM_ADAPTERS_HOME` when set. It installs `quickjs-wasi@3.0.1`, `jq-wasm@1.2.0-jq-1.8.2`, `@bsull/eryx@0.5.0`, and `node@24` for the Python JSPI child runner, writes `freeflow-adapter-env.sh`, probes sandbox proofs, and updates `outputRouter.scriptTransform.languages` with only proof-passing languages.
+- Freeflow auto-discovers adapters from that global cache. The explicit roots `FREEFLOW_QUICKJS_WASI_ROOT`, `FREEFLOW_JQ_WASM_ROOT`, and `FREEFLOW_ERYX_ROOT` remain overrides for custom installs.
+- Python/Eryx is installed by setup and uses the setup-installed child Node process launched with `--experimental-wasm-jspi` when the host process lacks JSPI. It must not be marked available unless that child runner passes the required sandbox probes.
+- `scriptTransform.languages` supports `javascript`, `python`, and `jq`; enable only languages whose adapters passed sandbox proofs.
+- `scriptTransform.sandbox` currently supports `auto`, `network` supports only `off`, and `rawScriptPersistence` supports only `disabled`.
+- `scriptTransform.limits.timeoutMs`, `maxInputBytes`, and `maxOutputBytes` must be positive integers within product caps. Per-call script limits may only tighten configured values.
+
+## Verify
+
+After writing optional capability config, use `freeflow_status` or equivalent direct inspection to verify:
+
+- JSON parses.
+- `defaultMode` is valid.
+- A minimal shared setup with no optional settings contains only `defaultMode`.
+- Newly added `enabled`, `interactionContract`, `skills.enabled`, `outputRouter`, `outputRouter.observedRouting`, and `outputRouter.scriptTransform` keys were requested; preserved valid settings remain unchanged.
+- Invalid router, observed-routing, or script-transform values are not written.
+- Output Router, observed routing, native safety-net routing, and script transform are not enabled unless explicitly requested.
+- If script transform setup was accepted, global adapter install completed or a clear install/probe failure was reported, and enabled languages match proof-passing adapters.
+- No observed-routing entry uses `redacted`, and every enabled entry has explicit persistence.
+- `freeflow_status` shows effective defaults and migration recommendations without rewriting config.
+- No repo-local hooks, skill files, setup-output-router skill, docs inventories, or repo-local storage directories were created.

package/skills/simplify-code/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: simplify-code
+description: Use when simplifying working code without changing behavior, including removing duplication, indirection, dead abstractions, or confusing control flow.
+---
+
+# Simplify Code
+
+Reduce the concepts a reader must hold while preserving accepted behavior.
+
+Fewer lines, files, functions, or abstractions are not automatically simpler. Prefer the shape that makes behavior, ownership, and failure paths easier to understand and change.
+
+## Establish The Boundary
+
+Before editing:
+
+- understand the affected code, callers, tests, comments, and repository conventions;
+- establish the smallest verification baseline that protects observable behavior and error semantics;
+- understand why the current structure exists, including compatibility, performance, platform, history, and failure constraints;
+- define one narrow simplification outcome.
+
+Use this skill only when behavior should remain unchanged. If expected behavior is unclear or needs to change, return that evidence to [Workflow](../workflow/SKILL.md). If the interface or ownership is structurally wrong, use [Design for Depth](../design-for-depth/SKILL.md). If no reliable behavior loop exists, use [TDD](../tdd/SKILL.md) or [Diagnose Failure](../diagnose-failure/SKILL.md) first.
+
+Read [Code Practices](../execute-work/references/code-practices.md) while changing code. Read [Simplification Patterns](references/simplification-patterns.md) when choosing a transformation or deciding whether deletion really reduces complexity.
+
+## Classify The Opportunity
+
+- **Local expression:** names, guards, control flow, duplication, or unnecessary temporary state.
+- **Pass-through indirection:** wrapper, adapter, helper, or layer hides no useful decision.
+- **Accidental abstraction:** generalized machinery has no accepted variation or decision-hiding value.
+- **Scattered concept:** one behavior or policy can move toward one owner without changing its contract.
+- **Dead path:** evidence shows code is unused, unreachable, superseded, or impossible under current invariants.
+- **Structural pressure:** simplification requires changing interfaces, ownership, state, or architecture; return it to Workflow rather than presenting it as cleanup.
+
+## Simplify In Bounded Steps
+
+For each step:
+
+1. name the complexity being removed;
+2. make one behavior-preserving change;
+3. run the focused behavior and failure checks;
+4. inspect whether concepts, coordination, and change surface decreased;
+5. keep or revert the step from evidence.
+
+Keep feature work, bug fixes, edge-case handling, public behavior changes, and broad modernization outside the simplification slice. Report adjacent opportunities rather than absorbing them.
+
+Follow project conventions rather than personal style. Preserve relevant inputs, outputs, side effects, ordering, errors, timing, permissions, compatibility, and resource behavior.
+
+Preserve comments that explain non-obvious rationale, constraints, invariants, or workarounds. Update or remove comments that became stale. Do not add comments that merely narrate the simplified code.
+
+## Treat Tests As Evidence
+
+Do not rewrite valid behavior tests merely to make simplification pass.
+
+If an implementation-detail test fails while observable behavior appears unchanged, classify the conflict before editing it. Add characterization coverage when important accepted behavior lacks protection. Use expected values independent from the implementation.
+
+A green suite is necessary but not sufficient. Inspect the resulting code and real caller path.
+
+## Delete Deliberately
+
+Understand the purpose and current consumers before deleting code.
+
+Removing a useful module should concentrate complexity behind a better interface, not scatter it into callers. Do not delete compatibility, fallback, platform, migration, audit, or recovery behavior because it appears redundant. Use [Migration Work](../migration-work/SKILL.md) when removal has consumer or compatibility obligations.
+
+## Stop
+
+Stop when:
+
+- preserving behavior cannot be demonstrated;
+- the simpler version changes public or failure semantics;
+- performance or resource tradeoffs are material and unmeasured;
+- each step exposes another interface, ownership, or edge-case problem;
+- the diff broadens beyond the accepted boundary;
+- source truth or user decisions conflict with deletion;
+- the result is shorter but harder to explain or test.
+
+Once evidence supports unchanged behavior and the accepted complexity has been removed, freeze the slice. Further cleanup, modernization, and possible improvements require another selected slice. Do not continue to satisfy a line-count target or reviewer taste.
+
+## Report
+
+Report the boundary simplified, concepts or coordination removed, behavior evidence run before and after, relevant comments preserved or changed, intentionally retained complexity, and remaining unverified behavior. A successful simplification reduces reader and change coordination, not merely diff size.

package/skills/simplify-code/references/simplification-patterns.md

@@ -0,0 +1,70 @@
+# Simplification Patterns
+
+Use these as candidate transformations, not automatic rules. Preserve behavior and project conventions.
+
+## Control Flow
+
+- Replace deep nesting with guard clauses when exits are truly equivalent.
+- Collapse duplicate branches into one named path.
+- Replace repeated conditionals on one shape with an explicit model or dispatcher when that removes branching across callers.
+- Name intermediate concepts when a dense expression hides intent.
+- Keep straightforward branching when a lookup, callback table, or polymorphic hierarchy would add more concepts.
+
+## Locality
+
+- Move behavior toward the state or policy it owns.
+- Gather scattered validation, normalization, or failure handling behind one stable seam.
+- Separate orchestration from business rules when each can then be read and tested independently.
+- Reuse a canonical helper instead of maintaining a near-duplicate.
+- Do not centralize unrelated behavior merely because its syntax looks similar.
+
+## Indirection
+
+Question:
+
+- pass-through wrappers;
+- one-use factories and strategy layers;
+- aliases that no longer protect compatibility;
+- helpers whose interface is as complex as their implementation;
+- extension points with no accepted variation;
+- adapters that outlived a migration.
+
+Keep indirection when it hides volatile dependencies, enforces policy, preserves a real compatibility contract, or creates meaningful test and change locality.
+
+## Names And Types
+
+- Rename generic or misleading terms to match domain language.
+- Make invariants explicit at a type or interface boundary when doing so removes downstream checks.
+- Remove casts, optionality, and silent fallbacks only after proving the stronger invariant.
+- Keep comments that explain why, constraints, or non-obvious tradeoffs; remove comments that merely narrate clear code.
+
+## Duplication
+
+Duplication is harmful when one behavior must change in several places and can drift.
+
+Do not extract merely because two snippets look alike. First confirm they represent the same concept and should evolve together.
+
+A small amount of explicit repetition can be simpler than a generalized abstraction with configuration, callbacks, flags, or hidden coupling.
+
+## Dead And Legacy Paths
+
+Before removal, inspect static references, runtime use, generated callers, config, tests, history, and compatibility obligations.
+
+- Truly dead local code may be removed within the agreed simplification boundary.
+- Supported legacy behavior requires deprecation/migration evidence.
+- Historical docs and audit evidence are not dead code.
+- Commented-out code normally belongs in version history, but confirm it is not an intentional operational instruction.
+
+## Before And After Test
+
+Ask:
+
+- Are there fewer concepts and branches?
+- Is ownership clearer?
+- Can behavior be understood through fewer files or transitions?
+- Did error and failure semantics remain visible?
+- Is the public interface smaller or unchanged?
+- Did tests become more behavior-focused rather than more coupled?
+- Would the next likely change touch fewer coordinated locations?
+
+If the answer is mostly no, complexity was relocated rather than reduced.

package/skills/tdd/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: tdd
+description: Use when implementing or changing behavior test-first, fixing a bug with regression evidence, protecting behavior during refactoring, or when a test is difficult to write or starts shaping production design.
+---
+
+# Test-Driven Development
+
+Use one observed failing behavior check to guide the smallest complete implementation for one accepted behavior.
+
+TDD is an execution method inside [Execute Work](../execute-work/SKILL.md). One vertical RED/GREEN/REFACTOR loop is a bounded action, not automatically a Track Work slice. Several accepted behavior loops may remain inside one coherent current slice.
+
+TDD does not define intended behavior. The accepted request, source truth, and user decisions establish what should happen.
+
+## Follow The Behavior Loop
+
+```text
+[Accepted behavior with settled expectation]
+-> [Choose stable seam and independent oracle]
+-> [RED: write and run the smallest behavior check]
+   -> fails for expected missing behavior -> GREEN
+   -> passes immediately -> inspect test, boundary, or existing behavior
+   -> errors for unrelated reason -> correct harness or diagnose
+-> [GREEN: smallest complete implementation]
+-> [Verify focused behavior]
+-> [REFACTOR when useful, without behavior change]
+-> [Verify original path and affected boundary]
+-> [Route]
+   -> another accepted behavior in this slice -> next TDD loop
+   -> coherent extension -> approve and record when needed
+   -> unclear cause or structural pressure -> Workflow
+   -> supported bounded action -> return to Execute Work
+```
+
+Do not write all tests first and all implementation later. Finish, verify, and route one accepted behavior before starting another.
+
+## Use Or Exit Deliberately
+
+Use TDD for accepted behavior changes, bug fixes with a supported cause, consequential logic, and refactors whose behavior needs protection.
+
+Do not force test-first work onto documentation, static content, mechanical formatting, generated output, or a disposable learning prototype whose result is not selected production behavior.
+
+Stop before RED when expected behavior, failure semantics, or a public contract is unsettled. Return the missing direction to [Workflow](../workflow/SKILL.md) rather than encoding a guess as a test.
+
+## Choose The Seam And Oracle
+
+Test observable behavior through the highest stable interface that exercises the real requirement.
+
+A useful seam:
+
+- is used by callers rather than created only for tests;
+- survives internal refactoring;
+- reaches the real behavior or failure path;
+- keeps setup proportionate;
+- can disagree with the implementation.
+
+Derive expected results from source truth, a worked example, protocol contract, or independent calculation—not the implementation algorithm.
+
+Read [Test Design](references/test-design.md) when the test level, oracle, double, rejected state, composed failure, time or concurrency boundary, or legacy seam is unclear.
+
+If testing requires owned internals, duplicated caller choreography, or production hooks used only by tests, return the evidence to Workflow. Use [Design for Depth](../design-for-depth/SKILL.md) only when it establishes design-bearing interface or ownership pressure; do not redesign merely because one test is inconvenient.
+
+## Enforce The Test-First Evidence
+
+- Observe RED failing for the intended missing behavior before changing production code.
+- If RED passes immediately, inspect the test, observing boundary, and existing behavior; do not proceed to GREEN automatically.
+- If RED fails because of syntax, setup, environment, or unrelated behavior, correct the harness or diagnose before implementation.
+- Implement the smallest complete GREEN behavior. Read [Code Practices](../execute-work/references/code-practices.md) while changing code.
+- Refactor only when it improves the result while the focused behavior check remains green.
+- Re-run the original path and smallest affected boundary before returning the supported action and evidence to Execute Work.
+- Do not claim TDD when the check was written after implementation or RED was never observed for the intended reason.
+
+## Keep Tests About Accepted Behavior
+
+Prefer observable outcomes over internal call sequences, real implementations before doubles, independent expected values, descriptive domain names, and one behavior concept per test.
+
+Use fakes, stubs, mocks, or spies only at a boundary where replacement is necessary and the double preserves the fields, effects, invariants, and failure behavior the test needs.
+
+Do not copy the implementation into the expected value, add production methods used only by tests, change a valid test merely to make implementation pass, or treat coverage and test count as proof.
+
+Add an edge-case check only when accepted behavior, observed failure, material safety, or a settled failure contract requires it. If behavior is undefined, return it to Workflow. When related cases keep adding states, flags, setup, or patches, stop the behavior-loop stream and diagnose the shared contract, cause, ownership, or interface.
+
+## Fix Bugs Through The Reported Boundary
+
+First reproduce the reported symptom through the correct seam. A nearby failing path is not the bug.
+
+If no reliable diagnostic loop or supported cause exists, use [Diagnose Failure](../diagnose-failure/SKILL.md) before selecting a production correction. After RED and GREEN, rerun both the minimized regression check and the original unminimized symptom or strongest available observer.
+
+## Stop When Tests Start Designing The System
+
+Return evidence to Workflow when test setup grows faster than behavior coverage, each case requires another public state or fallback, tests protect machinery introduced by earlier patches, the next check requires an unplanned subsystem, or making it pass expands accepted scope.
+
+A green local loop does not prove the global design is right. Diagnose repeated or unexplained failure before redesigning.
+
+## Report
+
+Report the accepted behavior and seam, observed RED result, GREEN implementation, refactor if any, original-path and broader verification, current slice effect, and remaining unverified behavior. Return route-changing evidence rather than silently beginning another behavior or slice.

package/skills/tdd/references/test-design.md

@@ -0,0 +1,96 @@
+# Test Design
+
+Read this when the right test level is unclear, a dependency needs a double, legacy behavior lacks a seam, or test setup starts driving production design.
+
+The goal is confidence in accepted behavior, not maximal isolation or a fixed unit/integration/end-to-end ratio. One TDD behavior loop is a bounded action and may remain inside a larger coherent Track Work slice.
+
+## Choose The Confidence Boundary
+
+Start from the highest stable interface used by callers, then choose the smallest test environment that still exercises its real behavior and failure path:
+
+- **Focused behavior test:** deterministic logic or one stable public operation can prove the requirement.
+- **Integration test:** correctness depends on collaborating components, persistence, serialization, process boundaries, or a real adapter contract.
+- **End-to-end or user-path check:** the requirement is a critical flow whose value depends on the assembled system.
+- **Characterization test:** existing behavior must be observed and protected before a behavior-preserving refactor.
+
+A characterization test records current behavior; it does not make that behavior desired or authoritative. Stop when intended behavior conflicts with source truth or remains user-owned.
+
+A smaller environment is not better when it mocks away the behavior being claimed. A larger environment is not better when its extra machinery adds noise without proving more.
+
+## Build An Independent Oracle
+
+Expected results should come from source truth, a worked example, a protocol contract, or an independently calculated value.
+
+Do not compute the expected value with the same algorithm as the implementation. That produces agreement by construction.
+
+Prefer observable state, outputs, errors, persisted effects, and caller-visible behavior. Assert an interaction only when that interaction is itself part of the accepted contract or the real effect cannot be observed safely at this test boundary.
+
+Keep one behavior concept per test. Multiple assertions are fine when they jointly describe one outcome.
+
+## Rejection And Composed Failures
+
+For authority, persistence, canonical evidence, retry, cancellation, or recovery behavior, identify the dimensions that materially change the outcome:
+
+```text
+entry point
+× valid or invalid input
+× empty or existing accepted state
+× pre-commit or post-commit failure
+× first call or retry/replay
+```
+
+Do not expand this into an exhaustive matrix by habit. Select the smallest rows that can disprove the accepted failure contract. For each selected row, assert:
+
+- returned result;
+- allowed writes or effects;
+- forbidden writes or effects;
+- preservation of prior accepted state;
+- required diagnostic or recovery evidence.
+
+When two accepted conditions can coincide, test the composition rather than assuming isolated cases commute. Examples include cancellation plus integrity failure, successful commit plus failed reconciliation, invalid replacement plus existing valid state, or bounded recovery plus continuation redemption.
+
+## Choose A Test Double
+
+Preference order:
+
+1. **Real implementation:** use when deterministic, fast enough, safe, and controllable.
+2. **Fake:** a lightweight working implementation that preserves the relevant contract.
+3. **Stub:** returns fixed data needed to reach the behavior under test.
+4. **Mock or spy:** records interactions; use sparingly when the interaction itself matters.
+
+Before replacing a dependency, identify:
+
+- the behavior and side effects it owns;
+- which of those effects the test depends on;
+- the boundary being isolated;
+- how the double stays faithful to the real contract and failure modes.
+
+Mock the slow, external, destructive, privileged, or nondeterministic boundary—not a higher-level operation whose behavior the test needs.
+
+Useful double boundaries often include external APIs, email or payment delivery, uncontrollable clocks or randomness, destructive infrastructure, and unavailable remote services. Databases and filesystems may be cheaper and more trustworthy to use for real than to imitate.
+
+A fake or stub must preserve the fields, invariants, errors, and side effects relevant downstream. Validate it against a schema, recorded contract, or shared contract tests when drift would create false confidence.
+
+Do not add public production methods, flags, branches, or lifecycle operations used only by tests. Keep cleanup and fixture construction in test utilities unless production genuinely owns that behavior.
+
+## Time, Randomness, And Concurrency
+
+Prefer an existing controllable boundary for clocks, randomness, scheduling, and external events. Do not expose new public test hooks merely to make assertions convenient.
+
+Avoid arbitrary sleeps as proof. Use observable synchronization, deterministic inputs, bounded eventual assertions, or the real diagnostic loop.
+
+When a race or flaky path cannot be made deterministic, use [Diagnose Failure](../../diagnose-failure/SKILL.md) to raise the reproduction rate and gather evidence before changing production behavior.
+
+## Pressure Signals
+
+Question the seam before adding more test machinery when:
+
+- mock setup is longer or more conditional than the behavior;
+- removing a mock changes what the test is actually proving;
+- many owned internals must be exposed or replaced;
+- doubles duplicate production orchestration;
+- test-only production APIs appear;
+- integration repeatedly fails despite isolated tests passing;
+- fixtures must know internal states, ordering, or cleanup protocols callers should not coordinate.
+
+A real integration test may be simpler than a network of mocks. If the difficulty reflects caller choreography or a shallow interface, use [Design for Depth](../../design-for-depth/SKILL.md) rather than designing production around the test framework.