@hassangameryt/freeflow 0.3.0 → 0.5.0

package/skills/review-work/references/security-risk-lens.md

@@ -0,0 +1,67 @@
+# Security Risk Lens
+
+Read this when work changes trust boundaries, authentication, authorization, permissions, untrusted input, secrets, sensitive data, dependencies, external integrations, execution, or failure behavior with security consequences.
+
+This lens helps frame review. It does not replace repo security policy, threat modeling, specialist review, or stack-specific hardening guidance.
+
+## Establish Authority
+
+Identify:
+
+- assets and data requiring protection;
+- actors, roles, tenants, and privilege levels;
+- trust boundaries and external systems;
+- accepted security/privacy policy and threat model;
+- compatibility and failure behavior that security controls must preserve.
+
+Security-sensitive product behavior remains user-owned. Do not invent access, retention, logging, or fail-open/closed policy during review.
+
+## Trace The Paths
+
+Review the affected path from boundary to effect:
+
+- authentication: who or what is this actor;
+- authorization: may this actor perform this operation on this resource;
+- input: validation, canonicalization, size, encoding, and injection surfaces;
+- output: escaping, disclosure, error detail, and side channels;
+- data: collection, transport, storage, isolation, retention, deletion, and audit;
+- secrets: source, scope, rotation, exposure, and logging;
+- execution: shell, file, URL, template, deserialization, plugin, or code-loading boundaries;
+- dependencies: provenance, permissions, known risk, update impact, and transitive behavior;
+- failure: partial state, retries, lockout, rate limits, rollback, and fail-open/closed behavior.
+
+Look for confused-deputy and cross-tenant paths, not only malformed input.
+
+## Evidence
+
+Prefer evidence at the real boundary:
+
+- tests proving allowed and denied roles/resources;
+- negative input and injection cases;
+- dependency or configuration inspection tied to the shipped artifact;
+- logs or traces demonstrating no secret/sensitive leakage;
+- failure-path tests for partial authorization, retry, and recovery;
+- specialist analysis for cryptography, sandboxing, identity protocols, or high-impact threats.
+
+A generic scanner pass cannot prove authorization logic or policy correctness. A unit test cannot prove deployed headers, identity configuration, or infrastructure permissions.
+
+Do not copy secrets, credentials, unrestricted personal data, or sensitive payloads into review context. Use the smallest sanitized evidence that supports the review item.
+
+## Review Item Calibration
+
+Treat supported exploitable behavior, policy violation, unintended privilege or data exposure, unsafe failure semantics, secret leakage, or a missing required control as an Issue.
+
+Classify the Issue against the accepted security policy and reviewed boundary:
+
+- **Blocking:** crossing the boundary would remain unsafe, non-compliant, or contrary to a required control.
+- **Non-blocking:** the security issue is real but can be deferred safely without violating the accepted boundary.
+
+Use **Question** when security behavior or accepted risk remains undecided. Use **Needs evidence** when a control may exist but the available test or environment cannot establish it.
+
+Treat materially useful defense-in-depth beyond the accepted boundary as an Improvement. Do not turn theoretical hardening, preference, or hypothetical completeness into an Issue.
+
+Do not omit an observed security issue merely because the selected lenses were narrower. Name the asset, path, precondition, consequence, evidence, and source requirement.
+
+## Route
+
+When security evidence changes the path, use [Workflow](../../workflow/SKILL.md) to choose what follows. Use [Diagnose Failure](../../diagnose-failure/SKILL.md) for unknown exploitability or root cause, [Decision Gate](../../decision-gate/SKILL.md) for missing policy or accepted-risk decisions, [Design For Depth](../../design-for-depth/SKILL.md) when trust decisions spread across callers, and [Launch Work](../../launch-work/SKILL.md) when the concern affects production rollout.

package/skills/setup-freeflow/SKILL.md

@@ -1,106 +1,92 @@
 ---
 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.
+description: Use when activating Freeflow in a repository, repairing its repository or personal configuration, or checking whether the current host is delivering Freeflow context.
 ---
 
 # Setup Freeflow
 
-Use `references/activation-contract.md` before rendering activation text, config, or host setup.
+Create or repair the smallest valid layered setup. Keep repository activation, personal overrides, and host runtime delivery as separate facts.
 
-Use `references/host-setup.md` when the request mentions Codex, Claude, both hosts, team setup, solo setup, strict defaults, hooks, CLI, or setup profiles.
+- `.freeflow/config.json` is the required shared repository activation config.
+- `.freeflow/local.json` is an optional per-checkout personal override. It cannot activate Freeflow by itself.
+- Runtime delivery depends on the current host's installed and trusted adapter.
 
-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.
+Answer setup questions and delivery checks read-only. An explicit action request authorizes the smallest selected setup change under the state rules below. When repository config is missing, first activation authorizes minimal shared config; it does not authorize personal overrides, optional capabilities, replacement of invalid config, or edits to repo-owned host instructions.
 
-## Stop Before Editing
+Read [the activation contract](references/activation-contract.md) before changing setup state. Read [host setup](references/host-setup.md) when runtime delivery, lifecycle, or host trust matters.
 
-Do not create config, add activation blocks, imports, or rule files until setup has a clear host target and no unresolved repo-rule conflict.
+## Establish Mutation Authority
 
-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
+Classify the current state before editing:
 
-For a hard stop, make no file changes. Name the blocker and ask one direct question.
+- **Unconfigured:** repository config is missing or invalid, so no Freeflow mode is effective. An explicit setup request may create minimal config when it is missing. Replacing or reinterpreting invalid config still requires the specific authority described below.
+- **Configured but ineffective:** valid repository activation exists, but Freeflow is disabled, Skills are dormant, or invalid local config blocks runtime. No mode is effective. An explicit request governs the selected enablement, configuration, or repair; any dormant resolved mode does not.
+- **Effective:** Freeflow Skills report an effective mode. Obey it. Conversation remains read-only; Workflow or Strict Workflow allows agent-performed mutation only for the separately requested setup or repair.
 
-## Inspect
+User-operated host settings are direct user actions, not agent-performed config edits. Prefer them when available and do not claim their state changed until the host reports it.
 
-Inspect `.freeflow/config.json`, `AGENTS.md`, `CLAUDE.md`, `.claude/rules/freeflow-core.md`, `.codex/rules/`, existing `## Freeflow` blocks, and conflicting repo instructions.
+## Inspect The Layers
 
-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.
+Before editing:
 
-## Target
+1. inspect `.freeflow/config.json` and `.freeflow/local.json` independently;
+2. identify which requested values are shared repository state and which are personal overrides;
+3. inspect repo instructions only when a conflict would change setup behavior;
+4. identify the host and available delivery evidence when runtime status matters.
 
-- 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.
+A valid repository config establishes activation. A missing local config inherits shared values. An invalid existing local config blocks effective Freeflow instead of falling back silently.
 
-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.
+If setup is already valid and no change was requested, preserve it and report the effective sources. Do not rewrite config merely to normalize formatting or materialize defaults.
 
-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.
+## Configure Shared Activation
 
-## Config
+For a new default setup, write:
 
-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
+```json
+{
+  "defaultMode": "workflow"
+}
 ```
 
-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.
+During first activation, an explicitly requested `conversation` or `strict-workflow` mode becomes the shared repository default. Preserve valid existing settings and add no unrequested keys or empty sections.
+
+If repository config is invalid or conflicts with accepted source truth, use [Decision Gate](../decision-gate/SKILL.md) before replacing or reinterpreting it.
 
-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.
+Do not create or append Freeflow instructions in `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, or another host-owned instruction surface.
 
-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.
+## Add Personal Overrides Only When Requested
 
-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.
+Use `.freeflow/local.json` for an explicitly selected per-checkout override of `enabled`, `interactionContract`, `skills.enabled`, or `defaultMode`. Omitted values inherit from repository config and built-in defaults.
 
-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.
+In Pi, `/freeflow settings` edits personal overrides and `/freeflow settings repo` edits shared settings. Prefer those controls when available.
 
-## Activation
+Before writing local config in a Git checkout, verify it is untracked and ignored. Do not modify shared ignore policy merely to store a personal preference; use the host's safe settings path or local Git exclusion. Refuse to overwrite a tracked local config.
 
-Render the canonical blocks from `references/activation-contract.md`.
+If local config is invalid, report that it blocks effective runtime. Repair or remove it only with authorization; never discard it and fall back silently.
 
-For Codex, put the Codex core block in `AGENTS.md`.
+## Establish Same-Turn Context
 
-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.
+After successful verification, apply newly effective context directly for the remainder of the setup turn:
 
-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.
+- read the [Interaction Contract](../../runtime/interaction-contract.md) when it is effective;
+- read [Workflow](../workflow/SKILL.md) and [Mode Contract](../mode-contract/SKILL.md) when Skills are effective.
 
-## Do Not Create
+This direct read establishes same-turn guidance; it does not prove that a lifecycle adapter ran. After first activation, use [host setup](references/host-setup.md) to name the exact host-native lifecycle action for automatic delivery and resource refresh, state what applies before that boundary, and keep delivery confirmed, unavailable, or unconfirmed from evidence.
 
-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 And Report
 
-## Verify
+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
+- repository config parses and contains a valid `defaultMode`;
+- local config is missing or valid, personal, untracked, and ignored when applicable;
+- effective `enabled`, Interaction Contract, Skills, and configured default values have the expected sources;
+- Skills-disabled mode remains resolved but dormant;
+- no repo-owned host instructions or 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.
+Report separately:
 
-If verification cannot run, say what remains unverified.
+1. shared repository activation;
+2. personal override state and effective sources;
+3. effective Interaction Contract, Skills, and mode state;
+4. same-turn direct context reads;
+5. automatic runtime delivery as **confirmed**, **unavailable**, or **unconfirmed**.

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

@@ -1,100 +1,115 @@
 # 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.
+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.
 
-## Host Adapters
+Missing or invalid repository config means repository activation is absent. A valid config with effective `enabled: false` remains configured but inactive.
 
-Codex adapter:
+## Personal Overrides
 
-- 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.
+`.freeflow/local.json` is optional per-checkout state. It cannot activate Freeflow without a valid repository config.
 
-Claude adapter:
+It may override these core values:
 
-- 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.
+```json
+{
+  "enabled": true,
+  "interactionContract": true,
+  "skills": {
+    "enabled": true
+  },
+  "defaultMode": "strict-workflow"
+}
+```
 
-Config adapter:
+Every field is optional. Omission inherits the repository value, then the built-in default. Local core precedence is property-level, not whole-file replacement.
 
-- 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`.
+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.
 
-## Codex Core Block
+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.
 
-<!-- freeflow-activation-contract:codex-core:start -->
-```md
-## Freeflow
+## Effective Core State
 
-Use Freeflow for consequential work. Default mode: `.freeflow/config.json`.
+Resolve core values in this order:
 
-Move forward when context is sufficient. Re-enter clarification when new ambiguity would change the next action.
+```text
+host session override -> personal override -> repository value -> built-in default
+```
 
-Treat questions as questions and suggestions as hypotheses. Answer directly; do not infer correction, permission, or agreement.
+Host session overrides are host state, not config, and cannot bypass missing or invalid repository activation. Pi may temporarily override Freeflow master enablement, Interaction Contract, Skills, and mode. Claude and Codex support mode-only overrides in plugin-owned session state.
 
-Ask before user-owned decisions: product behavior, scope, public APIs, security, privacy, billing, data loss, compatibility, permissions, or irreversible architecture.
+Effective Freeflow requires:
 
-Treat live repo evidence and existing docs/tests as source truth. If the user request conflicts with them, stop and ask before changing behavior.
+1. valid repository config;
+2. missing or valid local config;
+3. session-resolved `enabled: true`.
 
-Verify before completion claims. Capture only stable decisions, glossary terms, ADR-worthy tradeoffs, or useful handoff memory.
-```
-<!-- freeflow-activation-contract:codex-core:end -->
+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 Import Block
+## Mutation Authority By State
 
-<!-- freeflow-activation-contract:claude-import:start -->
-```md
-## Freeflow
+Mode constrains agent-performed setup only when a mode is effective:
 
-@.claude/rules/freeflow-core.md
-```
-<!-- freeflow-activation-contract:claude-import:end -->
+- **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 state.
+
+Pi may additionally deliver explicitly enabled Pi capability context through its extension. Codex and Claude `SessionStart` hooks deliver only the core Interaction Contract, Workflow bootstrap, and mode state; their `UserPromptSubmit` hook delivers only an explicit session-mode change or failure delta.
+
+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,68 @@
 # 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 runtime hook reads the same repository and local layers plus plugin-owned session mode state. At supported session start, resume, clear, and compact boundaries, `SessionStart` restores the complete enabled context. On submitted prompts, `UserPromptSubmit` changes mode only for an explicit native or conservative natural-language session control and otherwise emits nothing.
+
+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 configured, session, resolved, and effective mode state without treating a configured default as the current session mode.
+
+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.
+
+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/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.