@hassangameryt/freeflow 0.7.3 → 0.9.0

package/pi-extension/tests/settings/settings-tui.test.js

@@ -1,243 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-
-import { CURSOR_MARKER, visibleWidth } from "@earendil-works/pi-tui";
-
-import { PiSettingsComponent } from "../../dist/settings/settings-tui.js";
-
-const theme = {
-  fg(_color, text) {
-    return text;
-  },
-  bold(text) {
-    return text;
-  },
-};
-
-function deferred() {
-  let resolve;
-  let reject;
-  const promise = new Promise((resolvePromise, rejectPromise) => {
-    resolve = resolvePromise;
-    reject = rejectPromise;
-  });
-  return { promise, resolve, reject };
-}
-
-function createComponent(entries, options = {}) {
-  const notifications = [];
-  let closed = false;
-  const component = new PiSettingsComponent({
-    title: options.title ?? "Test Settings",
-    entries,
-    theme: options.theme ?? theme,
-    requestRender() {},
-    notify(message, level) {
-      notifications.push({ message, level });
-    },
-    done() {
-      closed = true;
-    },
-  });
-  return { component, notifications, isClosed: () => closed };
-}
-
-test("Pi settings publish values only after persistence and block concurrent edits", async () => {
-  let current = "disabled";
-  let commits = 0;
-  const write = deferred();
-  const entry = {
-    id: "feature.enabled",
-    label: "Feature",
-    description: "Enable the feature.",
-    currentValue: () => current,
-    inactive: () => false,
-    currentChoiceKey: () => (current === "enabled" ? "true" : "false"),
-    choices: [
-      { key: "true", value: true, label: "enabled" },
-      { key: "false", value: false, label: "disabled" },
-    ],
-    async commit() {
-      commits += 1;
-      await write.promise;
-      current = "enabled";
-      return { changed: true, reloadRequired: true };
-    },
-  };
-  const { component } = createComponent([entry]);
-
-  component.handleInput("\r");
-  component.handleInput("\u001b[A");
-  component.handleInput("\r");
-  component.handleInput("\r");
-
-  assert.equal(commits, 1);
-  assert.equal(current, "disabled");
-  write.resolve();
-  await component.waitForWrites();
-  assert.equal(current, "enabled");
-  assert.match(component.render(80).join("\n"), /Feature\s+enabled/);
-  assert.deepEqual(component.sessionResult(), { changed: true, configChanged: true, failed: false });
-});
-
-test("Pi settings retain the persisted value when a write fails", async () => {
-  const current = "disabled";
-  const entry = {
-    id: "feature.enabled",
-    label: "Feature",
-    description: "Enable the feature.",
-    currentValue: () => current,
-    inactive: () => false,
-    currentChoiceKey: () => "false",
-    choices: [
-      { key: "true", value: true, label: "enabled" },
-      { key: "false", value: false, label: "disabled" },
-    ],
-    async commit() {
-      throw new Error("disk unavailable");
-    },
-  };
-  const { component, notifications } = createComponent([entry]);
-
-  component.handleInput("\r");
-  component.handleInput("\u001b[A");
-  component.handleInput("\r");
-  await component.waitForWrites();
-  component.handleInput("\u001b");
-
-  assert.equal(current, "disabled");
-  assert.match(component.render(80).join("\n"), /Feature\s+disabled/);
-  assert.deepEqual(component.sessionResult(), { changed: false, configChanged: false, failed: true });
-  assert.deepEqual(notifications, [{ message: "Write failed: disk unavailable", level: "error" }]);
-});
-
-test("Pi settings delegate paste, cursor, grapheme, and IME behavior to Input", async () => {
-  let current = "";
-  const entry = {
-    id: "feature.label",
-    label: "Label",
-    description: "Unicode label.",
-    currentValue: () => current,
-    inactive: () => false,
-    edit: {
-      initialValue: () => current,
-      parse: (text) => text,
-    },
-    async commit(value) {
-      current = value;
-      return { changed: true, reloadRequired: true };
-    },
-  };
-  const { component } = createComponent([entry]);
-  component.focused = true;
-
-  component.handleInput("\r");
-  assert.ok(component.render(40).join("\n").includes(CURSOR_MARKER));
-  component.handleInput("\u001b[200~ab🙂\u001b[201~");
-  component.handleInput("\u001b[D");
-  component.handleInput("\u007f");
-  component.handleInput("界");
-  component.handleInput("\r");
-  await component.waitForWrites();
-
-  assert.equal(current, "a界🙂");
-});
-
-test("Pi settings start value editing at the end of the existing value", async () => {
-  let current = "abc";
-  const entry = {
-    id: "feature.label",
-    label: "Label",
-    description: "Editable label.",
-    currentValue: () => current,
-    inactive: () => false,
-    edit: {
-      initialValue: () => current,
-      parse: (text) => text,
-    },
-    async commit(value) {
-      current = value;
-      return { changed: true, reloadRequired: true };
-    },
-  };
-  const { component } = createComponent([entry]);
-
-  component.handleInput("\r");
-  component.handleInput("X");
-  component.handleInput("\r");
-  await component.waitForWrites();
-
-  assert.equal(current, "abcX");
-});
-
-test("Pi settings keep typed input open when parsing fails", () => {
-  let commits = 0;
-  const entry = {
-    id: "feature.limit",
-    label: "Limit",
-    description: "Positive integer.",
-    currentValue: () => "1",
-    inactive: () => false,
-    edit: {
-      initialValue: () => "",
-      parse(text) {
-        const value = Number(text);
-        if (!Number.isInteger(value) || value <= 0) throw new Error("expected a positive integer");
-        return value;
-      },
-    },
-    async commit() {
-      commits += 1;
-      return { changed: true, reloadRequired: true };
-    },
-  };
-  const { component } = createComponent([entry]);
-
-  component.handleInput("\r");
-  component.handleInput("invalid");
-  component.handleInput("\r");
-
-  assert.equal(commits, 0);
-  assert.match(component.render(60).join("\n"), /Invalid value: expected a positive integer/);
-});
-
-test("Pi settings search accepts bracketed paste", () => {
-  const entries = ["Alpha", "Beta"].map((label) => ({
-    id: label.toLowerCase(),
-    label,
-    description: `${label} setting`,
-    currentValue: () => "off",
-    inactive: () => true,
-  }));
-  const { component } = createComponent(entries);
-
-  component.handleInput("\u001b[200~Beta\u001b[201~");
-  const rendered = component.render(60).join("\n");
-  assert.match(rendered, /Beta/);
-  assert.doesNotMatch(rendered, /Alpha/);
-});
-
-test("Pi settings keep ANSI and Unicode rendering within terminal width", () => {
-  const ansiTheme = {
-    fg(_color, text) {
-      return `\u001b[36m${text}\u001b[0m`;
-    },
-    bold(text) {
-      return `\u001b[1m${text}\u001b[22m`;
-    },
-  };
-  const entry = {
-    id: "unicode",
-    label: "設定🙂",
-    description: "幅の広い Unicode description with several words.",
-    currentValue: () => "有効界",
-    inactive: () => true,
-  };
-  const { component } = createComponent([entry], { title: "設定パネル", theme: ansiTheme });
-
-  for (const width of [12, 20, 40]) {
-    for (const line of component.render(width)) {
-      assert.ok(visibleWidth(line) <= width, `line width ${visibleWidth(line)} exceeds ${width}: ${line}`);
-    }
-  }
-});

package/pi-extension/tsconfig.json

@@ -1,16 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "rootDir": "src",
-    "outDir": "dist",
-    "declaration": false,
-    "sourceMap": false,
-    "strict": false,
-    "noEmitOnError": true,
-    "skipLibCheck": true,
-    "types": ["node"]
-  },
-  "include": ["src/**/*.ts"]
-}

package/plugin.json

@@ -1,33 +0,0 @@
-{
-  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
-  "name": "freeflow",
-  "version": "0.7.3",
-  "description": "Feedback-based control system for coding agents.",
-  "author": {
-    "name": "Hassan Mohiddin"
-  },
-  "homepage": "https://github.com/hassan-mohiddin/freeflow",
-  "repository": "https://github.com/hassan-mohiddin/freeflow",
-  "license": "MIT",
-  "keywords": [
-    "workflow",
-    "skills",
-    "agents",
-    "feedback-loop",
-    "task-memory",
-    "planning",
-    "verification",
-    "review",
-    "agent-plugins",
-    "gemini",
-    "copilot",
-    "vscode",
-    "cursor",
-    "kiro",
-    "opencode",
-    "hermes"
-  ],
-  "extensions": {
-    "com.github.copilot": {}
-  }
-}

package/runtime/prompts/context-virtualization.md

@@ -1,3 +0,0 @@
-## Context Virtualization Cue
-
-After broad or noisy tool evidence has been safely narrowed, exhausted, or crossed a meaningful activity boundary, use Context Virtualization to keep necessary evidence active and archive residue. Do not archive governing context or exact evidence still needed by current work.

package/runtime/prompts/conversation-history.md

@@ -1,3 +0,0 @@
-## Conversation History Cue
-
-When the next decision requires exact prior conversation evidence absent from active context, use Conversation History instead of reconstructing it from memory.

package/skills/action-selection/SKILL.md

@@ -1,100 +0,0 @@
----
-name: "action-selection"
-description: "Use when choosing or bounding an environment interaction, especially when the needed context, target, observer, or scope is uncertain, output may be broad, or recent actions have not advanced the current question."
----
-
-# Action Selection
-
-Choose one covered environment interaction that advances the current question or result, observe what it actually changes, and return the changed evidence to the current owner.
-
-An environment interaction is a bounded tool-mediated observation or effect. A current activity can need several interactions; a tool call is not a task phase, Slice, or reason to change ownership.
-
-Action Selection does not decide the user's outcome, work agreement, execution method, Slice, checkpoint, or Workflow route. It serves the owner responsible for those judgments and cannot accept the whole result.
-
-## Identify The Immediate Need
-
-Before touching the environment, identify what this interaction must answer or produce. Reuse evidence already available and current enough for that purpose.
-
-The need may be:
-
-- understanding the required outcome or reported symptom;
-- establishing the mechanism, dependency, or approach;
-- applying an understood change;
-- observing whether a claim holds;
-- reconstructing missing continuation state.
-
-Use these purposes to focus the action, not to print phase labels or restart planning. Ask: what is the minimum sufficient context or effect for this next decision? Minimum means sufficient, not merely short.
-
-Do not collect information because it may be useful later. Do not confuse the existence of a source or reference with having its necessary contents available.
-
-## Take The Fast Path When The Action Is Known
-
-Use the direct tool when the target, purpose, scope, and observing boundary are already supported and the action is covered, mechanical, and directly verifiable.
-
-Examples include reading a known function or range, applying an exact selected edit, running an already-chosen focused check, or inspecting its resulting diff.
-
-Do not manufacture alternative tools or repeat the action-selection method for an obvious continuation. A command being easy to run does not make its target or hypothesis well chosen.
-
-## Compare Only Meaningful Alternatives
-
-When the target, observer, or scope is uncertain, likely output is broad, the action is destructive, expensive, or difficult to recover, or recent work has stalled:
-
-1. Identify the fact or effect the current owner needs.
-2. Check whether existing evidence already supplies it.
-3. Consider only a few materially different ways to obtain it.
-4. Reject unchanged rereads, equivalent searches, eliminated approaches, and information without a current use.
-5. Prefer the most direct action that distinguishes the plausible answers.
-6. Among equally useful actions, prefer proportionate output, side effects, context residue, and recovery cost.
-7. Execute the selected action once; choose the next interaction from its actual result.
-
-Keep this comparison internal unless a user-owned choice is exposed. Do not emit candidate tables, numeric scores, simulated results, or a speculative sequence of tool calls.
-
-A good observation can change the owner's belief or next action whether it supports or contradicts the leading explanation. An exact mutation can advance a settled result without testing a new hypothesis.
-
-## Bound The Tool And Its Output
-
-Use the simplest operation that can establish the required relationship:
-
-- known file, symbol, artifact, or range -> focused read or operation;
-- ownership, caller, or dependency question -> structured relationship query where available;
-- literal or generated reference -> bounded content search;
-- behavioral claim -> the owner's selected test, observer, or reproduction;
-- understood effect -> narrow direct mutation;
-- unknown location -> bounded discovery, then narrow from its result.
-
-Choose scope before execution: directory, source kind, pattern, range, test target, time window, result count, fields, affected state, or recovery scope. Exclude unrelated history, generated output, and dependencies unless the current question needs them.
-
-Use a location or count query before requesting all matching bodies when volume is uncertain. Prefer bounded output with an accessible full result. Truncation or a sampled result must remain explicit; it is not proof that omitted matches are irrelevant or that a search was exhaustive.
-
-Context cost includes instructions, results, repeated material, and the capacity still needed for implementation, checking, correction, and continuation. Use host-supplied usage when available; do not invent token measurements or treat the provider maximum as a promise that a unit will fit.
-
-The owner selects the work horizon. Return unexpectedly large context needs to it instead of reading the entire dependency tree or silently shrinking acceptance.
-
-## Observe Before Continuing
-
-After the interaction, determine:
-
-- what actually ran or was returned;
-- what changed in evidence, hypotheses, implementation, or task state;
-- whether the intended question was answered or effect produced;
-- which uncertainty, partial effect, or contradictory observation remains.
-
-New content is not automatically useful evidence. A successful read is not understanding; a successful write is not correctness; a passing tool result is not proof of the wider claim. Return evidence to its owner for interpretation at the required boundary.
-
-When a read settles the question, stop that investigation. Ordinary local continuation may be obvious; an invalidated implementation premise needs reassessment before dependent effects.
-
-If the result did not advance the question, do not repeat it using synonyms, nearby files, a wider equivalent search, or another tool. Change the question or observer, or report the missing evidence.
-
-When two or more recent interactions have not materially changed understanding, advanced the covered effect, or supported a new branch, read [Trajectory Stalls](references/trajectory-stalls.md) before another interaction.
-
-## Return Without Expanding The Work
-
-Return the observation and material state change to the same current owner. Action Selection does not transfer compute profiles, accept an implementation, or create authority.
-
-When an experiment reveals a new prerequisite, report what it blocks: the current observer, chosen approach, or required outcome. Do not convert a blocked tool or prototype into permission to build a subsystem.
-
-Use [Diagnose Failure](../diagnose-failure/SKILL.md) for unexplained repeated failures. Return changed authority, scope, ownership, direction, evidence boundary, or stop conditions to [Workflow](../workflow/SKILL.md).
-
-Stop when the immediate need is satisfied, the active contract requires return, no useful covered interaction remains, or another activity must settle the next choice. Reuse adequate evidence instead of generating new calls to justify completion.
-
-The goal is fewer low-value interactions while preserving sufficient evidence and the agreed outcome—not fewer calls at any cost.

package/skills/action-selection/references/trajectory-stalls.md

@@ -1,71 +0,0 @@
-# Trajectory Stalls
-
-Read this when two or more recent environment interactions have not materially changed the current question, advanced the covered effect, or supported a new branch.
-
-A stall is evidence that the current interaction policy is no longer producing useful progress. It does not prove that the task is difficult, the design is wrong, or another model is required.
-
-## Recognize A Stall
-
-Common stall patterns include:
-
-- repeating searches with synonymous terms;
-- rereading unchanged sources without a new question;
-- rerunning the same check against unchanged state;
-- widening search breadth without narrowing the hypothesis;
-- collecting new output that does not change any belief or decision;
-- revisiting a path already eliminated by supported evidence;
-- changing hypotheses without a new observation;
-- alternating edits, failures, and reversions without a supported cause;
-- following each newly mentioned symbol or file away from the accepted outcome;
-- continuing because interaction began rather than because evidence supports another step.
-
-The following are not automatically stalls:
-
-- several distinct mechanical interactions required by one exact covered effect;
-- rerunning evidence after relevant state changed;
-- a long-running operation that is still producing the selected result;
-- checking a broader boundary after a focused result when that boundary was already required;
-- returning through several files along one supported call or dependency path.
-
-Judge progress by changed understanding, produced effects, or a newly supported branch—not raw action count.
-
-## Stop Before Another Similar Interaction
-
-Before another environment action:
-
-1. restate the unresolved question or exact covered effect;
-2. identify what the recent interactions established;
-3. identify which paths or hypotheses they eliminated;
-4. state why the interactions failed to change the decision;
-5. determine whether another observer class could discriminate where the previous one could not.
-
-Different observer classes may include:
-
-- structural navigation instead of text search;
-- caller or dependency tracing instead of concept search;
-- runtime behavior instead of source inspection;
-- source inspection instead of another runtime rerun;
-- exact artifact comparison instead of summary output;
-- a minimized reproduction instead of another speculative edit.
-
-Changing syntax, keywords, directories, or tools without changing the evidence relationship is not a different observer class.
-
-## Recover With One Discriminating Action
-
-When a different covered observer can answer the unresolved question:
-
-1. name what result would support or contradict the leading path;
-2. bound one interaction;
-3. execute it once;
-4. return its observation to the current owner.
-
-Do not compensate for a stall by generating a long plan, exploring every remaining path, or broadening the task.
-
-When no covered interaction can discriminate:
-
-- return the smallest missing evidence to the current owner;
-- return a changed authority, scope, ownership, direction, or required observing boundary to [Workflow](../../workflow/SKILL.md);
-- use [Diagnose Failure](../../diagnose-failure/SKILL.md) when repeated failure lacks a supported cause;
-- stop when the active execution contract requires return.
-
-A stall recovery succeeds when the decision surface changes or the absence of a safe useful interaction becomes explicit. It does not require another tool call.

package/skills/bypass/SKILL.md

@@ -1,153 +0,0 @@
----
-name: bypass
-description: "Use when the user explicitly asks to skip or reduce optional workflow pressure for the next authorized activity or the current task."
----
-
-# Bypass
-
-Reduce explicitly selected optional workflow pressure without changing authority, accepted intent, the current owner, execution method, evidence semantics, selected checkpoints, mode, active capability protocols, or host controls.
-
-Bypass is a user-controlled pressure modifier. It does not authorize the underlying work and does not perform that work itself.
-
-**Optional pressure** is a workflow step whose removal does not weaken accepted intent, material risk control, required evidence, a selected checkpoint, or safe continuation.
-
-## Interpret The Request Narrowly
-
-Use Bypass only when the user explicitly asks to skip or reduce workflow pressure. Do not infer bypass from urgency, frustration, brevity, “just do it,” or a preference for concise responses.
-
-Establish:
-
-- the already-authorized bounded activity;
-- the specific pressure the user wants removed;
-- whether the requested scope is `next` or `task`;
-- the authority, evidence, checkpoints, and stop conditions that remain;
-- when the bypass expires.
-
-A bare `/bypass` means `/bypass next`.
-
-If the same user turn both authorizes an activity and explicitly requests reduced pressure, interpret the whole turn through [Workflow](../workflow/SKILL.md). Bypass may modify that authorized activity; it does not supply its authority.
-
-If no authorized activity exists, return to Workflow and wait. Do not treat bypass as permission to implement, inspect actively, mutate, deliver, commit, or continue.
-
-## Skip Only Optional Pressure
-
-A valid bypass may remove:
-
-- an unnecessary Spec, Plan, or Working Record;
-- extended questioning whose answer would not change the accepted activity;
-- an artifact created only for ceremony;
-- duplicate explanation or status reporting;
-- a proposed but unselected review or checkpoint with no remaining risk purpose;
-- another optional step whose removal does not weaken the supported outcome.
-
-Do not infer that a named artifact, review, check, or checkpoint is optional. Inspect what it protects before removing it.
-
-Freeflow should already avoid unnecessary ceremony. Bypass is an explicit user override when optional pressure was proposed or recommended but was not selected as a required boundary, or would otherwise remain in the route.
-
-## Preserve Non-Bypassable Boundaries
-
-Bypass does not remove or override:
-
-- the user’s authority over product behavior, scope, priorities, public interfaces, compatibility, permissions, security, privacy, billing, data loss, migration direction, deployment, or another hard-to-reverse outcome;
-- conflicts among the request, code, tests, docs, policies, requirements, accepted behavior, or another source of truth;
-- the accepted authority envelope or separately controlled effects;
-- host safety, sandbox, permission, approval, or tool controls;
-- mode boundaries or active capability protocols;
-- the distinction between available evidence and supported claims;
-- required self-review before accepting or reusing a supported result;
-- an accepted Spec, Plan, selected checkpoint, required artifact review, or selected independent review;
-- a stop condition, blocker, or evidence that invalidates the current route.
-
-Material risk still requires the decisions and evidence that address it. A domain label alone does not require ceremony, but bypass cannot erase an observed risk.
-
-Bypass cannot allow an active compute profile to act outside its execution protocol. Use the capability’s own user controls when the user wants to change manual or automatic control, profile behavior, or another capability setting.
-
-## Respect Declined Evidence Without Inventing Support
-
-A user may explicitly decline a test, build, runtime probe, review, or other evidence generation. Respect that instruction unless a higher-priority repository, host, or safety requirement prevents it.
-
-Declining evidence does not make the corresponding claim supported.
-
-When evidence is declined:
-
-- perform only the remaining authorized work that can continue safely;
-- leave the affected claim explicitly unverified;
-- do not accept or reuse the result beyond the remaining evidence boundary;
-- do not cross a checkpoint or dependent boundary that requires the missing evidence;
-- return to Workflow when the expected exit, checkpoint, or safe continuation must change.
-
-A request to skip evidence generation changes what may be claimed. It does not change what the available evidence proves.
-
-## Route Changes Are Not Bypass
-
-Treat the request as a Workflow route change when the user wants to:
-
-- change accepted behavior, scope, effects, or stop conditions;
-- weaken or replace an accepted evidence requirement;
-- cancel or replace a selected checkpoint;
-- revise an accepted Spec or Plan;
-- change mode or an active capability protocol;
-- continue despite contradictory evidence or a source conflict.
-
-An explicit user instruction may authorize the changed route, but Workflow must reconcile its consequences before dependent work continues.
-
-Use [Decision Gate](../decision-gate/SKILL.md) only when one user-owned choice or source conflict remains unresolved.
-
-## Apply The Selected Scope
-
-### Next
-
-`/bypass next` removes one identified optional pressure from the current authorized activity.
-
-The bypass is spent when:
-
-- the selected pressure is skipped;
-- the activity changes;
-- another gate or stop condition appears;
-- the route ends.
-
-Re-check the route immediately after applying it. Do not carry the bypass into another activity by implication.
-
-### Task
-
-`/bypass task` reduces identified optional pressure for the current accepted task.
-
-The task is the accepted request or active Working Record scope—not the repository, session, branch, or future related work.
-
-Name the pressure being reduced when possible. Do not interpret task scope as “ignore all workflow for this task.”
-
-Task scope ends when:
-
-- the task completes or is abandoned;
-- its accepted outcome changes materially;
-- the user withdraws or replaces the bypass;
-- a new task begins.
-
-Reassess new risks, conflicts, evidence requirements, checkpoints, and separately controlled effects inside the task. Task scope does not make them optional.
-
-When an existing Working Record is already authorized for maintenance and the task-scoped bypass must survive context loss, use [Track Work](../track-work/SKILL.md) to preserve its source, exact pressure, scope, and expiry.
-
-The record preserves the user instruction; it does not broaden it. Without durable task memory, do not claim task-scoped bypass survives context loss.
-
-Never convert `next` or `task` scope into permanent, repository-wide, session-wide, or cross-task behavior.
-
-## Return The Modified Route
-
-When the bypass is valid:
-
-1. identify the optional pressure being removed;
-2. apply only the selected scope;
-3. return the reduced-pressure route to the unchanged current owner;
-4. let that owner perform the separately authorized activity;
-5. preserve the same evidence honesty, self-review, and stop conditions;
-6. report what was skipped only when it materially clarifies the result or remaining scope.
-
-Do not narrate internal bypass state on every turn. Speak in ordinary engineering language unless the scope or expiry matters to the user.
-
-When a boundary remains:
-
-1. do not perform the blocked action;
-2. state the boundary the bypass cannot remove;
-3. return to Workflow, Decision Gate, or the relevant current owner.
-
-Bypass ends when the selected optional pressure has been removed, its scope expires, or a non-bypassable boundary requires another route.