@hassangameryt/freeflow 0.5.0 → 0.6.0

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

@@ -68,7 +68,7 @@ If local config is invalid, report that it blocks effective runtime. Repair or r
 
 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 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.
@@ -83,6 +83,8 @@ Verify:
 - Skills-disabled mode remains resolved but dormant;
 - 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;

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

@@ -80,11 +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 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.
+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.
 
@@ -47,7 +47,7 @@ Confirm automatic delivery through current extension status or runtime evidence
 
 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.
+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.
 

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