@hassangameryt/freeflow 0.6.0 → 0.7.1

package/skills/setup-freeflow/SKILL.md

@@ -19,9 +19,9 @@ Read [the activation contract](references/activation-contract.md) before changin
 
 Classify the current state before editing:
 
-- **Unconfigured:** repository config is missing or invalid, so no Freeflow mode is effective. An explicit setup request may create minimal config when it is missing. Replacing or reinterpreting invalid config still requires the specific authority described below.
-- **Configured but ineffective:** valid repository activation exists, but Freeflow is disabled, Skills are dormant, or invalid local config blocks runtime. No mode is effective. An explicit request governs the selected enablement, configuration, or repair; any dormant resolved mode does not.
-- **Effective:** Freeflow Skills report an effective mode. Obey it. Conversation remains read-only; Workflow or Strict Workflow allows agent-performed mutation only for the separately requested setup or repair.
+- **Unconfigured:** repository config is missing or invalid, so Freeflow is not effective. An explicit setup request may create minimal config when it is missing. Replacing or reinterpreting invalid config still requires the specific authority described below.
+- **Configured but ineffective:** valid repository activation exists, but Freeflow is disabled or an invalid local config blocks runtime. No Freeflow guidance is effective. An explicit request governs the selected enablement, configuration, or repair.
+- **Effective:** Freeflow core guidance, the Interaction Contract, and base skills are effective. An explicit setup or repair request may be carried out within its authority; optional capability behavior remains independently gated.
 
 User-operated host settings are direct user actions, not agent-performed config edits. Prefer them when available and do not claim their state changed until the host reports it.
 
@@ -34,21 +34,19 @@ Before editing:
 3. inspect repo instructions only when a conflict would change setup behavior;
 4. identify the host and available delivery evidence when runtime status matters.
 
-A valid repository config establishes activation. A missing local config inherits shared values. An invalid existing local config blocks effective Freeflow instead of falling back silently.
+A valid repository config establishes activation. A missing local config inherits repository settings. An invalid existing local config blocks effective Freeflow instead of falling back silently.
 
 If setup is already valid and no change was requested, preserve it and report the effective sources. Do not rewrite config merely to normalize formatting or materialize defaults.
 
 ## Configure Shared Activation
 
-For a new default setup, write:
+For a new setup, write the minimal activation boundary:
 
 ```json
-{
-  "defaultMode": "workflow"
-}
+{}
 ```
 
-During first activation, an explicitly requested `conversation` or `strict-workflow` mode becomes the shared repository default. Preserve valid existing settings and add no unrequested keys or empty sections.
+Add `enabled: false` only when the user explicitly requests Freeflow to be disabled. Add optional capability configuration only when the user explicitly requests it.
 
 If repository config is invalid or conflicts with accepted source truth, use [Decision Gate](../decision-gate/SKILL.md) before replacing or reinterpreting it.
 
@@ -56,7 +54,7 @@ Do not create or append Freeflow instructions in `AGENTS.md`, `CLAUDE.md`, `.cla
 
 ## Add Personal Overrides Only When Requested
 
-Use `.freeflow/local.json` for an explicitly selected per-checkout override of `enabled`, `interactionContract`, `skills.enabled`, or `defaultMode`. Omitted values inherit from repository config and built-in defaults.
+Use `.freeflow/local.json` for an explicitly selected per-checkout override of `enabled`, `contextVirtualization`, or `conversationHistory`. Omitted values inherit from repository config and built-in defaults. Configure optional Cognitive Routing values only through its explicit settings surface.
 
 In Pi, `/freeflow settings` edits personal overrides and `/freeflow settings repo` edits shared settings. Prefer those controls when available.
 
@@ -68,19 +66,18 @@ If local config is invalid, report that it blocks effective runtime. Repair or r
 
 After successful verification, apply newly effective context directly for the remainder of the setup turn:
 
-- read the [Interaction Contract](../../runtime/prompts/interaction-contract.md) when it is effective;
-- read [Workflow](../workflow/SKILL.md) and [Mode Contract](../mode-contract/SKILL.md) when Skills are effective.
+- read the [Interaction Contract](../../runtime/prompts/interaction-contract.md);
+- read [Workflow](../workflow/SKILL.md) when Freeflow is effective.
 
-This direct read establishes same-turn guidance; it does not prove that a lifecycle adapter ran. After first activation, use [host setup](references/host-setup.md) to name the exact host-native lifecycle action for automatic delivery and resource refresh, state what applies before that boundary, and keep delivery confirmed, unavailable, or unconfirmed from evidence.
+These direct reads establish same-turn guidance; they do not prove that a lifecycle adapter ran. After first activation, use [host setup](references/host-setup.md) to name the exact host-native lifecycle action for automatic delivery and resource refresh, state what applies before that boundary, and keep delivery confirmed, unavailable, or unconfirmed from evidence.
 
 ## Verify And Report
 
 Verify:
 
-- repository config parses and contains a valid `defaultMode`;
+- repository config parses and is the required activation boundary;
 - local config is missing or valid, personal, untracked, and ignored when applicable;
-- effective `enabled`, Interaction Contract, Skills, and configured default values have the expected sources;
-- Skills-disabled mode remains resolved but dormant;
+- effective `enabled`, core guidance, and optional capability values have the expected sources;
 - no repo-owned host instructions or unrelated files changed.
 
 After verification supports a setup result, silently self-review the final observed or changed state before accepting, reusing, or reporting it. Correct clear local issues within the existing setup authority and re-verify the affected boundary; stop on ambiguity, route change, or an out-of-envelope correction.
@@ -89,6 +86,6 @@ Report separately:
 
 1. shared repository activation;
 2. personal override state and effective sources;
-3. effective Interaction Contract, Skills, and mode state;
+3. effective Freeflow core guidance, Interaction Contract, base skills, and optional capability state;
 4. same-turn direct context reads;
 5. automatic runtime delivery as **confirmed**, **unavailable**, or **unconfirmed**.

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

@@ -7,19 +7,18 @@ Freeflow uses layered checkout configuration. Shared repository activation, pers
 `.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:
+Missing core keys use built-in defaults:
 
 - `enabled: true`
-- `interactionContract: true`
-- `skills.enabled: true`
-- `defaultMode: workflow`
+- `contextVirtualization: false`
+- `conversationHistory: false`
+
+Optional capability configuration is explicit and remains independently gated. The legacy `defaultMode`, `interactionContract`, and `skills` keys are unsupported and make the configuration invalid.
 
-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.
+Do not add 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.
 
@@ -31,12 +30,9 @@ It may override these core values:
 
 ```json
 {
-  "enabled": true,
-  "interactionContract": true,
-  "skills": {
-    "enabled": true
-  },
-  "defaultMode": "strict-workflow"
+  "enabled": false,
+  "contextVirtualization": true,
+  "conversationHistory": true
 }
 ```
 
@@ -48,29 +44,28 @@ A missing local file means full inheritance. An invalid existing local file bloc
 
 ## Effective Core State
 
-Resolve core values in this order:
+Resolve remaining configurable values in this order:
 
 ```text
 host session override -> personal override -> repository value -> built-in default
 ```
 
-Host session overrides are host state, not config, and cannot bypass missing or invalid repository activation. Pi may temporarily override Freeflow master enablement, Interaction Contract, Skills, and mode. Claude and Codex support mode-only overrides in plugin-owned session state.
+Host session overrides are host state, not config, and cannot bypass missing or invalid repository activation. Pi may temporarily override Freeflow enablement and the remaining optional context capabilities. Cognitive Routing has its own host-managed session control.
 
 Effective Freeflow requires:
 
 1. valid repository config;
 2. missing or valid local config;
-3. session-resolved `enabled: true`.
+3. session-resolved `enabled: true`;
+4. the mandatory `core.md` and `interaction-contract.md` prompt files.
 
-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.
+The core prompt and Interaction Contract are always delivered together when Freeflow is enabled. Base Freeflow skills are exposed with that core surface. Context Virtualization, Conversation History, and Cognitive Routing remain independently gated capabilities.
 
 ## 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.
+- **Unconfigured:** missing or invalid repository config means Freeflow is not effective. 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 or invalid local config prevents effective Freeflow. An explicit request governs the selected enablement, configuration, or repair.
+- **Effective:** obey the Interaction Contract and core Workflow guidance. Optional capability behavior remains subject to its own effective state.
 
 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.
 
@@ -78,15 +73,14 @@ A user operating native host settings changes host-managed state directly. That
 
 Configuration does not prove runtime delivery.
 
-When effective, host adapters may deliver:
-
-- `runtime/prompts/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 state.
+When effective, host adapters deliver:
 
-Pi may additionally expose explicitly enabled Pi capability skills and tools through its extension. Codex and Claude `SessionStart` hooks compose static fragments from `runtime/prompts/` and mode state; their `UserPromptSubmit` hook delivers only an explicit session-mode change or failure delta.
+- `runtime/prompts/core.md`;
+- `runtime/prompts/interaction-contract.md`;
+- the base Freeflow skill surface;
+- compact current capability state.
 
-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.
+Pi may additionally expose explicitly enabled Pi capability skills and tools. Codex and Claude `SessionStart` hooks compose the mandatory core fragments. Adapters load context only; they do not enforce policy, block tools, grant permissions, or replace repo instructions.
 
 A setup report classifies automatic delivery as:
 

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

@@ -28,26 +28,25 @@ Pi provides these settings scopes:
 
 ```text
 /freeflow settings          personal overrides
-/freeflow settings session  temporary session overrides
+/freeflow settings session  temporary enablement and optional-context 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.
+Session settings can temporarily inherit, enable, or disable Freeflow, Context Virtualization, and Conversation History. One reset action clears those remaining session 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 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 and composes the gated static fragments from `runtime/prompts/`. Runtime State is appended to every provider request; Workflow, Action Selection, and capability bodies remain discoverable rather than hidden persistent messages. Interaction Contract may be independent from Skills; Cognitive Routing, Context Virtualization, and Conversation History require Skills.
+When effective, Pi's `before_agent_start` path preserves the existing system prompt and composes the mandatory `core.md` and `interaction-contract.md` fragments plus effective optional capability prompts. Runtime State is refreshed at session start, after context reconstruction or loss, and when displayed state changes; unchanged state remains in the provider context. Base skill bodies and capability bodies remain discoverable rather than hidden persistent messages. Cognitive Routing, Context Virtualization, and Conversation History are independently gated.
 
-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.
+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. 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 runtime hook reads the same repository and local layers plus plugin-owned session mode state. At supported session start, resume, clear, and compact boundaries, `SessionStart` restores the complete enabled context. On submitted prompts, `UserPromptSubmit` changes mode only for an explicit native or conservative natural-language session control and otherwise emits nothing.
+The packaged runtime hook reads the same repository and local layers. At supported `SessionStart` boundaries—startup, resume, clear, and compact—it restores the complete enabled core context. It does not process submitted prompts or persist session controls.
 
-When top-level Freeflow is effective, the hook loads the applicable static fragments from `runtime/prompts/` and reports configured, session, resolved, and effective mode state without treating a configured default as the current session mode. It does not inject a full Workflow bootstrap.
+When top-level Freeflow is effective, the hook loads `runtime/prompts/core.md` and `runtime/prompts/interaction-contract.md` and emits a compact active Runtime State. It does not inject a full Workflow body or inspect Pi-only capabilities.
 
 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.
 

package/skills/simplify-code/SKILL.md

@@ -1,80 +1,138 @@
 ---
 name: simplify-code
-description: Use when simplifying working code without changing behavior, including removing duplication, indirection, dead abstractions, or confusing control flow.
+description: Use when working code should become easier to understand or change without altering accepted behavior, including removing duplication, indirection, dead abstractions, or confusing control flow.
 ---
 
 # Simplify Code
 
-Reduce the concepts a reader must hold while preserving accepted behavior.
+Reduce the concepts and coordination 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.
+Fewer lines, files, functions, or abstractions are not automatically simpler. Prefer the shape that makes behavior, ownership, and failure paths easier to understand, test, and change.
 
-## Establish The Boundary
+Simplify Code applies one behavior-preserving transformation. It does not define behavior, authorize effects, redesign ownership silently, select or close a Slice, or turn nearby cleanup into accepted work.
 
-Before editing:
+A **simplification action** removes one named source of complexity and produces one assessable before-and-after result. It may contain several mechanical edits and focused checks.
 
-- 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.
+## Enter With A Protected Boundary
 
-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.
+Before editing, establish:
 
-Before changing code, read [Code Practices](../execute-work/references/code-practices.md). Before choosing a transformation or deciding whether deletion really reduces complexity, read [Simplification Patterns](references/simplification-patterns.md).
+- the accepted behavior that must remain unchanged;
+- the callers and failure semantics capable of detecting drift;
+- the smallest reliable behavior baseline;
+- the named complexity or coordination to remove;
+- why the current structure exists, including compatibility, performance, platform, migration, and recovery constraints.
 
-## Classify The Opportunity
+If behavior is unclear or should change, return to [Workflow](../workflow/SKILL.md).
 
-- **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.
+If no reliable behavior check protects the accepted boundary, use [TDD](../tdd/SKILL.md) to establish characterization evidence before simplification. When failure or current behavior remains unexplained, use [Diagnose Failure](../diagnose-failure/SKILL.md).
+
+When the intended result requires changing interfaces, ownership, public state, or failure behavior, return the structural pressure to Workflow with [Design for Depth](../design-for-depth/SKILL.md) as a lens. Do not disguise redesign as cleanup.
+
+Before selecting or materially changing the transformation, read [Simplification Patterns](references/simplification-patterns.md).
+
+Before changing code, read [Code Practices](../execute-work/references/code-practices.md).
+
+## Choose One Simplification
+
+Classify the named complexity:
+
+- **Local expression:** confusing names, guards, branching, duplication, or temporary state.
+- **Pass-through indirection:** a wrapper, helper, adapter, or layer hides no useful decision.
+- **Accidental abstraction:** generalized machinery has no accepted variation or information-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.
+- **Structural pressure:** simplification requires changing interfaces, ownership, state, or architecture; return it rather than editing.
+
+Select the smallest coherent transformation that removes the named complexity while leaving observable and failure behavior intact.
 
-## Simplify In Bounded Steps
+Do not invoke Simplify Code for immediate local cleanup already contained in one TDD behavior loop. Use it when complexity reduction is itself the accepted result.
 
-For each step:
+## Simplify As One Coherent Action
 
-1. name the complexity being removed;
-2. make one behavior-preserving change;
+For the selected transformation:
+
+1. name the concepts, branches, indirection, or coordination being removed;
+2. make the complete 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.
+4. inspect the real caller path;
+5. compare conceptual and coordination cost before and after;
+6. keep or revert the action from evidence.
+
+Several edits may belong to one transformation. Do not create a new action merely because the file, tool, or syntax changes.
 
-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.
+Keep feature work, bug fixes, edge-case behavior, public contract changes, broad modernization, and unrelated cleanup outside the simplification boundary.
 
-Follow project conventions rather than personal style. Preserve relevant inputs, outputs, side effects, ordering, errors, timing, permissions, compatibility, and resource behavior.
+Preserve relevant:
 
-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.
+- inputs and outputs;
+- side effects and ordering;
+- errors and recovery;
+- timing and resource behavior;
+- permissions and compatibility;
+- failure units and externally visible state.
+
+Follow repository conventions rather than personal style.
 
 ## 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.
+If an implementation-detail test fails while caller-visible behavior appears unchanged, classify the conflict before editing:
+
+- the implementation detail may be an accepted contract;
+- the test may be stale or over-coupled;
+- the simplification may have changed relevant behavior;
+- the observing boundary may be insufficient.
+
+A green suite is necessary but not sufficient. Inspect the resulting code, real caller path, and relevant failure behavior.
 
-A green suite is necessary but not sufficient. Inspect the resulting code and real caller path.
+Add characterization coverage only for behavior that must remain stable. Do not fossilize unnecessary machinery merely because it existed before simplification.
 
 ## Delete Deliberately
 
-Understand the purpose and current consumers before deleting code.
+Before deletion, establish the code’s purpose and current consumers through source, runtime registration, configuration, generated callers, tests, history, and compatibility obligations as relevant.
+
+Removing an unnecessary layer should reduce coordination, not scatter its protocol 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 carries consumer, state, or compatibility obligations.
 
-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.
+## Determine Whether It Became Simpler
 
-## Stop
+Ask:
+
+- Are there fewer concepts and branches?
+- Is ownership clearer?
+- Can the behavior be understood through fewer coordinated locations?
+- Did 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 require fewer coordinated edits?
+
+If the answers are mostly no, complexity was relocated rather than reduced.
 
 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;
+- unchanged behavior cannot be supported;
+- public or failure semantics changed;
+- performance or resource tradeoffs became material and unmeasured;
+- each change exposes another interface, ownership, or edge-case problem;
+- the action broadens beyond its accepted boundary;
+- source truth or user decisions conflict with the transformation;
 - 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.
+## Return The Method Result
+
+Once evidence supports unchanged behavior and the named complexity has been removed, stop the simplification route and return to the current owner.
+
+Return:
 
-## Report
+- the protected behavior boundary;
+- concepts or coordination removed;
+- before-and-after behavior evidence;
+- resulting caller and failure-path shape;
+- comments preserved, changed, or removed;
+- intentionally retained complexity;
+- what remains unverified.
 
-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.
+Do not freeze or close the Slice. Do not continue into further cleanup, modernization, or possible improvements without another accepted bounded action.

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

@@ -1,6 +1,6 @@
 # Simplification Patterns
 
-Read this before choosing a simplification transformation or deciding whether deletion really reduces complexity. Use these patterns as candidates, not automatic rules. Preserve behavior and project conventions.
+Read this before selecting or materially changing a simplification transformation. Use these patterns to compare candidates for the named complexity; they do not authorize another result or guarantee that fewer constructs are simpler. Preserve behavior and project conventions.
 
 ## Control Flow
 

package/skills/tdd/SKILL.md

@@ -1,76 +1,143 @@
 ---
 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.
+description: Use when implementing or changing settled behavior test-first, reproducing a bug through regression evidence, or protecting existing behavior before a refactor.
 ---
 
 # Test-Driven Development
 
-Selecting TDD creates no authority. Enter RED only when accepted behavior is settled and the current authority envelope covers the test and production effects.
+Use one observed failing behavior check to guide the smallest complete implementation for one settled behavior.
 
-Use one observed failing behavior check to guide the smallest complete implementation for one accepted behavior.
+TDD provides test-first behavior discipline. It does not define intended behavior, authorize test or production effects, select or close a Slice, or prove claims beyond its observing boundary.
 
-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 new Slice. Several accepted behavior loops may remain inside one coherent Slice; when durable task memory exists, [Track Work](../track-work/SKILL.md) preserves it as the Current Slice.
+One behavior loop is one coherent method result. It may contain several reads, edits, commands, and focused checks. Finish and return one behavior before starting another.
 
-TDD does not define intended behavior. The accepted request, source truth, and user decisions establish what should happen.
+## Enter With Settled Behavior
 
-## Use Or Exit Deliberately
+Before RED, establish:
 
-Use TDD when test-first execution is selected for an accepted behavior change, bug correction with a supported cause, consequential logic, or refactor whose behavior needs protection.
+- the accepted behavior and caller-visible result;
+- relevant success and failure semantics;
+- the boundary where the behavior must hold;
+- authority covering both the check and production effects;
+- the expected reason RED should fail.
 
-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.
+Return unsettled behavior, source conflicts, or user-owned choices to [Workflow](../workflow/SKILL.md). Do not encode a guess as a test.
 
-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.
+Use TDD for:
 
-When TDD applies, before designing or materially changing its behavior check, read [Test Design](references/test-design.md) to choose the test level, seam, oracle, doubles, rejected-state coverage, composed failures, time or concurrency boundary, and characterization strategy.
+- accepted behavior changes;
+- bug corrections with a supported cause or reliable regression loop;
+- consequential logic whose contract benefits from executable evidence;
+- characterization needed before a protected refactor.
+
+Do not force TDD onto documentation, static content, formatting, generated output, or a disposable prototype that is not selected production behavior.
+
+When a bug lacks a supported cause or reliable reproduction, use [Diagnose Failure](../diagnose-failure/SKILL.md) before selecting a production correction.
+
+## Design The Behavior Check
+
+Before designing or materially changing the check, read [Test Design](references/test-design.md).
+
+Name:
+
+- the behavior concept;
+- the stable caller-visible seam;
+- an oracle independent from the implementation;
+- the expected missing behavior RED should expose;
+- the focused and affected boundaries that must be rerun after GREEN.
+
+Use the smallest test environment that still exercises the real behavior and relevant failure path. Do not choose a smaller boundary that mocks away the claim or a larger one that adds noise without proving more.
+
+Keep one behavior concept per loop. Several assertions are appropriate when they jointly describe one outcome.
 
 ## Follow The Behavior Loop
 
 ```text
-[Accepted behavior with settled expectation]
+[Settled accepted behavior]
 -> [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 -> Workflow -> when covered, record if needed -> next TDD loop
-   -> unclear cause or structural pressure -> Workflow
-   -> supported bounded action -> return to Execute Work
+   -> fails for the intended missing behavior -> GREEN
+   -> passes immediately -> inspect test, boundary, and existing behavior
+   -> errors or fails elsewhere -> correct the harness or diagnose
+-> [GREEN: implement the smallest complete behavior]
+-> [Run the focused behavior check]
+-> [REFACTOR locally when useful]
+-> [Rerun the original path and affected boundary]
+-> [Return the method result and evidence]
 ```
 
-Do not write all tests first and all implementation later. Finish, verify, and route one accepted behavior before starting another.
+Do not write all tests first and implementation later. Finish one behavior loop before another.
+
+## Observe Valid RED
+
+Run RED before changing production behavior.
+
+RED is valid only when:
+
+- the check executes through the intended seam;
+- its assertion represents accepted behavior;
+- it fails because the behavior is missing or incorrect;
+- unrelated syntax, setup, environment, or fixture failures do not explain it.
 
-## Enforce The Test-First Evidence
+If the check passes immediately, inspect whether:
 
-- 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.
-- Before changing production code for GREEN, read [Code Practices](../execute-work/references/code-practices.md). Then implement the smallest complete behavior.
-- 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.
+- the behavior already exists;
+- the assertion is ineffective;
+- the observing boundary is wrong;
+- the test is reproducing a nearby path rather than the reported behavior.
 
-## Keep Tests About Accepted Behavior
+Do not proceed automatically to GREEN.
 
-Use the behavior check as the RED/GREEN contract for one accepted behavior. Do not change a valid test, copy the production implementation into its expected value, or add production hooks used only by tests merely to reach GREEN.
+Correct a clear local harness defect. When the failure remains unexplained or repeated harness changes do not establish valid RED, return to Diagnose Failure.
 
-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.
+## Implement Complete GREEN
+
+Before changing production code, read [Code Practices](../execute-work/references/code-practices.md).
+
+Implement the smallest complete behavior that satisfies the accepted contract—not merely the visible assertion.
+
+Do not:
+
+- weaken or rewrite a valid test to obtain GREEN;
+- calculate expected values through production logic;
+- add public hooks, states, flags, or branches used only by tests;
+- silently invent fallback, retry, recovery, or edge-case behavior;
+- broaden implementation into another accepted behavior.
+
+If GREEN requires an unsettled behavior, public contract, subsystem, or material scope expansion, return the evidence to Workflow.
+
+## Refactor Locally
+
+Refactor only when it improves the behavior just implemented while its focused check remains green.
+
+TDD refactoring is immediate local cleanup within the behavior loop. It may improve names, remove nearby duplication, simplify control flow, or clarify ownership without changing the accepted result.
+
+Do not turn REFACTOR into a general cleanup stream. When reducing existing complexity is itself an accepted result, return the completed behavior loop and use [Simplify Code](../simplify-code/SKILL.md) as a separate execution route.
+
+When test pressure exposes caller coordination, public states, test-only seams, or ownership problems, preserve that evidence. Use [Design for Depth](../design-for-depth/SKILL.md) only when structural pressure is supported.
 
 ## Fix Bugs Through The Reported Boundary
 
-First reproduce the reported symptom through the correct seam. A nearby failing path is not the bug.
+First reproduce the reported symptom through the correct seam. A nearby failing path is diagnostic evidence, not the bug.
+
+After GREEN, rerun:
+
+1. the minimized regression check;
+2. the original unminimized symptom or strongest available observer;
+3. the smallest affected boundary capable of exposing regression.
 
-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.
+Do not report a fix when only the minimized check passes and the reported boundary remains unavailable.
 
-## Stop When Tests Start Designing The System
+## Return The Method Result
 
-When Test Design's pressure signals appear, the next check requires an unplanned subsystem, or making it pass expands accepted scope, stop and return the evidence to Workflow. Use [Design for Depth](../design-for-depth/SKILL.md) only when that evidence establishes design-bearing interface or ownership pressure; diagnose repeated or unexplained failure before redesigning.
+Return to the current owner with:
 
-## Report
+- accepted behavior and observing seam;
+- observed RED result and why it was valid;
+- GREEN implementation result;
+- local refactor, when performed;
+- focused, original-path, and affected-boundary evidence;
+- what the evidence supports and does not support;
+- unresolved or unverified behavior.
 
-Report the accepted behavior and seam, observed RED result, GREEN implementation, refactor if any, original-path and broader verification, Slice effect when relevant, and remaining unverified behavior. Return route-changing evidence rather than silently beginning another behavior or slice.
+Do not select another behavior, close the Slice, trigger review, commit, or continue merely because GREEN was reached.