@hassangameryt/freeflow 0.1.0 → 0.3.0

package/{plugins/freeflow/skills → skills}/setup-freeflow/references/activation-contract.md

@@ -10,6 +10,7 @@ Use this Markdown reference as the v0.1 contract module:
 getActivationContract(defaultMode) -> ActivationContract
 planActivation(contract, repoState, request) -> ActivationPlan | ActivationStop
 renderActivation(contract, target) -> rendered text or checks
+planOptionalEvidenceRoutingConfig(request) -> EvidenceRoutingConfigPlan | ActivationStop
 ```
 
 Do not add a code module until setup behavior needs logic that cannot be kept clear in the skill and this reference.
@@ -17,7 +18,8 @@ Do not add a code module until setup behavior needs logic that cannot be kept cl
 ## Invariants
 
 - Activation text contains always-on invariants only, not the full workflow spine.
-- Config has exactly one field: `defaultMode`.
+- 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`.
@@ -25,9 +27,9 @@ Do not add a code module until setup behavior needs logic that cannot be kept cl
 - 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, version metadata, activation path, current task, or current phase.
-- Plugin-bundled context hooks may load workflow and interview-gate context at session start, but they are package runtime, not setup output.
-- After successful setup verification, setup reads the workflow skill, workflow map, and interview-gate skill before its final response so the current session is immediately usable.
+- 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.
 
 ## Host Adapters
 
@@ -46,8 +48,12 @@ Claude adapter:
 Config adapter:
 
 - Create or update `.freeflow/config.json`.
-- Write exactly `{ "defaultMode": "<mode>" }`.
+- 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`.
 
 ## Codex Core Block
 
@@ -81,14 +87,14 @@ Verify before completion claims. Capture only stable decisions, glossary terms,
 
 ## Drift Checks
 
-Run `plugins/freeflow/evals/scripts/check-activation-contract.sh` when changing setup behavior, post-setup fixtures, setup eval assertions, or docs that quote setup behavior.
-Run `plugins/freeflow/evals/scripts/check-runtime-context-hook.sh` when changing plugin-bundled runtime context hooks.
+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.
 
 The check keeps these surfaces aligned:
 
 - this canonical reference
 - `setup-freeflow/SKILL.md`
 - `setup-freeflow/references/host-setup.md`
-- `docs/freeflow-runtime-and-lifecycle.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

package/{plugins/freeflow/skills → skills}/setup-freeflow/references/host-setup.md

@@ -16,6 +16,8 @@ Current runtime is not enough to choose a host when both `AGENTS.md` and `CLAUDE
 
 Solo setup is the default: one host target, compact activation, `defaultMode: "workflow"`, no extra docs.
 
+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.
+
 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.
 
 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.
@@ -24,10 +26,10 @@ Valid persisted defaults are exactly `conversation`, `workflow`, and `strict-wor
 
 ## Not Setup
 
-Do not install repo-local hooks, CLI commands, lint rules, global standards, docs inventories, or state files during setup.
+Do not install repo-local hooks, CLI commands, lint rules, global standards, docs inventories, setup-output-router skills, or state files during setup.
 
-Freeflow's plugin-bundled context hooks are package runtime. They load workflow and interview-gate context at session start, but setup should not copy hook files into the target repo.
+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.
 
-After successful setup verification, setup should read the workflow skill, workflow map, and interview-gate skill 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.
+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.
 
 If the user asks for enforcement, say Freeflow setup is instruction-only for now and ask whether to handle enforcement as a separate task.

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

@@ -0,0 +1,102 @@
+# 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`).
+
+## 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.
+- Observed routing is opt-in per producer/server. The user must choose persistence for each enabled entry before setup writes config.
+- 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.
+
+## 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.
+
+Supported high-level repo config keys:
+
+```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" }
+      }
+    },
+    "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
+    },
+    "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.
+- `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.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.
+- 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.
+- 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.
+- `scriptTransform.sandbox` currently supports `auto`, `network` supports only `off`, and `rawScriptPersistence` supports only `disabled`.
+- `scriptTransform.limits.timeoutMs`, `maxInputBytes`, and `maxOutputBytes` must be positive integers within product caps. Per-call script limits may only tighten configured values.
+
+## Verify
+
+After writing optional evidence-routing config, use `freeflow_status` or equivalent direct inspection to verify effective behavior:
+
+- 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.
+- 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.
+- No repo-local hooks, skill files, setup-output-router skill, docs inventories, or repo-local storage directories were created.

package/{plugins/freeflow/skills → skills}/verify-work/SKILL.md

@@ -57,6 +57,8 @@ Not verified: ...
 Next: ...
 ```
 
-For completed consequential work, `Next:` is mandatory. Omit it only for direct question answers, mid-task status, or clarification-only turns.
+For completed consequential work, include `Next:` because completion leaves a route decision. Omit it only for direct question answers, mid-task status, clarification-only turns, or direct owner-decision questions.
+
+For pure questions, include `Next:` only when a concrete next route helps.
 
 Keep it short.

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

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

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

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

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

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

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

@@ -21,7 +21,7 @@ Do not add references, examples, README files, changelogs, or metadata when a co
 
 Do not add helper scripts for commands the agent can run directly, such as `git log`, `git diff`, search, formatting, or line counts. Scripts are for repeated deterministic work that would be risky or wasteful to retype.
 
-Follow the repo's line budget. If none exists, keep `SKILL.md` under 100 lines unless the extra lines clearly earn their place.
+Treat the repo's line budget as a best practice, not a hard cap. If none exists, aim to keep `SKILL.md` under 100 lines for normal skills. Let deep skills exceed it when the active rules, examples, or structure clearly earn their place.
 
 ## Description First
 

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

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

package/plugins/freeflow/docs/README.md

@@ -1,39 +0,0 @@
-# Freeflow Docs
-
-These docs describe the public plugin behavior. Historical research stays in root `docs/`; eval sources and reports live under `plugins/freeflow/evals/`.
-
-After installing Freeflow, run setup in each repo where you want it active:
-
-```text
-/setup-freeflow
-```
-
-Setup creates activation/config files only.
-
-In Codex, open the hooks screen after install:
-
-```text
-/hooks
-```
-
-Press `t` to trust/enable the Freeflow `SessionStart` hook when Codex marks it as needing review. Once enabled, plugin-bundled hooks load workflow and interview-gate context at session start, resume, clear, and compact.
-
-In Pi, install Freeflow as a Pi package from npm:
-
-```bash
-pi install npm:@hassangameryt/freeflow
-```
-
-Or install directly from GitHub:
-
-```bash
-pi install git:github.com/hassan-mohiddin/freeflow
-```
-
-The package exposes `plugins/freeflow/skills/` and `plugins/freeflow/pi-extension/index.js`. The Pi extension registers direct Freeflow commands, keeps `/workflow` mode changes scoped to the Pi session, refreshes workflow and interview-gate context on session start and compact, and injects that context before agent turns. It does not enforce policy, block tools, grant permissions, or create repo-local hooks.
-
-- [Workflow](workflow.md): modes, entry points, loops, and the compact workflow map.
-- [Skills](skills.md): shipped skills and what each one is for.
-- [Architecture](architecture.md): package layout, runtime boundary, context hooks, and progressive disclosure model.
-- [Release evidence](release-evidence.md): v0.1 acceptance evidence and deferred checks.
-- [ADRs](adr/README.md): durable release decisions.

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

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

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

@@ -1,7 +0,0 @@
-# Freeflow ADRs
-
-Durable decisions for the public Freeflow package:
-
-- [ADR 0001: Three Workflow Modes](0001-three-modes.md)
-- [ADR 0002: Evals Before Enforcement Hooks](0002-evals-before-hooks.md)
-- [ADR 0003: v0.1 Release Boundary](0003-release-boundary.md)