@hassangameryt/freeflow 0.3.0 → 0.4.0

package/skills/setup-freeflow/references/activation-contract.md

@@ -1,100 +1,120 @@
 # Activation Contract
 
-This is the canonical Freeflow setup contract. Setup renders this contract into host instruction files; docs, fixtures, and eval assertions should reference it or be checked against it.
+Freeflow uses layered checkout configuration. Shared repository activation, personal overrides, and runtime delivery are separate facts.
 
-## Interface
+## Repository Activation
 
-Use this Markdown reference as the v0.1 contract module:
+`.freeflow/config.json` is the required shared activation boundary. Minimal setup is:
 
-```text
-getActivationContract(defaultMode) -> ActivationContract
-planActivation(contract, repoState, request) -> ActivationPlan | ActivationStop
-renderActivation(contract, target) -> rendered text or checks
-planOptionalEvidenceRoutingConfig(request) -> EvidenceRoutingConfigPlan | ActivationStop
+```json
+{
+  "defaultMode": "workflow"
+}
 ```
 
-Do not add a code module until setup behavior needs logic that cannot be kept clear in the skill and this reference.
+Supported defaults are `conversation`, `workflow`, and `strict-workflow`. Missing core keys use built-in defaults:
 
-## Invariants
+- `enabled: true`
+- `interactionContract: true`
+- `skills.enabled: true`
+- `defaultMode: workflow`
 
-- Activation text contains always-on invariants only, not the full workflow spine.
-- Minimal config has exactly one field: `defaultMode`.
-- Optional `outputRouter`, `observedRouting`, and `scriptTransform` config is allowed only after the capabilities decision point or an explicit request. Removed `capture` and `providers` config is not written by setup.
-- Valid defaults are exactly `conversation`, `workflow`, and `strict-workflow`.
-- Default mode is `workflow` unless the user explicitly persists another valid mode.
-- Codex activation writes `AGENTS.md`, not `.codex/rules`.
-- Claude activation writes a `CLAUDE.md` import plus one `.claude/rules/freeflow-core.md`.
-- Multi-agent setup updates both host surfaces only on explicit request and reports drift risk.
-- Existing repo instructions remain source truth.
-- Setup hard-stops before unresolved host ambiguity or repo-rule conflict.
-- Setup does not create repo-local hooks, docs inventories, state files, handoffs, empty `CONTEXT.md`, skill inventories, `setup-output-router` skills, version metadata, activation path, current task, or current phase.
-- Plugin-bundled context hooks may load mode-contract, workflow, interview-gate, discover, and output-router context at session start, but they are package runtime, not setup output.
-- After successful setup verification, setup reads the mode-contract, workflow, interview-gate, discover, and output-router skills before its final response so the current session is immediately usable.
+Repository config may also contain documented Output Router settings. Add optional settings only after an explicit request and preserve valid existing settings during idempotent setup.
 
-## Host Adapters
+Do not add current mode, task state, phase, file inventories, plans, version metadata, activation paths, empty optional sections, host instruction copies, or generated workflow text.
 
-Codex adapter:
+Missing or invalid repository config means repository activation is absent. A valid config with effective `enabled: false` remains configured but inactive.
 
-- Update an existing `## Freeflow` block in `AGENTS.md`, or add one near existing agent/workflow instructions.
-- Keep exactly one `## Freeflow` block.
-- Never use `.codex/rules` for Freeflow behavior.
+## Personal Overrides
 
-Claude adapter:
+`.freeflow/local.json` is optional per-checkout state. It cannot activate Freeflow without a valid repository config.
 
-- Update `CLAUDE.md` with only the import block below.
-- Write the Codex core block text to `.claude/rules/freeflow-core.md`.
-- Keep exactly one imported core file unless the user explicitly confirms a split after the one-file recommendation.
+It may override these core values:
 
-Config adapter:
+```json
+{
+  "enabled": true,
+  "interactionContract": true,
+  "skills": {
+    "enabled": true
+  },
+  "defaultMode": "strict-workflow"
+}
+```
 
-- Create or update `.freeflow/config.json`.
-- For minimal setup, write exactly `{ "defaultMode": "<mode>" }`.
-- Use `workflow` unless the user explicitly asks to persist `conversation` or `strict-workflow`.
-- Add `outputRouter`, `observedRouting`, or `scriptTransform` only after the capabilities decision point or an explicit request, using `output-router-setup.md`. Do not write removed `capture` or `providers` config.
-- Missing `outputRouter`, `observedRouting`, and `scriptTransform` means built-in defaults, not a setup warning.
-- Never enable observed routing or native safety-net routing by default.
-- Observed routing requires explicit producer/server entries and user-chosen persistence: `exact`, `metadata-only`, or `none`. Do not offer or write `redacted`.
+Every field is optional. Omission inherits the repository value, then the built-in default. Local core precedence is property-level, not whole-file replacement.
 
-## Codex Core Block
+The local file may also contain documented local-only `processing` config. It must not contain repository-owned Output Router config.
 
-<!-- freeflow-activation-contract:codex-core:start -->
-```md
-## Freeflow
+Keep local config untracked and ignored. In a Git checkout, prefer `.git/info/exclude` or an existing ignore rule over an unsolicited shared `.gitignore` edit. Refuse to write personal overrides to a tracked local file.
 
-Use Freeflow for consequential work. Default mode: `.freeflow/config.json`.
+A missing local file means full inheritance. An invalid existing local file blocks effective Freeflow and must not silently fall back to repository settings. Repair or removal requires authorization.
 
-Move forward when context is sufficient. Re-enter clarification when new ambiguity would change the next action.
+## Effective Core State
 
-Treat questions as questions and suggestions as hypotheses. Answer directly; do not infer correction, permission, or agreement.
+Resolve core values in this order:
 
-Ask before user-owned decisions: product behavior, scope, public APIs, security, privacy, billing, data loss, compatibility, permissions, or irreversible architecture.
+```text
+host session override -> personal override -> repository value -> built-in default
+```
 
-Treat live repo evidence and existing docs/tests as source truth. If the user request conflicts with them, stop and ask before changing behavior.
+Host session overrides, where supported, may temporarily change Freeflow master enablement, Interaction Contract, Skills, and mode. They are host session state, not config, and cannot bypass missing or invalid repository activation.
 
-Verify before completion claims. Capture only stable decisions, glossary terms, ADR-worthy tradeoffs, or useful handoff memory.
-```
-<!-- freeflow-activation-contract:codex-core:end -->
+Effective Freeflow requires:
 
-## Claude Import Block
+1. valid repository config;
+2. missing or valid local config;
+3. session-resolved `enabled: true`.
 
-<!-- freeflow-activation-contract:claude-import:start -->
-```md
-## Freeflow
+The Interaction Contract and Skills are independent resolved switches. When Skills are disabled, the configured mode remains visible as resolved state but no Freeflow mode is effective.
 
-@.claude/rules/freeflow-core.md
-```
-<!-- freeflow-activation-contract:claude-import:end -->
+Repository-owned Output Router settings remain independent capability config and take effect only while top-level Freeflow is enabled.
+
+## Mutation Authority By State
+
+Mode constrains agent-performed setup only when a mode is effective:
+
+- **Unconfigured:** missing or invalid repository config means no effective mode. An explicit setup request may create missing minimal activation; replacing invalid config requires specific authorization and source-conflict resolution.
+- **Configured but ineffective:** top-level disablement, dormant Skills, or invalid local config leaves no effective mode. An explicit request governs the selected enablement, configuration, or repair; any reported resolved mode remains dormant state only.
+- **Effective:** obey the reported mode. Conversation is read-only. Workflow and Strict Workflow allow only separately authorized setup or repair.
+
+A user operating native host settings changes host-managed state directly. That action is distinct from an agent editing `.freeflow/config.json` or `.freeflow/local.json`; verify the resulting source and effective state afterward.
+
+## Runtime Delivery
+
+Configuration does not prove runtime delivery.
+
+When effective, host adapters may deliver:
+
+- `runtime/interaction-contract.md` when the Interaction Contract switch is enabled;
+- one full `skills/workflow/SKILL.md` bootstrap when Skills are enabled;
+- compact active or dormant mode and capability state;
+- explicitly enabled capability context owned by that capability.
+
+The full Mode Contract and other workflow skills remain on demand. Adapters load context only; they do not enforce policy, block tools, grant permissions, or replace repo instructions.
+
+A setup report classifies automatic delivery as:
+
+- **confirmed:** trustworthy evidence shows the current host adapter ran;
+- **unavailable:** the adapter is absent, disabled, denied, untrusted, or unsupported;
+- **unconfirmed:** the host exposes no trustworthy execution evidence.
+
+For the setup turn itself, direct reads of newly effective context establish guidance only for that turn. Report those reads separately from lifecycle delivery.
+
+## Repo-Owned Instructions
+
+Do not create replacement Freeflow text in `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, or another repository instruction surface.
 
-## Drift Checks
+Existing repo instructions remain live source truth within host precedence. Inspect conflicts and use Decision Gate rather than overwriting them to make Freeflow appear active.
 
-Run `evals/scripts/check-activation-contract.sh` when changing setup behavior, post-setup fixtures, setup eval assertions, or docs that quote setup behavior.
-Run `evals/scripts/check-runtime-context-hook.sh` when changing plugin-bundled runtime context hooks.
+## Setup Invariants
 
-The check keeps these surfaces aligned:
+Setup is:
 
-- this canonical reference
-- `setup-freeflow/SKILL.md`
-- `setup-freeflow/references/host-setup.md`
-- `docs/freeflow-runtime-and-lifecycle.md` in the Freeflow development repo
-- post-setup `AGENTS.md` fixtures
-- setup eval assertions that depend on canonical activation text
+- idempotent;
+- minimal by default;
+- explicit about shared versus personal state;
+- fail-closed for an invalid personal layer;
+- non-mutating toward repo-owned host instructions;
+- explicit about same-turn reads versus automatic runtime delivery;
+- free of generated replacement instructions and unrequested capability config.

package/skills/setup-freeflow/references/host-setup.md

@@ -1,35 +1,72 @@
 # Host Setup
 
-Use this only when setup asks for a host, profile, default mode, team install, hooks, CLI, or multi-agent shape. Use `activation-contract.md` for canonical activation text, config invariants, and host adapter rules.
+Host choice affects runtime delivery and settings controls, not the required repository activation shape.
 
-## Hosts
+## Shared Checkout Shape
 
-Codex setup writes `AGENTS.md` and `.freeflow/config.json`.
+Every host requires:
 
-Claude setup writes `CLAUDE.md`, `.claude/rules/freeflow-core.md`, and `.freeflow/config.json`.
+```text
+.freeflow/config.json
+```
 
-Multi-agent setup updates both host surfaces only when the user asks for both or multi-agent setup. Mention that duplicated always-on text can drift, render both hosts from `activation-contract.md`, and keep Claude's full block in one imported file.
+Each checkout may also use:
 
-Current runtime is not enough to choose a host when both `AGENTS.md` and `CLAUDE.md` exist.
+```text
+.freeflow/local.json
+```
 
-## Profiles
+The repository file establishes shared activation. The local file supplies optional personal overrides and cannot activate Freeflow alone. Keep it untracked and ignored.
 
-Solo setup is the default: one host target, compact activation, `defaultMode: "workflow"`, no extra docs.
+Do not generate host-specific Freeflow instructions in `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, or another repo-owned instruction surface.
 
-Evidence-routing setup is an opt-in config branch inside normal setup, not a separate host profile. Use `output-router-setup.md`; keep minimal setup config unchanged unless the user accepts the capabilities decision point or explicitly asks for output-router/observed-routing/script-transform config.
+## Pi
 
-Team setup still uses compact activation. Add both hosts only if requested. Do not add team standards, onboarding docs, owners, approvers, repo-local hooks, or CLI checks as part of setup unless the user separately asks and the repo has a validated path for them.
+The Pi extension reads both config layers before each agent turn. A valid repository config plus a missing or valid local layer is required before Freeflow can become effective.
 
-Strict setup changes `.freeflow/config.json` to `strict-workflow` only when the user explicitly asks to make that the repo default. Otherwise recommend strict-workflow for high-risk work without persisting it.
+Pi provides these settings scopes:
 
-Valid persisted defaults are exactly `conversation`, `workflow`, and `strict-workflow`.
+```text
+/freeflow settings          personal overrides
+/freeflow settings session  temporary session overrides
+/freeflow settings repo     shared repository settings
+/freeflow mode               direct temporary session mode
+```
 
-## Not Setup
+Session settings can temporarily inherit, enable, or disable Freeflow, Interaction Contract, and Skills, and can override mode. One reset action clears all four overrides. They persist in the active Pi session branch JSONL, never write `.freeflow/config.json` or `.freeflow/local.json`, and cannot bypass missing or invalid repository activation. Master or Skills changes reload Pi resources when supported.
 
-Do not install repo-local hooks, CLI commands, lint rules, global standards, docs inventories, setup-output-router skills, or state files during setup.
+Personal settings use omission to inherit. The settings path refuses to overwrite invalid or tracked local config and establishes local Git exclusion when needed. These are user-operated host controls; they update state before the next model turn. Agent-performed file edits still follow Setup Freeflow's mutation-authority rules.
 
-Freeflow's plugin-bundled context hooks are package runtime. They load mode-contract, workflow, interview-gate, discover, and output-router context at session start, but setup should not copy hook files into the target repo.
+When effective, Pi's `before_agent_start` path preserves the existing system prompt, adds current layered status and enabled model-facing context, and loads Workflow as one hidden persistent message while Skills are enabled. Interaction Contract delivery is independent from Skills. Mode Contract remains on demand.
 
-After successful setup verification, setup should read the mode-contract, workflow, interview-gate, discover, and output-router skills before the final response. If session-start runtime context does not load in later sessions, tell the user to review/trust the installed Freeflow plugin hooks or start a fresh/compacted session. Do not create repo-local hook files as a workaround.
+A config written during setup is visible to the available Pi adapter on the next agent turn. After first activation, tell the user to run `/reload` so Pi refreshes skills and resources fully. Without reload, the adapter can load core runtime context on the next agent turn, but resource discovery waits for reload. A session-mode command applies before the next model turn and does not require reload. For the remainder of the setup turn, read newly effective context directly after verification instead of claiming that another `before_agent_start` invocation already occurred.
 
-If the user asks for enforcement, say Freeflow setup is instruction-only for now and ask whether to handle enforcement as a separate task.
+Confirm automatic delivery through current extension status or runtime evidence when available.
+
+## Codex And Claude
+
+The packaged lifecycle hook reads the same repository and local layers at supported session start, resume, clear, and compact boundaries.
+
+When top-level Freeflow is effective, the hook loads the Interaction Contract if enabled and the full Workflow bootstrap if Skills are enabled. It reports layered value sources and active or dormant mode state. Optional capabilities remain independently gated by valid repository config and top-level Freeflow.
+
+After first-time setup, tell the user to trigger the least disruptive supported host-native lifecycle boundary: resume, clear, compact, or a new session/startup as available. Name the exact control supported by the current host; do not prescribe Pi's `/reload`. Until that boundary runs, use same-turn direct reads without claiming automatic delivery.
+
+Classify delivery as:
+
+- **confirmed** when the current adapter invocation is evidenced;
+- **unavailable** when the plugin or hook is absent, disabled, denied, untrusted, or unsupported;
+- **unconfirmed** when the adapter may be installed and trusted but the host exposes no trustworthy evidence that it ran for the current lifecycle.
+
+Installed and trusted registration can establish availability for the next lifecycle action; it does not prove delivery already occurred.
+
+Do not compensate for unavailable or unconfirmed delivery by copying Freeflow text into repository instructions.
+
+## Optional Capabilities
+
+Do not ask a generic capability question during normal setup. If Output Router is explicitly requested, use `output-router-setup.md` and keep its config in the shared repository layer unless the documented setting is specifically local-only.
+
+Do not install repo-local hooks, CLI commands, lint rules, global standards, documentation inventories, or state files during setup.
+
+## Conflicts
+
+Repository instructions can conflict with Freeflow behavior even though they are not activation markers. Name the conflict and ask before changing setup or behavior when it would alter the next action.

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

@@ -1,85 +1,93 @@
 # Output Router Setup
 
-Use this when setup reaches the optional capabilities branch or explicitly asks for output-router, observed-routing, generated-path, native safety-net, vault, threshold, script-transform adapters, or script-transform repo config (`scriptTransform`).
+Use this only when repository setup or repair explicitly includes Output Router, observed routing, generated-path hints, native safety-net routing, vault, thresholds, script-transform adapters, or script-transform repository config.
 
 ## Defaults
 
-- The output router has built-in defaults. A repo does not need optional config for normal search/run/transform behavior.
-- Minimal `/setup-freeflow` must still write only `defaultMode`.
-- Ask one capabilities decision point. If declined, do not write `outputRouter`, `observedRouting`, or `scriptTransform`, and do not install script adapters.
+- Minimal `/setup-freeflow` writes only repository `defaultMode`. `.freeflow/config.json` remains required for activation; a local override cannot activate Freeflow.
+- Output Router is repository-owned and disabled by default.
+- Missing optional sections mean built-in defaults, not setup failure.
+- Normal setup does not ask a generic capability question. If Output Router was not explicitly requested, do not write `outputRouter` config or install script adapters.
+- If the user explicitly opts into Output Router during setup, write `outputRouter.enabled: true` directly. Do not make them run another command afterward.
 - Observed routing is opt-in per producer/server. The user must choose persistence for each enabled entry before setup writes config.
+- Preserve unrelated valid repository and personal settings. Do not copy Output Router config into `.freeflow/local.json`; only documented local-only processing settings belong there.
 - Do not create a separate `setup-output-router` skill.
 
-If the user says only “set up the output router” with no requested knobs, say the router works with built-in defaults and ask which optional config they want persisted. Recommend no repo config unless they need observed routing, repo-specific hints, script transform setup, or safety-net behavior.
+If the user says only “set up the output router” with no requested knobs, explain that enabling Output Router is enough for the router tools/guidance, then ask which optional subfeatures, if any, they want persisted. Recommend no subfeature config unless they need observed routing, repo-specific hints, script transform setup, or native safety-net behavior.
 
 ## Config Shape
 
-Write only keys the user explicitly requests. Do not dump all defaults and do not create empty `outputRouter`, `observedRouting`, or `scriptTransform` objects. Do not write removed `capture` or `providers` config.
+Write only keys the user explicitly requests. Do not dump defaults and do not create empty optional objects. Output-router-related config lives under `outputRouter`. Do not write removed `capture` or `providers` config.
 
-Supported high-level repo config keys:
+Supported shape:
 
 ```json
 {
   "defaultMode": "workflow",
   "outputRouter": {
     "enabled": true,
-    "profile": "standard",
-    "postToolRouting": "off",
-    "largeOutputBytes": 64000,
-    "largeOutputLines": 1000,
-    "vaultRoot": "~/.cache/freeflow-router/vault",
-    "vaultRetentionDays": 7,
-    "generatedPaths": ["graphify-out/**"],
-    "noisyCommandHints": ["npm test"]
-  },
-  "observedRouting": {
-    "enabled": true,
-    "onRoutingFailure": "fail-open",
-    "mcp": {
-      "servers": {
-        "github": { "enabled": true, "persistence": "exact" },
-        "gmail": { "enabled": true, "persistence": "metadata-only" }
-      }
+    "postToolRouting": "safety-net",
+    "thresholds": {
+      "largeOutputBytes": 64000,
+      "largeOutputLines": 2000
     },
-    "web": { "enabled": true, "persistence": "exact" },
-    "fetch": { "enabled": true, "persistence": "exact" },
-    "codeSearch": { "enabled": true, "persistence": "exact" }
-  },
-  "scriptTransform": {
-    "enabled": true,
-    "sandbox": "auto",
-    "languages": ["javascript", "python", "jq"],
-    "network": "off",
-    "limits": {
-      "timeoutMs": 5000,
-      "maxInputBytes": 1048576,
-      "maxOutputBytes": 65536
+    "vault": {
+      "root": "~/.cache/freeflow-router/vault",
+      "retention": { "strategy": "ttl", "ttlDays": 7 }
+    },
+    "hints": {
+      "generatedPathGlobs": ["graphify-out/**"],
+      "noisyCommandPatterns": ["npm test"]
+    },
+    "observedRouting": {
+      "enabled": true,
+      "onRoutingFailure": "fail-open",
+      "mcp": {
+        "servers": {
+          "github": { "enabled": true, "persistence": "exact" },
+          "gmail": { "enabled": true, "persistence": "metadata-only" }
+        }
+      },
+      "web": { "enabled": true, "persistence": "exact" },
+      "fetch": { "enabled": true, "persistence": "exact" },
+      "codeSearch": { "enabled": true, "persistence": "exact" }
     },
-    "rawScriptPersistence": "disabled"
+    "scriptTransform": {
+      "enabled": true,
+      "sandbox": "auto",
+      "languages": ["javascript", "python", "jq"],
+      "network": "off",
+      "limits": {
+        "timeoutMs": 5000,
+        "maxInputBytes": 1048576,
+        "maxOutputBytes": 65536
+      },
+      "rawScriptPersistence": "disabled"
+    }
   }
 }
 ```
 
 Rules:
 
-- `outputRouter.enabled` defaults to `true`; write it only as an intentional high-level decision.
-- `outputRouter.profile` currently supports `standard`; write it only when the user chooses the evidence-routing branch.
-- `postToolRouting` defaults to `off`. Use `safety-net` only when explicitly requested. Treat `strict` as reserved; ask before writing it.
-- `largeOutputBytes`, `largeOutputLines`, and `vaultRetentionDays` must be positive integers.
-- `vaultRoot` must be a non-empty string. Repo-local storage requires explicit user choice.
-- `generatedPaths` are broad-scan generated-path hints. Explicit file or directory retrieval must remain available.
-- `noisyCommandHints` is parsed as hint config. Do not add it unless the user explicitly asks for command-pattern hints.
+- Top-level `enabled` and `skills.enabled` default to true after setup; write them only when the user explicitly wants to disable Freeflow or the skills layer.
+- `outputRouter.enabled` defaults to `false`; write `true` only when the user chooses Output Router.
+- `postToolRouting` defaults to `off`. Do not write `off`; use `safety-net` only when explicitly requested. Treat `strict` as reserved; ask before writing it.
+- `thresholds.largeOutputBytes`, `thresholds.largeOutputLines`, and `vault.retention.ttlDays` must be positive integers.
+- `vault.root` must be a non-empty string. Repo-local storage requires explicit user choice.
+- `hints.generatedPathGlobs` are broad-scan generated-path hints. Explicit file or directory retrieval must remain available.
+- `hints.noisyCommandPatterns` is parsed as hint config. Do not add it unless the user explicitly asks for command-pattern hints.
 - `observedRouting.enabled` defaults to `false`; write it only when the user chooses observed routing.
-- `observedRouting.onRoutingFailure` currently supports `fail-open`; write it only when persisting observed routing.
-- `observedRouting.mcp.servers` must contain explicit server entries only. Setup may discover configured servers for a multi-select, but must not persist a volatile inventory of every installed tool.
+- `observedRouting.onRoutingFailure` currently supports `fail-open`; omit it unless a caller needs an explicit non-default once supported.
+- `observedRouting.mcp.servers` must contain explicit server entries only. Setup may discover configured servers for selection, but must not persist a volatile inventory of every installed tool.
 - `observedRouting.web`, `observedRouting.fetch`, and `observedRouting.codeSearch` are Pi observed-routing producers. Enable only the producers the user chose.
 - Every enabled observed-routing entry needs a user-chosen persistence mode: `exact`, `metadata-only`, or `none`.
 - Recommend `exact` for public-ish evidence producers such as GitHub, web, fetch, and code search. Recommend `metadata-only` for sensitive or unknown producers such as Gmail, Slack, private customer systems, or likely-secret outputs.
 - Do not offer or write `redacted`; it is reserved for future work and currently falls back to `metadata-only` with a warning if hand-edited.
 - Pi public `freeflow_capture` and the separate `providers` setup surface have been removed. Do not write removed `capture` or `providers` config.
-- `scriptTransform.enabled` defaults to `false`; write it only after an explicit script-execution opt-in.
+- `scriptTransform.enabled` defaults to `false`; write `true` only after an explicit script-execution opt-in.
 - If the user opts into script transform setup and adapters are missing or unavailable, recommend installing global adapters. On consent, resolve `../../router/dist/setup/script-transform-adapters.js` relative to `skills/setup-freeflow/SKILL.md` and run `node <plugin-root>/router/dist/setup/script-transform-adapters.js install --config .freeflow/config.json`.
-- The installer uses `~/.cache/freeflow-script-adapters` by default, or `FREEFLOW_SCRIPT_TRANSFORM_ADAPTERS_HOME` when set. It installs `quickjs-wasi@3.0.1`, `jq-wasm@1.2.0-jq-1.8.2`, `@bsull/eryx@0.5.0`, and `node@24` for the Python JSPI child runner, writes `freeflow-adapter-env.sh`, probes sandbox proofs, and updates `scriptTransform.languages` with only proof-passing languages.
+- The installer uses `~/.cache/freeflow-script-adapters` by default, or `FREEFLOW_SCRIPT_TRANSFORM_ADAPTERS_HOME` when set. It installs `quickjs-wasi@3.0.1`, `jq-wasm@1.2.0-jq-1.8.2`, `@bsull/eryx@0.5.0`, and `node@24` for the Python JSPI child runner, writes `freeflow-adapter-env.sh`, probes sandbox proofs, and updates `outputRouter.scriptTransform.languages` with only proof-passing languages.
 - Freeflow auto-discovers adapters from that global cache. The explicit roots `FREEFLOW_QUICKJS_WASI_ROOT`, `FREEFLOW_JQ_WASM_ROOT`, and `FREEFLOW_ERYX_ROOT` remain overrides for custom installs.
 - Python/Eryx is installed by setup and uses the setup-installed child Node process launched with `--experimental-wasm-jspi` when the host process lacks JSPI. It must not be marked available unless that child runner passes the required sandbox probes.
 - `scriptTransform.languages` supports `javascript`, `python`, and `jq`; enable only languages whose adapters passed sandbox proofs.
@@ -88,14 +96,14 @@ Rules:
 
 ## Verify
 
-After writing optional evidence-routing config, use `freeflow_status` or equivalent direct inspection to verify effective behavior:
+After writing optional capability config, use `freeflow_status` or equivalent direct inspection to verify:
 
 - JSON parses.
 - `defaultMode` is valid.
-- Minimal setup still contains only `defaultMode` when capabilities were declined.
-- Optional `outputRouter`, `observedRouting`, and `scriptTransform` sections contain only requested keys.
-- Invalid router/observed-routing/script-transform values are not written.
-- Observed routing, native safety-net routing, and script transform are not enabled unless explicitly requested.
+- A minimal shared setup with no optional settings contains only `defaultMode`.
+- Newly added `enabled`, `interactionContract`, `skills.enabled`, `outputRouter`, `outputRouter.observedRouting`, and `outputRouter.scriptTransform` keys were requested; preserved valid settings remain unchanged.
+- Invalid router, observed-routing, or script-transform values are not written.
+- Output Router, observed routing, native safety-net routing, and script transform are not enabled unless explicitly requested.
 - If script transform setup was accepted, global adapter install completed or a clear install/probe failure was reported, and enabled languages match proof-passing adapters.
 - No observed-routing entry uses `redacted`, and every enabled entry has explicit persistence.
 - `freeflow_status` shows effective defaults and migration recommendations without rewriting config.

package/skills/simplify-code/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: simplify-code
+description: Use when simplifying working code without changing behavior, including removing duplication, indirection, dead abstractions, or confusing control flow.
+---
+
+# Simplify Code
+
+Reduce the concepts a reader must hold while preserving accepted behavior.
+
+Fewer lines, files, functions, or abstractions are not automatically simpler. Prefer the shape that makes behavior, ownership, and failure paths easier to understand and change.
+
+## Establish The Boundary
+
+Before editing:
+
+- understand the affected code, callers, tests, comments, and repository conventions;
+- establish the smallest verification baseline that protects observable behavior and error semantics;
+- understand why the current structure exists, including compatibility, performance, platform, history, and failure constraints;
+- define one narrow simplification outcome.
+
+Use this skill only when behavior should remain unchanged. If expected behavior is unclear or needs to change, return that evidence to [Workflow](../workflow/SKILL.md). If the interface or ownership is structurally wrong, use [Design for Depth](../design-for-depth/SKILL.md). If no reliable behavior loop exists, use [TDD](../tdd/SKILL.md) or [Diagnose Failure](../diagnose-failure/SKILL.md) first.
+
+Read [Code Practices](../execute-work/references/code-practices.md) while changing code. Read [Simplification Patterns](references/simplification-patterns.md) when choosing a transformation or deciding whether deletion really reduces complexity.
+
+## Classify The Opportunity
+
+- **Local expression:** names, guards, control flow, duplication, or unnecessary temporary state.
+- **Pass-through indirection:** wrapper, adapter, helper, or layer hides no useful decision.
+- **Accidental abstraction:** generalized machinery has no accepted variation or decision-hiding value.
+- **Scattered concept:** one behavior or policy can move toward one owner without changing its contract.
+- **Dead path:** evidence shows code is unused, unreachable, superseded, or impossible under current invariants.
+- **Structural pressure:** simplification requires changing interfaces, ownership, state, or architecture; return it to Workflow rather than presenting it as cleanup.
+
+## Simplify In Bounded Steps
+
+For each step:
+
+1. name the complexity being removed;
+2. make one behavior-preserving change;
+3. run the focused behavior and failure checks;
+4. inspect whether concepts, coordination, and change surface decreased;
+5. keep or revert the step from evidence.
+
+Keep feature work, bug fixes, edge-case handling, public behavior changes, and broad modernization outside the simplification slice. Report adjacent opportunities rather than absorbing them.
+
+Follow project conventions rather than personal style. Preserve relevant inputs, outputs, side effects, ordering, errors, timing, permissions, compatibility, and resource behavior.
+
+Preserve comments that explain non-obvious rationale, constraints, invariants, or workarounds. Update or remove comments that became stale. Do not add comments that merely narrate the simplified code.
+
+## Treat Tests As Evidence
+
+Do not rewrite valid behavior tests merely to make simplification pass.
+
+If an implementation-detail test fails while observable behavior appears unchanged, classify the conflict before editing it. Add characterization coverage when important accepted behavior lacks protection. Use expected values independent from the implementation.
+
+A green suite is necessary but not sufficient. Inspect the resulting code and real caller path.
+
+## Delete Deliberately
+
+Understand the purpose and current consumers before deleting code.
+
+Removing a useful module should concentrate complexity behind a better interface, not scatter it into callers. Do not delete compatibility, fallback, platform, migration, audit, or recovery behavior because it appears redundant. Use [Migration Work](../migration-work/SKILL.md) when removal has consumer or compatibility obligations.
+
+## Stop
+
+Stop when:
+
+- preserving behavior cannot be demonstrated;
+- the simpler version changes public or failure semantics;
+- performance or resource tradeoffs are material and unmeasured;
+- each step exposes another interface, ownership, or edge-case problem;
+- the diff broadens beyond the accepted boundary;
+- source truth or user decisions conflict with deletion;
+- the result is shorter but harder to explain or test.
+
+Once evidence supports unchanged behavior and the accepted complexity has been removed, freeze the slice. Further cleanup, modernization, and possible improvements require another selected slice. Do not continue to satisfy a line-count target or reviewer taste.
+
+## Report
+
+Report the boundary simplified, concepts or coordination removed, behavior evidence run before and after, relevant comments preserved or changed, intentionally retained complexity, and remaining unverified behavior. A successful simplification reduces reader and change coordination, not merely diff size.

package/skills/simplify-code/references/simplification-patterns.md

@@ -0,0 +1,70 @@
+# Simplification Patterns
+
+Use these as candidate transformations, not automatic rules. Preserve behavior and project conventions.
+
+## Control Flow
+
+- Replace deep nesting with guard clauses when exits are truly equivalent.
+- Collapse duplicate branches into one named path.
+- Replace repeated conditionals on one shape with an explicit model or dispatcher when that removes branching across callers.
+- Name intermediate concepts when a dense expression hides intent.
+- Keep straightforward branching when a lookup, callback table, or polymorphic hierarchy would add more concepts.
+
+## Locality
+
+- Move behavior toward the state or policy it owns.
+- Gather scattered validation, normalization, or failure handling behind one stable seam.
+- Separate orchestration from business rules when each can then be read and tested independently.
+- Reuse a canonical helper instead of maintaining a near-duplicate.
+- Do not centralize unrelated behavior merely because its syntax looks similar.
+
+## Indirection
+
+Question:
+
+- pass-through wrappers;
+- one-use factories and strategy layers;
+- aliases that no longer protect compatibility;
+- helpers whose interface is as complex as their implementation;
+- extension points with no accepted variation;
+- adapters that outlived a migration.
+
+Keep indirection when it hides volatile dependencies, enforces policy, preserves a real compatibility contract, or creates meaningful test and change locality.
+
+## Names And Types
+
+- Rename generic or misleading terms to match domain language.
+- Make invariants explicit at a type or interface boundary when doing so removes downstream checks.
+- Remove casts, optionality, and silent fallbacks only after proving the stronger invariant.
+- Keep comments that explain why, constraints, or non-obvious tradeoffs; remove comments that merely narrate clear code.
+
+## Duplication
+
+Duplication is harmful when one behavior must change in several places and can drift.
+
+Do not extract merely because two snippets look alike. First confirm they represent the same concept and should evolve together.
+
+A small amount of explicit repetition can be simpler than a generalized abstraction with configuration, callbacks, flags, or hidden coupling.
+
+## Dead And Legacy Paths
+
+Before removal, inspect static references, runtime use, generated callers, config, tests, history, and compatibility obligations.
+
+- Truly dead local code may be removed within the agreed simplification boundary.
+- Supported legacy behavior requires deprecation/migration evidence.
+- Historical docs and audit evidence are not dead code.
+- Commented-out code normally belongs in version history, but confirm it is not an intentional operational instruction.
+
+## Before And After Test
+
+Ask:
+
+- Are there fewer concepts and branches?
+- Is ownership clearer?
+- Can behavior be understood through fewer files or transitions?
+- Did error and failure semantics remain visible?
+- Is the public interface smaller or unchanged?
+- Did tests become more behavior-focused rather than more coupled?
+- Would the next likely change touch fewer coordinated locations?
+
+If the answer is mostly no, complexity was relocated rather than reduced.