@hassangameryt/freeflow 0.1.0 → 0.3.0

package/plugin-docs/architecture.md

@@ -0,0 +1,89 @@
+# Architecture
+
+Freeflow is a portable skill pack for coding agents.
+
+## Runtime Boundary
+
+Freeflow ships Markdown skills, bundled references, lightweight context-loading hooks, and a Pi extension. It does not ship a CLI, Codex/Claude native slash handlers, enforcement hooks, or a new agent runtime in this release.
+
+Host runtimes still control tools, sandboxing, approvals, and permissions. Freeflow controls workflow pressure:
+
+- how much clarification is needed
+- when artifacts are useful
+- when source-truth conflicts stop edits
+- when review and verification are required
+- when a handoff or durable decision is useful
+
+## Package Layout
+
+```text
+freeflow/
+  package.json
+  .agents/plugins/marketplace.json
+  .codex-plugin/plugin.json
+  .claude-plugin/marketplace.json
+  .claude-plugin/plugin.json
+  README.md
+  LICENSE
+  CHANGELOG.md
+  command-surface.json
+  assets/
+  plugin-docs/
+  docs/
+  evals/
+  hooks/
+  pi-extension/
+  router/
+  skills/
+```
+
+The repository root is the plugin root. Codex uses `.agents/plugins/marketplace.json`; Claude uses `.claude-plugin/marketplace.json`. Both point at `.`. Pi uses the root `package.json` `pi` manifest to load `skills/` and the built extension at `pi-extension/dist/index.js`; TypeScript source lives under `pi-extension/src/`.
+
+The repo root is the single runtime source of truth. Skill edits, bundled references, eval metadata, public docs, and command-surface metadata live there to avoid generated package drift. Public plugin docs live under `plugin-docs/`. Project-development memory lives under `docs/` and is not part of the runtime surface.
+
+`router/src/` is organized by responsibility: public tool entrypoints in `tools/`, transformation internals in `transform/`, evidence helpers in `evidence/`, vault storage in `vault/`, repo traversal in `repo/`, capture/routing/parsers in `routing/`, sandbox adapters in `sandbox/`, configuration contracts in `config/`, benchmark harnesses in `benchmarks/`, and frozen experiments in `experiments/`. `router/dist/` mirrors that layout as generated package output; active deprecated or historical router artifacts stay outside runtime code under `deprecated/router/`.
+
+## Progressive Disclosure
+
+Each skill keeps its active `SKILL.md` short. Stable details move into `references/` files only when they prevent bloat, reduce repeated work, or address measured failures.
+
+This keeps the model's first-loaded instructions focused on behavior:
+
+- trigger
+- loop
+- stop condition
+- failure prevention
+
+## Host Setup
+
+`setup-freeflow` installs a compact always-on contract into the host repo.
+
+The canonical setup contract lives in `skills/setup-freeflow/references/activation-contract.md`; setup docs, fixtures, and eval assertions should reference it or be checked against it.
+
+Codex setup targets `AGENTS.md` and `.freeflow/config.json`.
+
+Claude setup targets `CLAUDE.md`, `.claude/rules/freeflow-core.md`, and `.freeflow/config.json` when Claude is the selected host.
+
+Setup should not silently update both hosts or overwrite stronger repo-specific rules. Existing repo instructions are source truth.
+
+## Runtime Context Hooks
+
+The installed plugin owns `hooks/hooks.json`. Setup does not copy hook files into target repos.
+
+The hooks load the existing `mode-contract`, `workflow`, `interview-gate`, `discover`, and `output-router` skills:
+
+- at session start, including startup, resume, clear, and compact
+
+They also report whether the current repo appears set up, partially set up, or missing setup, and state the runtime priority order: mode-contract handles mode issues first, workflow classifies, interview-gate stops silent decisions, discover handles context-building, and output-router chooses evidence transport. They do not run after edit/write tools, block tools, grant permissions, enforce mode policy, or replace repo instructions.
+
+Setup handles the same-session case directly: after successful setup verification, it reads the mode-contract, workflow, interview-gate, discover, and output-router skills before its final response and only then says that context is loaded.
+
+Host runtimes may require plugin hooks to be reviewed and trusted after install. If the host skips untrusted hooks, setup still writes activation/config files, but future session-start runtime context will not load until hooks are trusted and the session is restarted, resumed, cleared, or compacted.
+
+Pi uses an extension instead of `hooks/hooks.json`. The built Pi extension registers direct commands, reads `mode-contract/SKILL.md`, `workflow/SKILL.md`, `interview-gate/SKILL.md`, `discover/SKILL.md`, and `output-router/SKILL.md`, refreshes that context on `session_start` and `session_compact`, injects full skill context once during Pi's `before_agent_start` lifecycle after that boundary, then keeps later turns to a short mode/priority refresh plus compact output-router tool reminder. The workflow-map and output-router safety-policy references remain available on demand but are not injected wholesale by default. The same extension registers `freeflow_status`, `freeflow_search`, `freeflow_run`, and `freeflow_batch` and gives them compact/expanded TUI renderers so collapsed tool rows stay readable while `ctrl+o` shows structured status, evidence, recovery details, and non-destructive migration recommendations. `freeflow_search action=transform operation.kind="script"` and `freeflow_run` script producers stay disabled until setup/user config opts in; setup can install JavaScript/Python/jq adapters into a user-global Freeflow cache, Pi auto-discovers that cache plus explicit `FREEFLOW_QUICKJS_WASI_ROOT`, `FREEFLOW_JQ_WASM_ROOT`, and `FREEFLOW_ERYX_ROOT` overrides, and only proof-passing languages are enabled. The Eryx Python adapter launches the setup-installed `node@24` child process with `--experimental-wasm-jspi` when needed, so normal Pi launches can still use Python after setup proof passes. When configured, its Pi `tool_result` hook observed-routes MCP, web, fetch, and code-search outputs after direct host execution; host permissions and execution remain owned by Pi. Pi `/workflow` commands set a session-scoped current-mode override, while `.freeflow/config.json` remains the default-mode source. It follows the same boundary as the Codex/Claude hooks: context loading and output routing only, no enforcement.
+
+## Deferred Enforcement
+
+Enforcement hooks and CLI checks are intentionally deferred. They are useful only after skill wording and evals prove a repeated behavior needs mechanical enforcement.
+
+For this release, commands are model-routed language such as `/write-spec` or `/verify-work`; they are not native registered slash handlers.

package/plugin-docs/output-router.md

@@ -0,0 +1,396 @@
+# Output Router
+
+Freeflow Output Router keeps agent context focused while preserving exact evidence outside context.
+
+Use it when broad repo exploration, generated artifacts, large logs, or noisy command output would otherwise flood the model.
+
+For the full architecture, see [`docs/designs/freeflow-output-router-architecture.md`](../docs/designs/freeflow-output-router-architecture.md).
+
+## Core Idea
+
+```text
+smallest sufficient evidence in context
++ exact recovery when exactness matters
++ no surprise native tool semantics
+```
+
+The router ships explicit tools and Pi observed routing:
+
+- `freeflow_search`: search/retrieve repo or vault evidence, and transform file/output sources through `action="transform"`.
+- `freeflow_run`: run shell commands or sandboxed script producers, apply the run storage policy, and return compact evidence with recovery guidance.
+- `freeflow_batch`: run independent `run`/`search` steps and optionally aggregate query answers.
+- Pi observed routing: route enabled MCP/web/fetch/code-search outputs after direct host tool calls.
+- `freeflow_status`: inspect effective config, observed routing, script transform, vault writability/index state, and non-destructive migration recommendations.
+
+Native tools still matter:
+
+- use native `read` for known whole files,
+- use native `bash` for small/direct raw shell behavior,
+- use native `edit`/`write` for mutations.
+
+## Tiny Map
+
+```mermaid
+flowchart LR
+  Agent[agent]
+  Search[freeflow_search]
+  Run[freeflow_run]
+  Repo[repo files]
+  Vault[Freeflow vault]
+  Observed[Pi observed routing]
+  Transform[freeflow_search action=transform]
+  Status[freeflow_status]
+  Native[native read/bash]
+  Evidence[bounded evidence]
+  Raw[exact or metadata-only recovery]
+
+  Agent -->|existing info| Search
+  Agent -->|noisy command| Run
+  Agent -->|direct MCP/web/fetch/code-search| Observed
+  Agent -->|transform source| Transform
+  Agent -->|inspect config/status| Status
+  Agent -->|direct/raw known output| Native
+  Search --> Repo --> Evidence
+  Search --> Vault --> Evidence
+  Transform --> Vault
+  Transform --> Evidence
+  Run --> Vault
+  Observed --> Vault
+  Run --> Evidence
+  Observed --> Evidence
+  Vault --> Raw
+```
+
+## Tool Choice
+
+| Need | Use |
+| --- | --- |
+| Find repo evidence before reading files | `freeflow_search action=query` |
+| Get candidate paths first | `freeflow_search action=locate` |
+| Find where exact-ish text/code exists | `freeflow_search action=get` |
+| Retrieve exact known repo/vault lines | `freeflow_search action=retrieve` with `lineRange` |
+| Widen previous evidence | `freeflow_search action=expand` |
+| Explain a previous routed decision/output | `freeflow_search action=explain` |
+| Run noisy/large command output | `freeflow_run` with `command` |
+| Run code as a sandboxed base producer | `freeflow_run` with `script` |
+| Use enabled Pi MCP/web/fetch/code-search output | Call the host tool directly; observed routing runs after the tool result |
+| Transform repo/vault sources or compute deterministic subsets/stats from vaulted output | `freeflow_search action=transform` |
+| Inspect script-transform disabled/unavailable state | `freeflow_status` |
+| Inspect effective config, observed routing, script transform, vault/index state, or migration recommendations | `freeflow_status` |
+| Read a known whole file | native `read` |
+| Run small exact command | native `bash` |
+
+## `freeflow_search`
+
+Sources:
+
+- `repo`: local repo files.
+- `vault`: previous routed command/native/observed/transformed output, either by known `outputId` or vault-wide index query.
+
+Actions:
+
+- `query`: returns best evidence packets; default `topK=1`. For vault sources, omit `outputId` to search the current session's vault index.
+- `locate`: returns candidate locations; default `topK=5`. For vault sources, omit `outputId` to locate indexed vault outputs without raw retrieval.
+- `get`: maps exact-ish text/code/query to the best matching path or output id plus line range and matched content.
+- `retrieve`: maps known coordinates to exact content; use it when path/output id and line range are already known.
+- `expand`: expands a previous evidence packet to `lines_30`, `lines_80`, or `full`.
+- `explain`: explains a route decision or vault output.
+
+Example:
+
+```json
+{
+  "action": "query",
+  "source": { "kind": "repo" },
+  "query": "Sandbox Permissions UseDefault RequireEscalated WithAdditionalPermissions",
+  "preserve": "important"
+}
+```
+
+Vault-wide indexed query:
+
+```json
+{
+  "action": "query",
+  "source": { "kind": "vault" },
+  "query": "rate limit deployment failed github issue",
+  "filters": { "producerKind": "mcp", "server": "github" }
+}
+```
+
+Evidence packets include:
+
+- source/path,
+- line range,
+- exact excerpt,
+- why the router selected it,
+- expansion/recovery guidance.
+
+Repo retrieval uses deterministic scanner ranking by default. Broad scans skip generated/dependency/cache paths such as `graphify-out/**`, but explicit path retrieval remains available.
+
+Vault-wide retrieval uses the vault index sidecar. Exact records return source output ids, streams, and line ranges for recovery; metadata-only records can be found by metadata but do not expose raw recovery. Use `filters` for producer/server/tool/hostToolName/stream/record-kind/recoverability narrowing. Use `source.outputId` with `retrieve`, `expand`, or `explain` when the exact vaulted output is known.
+
+## `freeflow_run`
+
+`freeflow_run` executes one base producer, applies the configured run storage policy, then returns useful evidence. The base producer can be either a host-approved shell command or a sandboxed script. The default `hybrid-dedupe` policy keeps exact raw recovery for exactness-sensitive output while allowing small non-sensitive command successes to become metadata-only. Script producers are treated as exactness-sensitive because raw script text is not persisted.
+
+Command example:
+
+```json
+{
+  "command": "npm test",
+  "goal": "verification",
+  "preserve": "important"
+}
+```
+
+Sandboxed script producer example:
+
+```json
+{
+  "script": {
+    "language": "javascript",
+    "code": "console.log(JSON.stringify({ ok: true }))",
+    "label": "emit-json"
+  },
+  "preserve": "important"
+}
+```
+
+Returned results include:
+
+- `outputId`,
+- `execution.status` and `exitCode`,
+- `producer.kind` (`command` or `script`),
+- `scriptProducer` metadata for sandboxed script producers, including language, policy, adapter, limits, and code hash,
+- parser metadata,
+- important lines,
+- exact recovery instructions when exact recovery exists, or metadata-only rerun guidance when it does not.
+
+Command parsers currently cover:
+
+- test runner output,
+- TypeScript/lint diagnostics,
+- git status/diffstat,
+- build/toolchain errors,
+- generic fallback,
+- duplicate output detection.
+
+## Pi Observed Routing
+
+Pi observed routing handles configured MCP, web, fetch, and code-search outputs after direct host tool execution. Public Pi `freeflow_capture` has been removed; use the host MCP/web/fetch/code-search tool directly and configure `observedRouting` when routed recovery is needed.
+
+Mutating MCP/tools remain direct host calls after explicit user intent. Freeflow treats read/write classification as routing metadata, not as a host permission gate.
+
+## `freeflow_search action=transform`
+
+`freeflow_search action=transform` transforms existing vaulted output. Current deterministic operations do not execute arbitrary code.
+
+`operation.kind="script"` is the sandboxed transform branch under the same tool. `freeflow_run` also exposes the same sandbox engine as a base `script` producer. Both are disabled by default, have no unsandboxed fallback, and do not persist raw script text. Transform scripts vault successful stdout as transformed text with source lineage. Run script producers capture stdout/stderr/combined as run output with `producer.kind="script"`; failures and output-limit overflows return structured no-recovery results.
+
+Current product execution support is Pi-first and explicit package-root opt-in:
+
+- JavaScript can run through a proof-backed QuickJS adapter only when script transform is explicitly enabled and Pi can discover a local `quickjs-wasi` package root.
+- Python can run through a proof-backed Eryx adapter only when script transform is explicitly enabled and Freeflow can discover an installed `@bsull/eryx` package root plus a JSPI-capable Node runtime. Setup installs `node@24` for this Python child runner. When the host process lacks JSPI, the adapter runs Eryx through that setup-installed child Node process launched with `--experimental-wasm-jspi` and enables Python only if the runner passes sandbox proofs.
+- jq can run through a proof-backed `jq-wasm` adapter only when script transform is explicitly enabled and Pi can discover a local `jq-wasm` package root.
+
+`freeflow_status` reports the script-sandbox contract version, configured languages, required adversarial proofs, rejected unsafe mechanisms such as Node `vm`/plain subprocesses, candidate-unproven OS sandbox adapters, and whether QuickJS, Eryx, and jq-wasm adapters are available. A language remains unavailable until a registered adapter passes every required proof. Proof results are cached in-process by adapter content hash and probe limits so repeated status/transform checks do not rerun the same adversarial probes.
+
+Current deterministic operations include:
+
+- regex filtering and match counts,
+- JSON Pointer/path extraction,
+- grouping, dedupe, and topN extraction,
+- URL/citation extraction,
+- line and size stats.
+
+Transformed output is vaulted separately and points back to source output ids through lineage. Script operation hashing records code hashes, not raw code.
+
+### Optional script adapters
+
+Freeflow setup can install script adapters into a user-global cache after explicit consent. The default adapter home is `~/.cache/freeflow-script-adapters`; override it with `FREEFLOW_SCRIPT_TRANSFORM_ADAPTERS_HOME` when needed. Setup installs:
+
+- `quickjs-wasi@3.0.1` for JavaScript.
+- `jq-wasm@1.2.0-jq-1.8.2` for jq.
+- `@bsull/eryx@0.5.0` plus `node@24` for Python. The adapter launches the setup-installed child Node process with `--experimental-wasm-jspi` when needed; setup enables Python only after that child runner passes sandbox proofs.
+
+Freeflow auto-discovers adapters from the global cache. Explicit package-root overrides remain available:
+
+- `FREEFLOW_QUICKJS_WASI_ROOT` for a custom `quickjs-wasi` package root.
+- `FREEFLOW_JQ_WASM_ROOT` for a custom `jq-wasm` package root.
+- `FREEFLOW_ERYX_ROOT` for a custom `@bsull/eryx` package root.
+
+Discovery alone does not enable execution. `.freeflow/config.json` must opt in. The setup installer writes only proof-passing languages, for example:
+
+```json
+{
+  "defaultMode": "workflow",
+  "scriptTransform": {
+    "enabled": true,
+    "languages": ["javascript", "jq"]
+  }
+}
+```
+
+Supported `scriptTransform` keys are `enabled`, `sandbox`, `languages`, `network`, `limits`, and `rawScriptPersistence`. Defaults keep `sandbox: "auto"`, `network: "off"`, `rawScriptPersistence: "disabled"`, and conservative input/output/time limits. Per-call script limits may only tighten configured limits.
+
+QuickJS guest JavaScript receives only `readText(alias)`, `writeText(text)`, `console.log`, and `console.error`. Eryx guest Python receives `read_text(alias)`, `write_text(text)`, and a `sources` dict keyed by source alias. jq receives a JSON object keyed by source alias, so a source with alias `log` is available as `.log`. Vault sources are copied into temporary input files before adapter execution; repo, home, vault, process, require, fetch, package loading, and host filesystem APIs are not exposed to guest code. Invalid or missing adapter roots fail closed as adapter unavailable.
+
+The Python adapter runs Eryx inside a Node Worker with Worker termination for timeouts, bounded stdout/stderr before results cross the Worker-to-host boundary, a temp-copy import rewrite to force preview2 browser/in-memory shims, and a deny-only network shim. It collects no output files; transformed content comes from stdout. Residual caveat: Eryx/Python can still materialize large strings inside the Worker before wrapper truncation; product execution treats output-limit overflow as a structured failure with no exact recovery.
+
+The jq adapter runs `jq-wasm` inside a Node Worker with Worker termination for timeouts and bounded stdout/stderr before results cross the Worker-to-host boundary. Residual caveat: `jq-wasm` can still generate large in-Worker strings before truncation; product execution treats output-limit overflow as a structured failure with no exact recovery.
+
+### Local unsafe processing opt-in
+
+Freeflow also has an internal processing-engine branch for local power users who explicitly accept unsandboxed execution risk. This is not enabled by shared repo config.
+
+Use local-only `.freeflow/local.json`:
+
+```json
+{
+  "processing": {
+    "unsafeUnsandboxed": {
+      "enabled": true
+    }
+  }
+}
+```
+
+Rules:
+
+- `.freeflow/local.json` is local-only and should be ignored by git.
+- `.freeflow/config.json` cannot enable unsafe unsandboxed processing.
+- Each call must still request `script.policy="unsafe-unsandboxed"`; sandboxed remains the default.
+- Unsafe results must say `unsafe/unsandboxed`; they must not claim sandbox, read-only, or network-off execution.
+- Missing or invalid local opt-in rejects the unsafe call. Freeflow must not silently fall back to an unsandboxed host path.
+
+## `freeflow_status`
+
+`freeflow_status` reports effective Freeflow behavior without rewriting config.
+
+It shows:
+
+- router enabled/profile and thresholds,
+- vault path and writability,
+- observed-routing policy and recoverability defaults,
+- script-transform enabled/off state through `scriptTransform`, adapter availability, configured languages, required sandbox proofs, rejected/candidate mechanisms, no-network policy, limits, and raw-script persistence state,
+- config warnings and safe fallbacks,
+- non-destructive migration recommendations for stale explicit defaults or unknown keys.
+
+Migration recommendations are informational only. They require explicit confirmation before any future rewrite of `.freeflow/config.json`.
+
+## Vault Recovery
+
+Recover exact command output with:
+
+```json
+{
+  "action": "retrieve",
+  "source": { "kind": "vault", "outputId": "ffout_...", "stream": "combined" },
+  "lineRange": { "start": 1, "end": 40 },
+  "preserve": "full"
+}
+```
+
+Streams:
+
+- command output: `stdout`, `stderr`, `combined`,
+- native safety-net output: `raw`.
+
+Default vault root:
+
+```text
+~/.cache/freeflow-router/vault
+```
+
+## Config
+
+The router works with built-in defaults. Minimal `/setup-freeflow` writes only `defaultMode`.
+
+Optional repo config lives in `.freeflow/config.json` only after the setup evidence-routing decision point or an explicit request:
+
+```json
+{
+  "defaultMode": "workflow",
+  "outputRouter": {
+    "enabled": true,
+    "profile": "standard",
+    "postToolRouting": "off",
+    "storagePolicy": "hybrid-dedupe",
+    "largeOutputBytes": 64000,
+    "largeOutputLines": 1000,
+    "vaultRoot": "~/.cache/freeflow-router/vault",
+    "vaultRetentionDays": 7,
+    "generatedPaths": ["graphify-out/**"],
+    "noisyCommandHints": ["npm test"]
+  },
+  "observedRouting": {
+    "enabled": true,
+    "onRoutingFailure": "fail-open",
+    "mcp": {
+      "servers": {
+        "github": { "enabled": true, "persistence": "exact" },
+        "gmail": { "enabled": true, "persistence": "metadata-only" }
+      }
+    },
+    "web": { "enabled": true, "persistence": "exact" },
+    "fetch": { "enabled": true, "persistence": "exact" },
+    "codeSearch": { "enabled": true, "persistence": "exact" }
+  }
+}
+```
+
+Rules:
+
+- `postToolRouting` defaults to `off`.
+- `storagePolicy` defaults to `hybrid-dedupe` for `freeflow_run` command/script capture. `store-everything` is the compatibility/diagnostic override.
+- Small non-sensitive successful command output may be metadata-only; failures, verification/diagnosis/build/test output, `preserve=full`, filters/script filters, script producers, and large/noisy output stay exact.
+- Exact duplicate run output may store current metadata pointing to a prior exact `outputId`; plain metadata-only records must not claim exact recovery.
+- `safety-net` is opt-in.
+- `strict` is reserved.
+- Observed routing is opt-in per producer/server. Setup writes explicit entries only after the user chooses them.
+- Observed-routing persistence modes are `exact`, `metadata-only`, and `none`. `redacted` is future-only and not a setup option.
+- Native safety-net routing is configured with `outputRouter.postToolRouting`; removed `capture` and `providers` config must not be written.
+- Do not dump defaults into config.
+- Write only requested keys.
+
+## Observed Routing
+
+Pi can route enabled MCP, web, fetch, and code-search outputs after the direct host tool call. The agent still calls the host tool directly; Freeflow only routes/reduces/stores the completed output.
+
+Observed routing is off by default. Setup must choose each enabled producer/server and its persistence mode up front.
+
+## Native Safety Net
+
+Pi can optionally route large native `read`/`bash` results after the tool runs.
+
+Default: off.
+
+When enabled, a routed native result is labeled, vaulted, and includes an `outputId`. If safety-net routing fails, Freeflow fails open and returns native output with a warning.
+
+## Defaults And Experiments
+
+Current adoption decisions:
+
+- Scanner retrieval is the default backend.
+- The no-dependency local index is experimental and not adopted by default.
+- SQLite/FTS is not adopted.
+- Model-assisted routing is not default.
+- Graphify, Claude Context, RTK, and Squeez are optional references/comparators, not dependencies.
+
+## Evidence
+
+Current release evidence:
+
+- Retrieval benchmark: improved router passed 7/7 fixtures.
+- Command benchmark: `freeflow_run` passed 8/8 fixtures with exact recovery for exactness-sensitive command fixtures and duplicate recovery through prior exact output ids.
+- Historical capture/transform/provider eval: targeted Slice 9 eval passed 14/14 objective gates before the provider-summary config surface was removed; observed routing now owns producer output routing.
+- Pi observed-routing eval: targeted eval passed 28/28 objective gates for MCP, web, fetch, code-search, metadata-only persistence, and Pi capability status.
+- Vault-index storage spike: selected deterministic local JSON sidecar behind the vault-index interface; SQLite/FTS remains deferred because native/runtime dependency adoption needs owner approval.
+- Optional repo-source index benchmark: scanner remains default; repo-source index not adopted. Latest repo search backend benchmark compared scanner-only, local lexical index, Node `node:sqlite` FTS5/BM25/trigram, and conservative hybrid scanner+index; all passed 3/3 fixtures with recall@3 3/3 and zero generated false positives. FTS was tested through the experimental Node runtime available in this environment; no package dependency was added.
+- Storage-policy benchmark: `hybrid-dedupe` is the command-capture default after benchmark evidence; threshold-only storage was disqualified.
+- Codex Structured Q&A benchmark: improved router passed the Sandbox Permissions fixture where native broad search selected `graphify-out/graph.html`.
+- Context Mode normalized benchmark: Freeflow-owned tools and the normalized Context Mode-style proxy both passed 6/6 fixtures. Freeflow preserved exact facts/recovery on 6/6 but did not beat the proxy on model-visible bytes in these normalized fixtures; no public superiority claim is made.
+- Setup eval: optional `outputRouter`/`observedRouting`/`scriptTransform` config is opt-in through the capabilities branch; minimal setup remains only `defaultMode`.
+
+See `release-evidence.md` and runtime reports under `evals/reports/runtime/`.

package/plugin-docs/release-evidence.md

@@ -0,0 +1,77 @@
+# Release Evidence
+
+Freeflow v0.3.0 is based on the v0.1 local acceptance suite plus targeted runtime, setup, and output-router evidence from the development repository.
+
+## Acceptance Summary
+
+The local v0.1 acceptance suite passed after measured fixes and was rerun during prepublish verification on 2026-05-26.
+
+High-signal behaviors covered:
+
+- Source-truth conflicts stop before edits.
+- Strict public API specs ask for owner decisions.
+- Execution stops when verification reveals a bad plan.
+- Commit flow refuses mixed staged sensitive changes.
+- Discovery checkpoints replace separate briefing, grilling, and decision-capture commands for discovery work.
+- Bypass skips ceremony, not judgment.
+
+## Command Surface
+
+The development registry covers:
+
+- 4 mode commands.
+- 12 direct skill calls.
+- 3 developer skill calls.
+
+Codex/Claude native slash handlers are not shipped in this release. In those hosts, commands are model-routed through natural language and skill activation. Pi registers direct Freeflow commands through its extension, including `/output-router`.
+
+## Runtime Context
+
+Freeflow ships plugin-bundled context hooks that load the existing `mode-contract`, `workflow`, `interview-gate`, `discover`, and `output-router` skills at session start. The Pi extension injects full skill context once after session/compact boundaries, then keeps later turns to a short mode/priority refresh plus compact output-router tool reminder. Workflow-map and output-router safety-policy references remain available on demand but are not injected wholesale by default. Runtime context states the priority order: mode-contract handles mode issues first, workflow classifies, interview-gate stops silent decisions, discover handles context-building, and output-router chooses evidence transport. These hooks do not run after edit/write tools, enforce behavior, block tools, or create repo-local hook files.
+
+For the same session that runs setup, `setup-freeflow` reads the mode-contract, workflow, interview-gate, discover, and output-router skills after successful setup verification before saying that context is loaded.
+
+Host trust prompts for plugin hooks are expected host behavior. Local metadata validation checks hook packaging and deterministic output, not end-to-end host trust UI.
+
+## Output Router Evidence
+
+Output-router behavior is backed by deterministic runtime reports under `evals/reports/runtime/`.
+
+Verified in the development repo:
+
+- Retrieval benchmark: improved router passed 7/7 gated fixtures and fixed the generated-artifact Sandbox Permissions false-positive shape.
+- Command-output benchmark: `freeflow_run` passed 8/8 fixtures, preserved exact facts, and verified raw vault recovery.
+- Historical capture/transform/provider eval: targeted eval passed 14/14 objective gates before provider-summary config was removed; observed routing now owns producer output routing.
+- Pi observed-routing eval: targeted eval passed 28/28 gates with 82.2% overall byte reduction across MCP/web/fetch/code-search fixtures, exact recovery where configured, metadata-only no-raw recovery, and Pi capability status.
+- Vault-index storage/write/query path: selected deterministic local JSON sidecar for vault evidence indexing without adding native dependencies, indexes persisted appends immediately, supports vault-wide `freeflow_search` query/locate with recovery pointers, preserves metadata-only/no-persist rules, and keeps index failures non-blocking; SQLite/FTS remains deferred pending owner approval.
+- Script execution schema/status gate: `freeflow_search action=transform operation.kind="script"` and `freeflow_run` script producers are shaped under existing public tools, disabled by default, report status/config/limits/raw-script persistence, and return structured disabled/unavailable before execution when script transform or a requested adapter is unavailable. Transform scripts resolve vault sources; run script producers execute with an empty source manifest and capture stdout/stderr as run output.
+- Script-sandbox proof gate: router exposes a sandbox adapter/probe interface, required adversarial proofs, rejected unsafe mechanisms, and status-visible candidate-unproven mechanisms; no unsandboxed fallback exists. JavaScript, Python, and jq product execution are implemented only after setup/user config opts in and proof-backed adapters are available. Python uses the Eryx adapter from the global adapter cache or `FREEFLOW_ERYX_ROOT`; when the host lacks JSPI, the adapter launches the setup-installed `node@24` child process with `--experimental-wasm-jspi` and enables Python only after that runner passes proofs. Earlier adapter evidence is in `evals/reports/runtime/eryx-python-proof-spike-2-report.md`; current transform-routing evidence is in `evals/reports/runtime/output-router-transform-eval-1-report.md`; current setup smoke verifies Python availability through the child runner. Probe resource hardening reduced flood fixture sizes and caches proof results by adapter hash/probe limits.
+- Optional repo-source local index benchmark: scanner remains default, index is not adopted by default, and the no-dependency repo-source index remains experimental. The latest repo search backend benchmark compares scanner-only, local lexical index, Node `node:sqlite` FTS5/BM25/trigram, and conservative hybrid scanner+index; all pass the current fixtures with recall@3 3/3 and zero generated false positives. FTS was tested through the experimental Node runtime available in this environment; no package dependency was added.
+- Storage-policy benchmark/adoption: `hybrid-dedupe` is the `freeflow_run` command/script capture default after benchmark evidence; failures/verification/diagnostics, `preserve=full`, filters/script filters, script producers, and large/noisy outputs remain exact; small non-sensitive command successes may be metadata-only; exact duplicates may point to a prior exact output.
+- Context Mode normalized benchmark: Freeflow-owned tools and the normalized Context Mode-style proxy both pass 6/6 fixtures. Freeflow preserves exact facts/recovery on 6/6, but visible answer accuracy is 4/6 and the proxy is smaller on model-visible bytes for these normalized fixtures; no public superiority claim is made.
+- Context Mode real deep final benchmark: Freeflow improved from 17/28 correct and 76/92 facts to 35/36 correct and 124/124 facts, with weighted reduction improving from 76.28% to 95.76%. Freeflow beats Context Mode for covered reducers and batch aggregation on context size, but Context Mode still wins indexed repo/docs search compactness and latency. Evidence: `evals/reports/runtime/context-mode-real-deep-final-slice-11-report.md` and `evals/reports/runtime/context-mode-real-deep-final-slice-11-review.md`.
+- Codex Structured Q&A macro benchmark: improved router passed the first Sandbox Permissions Q&A fixture while the native broad-search proxy selected `graphify-out/graph.html`.
+- Large Codex scanner benchmark: scanner remains the retrieval backend; latest recorded report-refresh evidence kept scanner at 6/8 strict fixtures with bounded context.
+- Setup/config eval: `setup-freeflow` supports optional capabilities repo config (`outputRouter`, `observedRouting`, `scriptTransform`) only after an explicit setup branch/request; minimal setup still writes only `defaultMode`.
+
+Adoption decisions:
+
+- Scanner improvements ship as default behavior.
+- Native post-tool safety-net routing remains off unless explicitly configured.
+- The no-dependency local index stays experimental.
+- SQLite/FTS, model-assisted routing, Graphify, and Claude Context remain optional/non-default comparison paths, not product dependencies.
+
+## Release Metadata
+
+Run `evals/scripts/validate-release-metadata.sh` for local prepublish checks across marketplace metadata, host manifests, command-surface routing, release-boundary docs, package cleanliness, and deferred install-smoke status.
+
+Run `evals/scripts/check-runtime-context-hook.sh` after changing lifecycle context hooks.
+
+## Known Deferred Work
+
+- Live Claude smoke evals after Hassan confirms Claude testing is available again.
+- GitHub-install smoke tests in separate Codex, Claude, and fresh Pi environments.
+- Enforcement hooks or CLI checks only after repeated behavior failures justify them.
+- Public marketplace submission only after GitHub install works for required hosts.
+
+Full eval reports are development evidence and are not included in the runtime package.

package/{plugins/freeflow/docs → plugin-docs}/skills.md

@@ -1,6 +1,6 @@
 # Skills
 
-Freeflow ships a small workflow skill pack. Natural language is the preferred interface. In Codex/Claude, slash-style phrases work as model-routed skill hints in v0.1; in Pi, the extension registers direct Freeflow commands.
+Freeflow ships a small workflow skill pack. Natural language is the preferred interface. In Codex/Claude, slash-style phrases work as model-routed skill hints; in Pi, the extension registers direct Freeflow commands.
 
 ## Core
 
@@ -9,29 +9,29 @@ Freeflow ships a small workflow skill pack. Natural language is the preferred in
 | `workflow` | Choosing the next workflow entry point or explaining the full flow. |
 | `mode-contract` | Inferring or switching `conversation`, `workflow`, or `strict-workflow`. |
 | `interview-gate` | Ambiguity or a user-owned decision would change the next action. |
+| `output-router` | Choosing routed tools for large/noisy output, vault recovery, or output-router configuration. |
 | `bypass` | Skipping unnecessary ceremony without skipping judgment. |
+| `design-for-depth` | Module/interface/seam choices affect complexity, locality, testability, future change, or repeated edge-case churn. |
 
 ## Discovery And Artifacts
 
 | Skill | Use When |
 | --- | --- |
-| `research-brief` | Repo, domain, evidence, or current facts are unknown. |
-| `grill-context` | Direction is vague and a decision tree needs clarification. |
+| `discover` | An idea, feature, architecture direction, vague task, or consequential question needs evidence, brainstorming, targeted questions, and a checkpoint before spec, plan, build, or durable memory. |
 | `write-spec` | Agreed requirements or decisions need a durable spec. |
-| `review-artifact` | A spec, plan, handoff, research brief, or decision note must guide future work. |
+| `review-artifact` | A spec, plan, handoff, discovery checkpoint, or decision note must guide future work. |
 | `write-plan` | An approved spec or explicit task context needs executable slices. |
 
 ## Execution And Closeout
 
 | Skill | Use When |
 | --- | --- |
-| `execute-plan` | An approved plan exists and should be implemented in checked slices. |
+| `execute-plan` | An approved plan exists and should be implemented in checked slices, especially multi-slice/TDD work with verification, review, commit, or handoff checkpoints. |
 | `diagnose-failure` | Behavior is broken, failing, flaky, slow, or unclear. |
-| `review-work` | A completed diff or review feedback needs bug/risk-focused review. |
+| `review-work` | A completed diff or review feedback needs bug/risk-focused review or adjudication before fixes. |
 | `verify-work` | Fresh evidence is needed before claiming completion. |
 | `commit-work` | Reviewed, verified, intended work is ready to commit. |
 | `handoff` | Pausing, compacting, transferring context, or preserving continuation memory. |
-| `capture-decisions` | Stable decisions, glossary terms, rejected approaches, or ADR-worthy tradeoffs should be recorded. |
 
 ## Contributor Skills
 

package/{plugins/freeflow/docs → plugin-docs}/workflow.md

@@ -4,7 +4,7 @@ Freeflow is a workflow layer, not a new agent. It helps the agent choose the rig
 
 ## Modes
 
-- `conversation`: answer, explain, critique, or explore without workflow pressure.
+- `conversation`: non-mutating discussion, read-only exploration, and planning in chat; edits or other state-changing work require switching to `workflow` or `strict-workflow` first.
 - `workflow`: default for consequential work; use the workflow spine and scale detail to risk.
 - `strict-workflow`: high-risk or hard-to-reverse work with stronger gates.
 
@@ -16,7 +16,7 @@ Use strict-workflow for security, privacy, billing, public APIs, migrations, dat
 flowchart LR
   Request{request}
   Talk[conversation<br/>answer directly]
-  Discover[discover<br/>research / grill]
+  Discover[discover<br/>checkpoint]
   Spec[spec]
   Plan[plan]
   Build[build<br/>execute / diagnose]
@@ -29,7 +29,7 @@ flowchart LR
   Check -. new evidence or failed check .-> Discover
 ```
 
-The map is orienting, not mandatory. Small reversible work can skip unnecessary artifacts and gates.
+The map is orienting, not mandatory. Small reversible work can skip unnecessary artifacts and gates. Use `/discover` for the discovery loop.
 
 ## Backward Edge
 
@@ -40,7 +40,7 @@ flowchart LR
   Trigger{new evidence<br/>conflict<br/>failed check<br/>owner decision}
   Decide{changes<br/>next action?}
   Continue[continue]
-  Reenter[clarify / research<br/>revise spec or plan<br/>diagnose / split / stop]
+  Reenter[clarify / discover<br/>revise spec or plan<br/>diagnose / split / stop]
 
   Trigger --> Decide
   Decide -->|no| Continue