@hassangameryt/freeflow 0.3.0 → 0.5.0

package/.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "freeflow",
-  "description": "Lightweight workflow for coding agents.",
+  "description": "Feedback-based control system for coding agents.",
   "owner": {
     "name": "Hassan Mohiddin",
     "url": "https://github.com/hassan-mohiddin"
@@ -9,10 +9,10 @@
   "plugins": [
     {
       "name": "freeflow",
-      "description": "Conversation, workflow, and strict-workflow skills for coding agents.",
-      "version": "0.3.0",
+      "description": "Feedback-based control for coding agents.",
+      "version": "0.5.0",
       "category": "development",
-      "source": ".",
+      "source": "./",
       "author": {
         "name": "Hassan Mohiddin"
       },

package/.claude-plugin/plugin.json

@@ -1,19 +1,23 @@
 {
   "name": "freeflow",
-  "description": "Lightweight workflow for coding agents. Conversation, workflow, and strict-workflow skills for planning, execution, review, verification, handoff, and decision capture.",
-  "version": "0.3.0",
+  "description": "Freeflow gives coding agents an Interaction Contract, evidence-driven Workflow, focused methods, and durable task memory across conversation, workflow, and strict-workflow modes.",
+  "version": "0.5.0",
   "author": {
     "name": "Hassan Mohiddin"
   },
   "homepage": "https://github.com/hassan-mohiddin/freeflow",
   "repository": "https://github.com/hassan-mohiddin/freeflow",
   "license": "MIT",
+  "skills": "./skills/",
   "keywords": [
     "workflow",
     "skills",
     "agents",
+    "feedback-loop",
+    "task-memory",
     "planning",
     "verification",
+    "review",
     "claude-code",
     "codex"
   ]

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "freeflow",
-  "version": "0.3.0",
-  "description": "Lightweight workflow for coding agents.",
+  "version": "0.5.0",
+  "description": "Feedback-based control system for coding agents.",
   "author": {
     "name": "Hassan Mohiddin"
   },
@@ -12,23 +12,23 @@
     "workflow",
     "skills",
     "agents",
+    "feedback-loop",
+    "task-memory",
     "planning",
     "verification",
+    "review",
     "codex",
     "claude"
   ],
   "skills": "./skills/",
+  "hooks": "./hooks/hooks.json",
   "interface": {
     "displayName": "Freeflow",
-    "shortDescription": "Lightweight workflow for coding agents.",
-    "longDescription": "Freeflow guides coding agents through conversation, workflow, and strict-workflow modes with interview gates, source-truth checks, planning, execution, review, verification, commit discipline, handoffs, and durable decision capture.",
+    "shortDescription": "Feedback-based control for coding agents.",
+    "longDescription": "Freeflow gives coding agents an Interaction Contract, evidence-driven Workflow, focused methods, and durable task memory across conversation, workflow, and strict-workflow modes.",
     "developerName": "Hassan Mohiddin",
     "category": "Coding",
-    "capabilities": [
-      "Interactive",
-      "Read",
-      "Write"
-    ],
+    "capabilities": ["Interactive", "Read", "Write"],
     "defaultPrompt": [
       "Use Freeflow workflow mode for this task.",
       "Keep this in conversation mode.",

package/README.md

@@ -1,73 +1,139 @@
 # Freeflow
 
-Lightweight workflow for coding agents.
+**A feedback-based control system for coding agents.**
 
-Agent workflow tools tend to choose one side of the problem: sharp point skills, full lifecycle methodology, or enforcement-heavy runtimes. The missing layer is a small workflow spine that prevents silent product decisions, source-truth rewrites, fake verification, and messy handoffs without turning every change into a process operating system.
+Freeflow helps coding agents move through consequential work without a rigid pipeline, silent decisions, or context-heavy ceremony.
 
-## Workflow
+> Use feedback to choose the smallest useful next action.
+>
+> Re-enter the narrowest owning activity when evidence changes the path.
+>
+> Memory preserves context. It does not create authority.
 
-Freeflow is a workflow layer, not a new agent. It helps the agent choose the right amount of process for the task.
+The active agent still does the work. Freeflow supplies the interaction contract, workflow routing, focused methods, task memory, and evidence discipline that help it decide what to do next—and when not to edit.
 
-### Modes
+## Why Freeflow
 
-- `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.
+Coding agents are strong at mutation and weak at control boundaries:
 
-Use strict-workflow for security, privacy, billing, public APIs, migrations, data loss, compatibility, permissions, deployment, or irreversible architecture.
+| Common failure | Freeflow response |
+| --- | --- |
+| A question or tentative idea becomes an edit. | The Interaction Contract answers first and waits for clear action authority. |
+| A prompt conflicts with tests, policy, or accepted behavior. | Decision Gate names the conflict and stops before mutation. |
+| Work follows a plan after evidence invalidates it. | Workflow routes from evidence and preserves unaffected work. |
+| Every task gets a spec, plan, review, and status ceremony. | Workflow enters at the narrowest useful owner and creates artifacts only when they help. |
+| A passing command becomes an unsupported completion claim. | Verify Work matches direct evidence to the exact claim and boundary. |
+| Review findings are treated as commands. | The active agent adjudicates; corrections require existing or explicit authority. |
+| Compaction loses task state or imports stale branch authority. | Track Work restores the complete Working Record and reconciles it with the current conversation and live repo. |
+| Large search, logs, and test output consume the context window. | Pi's optional Output Router returns focused evidence with exact recovery where configured. |
 
-### Map
+Freeflow is not a new agent or workflow engine. It is a portable control layer for Codex, Claude Code, Pi, and similar coding environments.
 
-```mermaid
-flowchart LR
-  Request{request}
-  Talk[conversation<br/>answer directly]
-  Discover[discover<br/>research checkpoint]
-  Spec[spec]
-  Plan[plan]
-  Build[build<br/>execute / diagnose]
-  Check[review + verify]
-  Close[commit / handoff]
+## The Control System
 
-  Request -->|question| Talk
-  Request -->|work| Discover
-  Discover --> Spec --> Plan --> Build --> Check --> Close
-  Check -. new evidence or failed check .-> Discover
-```
+One user interaction is an **Interaction Lifecycle**:
 
-The map is orienting, not mandatory. Small reversible work can skip unnecessary artifacts and gates.
+![Freeflow Workflow: Entry, Feedback Loop, and Supported Exit](assets/workflow.png)
 
-### Backward Edge
+```text
+[Entry] -> [Feedback Loop when needed] -> [Supported Exit]
+   ^              ^        |                  |
+   |              |________|                  |
+   |__________________________________________|
+            later user turn or evidence
+```
 
-Loop back when new evidence changes the path:
+When work is needed, the inner **Feedback Loop** is:
 
-```mermaid
-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]
+![Freeflow Core Feedback Loop: orient, use the owning skill, verify, self-review once, and route from evidence](assets/feedback-loop.png)
 
-  Trigger --> Decide
-  Decide -->|no| Continue
-  Decide -->|yes| Reenter
-  Reenter -. resume .-> Decide
+```text
+orient to accepted intent, task memory, and live evidence
+-> use the narrowest owning skill
+-> implement, discuss, test, or observe
+-> verify what the evidence proves
+-> when supported, self-review once
+-> continue, correct, diagnose, revise, ask, defer, or stop
 ```
 
-The agent should not silently choose the backward destination when the choice changes product behavior, scope, compatibility, public APIs, security, privacy, billing, data loss, permissions, or irreversible architecture.
+A Supported Exit may answer, wait, pause, hand off, defer, stop, preserve a controlled boundary, or complete. Freeflow does not invent another phase merely because one exists in the full skill pack.
+
+## Core Principles
+
+- **The active agent owns the current route.** Independent review may add judgment; it does not take over routing or verification.
+- **Verification is factual. Review is judgment.** The active agent verifies; self-review is silent; selected independent review uses a separate context.
+- **Pass is not the only review exit.** Pass, Non-blocking, Inconclusive, and Blocking all end review and return evidence to Workflow.
+- **Review findings do not authorize edits.** Ask for unapproved corrections and any warranted focused follow-up together.
+- **Specs and Plans have separate jobs and separate reviews.** Working Records carry evolving state; Plans remain stable ordered strategy.
+- **A slice may span several feedback iterations.** Extend its boundary write-ahead only while the intended result remains coherent.
+- **Diagnose before redesigning.** Ordinary mistakes do not prove structural failure.
+- **Bypass skips optional pressure, not authority, safety, evidence, or selected review.**
+
+## Modes
+
+Freeflow has exactly three modes:
+
+| Mode | Use for | Guardrail |
+| --- | --- | --- |
+| `conversation` | Discussion, critique, explanation, and read-only exploration | Agent-performed mutation requires switching mode. |
+| `workflow` | Normal consequential or mutating work | Use the adaptive lifecycle and proportionate evidence. |
+| `strict-workflow` | High-risk or hard-to-reverse work | Stronger decision, evidence, and checkpoint pressure without review after every slice. |
+
+Task type and direct skill calls do not silently switch mode.
+
+## Skills And Routing
+
+Freeflow ships 25 model/contributor skills to Codex, Claude Code, and Pi. The Pi package also includes Output Router as a separately packaged optional capability; it is not part of Codex or Claude skill discovery or lifecycle context.
+
+See the [typed skill routing map](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/skill-routing.md) for every owner, sibling route, and reference dependency. See [Workflow](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/workflow.md) for the lifecycle and [Architecture](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/architecture.md) for delivery and configuration.
+
+## Task Memory Without A Second Task System
+
+Track Work maintains one Working Record for an ongoing task:
 
-### Bypass
+- current context;
+- one current slice;
+- ordered proposed slices;
+- task-local decisions and hypotheses;
+- evidence pointers and completed history;
+- one next useful action;
+- optional inert Notes.
 
-Bypass skips ceremony, not judgment.
+It records state transitions, not every edit or comment. Routine in-slice feedback is not checkpoint history. After compaction, summarization, clear, resume, or session navigation, Workflow reads the complete record before continuing and treats it as memory rather than authority.
 
-Use `bypass` only to skip an unnecessary gate. It does not skip user-owned decisions, source-truth conflicts, risky checks, or fresh verification before completion claims.
+## Context Is For Decisions, Not Dumps
+
+In Pi, the optional Output Router keeps noisy evidence recoverable without forcing all of it into model context.
+
+| Need | Use |
+| --- | --- |
+| Search repo, explicit local sources, or routed evidence | `freeflow_search` |
+| Run noisy tests, builds, typechecks, logs, or diagnostics | `freeflow_run` |
+| Run independent searches/checks and aggregate facts | `freeflow_batch` |
+| Compute bounded subsets or statistics | `freeflow_search action=transform` |
+| Inspect configuration, vault, routing, or adapters | `freeflow_status` |
+| Read a known file or run a tiny exact command | Native host tools |
+
+Output Router is disabled by default and available only through the Pi extension. Enable it explicitly through Pi's `/output-router` surface.
+
+## Evidence, Not Marketing Certainty
+
+Historical v0.1 workflow fixtures and current router benchmarks remain reproducible evidence, not universal guarantees. The current adaptive skill candidate is **Unverified** pending baseline-vs-with-skill behavioral evaluation.
+
+| Evidence | Result |
+| --- | --- |
+| Historical v0.1 acceptance suite | 15/15 fixtures passed after measured fixes. |
+| Historical source-truth conflict pressure | Baseline 2/10; with-skill 10/10. |
+| Retrieval benchmark | 7/7 gated fixtures; 98.54% weighted context reduction. |
+| Command-output benchmark | 8/8 fixtures with exact recovery; 85.03% weighted reduction. |
+| Pi observed-routing eval | 28/28 objective gates; 82.2% overall byte reduction. |
+
+See [release evidence](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/release-evidence.md) for boundaries, reports, and deferred checks.
 
 ## Install
 
 ### Codex
 
-Register the GitHub repo as a Codex marketplace, refresh it, then install Freeflow:
-
 ```bash
 codex plugin marketplace add https://github.com/hassan-mohiddin/freeflow.git
 codex plugin marketplace upgrade freeflow
@@ -75,151 +141,148 @@ codex plugin add freeflow@freeflow
 codex plugin list | rg freeflow
 ```
 
-In the Codex app, add the same GitHub marketplace URL from `/plugins`, then search for `freeflow`.
+Trust the Freeflow `SessionStart` hook from `/hooks` when Codex requests review, then start a new session so skills and lifecycle context load from the installed plugin.
 
 ### Claude Code
 
-Register the marketplace:
-
 ```bash
 /plugin marketplace add hassan-mohiddin/freeflow
 /plugin install freeflow
+/reload-plugins
 ```
 
-Or install directly from GitHub:
-
-```bash
-/plugin install hassan-mohiddin/freeflow
-```
+Start a new session after first install when the current session predates the plugin.
 
-### Pi Coding Agent
-
-Install Freeflow as a native Pi package from npm:
+### Pi
 
 ```bash
 pi install npm:@hassangameryt/freeflow
 ```
 
-Or install directly from GitHub:
+Or:
 
 ```bash
 pi install git:github.com/hassan-mohiddin/freeflow
 ```
 
-For local development from this checkout:
-
-```bash
-pi install .
-```
-
-The Pi package exposes Freeflow skills and a small extension that registers direct Freeflow commands and loads mode-contract, workflow, interview-gate, discover, and output-router context before agent turns.
+## Activate In A Repository
 
-### Required Step 1: Run Setup
-
-**Run this in every repo after installing Freeflow:**
+Run:
 
 ```text
 /setup-freeflow
 ```
 
-Setup creates the repo activation file and `.freeflow/config.json`. It does not create repo-local hooks, docs inventories, state files, handoffs, or `.codex/rules` behavior files.
-
-After successful setup, the setup skill reads the mode-contract, workflow, interview-gate, discover, and output-router skills before its final response so the current session can continue with Freeflow loaded.
+Minimal setup creates shared activation:
 
-### Required Step 2: Enable Hooks
+```json
+{
+  "defaultMode": "workflow"
+}
+```
 
-**In Codex, open the hooks screen and trust the Freeflow `SessionStart` hook:**
+Configuration layers are:
 
 ```text
-/hooks
+host session mode override
+-> .freeflow/local.json personal core override
+-> .freeflow/config.json shared repository value
+-> built-in default
 ```
 
-Press `t` to trust/enable the hook when Codex marks it as needing review.
+`.freeflow/config.json` is required. `.freeflow/local.json` is optional and cannot activate Freeflow by itself. Pi stores session overrides in branch-aware session JSONL; Claude and Codex store mode overrides in plugin-owned data keyed by host session ID. Session controls do not mutate config files and cannot bypass missing or invalid repository activation. Setup does not write Freeflow instructions into `AGENTS.md`, `CLAUDE.md`, or host rule files.
 
-Once enabled, the hook loads Freeflow mode-contract, workflow, interview-gate, discover, and output-router context at session start, resume, clear, and compact.
+## Runtime Delivery
 
-In Pi, Freeflow's package extension provides the context-loading hook through Pi lifecycle events. It refreshes workflow context on session start and compact, then injects it before agent turns. If you install it project-locally, trust the project when Pi prompts for project-local package resources.
+When effective, host adapters deliver:
 
-These hooks do not run after every edit, block tools, grant permissions, or enforce workflow policy.
+- `runtime/interaction-contract.md` as developer context for compact turn interpretation;
+- one `skills/workflow/SKILL.md` bootstrap per context epoch while Skills are effective;
+- compact active or dormant mode state.
 
-### Other Agents
+Mode Contract and other skills remain on demand. Hooks load context only; they do not enforce policy, block tools, grant permissions, or replace repo instructions.
 
-Copy the `skills/` directory into the agent's skills/plugin system and make sure the agent can read `SKILL.md` files with bundled `references/`.
+Pi appends effective compact context before agent turns and stores Workflow as one hidden persistent session message. Codex and Claude use one packaged runtime hook: `SessionStart` restores the complete enabled context after startup, resume, clear, and compact; `UserPromptSubmit` emits only for an explicit session-mode control and stays silent on ordinary prompts. Claude uses a bounded host-process-scoped, one-shot lifecycle handoff to retain an override when `/clear` changes the host session identifier. Their hook never exposes Output Router. Setup reports automatic delivery as confirmed, unavailable, or unconfirmed.
 
-## Usage
+## Commands
 
-Use natural language first:
+Natural language is preferred. Pi registers these canonical direct calls:
 
 ```text
-Use Freeflow workflow mode for this task.
-Keep this in conversation mode.
-Use strict-workflow for this billing change.
-Verify before claiming completion.
-Create a research checkpoint.
-```
-
-Slash-style prompts are model-routed in Codex and Claude:
-
-```text
-/workflow conversation
-/workflow workflow
-/workflow strict-workflow
-/workflow reset
-/research
+/discuss
+/track-work
 /write-spec
 /review-artifact
 /write-plan
-/execute-plan
+/execute-work
+/simplify-code
+/migration-work
 /diagnose-failure
 /verify-work
 /review-work
 /commit-work
 /handoff
+/finish-branch
+/release-work
+/launch-work
 /bypass
-/output-router
 ```
 
-For Codex and Claude, these commands work as skill-routing language. In Pi, the package extension registers native command handlers for Freeflow commands. Pi `/workflow` mode changes are session-scoped and update the footer; `.freeflow/config.json` remains the repo default only.
+Pi-only compatibility aliases:
+
+```text
+/discover
+/execute-plan
+```
+
+Contributor calls:
 
-## Docs
+```text
+/setup-freeflow
+/write-skill
+/evaluate-skill
+```
 
-- [Docs index](plugin-docs/README.md)
-- [Workflow](plugin-docs/workflow.md)
-- [Skills](plugin-docs/skills.md)
-- [Architecture](plugin-docs/architecture.md)
-- [Release evidence](plugin-docs/release-evidence.md)
-- [ADRs](plugin-docs/adr/README.md)
+Mode controls:
 
-## Evidence
+```text
+/freeflow mode conversation
+/freeflow mode workflow
+/freeflow mode strict-workflow
+/freeflow mode reset
+```
 
-Freeflow does not claim to beat Matt Pocock's skills or Obra's Superpowers. Those are references for skill sharpness and lifecycle discipline. Current evals compare baseline agent behavior against Freeflow instructions/skills, then verify command coverage.
+Pi-native settings controls:
 
-| Report | Baseline | With Freeflow | What It Shows |
-| --- | ---: | ---: | --- |
-| v0.1 acceptance suite | - | 15/15 pass | Required release behaviors passed after measured fixes. |
-| Always-on source-truth conflict | 2/10 | 10/10 | Freeflow stopped a pressured billing rewrite, made no edits, named the conflict, and asked for the policy decision. |
-| Write spec from stale handoff | 4/10 | 10/10 | Freeflow refused to supersede billing policy from stale handoff text. |
-| Write plan with hidden billing decision | 4/10 | 10/10 | Freeflow created no plan, named the policy conflict, and asked which path to follow. |
-| Cold spec call without context | 2/10 | 10/10 | Freeflow did not invent onboarding behavior from adjacent files. |
-| Workflow context lifecycle | fail | pass | Setup loads workflow context for the same session; session-start hooks load workflow context without `PostToolUse`. |
-| Output router retrieval | - | 7/7 pass | Deterministic router evidence fixes generated-artifact false positives while keeping scanner retrieval default. |
-| Output router run recovery | - | 8/8 pass + script-producer unit coverage | `freeflow_run` preserves exact facts and verifies raw vault recovery for routed command output; sandboxed script producers capture stdout/stderr through the same run pipeline. |
-| Codex Structured Q&A | native proxy 0/1 | improved router 1/1 | Sandbox Permissions Q&A resolves to the source markdown instead of a generated `graphify-out` decoy. |
-| Command surface audit | - | Pass | 4 mode commands, 12 direct skill calls, and 3 developer skill calls are covered while native slash handlers remain disabled for Codex/Claude. |
+```text
+/freeflow
+/output-router
+```
+
+Pi `/freeflow settings` edits personal core overrides, `/freeflow settings session` manages temporary core and mode overrides, and `/freeflow settings repo` edits shared settings. For session mode, Pi uses `/freeflow mode <mode|reset>`, Claude uses `/freeflow:mode-contract <mode|reset>`, and Codex uses `$mode-contract <mode|reset>`. Clear natural-language instructions such as “Switch to conversation mode” use the same host-managed session control; questions and hypotheticals do not.
+
+Claude exposes plugin skills as namespaced commands such as `/freeflow:discuss`; Codex exposes them through `/skills` and `$discuss`. Freeflow uses these host-native skill surfaces instead of duplicate manifest command handlers. Direct skill calls select a method. They do not change mode unless they invoke the mode control, authorize mutation, or create independent review context.
+
+A request to change the **default** is separate. Explicit local/personal wording targets `.freeflow/local.json`; explicit repository/shared/team wording targets `.freeflow/config.json`. An unqualified “change the default mode” request requires one local-versus-repository clarification before editing.
 
-Eval sources and reports live with the plugin under `evals/`; generated run output is ignored. Concise release evidence is summarized in [plugin-docs/release-evidence.md](plugin-docs/release-evidence.md).
+## Public Docs
+
+- [Docs index](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/README.md)
+- [Workflow](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/workflow.md)
+- [Skill routing](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/skill-routing.md)
+- [Architecture](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/architecture.md)
+- [Output Router](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/output-router.md)
+- [Release evidence](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/release-evidence.md)
+- [Release ADRs](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/adr/README.md)
 
 ## What Freeflow Is Not
 
 - Not a new agent.
-- Not a CLI framework.
-- Not an enforcement hook system.
+- Not a mandatory phase pipeline.
+- Not a CLI enforcement framework.
+- Not a replacement for repository instructions, tests, policies, or review culture.
 - Not old Orchestra with a smaller README.
-- Not a replacement for Matt's skills or Superpowers.
-
-The shipped hooks are context-loading only. They do not enforce policy, block tools, or replace repo instructions.
-
-Freeflow is the lightweight workflow layer between point skills and full process systems.
+- Not proof that the current candidate is behaviorally ready.
 
 ## License
 

package/{skills → capabilities}/output-router/SKILL.md

@@ -1,32 +1,32 @@
 ---
 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.
+description: Use after the Workflow, Decision Gate, or Discuss route is clear when choosing between native tools and Freeflow routed tools, retrieving repo/local/vault evidence, transforming bounded evidence, handling unknown-size or broad output, running likely-large/noisy commands, recovering vaulted output, tuning outputRouter/observedRouting/scriptTransform after setup, 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.
+Freeflow tools are the safe first choice for unknown-size, exploratory, repo-wide, generated/log-adjacent, structured, or likely noisy output, including broad `rg`/`find`/`git`/help/docs scans. Native tools stay direct for known-small, exact, intentionally raw, or mutating work. A post-hoc cap such as `head`, `sed -n`, `tail`, or `wc` does not make a broad producer known-small.
 
-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.
+Output Router does not classify the task. Workflow, Decision Gate, or Discuss decides whether to answer, ask, explore, 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`.
+- Existing repo, explicit local, or 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`.
+- Known whole file, intentionally exact shell behavior, cmux/Pi control probes, explicit fallback after a routed-source limitation, or edits: use native `read`, `bash`, `edit`, or `write`.
 
-When unsure how much output will return, use Freeflow first.
+When unsure how much output will return, use Freeflow first. Bound the producer before using native tools; do not rely on trimming the output after a broad command runs.
 
 ## `freeflow_search`: Existing Data
 
-Use `freeflow_search` for repo files and vaulted output that already exists.
+Use `freeflow_search` for repo files, explicit external local files, and vaulted output that already exists.
 
 Actions:
 
@@ -36,9 +36,9 @@ Actions:
 - `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.
+- `transform`: compute facts or deterministic subsets from repo/local/vault/file/output data.
 
-Use `source.kind="repo"` for the current checkout. Use `source.kind="vault"` for previous Freeflow outputs.
+Use `source.kind="repo"` for the current checkout. Use `source.kind="local"` for external local docs/files with an explicit absolute `root` and optional relative `path`; do not put local roots in shared config. Use `source.kind="vault"` for previous Freeflow outputs.
 
 Vault search patterns:
 
@@ -68,7 +68,7 @@ Prefer deterministic operations when enough:
 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.
+- `script` without `operation` runs the processing-engine script path over repo/local/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.
@@ -121,7 +121,7 @@ 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.
+- gather multiple repo/local/vault facts without injecting every child result.
 
 Do not use batch for:
 
@@ -137,10 +137,12 @@ Child outputs remain in `details.result.steps`; exact child run output remains r
 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.
+- `bash`: expected-small exact shell behavior, host access, cmux/Pi control probes, or bounded producer behavior 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.
+Native `bash`/`read` remain valid for known-small exact checks, cmux/Pi control probes, exact file reads, or explicit fallback after a routed-source limitation; name the limitation and keep the fallback narrow.
+
+Do not run broad native commands just to see what comes back. `head`, `sed -n`, `tail`, `wc`, or similar output caps bound visible text, not producer scope or relevance. Likely-large native commands include repo-wide `rg`, `grep -R`, `find`, package scans, generated-artifact scans, docs/help 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.
 
@@ -191,12 +193,14 @@ When line numbers are unknown, use `query` or `get` first. Use `expand` when a r
 
 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:
+Use Pi's `/output-router enable` or repository settings surface for initial enablement. Read [setup guidance](references/setup.md) before repairing capability config or changing optional routing features. After valid setup, Output Router owns explicit operational tuning requested through its capability surface.
+
+Persist operational config only after an explicit tuning request or a previously accepted setup branch:
 
 - `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.
+- `outputRouter.observedRouting`: explicit MCP servers and web/fetch/codeSearch producer persistence.
+- `outputRouter.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.
+Read [the safety policy](references/safety-policy.md) before changing routing policy, reviewing router behavior, or handling exactness-sensitive output.

package/{skills → capabilities}/output-router/references/safety-policy.md

@@ -37,4 +37,4 @@ Exactness-sensitive output includes:
 - 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.
+- This policy does not replace host permissions, sandboxing, approvals, or workflow/decision gates.