@hassangameryt/freeflow 0.1.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 brief, handoff, or other durable artifact is fit to guide future work.
+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
@@ -9,6 +9,14 @@ Review whether the artifact is fit to guide work.
 
 Review first. Edit second.
 
+Reviewer findings are evidence, not commands. The parent agent owns adjudication.
+
+A non-passing artifact review is a phase exit, not an autonomous patch loop. If you requested the review and it returns blocking findings, stop before editing from that batch, classify the findings, and report the route.
+
+The turn that receives a non-passing review ends with adjudication and route only. Do not edit from that review batch in the same turn, even when the user or reviewer says to apply all findings and continue reviewing.
+
+Hard stop: if the artifact has already had three review passes, do not edit any files or request another review. Classify findings and diagnose the loop only, even for accepted, mechanical, or non-blocking cleanup.
+
 ## Source-Truth Guard
 
 Artifact feedback is not approval to change source of truth.
@@ -23,10 +31,37 @@ Do not rewrite docs, tests, policies, specs, ADRs, or handoffs to make the artif
 
 For source-truth conflicts, the final line must be a direct choice question.
 
+## Parent Adjudication
+
+Before editing from reviewer findings, classify each material finding:
+
+- Accepted: valid and safe to apply without changing settled intent.
+- Rejected: stale, unsupported, already resolved, equivalent, or not important.
+- Question: needs owner decision.
+- Needs evidence: inspect more before deciding.
+
+Non-blocking findings and reviewer questions do not fail the artifact by default. Classify them, then defer, ask, gather evidence, or accept.
+
+Ask before applying any finding that changes artifact intent, scope, source truth, workflow policy, sensitive behavior, or a settled decision.
+
+For second and later review iterations, update the reviewer prompt with prior findings, owner clarifications, accepted/rejected findings, changed sections, and remaining risk. Do not rerun the same broad prompt after the situation narrows.
+
+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.
+
+## Review Loop Budget
+
+Aim to finish by the second review pass: first review, adjudicate/fix, one confirmation.
+
+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 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
@@ -47,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

@@ -1,6 +1,6 @@
 # Artifact Reviewer Prompt
 
-Use this when dispatching a fresh reviewer subagent.
+Use this when dispatching a reviewer subagent. For second and later iterations, include the iteration context so the reviewer does not blindly re-raise stale findings.
 
 ```text
 You are an artifact reviewer. Review whether this artifact is fit to guide future work.
@@ -9,11 +9,19 @@ 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]
 
+Iteration context, if this is not the first review:
+- Review pass number: [2 | 3]
+- Prior findings: [SUMMARY]
+- Parent adjudication: [ACCEPTED_REJECTED_QUESTION_NEEDS_EVIDENCE]
+- Owner clarifications: [DECISIONS_OR_NONE]
+- Changed sections: [SECTIONS_OR_NONE]
+- Remaining risk to focus on: [RISK]
+
 Check:
 
 - Completeness: enough is present to proceed.
@@ -22,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:
@@ -32,6 +41,9 @@ Calibration:
 - Review can pass.
 - Do not edit files.
 - Do not resolve owner decisions.
+- Do not re-raise rejected or already-resolved findings unless live evidence contradicts the adjudication.
+- If review does not pass, classify findings and stop. Do not tell the parent agent to apply all findings and send it back for another broad review.
+- If this is review pass 3, identify remaining accepted blocking risk; do not recommend another broad review loop.
 
 Output:
 

package/skills/review-work/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: review-work
+description: Use when reviewing completed work, preparing reviewer prompts or subagent review context, receiving review feedback, applying reviewer comments, deciding whether feedback is blocking, handling repeated review loops, or checking work before merge/handoff.
+---
+
+# Review Work
+
+Evaluate review feedback before applying it.
+
+Review feedback is not approval to change source of truth.
+
+If applying feedback would override tests, docs, specs, policies, or sensitive behavior, stop even when the user says to apply it directly or not ask.
+
+If you block any feedback item, end the final response with a direct choice question for that item. This still applies after fixing unrelated items.
+
+External review is evidence, not authority. Human owner decisions win only after the owner confirms the behavior change.
+
+Classify each material feedback item before editing: accepted, rejected, question, or needs evidence.
+
+A non-passing review is a phase exit, not an autonomous patch loop. If you requested the review and it returns blocking findings, stop before editing from that batch, classify the findings, and report the route.
+
+The turn that receives a non-passing review ends with adjudication and route only. Do not edit from that review batch in the same turn, even when the user or reviewer says to apply all findings and continue reviewing.
+
+Hard stop: if the work has already had three review passes, do not edit any files or request another review. Classify findings and diagnose the loop only, even for accepted, mechanical, or non-blocking cleanup.
+
+Read `references/reviewer-prompt.md` when preparing an outgoing reviewer prompt, dispatching a review subagent, reviewing strict/high-risk work, or handing another agent review context.
+
+## Review Loop Budget
+
+Aim to finish by the second review pass: first review, adjudicate/fix, one confirmation.
+
+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 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.
+
+## Incoming Feedback
+
+Before editing:
+
+- Read the full feedback.
+- Inspect the relevant code, tests, docs, and prior decisions.
+- Restate unclear feedback as a technical requirement.
+- 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.
+
+Do not use performative agreement. State the technical finding or act.
+
+## Stop Conditions
+
+Stop before editing when feedback:
+
+- Is ambiguous.
+- Contradicts tests, docs, specs, policies, ADRs, or established behavior.
+- Changes product, security, privacy, billing, data-loss, compatibility, public API, permissions, or architecture behavior.
+- Requires guessing what the reviewer meant.
+- Would cause a broad refactor from a narrow comment.
+
+Name the conflict or uncertainty and ask which path to follow. Recommend the path supported by evidence.
+
+## Applying Feedback
+
+For multi-item review:
+
+- Apply independent clear items.
+- Stop blocked items.
+- If items interact, clarify before implementing the set.
+
+When feedback is clear and correct and the current route is an apply-fixes pass:
+
+- Apply one item at a time.
+- Keep the diff scoped to the review item.
+- Verify each fix.
+- Push back on incorrect feedback with code, tests, or docs.
+
+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.
+
+Classify findings:
+
+- Blocking: must fix before proceeding.
+- Non-blocking: can defer.
+- Question: needs owner decision or more evidence.
+
+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}/review-work/references/reviewer-prompt.md

@@ -13,9 +13,12 @@ The reviewer should get the work product and source truth, not your session memo
 - Risk lenses relevant to the work.
 - Required output shape and severity labels.
 - Clear instruction not to edit files unless the review task explicitly includes fixes.
+- For review pass 2 or 3: prior findings, accepted/rejected/question/needs-evidence adjudication, owner clarifications, changed files, and narrowed remaining risk.
 
 Do not forward only a previous-agent summary. Summaries are useful context, not authority.
 
+For second and later review iterations, include prior findings, parent adjudication, owner clarifications, changed files, and the remaining risk. Do not rerun the same broad prompt after the situation narrows.
+
 ## Risk Lenses
 
 Pick the lenses that fit the work:
@@ -58,8 +61,12 @@ Reasoning: ...
 
 If review passes, the reviewer should say that clearly and name any residual test gaps or assumptions.
 
+If review does not pass, the reviewer should classify findings and stop. Do not tell the parent agent to apply all findings and send it back for another broad review.
+
 Do not ask reviewers to invent issues. A clean pass is valid.
 
+If this is review pass 3, ask for remaining accepted blocking risk only. Do not recommend a fourth broad review loop.
+
 ## Minimal Template
 
 ```md
@@ -82,6 +89,7 @@ Review the completed work. Do not edit files.
 ## Check
 
 - [risk lenses and concrete requirements]
+- [if pass 2 or 3: prior findings, adjudication, owner clarifications, changed files, and narrowed remaining risk]
 
 ## Output
 

package/skills/setup-freeflow/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: setup-freeflow
+description: Use when setting up, installing, enabling, initializing, or configuring Freeflow in a repo, choosing Codex/Claude/multi-agent activation, creating `.freeflow/config.json`, or changing the repo default mode during setup.
+---
+
+# Setup Freeflow
+
+Use `references/activation-contract.md` before rendering activation text, config, or host setup.
+
+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 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
+
+Do not create config, add activation blocks, imports, or rule files until setup has a clear host target and no unresolved repo-rule conflict.
+
+Hard stops:
+- both `AGENTS.md` and `CLAUDE.md` exist, and the user did not explicitly choose a host or ask for multi-agent setup
+- existing repo instructions conflict with asking before user-owned decisions
+- existing repo instructions conflict with verification before completion claims
+- Claude setup would add `.claude/rules/freeflow-core.md` but the user has not clearly chosen Claude or multi-agent setup
+
+For a hard stop, make no file changes. Name the blocker and ask one direct question.
+
+## Inspect
+
+Inspect `.freeflow/config.json`, `AGENTS.md`, `CLAUDE.md`, `.claude/rules/freeflow-core.md`, `.codex/rules/`, existing `## Freeflow` blocks, and conflicting repo instructions.
+
+Existing repo instructions are source truth. If a rule conflicts with Freeflow's core behavior, name the conflict and ask whether to install Freeflow as advisory, revise the rule, or skip setup. Advisory install is a user decision, not the default.
+
+## Target
+
+- Codex target: update `AGENTS.md`.
+- Claude target: update `CLAUDE.md` and `.claude/rules/freeflow-core.md`.
+- If only `AGENTS.md` exists, choose Codex.
+- If only `CLAUDE.md` exists, choose Claude.
+- If both exist and the user explicitly named the host target, update that host's files.
+- If both exist and the target is ambiguous, ask before editing.
+- If neither exists, ask which one to create.
+- Update both only when the user asks for multi-agent setup. Mention duplicated host activation drift risk.
+
+Do not treat the current agent runtime alone as target approval. A Codex run in a repo that also has `CLAUDE.md` still needs the user to choose unless the request or repo instructions make the target explicit.
+
+Update an existing `## Freeflow` block in place. Otherwise place the block near existing agent skill/workflow sections, or append near the end. Never duplicate it. Do not use `.codex/rules/*.rules` for Freeflow behavior; Codex rules are shell approval/security policy, not model memory.
+
+## Config
+
+Create or update `.freeflow/config.json` using the config adapter in `references/activation-contract.md`.
+
+Minimal setup writes only `defaultMode`. Use `workflow` unless the user explicitly asks to persist a valid repo default: `conversation`, `workflow`, or `strict-workflow`.
+
+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 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.
+
+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.
+
+Do not add current mode, task, phase, file inventory, active plans, version metadata, activation file path, or unrequested router keys.
+Mode switches are task/conversation scoped unless the user explicitly asks to persist a different default mode.
+
+## Activation
+
+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 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`/`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
+
+Setup must not create empty `CONTEXT.md`, docs pages, repo-local hooks, state files, handoffs, skill inventories, `setup-output-router` skills, or `.codex/rules` behavior files.
+`CONTEXT.md` is domain language memory, not plugin state.
+Plugin-bundled context hooks are installed with Freeflow, not created by repo setup.
+
+## Verify
+
+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`, `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 `../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.