@hassangameryt/freeflow 0.7.2 → 0.8.0

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.2",
+  "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.2",
+  "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)