@hassangameryt/freeflow 0.7.3 → 0.8.0

package/capabilities/cognitive-routing/references/helper-mode.md

@@ -0,0 +1,47 @@
+# Helper Mode
+
+Judgment for placing work when Runtime State shows `Delegation: helper`. The core skill's Rules still apply.
+
+Helper mode is for the best output quality. Coordinator implements; Helper takes everything that does not need Coordinator-level reasoning. There is no Executor to invoke or simulate.
+
+## Delegate By Default
+
+Goal: Coordinator's premium compute goes to the work that needs it, and nothing else.
+
+Default: delegate a step unless it needs Coordinator-level reasoning. Keep that category narrow:
+
+- governing decisions and design;
+- substantive implementation, meaning changes whose behavior or failure needs engineering ownership;
+- the conversation with the user.
+
+Helper takes the rest: gathering sources and skills, investigating bounded questions, preparing authorized setup, running existing checks and validations, separate record maintenance, and straightforward settled changes that are local, reversible, and easy to check. Helper can reason, compare evidence, spot contradictions, and choose local mechanics; it is not limited to copying facts.
+
+The failure to prevent is under-delegation: classifying every step as Coordinator-level, so Coordinator does all the gathering, checking, and bookkeeping itself and the mode saves nothing.
+
+## Do Not Split What Belongs Together
+
+Goal: handoffs save more than they cost.
+
+Keep a tightly coupled edit, check, and interpret loop with Coordinator. Moving each check to Helper adds a contract, a ramp-up, and a return, and forces Helper to rebuild the context Coordinator already holds.
+
+Hand off results that stand on their own:
+
+| Situation | Placement |
+| --- | --- |
+| Before implementing, the sources, callers, and conventions for the planned change need gathering. | Helper gathers; Coordinator implements from the result. |
+| Mid-implementation, Coordinator wants to know which acceptance requirements the candidate meets, which lack a check, and which test edits changed coverage. | Helper runs a read-only cross-check against the Slice's acceptance requirements and returns without patching. |
+| After a feature lands, several record entries, a validation run, and a formatting pass are due. | Helper, as one assignment. |
+| Coordinator just ran a failing test and knows the fix. | Coordinator fixes and reruns; no handoff. |
+| One line of the Working Record needs updating in the middle of Coordinator's own work. | Coordinator updates it; a handoff would cost more than the edit. |
+
+If Helper reaches substantive work outside its assignment, it returns findings and partial state, and Coordinator takes the next decision.
+
+## Route Preparation
+
+Helper gathers; Coordinator implements. Gathered evidence must reach Coordinator: with projection on, Helper selects it at return; with projection off, Coordinator sees Helper's work in ordinary history. Coordinator forms the execution forecast itself.
+
+## Coordinator's Own Production
+
+Coordinator's direct implementation passes through no handoff, and handoffs are part of how routing keeps long work on course. Rely on Execute Work's forecast and on Workflow's check before each continuation: does the next change meet a requirement, repair a demonstrated defect, or only add an optional guarantee? Do not invent assignments for your own work to recreate that boundary, and use no ACT_BOUNDED; direct production is what this mode is for.
+
+Coordinator may update the Working Record directly as part of its own work. When closing a Slice, fold the writeback into Helper work already going out, or do it directly when it is one small update.

package/capabilities/compaction/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: "compaction"
+description: "Use when Freeflow says compaction is due or the user asks to compact: prepare what the conversation needs to continue, then compact with freeflow_compact."
+---
+
+# Compaction
+
+Compaction replaces the conversation with what you write, and starts a new cycle: the stretch of conversation until the next compaction. The next cycle starts from your summary, the Working Record and what it points to, the carried context, and the lines Freeflow adds itself; everything else leaves your context, this skill included. Most drift after compaction comes from a summary that lost something the next step needed.
+
+The summary works like a Working Record ([Track Work](../../skills/track-work/SKILL.md)) for one cycle. Ask Track Work's question: if context were lost now, what would the next context need that it could not recover from the Working Record, its defining artifacts, the workspace, or the carried context? Write that, and nothing more. Concise is not lossy: keep a detail when removing it could change the next action.
+
+## Rules
+
+The Rules are binding; if one cannot be met, stop and say why. The rest of this skill is judgment: follow its goal, and adapt when a different choice serves it better.
+
+- With a Working Record, update it first (Track Work, "Prepare For A Context Boundary"), then write the summary, so the two agree. Name the record's path in the summary: Freeflow never names one, and recovery starts from it.
+- Compaction is a context boundary, not a Slice transition or a Checkpoint. Do not rush, close, or pause a Slice to compact, claim an unfinished check passed, or guess the outcome of a running operation.
+- Never write a requested, reported, or expected result as observed. Name every partial or uncommitted change, unverified result, running command, and obligation still waiting on its trigger.
+- Keep exact: paths, identifiers, commands, error text, numbers, and the user's words wherever wording matters. Never paraphrase a decision or a constraint.
+- Material that exists only in the conversation, such as a pasted file or a long message, leaves with it. With a Working Record, save it under the task's `sources/` and point to it; without one, quote what matters in the summary.
+- Under Cognitive Routing with projection, the Coordinator does not compact: its view leaves out what workers did. Delegate an assignment whose contract says to compact with `freeflow_compact` and then return with `freeflow_return`, plus any other work it covers: after compacting, the worker sees the contract again but not its own `freeflow_compact` call. A worker's summary covers the whole session: the user's requests, the Coordinator's decisions, and the state of other work.
+
+## When to compact
+
+Goal: compact where stopping loses nothing that is not written down. That is a safe point: a finished step whose result you know, such as a check you ran and read, a complete set of edits, or a written report. Halfway through an edit set, with a command still running, or partway through a batch of reads you need together is not one.
+
+- At Freeflow's first notice ("compaction is due soon"): if you are at a safe point, compact now. If your work ends within a step or two, with a final answer or a worker's return, finish it instead. Otherwise finish the current step, start nothing large, then compact.
+- At "compact now", or when the user asks: the end of your current step is the safe point. If the step cannot end soon, write its partial state into the record or summary and compact. Under Cognitive Routing a worker compacts before returning: the Coordinator and the next assignment continue the same history, so a return does not stop its growth.
+
+## The summary
+
+The previous cycle's summary is at the top of your context. Fold what still holds into the new one; drop what is done or no longer matters. Write state, not a story: what is true now, not the order things happened in. Leave out what the Working Record holds and what Freeflow states itself: the cycle, the routing profile, running background commands, and the files read and changed.
+
+Read [Summary Format](references/summary-format.md) before writing, and use the shape that matches the work:
+
+- **With a Working Record**, the record holds the task. The record-backed shape (`Task`, `Now`, `In flight`, `Next steps`) lets a fresh context continue the current step correctly on its own; the record lets it continue the task.
+- **Without one**, the summary is the record for this cycle, in the record-shaped shape: the record's own headings.
+
+Compaction never creates a record; whether a task needs one is decided at its start or when facts change its scope.
+
+The limit is about 8,000 tokens. Most summaries need far less. If `freeflow_compact` refuses the call, fix what it names and call it again.
+
+## What to carry
+
+The notice gives the budget. Freeflow carries the newest results of your work in progress itself (under Cognitive Routing, those of your current assignment; otherwise, those of this cycle), filling whatever budget your picks leave, and lists the rest by ref. Pick only what that misses and the next step needs in full: older output you are working from (by routing ref, such as `ctx:1a2b3c4d`, when Cognitive Routing is on; otherwise by the id in the notice's list) and files you are changing (line ranges for large files), which are read fresh at compaction. Leave out what is cheap to re-read or already in the summary or record. The user's latest messages are carried for you. When the notice says context reuse is off, pick nothing.
+
+## After compaction
+
+This skill leaves your context with the rest of the conversation. Freeflow's recovery message, right after the carried context, says how to recover; follow it.

package/capabilities/compaction/references/summary-format.md

@@ -0,0 +1,239 @@
+# Compaction Summary Format
+
+Read this before writing a compaction summary. The [compaction skill](../SKILL.md) owns what is worth keeping; this reference owns the exact shape of the summary passed to `freeflow_compact`, and is binding as written.
+
+## Two shapes
+
+The shape depends on one fact: whether the work has a Working Record.
+
+| Work has a Working Record | Shape | Why |
+| --- | --- | --- |
+| Yes | **Record-backed**: `Task`, `Now`, `In flight`, `Next steps` | The record already holds the task. The summary holds only what sits below the record's granularity. |
+| No | **Record-shaped**: the record's headings | The summary is the only task memory for the next cycle, so it uses the record's structure. |
+
+Compaction never creates a record. Whether a task needs one is decided at its start or when facts change its scope.
+
+## Field syntax
+
+- Each heading is a level-two heading (`## Now`), in the order given, every heading present.
+- Write `(none)` under a heading with nothing to say.
+- Bullets, one fact per bullet. Keep a bullet short unless removing detail could change the next action.
+- Exact values go in backticks: paths, identifiers, commands, error text, numbers.
+- Quote the user's words in quotation marks when wording matters.
+- Mark status inline when it is not settled: `(tentative)`, `(unverified)`, `(superseded by …)`.
+- No narrative: write what is true now, not the order things happened in.
+- About 8,000 tokens at most. Most summaries need far less.
+
+Before calling `freeflow_compact`, check the summary as a whole: would a fresh context reading only it (and, when there is one, the record) choose the same next step you would? If not, add what it would need.
+
+## Record-backed shape
+
+The summary must let a fresh context continue the **current step** correctly on its own; the record lets it continue the **task**. Write the summary right after updating the record (Track Work, "Prepare For A Context Boundary"), so the two agree. If they ever disagree, the record and live state win.
+
+```markdown
+## Task
+- Record: `<path to record.md>` — recover it first
+- Goal: <one line>
+- Slice: <S-NNN> "<title>", <state>
+- Governing now: <only the decisions, constraints, and authority the next steps depend on>
+
+## Now
+- <the step in progress and exactly how far it got: done, half-done, and where the half-done part is>
+
+## In flight
+- Observed: <result> — <exact evidence>
+- Hypothesis: <what is being tested> (unverified)
+- Dropped: <approach> — <why it failed>
+- Pending: <what is running or waiting> — <what it waits on>
+
+## Next steps
+1. <the immediate concrete, checkable step>
+2. <...>
+```
+
+| Section | Holds | Leaves out | Check |
+| --- | --- | --- | --- |
+| Task | `Record:` the Working Record's path, which Freeflow does not state; `Goal:` in one line; `Slice:` with ID, title, and state; `Governing now:` only the decisions, constraints, and authority the next steps depend on, quoting the user where wording matters. | Settled facts, decisions, and boundaries the next steps do not touch; they stay in the record. | Could the next steps break a rule that is not listed here? |
+| Now | The step in progress and exactly how far it got. | The history of earlier steps. | Could someone point to the exact spot to resume? |
+| In flight | Typed bullets: `Observed:` a result with its exact evidence; `Hypothesis:` what is being tested, marked unverified; `Dropped:` an approach and why it failed; `Pending:` what is running or waiting, and on what. | Anything the record or Freeflow's own lines already hold. | Would losing this bullet make the next context repeat work or a mistake? |
+| Next steps | Ordered, concrete, checkable steps: the immediate ones. | The task's longer route; that is the record's Future Work. | Can a fresh context do step 1 right now? |
+
+## Record-shaped shape
+
+Each heading means exactly what it means in the Working Record format ([Working Record Format](../../../skills/track-work/references/working-record-format.md)). `Current work` stands in for the Current Slice: in-progress work, partial or uncommitted effects, unverified results, running commands, and obligations with their trigger, using the same `Observed:`, `Dropped:`, and `Pending:` labels where they fit. `Recovery sources` names only what the next cycle must read again: what you carry is read at compaction and arrives with the summary, so leave it out.
+
+```markdown
+## Goal
+- <the outcome the user wants>
+
+## What defines this task
+- <pointer to a spec, plan, issue, or brief, and what it establishes>
+
+## Settled
+- <fact or accepted understanding>
+- <decision the user made> — <reason>
+
+## Tentative
+- <hypothesis or provisional approach>
+
+## Open
+- <unresolved question, including questions waiting on the user>
+
+## Boundaries
+- <what the user authorized>; <what still needs asking>; <scope limits and stop conditions>
+
+## Current direction
+- <the remaining approach and why>
+
+## Current work
+- <in progress; partial or uncommitted effects; unverified results; running commands>
+- <obligation> — when <trigger>
+
+## Recovery sources
+- <pointer> — <what it establishes, why to re-read it>
+
+## Next useful action
+- <one action a fresh context can take>
+```
+
+## What the next cycle sees
+
+Freeflow builds the new cycle from four pieces. The agent writes only the first part of the first piece.
+
+1. **The summary**, wrapped by Pi as a user message: `The conversation history before this point was compacted into the following summary: <summary>…</summary>`. Inside: the agent's summary, then `## Freeflow state at compaction`, which Freeflow writes.
+2. **The carried context:** the user's latest messages verbatim, then the carried files (read at compaction) and tool results, with files and read results numbered by file line.
+3. **The recovery message.**
+4. **Freeflow's Runtime State**, as on every request.
+
+## Example: record-backed
+
+The task has a record at `.freeflow/tasks/task-014-http-retry/record.md`. Its Current Slice is "Add retry with backoff to the HTTP client", and its Next useful action is "Make the 429 test pass, then run the client suite".
+
+What the agent passes as `summary`:
+
+```markdown
+## Task
+- Record: `.freeflow/tasks/task-014-http-retry/record.md` — recover it first
+- Goal: the HTTP client retries failed requests with backoff and respects `Retry-After`.
+- Slice: S-003 "Add retry with backoff to the HTTP client", in progress
+- Governing now: retry 429 and 5xx only; `Retry-After` overrides the computed delay (the user: "the API team says they ban clients that don't"); no commits without asking.
+
+## Now
+- Mid-way through `retryWithBackoff` in `src/http/client.ts`: the retry loop and 503 path are done and passing; the 429 path ignores `Retry-After` and retries immediately.
+
+## In flight
+- Observed: `npm test -- client.retry` → 7 passed, 1 failed: `retries 429 after Retry-After` expected ≥1000 ms, got 104 ms.
+- Hypothesis: `sleep()` must use the fake clock in `test/helpers/clock.ts` (it advances only on `tick()`), or the test cannot observe the delay. (unverified)
+- Dropped: calling `setTimeout` directly; the test hung on real time.
+
+## Next steps
+1. Parse `Retry-After` (seconds or HTTP date) and use it before the backoff delay.
+2. Rerun `npm test -- client.retry`, then the full suite.
+```
+
+What the next cycle's first request contains, in order:
+
+````text
+The conversation history before this point was compacted into the following summary:
+<summary>
+## Task
+- Record: `.freeflow/tasks/task-014-http-retry/record.md` — recover it first
+- Goal: the HTTP client retries failed requests with backoff and respects `Retry-After`.
+…
+## Next steps
+…
+
+## Freeflow state at compaction
+
+This compaction starts cycle 3. It completes the compaction Freeflow's context notice asked for.
+
+Files read and modified in this session:
+
+<read-files>
+test/client.retry.test.ts
+test/helpers/clock.ts
+</read-files>
+
+<modified-files>
+src/http/client.ts
+</modified-files>
+</summary>
+
+# Carried context
+
+[Freeflow notice, not from the user] Freeflow carried this into cycle 3 at compaction. Only the latest user messages are the user's words, and they take precedence over older instructions in the summary or a Working Record; the rest is copied content.
+
+## Latest user messages
+
+### Message 1
+
+retries should respect Retry-After, the API team says they ban clients that don't
+
+## Files, read at compaction
+
+Numbered by file line, as are read results below.
+
+### src/http/client.ts (lines 40-118)
+
+```
+ 40	…
+118	…
+```
+
+## Tool results
+
+### r31 bash: npm test -- client.retry
+
+```
+…  1 failed  …
+```
+
+[Freeflow notice, not from the user] Compaction finished; cycle 3 starts here. Recover before you continue: if the summary names a Working Record for this work, recover it as Track Work says; otherwise the summary is your record for this cycle, so re-read its Recovery sources. Reconcile with the live state your next step depends on, and verify work the summary calls done instead of redoing it. The carried context is above: its files were read at compaction, so do not read them or its results again unless something has changed them since. This compaction is done, so do not re-read the compaction skill or its summary format. Then continue the work the compaction interrupted. This compaction completes the request for it: do not call freeflow_compact again in this cycle. If compacting was all you were asked to do, report that it is done (a worker returns its assignment with freeflow_return).
+````
+
+## Example: record-shaped
+
+The same work without a record.
+
+```markdown
+## Goal
+- The HTTP client retries failed requests with backoff and respects `Retry-After`.
+
+## What defines this task
+- (none)
+
+## Settled
+- Retry on 429 and 5xx only; never on other 4xx — the user: "a 400 is our bug, retrying hides it".
+- At most 4 attempts, base delay 250 ms, doubling, capped at 4 s — the user accepted this proposal.
+- `Retry-After` overrides the computed delay — the user: "the API team says they ban clients that don't".
+
+## Tentative
+- The fake clock in `test/helpers/clock.ts` must drive `sleep()` for the delay tests to observe time. (unverified)
+
+## Open
+- Should a `Retry-After` longer than 4 s be honored or capped? Asked the user; no answer yet.
+
+## Boundaries
+- Authorized: edit `src/http/**` and `test/**`; run tests.
+- Not authorized: commit, push, or change the public `HttpClient` options.
+- Stop and ask if the fix needs a new dependency.
+
+## Current direction
+- Finish the 429 path in `retryWithBackoff`, then run the full client suite.
+
+## Current work
+- `src/http/client.ts`: retry loop and 5xx path done and passing; 429 path in progress, uncommitted.
+- Observed: `npm test -- client.retry` → 7 passed, 1 failed: `retries 429 after Retry-After` expected ≥1000 ms, got 104 ms.
+- Dropped: calling `setTimeout` directly; the test hung on real time.
+- Run `npm test` (full suite) — when the retry tests pass.
+
+## Recovery sources
+- `src/http/client.ts` lines 40–118 — the retry loop being changed.
+- `test/client.retry.test.ts` — the expected delays per status.
+- `test/helpers/clock.ts` — how the fake clock advances.
+
+## Next useful action
+- Parse `Retry-After` (seconds or HTTP date) and use it before the backoff delay; rerun `npm test -- client.retry`.
+```
+
+The next cycle receives it the same way, with the same recovery message. The summary names no record, so the summary is the record for this cycle.

package/command-surface.json

@@ -30,6 +30,10 @@
       "command": "/write-plan",
       "skill": "write-plan"
     },
+    {
+      "command": "/write-docs",
+      "skill": "write-docs"
+    },
     {
       "command": "/execute-work",
       "skill": "execute-work"

package/gemini-extension.json

@@ -1,5 +1,5 @@
 {
   "name": "freeflow",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Feedback-based control system for coding agents."
 }

package/hooks/shared/runtime-context.mjs

@@ -66,31 +66,27 @@ function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
+function removedContextConfigError(value, filePath) {
+  const removedKeys = ["contextVirtualization", "conversationHistory"].filter((key) => Object.hasOwn(value, key));
+  return removedKeys.length > 0
+    ? `Removed Freeflow context setting(s) in ${filePath}: ${removedKeys.join(", ")}. Delete those keys before using Freeflow.`
+    : null;
+}
+
 function validateCoreConfigFields(value) {
   if (Object.hasOwn(value, "enabled") && typeof value.enabled !== "boolean") {
     return "enabled must be a boolean";
   }
-  if (Object.hasOwn(value, "contextVirtualization") && typeof value.contextVirtualization !== "boolean") {
-    return "contextVirtualization must be a boolean";
-  }
-  if (Object.hasOwn(value, "conversationHistory") && typeof value.conversationHistory !== "boolean") {
-    return "conversationHistory must be a boolean";
-  }
   return null;
 }
 
 function isValidSetupConfig(value) {
   if (!isRecord(value)) return "repository config must be a JSON object";
 
-  const allowedKeys = new Set([
-    "enabled",
-    "contextVirtualization",
-    "conversationHistory",
-    "outputRouter",
-    "observedRouting",
-    "scriptTransform",
-    "cognitiveRouting",
-  ]);
+  const removedContextError = removedContextConfigError(value, ".freeflow/config.json");
+  if (removedContextError) return removedContextError;
+
+  const allowedKeys = new Set(["enabled", "outputRouter", "observedRouting", "scriptTransform", "cognitiveRouting"]);
   if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
     return "repository config contains unsupported top-level keys";
   }
@@ -107,13 +103,10 @@ function isValidSetupConfig(value) {
 function isValidLocalConfig(value) {
   if (!isRecord(value)) return "local config must be a JSON object";
 
-  const allowedKeys = new Set([
-    "enabled",
-    "processing",
-    "cognitiveRouting",
-    "contextVirtualization",
-    "conversationHistory",
-  ]);
+  const removedContextError = removedContextConfigError(value, ".freeflow/local.json");
+  if (removedContextError) return removedContextError;
+
+  const allowedKeys = new Set(["enabled", "processing", "cognitiveRouting"]);
   if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
     return "local config contains unsupported top-level keys";
   }
@@ -127,11 +120,7 @@ function resolveLayeredValue(repository, local, key, fallback) {
 }
 
 function resolveCoreConfig(repository, local) {
-  return {
-    enabled: resolveLayeredValue(repository, local, "enabled", true),
-    contextVirtualization: resolveLayeredValue(repository, local, "contextVirtualization", false),
-    conversationHistory: resolveLayeredValue(repository, local, "conversationHistory", false),
-  };
+  return { enabled: resolveLayeredValue(repository, local, "enabled", true) };
 }
 
 export function readConfig(root) {
@@ -151,8 +140,6 @@ export function readConfig(root) {
     localValid,
     error: repository.valid ? local.error : repository.error,
     enabled,
-    contextVirtualizationEnabled: enabled && core.contextVirtualization,
-    conversationHistoryEnabled: enabled && core.conversationHistory,
   };
 }
 
@@ -173,7 +160,18 @@ function runtimeStateContext() {
 
 export function renderRuntimeContext(root) {
   const config = readConfig(root);
-  if (!config.valid || !config.enabled) return "";
+  if (!config.valid) {
+    if (config.error?.startsWith("Removed Freeflow context setting(s) in ")) {
+      return [
+        "# Freeflow Configuration Error",
+        "",
+        `Freeflow is inactive. ${config.error}`,
+        "Remove the named key(s), then restart the session.",
+      ].join("\n");
+    }
+    return "";
+  }
+  if (!config.enabled) return "";
 
   const { corePrompt, interactionContract } = loadRuntimeContext();
   return [corePrompt, interactionContract, runtimeStateContext()].filter(Boolean).join("\n\n");

package/licenses/Apache-2.0.txt

@@ -0,0 +1,55 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/ 
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hassangameryt/freeflow",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Feedback-based control system for coding agents.",
   "publishConfig": {
     "access": "public"
@@ -22,7 +22,7 @@
     "build:pi-extension": "node -e \"require('node:fs').rmSync('pi-extension/dist', { recursive: true, force: true })\" && tsc -p pi-extension/tsconfig.json && npm run format:pi-extension-dist",
     "build": "npm run build:pi-extension",
     "typecheck": "tsc -p pi-extension/tsconfig.json --noEmit",
-    "check": "npm run typecheck && npm run check:source && npm run check:host-manifests && npm run check:changelog && npm run check:release-workflow && npm run check:docs && npm run format:check && npm run check:release-version && npm run check:commands && npm run check:activation && npm run check:runtime && npm run check:package",
+    "check": "npm run typecheck && npm run check:source && npm run check:host-manifests && npm run check:changelog && npm run check:release-workflow && npm run check:docs && npm run format:check && npm run check:release-version && npm run check:commands && npm run check:activation && npm run check:runtime && npm run check:package && npm run check:eval-coverage",
     "check:source": "node scripts/validation/check-source-files.mjs",
     "check:host-manifests": "node scripts/validation/check-host-manifests.mjs",
     "check:changelog": "node scripts/validation/check-changelog.mjs --structure",
@@ -33,7 +33,9 @@
     "check:activation": "scripts/validation/check-activation-contract.sh",
     "check:runtime": "hooks/tests/check-runtime-context-hook.sh",
     "check:package": "node scripts/validation/check-package.mjs",
+    "check:eval-coverage": "node scripts/validation/check-eval-coverage.mjs",
     "check:release-metadata": "scripts/validation/validate-release-metadata.sh --mode prepublish",
+    "perf:request": "node scripts/perf/request-overhead.mjs",
     "test:pi-extension": "npm run build && node --test $(find pi-extension/tests -name '*.test.js' | sort)",
     "test:host-manifests": "node --test scripts/validation/check-host-manifests.test.mjs hooks/tests/check-host-adapters.test.mjs",
     "test:skill-author": "node --test $(find .skill-eval/write-skill/tests -name '*.test.mjs' | sort)",
@@ -44,6 +46,7 @@
     "test:changelog": "node --test scripts/validation/check-changelog.test.mjs",
     "test:release-workflow": "node --test scripts/validation/check-release-workflow.test.mjs",
     "test:docs": "node --test scripts/validation/check-docs.test.mjs",
+    "test:eval-coverage": "node --test scripts/validation/check-eval-coverage.test.mjs",
     "release:prepare": "node scripts/release.mjs",
     "release:notes": "node scripts/release-notes.mjs",
     "snapshot:refresh": "node scripts/freeflow-snapshot.mjs"
@@ -87,24 +90,34 @@
     ".cursor-plugin/**",
     "com.github.copilot/**",
     "LICENSE",
+    "NOTICE",
+    "licenses/**",
     "README.md",
     "assets/**",
     "capabilities/**",
     "runtime/**",
     "command-surface.json",
-    "hooks/**",
-    "pi-extension/**",
+    "hooks/adapters/**",
+    "hooks/claude/hooks.json",
+    "hooks/codex/hooks.json",
+    "hooks/cursor/hooks.json",
+    "hooks/freeflow-runtime-context.mjs",
+    "hooks/hooks.json",
+    "hooks/shared/runtime-context.mjs",
+    "pi-extension/freeflow/**",
+    "pi-extension/dist/**",
     "skills/**"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-coding-agent": ">=0.99.1",
+    "@earendil-works/pi-tui": ">=0.99.1"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.85.1",
-    "@earendil-works/pi-tui": "0.85.1",
+    "@earendil-works/pi-coding-agent": "1.0.1",
+    "@earendil-works/pi-tui": "1.0.1",
     "@types/node": "^22.15.30",
     "prettier": "3.9.5",
     "typescript": "^5.8.3"
-  }
+  },
+  "dependencies": {}
 }

package/pi-extension/README.md

@@ -0,0 +1,41 @@
+# Freeflow Pi Extension
+
+The Pi integration of Freeflow. Pi loads it as an extension and it adds Freeflow's runtime context, Cognitive Routing, Tool Execution, provider prompt-cache support, the `/freeflow` command, and Freeflow's skill commands.
+
+Supported hosts: Pi `>=0.99.1` (developed and tested against the version pinned in the root `package.json`). The other hosts Freeflow supports load skills and hooks only; this directory is Pi-specific.
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| [`src/`](src/README.md) | TypeScript source. Edit here. |
+| `dist/` | Compiled JavaScript built from `src/`. Committed and shipped in the npm package; never edit by hand. |
+| [`freeflow/`](freeflow/README.md) | The entry point Pi loads (`package.json` → `pi.extensions`). Re-exports `dist/index.js`. |
+| [`tests/`](tests/README.md) | Node test suites, run against `dist/`. |
+| `tsconfig.json` | Compiles `src/` into `dist/`. |
+
+## Build and test
+
+Run from the repository root:
+
+```bash
+npm run build             # src/ → dist/, then formats dist/
+npm run typecheck         # type errors only, no output
+npm run test:pi-extension # builds, then runs every tests/**/*.test.js
+npm run check             # the full deterministic gate used in CI
+```
+
+Commit `dist/` together with the `src/` change that produced it. Pi development uses a committed snapshot of the repository, not this working tree (see `AGENTS.md`, "Development Snapshot Boundary").
+
+## Rules that apply everywhere here
+
+- **Performance.** Keep per-request and per-turn work small and independent of session length; keep `tests/integration/request-path-budget.test.js` passing. See [Performance](../dev-docs/guides/performance.md).
+- **Prompt cache.** Never change content a provider already cached, keep the Freeflow system section and tool definitions fixed, and append new content at the end. Every request-assembly change needs a test in which a later request starts with the earlier one. See [Prompt cache rules](../dev-docs/guides/prompt-cache.md).
+- **Host source.** Work from a pinned upstream Pi checkout, not installed or cached docs (`AGENTS.md`, "External Host Source Provenance").
+- **Pi imports.** Pi provides `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` to extensions at runtime. They are peer dependencies, never bundled.
+
+## Further reading
+
+- [Pi integration](../plugin-docs/integrations/pi.md)
+- [Architecture](../dev-docs/README.md) and [Prompt architecture](../dev-docs/subsystems/prompt-assembly.md)
+- [Cognitive Routing](../plugin-docs/capabilities/cognitive-routing.md) and [Tool Execution](../plugin-docs/capabilities/tool-execution.md)