@hassangameryt/freeflow 0.5.0 → 0.7.0

package/skills/design-for-depth/references/module-and-dependency-design.md

@@ -0,0 +1,147 @@
+# Module And Dependency Design
+
+Read this when module decomposition, cohesion, dependency direction, cycles, layering, policy-versus-infrastructure ownership, or change propagation materially affects the design.
+
+Do not use this reference merely because the codebase has many files or dependencies.
+
+## Decompose Around Coherent Decisions
+
+A module should own one coherent outcome, policy, state boundary, or failure unit.
+
+Do not split only by:
+
+- processing step;
+- technical file type;
+- framework convention;
+- arbitrary size;
+- desire for more abstractions.
+
+Ask:
+
+- Which behavior changes together?
+- Which decision has one reason to change?
+- Which state and failure behavior belong together?
+- What should callers stop coordinating?
+
+## Prefer Cohesion Over Convenience
+
+High cohesion means related behavior, invariants, state, and failure handling live together.
+
+Pressure exists when:
+
+- one module owns unrelated policies;
+- one policy is spread across many modules;
+- state transitions are separated from their invariants;
+- failure handling is detached from the operation it protects;
+- callers assemble the real behavior from helpers.
+
+Do not centralize unrelated behavior merely to reduce duplication.
+
+## Direct Dependencies Toward Stable Policy
+
+Policy should not depend directly on volatile infrastructure details when those details can change independently.
+
+Prefer:
+
+```text
+stable outcome or policy
+-> small dependency interface
+-> infrastructure adapter
+```
+
+Use dependency inversion only when it hides real variation, provider mechanics, migration, or testing control.
+
+Do not add interfaces around every concrete implementation.
+
+## Detect Dependency Cycles
+
+A dependency cycle often indicates:
+
+- responsibilities are divided incorrectly;
+- shared policy has no owner;
+- state is jointly owned;
+- interfaces expose implementation details;
+- modules must know each other’s lifecycle.
+
+Do not break a cycle by moving imports or creating a neutral-looking utility while preserving the same conceptual cycle.
+
+Name the shared decision and assign ownership.
+
+## Preserve Honest Layering
+
+A layer is useful when it hides a distinct level of decision.
+
+A layer is shallow when it:
+
+- forwards calls;
+- renames types;
+- exposes lower-layer errors and states;
+- requires callers to understand both layers;
+- exists only to satisfy a pattern.
+
+Allow a higher-level module to request outcomes. Keep infrastructure details below the boundary.
+
+## Use Ports And Adapters Proportionately
+
+A port is an outcome or capability required by policy. An adapter supplies concrete infrastructure.
+
+Use when:
+
+- provider variation exists;
+- migration is known;
+- infrastructure details leak into policy;
+- tests require safe dependency control.
+
+Avoid when:
+
+- one stable implementation exists;
+- the wrapper hides no decision;
+- the generic interface preserves provider quirks;
+- caller complexity does not decrease.
+
+## Keep Shared Code From Becoming Shared Ownership
+
+A shared helper may centralize syntax while leaving policy ownership scattered.
+
+Before extracting shared code, ask:
+
+- Is this one concept that should evolve together?
+- Who owns its behavior and failure contract?
+- Are callers still making the same decision independently?
+- Does extraction remove coordination or merely relocate code?
+
+Some duplication is cheaper than a shared abstraction with unclear ownership.
+
+## Test Through Module Contracts
+
+Module tests should protect:
+
+- coherent behavior;
+- invariants;
+- public failure semantics;
+- dependency contracts;
+- real seams.
+
+Question module shape when tests must:
+
+- construct many internals;
+- reproduce dependency ordering;
+- mock several owned collaborators;
+- inspect states callers should not know.
+
+Do not make production architecture imitate the test framework.
+
+## Return
+
+Return:
+
+- affected modules and responsibilities;
+- policy, state, or failure ownership;
+- dependency direction;
+- cycle or layering pressure;
+- proposed boundary and caller contract;
+- variation or migration justifying seams;
+- evidence and unresolved decisions;
+- narrowest supported route.
+
+Stop when dependencies support the selected outcome without unnecessary coordination. Do not reorganize the entire codebase for conceptual purity.

package/skills/design-for-depth/references/software-design-philosophy.md

@@ -1,248 +1,202 @@
 # Software Design Philosophy
 
-Use this reference when `design-for-depth` needs deeper reasoning than the active skill can carry.
+Read this when structural pressure is supported but the likely-changing decision or missing information-hiding boundary cannot yet be named.
 
-This is not a checklist to run every time. Pull the idea that changes the next route.
+Use only the principle that identifies the missing ownership. Do not produce a literature review, pattern catalog, or system-wide redesign.
 
-## Core Claim
+## Complexity Is Coordination
 
-Good design reduces coordination.
+Complexity is not line count. It appears as:
 
-A deep module lets callers, tests, reviewers, and future agents use a small interface to get a lot of behavior. A shallow module makes them learn almost as much as the implementation.
+- **Change amplification:** one behavior change requires many surrounding edits.
+- **Cognitive load:** callers must remember many facts to use the module correctly.
+- **Obscurity:** important rules or ownership are difficult to discover.
+- **Dependency burden:** safe change requires understanding unrelated modules.
+- **Unknown unknowns:** a caller cannot tell what else it must inspect.
 
-Design work is worthwhile when it hides a decision that would otherwise spread.
+A large implementation can be simple to use. A small helper can be complex when every caller must know its quirks.
 
-## Ousterhout: Complexity, Deep Modules, Strategic Programming
-
-### Complexity
-
-Complexity shows up as:
+Ask:
 
-- too many dependencies;
-- obscurity, where important facts are hard to find;
-- change amplification, where a small behavior change touches many places;
-- cognitive load, where the user of a module must remember too much;
-- unknown unknowns, where a future agent cannot tell what it must inspect.
+- What must a future caller or maintainer know?
+- How many locations must change together?
+- Which important facts are difficult to discover?
+- Which dependencies must be inspected before a safe change?
 
-For Freeflow, complexity is not “many lines.” A single compact helper can be complex if callers must know its quirks. A large implementation can be simple to use if the interface hides the hard parts.
+## Deep Modules
 
-### Deep modules
+A deep module provides substantial coherent behavior through a small interface.
 
-A deep module has a simple interface and useful behavior behind it.
+Callers state the outcome they need. The module owns:
 
-Deep means:
+- sequencing;
+- likely-changing policy;
+- internal state transitions;
+- cleanup;
+- provider mechanics;
+- internal failure handling.
 
-- callers say what outcome they need;
-- implementation owns sequencing and policy details;
-- tests can verify behavior through the public interface;
-- future changes stay localized;
-- docs and review comments do not need to explain the hidden machinery every time.
+A wrapper is not deep merely because it hides lines. It is deep when callers stop knowing concepts or coordinating protocol.
 
-Shallow means:
+Depth is not breadth. A god module hiding unrelated decisions is not deep.
 
-- the interface mirrors the implementation;
-- callers pass many flags and know ordering rules;
-- tests assert internal call sequences;
-- wrappers rename work without hiding decisions;
-- future agents still need to inspect everything to use it safely.
+## Strategic And Tactical Design
 
-### Strategic vs tactical programming
+A tactical change makes the current patch fit.
 
-Tactical programming makes the current patch fit, even if it spreads complexity.
+A strategic change spends proportionate effort so that the next likely change remains local and correct use remains simple.
 
-Strategic programming spends a little extra attention to preserve future locality.
+Do not redesign everything in anticipation of the future. Do stop when the current patch clearly:
 
-Freeflow translation:
+- spreads a likely-changing decision;
+- adds caller protocol;
+- exposes internal state;
+- creates another required workaround;
+- makes the next accepted change materially harder.
 
-- Do not redesign everything up front.
-- Do stop when the local patch clearly makes the next slice, review, or bug fix harder.
-- Return the structural evidence to [Workflow](../../workflow/SKILL.md) when a tactical patch is becoming structural work.
+Strategic design is proportionate investment, not maximal architecture.
 
-## Parnas: Information Hiding
+## Hide Likely-Changing Decisions
 
-Parnas's key design move: modules should hide design decisions likely to change.
+Organize modules around decisions likely to change, not merely processing steps.
 
-Do not decompose only by processing steps:
+Instead of exposing:
 
 ```text
-parse -> validate -> send -> log
+parse -> validate -> retry -> send -> log -> clean up
 ```
 
-when the real likely-changing decision is:
+look for the decision those steps implement:
 
 ```text
-notification delivery policy: provider choice, retry, fallback, telemetry, failure semantics
+notification delivery policy
 ```
 
-A good module hides the unstable decision.
-
-For consequential systems, failure behavior is often the unstable decision. Hide the contract in the module before callers invent their own retries, fallbacks, state writes, escalation paths, or graceful-failure claims.
-
 Ask:
 
-- What decision would cause the most edits if it changed?
-- What can fail, who observes it, what state is written, and what must not happen?
-- Does the system fail closed, fail open, degrade, escalate, retry, or stop?
-- What recovery path and evidence prove graceful handling?
-- Which callers currently know that decision?
-- Can one module own it?
-- What interface would let callers stop knowing it?
+- What decision would cause the most surrounding edits if it changed?
+- Which callers currently know it?
+- Who should own it?
+- What outcome-level interface would let callers stop knowing it?
+- Is the decision accepted or still user-owned?
 
-Examples:
+Failure and recovery policy are often likely-changing decisions.
 
-- Billing grace period policy should not be spread across webhook handlers, email copy, UI guards, and tests.
-- Notification retry/fallback policy should not be duplicated in each route.
-- Permission semantics should not be separately encoded in frontend, backend, and test setup.
-- Cache invalidation rules should not require every caller to remember freshness knobs.
+## Preserve Conceptual Integrity
 
-## Feathers: Seams And Enabling Points
+A module should express one coherent model of its outcome, state, and failure behavior.
 
-A seam is where behavior can change without editing the surrounding work.
+Pressure exists when:
 
-A seam needs an enabling point: the place where a different adapter, test double, probe, or behavior can be supplied.
+- the same concept has different names or rules across callers;
+- several modules partially own the same decision;
+- one module exposes unrelated mental models;
+- callers translate between incompatible representations;
+- each feature adds another exception to the shared concept.
 
-Freeflow use:
+Prefer one clear ownership model over several locally convenient but incompatible ones.
 
-- Use seams to make hard-to-test or hard-to-change behavior tractable.
-- Do not create seams merely because a pattern sounds clean.
-- Prefer seams that match real variation or observability needs.
+Conceptual integrity does not mean one module or one abstraction. It means related behavior follows one coherent set of decisions.
 
-Questions:
+## Use Seams And Enabling Points For Real Leverage
 
-- What behavior needs to vary?
-- Where can that variation enter without editing callers?
-- What enabling point supplies the adapter or behavior?
-- Does the seam protect production code and tests, or only add indirection?
+A seam allows behavior, dependencies, or observation to change without editing surrounding code.
 
-Good seam candidates:
+An enabling point supplies the variation:
 
-- provider variation: email/SMS/payment/search/storage;
-- environment variation: prod/test/offline/fake implementations;
-- observability variation: probes, clocks, log sinks, metrics;
-- migration variation: old and new implementations behind one interface.
+- adapter;
+- provider;
+- fake;
+- clock;
+- probe;
+- policy;
+- migration implementation.
 
-Weak seam candidates:
+Good seams correspond to:
 
-- one implementation with no likely variation;
-- a seam created only to mock internals while the real interface stays awkward;
-- a factory/registry around every function;
-- an adapter whose interface still exposes provider-specific quirks.
+- demonstrated provider or environment variation;
+- known migration;
+- dependency control required by tests;
+- observation or fault injection;
+- policy that changes independently from infrastructure.
 
-## Ports And Adapters
+Weak seams:
 
-Ports/adapters protects core behavior from infrastructure details.
+- wrap one stable call;
+- add factories without ownership;
+- expose provider quirks through generic names;
+- exist only to mock internals while the caller interface remains awkward.
 
-Freeflow wording:
+## Separate Policy From Infrastructure
 
-- The core owns policy.
-- The adapter owns provider mechanics.
-- The interface between them says what the core needs or provides.
+When infrastructure details leak into product or domain policy, use a boundary where:
 
-Use this idea when infrastructure details are leaking into product logic.
+```text
+policy requests outcome
+-> adapter performs provider mechanics
+```
 
 Examples:
 
-- Stripe event parsing is adapter work; billing policy is core work.
-- Email provider retries are adapter work; user notification policy may be core work.
-- Database query syntax is adapter work; permission semantics are core work.
-- Browser event plumbing is adapter work; user-flow state is core work.
-
-Do not over-apply ports/adapters:
-
-- simple scripts may not need ports;
-- a single stable library call may not need an adapter;
-- wrapping an SDK without hiding policy or provider quirks is often shallow.
-
-## Public Contract Cost
-
-Hyrum's Law applies beyond public HTTP APIs: every observable flag, path, state, ordering rule, filename, error, timing behavior, and fallback can become depended upon.
-
-Expose a fact only when the caller owns it or correct use requires it. Internal protocols may remain detailed and independently tested without becoming public seams.
-
-A useful split:
-
-- **Public:** caller-owned outcome, decisions, stable invariants, and observable failure semantics.
-- **Internal:** storage layout, provider mechanics, retries, cleanup, integrity publication, temporary states, and optimization machinery.
-
-Public flexibility has permanent coordination cost. One outcome-level operation is often deeper than a toolkit that lets callers reconstruct the module's lifecycle.
+- billing policy should not depend on payment-provider error names;
+- notification policy should not be repeated in each provider call;
+- permission semantics should not depend on database representation;
+- user-flow state should not depend on browser event plumbing.
 
-## Maturity And Learning
+Do not add ports and adapters around every stable library call. The boundary is useful only when it hides policy, variation, or mechanics callers should not own.
 
-Classify mechanisms before adding them:
+## Treat Observable Facts As Contracts
 
-- required trust and safety cannot be deferred merely to simplify the design;
-- efficiency, scale, and portability require accepted requirements or observed pressure.
+Callers may depend on any observable:
 
-When the best interface cannot be known from source inspection, use a bounded learning slice. Name the question, competing designs, evidence, cost boundary, and discard-or-promote rule. Code can answer a design question without becoming the production design automatically.
+- flag;
+- path;
+- state;
+- error;
+- timing rule;
+- fallback;
+- ordering behavior;
+- filename;
+- retry count.
 
-## Refactoring Pressure
+Expose a fact only when:
 
-Design pressure often appears as ordinary implementation pain:
+- the caller owns the decision;
+- correct use requires it;
+- it is stable enough to support;
+- its compatibility cost is understood.
 
-- shotgun surgery;
-- repeated review findings;
-- flaky tests around ordering;
-- many mocks for one behavior;
-- hard-to-explain correctness;
-- one bug fix causing another;
-- “just add this flag everywhere.”
+Public flexibility has lasting coordination cost. Prefer one outcome-level operation over a toolkit that requires callers to reconstruct the lifecycle.
 
-Do not treat all pressure as a command to refactor.
+## Separate Required Capability From Speculation
 
-Classify it:
+Classify proposed mechanisms as:
 
-- **Real design pressure:** complexity spread blocks safe progress.
-- **Local mess:** cleanup can happen within current scope.
-- **Deferred deepening:** record the candidate, finish current work.
-- **Owner decision:** deeper change affects product/API/security/compatibility.
+- **Trust:** required to know the result is valid.
+- **Safety:** prevents damage, leakage, or runaway behavior.
+- **Efficiency:** saves time, requests, or money.
+- **Scale:** supports concurrency or volume.
+- **Portability:** supports additional environments or providers.
 
-## Applying The Philosophy In Freeflow
+Required trust and safety cannot be deferred merely to simplify the design.
 
-### In discussion
+Efficiency, scale, and portability require accepted requirements or observed pressure. Do not turn imagined future variation into present interface cost.
 
-Use design ideas to ask better questions, not to freeze architecture.
+## Name The Missing Boundary
 
-Good questions:
-
-- Which decision is most likely to change?
-- Who should know this rule?
-- What should callers stop coordinating?
-- What future variation is real, not imagined?
-- Which tests should survive a provider or implementation change?
-
-### In specs
-
-Specs name behavior and boundaries. They should not lock in unproven module shapes.
-
-Use:
-
-```text
-Tentative: notification delivery may need one policy-owning module if retries/fallbacks continue spreading.
-Open: whether provider variation is real now or deferred.
-```
-
-not:
+Use supported evidence to state:
 
 ```text
-Requirement: implement NotificationDeliveryPortFactoryStrategy.
+Outcome:
+Coordination currently spread across:
+Likely-changing decision:
+Current owners:
+Proposed owner:
+What callers would stop knowing:
+Failure unit:
+Evidence still missing:
 ```
 
-### In plans
-
-Use [Write Plan](../../write-plan/SKILL.md) only when the ordered strategy can be stated without guessing. When later direction remains provisional, keep it in [Track Work](../../track-work/SKILL.md) or return the evidence to [Workflow](../../workflow/SKILL.md) rather than freezing it as a Plan.
-
-For consequential systems, make failure behavior explicit before implementation choices harden. Do not leave it as an implementer guess after planning only the happy path.
-
-A good slice can be verified through the intended interface. If the slice requires broad caller choreography, revise the slice.
-
-### In review
-
-Review design depth by asking whether the diff reduces or increases caller knowledge.
-
-A diff can pass tests and still fail design review if it scatters policy or creates a shallow interface.
-
-### In diagnosis
-
-Repeated failures may indicate that the system is missing a module, seam, or source-truth decision.
+If the decision cannot yet be named, define one bounded learning question. Do not create a generic abstraction as a substitute for understanding.
 
-Do not keep fixing symptoms when every fix reveals another coordination problem.
+Stop once the missing decision or boundary is named—or evidence shows no worthwhile boundary change is supported.

package/skills/design-for-depth/references/state-and-failure-boundaries.md

@@ -0,0 +1,136 @@
+# State And Failure Boundaries
+
+Read this when correctness materially depends on canonical state, partial effects, atomic visibility, concurrency, cancellation, retries, recovery, reconciliation, or evidence of the final outcome.
+
+Do not apply this reference to a simple local value change whose state owner and failure behavior are already sound.
+
+## Name Canonical State
+
+Identify:
+
+- canonical source of truth;
+- who may create, replace, or invalidate it;
+- visible states and invariants;
+- commit or visibility point;
+- diagnostic versus authoritative records;
+- what callers may safely cache or infer.
+
+Do not let several modules each behave as the source of truth.
+
+A log, cache, temporary file, UI projection, or recovery marker is not canonical merely because it is observable.
+
+## Define State Transitions
+
+For every material transition, establish:
+
+```text
+precondition
+-> accepted operation
+-> commit or visibility point
+-> resulting canonical state
+-> evidence
+```
+
+Name forbidden transitions and partial states.
+
+Prefer one owner for transition policy. Callers should not reproduce state-machine rules independently.
+
+## Bound Partial Effects
+
+When an operation affects several resources or can fail midway, establish:
+
+- which effects may occur before commitment;
+- which effects are forbidden before commitment;
+- what must be rolled back, reconciled, or retained;
+- what prior accepted state must survive;
+- how partial outcomes are detected;
+- what result is safe to expose.
+
+Atomicity may come from transactions, staging, replacement, versioning, or explicit reconciliation. Do not claim atomic behavior from intention alone.
+
+## Separate Retry, Resume, And Replay
+
+These are different capabilities:
+
+- **Retry:** attempt the same operation again.
+- **Resume:** continue incomplete work from preserved state.
+- **Replay:** apply an event or request again.
+- **Idempotency:** repeated application has one supported effect.
+- **Recovery:** restore a safe supported state.
+- **Reconciliation:** compare and resolve divergent state.
+
+Supporting one does not imply the others.
+
+Expose them only when required by accepted behavior or observed failure.
+
+## Design Concurrency Deliberately
+
+When operations can overlap, identify:
+
+- shared state;
+- ordering and visibility;
+- lost-update or duplicate-effect risk;
+- serialization or conflict rule;
+- cancellation behavior;
+- stale-read policy;
+- observer capable of proving the required outcome.
+
+Do not add locks, queues, retries, or optimistic versions without naming the invariant they protect.
+
+## Define Failure And Recovery
+
+For the failure unit, state:
+
+- who observes failure;
+- canonical state after failure;
+- diagnostic evidence;
+- forbidden partial effects;
+- fail-open, fail-closed, degrade, stop, retry, or escalation behavior;
+- safe restart or recovery operation;
+- evidence proving recovery.
+
+A graceful error response does not prove graceful state handling.
+
+## Keep Recovery Out Of Ordinary Callers
+
+Callers should normally request an outcome and receive supported success or failure.
+
+Do not require every caller to know:
+
+- cleanup order;
+- retry schedule;
+- temporary paths;
+- partial-state markers;
+- provider error translation;
+- reconciliation commands.
+
+Publish diagnostics without exposing recovery choreography unless callers genuinely own recovery.
+
+## Test State And Failure Through Observable Invariants
+
+Tests should verify:
+
+- accepted final state;
+- preserved prior state;
+- forbidden writes;
+- composed failures;
+- retry or replay behavior when required;
+- cancellation and recovery;
+- evidence at the real observing boundary.
+
+A passing happy-path test does not prove partial-failure safety.
+
+## Return
+
+Return:
+
+- canonical state and owner;
+- material invariants;
+- transition and visibility boundary;
+- failure unit;
+- forbidden partial outcomes;
+- retry, resume, replay, and recovery capabilities actually required;
+- evidence and remaining uncertainty;
+- narrowest supported route.
+
+Stop when state and failure ownership are sufficient for the current design decision. Do not design every theoretical failure mode.