@hassangameryt/freeflow 0.2.0 → 0.3.0

package/plugins/freeflow/router/dist/types.d.ts

@@ -1,234 +0,0 @@
-export declare const PRESERVE_MODES: readonly ["summary", "important", "full"];
-export type PreserveMode = (typeof PRESERVE_MODES)[number];
-export declare const RETRIEVAL_ACTIONS: readonly ["query", "locate", "retrieve", "expand", "explain"];
-export type RetrievalAction = (typeof RETRIEVAL_ACTIONS)[number];
-export declare const TOOL_STATUSES: readonly ["ok", "error"];
-export type ToolStatus = (typeof TOOL_STATUSES)[number];
-export declare const EXECUTION_STATUSES: readonly ["success", "failed", "timed_out", "cancelled"];
-export type ExecutionStatus = (typeof EXECUTION_STATUSES)[number];
-export declare const ROUTING_STATUSES: readonly ["routed", "passed_through", "partial", "failed"];
-export type RoutingStatus = (typeof ROUTING_STATUSES)[number];
-export declare const ROUTE_KINDS: readonly ["retrieve", "run", "safety-net", "pass-through"];
-export type RouteKind = (typeof ROUTE_KINDS)[number];
-export declare const EVIDENCE_WINDOWS: readonly ["exact", "small", "lines_30", "lines_80", "section", "full"];
-export type EvidenceWindow = (typeof EVIDENCE_WINDOWS)[number];
-export declare const OUTPUT_STREAMS: readonly ["stdout", "stderr", "combined", "raw"];
-export type OutputStream = (typeof OUTPUT_STREAMS)[number];
-export declare const POST_TOOL_ROUTING_MODES: readonly ["off", "safety-net", "strict"];
-export type PostToolRoutingMode = (typeof POST_TOOL_ROUTING_MODES)[number];
-export interface RepoSourceRef {
-    kind: "repo";
-    path: string;
-}
-export interface VaultSourceRef {
-    kind: "vault";
-    outputId: string;
-    stream?: OutputStream;
-}
-export interface NativeToolSourceRef {
-    kind: "native";
-    tool: string;
-    outputId: string;
-}
-export type SourceRef = RepoSourceRef | VaultSourceRef | NativeToolSourceRef;
-export interface EvidencePacket {
-    id: string;
-    source: SourceRef;
-    excerpt: string;
-    why: string;
-    window: EvidenceWindow;
-    expandable: boolean;
-    path?: string;
-    lines?: string;
-}
-export interface RecoveryHint {
-    how: string;
-    outputId?: string;
-    evidenceId?: string;
-}
-export interface RoutingDecision {
-    status: RoutingStatus;
-    route: RouteKind;
-    reason: string;
-}
-export interface CommandExecution {
-    status: ExecutionStatus;
-    exitCode: number | null;
-    durationMs?: number;
-}
-export interface ImportantLine {
-    stream: Exclude<OutputStream, "raw">;
-    lines: string;
-    excerpt: string;
-}
-export interface CommandParserReference {
-    path: string;
-    line?: number;
-    column?: number;
-    code?: string;
-    severity?: "error" | "warning" | "info";
-    message: string;
-}
-export interface CommandParserMetadata {
-    name: string;
-    confidence: number;
-    fidelity: "exact" | "lossy";
-    compressed: boolean;
-    counts?: Record<string, number>;
-    references?: CommandParserReference[];
-}
-export interface RoutedResultBase {
-    toolStatus: ToolStatus;
-    decisionId: string;
-    preserve: PreserveMode;
-    routing: RoutingDecision;
-    recovery?: RecoveryHint;
-    evidence?: EvidencePacket[];
-}
-export interface RetrievalRoutedResult extends RoutedResultBase {
-    source?: SourceRef;
-}
-export interface CommandRoutedResult extends RoutedResultBase {
-    outputId: string;
-    execution: CommandExecution;
-    summary?: string;
-    importantLines?: ImportantLine[];
-    parser?: CommandParserMetadata;
-}
-export type RoutedResult = RetrievalRoutedResult | CommandRoutedResult;
-export interface LineByteCounts {
-    lines: number;
-    bytes: number;
-}
-export interface CommandOutputPaths {
-    meta: string;
-    stdout: string;
-    stderr: string;
-    combined: string;
-}
-export interface OutputFingerprints {
-    exactSha256: string;
-    normalizedSha256: string;
-    commandFingerprintSha256?: string;
-}
-export interface VaultRecordBase {
-    outputId: string;
-    objectId: string;
-    createdAt: string;
-    paths: {
-        meta: string;
-    };
-    decisionIds: string[];
-    contentHashSha256: string;
-    fingerprints?: OutputFingerprints;
-    retention?: VaultRetentionPolicy;
-    expiresAt?: string;
-}
-export interface CommandOutputRecord extends VaultRecordBase {
-    kind: "command";
-    command: string | readonly string[];
-    executionStatus: ExecutionStatus;
-    exitCode: number | null;
-    paths: CommandOutputPaths;
-    lineCounts: {
-        stdout: number;
-        stderr: number;
-        combined: number;
-    };
-    byteCounts: {
-        stdout: number;
-        stderr: number;
-        combined: number;
-    };
-    hashes: {
-        stdoutSha256?: string;
-        stderrSha256?: string;
-        combinedSha256?: string;
-    };
-    fingerprints: OutputFingerprints & {
-        commandFingerprintSha256: string;
-    };
-    cwd?: string;
-    durationMs?: number;
-}
-export interface TextOutputRecord extends VaultRecordBase {
-    kind: "text";
-    sourceKind: "native" | "mcp" | "fetch" | "other";
-    paths: {
-        meta: string;
-        raw: string;
-    };
-    lineCounts: {
-        raw: number;
-    };
-    byteCounts: {
-        raw: number;
-    };
-    hashes: {
-        rawSha256?: string;
-    };
-    fingerprints: OutputFingerprints;
-}
-export interface RepoFileReferenceRecord extends VaultRecordBase {
-    kind: "repo-file";
-    path: string;
-    paths: {
-        meta: string;
-    };
-    hashSha256?: string;
-}
-export type VaultRecord = CommandOutputRecord | TextOutputRecord | RepoFileReferenceRecord;
-export interface SessionIndexEntry {
-    outputId: string;
-    objectId: string;
-    kind: VaultRecord["kind"];
-    createdAt: string;
-    executionStatus?: ExecutionStatus;
-    fingerprints?: OutputFingerprints;
-}
-export interface VaultSessionIndex {
-    version: 1;
-    sessionId: string;
-    createdAt: string;
-    updatedAt: string;
-    outputs: string[];
-    records: Record<string, SessionIndexEntry>;
-    successful: string[];
-    failed: string[];
-    timedOut: string[];
-    cancelled: string[];
-}
-export interface DecisionRecord {
-    decisionId: string;
-    createdAt: string;
-    route: RouteKind;
-    preserve: PreserveMode;
-    reason: string;
-    source?: SourceRef;
-    outputId?: string;
-    evidenceIds?: string[];
-}
-export interface RouterThresholds {
-    largeOutputBytes: number;
-    largeOutputLines: number;
-}
-export type VaultRetentionPolicy = {
-    strategy: "ttl";
-    ttlDays: number;
-} | {
-    strategy: "manual";
-};
-export interface RouterVaultConfig {
-    root: string;
-    retention?: VaultRetentionPolicy;
-}
-export interface RouterHints {
-    generatedPathGlobs?: string[];
-    noisyCommandPatterns?: string[];
-}
-export interface RouterConfig {
-    postToolRouting: PostToolRoutingMode;
-    thresholds: RouterThresholds;
-    vault: RouterVaultConfig;
-    hints?: RouterHints;
-}

package/plugins/freeflow/router/dist/types.js

@@ -1,9 +0,0 @@
-export const PRESERVE_MODES = ["summary", "important", "full"];
-export const RETRIEVAL_ACTIONS = ["query", "locate", "retrieve", "expand", "explain"];
-export const TOOL_STATUSES = ["ok", "error"];
-export const EXECUTION_STATUSES = ["success", "failed", "timed_out", "cancelled"];
-export const ROUTING_STATUSES = ["routed", "passed_through", "partial", "failed"];
-export const ROUTE_KINDS = ["retrieve", "run", "safety-net", "pass-through"];
-export const EVIDENCE_WINDOWS = ["exact", "small", "lines_30", "lines_80", "section", "full"];
-export const OUTPUT_STREAMS = ["stdout", "stderr", "combined", "raw"];
-export const POST_TOOL_ROUTING_MODES = ["off", "safety-net", "strict"];

package/plugins/freeflow/skills/output-router/SKILL.md

@@ -1,69 +0,0 @@
----
-name: output-router
-description: Use when choosing between native tools and Freeflow routed tools, retrieving repo/vault evidence, running likely-large or noisy commands, recovering vaulted output, configuring outputRouter, or handling optional native read/bash safety-net routing.
----
-
-# Output Router
-
-Route output deliberately. Native tools stay direct unless explicit config enables the safety net.
-
-## Tool Choice
-
-- Need existing repo or vault information: use `freeflow_retrieve`.
-- Need candidate paths first: use `freeflow_retrieve action=locate`.
-- Need a best evidence packet: use `freeflow_retrieve action=query`.
-- Need exact known repo/vault lines: use `freeflow_retrieve action=retrieve` with `source.path` or `source.kind=vault`, plus `lineRange` when exact lines matter.
-- Need more around prior evidence: use `freeflow_retrieve action=expand`.
-- Need to explain a routed result or vault id: use `freeflow_retrieve action=explain`.
-- Need to run a likely-large or noisy command: use `freeflow_run`.
-- Need a whole known file/artifact: use native read.
-- Need direct shell behavior or expected-small exact output: use native bash.
-- Need to edit files: use native edit/write.
-
-## Hard Rules
-
-- Do not pretend routed output is native output.
-- Do not silently shorten native output. If the safety net transforms it, the result must say Freeflow routed it and include recovery instructions.
-- Capture raw output before transforming it.
-- Treat `preserve: full` as exact fidelity, not unlimited context injection. Over cap, return exact chunks or retrieval pointers.
-- Freeflow mode changes guidance strength only. It must not enable `postToolRouting`.
-- Keep `toolStatus`, `execution.status`, and `routing.status` separate.
-
-## Safety Policy
-
-Read `references/safety-policy.md` before changing routing policy, reviewing router behavior, or routing exactness-sensitive output.
-
-## Recovery Pattern
-
-For routed command or native safety-net output, recover exact text with:
-
-```json
-{
-  "action": "retrieve",
-  "source": { "kind": "vault", "outputId": "ffout_...", "stream": "stdout|stderr|combined|raw" },
-  "lineRange": { "start": 1, "end": 20 },
-  "preserve": "full"
-}
-```
-
-Use `query` first when the needed lines are unknown. Use `expand` when a previous evidence packet is too narrow.
-
-## Config
-
-The router works with built-in defaults. Persist `outputRouter` config only when explicitly requested; `setup-freeflow` owns repo setup/config changes.
-
-Supported repo keys are `postToolRouting`, `largeOutputBytes`, `largeOutputLines`, `vaultRoot`, `vaultRetentionDays`, `generatedPaths`, and `noisyCommandHints`.
-
-`outputRouter.postToolRouting` controls native read/bash safety-net routing:
-
-- `off`: native outputs pass through unchanged.
-- `safety-net`: large/noisy native read/bash output may be vaulted and labeled.
-- `strict`: reserved for stronger future guards; do not invent blocking behavior.
-
-Rules:
-
-- Minimal setup stays only `defaultMode`.
-- Do not dump defaults or create an empty `outputRouter` object.
-- `generatedPaths` affects broad scans only; explicit path retrieval remains available.
-- Freeflow mode changes guidance strength only. It must not enable `postToolRouting`.
-- Invalid config must fall back safely with a warning.

package/plugins/freeflow/skills/output-router/references/safety-policy.md

@@ -1,33 +0,0 @@
-# Output Router Safety Policy
-
-Use this reference for exactness-sensitive output routing.
-
-## Main Rule
-
-Do not silently summarize or compress exactness-sensitive output.
-
-Exactness-sensitive output includes:
-
-- user-requested exact/full output,
-- small outputs,
-- verification output needed for completion claims,
-- failure evidence needed for diagnosis,
-- source-truth conflict evidence,
-- security, privacy, billing, data-loss, or public API evidence,
-- anything marked `preserve: full`.
-
-## Required Behavior
-
-- Capture raw evidence before transformation whenever output is routed.
-- Label every transformed native result as Freeflow-routed output.
-- Include an `outputId` and exact recovery instructions for routed output.
-- Preserve exact failure and verification evidence lines; do not paraphrase them.
-- Pass small native outputs through unchanged.
-- For huge exactness-sensitive output, use vaulting and exact chunk retrieval instead of lossy summarization.
-- If post-tool safety-net routing fails, fail open: return the native output unchanged when possible and include a warning.
-
-## Non-Goals
-
-- This policy does not enable post-tool routing by itself.
-- This policy does not authorize model-assisted summarization inside the router runtime.
-- This policy does not require existing Freeflow skills to depend on the router runtime.

package/plugins/freeflow/skills/research/LANGUAGE.md

@@ -1,61 +0,0 @@
-# Research Language
-
-Use the same language as architecture review so early research shapes the codebase with the same concepts later used to review it.
-
-## Terms
-
-**Module**
-The thing being understood, built, or reshaped. It can be a feature, flow, artifact, repo area, package, class, function, or future slice of code.
-
-**Interface**
-Everything a user, caller, or future agent must know to use or continue the module correctly: names, inputs, invariants, ordering, error modes, ownership, and source truth.
-
-**Implementation**
-The details that can stay hidden behind the interface. Research should decide what callers must know before exposing implementation detail.
-
-**Depth**
-Leverage at the interface. Deep research makes the next spec, plan, or module simpler to use. Shallow research pushes coordination into the user, callers, or future agents.
-
-**Seam**
-Where behavior, ownership, or variation can change without rewriting surrounding work. A seam can be code, artifact, process, owner, or dependency shaped.
-
-**Adapter**
-A concrete thing satisfying an interface at a seam. Use this when something actually varies across the seam; do not invent adapters for ceremony.
-
-**Leverage**
-What one question, decision, or interface unlocks for future work.
-
-**Locality**
-Where evidence, decisions, tests, and changes should concentrate so future work can find them.
-
-## Deletion Tests
-
-Question deletion test:
-
-```text
-If I do not ask this, does downstream complexity spread?
-```
-
-Decision deletion test:
-
-```text
-If this is not captured, will future work rediscover or contradict it?
-```
-
-Module deletion test:
-
-```text
-If this module disappears, does complexity vanish or spread across callers?
-```
-
-## Research Use
-
-Use domain language from `CONTEXT.md`, existing docs, tests, and code. Do not invent polished names before evidence supports them.
-
-Name the outside first: what should users, callers, or future agents need to know? Then decide which implementation details can stay hidden.
-
-A good research pass should make later architecture review ask:
-
-```text
-Did we build the deep module we shaped here?
-```

package/plugins/freeflow/skills/research/SKILL.md

@@ -1,128 +0,0 @@
----
-name: research
-description: Use when shaping an idea, feature, architecture direction, vague task, or consequential question before spec, plan, build, or durable memory. Use when evidence, brainstorming, targeted questions, and decision checkpointing need to interleave.
----
-
-# Research
-
-Research is the discovery loop before action: evidence-guided back-and-forth that finds high-leverage decisions and ends in a checkpoint.
-
-For short-lived work, the checkpoint can stay in chat. When it must guide later work, save it in the narrowest owning artifact: spec, plan, handoff, decision note, ADR, or domain memory.
-
-Goal: enough evidence and shared understanding to checkpoint the current direction and route to spec, plan, more research, durable memory, build, or stop without inventing product, domain, scope, public API, security, privacy, billing, data-loss, compatibility, or architecture decisions.
-
-## Language
-
-Use the same architecture language when shaping work. Read `LANGUAGE.md` when the research needs deeper language mapping or the checkpoint will shape architecture:
-
-- **Module** — the thing being understood, built, or reshaped; it has an **interface** and an **implementation**.
-- **Interface** — what users, callers, or future agents must know to use or continue the work correctly.
-- **Implementation** — the details that can stay hidden behind the interface.
-- **Depth** — leverage at the interface. **Deep** means a small interface carries a lot of useful behavior. **Shallow** means the user, caller, or future agent must coordinate too many details.
-- **Seam** — where behavior, ownership, or variation can change without rewriting the surrounding work.
-- **Adapter** — a concrete thing satisfying an interface at a seam.
-- **Leverage** — how much future work one question, decision, or interface unlocks.
-- **Locality** — keeping evidence, decisions, tests, and changes where future work can find them.
-
-Use the **deletion test** on questions, decisions, and proposed modules: if skipping it makes complexity spread downstream, it matters. If skipping it makes complexity vanish, it was ceremony.
-
-## Loop
-
-1. Identify the target: repo area, artifact, URL, product, model, package, paper, issue, or idea. If multiple plausible targets would change research, ask for the source.
-2. Inspect the smallest evidence that can answer the current question: code, tests, docs, ADRs, specs, logs, issues, provided context, or current external sources.
-3. Explain the current understanding in plain language.
-4. Ask one path-changing question when the answer would change the next route.
-5. Let the user challenge, counter-question, or go deeper. Treat that as research input, not interruption.
-6. Refresh evidence when new claims, conflicts, or branches appear.
-7. Track decisions as settled, tentative, or open.
-8. Stop when remaining ambiguity would not change the next artifact or action.
-
-Research may move through evidence, brainstorming, targeted questioning, and checkpointing in any order. Do not force a fixed sequence when the evidence or conversation needs a loop.
-
-## Question Discipline
-
-Prefer deeper questions over more questions. Ask as many as the situation needs, but each question should earn its place: a good question collapses branches; a shallow question collects approvals.
-
-Before asking, run the question deletion test:
-
-```text
-If I do not ask this, does downstream complexity spread?
-```
-
-If no, skip it.
-
-Bad question:
-
-```text
-Should the button be blue or green?
-```
-
-when the feature purpose is still unclear.
-
-Good question:
-
-```text
-Is this for one workflow or many workflows?
-```
-
-because it changes the module interface, spec shape, and test surface.
-
-Long question chains are a failure mode, not diligence. Do not answer pressure for "every question" or "25-50 questions" by dumping a long questionnaire. That creates shallow approvals.
-
-Do not turn recommendations into an approval script. Recommendations should clarify tradeoffs, not make it easy to rubber-stamp many decisions. Give the recommendation when useful, then wait when the choice is user-owned.
-
-Instead of a long questionnaire: inspect evidence, name the decision tree, group lower-level unknowns, and ask the first high-leverage question that changes the next route. Continue in later turns as needed.
-
-After a few path-changing questions, or whenever the user introduces a new claim, inspect evidence, summarize, or checkpoint before asking more.
-
-## Decision Discipline
-
-Read `ARTIFACT-DESTINATIONS.md` when a checkpoint or decision must survive beyond chat and the owning destination is not obvious.
-
-Not every answer is durable. Keep a lightweight ledger:
-
-- **Settled** — explicit user decision or evidence-backed fact.
-- **Tentative** — useful working assumption, not authority.
-- **Open** — unresolved question that can change the next route.
-
-Persist a decision only when absence would make future work rediscover or contradict it.
-
-Put durable decisions where they belong:
-
-- Domain term or meaning -> existing glossary, `CONTEXT.md`, or domain doc.
-- Feature behavior, scope, or acceptance -> spec.
-- Future implementation path -> plan.
-- Immediate continuation state -> handoff.
-- Hard-to-reverse, surprising tradeoff chosen from alternatives -> ADR.
-- No durable value -> leave it in chat.
-
-If the destination is missing or ambiguous, ask before writing.
-
-## Stop Conditions
-
-Stop and ask the user when research reveals a user-owned decision, source-of-truth conflict, path conflict, material method substitution, or ambiguous artifact destination.
-
-Do not write implementation files from research.
-
-Write specs, plans, ADRs, handoffs, or decision notes only when the user asks or the checkpoint must guide later work.
-
-Do not leave research by silently jumping to spec, plan, or build. Close with a checkpoint when consequential direction changed.
-
-## Checkpoint Shape
-
-Read `CHECKPOINTS.md` when saving a checkpoint or choosing chat versus artifact.
-
-Use this shape when ending a research pass or routing forward. Save it in the owning artifact when it must survive beyond chat. Omit sections that do not apply.
-
-```text
-Question / goal: ...
-Evidence: ...
-Current understanding: ...
-Settled: ...
-Tentative: ...
-Open: ...
-Recommendation: ...
-Next: Forward | Backward | Branch | Stop — ...
-```
-
-`Next:` is routing, not permission to create the next artifact.

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

@@ -1,52 +0,0 @@
-# Output Router Setup
-
-Use this only when setup explicitly asks for output-router repo config, generated-path hints, native safety-net routing, vault settings, or output thresholds.
-
-## Defaults
-
-- The output router has built-in defaults. A repo does not need `outputRouter` config to use it.
-- Minimal `/setup-freeflow` must still write only `defaultMode`.
-- Do not ask every setup user about router config.
-- Do not create a separate `setup-output-router` skill.
-
-If the user says only “set up the output router” with no requested knobs, say the router works with built-in defaults and ask which optional config they want persisted. Recommend no repo config unless they need a repo-specific hint or safety-net behavior.
-
-## Config Keys
-
-Write only keys the user explicitly requests. Do not dump all defaults and do not create an empty `outputRouter` object.
-
-Supported repo config keys:
-
-```json
-{
-  "defaultMode": "workflow",
-  "outputRouter": {
-    "postToolRouting": "off",
-    "largeOutputBytes": 64000,
-    "largeOutputLines": 1000,
-    "vaultRoot": "~/.cache/freeflow-router/vault",
-    "vaultRetentionDays": 7,
-    "generatedPaths": ["graphify-out/**"],
-    "noisyCommandHints": ["npm test"]
-  }
-}
-```
-
-Rules:
-
-- `postToolRouting` defaults to `off`. Use `safety-net` only when explicitly requested. Treat `strict` as reserved; ask before writing it.
-- `largeOutputBytes`, `largeOutputLines`, and `vaultRetentionDays` must be positive integers.
-- `vaultRoot` must be a non-empty string.
-- `generatedPaths` are broad-scan generated-path hints. Explicit file or directory retrieval must remain available.
-- `noisyCommandHints` is parsed as hint config. Do not add it unless the user explicitly asks for command-pattern hints.
-
-## Verify
-
-After writing optional router config:
-
-- JSON parses.
-- `defaultMode` is valid.
-- `outputRouter` contains only requested keys.
-- Invalid router values are not written.
-- Native safety-net routing is not enabled unless explicitly requested.
-- No repo-local hooks, skill files, setup-output-router skill, or docs inventories were created.