@hassangameryt/freeflow 0.8.0 → 0.9.0

package/skills/review-work/references/adjudicate-work-review.md

@@ -1,97 +0,0 @@
-# Adjudicate Work Review
-
-Read this after an independent work review returns and before selecting what follows from its report.
-
-This reference is judgment; Review Work's Rules still bind. Adjudication belongs to the receiving active agent. It tests the report against the reviewed state, source truth, and evidence. It is not independent review and does not inherit the reviewer's authority or judgment.
-
-## Dispose Each Material Item
-
-For every material item, choose one disposition.
-
-### Accepted
-
-State:
-
-- the supported implementation problem;
-- its consequence for the reviewed boundary;
-- whether it is Blocking or Non-blocking;
-- whether its cause is supported, unnecessary to select a clear local correction, or uncertain.
-
-### Rejected
-
-State the concrete reason: unsupported, stale, resolved, duplicate, preference-only, out of scope, or based on a source misread.
-
-### Open
-
-State:
-
-- the unresolved concern;
-- its potential boundary consequence;
-- the missing evidence or owner decision.
-
-When factual evidence is missing, restate the item as a Verify Work input: claim, required observing boundary, available evidence and its limit, and the smallest evidence that could disagree.
-
-A suggested correction may help explain a finding, but it does not establish cause, select the remedy, or authorize implementation.
-
-After disposing the items, derive the adjudicated judgment. Do not separately accept the reviewer's overall judgment.
-
-- **Pass:** no accepted Issues or material Open items remain.
-- **Non-blocking:** only accepted Non-blocking Issues remain.
-- **Inconclusive:** a material Open item prevents judgment.
-- **Blocking:** at least one accepted Blocking Issue remains.
-
-## Use Verification Results
-
-Route a known material evidence gap through [Workflow](../../../skills/workflow/SKILL.md) to [Verify Work](../../../skills/verify-work/SKILL.md). Verification produces factual evidence; it does not revise the reviewer's report or determine the review judgment.
-
-- **Supported:** re-adjudicate the evidence gap. Do not infer Pass.
-- **Contradicted:** re-adjudicate against source truth; the result may establish an Issue, invalidate one, or expose a source conflict.
-- **Inconclusive:** keep the item Open. The adjudicated review remains Inconclusive when the gap is material.
-- **Unavailable:** keep the item Open and state why the required boundary cannot currently be observed.
-
-Select focused independent follow-up only when the new evidence still requires judgment from a separate context.
-
-## Decide Whether Remediation Is Ready
-
-Remediation is ready when:
-
-- required behavior is settled;
-- the problem and boundary consequence are supported;
-- enough cause or decision basis exists to bound a correction;
-- affected interactions and dependencies are known sufficiently;
-- no material alternative or user-owned choice remains.
-
-When remediation is ready, state:
-
-- the proposed correction and rationale;
-- affected behavior and locations;
-- required ordering or constraints;
-- regression evidence and verification boundary;
-- whether focused independent follow-up remains justified;
-- the authority state.
-
-Use existing correction authority only when it covers that result. Otherwise propose the correction and any warranted follow-up once, then wait. A finding, adjudication, or selected review does not authorize mutation.
-
-Actual correction returns to [Execute Work](../../../skills/execute-work/SKILL.md). Preserve the accepted behavior; do not change tests, Specs, policies, or source truth merely to satisfy a reviewer or obtain Pass.
-
-## Route When Remediation Is Not Ready
-
-- unclear or repeated cause: [Diagnose Failure](../../../skills/diagnose-failure/SKILL.md);
-- unsettled direction or materially different remedies: [Discuss](../../../skills/discuss/SKILL.md);
-- user-owned choice or source conflict: [Decision Gate](../../../skills/decision-gate/SKILL.md);
-- missing factual support: route the named claim through [Workflow](../../../skills/workflow/SKILL.md) to [Verify Work](../../../skills/verify-work/SKILL.md);
-- uncovered correction: propose the bounded correction and wait.
-
-When findings interact, assumptions are challenged, or user input could change the remedy, report a problem checkpoint and stop before selecting or executing a correction.
-
-## After Authorized Correction
-
-Verify the affected boundary and perform ordinary self-review.
-
-Select focused independent follow-up only when accepted corrections, affected interactions, new evidence, or remaining risk still require judgment from a separate context. Do not dispatch follow-up merely because Review 1 found an Issue or because remediation occurred.
-
-If Review 2 remains Blocking, adjudicate it before acting again. Diagnose a repeated, extending, invalidating, or causally uncertain blocker. Return an independent clear local defect to its owner when diagnosis would add no useful understanding. Review 3 remains exceptional, separately authorized, and final.
-
-## Stop
-
-Stop when every material item is Accepted, Rejected, or Open; the adjudicated judgment is supported; and the next route and authority state are explicit.

package/skills/review-work/references/independent-work-reviewer-contract.md

@@ -1,139 +0,0 @@
-# Independent Work Reviewer Contract
-
-Read this before preparing or performing a separately selected independent review of implementation or integrated work.
-
-This reference is a contract: the required context and the reviewer prompt are binding as written. The reviewer did not produce the reviewed state. Give them the work product, source truth, and evidence needed to judge it directly. Do not provide only the producer's summary, reasoning, or claimed result.
-
-## Required Context
-
-Provide:
-
-- the work and future action covered by the review;
-- accepted outcome, requirements, and non-goals;
-- relevant Specs, Plans, tests, policies, ADRs, and established behavior;
-- the implementation, changed files, or diff range;
-- verification evidence and known gaps;
-- only the review lenses material to this boundary;
-- active evidence authority: none, or each exact covered check with its expected evidence and stop condition;
-- review number and, for follow-up, prior items, adjudication, corrections, and new evidence.
-
-When state transitions or proof integrity matter, also provide the invariant or state owner, affecting paths, observing mechanism, forbidden mutations, prior-state requirements, adversarial disproof, mutation footprint, and fidelity limits.
-
-## Reviewer Prompt
-
-```md
-# Independent Work Review
-
-Review work you did not produce. Inspect the supplied work, source truth, and evidence directly. Report without editing. The review ends with this report; do not adjudicate findings, fix items, dispatch follow-up, or continue merely to obtain Pass.
-
-A pass is valid. Use a high evidence bar, not a high item count. Do not broaden scope or treat possible improvement as unfinished work.
-
-Use supplied and already available evidence. Do not start a missing active check unless the review contract explicitly authorizes that exact check. Otherwise report **Needs evidence** with the claim and required observing boundary. When an exact check is covered, apply Verify Work's check-result and claim-result semantics; active evidence does not authorize editing or broaden the review.
-
-## Boundary
-
-- Protected future action: [boundary]
-- Reviewed state: [commit, tree, diff, or other exact identity]
-- Work: [diff range, changed files, implementation, or integrated result]
-
-## Accepted Outcome And Non-Goals
-
-- Outcome: [required result]
-- Requirements: [accepted requirements]
-- Non-goals: [intentional exclusions]
-
-## Source Truth
-
-- [Specs, Plans, tests, policies, ADRs, and established behavior]
-
-## Verification Evidence
-
-- Checks and results: [commands, observations, and results]
-- Known gaps: [gaps or none]
-- When relevant: [state owner, affecting paths, observer, forbidden mutations, prior-state requirements, adversarial disproof, mutation footprint, fidelity limits]
-
-## Review Scope
-
-- Review number: [1 | 2 | 3]
-- Material lenses: [alignment and correctness | regression and integration | failure and risk | evidence | design and minimality | maintainability]
-- Active evidence authority: [none | exact covered check, expected evidence, and stop condition]
-
-For Review 2 or 3:
-
-- Prior items and adjudication: [Accepted | Rejected | Open]
-- Clarifications: [settled decisions or none]
-- Corrections and new evidence: [changes and verification]
-- Remaining risk: [narrow unresolved scope]
-
-## Check
-
-Apply only the selected lenses:
-
-- accepted behavior is implemented without invention or omission;
-- affected callers, states, and components remain correct together;
-- material failure paths and risks are handled safely;
-- verification supports the claims at the required boundary;
-- complexity and coordination are justified;
-- the work remains understandable without hidden policy or fragile coupling.
-
-Do not search for unrelated issues. Report an out-of-scope issue only when it materially affects whether this boundary may be crossed.
-
-Before calling something an Issue, ask:
-
-1. Is required behavior or source truth settled? If not, use **Question**.
-2. Are reachability and material consequence supported? If not, use **Needs evidence**.
-3. Does the boundary require correction? Use **Blocking Issue** when it cannot be crossed safely, otherwise **Non-blocking Issue** when correction can be deferred safely.
-4. Is the change merely useful beyond this boundary? Omit it by default; use **Improvement** only when materially relevant or requested.
-
-A **Needs evidence** item must identify the claim, required observing boundary, available evidence and its limit, why the gap affects judgment, and the smallest evidence that could disagree. Establish that the claim is required. Check the candidate examined and any later code/test changes; a weakened assertion or superseded capture cannot establish current acceptance. Missing evidence does not by itself justify an implementation fix or a stronger requirement.
-
-A Blocking Issue must identify the exact location, violated requirement or source truth, evidence, concrete boundary consequence, and correction constraints or owning activity to re-enter. Recommend a specific correction only when directly supported.
-
-For Review 2 or 3, inspect only accepted corrections, affected interactions, new evidence, and remaining risk. Do not reopen Rejected items without contradictory evidence. For each new Blocking Issue, state whether it repeats, extends, invalidates, or exposes another consequence of a prior correction; is independent; or cannot yet be related from the evidence. Report a related pattern rather than proposing another patch. Review 3 is final; do not recommend Review 4.
-
-## Determine The Judgment
-
-1. **Blocking:** at least one Blocking Issue exists.
-2. **Inconclusive:** no Blocking Issue exists, but a material Question or Needs evidence item prevents judgment.
-3. **Non-blocking:** only Non-blocking Issues remain.
-4. **Pass:** no Issues or material unresolved items remain.
-
-Improvements do not change the judgment.
-
-## Output
-
-Omit empty groups. Do not include Improvements unless they are materially relevant or explicitly requested.
-
-Review type: independent
-Review number: [1 | 2 | 3]
-Boundary: [reviewed work and protected future action]
-Reviewed state: [state identity]
-Judgment: Pass | Non-blocking | Inconclusive | Blocking
-Reasoning: [concise evidence-backed judgment]
-Relationship to prior items (Review 2 or 3 only): [related consequence | independent defect | unclear, with evidence]
-
-### Review Items
-
-#### Issues — Blocking
-- [location, issue, violated source, evidence, consequence, correction constraints or owning activity]
-
-#### Issues — Non-blocking
-- [location, issue, evidence, why it can be deferred]
-
-#### Unresolved — Questions
-- [question, effect on judgment, required answer]
-
-#### Unresolved — Needs evidence
-- [claim, required observing boundary, available evidence and limit, why the gap affects judgment, smallest evidence that could disagree]
-
-#### Improvements
-- [only when materially relevant or requested: improvement, benefit, evidence]
-
-Evidence gaps: [unproved claims or none]
-```
-
-## Calibration
-
-Lead with the few items that can change the boundary judgment. Prior review, urgency, implementation effort, or producer confidence does not establish correctness.
-
-The report is evidence for adjudication. It is not authority over source truth, owner decisions, corrections, or another independent dispatch. Pass, Non-blocking, Inconclusive, and Blocking are all valid exits.

package/skills/review-work/references/security-risk-lens.md

@@ -1,67 +0,0 @@
-# Security Risk Lens
-
-Read this before reviewing work that changes trust boundaries, authentication, authorization, permissions, untrusted input, secrets, sensitive data, security-relevant dependencies or external integrations, code-execution boundaries, or failure behavior with security consequences.
-
-This reference is judgment, with two Rules: security-sensitive product behavior stays user-owned, so never invent access, retention, logging, or fail-open or fail-closed policy during review; and never copy secrets, credentials, unrestricted personal data, or sensitive payloads into review context. It helps frame review and does not replace repository security policy, threat modeling, specialist review, or stack-specific hardening guidance.
-
-## Establish Authority
-
-Identify:
-
-- assets and data requiring protection;
-- actors, roles, tenants, and privilege levels;
-- trust boundaries and external systems;
-- accepted security and privacy policy and threat model;
-- compatibility and failure behavior that security controls must preserve.
-
-## Trace The Paths
-
-Review the affected path from boundary to effect:
-
-- authentication: who or what is this actor;
-- authorization: may this actor perform this operation on this resource;
-- input: validation, canonicalization, size, encoding, and injection surfaces;
-- output: escaping, disclosure, error detail, and side channels;
-- data: collection, transport, storage, isolation, retention, deletion, and audit;
-- secrets: source, scope, rotation, exposure, and logging;
-- execution: shell, file, URL, template, deserialization, plugin, or code-loading boundaries;
-- dependencies: provenance, permissions, known risk, update impact, and transitive behavior;
-- failure: partial state, retries, lockout, rate limits, rollback, and fail-open or fail-closed behavior.
-
-Look for confused-deputy and cross-tenant paths, not only malformed input.
-
-## Require Boundary-Matched Evidence
-
-Prefer evidence at the real boundary:
-
-- tests proving allowed and denied roles and resources;
-- negative input and injection cases;
-- dependency or configuration inspection tied to the shipped artifact;
-- logs or traces demonstrating no secret or sensitive leakage;
-- failure-path tests for partial authorization, retry, and recovery;
-- specialist analysis for cryptography, sandboxing, identity protocols, or high-impact threats.
-
-A generic scanner pass cannot prove authorization logic or policy correctness. A unit test cannot prove deployed headers, identity configuration, or infrastructure permissions.
-
-Use the smallest sanitized evidence that supports the item.
-
-## Calibrate Items
-
-Treat supported exploitable behavior, policy violation, unintended privilege or data exposure, unsafe failure semantics, secret leakage, or a missing required control as an Issue.
-
-Classify it against accepted security policy and the reviewed boundary:
-
-- **Blocking:** crossing the boundary would remain unsafe, non-compliant, or contrary to a required control.
-- **Non-blocking:** the issue is real but can be deferred safely without violating the accepted boundary.
-
-Use **Question** when security behavior or accepted risk remains undecided. Use **Needs evidence** when a control may exist but the available test or environment cannot establish it.
-
-Treat materially useful defense in depth beyond the accepted boundary as an Improvement. Omit theoretical hardening, preference, or hypothetical completeness.
-
-Do not omit an observed security issue because the selected lenses were narrower. Name the asset, path, precondition, consequence, evidence, and source requirement.
-
-## Return Through The Selected Role
-
-For self-review, return a route-changing security concern to [Workflow](../../../skills/workflow/SKILL.md). Use [Diagnose Failure](../../../skills/diagnose-failure/SKILL.md) for unknown exploitability or cause, [Decision Gate](../../../skills/decision-gate/SKILL.md) for missing policy or accepted-risk decisions, [Design For Depth](../../../skills/design-for-depth/SKILL.md) when trust decisions spread across callers, and [Launch Work](../../../skills/launch-work/SKILL.md) when the concern affects production rollout.
-
-For independent review, classify the concern in the review report and stop. Do not route, correct, or dispatch follow-up. The receiving agent adjudicates the report and selects what follows.

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

@@ -1,103 +0,0 @@
-# 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
-{}
-```
-
-Missing core keys use the built-in default `enabled: true`.
-
-Optional Cognitive Routing and Tool Execution configuration is explicit and remains independently gated. The legacy `defaultMode`, `interactionContract`, and `skills` keys are unsupported and make the configuration invalid. The removed `contextVirtualization` and `conversationHistory` keys are also unsupported in either config layer; delete them manually wherever present before Freeflow can activate. Setup does not migrate or remove them automatically.
-
-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.
-
-## Personal Overrides
-
-`.freeflow/local.json` is optional per-checkout state. It cannot activate Freeflow without a valid repository config.
-
-It may override the core enablement value:
-
-```json
-{
-  "enabled": false
-}
-```
-
-The field is optional. Omission inherits the repository value, then the built-in default. Local core precedence is property-level, not whole-file replacement.
-
-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 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 enablement. 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`;
-4. the mandatory `core.md` and `interaction-contract.md` prompt files.
-
-The core prompt and Interaction Contract are always delivered together when Freeflow is enabled. Base Freeflow skills are exposed with that core surface. Cognitive Routing and Tool Execution remain independently gated capabilities; Context Virtualization and Conversation History are removed.
-
-## Mutation Authority By State
-
-- **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.
-
-## Runtime Delivery
-
-Configuration does not prove runtime delivery.
-
-When effective, host adapters deliver:
-
-- `runtime/prompts/core.md`;
-- `runtime/prompts/interaction-contract.md`;
-- the base Freeflow skill surface;
-- compact current capability state.
-
-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:
-
-- **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

@@ -1,67 +0,0 @@
-# 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 Freeflow and Cognitive Routing session controls
-/freeflow settings repo     shared repository settings
-```
-
-Session settings can temporarily inherit, enable, or disable Freeflow and override Cognitive Routing profiles/delegation. One reset action clears those 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 mandatory `core.md` and `interaction-contract.md` fragments plus the Cognitive Routing prompt when effective. 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. The former Context Virtualization and Conversation History settings, prompts, and tool operations are removed.
-
-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. 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 `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.
-
-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.
-
-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/simplify-code/SKILL.md

@@ -1,85 +0,0 @@
----
-name: simplify-code
-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
-
-Remove one named source of complexity while preserving accepted behavior. Judge simplicity by the concepts and coordination a reader must hold—not line, file, or abstraction count alone.
-
-This method supplies a behavior-preserving transformation under the current owner. It does not define behavior, authorize redesign, select or close a Slice, or turn nearby cleanup into accepted work.
-
-## Establish What Must Stay True
-
-Before editing, identify:
-
-- the accepted behavior, relevant callers, and failure semantics;
-- the reliable baseline capable of detecting change;
-- the complexity or coordination to remove;
-- why the current structure exists, including compatibility, platform, performance, migration, and recovery constraints.
-
-If expected behavior is unclear or should change, return to [Workflow](../workflow/SKILL.md). If failure or current behavior is unexplained, use [Diagnose Failure](../diagnose-failure/SKILL.md). Do not characterize an invented expectation.
-
-Use existing adequate checks. When protection is missing, establish the smallest useful observation of behavior before transforming it; read [Test Design](../verify-work/references/test-design.md) before designing or materially changing the check. Characterization protects required stable behavior, not every accidental implementation detail. It is evidence for a refactor, not a mandatory test-first implementation method.
-
-Return changes to interfaces, ownership, public state, or failure behavior through Workflow with [Design for Depth](../design-for-depth/SKILL.md) as a lens. Do not disguise a material redesign as cleanup.
-
-Read [Simplification Patterns](references/simplification-patterns.md) before selecting or materially changing the transformation. Read [Code Practices](../execute-work/references/code-practices.md) before changing code.
-
-## Select One Coherent Transformation
-
-Name the actual complexity:
-
-- confusing expression, naming, branches, or temporary state;
-- a pass-through wrapper that hides no useful decision;
-- generalized machinery with no accepted variation;
-- a scattered concept that can have one owner without changing its contract;
-- an unused, superseded, unreachable, or impossible path;
-- structural pressure requiring a separately selected boundary change.
-
-Choose the smallest complete transformation that removes it. Keep related edits together even across files. Do not create another method activity for incidental local cleanup already contained in implementation; use Simplify Code when reducing complexity is itself the accepted result.
-
-Fewer helpers are not better if their removal spreads lifecycle or error-handling knowledge into callers. Preserve useful information hiding and intentional constraints.
-
-## Apply And Observe
-
-Within the existing agreement:
-
-1. State which concepts or coordination will disappear.
-2. Make the complete behavior-preserving change.
-3. Run focused behavior and failure checks.
-4. Inspect the real caller path and resulting code.
-5. Compare the required coordination before and after.
-6. Keep the supported result or return a failed transformation for correction or covered rollback.
-
-Preserve inputs/outputs, side effects and ordering, errors/recovery, relevant timing and resource behavior, permissions, compatibility, and externally visible state. Follow repository conventions rather than personal style.
-
-Do not combine feature work, bug fixes, new edge-case behavior, public contract changes, broad modernization, or unrelated cleanup with the transformation.
-
-## Interpret Checks Without Protecting Accidental Machinery
-
-Use [Verify Work](../verify-work/SKILL.md) to determine what the observations establish. A green suite cannot prove unchanged behavior it did not exercise. Do not rewrite a valid behavioral assertion merely to make the refactor pass.
-
-If an implementation-detail check fails while caller behavior appears unchanged, establish whether the detail is contractual, the check is stale or over-coupled, the transformation changed relevant behavior, or the observer is inadequate. Do not infer the answer from the desired cleanup.
-
-Test sequencing alone is not assurance. Retain or add independent checks where needed, and inspect the changed behavior rather than report only test counts.
-
-## Delete Only With Supported Absence
-
-Before removing code, establish its purpose and current consumers through relevant source, runtime registration, configuration, generated callers, tests, history, and compatibility obligations. An empty local search does not establish the absence of external or dormant consumers.
-
-Do not remove compatibility, fallback, platform, migration, audit, or recovery behavior merely because it looks redundant. Use [Migration Work](../migration-work/SKILL.md) when deletion carries consumer, state, or compatibility obligations.
-
-Preserve historical evidence; do not delete it to make a reference search clean.
-
-## Judge The Result And Stop
-
-Ask whether there are fewer concepts to coordinate, clearer ownership, fewer related edit locations, visible failure semantics, a smaller or unchanged public interface, and tests focused on behavior rather than internal choreography.
-
-If the result is shorter but harder to understand, test, or change, complexity was relocated rather than reduced.
-
-Stop and return the changed boundary when unchanged behavior is unsupported, public/failure semantics changed, a material resource tradeoff is unmeasured, source truth conflicts, or each correction exposes another ownership or edge-case problem. Do not extend cleanup to preserve a failing approach.
-
-When the named complexity is removed and the behavior boundary is supported, return to the current owner for applicable self-review and acceptance. Report the protected behavior, concepts removed, before/after evidence and limits, caller/failure-path shape, relevant comment changes, and intentionally retained complexity.
-
-Do not close the Slice, begin further cleanup, or claim broader modernization from this result. Continue only through another covered action serving the agreed outcome.

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

@@ -1,70 +0,0 @@
-# Simplification Patterns
-
-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
-
-- 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.