@hassangameryt/freeflow 0.2.0 → 0.3.0

package/skills/output-router/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: output-router
+description: Use after the workflow, interview-gate, or discover route is clear when choosing between native tools and Freeflow routed tools, retrieving repo/vault evidence, transforming bounded evidence, handling unknown-size or broad output, running likely-large/noisy commands, recovering vaulted output, configuring outputRouter/observedRouting/scriptTransform, or handling optional native read/bash safety-net routing.
+---
+
+# Output Router
+
+Choose how evidence moves into context.
+
+Freeflow tools are the safe first choice for unknown-size, exploratory, repo-wide, generated/log-adjacent, structured, or likely noisy output. Native tools stay direct for known-small, exact, intentionally raw, or mutating work.
+
+Output Router does not classify the task. Workflow, Interview Gate, and Discover decide whether to answer, ask, discover, plan, or stop. Output Router starts after that route is clear.
+
+## First Decision
+
+Ask what kind of data you need:
+
+- Existing repo/vault data: use `freeflow_search`.
+- New command or script-produced output: use `freeflow_run`.
+- Several independent Freeflow operations: use `freeflow_batch`.
+- Config/status/vault/script-adapter facts: use `freeflow_status`.
+- Enabled MCP/web/fetch/code-search output: call the host tool directly; Pi observed routing runs after the host result when configured.
+- Known whole file, intentionally exact shell behavior, or edits: use native `read`, `bash`, `edit`, or `write`.
+
+When unsure how much output will return, use Freeflow first.
+
+## `freeflow_search`: Existing Data
+
+Use `freeflow_search` for repo files and vaulted output that already exists.
+
+Actions:
+
+- `locate`: find likely paths/output ids first. Use before reading when you only need candidates.
+- `query`: return the best focused evidence packets for a search question.
+- `get`: user gave exact-ish text/code/snippet or asks “where is this?” Find the best match and return source coordinates plus matched content.
+- `retrieve`: you already know the path/outputId and line range. Return those exact lines. Do not use this as search.
+- `expand`: widen a previous evidence packet.
+- `explain`: explain a previous routed decision or vault output/recoverability.
+- `transform`: compute facts or deterministic subsets from repo/vault/file/output data.
+
+Use `source.kind="repo"` for the current checkout. Use `source.kind="vault"` for previous Freeflow outputs.
+
+Vault search patterns:
+
+- Unknown output id: `source.kind="vault"` without `outputId`, plus `query` and optional `filters`.
+- Known output id and unknown line: `action="query"` or `get` with `source.outputId`.
+- Known output id and known line range: `action="retrieve"` with `lineRange`.
+- Metadata-only result: use `action="explain"`; do not claim raw recovery.
+
+Use `preserve="full"` only when exact fidelity matters. It still means exact-under-caps, not unlimited context injection.
+
+## `freeflow_search action=transform`: Processing Existing Data
+
+Use transform when raw data is too large/structured and you need computed facts.
+
+Good transform cases:
+
+- logs: status counts, error rates, slow examples,
+- JSON/CSV: counts, groupings, top values, extracted fields,
+- test/build/typecheck output already in the vault,
+- MCP/web/fetch/code-search payloads already routed into the vault,
+- deterministic regex filtering, match counts, grouping, dedupe, topN, URL/citation extraction, line/size stats.
+
+Prefer deterministic operations when enough:
+
+- `regexFilter`, `countMatches`, `jsonExtract`, `groupByRegex`, `dedupe`, `topN`, `extractUrls`, `extractCitations`, `lineStats`, `sizeStats`.
+
+Use scripts only when deterministic operations cannot express the fact:
+
+- `operation.kind="script"` runs a sandboxed transform over vault sources.
+- `script` without `operation` runs the processing-engine script path over repo/vault sources.
+- Sandboxed scripts require `scriptTransform.enabled=true` and a proof-backed adapter.
+- Raw script code is not persisted; metadata stores hashes/labels/limits.
+- No sandboxed script path may silently fall back to host shell execution.
+
+Unsafe unsandboxed processing is local-only, explicit per call, and only through the processing script policy. It must say `unsafe/unsandboxed`. Never put that opt-in in shared config.
+
+## `freeflow_run`: New Output
+
+Use `freeflow_run` when the producer creates new output and routed evidence is enough.
+
+Base producers are mutually exclusive:
+
+- `command`: shell command through the host-approved runner.
+- `script`: sandboxed code-as-producer with no repo/home/env/network/vault access.
+
+Use `command` for:
+
+- tests, builds, lint, typecheck, CI-like checks,
+- broad shell search with unknown output size,
+- commands likely to print logs, JSON, status, or diagnostics,
+- commands whose exact raw output may need recovery.
+
+Use `script` for:
+
+- generating data with code when no repo/home/env/network access is needed,
+- safe code-as-producer execution through the same sandbox engine as transforms,
+- stdout/stderr capture that should route like command output.
+
+Do not use `freeflow_run script` when the code needs repo files, environment variables, network, package imports, or host filesystem access. Use a host command intentionally, or transform an explicitly captured source.
+
+Run modifiers:
+
+- `goal`: tell the router why the run exists, e.g. `verification`, `diagnosis`, `build`, `log analysis`.
+- `filters`: deterministic line filtering over captured stdout/stderr/combined.
+- `scriptFilter`: sandboxed script over already captured stdout/stderr/combined. It never reruns the base producer.
+- `preserve="full"`: request exact output under caps with vault recovery over cap.
+
+Run storage:
+
+- Default `hybrid-dedupe` stores exact output when exactness-sensitive and metadata-only for small non-sensitive successes.
+- Failures, verification/test/build/typecheck/diagnosis output, `preserve="full"`, filters, script filters, reducers, script producers, and large/noisy output are exactness-sensitive.
+- Exact duplicates may store current metadata pointing to a previous exact `outputId`.
+- Plain metadata-only records get rerun guidance, not exact recovery claims.
+
+## `freeflow_batch`: Independent Freeflow Work
+
+Use `freeflow_batch` when several Freeflow-owned `run` or `search` steps can happen independently.
+
+Good batch cases:
+
+- run several bounded searches in parallel,
+- run independent checks and ask `queries[]` to extract facts from child evidence,
+- gather multiple repo/vault facts without injecting every child result.
+
+Do not use batch for:
+
+- sequenced workflows,
+- arbitrary external tool orchestration,
+- mutating work,
+- steps where one child needs another child’s output.
+
+Child outputs remain in `details.result.steps`; exact child run output remains recoverable by child `outputId`.
+
+## Native Tools
+
+Use native tools when direct behavior is the point:
+
+- `read`: known whole file or exact direct file content is intended.
+- `bash`: expected-small exact shell behavior or host access is intentionally needed.
+- `edit` / `write`: mutations.
+
+Do not run broad native commands just to see what comes back. Likely-large native commands include repo-wide `rg`, `grep -R`, `find`, package scans, generated-artifact scans, logs, broad `git diff/log`, full tests/builds/lints/typechecks, and one-off scripts with unknown output size.
+
+If native read/bash safety net is enabled, large/noisy native output may be replaced with labeled Freeflow-routed output. It must include an `outputId` and recovery instructions. If safety-net routing fails, native output passes through with a warning.
+
+## Observed Routing
+
+For enabled Pi MCP/web/fetch/code-search producers, call the host tool directly. Freeflow observes the completed result after host execution.
+
+Observed routing:
+
+- is off by default,
+- is explicit per producer/server,
+- does not grant permissions or block host tools,
+- can persist exact output, metadata-only, or nothing depending on config,
+- fails open with original host output if routing fails.
+
+Mutating MCP/tool calls still require normal workflow/interview judgment before the host call. Observed routing is not permission approval.
+
+## Hard Rules
+
+- Do not pretend routed output is native output.
+- Do not silently shorten native output.
+- Capture raw output before transforming it.
+- Keep raw source recovery separate from transformed/reduced output recovery.
+- Treat `preserve="full"` as exact fidelity under caps, not unlimited context injection.
+- Preserve exact failure and verification evidence lines.
+- Keep `toolStatus`, `execution.status`, and `routing.status` separate.
+- Metadata-only records must never claim exact raw recovery.
+- Freeflow mode changes guidance strength only. It must not enable `postToolRouting`.
+- Do not write removed `capture` or `providers` config.
+- Do not offer `redacted`; it is future-only.
+
+## Recovery Pattern
+
+For routed run/native/observed/transform output, recover exact text with:
+
+```json
+{
+  "action": "retrieve",
+  "source": { "kind": "vault", "outputId": "ffout_...", "stream": "stdout|stderr|combined|raw" },
+  "lineRange": { "start": 1, "end": 20 },
+  "preserve": "full"
+}
+```
+
+When line numbers are unknown, use `query` or `get` first. Use `expand` when a returned evidence packet is too narrow. Use `explain` when recoverability is unclear.
+
+## Config
+
+Use `freeflow_status` to inspect effective config, vault writability/index state, script adapters, observed routing, and migration recommendations.
+
+Persist optional config only after an explicit setup branch/request:
+
+- `outputRouter`: `enabled`, `profile`, `postToolRouting`, `storagePolicy`, thresholds, vault root/retention, generated paths, noisy command hints.
+- `observedRouting`: explicit MCP servers and web/fetch/codeSearch producer persistence.
+- `scriptTransform`: enabled flag, languages, sandbox/network/limits/raw-script persistence.
+
+Minimal setup stays only `defaultMode`. Missing optional sections mean built-in defaults.
+
+Read `references/safety-policy.md` before changing routing policy, reviewing router behavior, or handling exactness-sensitive output.

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

@@ -0,0 +1,40 @@
+# Output Router Safety Policy
+
+Reference-only policy for exactness-sensitive output routing. Pi runtime context does not load this whole file by default; the active `output-router` skill carries the compact rules. Read this file before changing routing policy, reviewing router behavior, or handling a new exactness-sensitive output class.
+
+## Main Rule
+
+Do not silently summarize, compress, or replace exactness-sensitive output.
+
+Exactness-sensitive output includes:
+
+- user-requested exact/full output,
+- small native outputs where direct output is expected,
+- verification output needed for completion claims,
+- failure evidence needed for diagnosis,
+- source-truth conflict evidence,
+- security, privacy, billing, data-loss, permissions, or public API evidence,
+- failed, timed-out, or cancelled run output,
+- script-producer output,
+- filtered, script-filtered, reduced, or transformed output where raw source matters,
+- anything marked `preserve: full`.
+
+## Required Behavior
+
+- Capture raw evidence before transformation whenever output is routed.
+- Label every transformed native or observed result as Freeflow-routed output.
+- Include an `outputId` and exact recovery instructions when exact recovery exists.
+- Preserve exact failure and verification evidence lines; do not paraphrase them.
+- Pass small native outputs through unchanged unless explicit config and thresholds route them.
+- For huge exactness-sensitive output, use vaulting and exact chunk retrieval instead of lossy summarization.
+- If post-tool native safety-net routing fails, fail open: return the native output unchanged when possible and include a warning.
+- Keep raw source recovery separate from transformed/reduced output recovery.
+- Metadata-only records must never claim exact raw recovery. Duplicate metadata may point to a prior exact `outputId`; plain metadata-only records get rerun or explanation guidance.
+
+## Non-Goals
+
+- This policy does not enable post-tool routing by itself.
+- This policy does not authorize model-assisted summarization inside the router runtime.
+- This policy does not authorize unsandboxed script execution.
+- This policy does not require Pi runtime context to inject the full reference every turn.
+- This policy does not replace host permissions, sandboxing, approvals, or workflow/interview gates.

package/{plugins/freeflow/skills → skills}/review-artifact/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-artifact
-description: Use when asked to review whether a spec, plan, decision note, research checkpoint, handoff, or other durable artifact is fit to guide future work; also use when adjudicating artifact-review findings or repeated review loops.
+description: Use when asked to review whether a spec, plan, decision note, discovery checkpoint, handoff, or other durable artifact is fit to guide future work; also use when adjudicating artifact-review findings or repeated review loops.
 ---
 
 # Review Artifact
@@ -54,12 +54,14 @@ Aim to finish by the second review pass: first review, adjudicate/fix, one confi
 
 Three review passes is the hard cap for the same artifact and scope. Do not request a fourth review to chase a clean pass.
 
-At the third review, adjudicate before treating it as failure. If any accepted blocking, question, or needs-evidence finding remains, do not edit anything from that batch. Stop, report the adjudication, and zoom out to diagnose whether research, spec, plan, policies, source truth, artifact scope, or reviewer context is wrong or too thin.
+At the third review, adjudicate before treating it as failure. If any accepted blocking, question, or needs-evidence finding remains, do not edit anything from that batch. Stop, report the adjudication, and zoom out to diagnose whether discovery, spec, plan, policies, source truth, artifact scope, or reviewer context is wrong or too thin.
 
 ## Review Setup
 
 Use a fresh reviewer when the artifact will guide future work and subagents are available. Use [references/reviewer-prompt.md](references/reviewer-prompt.md).
 
+Use `../design-for-depth/SKILL.md` when the artifact encodes module, interface, seam, adapter, architecture, or slice-boundary decisions.
+
 For durable specs or future-agent-facing artifacts, use `../write-spec/references/artifact-standards.md` as the artifact identity standard when relevant.
 
 ## Inspect First
@@ -80,6 +82,7 @@ Live repo evidence overrides stale artifacts.
 - Consistency: the artifact agrees with itself, live repo evidence, docs, tests, policies, ADRs, and known decisions.
 - Identity: durable or strict-workflow artifacts have enough owner, status, source, and change history for future readers.
 - Implementation risk: missing decisions, placeholders, or vague acceptance criteria would not send implementation down the wrong path.
+- Design depth: module, interface, seam, adapter, or slice choices hide useful complexity instead of spreading coordination.
 - Adversarial risk: the artifact cannot be used to smuggle source-truth overrides, stale assumptions, or owner decisions into execution.
 
 Treat missing artifact identity as blocking only when it affects future-agent handoff, team ownership, strict-workflow risk, or implementation readiness. Do not nitpick headers on lightweight artifacts or chat answers.

package/{plugins/freeflow/skills → skills}/review-artifact/references/reviewer-prompt.md

@@ -9,7 +9,7 @@ Artifact:
 [ARTIFACT_PATH]
 
 Artifact type:
-[spec | plan | handoff | decision note | research brief | other]
+[spec | plan | handoff | decision note | discovery note | other]
 
 Source context to inspect:
 [DOCS_TESTS_POLICIES_ADRS_CODE_PATHS]
@@ -30,6 +30,7 @@ Check:
 - Consistency: artifact agrees with itself and source context.
 - Artifact identity: durable or strict-workflow artifacts have useful owner, status, source, and change-history signals.
 - Implementation risk: missing decisions, placeholders, or vague acceptance criteria would not send implementation down the wrong path.
+- Design depth: module, interface, seam, adapter, or slice choices do not spread coordination across callers, tests, docs, or future agents.
 - Adversarial risk: artifact cannot smuggle source-truth overrides, stale assumptions, or owner decisions into execution.
 
 Calibration:

package/{plugins/freeflow/skills → skills}/review-work/SKILL.md

@@ -31,7 +31,7 @@ Aim to finish by the second review pass: first review, adjudicate/fix, one confi
 
 Three review passes is the hard cap for the same work and scope. Do not request a fourth review to chase a clean pass.
 
-At the third review, adjudicate before treating it as failure. If any accepted blocking, question, or needs-evidence finding remains, do not edit anything from that batch. Stop, report the adjudication, and zoom out to diagnose whether research, spec, plan, policies, source truth, implementation, or reviewer context is wrong or too thin.
+At the third review, adjudicate before treating it as failure. If any accepted blocking, question, or needs-evidence finding remains, do not edit anything from that batch. Stop, report the adjudication, and zoom out to diagnose whether discovery, spec, plan, policies, source truth, module/interface design, implementation, or reviewer context is wrong or too thin.
 
 Non-blocking findings and reviewer questions do not fail the work by default. Classify them, then defer, ask, gather evidence, or accept.
 
@@ -45,6 +45,7 @@ Before editing:
 - Separate blocking issues from suggestions.
 - Check whether the feedback matches this codebase.
 - Check whether a finding is stale, already resolved, equivalent, or based on missing context.
+- Check whether repeated findings are design pressure: shallow module, bad seam, edge-case churn, or broad refactor from a narrow comment.
 
 Do not blindly apply vague, broad, or sensitive feedback.
 
@@ -79,6 +80,8 @@ When feedback is clear and correct and the current route is an apply-fixes pass:
 
 Do not apply a non-pass review batch and request another review in the same autonomous loop. Return the adjudication and next route first. A later explicit apply-fixes request can start a bounded fix pass for accepted, in-scope findings.
 
+If accepted findings expose shallow modules, bad seams, or complexity spread, use `../design-for-depth/SKILL.md` and route backward before broad refactoring.
+
 ## Outgoing Review
 
 When reviewing work, lead with bugs, regressions, missing tests, and requirement gaps.
@@ -93,4 +96,6 @@ Review can pass. Do not invent issues to justify the review.
 
 When asking another agent to review, give it source truth, changed files, risk lenses, and pass/fail criteria. Do not hand it only the previous agent's summary or your chat history.
 
+Set review subagent timeouts above 10 minutes; default to 15 minutes (`timeoutMs: 900000`). If a review times out, do not reduce review depth to dodge the timeout. Increase the timeout or ask before narrowing scope.
+
 For second and later review iterations, update the prompt with prior findings, owner clarifications, accepted/rejected findings, changed files, and remaining risk. Do not rerun the same broad prompt after the situation narrows.

package/{plugins/freeflow/skills → skills}/setup-freeflow/SKILL.md

@@ -9,7 +9,7 @@ Use `references/activation-contract.md` before rendering activation text, config
 
 Use `references/host-setup.md` when the request mentions Codex, Claude, both hosts, team setup, solo setup, strict defaults, hooks, CLI, or setup profiles.
 
-Use `references/output-router-setup.md` when setup explicitly asks for output-router repo config, generated-path hints, native safety-net routing, vault settings, or output thresholds.
+Use `references/output-router-setup.md` when setup reaches the optional evidence-routing decision point or asks for output-router/observed-routing/script-transform repo config, generated-path hints, native safety-net routing, vault settings, or output thresholds.
 
 ## Stop Before Editing
 
@@ -50,11 +50,21 @@ Create or update `.freeflow/config.json` using the config adapter in `references
 
 Minimal setup writes only `defaultMode`. Use `workflow` unless the user explicitly asks to persist a valid repo default: `conversation`, `workflow`, or `strict-workflow`.
 
-Optional `outputRouter` config belongs here only when explicitly requested. Read `references/output-router-setup.md` first. Do not add an empty `outputRouter`, dump router defaults, or ask every setup user about router config.
+Ask one optional capabilities decision point after minimal host/config setup: whether to configure evidence routing and script transform adapters beyond the minimal default. If declined, keep the minimal setup path.
 
-If the user asks for router setup but gives no config knobs, say the router works with built-in defaults and ask which optional config they want persisted. Recommend no repo config unless they need a repo-specific hint or native safety-net behavior.
+If accepted, read `references/output-router-setup.md` and ask only path-changing follow-ups: router profile or intentional overrides, observed MCP/web/fetch/code-search producers to enable, persistence for each enabled producer/server, native safety-net policy, and whether to install global script transform adapters. Write high-level decisions and explicit overrides only. Do not add empty `outputRouter`, `observedRouting`, or `scriptTransform` objects, and do not dump effective defaults.
 
-Never enable native safety-net routing by default. `postToolRouting: "safety-net"` requires an explicit request; `strict` is reserved and needs a separate confirmation before writing.
+If the user consents to script transform setup, install adapters globally, not repo-locally. Resolve `../../router/dist/setup/script-transform-adapters.js` relative to this skill file and run:
+
+```sh
+node <plugin-root>/router/dist/setup/script-transform-adapters.js install --config .freeflow/config.json
+```
+
+The installer uses `~/.cache/freeflow-script-adapters` by default, or `FREEFLOW_SCRIPT_TRANSFORM_ADAPTERS_HOME` when set. It installs JavaScript, jq, Python adapter packages, and a JSPI-capable `node@24` support runtime for Python, probes sandbox proofs, and writes `scriptTransform.enabled=true` with only proof-passing languages. Python/Eryx uses the setup-installed child Node process launched with `--experimental-wasm-jspi`; if that runtime cannot run the proofs, report the probe failure instead of claiming Python is enabled.
+
+If the user asks for router setup but gives no config knobs, say the router works with built-in defaults and ask which optional config they want persisted. Recommend no repo config unless they need observed routing, repo-specific hints, script transform setup, or safety-net behavior.
+
+Never enable observed routing or native safety-net routing by default. Observed routing requires explicit producer/server entries and a user-chosen persistence mode for each enabled entry. `outputRouter.postToolRouting: "safety-net"` requires an explicit request; `strict` is reserved and needs a separate confirmation before writing. Script transform may be enabled during setup only after explicit adapter-install/config consent and successful sandbox proof probing.
 
 Do not infer `strict-workflow` from "team", "strict gates", "careful", or high-risk examples. Recommend or ask unless the user explicitly says to make a mode the repo default.
 
@@ -67,9 +77,9 @@ Render the canonical blocks from `references/activation-contract.md`.
 
 For Codex, put the Codex core block in `AGENTS.md`.
 
-For Claude, put only the Claude import block in `CLAUDE.md`, then put the Codex core block text in `.claude/rules/freeflow-core.md`. Do not create a separate Claude rule file for `interview-gate`; plugin runtime loads it.
+For Claude, put only the Claude import block in `CLAUDE.md`, then put the Codex core block text in `.claude/rules/freeflow-core.md`. Do not create separate Claude rule files for `interview-gate` or `discover`; plugin runtime loads them.
 
-Do not list the whole workflow, every mode, or full `interview-gate` skill in always-loaded text. Do not split into multiple always-loaded Freeflow rule files unless the user explicitly confirms that split after the one-file recommendation.
+Do not list the whole workflow, every mode, or full `interview-gate`/`discover` skill in always-loaded text. Do not split into multiple always-loaded Freeflow rule files unless the user explicitly confirms that split after the one-file recommendation.
 
 ## Do Not Create
 
@@ -82,13 +92,15 @@ Plugin-bundled context hooks are installed with Freeflow, not created by repo se
 Before claiming setup is complete, check:
 - config JSON parses
 - minimal config contains only `defaultMode` with the requested explicit default, or `workflow` when no explicit default was requested
-- optional `outputRouter` config appears only when explicitly requested and contains only requested valid keys
-- native safety-net routing is off unless explicitly requested
+- optional `outputRouter`, `observedRouting`, and `scriptTransform` config appears only after the capabilities decision point or explicit request, and contains only requested valid keys
+- observed routing, native safety-net routing, and script transform are off unless explicitly requested and supported
+- every enabled observed-routing producer/server has user-chosen persistence: `exact`, `metadata-only`, or `none`; setup does not offer or write `redacted`
 - Codex setup has exactly one `## Freeflow` block in `AGENTS.md`
 - Claude setup has exactly one `CLAUDE.md` import and one `.claude/rules/freeflow-core.md` core file
+- when script transform setup was accepted, global adapters were installed under the reported adapter home, `freeflow_status` shows available adapters, and `.freeflow/config.json` enables only proof-passing `scriptTransform.languages`
 - `.codex/rules` was not created or changed for Freeflow behavior
 - no unrelated files changed
 
-After successful setup verification, read `../workflow/SKILL.md`, `../workflow/references/workflow-map.md`, and `../interview-gate/SKILL.md` before the final response. Only say workflow and interview-gate context is loaded for this session if all three files were read successfully.
+After successful setup verification, read `../mode-contract/SKILL.md`, `../workflow/SKILL.md`, `../interview-gate/SKILL.md`, `../discover/SKILL.md`, and `../output-router/SKILL.md` before the final response. Only say mode-contract, workflow, interview-gate, discover, and output-router context is loaded for this session if all five files were read successfully.
 
 If verification cannot run, say what remains unverified.

package/{plugins/freeflow/skills → skills}/setup-freeflow/references/activation-contract.md

@@ -10,7 +10,7 @@ Use this Markdown reference as the v0.1 contract module:
 getActivationContract(defaultMode) -> ActivationContract
 planActivation(contract, repoState, request) -> ActivationPlan | ActivationStop
 renderActivation(contract, target) -> rendered text or checks
-planOptionalOutputRouterConfig(request) -> OutputRouterConfigPlan | ActivationStop
+planOptionalEvidenceRoutingConfig(request) -> EvidenceRoutingConfigPlan | ActivationStop
 ```
 
 Do not add a code module until setup behavior needs logic that cannot be kept clear in the skill and this reference.
@@ -19,7 +19,7 @@ Do not add a code module until setup behavior needs logic that cannot be kept cl
 
 - Activation text contains always-on invariants only, not the full workflow spine.
 - Minimal config has exactly one field: `defaultMode`.
-- Optional `outputRouter` config is allowed only when explicitly requested.
+- Optional `outputRouter`, `observedRouting`, and `scriptTransform` config is allowed only after the capabilities decision point or an explicit request. Removed `capture` and `providers` config is not written by setup.
 - Valid defaults are exactly `conversation`, `workflow`, and `strict-workflow`.
 - Default mode is `workflow` unless the user explicitly persists another valid mode.
 - Codex activation writes `AGENTS.md`, not `.codex/rules`.
@@ -28,8 +28,8 @@ Do not add a code module until setup behavior needs logic that cannot be kept cl
 - Existing repo instructions remain source truth.
 - Setup hard-stops before unresolved host ambiguity or repo-rule conflict.
 - Setup does not create repo-local hooks, docs inventories, state files, handoffs, empty `CONTEXT.md`, skill inventories, `setup-output-router` skills, version metadata, activation path, current task, or current phase.
-- Plugin-bundled context hooks may load workflow and interview-gate context at session start, but they are package runtime, not setup output.
-- After successful setup verification, setup reads the workflow skill, workflow map, and interview-gate skill before its final response so the current session is immediately usable.
+- Plugin-bundled context hooks may load mode-contract, workflow, interview-gate, discover, and output-router context at session start, but they are package runtime, not setup output.
+- After successful setup verification, setup reads the mode-contract, workflow, interview-gate, discover, and output-router skills before its final response so the current session is immediately usable.
 
 ## Host Adapters
 
@@ -50,9 +50,10 @@ Config adapter:
 - Create or update `.freeflow/config.json`.
 - For minimal setup, write exactly `{ "defaultMode": "<mode>" }`.
 - Use `workflow` unless the user explicitly asks to persist `conversation` or `strict-workflow`.
-- Add `outputRouter` only when explicitly requested, using `output-router-setup.md`.
-- Missing `outputRouter` means built-in defaults, not a setup warning.
-- Never enable native safety-net routing by default.
+- Add `outputRouter`, `observedRouting`, or `scriptTransform` only after the capabilities decision point or an explicit request, using `output-router-setup.md`. Do not write removed `capture` or `providers` config.
+- Missing `outputRouter`, `observedRouting`, and `scriptTransform` means built-in defaults, not a setup warning.
+- Never enable observed routing or native safety-net routing by default.
+- Observed routing requires explicit producer/server entries and user-chosen persistence: `exact`, `metadata-only`, or `none`. Do not offer or write `redacted`.
 
 ## Codex Core Block
 
@@ -86,14 +87,14 @@ Verify before completion claims. Capture only stable decisions, glossary terms,
 
 ## Drift Checks
 
-Run `plugins/freeflow/evals/scripts/check-activation-contract.sh` when changing setup behavior, post-setup fixtures, setup eval assertions, or docs that quote setup behavior.
-Run `plugins/freeflow/evals/scripts/check-runtime-context-hook.sh` when changing plugin-bundled runtime context hooks.
+Run `evals/scripts/check-activation-contract.sh` when changing setup behavior, post-setup fixtures, setup eval assertions, or docs that quote setup behavior.
+Run `evals/scripts/check-runtime-context-hook.sh` when changing plugin-bundled runtime context hooks.
 
 The check keeps these surfaces aligned:
 
 - this canonical reference
 - `setup-freeflow/SKILL.md`
 - `setup-freeflow/references/host-setup.md`
-- `docs/freeflow-runtime-and-lifecycle.md`
+- `docs/freeflow-runtime-and-lifecycle.md` in the Freeflow development repo
 - post-setup `AGENTS.md` fixtures
 - setup eval assertions that depend on canonical activation text

package/{plugins/freeflow/skills → skills}/setup-freeflow/references/host-setup.md

@@ -16,7 +16,7 @@ Current runtime is not enough to choose a host when both `AGENTS.md` and `CLAUDE
 
 Solo setup is the default: one host target, compact activation, `defaultMode: "workflow"`, no extra docs.
 
-Output-router setup is an opt-in config branch inside normal setup, not a separate host profile. Use `output-router-setup.md`; keep minimal setup config unchanged unless the user explicitly asks for router config.
+Evidence-routing setup is an opt-in config branch inside normal setup, not a separate host profile. Use `output-router-setup.md`; keep minimal setup config unchanged unless the user accepts the capabilities decision point or explicitly asks for output-router/observed-routing/script-transform config.
 
 Team setup still uses compact activation. Add both hosts only if requested. Do not add team standards, onboarding docs, owners, approvers, repo-local hooks, or CLI checks as part of setup unless the user separately asks and the repo has a validated path for them.
 
@@ -28,8 +28,8 @@ Valid persisted defaults are exactly `conversation`, `workflow`, and `strict-wor
 
 Do not install repo-local hooks, CLI commands, lint rules, global standards, docs inventories, setup-output-router skills, or state files during setup.
 
-Freeflow's plugin-bundled context hooks are package runtime. They load workflow and interview-gate context at session start, but setup should not copy hook files into the target repo.
+Freeflow's plugin-bundled context hooks are package runtime. They load mode-contract, workflow, interview-gate, discover, and output-router context at session start, but setup should not copy hook files into the target repo.
 
-After successful setup verification, setup should read the workflow skill, workflow map, and interview-gate skill before the final response. If session-start runtime context does not load in later sessions, tell the user to review/trust the installed Freeflow plugin hooks or start a fresh/compacted session. Do not create repo-local hook files as a workaround.
+After successful setup verification, setup should read the mode-contract, workflow, interview-gate, discover, and output-router skills before the final response. If session-start runtime context does not load in later sessions, tell the user to review/trust the installed Freeflow plugin hooks or start a fresh/compacted session. Do not create repo-local hook files as a workaround.
 
 If the user asks for enforcement, say Freeflow setup is instruction-only for now and ask whether to handle enforcement as a separate task.

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

@@ -0,0 +1,102 @@
+# Output Router Setup
+
+Use this when setup reaches the optional capabilities branch or explicitly asks for output-router, observed-routing, generated-path, native safety-net, vault, threshold, script-transform adapters, or script-transform repo config (`scriptTransform`).
+
+## Defaults
+
+- The output router has built-in defaults. A repo does not need optional config for normal search/run/transform behavior.
+- Minimal `/setup-freeflow` must still write only `defaultMode`.
+- Ask one capabilities decision point. If declined, do not write `outputRouter`, `observedRouting`, or `scriptTransform`, and do not install script adapters.
+- Observed routing is opt-in per producer/server. The user must choose persistence for each enabled entry before setup writes config.
+- Do not create a separate `setup-output-router` skill.
+
+If the user says only “set up the output router” with no requested knobs, say the router works with built-in defaults and ask which optional config they want persisted. Recommend no repo config unless they need observed routing, repo-specific hints, script transform setup, or safety-net behavior.
+
+## Config Shape
+
+Write only keys the user explicitly requests. Do not dump all defaults and do not create empty `outputRouter`, `observedRouting`, or `scriptTransform` objects. Do not write removed `capture` or `providers` config.
+
+Supported high-level repo config keys:
+
+```json
+{
+  "defaultMode": "workflow",
+  "outputRouter": {
+    "enabled": true,
+    "profile": "standard",
+    "postToolRouting": "off",
+    "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" }
+  },
+  "scriptTransform": {
+    "enabled": true,
+    "sandbox": "auto",
+    "languages": ["javascript", "python", "jq"],
+    "network": "off",
+    "limits": {
+      "timeoutMs": 5000,
+      "maxInputBytes": 1048576,
+      "maxOutputBytes": 65536
+    },
+    "rawScriptPersistence": "disabled"
+  }
+}
+```
+
+Rules:
+
+- `outputRouter.enabled` defaults to `true`; write it only as an intentional high-level decision.
+- `outputRouter.profile` currently supports `standard`; write it only when the user chooses the evidence-routing branch.
+- `postToolRouting` defaults to `off`. Use `safety-net` only when explicitly requested. Treat `strict` as reserved; ask before writing it.
+- `largeOutputBytes`, `largeOutputLines`, and `vaultRetentionDays` must be positive integers.
+- `vaultRoot` must be a non-empty string. Repo-local storage requires explicit user choice.
+- `generatedPaths` are broad-scan generated-path hints. Explicit file or directory retrieval must remain available.
+- `noisyCommandHints` is parsed as hint config. Do not add it unless the user explicitly asks for command-pattern hints.
+- `observedRouting.enabled` defaults to `false`; write it only when the user chooses observed routing.
+- `observedRouting.onRoutingFailure` currently supports `fail-open`; write it only when persisting observed routing.
+- `observedRouting.mcp.servers` must contain explicit server entries only. Setup may discover configured servers for a multi-select, but must not persist a volatile inventory of every installed tool.
+- `observedRouting.web`, `observedRouting.fetch`, and `observedRouting.codeSearch` are Pi observed-routing producers. Enable only the producers the user chose.
+- Every enabled observed-routing entry needs a user-chosen persistence mode: `exact`, `metadata-only`, or `none`.
+- Recommend `exact` for public-ish evidence producers such as GitHub, web, fetch, and code search. Recommend `metadata-only` for sensitive or unknown producers such as Gmail, Slack, private customer systems, or likely-secret outputs.
+- Do not offer or write `redacted`; it is reserved for future work and currently falls back to `metadata-only` with a warning if hand-edited.
+- Pi public `freeflow_capture` and the separate `providers` setup surface have been removed. Do not write removed `capture` or `providers` config.
+- `scriptTransform.enabled` defaults to `false`; write it only after an explicit script-execution opt-in.
+- If the user opts into script transform setup and adapters are missing or unavailable, recommend installing global adapters. On consent, resolve `../../router/dist/setup/script-transform-adapters.js` relative to `skills/setup-freeflow/SKILL.md` and run `node <plugin-root>/router/dist/setup/script-transform-adapters.js install --config .freeflow/config.json`.
+- The installer uses `~/.cache/freeflow-script-adapters` by default, or `FREEFLOW_SCRIPT_TRANSFORM_ADAPTERS_HOME` when set. It installs `quickjs-wasi@3.0.1`, `jq-wasm@1.2.0-jq-1.8.2`, `@bsull/eryx@0.5.0`, and `node@24` for the Python JSPI child runner, writes `freeflow-adapter-env.sh`, probes sandbox proofs, and updates `scriptTransform.languages` with only proof-passing languages.
+- Freeflow auto-discovers adapters from that global cache. The explicit roots `FREEFLOW_QUICKJS_WASI_ROOT`, `FREEFLOW_JQ_WASM_ROOT`, and `FREEFLOW_ERYX_ROOT` remain overrides for custom installs.
+- Python/Eryx is installed by setup and uses the setup-installed child Node process launched with `--experimental-wasm-jspi` when the host process lacks JSPI. It must not be marked available unless that child runner passes the required sandbox probes.
+- `scriptTransform.languages` supports `javascript`, `python`, and `jq`; enable only languages whose adapters passed sandbox proofs.
+- `scriptTransform.sandbox` currently supports `auto`, `network` supports only `off`, and `rawScriptPersistence` supports only `disabled`.
+- `scriptTransform.limits.timeoutMs`, `maxInputBytes`, and `maxOutputBytes` must be positive integers within product caps. Per-call script limits may only tighten configured values.
+
+## Verify
+
+After writing optional evidence-routing config, use `freeflow_status` or equivalent direct inspection to verify effective behavior:
+
+- JSON parses.
+- `defaultMode` is valid.
+- Minimal setup still contains only `defaultMode` when capabilities were declined.
+- Optional `outputRouter`, `observedRouting`, and `scriptTransform` sections contain only requested keys.
+- Invalid router/observed-routing/script-transform values are not written.
+- Observed routing, native safety-net routing, and script transform are not enabled unless explicitly requested.
+- If script transform setup was accepted, global adapter install completed or a clear install/probe failure was reported, and enabled languages match proof-passing adapters.
+- No observed-routing entry uses `redacted`, and every enabled entry has explicit persistence.
+- `freeflow_status` shows effective defaults and migration recommendations without rewriting config.
+- No repo-local hooks, skill files, setup-output-router skill, docs inventories, or repo-local storage directories were created.

package/{plugins/freeflow/skills → skills}/verify-work/SKILL.md

@@ -57,6 +57,8 @@ Not verified: ...
 Next: ...
 ```
 
-For completed consequential work, `Next:` is mandatory. Omit it only for direct question answers, mid-task status, or clarification-only turns.
+For completed consequential work, include `Next:` because completion leaves a route decision. Omit it only for direct question answers, mid-task status, clarification-only turns, or direct owner-decision questions.
+
+For pure questions, include `Next:` only when a concrete next route helps.
 
 Keep it short.