@hassangameryt/freeflow 0.4.0 → 0.6.0

package/skills/review-artifact/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-artifact
-description: Use when reviewing a Working Record, spec, PRD, issue, API contract, technical design, migration contract, plan, decision record, ADR, handoff, or other durable artifact for fitness to guide its intended use.
+description: Use when reviewing durable task memory, a spec, PRD, issue, API contract, technical design, migration contract, plan, decision record, ADR, handoff, or another durable artifact for fitness to guide its intended use.
 ---
 
 # Review Artifact
@@ -14,7 +14,7 @@ Choose the role before reviewing:
 - **Self-review:** you produced the artifact. Inspect it silently using the relevant boundary and lenses below. Correct clear local issues within existing authority. Create no formal review items, judgment, number, or cycle. Return unresolved material issues to [Workflow](../workflow/SKILL.md).
 - **Independent review:** you did not produce the reviewed state. Inspect and report without editing. Use the formal item, judgment, and report method below. The receiving active agent adjudicates and routes the result.
 
-Reading this skill does not create independence. If you produced the artifact, do not present your own judgment as independent review. Read [the reviewer prompt](references/reviewer-prompt.md) when preparing or performing a separately selected independent review.
+Reading this skill does not create independence. If you produced the artifact, do not present your own judgment as independent review. Read the [Independent Artifact Reviewer Contract](references/independent-artifact-reviewer-contract.md) when preparing or performing a separately selected independent review.
 
 ## Establish The Boundary
 
@@ -29,6 +29,8 @@ Understand:
 
 Review the complete current artifact, not only its summary, change description, or author's reasoning. Review upstream authority before dependent artifacts. If an upstream issue invalidates downstream assumptions, mark affected material contingent instead of generating exhaustive findings against an unresolved basis.
 
+Review Artifact owns the intended-use boundary, lenses, and judgment. When source or dependency inspection branches among several plausible observers or is likely to be broad, use [Action Selection](../action-selection/SKILL.md) to choose and bound one environment interaction. It returns evidence to the same review role. Skip it for an obvious artifact, dependency, or source-truth read.
+
 When reviewing a Working Record, read [Track Work](../track-work/SKILL.md), which owns its format and lifecycle.
 
 ## Judge The Artifact By Its Job
@@ -72,33 +74,35 @@ A Blocking Issue must name the exact location, violated source truth or artifact
 
 Pass, Non-blocking, Inconclusive, and Blocking are all valid review exits. A review ends with its report; it does not remain active until the artifact passes.
 
-## Adjudicate And Route
-
-After independent review, the receiving active agent adjudicates each item against the artifact, source truth, and evidence:
+## Adjudicate Independent Review And Route
 
-- **Accepted:** supported and applicable.
-- **Rejected:** unsupported, stale, resolved, duplicate, preference-only, outside the artifact's job, or based on a source misread.
-- **Open:** a question or evidence gap prevents acceptance or rejection.
+After independent review, the receiving active agent adjudicates each material item against the artifact, source truth, and evidence rather than forwarding the report:
 
-Confirm whether each accepted Issue is Blocking or Non-blocking, then derive the adjudicated judgment. Do not accept the reviewer's overall judgment separately.
+- **Accepted:** supported and applicable. State the actual artifact problem, consequence for its intended use, and whether the revision basis is supported or uncertain.
+- **Rejected:** unsupported, stale, resolved, duplicate, preference-only, outside the artifact's job, or based on a source misread. State why.
+- **Open:** a question or evidence gap prevents acceptance or rejection. State the concern, potential consequence, and missing evidence or decision.
 
-Route from the adjudicated result:
+A reviewer's suggested revision may bound an item, but it does not settle source intent or select the revision. Confirm whether each accepted Issue is Blocking or Non-blocking, derive the adjudicated judgment, and do not accept the reviewer's overall judgment separately.
 
 - **Pass:** use the artifact for its intended purpose.
 - **Non-blocking:** use it with explicit deferrals.
 - **Inconclusive:** gather the missing evidence or decision.
 - **Blocking:** do not use the artifact across the blocked boundary; re-enter its narrowest owner, defer, or stop.
 
-Review findings are evidence, not commands. They do not authorize revision. Accepted revisions leave review and return to the artifact's owning skill; they may remain in the same [Track Work](../track-work/SKILL.md) slice while its intended result stays coherent.
+### Decide Whether Independent-Review Revision Is Ready
+
+A revision is ready when the artifact's job, the problem and consequence, and enough source or decision basis support a bounded revision. When the issue and source are clear, the revision local, affected dependencies known, and no material alternative or user choice remains, include adjudication and revision in the same assistant response.
 
-When revision authority is not already explicit, ask once for either:
+Use the current response for a separate problem checkpoint when findings interact, source intent or dependency effects remain uncertain, accepted content or strategy is challenged, materially different revisions remain, the artifact relies on an unsupported failure cause, or user input could change the approach:
 
-- the accepted revisions plus one warranted focused follow-up review; or
-- the accepted revisions alone when direct source evidence can settle the changed boundary.
+1. Report the adjudication, problem and consequence, revision-basis status, settled constraints, and controlling question or evidence.
+2. Name [Discuss](../discuss/SKILL.md), [Diagnose Failure](../diagnose-failure/SKILL.md), [Decision Gate](../decision-gate/SKILL.md), evidence gathering, or the artifact's affected owner as the next route, then stop and wait.
 
-Then wait for the user's response. Do not revise or dispatch a follow-up from the request, and do not ask again when existing authority already covers the bounded revision or review.
+Continue revision selection only when a later user turn or new evidence supplies enough support. Do not request revision authority before selecting a direction or wait for the user to elicit the missing analysis. The checkpoint is not another review and creates no revision or dispatch authority.
 
-Run a follow-up only when the changed boundary or affected dependencies still need independent judgment and that dispatch is authorized. Do not revise source truth, accepted intent, or owner decisions merely to satisfy a reviewer or obtain Pass.
+A revision-ready route states the proposed revision and rationale, dependency impact, verification boundary, whether focused follow-up is needed, and authority status. Findings are evidence, not commands, and do not authorize revision. Accepted revisions return to the artifact's owning skill and may remain in the same [Track Work](../track-work/SKILL.md) slice while its intended result stays coherent.
+
+Use existing revision authority when it covers the result. Otherwise ask once for the revision and any warranted focused follow-up; omit follow-up when direct source evidence can settle the changed boundary. Then wait; do not revise or dispatch a follow-up from the request itself. Run follow-up only when the changed boundary or affected dependencies still need independent judgment and that dispatch is authorized. Do not revise source truth, accepted intent, or owner decisions merely to satisfy a reviewer or obtain Pass.
 
 ## Limit The Review Cycle
 
@@ -106,21 +110,19 @@ For one independently reviewed artifact state and intended-use boundary:
 
 1. Review 1 is the normal broad review.
 2. Review 2, when needed and authorized, focuses on accepted revisions, affected dependencies, and remaining risk.
-3. Review 3 is exceptional, authorized separately, and final for that cycle.
+3. Review 3 is exceptional, separately authorized, and final.
 
-The budget is a cap, not dispatch authority. Do not request Review 4. At the cap, adjudicate and return control to Workflow; the artifact may be used, remain blocked, re-enter its owner, defer, or stop.
+The budget is a cap, not dispatch authority. Do not request Review 4; return control to Workflow at the cap.
 
-After Review 2 is adjudicated Blocking, stop before proposing another revision or Review 3. Classify its relationship to the prior revision:
+After Review 2 is adjudicated Blocking, stop before another revision or Review 3:
 
-- If the blocker repeats, extends, invalidates, or exposes another consequence of the prior revision, or its cause remains unsupported, read [Diagnose Failure](../diagnose-failure/SKILL.md) and diagnose the shared cause before another revision.
-- If it is an independent clear local defect with a supported cause, return directly to the artifact's owner and state why diagnosis is unnecessary.
+- If the blocker repeats, extends, invalidates, or exposes another consequence of the prior revision, or its cause remains unsupported, read [Diagnose Failure](../diagnose-failure/SKILL.md) and diagnose the shared cause first.
+- If it is an independent clear local defect with a supported cause, return to the artifact's owner and state why diagnosis is unnecessary.
 
-A reviewer judgment alone does not trigger diagnosis; active-agent adjudication and evidence do. Review 3 is final judgment after the cause and revision boundary are understood, not a third attempt to discover the cause through revisions. Workflow may later establish a new cycle only for a materially new artifact state and intended-use boundary; local edits, a different reviewer, or renamed scope do not reset it.
+Diagnosis follows adjudicated evidence, not reviewer judgment alone. Review 3 is final judgment after the cause and revision boundary are understood, not another attempt to discover them through revisions. Workflow may establish a new cycle only for a materially new reviewed state and intended-use boundary; local edits, a different reviewer, or renamed scope do not reset it.
 
 ## Report
 
-For self-review, report no formal review result. Correct clear local issues and surface only unresolved material issues that change fitness or route.
-
-For independent review, use the structured output in [the reviewer prompt](references/reviewer-prompt.md). The receiving agent reports the reviewer and adjudicated judgments, each material item's Accepted, Rejected, or Open outcome and reason, affected dependencies, remaining open items, and authorized or proposed next route.
+For self-review, report no formal result. Correct clear local issues and surface only unresolved material issues that change fitness or route.
 
-Omit empty groups. Support material judgments and adjudication with source or evidence rather than confidence.
+For independent review, use the [Independent Artifact Reviewer Contract](references/independent-artifact-reviewer-contract.md) and stop with its report. The receiving agent then reports the reviewer and adjudicated judgments, each material item's outcome and reason, and either the problem checkpoint or revision-ready route defined above. Omit empty groups and support the result with source or evidence rather than confidence.

package/skills/review-work/SKILL.md

@@ -16,7 +16,7 @@ Choose the role before reviewing:
 - **Self-review:** you produced the work. Inspect it silently using the relevant boundary and lenses below. Correct clear local issues within existing authority and re-verify. Create no formal review items, judgment, number, or cycle. Return unresolved material issues to [Workflow](../workflow/SKILL.md).
 - **Independent review:** you did not produce the reviewed state. Inspect and report without editing. Use the formal item, judgment, and report method below. The receiving active agent adjudicates and routes the result.
 
-Reading this skill does not create independence. If you produced the work, do not present your own judgment as independent review. Read [the reviewer prompt](references/reviewer-prompt.md) when preparing or performing a separately selected independent review.
+Reading this skill does not create independence. If you produced the work, do not present your own judgment as independent review. Before preparing or performing a separately selected independent review, read the [Independent Work Reviewer Contract](references/independent-work-reviewer-contract.md).
 
 ## Establish The Boundary
 
@@ -28,7 +28,9 @@ Understand:
 - verification evidence and known gaps;
 - risks and interactions material to the future action this review protects.
 
-Inspect the work and source truth directly, not only the author's summary, reasoning, or claimed result. Read [the security risk lens](references/security-risk-lens.md) when the work changes a security-relevant boundary.
+Inspect the work and source truth directly, not only the author's summary, reasoning, or claimed result. Before reviewing work that changes trust boundaries, authentication, authorization, permissions, untrusted input, secrets, sensitive data, security-relevant dependencies or external integrations, code-execution boundaries, or failure behavior with security consequences, read the [Security Risk Lens](references/security-risk-lens.md).
+
+Review Work owns the review boundary, lenses, and judgment. When source inspection branches among several plausible observers or is likely to be broad, use [Action Selection](../action-selection/SKILL.md) to choose and bound one environment interaction. It returns evidence to the same review role. Skip it for an obvious diff, file, or source-truth read.
 
 ## Review Proportionately
 
@@ -72,33 +74,35 @@ Use the most consequential applicable judgment:
 
 Pass, Non-blocking, Inconclusive, and Blocking are all valid review exits. A review ends with its report; it does not remain active until the work passes.
 
-## Adjudicate And Route
-
-After independent review, the receiving active agent adjudicates each item against the work, source truth, and evidence:
+## Adjudicate Independent Review And Route
 
-- **Accepted:** supported and applicable.
-- **Rejected:** unsupported, stale, resolved, duplicate, preference-only, out of scope, or based on a source misread.
-- **Open:** a question or evidence gap prevents acceptance or rejection.
+After independent review, the receiving active agent adjudicates each material item against the work, source truth, and evidence rather than forwarding the report:
 
-Confirm whether each accepted Issue is Blocking or Non-blocking, then derive the adjudicated judgment. Do not accept the reviewer's overall judgment separately.
+- **Accepted:** supported and applicable. State the actual implementation problem, boundary consequence, and whether its cause is supported, unnecessary to select a bounded correction, or uncertain.
+- **Rejected:** unsupported, stale, resolved, duplicate, preference-only, out of scope, or based on a source misread. State why.
+- **Open:** a question or evidence gap prevents acceptance or rejection. State the concern, potential consequence, and missing evidence or decision.
 
-Route from the adjudicated result:
+A reviewer's suggested correction may bound an item, but it does not establish the cause or select the remedy. Confirm whether each accepted Issue is Blocking or Non-blocking, derive the adjudicated judgment, and do not accept the reviewer's overall judgment separately.
 
 - **Pass:** proceed.
 - **Non-blocking:** proceed with explicit deferrals.
 - **Inconclusive:** gather the missing evidence or decision.
 - **Blocking:** do not cross the boundary; re-enter the narrowest owning activity, defer, or stop.
 
-Review findings are evidence, not commands. They do not authorize edits. Accepted implementation corrections leave review and return to [Execute Work](../execute-work/SKILL.md); they may remain in the same [Track Work](../track-work/SKILL.md) slice while its intended result stays coherent.
+### Decide Whether Independent-Review Remediation Is Ready
+
+Remediation is ready when accepted behavior, the problem and consequence, and enough causal or decision basis support a bounded correction. When the finding is clear, the correction local, verification direct, and no material alternative or user choice remains, include adjudication and remediation in the same assistant response.
 
-When correction authority is not already explicit, ask once for either:
+Use the current response for a separate problem checkpoint when findings interact, the cause matters but remains unsupported, accepted assumptions or design are challenged, materially different corrections remain, or user input could change the approach:
 
-- the accepted corrections plus one warranted focused follow-up review; or
-- the accepted corrections alone when direct evidence can settle the changed boundary.
+1. Report the adjudication, problem and consequence, cause status, settled constraints, and controlling question or evidence.
+2. Name [Discuss](../discuss/SKILL.md), [Diagnose Failure](../diagnose-failure/SKILL.md), [Decision Gate](../decision-gate/SKILL.md), evidence gathering, or another affected owner as the next route, then stop and wait.
 
-Then wait for the user's response. Do not correct or dispatch a follow-up from the request, and do not ask again when existing authority already covers the bounded correction or review.
+Continue remedy selection only when a later user turn or new evidence supplies enough support. Do not request implementation authority before selecting a remedy or wait for the user to elicit the missing analysis. The checkpoint is not another review and creates no correction or dispatch authority.
 
-Verify authorized corrections. Run a follow-up only when the changed boundary still needs independent judgment and that dispatch is authorized. Do not change tests, Specs, policies, or accepted behavior merely to satisfy a reviewer or obtain Pass.
+A remediation-ready route states the proposed correction and rationale, verification boundary, whether focused follow-up is needed, and authority status. Findings are evidence, not commands, and do not authorize edits. Accepted corrections return to [Execute Work](../execute-work/SKILL.md) and may remain in the same [Track Work](../track-work/SKILL.md) slice while its intended result stays coherent.
+
+Use existing correction authority when it covers the result. Otherwise ask once for the correction and any warranted focused follow-up; omit follow-up when direct evidence can settle the changed boundary. Then wait; do not correct or dispatch a follow-up from the request itself. Verify authorized corrections and run follow-up only when the changed boundary still needs independent judgment and that dispatch is authorized. Do not change tests, Specs, policies, or accepted behavior merely to satisfy a reviewer or obtain Pass.
 
 ## Limit The Review Cycle
 
@@ -106,21 +110,19 @@ For one independently reviewed work state and boundary:
 
 1. Review 1 is the normal broad review.
 2. Review 2, when needed and authorized, focuses on accepted corrections, affected interactions, and remaining risk.
-3. Review 3 is exceptional, authorized separately, and final for that cycle.
+3. Review 3 is exceptional, separately authorized, and final.
 
-The budget is a cap, not dispatch authority. Do not request Review 4. At the cap, adjudicate and return control to Workflow; the work may proceed, remain blocked, re-enter another owner, defer, or stop.
+The budget is a cap, not dispatch authority. Do not request Review 4; return control to Workflow at the cap.
 
-After Review 2 is adjudicated Blocking, stop before proposing another correction or Review 3. Classify its relationship to the prior correction:
+After Review 2 is adjudicated Blocking, stop before another correction or Review 3:
 
-- If the blocker repeats, extends, invalidates, or exposes another consequence of the prior correction, or its cause remains unsupported, read [Diagnose Failure](../diagnose-failure/SKILL.md) and diagnose the shared cause before another patch.
-- If it is an independent clear local defect with a supported cause, return directly to its owning activity and state why diagnosis is unnecessary.
+- If the blocker repeats, extends, invalidates, or exposes another consequence of the prior correction, or its cause remains unsupported, read [Diagnose Failure](../diagnose-failure/SKILL.md) and diagnose the shared cause first.
+- If it is an independent clear local defect with a supported cause, return to its owner and state why diagnosis is unnecessary.
 
-A reviewer judgment alone does not trigger diagnosis; active-agent adjudication and evidence do. Review 3 is final judgment after the cause and correction boundary are understood, not a third attempt to discover the cause through patches. Workflow may later establish a new cycle only for a materially new reviewed state and boundary; local fixes, a different reviewer, or renamed scope do not reset it.
+Diagnosis follows adjudicated evidence, not reviewer judgment alone. Review 3 is final judgment after the cause and correction boundary are understood, not another attempt to discover them through patches. Workflow may establish a new cycle only for a materially new reviewed state and boundary; local fixes, a different reviewer, or renamed scope do not reset it.
 
 ## Report
 
-For self-review, report no formal review result. Correct clear local issues and surface only unresolved material issues that change the route.
-
-For independent review, use the structured output in [the reviewer prompt](references/reviewer-prompt.md). The receiving agent reports the reviewer and adjudicated judgments, each material item's Accepted, Rejected, or Open outcome and reason, remaining open items, and authorized or proposed next route.
+For self-review, report no formal result. Correct clear local issues and surface only unresolved material issues that change the route.
 
-Omit empty groups. Support material judgments and adjudication with source or evidence rather than confidence.
+For independent review, use the [Independent Work Reviewer Contract](references/independent-work-reviewer-contract.md) and stop with its report. The receiving agent then reports the reviewer and adjudicated judgments, each material item's outcome and reason, and either the problem checkpoint or remediation-ready route defined above. Omit empty groups and support the result with source or evidence rather than confidence.

package/skills/review-work/references/{reviewer-prompt.md → independent-work-reviewer-contract.md}

@@ -1,6 +1,6 @@
 # Independent Work Reviewer Contract
 
-Use this when preparing an independent review of implementation or integrated work.
+Read this before preparing or performing a separately selected independent review of implementation or integrated work.
 
 The reviewer did not produce the work. Give them the work product, source truth, and evidence needed to judge it directly. Do not provide only the author's summary, reasoning, or claimed result.
 

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

@@ -1,6 +1,6 @@
 # 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.
+Read this before reviewing work that changes trust boundaries, authentication, authorization, permissions, untrusted input, secrets, sensitive data, security-relevant dependencies or external integrations, code-execution boundaries, 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.
 

package/skills/setup-freeflow/SKILL.md

@@ -13,7 +13,7 @@ Create or repair the smallest valid layered setup. Keep repository activation, p
 
 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.
 
-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. Read [Output Router setup](references/output-router-setup.md) only when the user explicitly requests it during setup or repair; later tuning belongs to [Output Router](../output-router/SKILL.md).
+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.
 
 ## Establish Mutation Authority
 
@@ -64,17 +64,12 @@ Before writing local config in a Git checkout, verify it is untracked and ignore
 
 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.
 
-## Keep Optional Setup Explicit
-
-Do not ask an automatic capabilities question. Configure Output Router only when explicitly requested, using [Output Router setup](references/output-router-setup.md). Preserve valid existing capability config during idempotent setup.
-
 ## Establish Same-Turn Context
 
 After successful verification, apply newly effective context directly for the remainder of the setup turn:
 
-- 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;
-- read an explicitly configured capability skill only when runtime state says it is effective.
+- read the [Interaction Contract](../../runtime/prompts/interaction-contract.md) when it is effective;
+- read [Workflow](../workflow/SKILL.md) and [Mode Contract](../mode-contract/SKILL.md) when Skills are effective.
 
 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.
 
@@ -86,13 +81,14 @@ Verify:
 - 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;
-- optional capability config changed only when requested;
 - no repo-owned host instructions or unrelated files changed.
 
+After verification supports a setup result, silently self-review the final observed or changed state before accepting, reusing, or reporting it. Correct clear local issues within the existing setup authority and re-verify the affected boundary; stop on ambiguity, route change, or an out-of-envelope correction.
+
 Report separately:
 
 1. shared repository activation;
 2. personal override state and effective sources;
-3. effective capability state;
+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

@@ -19,8 +19,6 @@ Supported defaults are `conversation`, `workflow`, and `strict-workflow`. Missin
 - `skills.enabled: true`
 - `defaultMode: workflow`
 
-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.
-
 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.
 
 Missing or invalid repository config means repository activation is absent. A valid config with effective `enabled: false` remains configured but inactive.
@@ -44,8 +42,6 @@ It may override these core values:
 
 Every field is optional. Omission inherits the repository value, then the built-in default. Local core precedence is property-level, not whole-file replacement.
 
-The local file may also contain documented local-only `processing` config. It must not contain repository-owned Output Router config.
-
 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.
 
 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.
@@ -58,7 +54,7 @@ Resolve core values in this order:
 host session override -> personal override -> repository value -> built-in default
 ```
 
-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.
+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.
 
 Effective Freeflow requires:
 
@@ -68,8 +64,6 @@ Effective Freeflow requires:
 
 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.
 
-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:
@@ -86,10 +80,11 @@ Configuration does not prove runtime delivery.
 
 When effective, host adapters may deliver:
 
-- `runtime/interaction-contract.md` when the Interaction Contract switch is enabled;
+- `runtime/prompts/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.
+- compact active or dormant mode state.
+
+Pi may additionally expose explicitly enabled Pi capability skills and tools through its extension. Codex and Claude `SessionStart` hooks compose static fragments from `runtime/prompts/` 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.
 

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

@@ -37,7 +37,7 @@ Session settings can temporarily inherit, enable, or disable Freeflow, Interacti
 
 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.
 
-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.
+When effective, Pi's `before_agent_start` path preserves the existing system prompt and composes the gated static fragments from `runtime/prompts/`. Runtime State is appended to every provider request; Workflow, Action Selection, and capability bodies remain discoverable rather than hidden persistent messages. Interaction Contract may be independent from Skills; Cognitive Routing, Context Virtualization, and Conversation History require Skills.
 
 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.
 
@@ -45,9 +45,9 @@ Confirm automatic delivery through current extension status or runtime evidence
 
 ## Codex And Claude
 
-The packaged lifecycle hook reads the same repository and local layers at supported session start, resume, clear, and compact boundaries.
+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 layered value sources and active or dormant mode state. Optional capabilities remain independently gated by valid repository config and top-level Freeflow.
+When top-level Freeflow is effective, the hook loads the applicable static fragments from `runtime/prompts/` and reports configured, session, resolved, and effective mode state without treating a configured default as the current session mode. It does not inject a full Workflow bootstrap.
 
 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.
 
@@ -61,10 +61,6 @@ Installed and trusted registration can establish availability for the next lifec
 
 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

package/skills/simplify-code/SKILL.md

@@ -20,7 +20,7 @@ Before editing:
 
 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.
+Before changing code, read [Code Practices](../execute-work/references/code-practices.md). Before choosing a transformation or deciding whether deletion really reduces complexity, read [Simplification Patterns](references/simplification-patterns.md).
 
 ## Classify The Opportunity
 

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

@@ -1,6 +1,6 @@
 # Simplification Patterns
 
-Use these as candidate transformations, not automatic rules. Preserve behavior and project conventions.
+Read this before choosing a simplification transformation or deciding whether deletion really reduces complexity. Use these patterns as candidates, not automatic rules. Preserve behavior and project conventions.
 
 ## Control Flow
 

package/skills/tdd/SKILL.md

@@ -5,12 +5,24 @@ description: Use when implementing or changing behavior test-first, fixing a bug
 
 # Test-Driven Development
 
+Selecting TDD creates no authority. Enter RED only when accepted behavior is settled and the current authority envelope covers the test and production effects.
+
 Use one observed failing behavior check to guide the smallest complete implementation for one accepted behavior.
 
-TDD is an execution method inside [Execute Work](../execute-work/SKILL.md). One vertical RED/GREEN/REFACTOR loop is a bounded action, not automatically a Track Work slice. Several accepted behavior loops may remain inside one coherent current slice.
+TDD is an execution method inside [Execute Work](../execute-work/SKILL.md). One vertical RED/GREEN/REFACTOR loop is a bounded action, not automatically a new Slice. Several accepted behavior loops may remain inside one coherent Slice; when durable task memory exists, [Track Work](../track-work/SKILL.md) preserves it as the Current Slice.
 
 TDD does not define intended behavior. The accepted request, source truth, and user decisions establish what should happen.
 
+## Use Or Exit Deliberately
+
+Use TDD when test-first execution is selected for an accepted behavior change, bug correction with a supported cause, consequential logic, or refactor whose behavior needs protection.
+
+Do not force test-first work onto documentation, static content, mechanical formatting, generated output, or a disposable learning prototype whose result is not selected production behavior.
+
+Stop before RED when expected behavior, failure semantics, or a public contract is unsettled. Return the missing direction to [Workflow](../workflow/SKILL.md) rather than encoding a guess as a test.
+
+When TDD applies, before designing or materially changing its behavior check, read [Test Design](references/test-design.md) to choose the test level, seam, oracle, doubles, rejected-state coverage, composed failures, time or concurrency boundary, and characterization strategy.
+
 ## Follow The Behavior Loop
 
 ```text
@@ -26,56 +38,26 @@ TDD does not define intended behavior. The accepted request, source truth, and u
 -> [Verify original path and affected boundary]
 -> [Route]
    -> another accepted behavior in this slice -> next TDD loop
-   -> coherent extension -> approve and record when needed
+   -> coherent extension -> Workflow -> when covered, record if needed -> next TDD loop
    -> unclear cause or structural pressure -> Workflow
    -> supported bounded action -> return to Execute Work
 ```
 
 Do not write all tests first and all implementation later. Finish, verify, and route one accepted behavior before starting another.
 
-## Use Or Exit Deliberately
-
-Use TDD for accepted behavior changes, bug fixes with a supported cause, consequential logic, and refactors whose behavior needs protection.
-
-Do not force test-first work onto documentation, static content, mechanical formatting, generated output, or a disposable learning prototype whose result is not selected production behavior.
-
-Stop before RED when expected behavior, failure semantics, or a public contract is unsettled. Return the missing direction to [Workflow](../workflow/SKILL.md) rather than encoding a guess as a test.
-
-## Choose The Seam And Oracle
-
-Test observable behavior through the highest stable interface that exercises the real requirement.
-
-A useful seam:
-
-- is used by callers rather than created only for tests;
-- survives internal refactoring;
-- reaches the real behavior or failure path;
-- keeps setup proportionate;
-- can disagree with the implementation.
-
-Derive expected results from source truth, a worked example, protocol contract, or independent calculation—not the implementation algorithm.
-
-Read [Test Design](references/test-design.md) when the test level, oracle, double, rejected state, composed failure, time or concurrency boundary, or legacy seam is unclear.
-
-If testing requires owned internals, duplicated caller choreography, or production hooks used only by tests, return the evidence to Workflow. Use [Design for Depth](../design-for-depth/SKILL.md) only when it establishes design-bearing interface or ownership pressure; do not redesign merely because one test is inconvenient.
-
 ## Enforce The Test-First Evidence
 
 - Observe RED failing for the intended missing behavior before changing production code.
 - If RED passes immediately, inspect the test, observing boundary, and existing behavior; do not proceed to GREEN automatically.
 - If RED fails because of syntax, setup, environment, or unrelated behavior, correct the harness or diagnose before implementation.
-- Implement the smallest complete GREEN behavior. Read [Code Practices](../execute-work/references/code-practices.md) while changing code.
+- Before changing production code for GREEN, read [Code Practices](../execute-work/references/code-practices.md). Then implement the smallest complete behavior.
 - Refactor only when it improves the result while the focused behavior check remains green.
 - Re-run the original path and smallest affected boundary before returning the supported action and evidence to Execute Work.
 - Do not claim TDD when the check was written after implementation or RED was never observed for the intended reason.
 
 ## Keep Tests About Accepted Behavior
 
-Prefer observable outcomes over internal call sequences, real implementations before doubles, independent expected values, descriptive domain names, and one behavior concept per test.
-
-Use fakes, stubs, mocks, or spies only at a boundary where replacement is necessary and the double preserves the fields, effects, invariants, and failure behavior the test needs.
-
-Do not copy the implementation into the expected value, add production methods used only by tests, change a valid test merely to make implementation pass, or treat coverage and test count as proof.
+Use the behavior check as the RED/GREEN contract for one accepted behavior. Do not change a valid test, copy the production implementation into its expected value, or add production hooks used only by tests merely to reach GREEN.
 
 Add an edge-case check only when accepted behavior, observed failure, material safety, or a settled failure contract requires it. If behavior is undefined, return it to Workflow. When related cases keep adding states, flags, setup, or patches, stop the behavior-loop stream and diagnose the shared contract, cause, ownership, or interface.
 
@@ -87,10 +69,8 @@ If no reliable diagnostic loop or supported cause exists, use [Diagnose Failure]
 
 ## Stop When Tests Start Designing The System
 
-Return evidence to Workflow when test setup grows faster than behavior coverage, each case requires another public state or fallback, tests protect machinery introduced by earlier patches, the next check requires an unplanned subsystem, or making it pass expands accepted scope.
-
-A green local loop does not prove the global design is right. Diagnose repeated or unexplained failure before redesigning.
+When Test Design's pressure signals appear, the next check requires an unplanned subsystem, or making it pass expands accepted scope, stop and return the evidence to Workflow. Use [Design for Depth](../design-for-depth/SKILL.md) only when that evidence establishes design-bearing interface or ownership pressure; diagnose repeated or unexplained failure before redesigning.
 
 ## Report
 
-Report the accepted behavior and seam, observed RED result, GREEN implementation, refactor if any, original-path and broader verification, current slice effect, and remaining unverified behavior. Return route-changing evidence rather than silently beginning another behavior or slice.
+Report the accepted behavior and seam, observed RED result, GREEN implementation, refactor if any, original-path and broader verification, Slice effect when relevant, and remaining unverified behavior. Return route-changing evidence rather than silently beginning another behavior or slice.

package/skills/tdd/references/test-design.md

@@ -1,8 +1,8 @@
 # Test Design
 
-Read this when the right test level is unclear, a dependency needs a double, legacy behavior lacks a seam, or test setup starts driving production design.
+Read this before designing or materially changing a TDD behavior check. Use it to choose the test level, seam, oracle, failure coverage, doubles, time or concurrency boundary, and characterization strategy.
 
-The goal is confidence in accepted behavior, not maximal isolation or a fixed unit/integration/end-to-end ratio. One TDD behavior loop is a bounded action and may remain inside a larger coherent Track Work slice.
+The goal is confidence in accepted behavior, not maximal isolation or a fixed unit/integration/end-to-end ratio.
 
 ## Choose The Confidence Boundary