npm - @hassangameryt/freeflow - Versions diffs - 0.7.3 → 0.9.0 - Mend

@hassangameryt/freeflow 0.7.3 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (426) hide show

package/skills/design-for-depth/references/design-pressure-signals.md DELETED Viewed

@@ -1,182 +0,0 @@
-# Design Pressure Signals
-Read this when observed coordination could change the next route and an equivalent design-route classification is not already supported.
-Do not count smells. Identify the pressure that changes the next action, or conclude that none does.
-## Classify The Evidence
-Ask:
-1. What caller outcome and interface are affected?
-2. What facts must callers know or coordinate?
-3. Did the current change add to that knowledge?
-4. What policy, dependency, state transition, or failure behavior is spreading?
-5. Is the cause supported?
-6. Can the issue be resolved inside accepted scope and authority?
-Choose the narrowest supported route:
-- **Continue:** current boundary remains sound.
-- **Local correction:** defect remains within one module and contract.
-- **Diagnosis:** failure is repeated or unexplained and cause is unsupported.
-- **Spec or Plan revision:** behavior, acceptance, or execution boundary is incomplete.
-- **User decision:** resolving pressure changes a user-owned outcome.
-- **Learning:** evidence cannot distinguish viable boundaries.
-- **Deepening:** supported information-hiding improvement fits accepted scope.
-- **Deferred deepening:** pressure is real but not worth resolving now.
-## Change Amplification
-Pressure exists when one policy change requires unrelated edits across callers.
-Example:
-```text
-Changing retry policy requires edits in API routes, workers,
-UI state, and tests.
-```
-Name the decision causing the edits. Do not merely move the same choreography into one helper.
-## Caller Protocol Growth
-Pressure exists when callers must perform internal lifecycle steps:
-```text
-configure -> open -> retry -> translate error -> clean up -> publish evidence
-```
-Related signals:
-- every correction adds another state or flag;
-- recovery steps become ordinary caller behavior;
-- callers depend on paths, filenames, provider errors, or queue names;
-- a complete outcome becomes a public protocol of attempts and temporary states.
-Ask whether one operation can own the complete success and failure unit while publishing diagnostics separately.
-## Scattered Policy
-Pressure exists when one product or operational decision is encoded in several places.
-Example:
-```text
-billing transition timing appears separately in webhook,
-dashboard, email, and worker behavior.
-```
-Do not centralize behavior until the policy is accepted. When it is user-owned or conflicting, stop for a decision.
-## Unowned State Or Failure
-Pressure exists when no module owns:
-- canonical state and its visibility point;
-- forbidden partial outcomes;
-- retry, degradation, or escalation;
-- cancellation and reconciliation;
-- recovery after partial completion;
-- evidence proving the final state.
-Do not design architecture around an invented failure policy.
-## Contract-Surface Growth
-Pressure exists when each patch adds public:
-- flags;
-- temporary states;
-- manifest fields;
-- retry links;
-- recovery instructions;
-- provider-specific errors;
-- cache or integrity controls.
-Ask whether callers own those facts or are being forced to understand internal protocol.
-## Distorted Tests
-Pressure exists when tests:
-- reproduce caller choreography;
-- mock many helpers to verify one outcome;
-- depend on private lifecycle states;
-- protect machinery introduced by recent patches;
-- prove rejection without checking forbidden writes;
-- make provider mechanics look like domain requirements.
-Do not automatically add mocks or test-only seams. First inspect whether the production boundary owns the complete behavior.
-An intentional internal test is not a defect merely because it observes internals.
-## Edge-Case Patch Streams
-Pressure exists when related fixes repeatedly add conditions, states, or caller rules.
-Example:
-```text
-handle missing contact
--> handle fallback
--> handle duplicate delivery
--> handle retry telemetry
--> expose another state to callers
-```
-Do not infer architecture from finding count alone. Diagnose whether the cases share one missing contract, state owner, or failure unit.
-## Scope Growth
-Pressure exists when a bounded result unexpectedly:
-- requires a subsystem;
-- expands remaining work;
-- pulls deferred capabilities into scope;
-- invalidates earlier evidence;
-- requires unrelated callers to change.
-Return the evidence. The correct route may be simplify, split, revise an artifact, learn, defer, or stop.
-## Common Interface Mismatches
-### Pass-through wrapper
-Renames a call without hiding policy or provider behavior.
-Keep only when it preserves a real domain, compatibility, or observation boundary.
-### Leaky interface
-Callers know infrastructure-specific details.
-### God module
-Unrelated decisions are collected behind one interface.
-### Speculative seam
-Indirection exists only for imagined variation.
-### Dependency cycle
-Modules cannot change independently because their responsibilities point at each other.
-### Premature artifact detail
-A Spec or Plan freezes classes, factories, tables, or algorithms before evidence supports the boundary.
-## False Positives
-Do not escalate when:
-- stable repetition remains small and local;
-- broad edits are mechanical and source-backed;
-- a one-off script does not need long-term abstraction;
-- a wrapper preserves a real compatibility contract;
-- an isolated condition is wrong but the interface remains sound;
-- an internal test intentionally verifies an internal module;
-- resolving the pressure would exceed the user’s goal without blocking it.
-Stop once the route is classified. Return evidence and classification; do not redesign automatically.

package/skills/design-for-depth/references/implementation-decisions.md DELETED Viewed

@@ -1,76 +0,0 @@
-# Implementation Decisions
-Read this when unresolved representation, identity, ownership, algorithm, dependency, or failure choices could materially change a technical recommendation or invalidate significant dependent work. Apply it before recommending a mechanism during discussion, writing its guiding design, or beginning substantial implementation. Skip it for a supported local change whose remaining mechanics do not alter those boundaries.
-Use this method under Design for Depth and the current activity. It does not create another planning phase, document requirement, approval gate, or compute role.
-## Identify What Implementation Would Still Have To Invent
-Start from the current goal and constraints, relevant source evidence, and existing design. During discussion, mark unsettled outcomes and approaches as provisional: compare their consequences without turning an explored option into an accepted requirement. Select supported engineering details within the agreement; return user-owned choices through the current activity. Ask:
-> Which remaining choices could change correctness, complexity, failure behavior, or force substantial dependent work to be redone?
-Name the actual question, not a generic demand for more design. For example, deciding which occurrence identifies a source matters more than choosing Map versus array; deciding what survives a failed transfer matters more than choosing a retry helper.
-For each consequential unknown, choose one route:
-- **Evidence supports a mechanism:** select it and explain why it fits.
-- **An environmental fact is missing:** identify the observation that distinguishes the alternatives before dependent implementation.
-- **A user-owned boundary is unsettled:** return that choice through the current owner.
-- **Only ordinary mechanics remain:** leave them to implementation and continue.
-Do not invent APIs, future files, or stronger guarantees to complete the design. Nor should the user have to choose implementation syntax: explain user-owned consequences and resolve supported engineering details within the agreement.
-## Choose The Representation And Mechanism
-Develop only the decisions that answer the current question. Reuse supported design rather than filling every category:
-| Decision | Make explicit when material |
-| --- | --- |
-| Representation and identity | Domain objects and independent lifetimes; what counts as the same occurrence; what must remain distinct |
-| State and ownership | Authoritative facts, derived caches, transition owner, and permitted mutations |
-| Algorithm and cost | Essential steps; collection keys and relationships; update/invalidation rules; work repeated as input grows |
-| Effects and failure | Required ordering; what is accepted or visible at each boundary; what survives failure and what may be retried |
-| Modules and dependencies | Who hides each decision; which callers consume the result; dependencies or coordination that must not spread |
-| Evidence | Observable required behavior and a plausible wrong implementation the check must reject |
-Use Design for Depth's interface, state/failure, and module references when their named questions need resolution; do not repeat their full methods here. Compare materially different approaches only when they remain viable. Prefer eliminating unnecessary coordination to hiding the same protocol behind another helper.
-## Preserve The Decision, Not A Complete Patch
-Communicate enough for another implementer, or your later context, to retain the chosen approach:
-- the decision and its source basis;
-- why it fits and the invariant it protects;
-- the essential mechanism, including a small type or control-flow sketch when useful;
-- the counterexample and distinguishing observer;
-- required constraints versus suggested mechanics and local freedom;
-- the evidence or condition that would invalidate the choice.
-Use a paragraph, example, or compact table. Do not prescribe every loop or helper, or reproduce the whole program in prose. Naming a data structure without its keys, meaning, and maintenance rules is not useful algorithmic direction.
-Keep durable decisions in the owning technical design; keep execution order in the Plan and changed understanding in task memory. A current assignment should carry the applicable decisions and relevant source section, not another complete copy of every artifact. A path or hash does not establish that its contents are available to the implementer.
-## Check Realization Before Dependent Expansion
-When an unfamiliar boundary could invalidate substantial later work, choose the first coherent implementation path that can disagree with the design. It may span several files and a failure case. A skeleton, happy-path result, or green summary alone may not exercise the decision.
-Assess the actual implementation and observation: which important choices were realized, omitted, contradicted, or replaced with a supported reason? Check ownership, identity, ordering, and the observer—not fidelity to suggested filenames or helper syntax.
-A precise sketch can be wrong. Preserve accepted behavior, stop dependent effects when the mechanism is invalidated, and resolve the affected choice through the current owner. Supported local corrections need no design restart. Once the boundary is established, reuse it rather than repeating this assessment after every edit.
-## Examples
-### Identity And Indexing
-Weak direction: "Use a Map and avoid repeated scans."
-Useful direction: "Keep native occurrence IDs as source identity. Equal bodies may identify several candidates; do not merge their occurrences. Let the source owner maintain the result-to-exchange relationship. Update appended sources and rebuild affected indexes after ancestry replacement. Check repeated equal bodies, late attribution, and a branch change; measure the repeated preparation path rather than only an isolated lookup. Helper layout is local. Reconsider the index if the source does not provide the assumed stable identity."
-### Acknowledgment And Retry
-Weak direction: "Make persistence idempotent and robust."
-Useful direction: "The append owner distinguishes observed acknowledgment from an uncertain attempt. An equal entry in memory does not resolve an earlier failure. Validate before mutation; publish accepted state only at the supported acknowledgment boundary. Test append advancing memory then failing, followed by the identical operation: uncertainty must remain until supported reconciliation. Also test an acknowledged duplicate so the implementation does not reject every retry. Do not infer filesystem durability from readback. Reconsider the mechanism if the actual host boundary differs."
-Stop when the current discussion has a supported recommendation or explicit open question, or the next implementation has a supported approach and intentional local freedom. Preserve provisional versus accepted decisions when passing the result back to the current activity; discussion does not authorize implementation. Do not pursue a complete blueprint for later work whose premises remain unsettled.

package/skills/design-for-depth/references/interface-design-loop.md DELETED Viewed

@@ -1,136 +0,0 @@
-# Interface Design Loop
-Read this before comparing materially different interfaces or settling an important correctness boundary where ownership is consequential.
-Use only evidence and criteria capable of distinguishing viable boundaries. Do not emit a full checklist unless the artifact itself requires one.
-## 1. Frame The Complete Outcome
-Orient broadly enough to state:
-- caller and complete outcome;
-- source-backed behavior and non-goals;
-- decisions the caller genuinely owns;
-- dependencies and current constraints;
-- material state and failure boundaries;
-- why the current seam requires attention.
-Do not begin from existing flags, storage paths, classes, or temporary states. They may be symptoms of the current design.
-## 2. Define The Failure Unit
-Name the coherent outcome treated as one success, failure, and recovery boundary.
-Define material:
-- terminal states and observers;
-- canonical and diagnostic state;
-- evidence written;
-- forbidden partial outcomes;
-- safe restart and recovery;
-- required proof;
-- whether partial reuse is required or merely an optimization.
-When correctness materially depends on canonical state, partial effects, atomic visibility, concurrency, cancellation, retries, recovery, reconciliation, or evidence of the final outcome, read [State And Failure Boundaries](state-and-failure-boundaries.md).
-## 3. Inventory Material Caller Knowledge
-List only facts callers must know and that could affect the boundary:
-- operations and inputs;
-- caller-owned decisions;
-- ordering and lifecycle states;
-- configuration and provider details;
-- dependencies;
-- errors and failure semantics;
-- compatibility and migration;
-- recovery, cost, and performance expectations.
-For each fact ask:
-- Does the caller own it?
-- Could the module own it?
-- Is it stable enough to expose?
-- Would changing it force surrounding edits?
-The goal is not zero interface knowledge. It is the smallest honest contract.
-## 4. Classify Capability Maturity
-Separate:
-- required trust and safety;
-- accepted efficiency or scale;
-- demonstrated portability;
-- speculative flexibility.
-Do not defer required correctness to obtain a simpler-looking interface. Do not promote hypothetical efficiency, scale, or portability into present architecture.
-## 5. Produce Alternatives Only When Real
-When materially different ownership choices remain viable, design two or three interfaces that change seam placement—not only terminology.
-For each show:
-1. ordinary caller usage;
-2. caller-owned decisions;
-3. hidden internal protocol;
-4. failure unit and observable behavior;
-5. dependency and adapter strategy;
-6. evidence needed;
-7. material cost or limitation.
-When module decomposition, cohesion, dependency direction, cycles, layering, policy-versus-infrastructure ownership, or change propagation materially affects the design, read [Module And Dependency Design](module-and-dependency-design.md).
-Do not manufacture alternatives for a local, reversible, source-backed choice.
-## 6. Compare On Discriminating Criteria
-Use only criteria that could change the recommendation:
-- behavior per interface fact;
-- locality of likely change;
-- cohesion and ownership clarity;
-- correct-use ergonomics;
-- misuse and hidden-decision risk;
-- dependency direction;
-- failure honesty and recovery;
-- contract stability;
-- test surface;
-- reversibility;
-- maturity fit;
-- implementation and evidence cost.
-Prefer the boundary that removes concepts and coordination, not one that centralizes the same protocol behind additional terminology.
-## 7. Learn Before Freezing
-When evidence cannot distinguish viable boundaries, define one bounded learning slice:
-```text
-Question:
-Competing boundaries:
-Smallest prototype or observation:
-Evidence required:
-Time or cost boundary:
-Discard-or-promote rule:
-Return condition:
-```
-The learning slice answers the design question. It does not quietly implement the whole subsystem.
-## 8. Return The Supported Boundary
-Return:
-- structural evidence;
-- selected boundary and hidden decision;
-- caller-owned contract;
-- module and dependency implications;
-- failure unit and material failure behavior;
-- rejected alternatives and discriminating reason, when alternatives were real;
-- unresolved user-owned decisions;
-- assumptions and required evidence;
-- narrowest next route.
-Stop once a boundary is supported or a bounded learning question is identified. Recommendation does not authorize implementation.

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

@@ -1,147 +0,0 @@
-# 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.