@hassangameryt/freeflow 0.2.0 → 0.3.0

package/{plugins/freeflow/skills → skills}/workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workflow
-description: Use when doing consequential work such as implementation, bug fixing, planning, research-for-action, review, verification, or handoff.
+description: Use when doing consequential work such as implementation, bug fixing, planning, discovery-for-action, review, verification, or handoff.
 ---
 
 # Workflow
@@ -12,7 +12,7 @@ Move forward when context is sufficient. Re-enter clarification when new ambigui
 Question means answer. Do not turn a question into a file edit, report, plan, or implementation.
 
 ```text
-Clarify / Research
+Clarify / Discover
 -> Decision / Spec
 -> Plan
 -> Execute
@@ -23,35 +23,37 @@ Clarify / Research
 
 This is a guide, not ceremony. Small reversible work can skip spec/plan artifacts.
 
-Method skills such as TDD, diagnosis, or execute-plan run inside the current workflow phase. Workflow owns routing, source-truth conflicts, user-owned decisions, review, verification, and handoff boundaries.
+Method skills and lenses such as TDD, diagnosis, execute-plan, or design-for-depth run inside the current workflow phase. Workflow owns routing, source-truth conflicts, user-owned decisions, review, verification, and handoff boundaries.
 
 Read `references/workflow-map.md` when the user asks for the full pipeline, public docs need a diagram, or the next workflow entry point is unclear.
 
 ## Route Closeout
 
-When a consequential workflow phase completes, name the next route.
+Use `Next:` to name a helpful next route for the user. It is general routing, not only a workflow-phase label.
 
-Use `Next:` in the final response unless this is a direct question answer, mid-task status, or clarification-only turn.
+Do not add `Next:` to every reply. Questions get answers first; add `Next:` only when the answer leaves a concrete next action, choice, stop condition, or route worth naming.
+
+For completed consequential work or workflow phases, include `Next:` unless this is a direct question answer, mid-task status, clarification-only turn, or the final line must be a direct owner-decision question.
 
 Choose one:
 
-- Forward: the next workflow entry point is clear.
-- Backward: new evidence requires clarification, research, or interview gate.
-- Branch: 2-3 valid next routes exist.
-- Stop: no required next action remains.
+- Forward: the next action or workflow entry point is clear.
+- Backward: new evidence requires clarification, discovery, or interview gate.
+- Branch: 2-3 valid next routes or actions exist.
+- Stop: no useful next action remains.
 
 Recommend the route supported by evidence. Do not ask a vague "what next?" question.
 
-After completed research with decisions that must survive beyond chat, route to `write-spec`, an owning decision artifact, or handoff before `write-plan` or execution.
+After completed discovery with decisions that must survive beyond chat, route to `write-spec`, an owning decision artifact, or handoff before `write-plan` or execution.
 
-`Next:` is routing, not permission to create the next artifact or continue into a new phase.
+`Next:` is routing, not permission to create the next artifact, continue into a new phase, or take the next action.
 
 ## Backward Edge
 
 If new evidence invalidates the current path, re-enter clarification.
 
 ```text
-Any state -> Clarify / Research -> explicit next state
+Any state -> Clarify / Discover -> explicit next state
 ```
 
 Do not silently substitute a different path, rewrite the spec, change the plan, or patch forward. State what changed, then decide whether to continue, revise spec, revise plan, diagnose, split scope, defer, or stop and ask.
@@ -76,7 +78,7 @@ Artifacts are memory, not proof of obedience.
 
 Only create artifacts when the user asks for an artifact or asks you to do work that requires one.
 
-Create them only when they preserve decisions, reduce risk, or help a future agent resume. Prefer short research notes, decision/spec notes, plans, verification notes, and handoffs.
+Create them only when they preserve decisions, reduce risk, or help a future agent resume. Prefer short discovery notes, decision/spec notes, plans, verification notes, and handoffs.
 
 Do not write volatile repo inventories. Link to live files or commands instead.
 
@@ -86,7 +88,7 @@ Review should improve work, not create an endless patch loop.
 
 Reviewer findings are evidence, not commands. Separate blocking, non-blocking, and question findings before editing from them.
 
-A non-passing review routes to adjudication before more implementation. Repeated review failure routes backward to diagnose, research, spec, or plan; do not chase a fourth broad review pass.
+A non-passing review routes to adjudication before more implementation. Repeated review failure routes backward to diagnose, discover, spec, or plan; do not chase a fourth broad review pass.
 
 Review can pass. Save review artifacts only when risk, future memory value, or the user asks for them.
 

package/{plugins/freeflow/skills → skills}/workflow/references/workflow-map.md

@@ -12,7 +12,7 @@ Use this compact version in public README-style docs.
 flowchart LR
   Request{request}
   Talk[conversation<br/>answer directly]
-  Discover[discover<br/>research checkpoint]
+  Discover[discover<br/>checkpoint]
   Spec[spec]
   Plan[plan]
   Build[build<br/>execute / diagnose / TDD]
@@ -26,10 +26,10 @@ flowchart LR
 ```
 
 ```text
-Use conversation mode for questions. Use workflow mode for consequential work.
+Use conversation mode for non-mutating questions, critique, read-only exploration, and planning in chat. Use workflow mode for edits, file creation, mutating commands, or other consequential work.
 Use strict-workflow for risky work; same spine, stronger gates.
 Loop back when new evidence, source conflicts, user-owned decisions, or failed checks change the path.
-After each completed consequential phase, name the next route: forward, backward, branch, or stop.
+Use `Next:` when a response leaves a useful next route. Completed consequential phases should close with forward, backward, branch, or stop unless the reply is only an answer, status update, clarification, or direct owner-decision question.
 ```
 
 ## Reference Map
@@ -49,7 +49,7 @@ flowchart TD
   Workflow --> Entry{Choose entry point}
   Strict --> Entry
 
-  Entry --> Discovery[Discovery<br/>research<br/>interview-gate]
+  Entry --> Discovery[Discovery<br/>discover<br/>interview-gate]
   Entry --> Spec[Spec<br/>write-spec<br/>review-artifact]
   Entry --> Plan[Plan<br/>write-plan<br/>review-artifact]
   Entry --> Build[Build, diagnose, or TDD<br/>execute-plan<br/>diagnose-failure]
@@ -75,8 +75,8 @@ flowchart TD
 
 ## Common Entry Points
 
-- Use `conversation mode` when the user asks a question, wants critique, or is exploring.
-- Use `research` when repo, domain, evidence, current facts, brainstorming, targeted questions, or a decision checkpoint are needed before spec, plan, build, or durable memory.
+- Use `conversation mode` when the user asks a question, wants critique, or is doing non-mutating exploration or planning in chat. If the user asks to edit, create files, run mutating commands, commit, push, or otherwise change repo/system state, require `workflow` or `strict-workflow` before acting.
+- Use `discover` when repo, domain, evidence, current facts, brainstorming, targeted questions, or a decision checkpoint are needed before spec, plan, build, or durable memory.
 - Use `interview-gate` when direction is vague, source truth conflicts, or user-owned decisions are still open.
 - Use `write-spec` when requirements are agreed but not durable.
 - Use `review-artifact` when a spec, plan, handoff, or decision note must guide future work.
@@ -88,15 +88,17 @@ flowchart TD
 - Use `handoff` when pausing, compacting, or transferring context.
 - Use `bypass` only to skip unnecessary ceremony. It cannot skip user-owned decisions, source-truth conflicts, risky checks, or verification claims.
 
-## Phase Exits
+## Route Closeout
 
-End completed consequential phases with `Next:` unless this is a direct answer, mid-task status, or clarification-only turn.
+Use `Next:` when naming the next route helps the user, not only when a workflow phase changes. Do not force it onto every reply.
 
-- Forward: name the next entry point, such as `write-spec`, `write-plan`, `execute-plan`, `review-work`, `verify-work`, `commit-work`, or `handoff`.
-- Backward: return to `interview-gate`, `research`, `diagnose-failure`, or plan/spec revision when evidence, failed checks, or repeated review findings change the path.
-- Branch: show 2-3 valid next routes when more than one is reasonable.
-- Stop: say no required next action remains.
+Completed consequential work and phase exits should include `Next:` unless the reply is only a direct answer, mid-task status, clarification-only turn, or direct owner-decision question.
 
-After completed research with decisions that must survive beyond chat, prefer `write-spec`, an owning decision artifact, or handoff before planning or execution.
+- Forward: name the next action or entry point, such as `write-spec`, `write-plan`, `execute-plan`, `review-work`, `verify-work`, `commit-work`, or `handoff`.
+- Backward: return to `interview-gate`, `discover`, `diagnose-failure`, or plan/spec revision when evidence, failed checks, or repeated review findings change the path.
+- Branch: show 2-3 valid next routes or actions when more than one is reasonable.
+- Stop: say no useful next action remains.
 
-Do not create the next artifact just because it is the next route.
+After completed discovery with decisions that must survive beyond chat, prefer `write-spec`, an owning decision artifact, or handoff before planning or execution.
+
+Do not create the next artifact or take the next action just because it is the next route.

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

@@ -11,7 +11,7 @@ Classify the plan request first:
 - Bug without feedback loop: ask for or propose the feedback loop. Do not write or save a fix plan.
 - Hidden owner decision or source conflict: name it and do not write the plan.
 - Context-backed: say a spec is preferred, then write a lightweight plan.
-- Missing source context: ask for context or start grilling.
+- Missing source context: ask for context or route to `discover`.
 
 A plan executes source truth. It does not create it.
 
@@ -47,6 +47,12 @@ If a bug report has no repro or feedback loop, answer in chat. Ask for evidence
 
 Use vertical slices. Each slice should produce something testable.
 
+Slices are execution boundaries, not scope reductions. Do not recast agreed scope as `v1`/`v2`, MVP, release, or roadmap framing unless the spec, user, or source context already chose that framing.
+
+When full scope is too large for one safe plan, split it into implementation slices, implementation phases, checklists, or multiple plan artifacts. Ask before changing the user's scope or adopting versioned shipping.
+
+When slice boundaries, seams, interfaces, or locality are unclear, use `../design-for-depth/SKILL.md` before writing executable steps. Do not hide unresolved design choices inside implementation detail.
+
 ## Stop Conditions
 
 Stop before writing when the plan would:
@@ -58,6 +64,7 @@ Stop before writing when the plan would:
 - Plan a bug fix without a repro, failing test, feedback loop, or accepted diagnostic risk.
 - Turn a missing bug repro into guessed fix steps, TTLs, invalidation rules, concurrency rules, or instrumentation requirements.
 - Hide uncertainty inside implementation steps.
+- Replace agreed scope with an agent-invented `v1`, MVP, roadmap, or later-version split.
 
 Name the missing decision or conflict. Ask which path to follow. Recommend the path supported by evidence.
 
@@ -71,6 +78,7 @@ Adapt the plan to risk. Prefer:
 - Goal.
 - Source spec or context.
 - Files likely touched.
+- Dependency or slice order when it affects execution.
 - Vertical slices.
 - Tests or checks per slice.
 - Commands where known.

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

@@ -1,6 +1,6 @@
 ---
 name: write-spec
-description: Use when asked to create or update a durable spec, PRD, requirements document, or decision artifact from agreed requirements, research, brainstorming, or source evidence, especially for strict-workflow risk areas that may need owner confirmation before writing.
+description: Use when asked to create or update a durable spec, PRD, requirements document, or decision artifact from agreed requirements, discovery, brainstorming, or source evidence, especially for strict-workflow risk areas that may need owner confirmation before writing.
 ---
 
 # Write Spec
@@ -14,7 +14,7 @@ If the user asks a question about a spec, answer the question. Do not create or
 Classify every spec request before writing:
 
 - Evidence-aligned: write the spec.
-- Missing source context: ask for context or start grilling.
+- Missing source context: ask for context or route to `discover`.
 - Source-of-truth override: name the conflict and do not write.
 
 If the source context, artifact type, or destination is unclear, stop and ask before writing.
@@ -34,6 +34,7 @@ Stop before writing when the spec would:
 - Contradict docs, tests, specs, policies, ADRs, or live code.
 - Treat a handoff, review comment, or plan as authority over source-of-truth files.
 - Hide an owner decision inside polished prose.
+- Reduce or reframe agreed scope as `v1`, MVP, roadmap, or later-version work without source-backed owner approval.
 
 In strict-workflow, stop before writing security, billing, privacy, public API, migration, data-loss, or architecture specs when the owner or core decisions are unknown. Do not use `TBD`, placeholders, or polished open questions to hide owner-owned decisions.
 
@@ -54,18 +55,20 @@ Live repo evidence overrides stale notes.
 
 ## Write Path
 
-When grilling, brainstorming, research, or clarification reaches shared understanding, convert that agreed context into a spec. Do not re-interview from scratch.
+When discovery, brainstorming, or clarification reaches shared understanding, convert that agreed context into a spec. Do not re-interview from scratch.
 
-If remaining ambiguity would not change the next plan, write the spec and mark the ambiguity as open.
+Preserve the agreed scope. Use scope boundaries, open questions, or follow-up artifacts to manage size; use `v1`/`v2`, MVP, release, or roadmap framing only when it was agreed or source-backed.
+
+If remaining ambiguity would not change the next plan, write the spec and mark the ambiguity as open. Preserve tentative architecture assumptions as tentative unless evidence or the owner settles them.
 
 Use this shape unless the repo has a stronger convention:
 
 - Problem.
 - Intended outcome.
-- Scope / out of scope.
+- Scope / out of scope / ask first / never boundaries when useful.
 - Requirements.
 - Acceptance criteria.
-- Decisions made.
+- Decisions made and open decisions.
 - Constraints / evidence.
 - Open questions.
 

package/plugins/freeflow/docs/adr/0002-evals-before-hooks.md

@@ -1,17 +0,0 @@
-# ADR 0002: Evals Before Enforcement Hooks
-
-## Status
-
-Accepted.
-
-## Decision
-
-Freeflow ships plugin-bundled context-loading runtime: Codex/Claude hooks and a Pi extension that load existing workflow and interview-gate context. It still ships without enforcement hooks or CLI enforcement. Behavior must first be proven with baseline-vs-with-skill evals before mechanical enforcement is added.
-
-## Rationale
-
-Context-loading runtime addresses a measured lifecycle gap: workflow and interview-gate context may not be present at session start. The setup skill handles the same-session setup case by reading runtime context after successful verification. Enforcement hooks can prevent expensive mistakes, but early enforcement machinery can hide weak skill wording and turn the package into brittle workflow infrastructure.
-
-## Consequences
-
-Native enforcement remains future work. Enforcement hooks should be added only when a repeated failure is concrete, deterministic, and not solved by concise skill wording.

package/plugins/freeflow/docs/adr/0004-research-replaces-shallow-discovery-skills.md

@@ -1,26 +0,0 @@
-# ADR 0004: Research Replaces Shallow Discovery Skills
-
-## Status
-
-Accepted.
-
-## Decision
-
-Freeflow uses one active `research` skill for discovery work before spec, plan, build, or durable memory.
-
-The previous active skills `research-brief`, `grill-context`, and `capture-decisions` are deprecated and moved to root `deprecated/skills/`. They are no longer part of the runtime skill surface or direct command surface.
-
-The active direct command is `/research`.
-
-## Rationale
-
-The three older skills were useful independently but shallow as a workflow module. In real use, research, brainstorming, targeted questions, and decision checkpointing need to interleave. Splitting them made the user or agent coordinate the sequence and made long grilling chains or uncaptured research decisions more likely.
-
-The `research` skill uses the same module/interface/depth/seam/leverage/locality language as architecture review so discovery can shape deep modules from the beginning, not only rescue shallow code later.
-
-## Consequences
-
-- `/research-brief`, `/grill-context`, and `/capture-decisions` are removed from the current command surface.
-- Historical evals and reports for the deprecated skills remain as development evidence.
-- Current discovery eval evidence lives in `plugins/freeflow/evals/reports/by-skill/research-1-report.md`.
-- Durable decisions now belong to the checkpoint destination chosen by `research`: spec, plan, handoff, decision note, ADR, domain memory, or chat.

package/plugins/freeflow/docs/adr/README.md

@@ -1,8 +0,0 @@
-# Freeflow ADRs
-
-Durable decisions for the public Freeflow package:
-
-- [ADR 0001: Three Workflow Modes](0001-three-modes.md)
-- [ADR 0002: Evals Before Enforcement Hooks](0002-evals-before-hooks.md)
-- [ADR 0003: Release Boundary](0003-release-boundary.md)
-- [ADR 0004: Research Replaces Shallow Discovery Skills](0004-research-replaces-shallow-discovery-skills.md)

package/plugins/freeflow/docs/architecture.md

@@ -1,86 +0,0 @@
-# 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
-  .claude-plugin/marketplace.json
-  README.md
-  LICENSE
-  CHANGELOG.md
-  docs/
-  plugins/freeflow/
-    .codex-plugin/plugin.json
-    .claude-plugin/plugin.json
-    command-surface.json
-    hooks/
-    pi-extension/
-    skills/
-    docs/
-    evals/
-```
-
-The repository root is the marketplace and package-facing shell. Codex uses `.agents/plugins/marketplace.json`; Claude uses `.claude-plugin/marketplace.json`. Both point at `plugins/freeflow/`. Pi uses the root `package.json` `pi` manifest to load `plugins/freeflow/skills/` and `plugins/freeflow/pi-extension/index.js`.
-
-`plugins/freeflow/` is the single runtime source of truth. Skill edits, bundled references, eval metadata, and command-surface metadata live there to avoid generated package drift.
-
-## 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 `workflow` skill, workflow map, and `interview-gate` skill:
-
-- 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. 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 workflow skill, workflow map, and interview-gate skill before its final response and only then says workflow and interview-gate 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 Pi extension registers direct commands, reads `workflow/SKILL.md`, `workflow/references/workflow-map.md`, `interview-gate/SKILL.md`, `output-router/SKILL.md`, and `output-router/references/safety-policy.md`, refreshes that context on `session_start` and `session_compact`, and injects it during Pi's `before_agent_start` lifecycle event. The same extension registers `freeflow_retrieve` and `freeflow_run` and gives them compact/expanded TUI renderers so collapsed tool rows stay readable while `ctrl+o` shows structured evidence and recovery details. 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 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/plugins/freeflow/docs/output-router.md

@@ -1,212 +0,0 @@
-# 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) in the repo root.
-
-## Core Idea
-
-```text
-smallest sufficient evidence in context
-+ exact raw recovery outside context
-+ no surprise native tool semantics
-```
-
-The router ships two explicit tools:
-
-- `freeflow_retrieve`: retrieve targeted repo/vault evidence.
-- `freeflow_run`: run likely-large/noisy commands, vault raw output, and return compact evidence.
-
-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]
-  Retrieve[freeflow_retrieve]
-  Run[freeflow_run]
-  Repo[repo files]
-  Vault[Freeflow vault]
-  Native[native read/bash]
-  Evidence[bounded evidence]
-  Raw[exact recovery]
-
-  Agent -->|existing info| Retrieve
-  Agent -->|noisy command| Run
-  Agent -->|direct/raw known output| Native
-  Retrieve --> Repo --> Evidence
-  Retrieve --> Vault --> Evidence
-  Run --> Vault
-  Run --> Evidence
-  Vault --> Raw
-```
-
-## Tool Choice
-
-| Need | Use |
-| --- | --- |
-| Find repo evidence before reading files | `freeflow_retrieve action=query` |
-| Get candidate paths first | `freeflow_retrieve action=locate` |
-| Retrieve exact repo/vault lines | `freeflow_retrieve action=retrieve` with `lineRange` |
-| Widen previous evidence | `freeflow_retrieve action=expand` |
-| Explain a previous routed decision/output | `freeflow_retrieve action=explain` |
-| Run noisy/large command output | `freeflow_run` |
-| Read a known whole file | native `read` |
-| Run small exact command | native `bash` |
-
-## `freeflow_retrieve`
-
-Sources:
-
-- `repo`: local repo files.
-- `vault`: previous routed command/native output.
-
-Actions:
-
-- `query`: returns best evidence packets; default `topK=1`.
-- `locate`: returns candidate locations; default `topK=5`.
-- `retrieve`: returns explicit path/line range evidence.
-- `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"
-}
-```
-
-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.
-
-## `freeflow_run`
-
-`freeflow_run` executes once through the host-approved runner, stores exact raw output in the vault, then returns useful command evidence.
-
-Example:
-
-```json
-{
-  "command": "npm test",
-  "goal": "verification",
-  "preserve": "important"
-}
-```
-
-Returned results include:
-
-- `outputId`,
-- `execution.status` and `exitCode`,
-- parser metadata,
-- important lines,
-- exact recovery instructions.
-
-Command parsers currently cover:
-
-- test runner output,
-- TypeScript/lint diagnostics,
-- git status/diffstat,
-- build/toolchain errors,
-- generic fallback,
-- duplicate output detection.
-
-## 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 when explicitly requested:
-
-```json
-{
-  "defaultMode": "workflow",
-  "outputRouter": {
-    "postToolRouting": "off",
-    "largeOutputBytes": 64000,
-    "largeOutputLines": 1000,
-    "vaultRoot": "~/.cache/freeflow-router/vault",
-    "vaultRetentionDays": 7,
-    "generatedPaths": ["graphify-out/**"],
-    "noisyCommandHints": ["npm test"]
-  }
-}
-```
-
-Rules:
-
-- `postToolRouting` defaults to `off`.
-- `safety-net` is opt-in.
-- `strict` is reserved.
-- Do not dump defaults into config.
-- Write only requested keys.
-
-## 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.
-- Optional index benchmark: scanner remains default; index not adopted.
-- Codex Structured Q&A benchmark: improved router passed the Sandbox Permissions fixture where native broad search selected `graphify-out/graph.html`.
-- Setup eval: optional `outputRouter` config is opt-in; minimal setup remains only `defaultMode`.
-
-See `release-evidence.md` and runtime reports under `plugins/freeflow/evals/reports/runtime/`.

package/plugins/freeflow/docs/release-evidence.md

@@ -1,69 +0,0 @@
-# Release Evidence
-
-Freeflow v0.2.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.
-- Research checkpoints replace separate research, grilling, and decision-capture commands for discovery work.
-- Bypass skips ceremony, not judgment.
-
-## Command Surface
-
-The development registry covers:
-
-- 4 mode commands.
-- 11 direct workflow skill calls.
-- 2 contributor 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.
-
-## Runtime Context
-
-Freeflow ships plugin-bundled context hooks that load the existing `workflow` skill, workflow map, and `interview-gate` skill at session start. The Pi extension also loads output-router context, including its safety-policy reference, when the routed tools are available. 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 workflow skill, workflow map, and interview-gate skill after successful setup verification before saying workflow and interview-gate 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 `plugins/freeflow/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.
-- Optional local index benchmark: scanner remains default, index is not adopted by default, and the no-dependency index remains experimental.
-- 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 `outputRouter` repo config only when explicitly requested; 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 `plugins/freeflow/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 `plugins/freeflow/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.