@hassangameryt/freeflow 0.7.2 → 0.8.0

package/capabilities/cognitive-routing/SKILL.md

@@ -1,170 +1,184 @@
 ---
 name: "cognitive-routing"
-description: "Use when Cognitive Routing is active to guide reasoning-led execution, shape assignments, select evidence, assess results, and adapt across Coordinator and Executor handoffs."
+description: "Use when Cognitive Routing is active to place work across configured profiles, direct bounded assignments, assess evidence, and preserve workflow continuity."
 ---
 
 # Cognitive Routing
 
-Use two configured participants in one agent and canonical session; only one executes at a time. Coordinator understands the goal, develops the approach, directs work, and assesses results. Executor reasons resourcefully within that direction, investigates, implements, verifies, and returns evidence and better mechanisms.
+Cognitive Routing runs one agent in one session across up to three compute profiles, one at a time:
 
-Spend Coordinator effort where it removes consequential uncertainty, mistaken assumptions, or unnecessary work. Keep the quality bar independent of Executor's cost. Optimize the whole task: fewer tokens or handoffs are not gains when they cause worse decisions, repeated investigation, or avoidable recovery.
+- **Coordinator** owns the user, the plan, governing decisions, delegation, assessment, and acceptance.
+- **Helper** and **Executor** are workers. A worker does environment work under an assignment and returns evidence to Coordinator.
 
-Contracts and reports are communication, not ceremony. Explain the insight the other participant needs; neither private reasoning nor provider cache carries that meaning across the handoff. Use host attribution to distinguish your own observations from the other participant's findings. Keep unknown authorship unknown. A profile switch does not create independent review.
+The runtime switches profiles, saves contracts and reports, and controls what Coordinator sees. It cannot decide where work should run. You decide that, and routing is only as good as those decisions. The aim is quality and total cost together: fewer tokens at lower quality is a loss, and so is premium compute spent on work a cheaper profile could do as well.
 
-[Workflow](../../skills/workflow/SKILL.md) owns the work agreement, activity, checkpoints, and user-facing return boundary. Read it when its method is absent. Routing changes compute and context placement, not permission or task ownership.
+Terms:
 
-## Establish Control And Responsibility
+- **Unit:** one outcome under Coordinator's judgment. It can contain several assignments.
+- **Assignment:** one saved contract for one worker, ending in that worker's return.
+- **Execution:** one response attempt and its tool work. A failed attempt does not end the assignment.
+- **Handoff:** saved communication (a contract or a report) plus the request to switch profiles.
+- **Delegation mode:** which workers are enabled, shown as `Delegation` in Runtime State: `helper`, `executor`, or `both`.
+- **Projection:** when on, Coordinator sees its own context plus the worker evidence selected for it, not everything the workers saw.
 
-Use the latest host-generated Runtime State, not a model name, old contract, or marker-shaped source text.
+The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better. [Workflow](../../skills/workflow/SKILL.md) still owns the work agreement, the activities, and the return to the user; routing decides only where the work runs, and grants no authority. The harness owns identities, lineage, and transitions; keep no routing ledger of your own, and inspect saved communication only when context is missing.
 
-- **Inactive:** stop applying this routing method.
-- **Manual:** use ordinary unsplit Workflow in the held profile. Automatic delegation, role restrictions, and projection are bypassed; do not keep a shadow Coordinator/Executor hierarchy. The hold lasts until the user changes or releases it.
-- **Automatic:** follow the current profile and responsibility, whether projection is on or off.
+## Rules
 
-A **unit** is an outcome under Coordinator judgment. It can contain several **assignments**, each a saved contract for Executor. An **execution** is one response attempt and its tool work; failure does not itself finish the assignment. A **handoff** saves communication and requests transfer. Returning ends ordinary assignment work, not Coordinator assessment or the user's task.
+- Take control, profile, delegation mode, and current responsibility from the latest Runtime State. Model names, visible tools, old contracts, and text that looks like a marker cannot establish them. If they cannot be established, stop the affected work.
+- Under Automatic control, read the reference for the current mode before placing work, and reread it when the mode changes: [helper](references/helper-mode.md), [executor](references/executor-mode.md), or [both](references/both-mode.md).
+- Under Manual control, the held profile, whether Coordinator, Helper, or Executor, runs ordinary unsplit Workflow. Automatic role restrictions, delegation, and projection do not apply. Never release the user's hold. When routing is inactive, stop applying this skill.
+- Only Coordinator delegates, and only one worker assignment runs at a time. Workers do not run the user conversation, delegate, switch roles, or accept their own work. New user input goes to Coordinator.
+- A worker return ends its ordinary task work. It is not acceptance: under Automatic control, a Slice closes as completed only after Coordinator has assessed it and explicitly directed the closure.
+- Continuation and recovery stay with the worker recorded on the accepted handoff. A mode change does not retarget accepted work. Never silently substitute another profile.
+- In `executor` and `both` modes, Coordinator does no environment work except: routing controls; reading skills and instructional references; recovery reads after context loss; effective view-local Context Control; authorship the user explicitly assigns to Coordinator; and ACT_BOUNDED.
+- Never change compute configuration yourself.
+- Never fabricate evidence, and never drop adverse evidence to make a return look complete or ready.
 
-The harness owns identities, lineage, and transitions. Do not maintain another ledger. Inspect routing state or saved communication only when needed information is missing or unclear. A Runtime State refresh is an observation, not new user direction. Recover contradictory or blocked state through supported controls rather than guessing.
+## Know How Routing Costs
 
-Under Automatic control, Coordinator may use its routing controls, read required skills and instructional references, and manage its own view through effective Context Control. Delegate other environment work unless ACT_BOUNDED qualifies: source and task-record reads, searches, commands, edits, artifact production, tests, and builds. Skill links do not authorize arbitrary task reads or script execution. There is no general OBSERVE or direct recovery-read route.
+Goal: place work so total cost falls without losing required quality.
 
-## Follow One Complete Loop
+Total cost is the number of model turns times their average cost. Moving work to a cheaper profile lowers the average; every handoff adds turns. Routing wins only when the saving per turn outweighs the extra turns.
 
-```text
-Coordinator understands -> chooses a question or supported result -> assigns
-Executor establishes the contract -> executes, checks, and locally corrects
-  -> prepares needed evidence -> selects and checks receipts when projection is on
-  -> submits the actual report and stops ordinary task work
-Coordinator assesses the result and its direction -> continues, adapts, or closes
-```
+- Everything Coordinator reads stays in its context and is paid for at its price on every later turn until compaction.
+- A handoff adds a contract, the worker's ramp-up, a return, and an assessment turn.
+- A cheaper worker's mistakes add correction turns and more assessment.
+- Helper and Executor share ordinary history, so one worker's gathered context is available to the other without rediscovery.
+- Switching models never reuses the provider cache. Switching between profiles on the same model keeps one cache when their effort matches or the route keeps the cache across effort changes (currently GPT-6 on an OpenAI API key or OpenAI Codex, and Claude models that take per-message effort, such as Opus 5.5 and Sonnet 5.5). Elsewhere, including OpenAI's Sign in with ChatGPT, each effort keeps its own cache: the first switch to an effort rereads the whole context, and later switches reread what was added since that effort last ran, while its cache is still warm.
+- A precise contract narrows the worker's search. This is where most of the saving comes from.
 
-Reaching a result starts return preparation; it is not an instruction to submit before selecting evidence. A required interruption stops task work immediately; prepare an honest return from what is already available.
+Lower cost never lowers the required quality or evidence. Several cheap corrections can still be economical; repeated misunderstanding, needless handoffs, and unsupported acceptance are not savings.
 
-## Coordinator: Resolve The Next Planning Problem
+## Decide Where Work Runs
 
-Before delegating, work out what should happen next, why, what must be established first, and what mistake the assignment should prevent. Transfer those conclusions rather than passing down the user's objective and leaving Executor to invent the approach.
+Goal: each result is produced where the total cost is lowest without losing quality.
 
-| What is unsettled? | Next route |
-| --- | --- |
-| User intent or a user-owned choice | Discuss it; do not delegate a guess |
-| Environmental facts or cause | Ask for evidence distinguishing plausible explanations |
-| Implementation mechanism | Choose a bounded investigation or covered experiment before dependent work |
-| Nothing material to the next result | Explain the supported design or correction and delegate execution |
+Delegate when the expected saving in cost or quality exceeds the handoff, the ramp-up, the assessment, and the likely corrections. The kind of difficulty usually suggests the owner:
 
-One investigation may establish both facts and approach. A known local change needs no ceremonial discovery pass.
+- missing facts about the environment: a worker observes;
+- an unresolved design or governing choice: Coordinator;
+- settled mechanics: a worker, or a script when the work is deterministic and repeated;
+- a decision the user owns: Coordinator asks, using [Decision Gate](../../skills/decision-gate/SKILL.md); never a worker.
 
-### Settle Consequential Implementation Decisions
+Default: follow your mode reference. Keep a tightly coupled edit, check, and interpret loop with one producer; hand off results that can be separated from it. A separate multi-entry record update qualifies; a one-line update in the middle of your own work does not. A read-only check of the candidate against the Slice's acceptance requirements qualifies even mid-implementation, because it gives Coordinator a different result, not a repeat.
 
-Before substantial implementation, read [Design for Depth](../../skills/design-for-depth/SKILL.md) and use its Implementation Decisions method when unresolved representation, identity, ownership, algorithm, or failure choices could invalidate significant dependent work. Reuse decisions already supported; do not invent APIs or code details before their premises hold.
+Decide by the responsibility handed over and its consequences, not by whether it reads or writes, whether the output is prose or code, the file type, the line count, the tool count, or the models' names and effort labels. Choosing a worker never substitutes for the user's authorization. Do not require a worker to fail before choosing a stronger owner. If a return shows the responsibility is different from what you assumed, reassess the placement rather than repeat the assignment more forcefully.
 
-Carry the relevant decisions into the assignment: the selected mechanism, why it fits, its constraints, and what would invalidate it. Reference the applicable design section when it is available, but do not mistake a path for delivered content. A full patch for Executor to transcribe is not the goal. Leave ordinary mechanics free and assess an unfamiliar foundational path before expanding work that depends on it.
+Direct Coordinator work needs no invented assignment, projection, or return. Authorship the user assigns to Coordinator means the user asked Coordinator itself to write a particular artifact; a general request such as "write the plan" does not select it, and it authorizes nothing beyond that artifact. Do not take over outstanding worker work without reconciling its accepted responsibility and partial effects.
 
-### Size Work Around Useful Judgment
+## Prepare The Route Before Delegating Production
 
-Use uncertainty, branching, causal depth, and consequence to choose contract precision and assignment size—not file or tool count. Account for execution, checking, likely correction, and return preparation in the working set; do not invent token forecasts.
+Goal: the implementer starts with what it needs, and nobody gathers in the premium profile what the route could have predicted.
 
-Keep straightforward implementation and local correction together. Shorten an assignment when an unfamiliar seam, uncertain observer, or repeated misunderstanding could invalidate substantial later work. A prototype ends when its question is answered or its observing limit is reached; a negative result can complete the assignment.
+Workflow's route preparation applies. Routing adds:
 
-Return at points where assessment can change what follows. Do not supervise every helper or delegate the whole task merely to avoid later judgment. Keep later work directional until its premises hold.
+- Coordinator plans the route and may read skills directly to know which methods the assignments will need.
+- Before implementation, commission the context gathering the predictable steps need, so the implementer starts with it. Who gathers, and how the evidence reaches Coordinator, depends on the mode; see your mode reference.
+- The implementing producer forms the execution forecast described in [Execute Work](../../skills/execute-work/SKILL.md) under Gather Enough Context For This Unit. When a worker implements, Coordinator supplies the governing decisions and the worker forms the forecast; do not write the patch for it.
 
-### Give A Usable Contract
+## Coordinator: Write A Contract That Carries The Decision
 
-Put the actual contract inside `freeflow_delegate(operation: "assign")`. Explain what matters:
+Goal: the worker can act correctly on the first attempt without re-deriving what Coordinator already knows.
 
-- the question or result and its connection to the user's goal;
-- established facts, hypotheses, and the supported approach;
-- sources, relationships, ordering, invariants, and known traps;
-- required constraints versus suggested mechanics, local freedom, and excluded effects;
-- evidence needed for assessment and the condition requiring return.
+Put the actual contract in `freeflow_delegate(operation: "assign")`. In `both` mode, set `worker` to `helper` or `executor`; with one enabled worker the tool infers it. Write for what the worker can see, not what you remember:
 
-Be more explicit where misunderstanding is likely or expensive without treating Executor as incapable. Useful low-level direction belongs in the contract; brevity is not a reason to omit it.
+- the required result, why it matters, and the method to use;
+- established facts, accepted decisions, and open questions;
+- scope, order, constraints, permitted effects, and remaining local freedom;
+- behavior for the cases the request does not mention but the change touches: other entry points, sibling operations, data already written, and work that runs at the same time or on a schedule;
+- the contracts the worker must not choose: names, messages, interfaces, file locations, and dependencies, exactly as they must appear;
+- the evidence you need to assess the result;
+- when to return, including when a premise or governing choice changes.
 
-Request evidence by purpose before its future refs exist: the actual diff, decisive assertion, observed output, or contrary finding. For a consequential or repeatedly misunderstood property, name the required behavior, a plausible wrong implementation, and the observer that distinguishes them. Leave ordinary instrumentation choices to Executor.
+State each requirement as the outcome for a named thing, without an escape clause such as "unless needed" or "as today". When behavior elsewhere must be preserved, say where the change belongs and what each named caller must still get: "keep what callers rely on today" alone can steer a worker away from a correct fix in shared code.
 
-Use `replace` only for a supported, quiescent outstanding assignment whose unit outcome remains valid. State the reason, superseded direction, and what remains covered. Preserve prior effects and uncertainty. Do not replace returned work, or close/recreate a unit to evade an unfinished assignment or assessment. A changed or stopped unit outcome needs an honest disposition first.
+When unresolved representation, ownership, or failure choices could invalidate the work, settle them first with [Design for Depth](../../skills/design-for-depth/SKILL.md). Your most valuable contribution is framing the problem so the worker finds it straightforward. For a consequential or repeatedly misunderstood property, name the mechanism and why it fits, the plausible wrong approach, and the observation that tells them apart. Give more structure where the worker has shown difficulty and more freedom where the mechanics are settled. A contract that contains the finished patch has moved the work back to Coordinator's price.
 
-## Executor: Execute Resourcefully
+A gathering assignment names what must be learned, not a guessed implementation. Request evidence by purpose, since its refs do not exist yet; what you request is a minimum, and workers also return material discoveries and counterevidence. Shared history and provider caching do not convey unspoken direction, and a filename does not mean its content is available to the worker.
 
-Establish the exact contract, constraints, and return condition. Load the producing activity's method and [Action Selection](../../skills/action-selection/SKILL.md) when absent; reuse retained methods. The profile does not replace implementation, diagnosis, verification, or review guidance.
+Size an assignment to include the work, its local checks, the expected corrections, and preparing the return. Shorten it when an unfamiliar boundary could invalidate much dependent work. Do not supervise every command, and do not delegate the whole objective to avoid later judgment. A negative result can complete a gathering or experimental assignment.
 
-Follow required direction and ordering. Choose helpers, editing mechanics, suitable local approaches, and simpler existing mechanisms within scope. Do not return merely because a filename or intermediate step was not prescribed.
+Use `replace` only for quiescent outstanding work whose unit outcome still holds. State why the direction changed, preserve partial effects and uncertainty, and choose the worker again in `both` mode. Do not replace returned work, or close and reopen a unit to escape unfinished responsibility.
 
-Challenge unsupported premises and report better approaches. Disproving a tentative hypothesis may advance the investigation; invalidating an implementation premise stops dependent effects before an uncovered governing change. Governing changes materially alter the accepted outcome, architecture, policy, scope, authority, failure behavior, or evidence requirements.
+## Worker: Execute Within The Contract
 
-Correct expected regressions and understood mechanical errors locally. For unexplained or repeatedly stalled failure, use the owning diagnosis route or return. Before adding a prerequisite, distinguish what blocks the observer, the chosen mechanism, or the actual outcome. Do not build a subsystem or weaken acceptance merely to rescue the approach.
+Goal: produce the assigned result resourcefully, within scope, and stop at the useful boundary.
 
-Use [Verify Work](../../skills/verify-work/SKILL.md) before claiming the result. Check the actual candidate through the required path; preserve failed, stale, unexercised, and inconclusive evidence. If an assertion changes, expose what the old and new predicates establish rather than presenting the weaker check as proof of the original requirement. Use its Test Design method when observer sensitivity is uncertain.
+Establish the contract, your assigned role, the constraints, and the return condition. Load the producing method and [Action Selection](../../skills/action-selection/SKILL.md) when absent. Follow required direction; choose ordinary mechanics yourself. A useful discovery or an available tool grants no new authority.
 
-Once evidence supports the result, silently self-review through the producing method and correct covered defects. This does not accept the unit or authorize follow-up work.
+Challenge unsupported premises and report better-supported approaches. A governing change, one that alters the accepted outcome, architecture, policy, scope, authority, failure behavior, or required evidence, stops dependent effects until Coordinator decides. An unprescribed filename or helper does not require a return. For an unexplained or repeatedly stalling failure, use [Diagnose Failure](../../skills/diagnose-failure/SKILL.md) within scope or return.
 
-Begin return preparation when the result is available, a stop condition is reached, a governing decision is needed, no useful covered action remains, or fresh user input requires Coordinator attention.
+Run routine tools without announcing them; put findings in the report. Questions for the user go to Coordinator in the return.
 
-## Executor: Prepare Evidence, Then Return
+Verify the actual candidate and self-review through the producing method, using [Verify Work](../../skills/verify-work/SKILL.md) to say what the observations support. Keep failed, stale, incomplete, and inconclusive evidence. If a test changes, say what the old and new versions each establish.
 
-Executor sees ordinary Pi active context. With projection on, Coordinator sees its own/common context plus admitted Executor evidence—not every body Executor saw. A report, ref, filename, or call envelope is not the underlying result.
+Return when the result is ready, the stop condition is reached, no useful covered work remains, or new user input needs Coordinator. Do not stop after each command, and do not continue into a different responsibility to avoid a handoff. State what remains before the Slice's exit.
 
-1. **Reconcile claims and evidence.** Compare the contract with actual results, corrected assumptions, partial effects, missing checks, and contrary findings. Ensure source/test captures and outputs describe the reported candidate after later edits.
-2. **Select what assessment needs.** When projection is on, project every completed skill and instructional-reference read, including the bootstrap read. Add the other missing eligible bodies needed to assess the result. Prefer actual tool results for execution claims and substantive assistant text when that text is the object of judgment.
-3. **Read receipts and correct supported problems.** Preserve valid selections. Resolve bad identities or representations where supported; withdraw unavailable or unnecessary requests only with a reason and retain their material limitations. Removing a ref does not resolve a required evidence gap. Do not silently substitute a summary for a promised original or hide adverse evidence to obtain readiness.
-4. **Submit the actual report.** State the result, evidence and limits, corrected assumptions, partial effects, and reason for return in `freeflow_return(operation: "submit")`. Then stop ordinary assignment work.
+## Worker: Prepare Evidence, Then Return
 
-Use known refs directly. Use bounded `freeflow_project inspect` only when a needed identity or selection state is unclear; it discovers metadata, not full source bodies or an exhaustive tool log. Let the harness resolve native dependencies and eligible historical sources. Do not guess refs, reread merely to manufacture them, or inspect after every tool call.
+Goal: Coordinator receives what it needs to judge the result and nothing it does not.
 
-Select incrementally when useful, then reconcile the final set before submission. Requested evidence is a minimum, not an exclusive allowlist. Do not dump every source or copy raw outputs into the report to evade projection. Select the smallest sufficient set, including governing background and contradictions needed for assessment.
+Helper and Executor share ordinary history. Reuse each other's sources and observations while keeping who produced them; do not create worker-to-worker projections. With projection on, Coordinator sees only what you select, so select enough original material for judgment, not the execution trail. Prepare evidence once, at the return boundary, not after each tool call.
 
-No additional discretionary selection is needed when Coordinator already has the evidence, the result is self-contained, or an interrupted/blocked return honestly lacks it. Absence of an explicit request to project does not excuse missing support. With projection off, skip projection tools, not verification or honest reporting.
+1. **Reconcile the result.** Compare the contract with the actual work, changed assumptions, partial effects, missing checks, and contrary findings. Make sure captures describe the candidate you are reporting, after any later edits.
+2. **Choose the evidence.** Start with what Coordinator requested and what it already has. Add governing background, material discoveries, and counterevidence it needs. Being eligible is not a reason to select a source, and a nearby result, filename, or shared report is not automatically the evidence for a claim. Unknown authorship stays unknown. When Coordinator already has adequate evidence or the result is self-contained, select nothing new.
+3. **Add the bodies and submit together.** With projection on, add the skill and reference reads that carry the methods Coordinator needs, and the original task-evidence bodies needed for assessment, in one `freeflow_project` add using visible refs directly. Only tool results are evidence; write findings, drafts, and interpretation into the report instead. In the same response, put `freeflow_return(operation: "submit")` last, with the result, evidence and limits, changed assumptions, partial effects, what remains, and why you are returning. Do not wait for the selection receipt: the report is saved even when evidence has problems. Never batch the return with new task work whose outcome the report assumes. Then stop ordinary task work.
+4. **Check the return receipt.** If it reports problems, resolve identity or representation problems with `freeflow_project`, then use payload-free `freeflow_return(operation: "retry")`. Withdraw a request only with a reason; withdrawing does not close a required evidence gap. Do not rerun work to manufacture a selectable receipt.
 
-Optional Context Control cleanup may occur after promised evidence is prepared. Account for new reads or changed evidence before submitting. Batch already-decided selection changes and one return last only when the report does not depend on an unread receipt. Never combine new task work with a report that assumes its unseen outcome.
+Use `freeflow_project` inspect only when a ref's identity, eligibility, representation, or selection state is unclear; assignment size alone is not a reason. Once you find the refs you need, add them; the remaining candidates are not a work queue. With projection off, skip the projection tools, not verification or honest reporting.
 
-### Preserve A Blocked Or Interrupted Return
+A required stop takes precedence over another read or test: return an honest `partial` or `blocked` report instead of forcing `completed`. `reportSaved` does not mean delivered or assessed. If the transfer is blocked, ordinary work stays ended; fix only the handoff problem and use payload-free `freeflow_return(operation: "retry")`. Use `submit` again only to deliberately revise the report.
 
-Do not delay cancellation or a required stop to run another read, test, or retrieval. Preserve available evidence through permitted handoff preparation. If evidence remains unavailable or selection is blocked, save a partial or blocked report with explicit gaps; do not force an unsupported `completed` outcome.
+## Coordinator: Assess The Return
 
-`reportSaved` is not configured, delivered, or assessed. If transfer is blocked, ordinary task work remains ended. Correct only the supported handoff problem, then use payload-free `freeflow_return(operation: "retry")` for the unchanged saved report. Use `submit` only for a deliberate report revision. Do not redo the investigation or repeat uncertain effects; reconcile them through supported controls.
+Goal: accept only what the evidence supports, and choose the next work from the actual gap.
 
-## Coordinator: Assess The Result And Your Direction
+Assess the report and evidence you received. Ordinary assessment needs neither routine inspection nor an `assess` call; `assess` restores a suspended evidence view after new user input paused it.
 
-Assess the report and evidence already received. Ordinary assessment requires neither `inspect` nor `assess`. The `assess` operation restores a suspended assessment's evidence obligation; it does not perform judgment or accept the result.
+For a material claim, compare the accepted property, the observation actually made, the decisive assertions, the candidate's identity, and the result. A confident report or a green suite cannot fill a missing link. Keep unsupported required claims open and stop dependent work. Check the actual state before calling something a defect or crediting a fix.
 
-For a material claim, compare the accepted property, actual observer, decisive assertions, candidate identity, and result. A confident report or green suite cannot supply a missing link. Keep unsupported required claims open and stop dependent work.
+Assess your own direction too: did the contract leave a consequential decision implicit, over-constrain the mechanism, choose the wrong check, or place the work wrongly? A worker that asked no questions has not shown the contract was sufficient; missing specification shows in the result, as a plausible but different name, location, or behavior. Improve the next contract from the answer.
 
-Also ask whether your direction served the user's outcome: did it leave a consequential decision implicit, impose an unnecessary mechanism, choose the wrong observer, or size the assignment poorly? Accept a simpler valid implementation without demanding your preferred style. For a consequential design choice, assess its actual realization, not merely a claim that the spec was followed.
+Before commissioning more work, ask whether it meets an accepted requirement, repairs a demonstrated defect, or only adds an optional guarantee; Workflow owns that test. Then choose from the gap:
 
-Reuse adequate verification and Executor self-review. Use [Review Work](../../skills/review-work/SKILL.md) or [Review Artifact](../../skills/review-artifact/SKILL.md) when their judgment method is needed; load it when absent. A separate independent review remains a Workflow decision, not an automatic handoff step.
+- **Supported result:** continue with the next covered work, or accept the outcome.
+- **Evidence omitted but it exists:** recover it (below) before investigating again; absence from your view does not mean the action never happened.
+- **Missing or inadequate observation:** request the observation that decides it, without changing the required property.
+- **Supported defect:** assign the correction and affected checks to the owner its responsibility needs.
+- **Invalidated approach or unclear cause:** revise the direction or commission diagnosis rather than repeat the demand.
+- **User-owned choice:** take it to the user before dependent work.
 
-Choose the next action from the actual gap:
+Repeated failure needs a changed premise, check, contract, working set, or mechanism, not lower acceptance or endless repair. Reuse adequate producer verification; a worker's audit in the same session is not independent review, which remains a separate Workflow choice.
 
-- **Supported result, covered work remains:** assign the next coherent result.
-- **Existing evidence omitted:** seek supported selection/delivery correction before new investigation.
-- **Missing or inadequate observation:** request the discriminating evidence, preserving the required property.
-- **Supported defect:** explain the correction and affected checks.
-- **Invalidated approach or unclear cause:** revise the affected direction or investigate; do not repeat the same demand more forcefully.
-- **User-owned choice:** discuss through Workflow or Decision Gate before dependent work.
-- **Outcome complete or deliberately stopped:** close with an honest disposition.
+Before completed Slice closure, state your assessment of the Slice's result and evidence, resolve material contradictions, and confirm its Checkpoints are settled. Then direct the [Track Work](../../skills/track-work/SKILL.md) closure through whichever route your mode allows, preferably folded into work already going to that profile rather than a handoff of its own. A prior "close it if green" instruction cannot stand in for assessing results you have not seen. Workers may record factual progress while the Slice is open; a worker writing the closure returns instead if new evidence contradicts the accepted basis.
 
-Carry supported lessons into later contracts. Add precision where misunderstanding occurred; keep freedom where execution was sound. Repeated failure needs a changed premise, observer, contract, working set, or mechanism—not lower acceptance or an endless repair loop. Changing user-controlled compute configuration remains a separate decision.
+Use `freeflow_unit(operation: "close")` when the unit's outcome is supported, or to record an authorized `cancelled` or `deferred` outcome. Closing a unit does not complete a Slice or task, clear history, or authorize a commit or delivery. Continue covered work to the agreed return point.
 
-Use `freeflow_unit(close)` as Coordinator only when the required result and evidence are supported and applicable checkpoints and contradictions are resolved, or record an authorized cancelled/deferred outcome without claiming completion. Closing a unit does not complete a Working Record task, delete relevant history, or authorize delivery, commit, release, or deployment. Continue covered work to the user's agreed boundary, not merely to an internal handoff.
+## Keep Control And Continuity
 
-## Handle Input, Context, And Recovery
+New natural-language input, including "continue", goes to Coordinator. If it reaches a worker mid-assignment, honor any restriction at once, stop task work, and return the partial state. When the user asks what a worker did, answer from `freeflow_unit` inspection or by asking that worker; absence from your view does not mean the action never happened. Runtime State refreshes are observations, not new direction. Technical retries stay within the accepted assignment; `/freeflow resume` continues unchanged saved work after reconciliation and does not release a Manual hold.
 
-Under Automatic control, Coordinator owns substantive user interpretation, discussion, decisions, and reporting. New natural-language input, including "continue," goes through Coordinator. If it reaches an already prepared Executor request, honor restrictions immediately, stop task work, and return the available partial state. Runtime State refreshes do not trigger this interruption rule.
+During a Manual hold, preserve any interrupted assignment, partial effects, and pending assessment; keep no shadow delegation. If the held preset cannot do the work, report it and leave the choice to the user. When the user releases the hold, Coordinator reconciles current direction, the mode, outstanding responsibility, and anything done during the hold before routing again.
 
-Native tool responses and technical retries continue within the assignment. `/freeflow resume` is an explicit user control for eligible interrupted work after reconciliation, not permission to release a manual hold or resume ordinary work after a saved return. Releasing Manual control returns responsibility for reconciliation to Coordinator.
+After context loss, follow the bootstrap in the capability cue, reload the methods and the mode reference, and recover control, mode, contract or report, user direction, partial effects, and stop conditions. When a Working Record exists, Coordinator reads it in full through Track Work, and the artifacts under `What defines this task`, directly, in every mode. Large Recovery sources that only serve execution stay with the worker that needs them. An outstanding worker reconstructs and continues its recorded assignment, and its recovery reads stay within the contract's limits; do not wrap existing responsibility in a new assignment. A summary mentioning a superseded contract does not revive it.
 
-After context loss or uncertain continuity, recover control, current responsibility, applicable contract/report, user direction, partial effects, evidence limits, and stop conditions. Reload missing methods. When a Working Record exists, follow [Track Work](../../skills/track-work/SKILL.md) for complete `full` recovery and current-source reconciliation; record and evidence reads remain Executor work. Do not combine a superseded stopping instruction with a newer contract.
+### Recover Missing Evidence For An Assessment
 
-Attach recovery to the existing responsibility. Outstanding assignments recover through their supported continuation. Returned work may use an attached recovery-only phase only if the runtime actually exposes it; otherwise inspect saved communication and stop if insufficient. Do not simulate recovery by replacing the assignment or report. A separate recovery assignment is appropriate only when no existing assignment or assessment needs preservation.
+Outstanding assignments use ordinary continuation, not this. For the current returned assessment, Coordinator uses `freeflow_unit(operation: "recover")` with the missing-evidence question, any exact task-file `paths`, and any captured result ids in `results` (a context ref such as `ctx:1a2b3c4d` goes in the request instead; the worker selects it). Recovery belongs to the assignment's recorded worker. Preserve the unit, assignment, original report, outcome, revision, selections, and assessment.
 
-Use `freeflow_unit(assess)` when a suspended assessment becomes the intended activity again. Failed restoration leaves the gap open. Suspension pauses additional evidence restoration, not the relevance of ordinary admitted history. Navigation does not roll back files, processes, or task memory; historical instructions do not grant current authority.
+During recovery, the worker may select previously exposed evidence and read only exact admitted task paths, granted captured results, or packaged Freeflow skill and reference files. It must not edit, run commands or tests, broaden discovery, or resume task work. Report stale or unavailable evidence without rerunning anything. Return with `freeflow_return(operation: "supplement")` and stop reading. A `partial` or `blocked` supplement can deliver its communication while the full evidence obligation stays suspended; payload-free `retry` resends an unchanged saved supplement.
 
-When Context Control is effective, read its method before managing your own view. Either profile may reduce obsolete or redundant material without losing current direction, contrary findings, or promised evidence. Cleanup is optional and never changes the other profile's view, canonical history, or evidence membership. Prepare promised originals first; if cleanup fails, retain the extra context and continue the valid handoff. Do not discard useful communication merely because a unit closed.
+A separate recovery assignment fits only when no existing assignment or assessment needs preserving. Coordinator uses `cancel-recovery` when the lookup is no longer needed; the original report and assessment remain. Deliver the supplement or cancel recovery before `assess`; new user input does not settle recovery. Do not simulate recovery by replacing an assignment/report or opening a new unit.
 
-## ACT_BOUNDED: Inseparable Judgment And Action
+### Keep Useful History
+
+Closing, replacing, returning, and pausing change responsibility, not the value of history already admitted. Keep past work distinguishable from the current obligation without removing it. Navigation does not roll back files, processes, or the record; compaction does not justify inventing source bodies or repeating uncertain effects. When Context Control is effective, read its method before managing a view, and keep current direction, contrary findings, and promised originals. Optional cleanup comes after the promised evidence is prepared; if cleanup fails, keep the extra context and continue the handoff.
 
-Beyond permitted routing, instructional reads, and view-local context operations, direct Coordinator environment work requires both inseparable judgment/action and a concrete material loss from delegation. Task size, convenience, fewer switches, preference for the stronger model, or failed recovery is insufficient.
+## ACT_BOUNDED: Inseparable Judgment And Action
 
-Synthesis may qualify when the requested artifact is the governing judgment itself and a decision-complete contract would already contain essentially the artifact. Sensitive result-by-result intervention may also qualify. Separable gathering, routine checking, and ordinary implementation remain delegated.
+In `executor` and `both` modes, Coordinator may do other environment work only when judgment and action cannot be separated and delegating would lose something concrete. Examples: synthesizing a governing artifact when a complete contract would already be the artifact; intervening result by result in sensitive work. Task size, convenience, fewer switches, a failed recovery, or a preference for premium compute do not qualify, and separable production does not become judgment by being relabelled.
 
-Before acting, state ACT_BOUNDED with the scope, expected result, existing authority, stop condition, inseparable judgment, and delegation loss. Stay within it; end on completion, interruption, context loss, changed applicability, or before delegating again. It grants no permission and does not create, transfer, or close routing responsibility.
+Before acting, state ACT_BOUNDED with its scope, expected result, existing authority, stop condition, the inseparable judgment, and what delegation would lose. Stay inside that scope; end on completion, interruption, context loss, changed applicability, or before delegating again. It grants no permission, assignment, or acceptance. Helper-mode Coordinator production needs no ACT_BOUNDED.
 
-Stop applying the automatic split when control becomes Manual or routing becomes inactive. Preserve unfinished responsibility honestly and follow ordinary Workflow.
+Stop applying the Automatic split when control becomes Manual or routing becomes inactive; preserve unfinished responsibility honestly and follow ordinary Workflow.

package/capabilities/cognitive-routing/references/both-mode.md

@@ -0,0 +1,36 @@
+# Both Mode
+
+Judgment for placing work when Runtime State shows `Delegation: both`. The core skill's Rules still apply, including the limit on Coordinator's own environment work.
+
+Both mode is the middle ground between quality and cost. Executor does consequential work, including code; Helper does support; Coordinator plans, writes contracts, assesses, and talks to the user. Every assignment names its worker with `worker: "helper"` or `worker: "executor"`.
+
+## Choose The Worker Per Assignment
+
+Goal: each assignment goes to the cheapest worker that can do it without losing quality.
+
+Default: Executor for results whose behavior or failure needs engineering ownership; Helper for gathering, checks, setup, record maintenance, and small settled changes.
+
+| Situation | Worker |
+| --- | --- |
+| Find the callers, contracts, and conventions the next change will touch. | Helper |
+| Implement the change and its tests. | Executor |
+| A one-line authorization change with security consequences. | Executor: small, but consequential. |
+| A read-only audit that decides whether the design holds. | Executor: no writes, but substantive judgment. |
+| Rerun the validation suite and the formatter after Executor's change. | Helper |
+| Update several record entries after an accepted result. | Helper, or folded into an assignment already going out. |
+
+The failure to prevent is misplacement: a consequential change given to Helper because it is short, or Executor spent on pure gathering. Decide by the responsibility and its consequences, not by size or by whether the work writes.
+
+These are available routes, not phases. A unit may use only Helper, go straight to Executor, or keep one coherent result with Executor through its checks and corrections.
+
+## Reuse What The Other Worker Found
+
+Goal: no worker rediscovers what the other already established.
+
+Helper and Executor share ordinary history. A typical route: Helper gathers; Executor's contract points at what Helper found instead of asking it to explore; Coordinator receives what it needs through projection. After implementation, Helper can run follow-up checks with Executor's context already present. Recheck a fact only when its freshness matters or its source is no longer available.
+
+Executor forms the execution forecast for production work; Coordinator supplies the governing decisions.
+
+## Mind The Model Configuration
+
+The user may run Coordinator and Executor on the same model at different effort. On routes that keep the provider cache across effort changes (currently GPT-6 on an OpenAI API key or OpenAI Codex), handoffs to Executor then reuse the cache and cost less. Elsewhere, including OpenAI's Sign in with ChatGPT, each effort keeps its own cache, so the first handoff at each effort rereads the whole context and later ones reread what was added since that effort last ran. With different models, every switch rereads the whole context. Either way the configuration is the user's choice; do not change it.

package/capabilities/cognitive-routing/references/executor-mode.md

@@ -0,0 +1,48 @@
+# Executor Mode
+
+Judgment for placing work when Runtime State shows `Delegation: executor`. The core skill's Rules still apply, including the limit on Coordinator's own environment work.
+
+Executor mode is the main cost saver. A cheaper Executor does the environment work: investigation, preparation, artifacts, implementation, checks, and record maintenance. Coordinator plans, writes contracts, assesses, and talks to the user, and executes nothing itself except under ACT_BOUNDED. The saving comes from two places: projection keeps Executor's working trail out of Coordinator's context, and precise contracts keep Executor from searching.
+
+## Make The Contract Do The Heavy Thinking
+
+Goal: Executor's first attempt is right often enough that the saving outweighs the corrections.
+
+Coordinator's judgment reaches the work only through the contract, so the contract carries the decision. Frame the problem so the cheaper model finds it straightforward: the representation to use, the invariant to preserve, the wrong approach that looks right, and the check that tells them apart. For consequential design choices, write that content with the Implementation Decisions method in [Design for Depth](../../../skills/design-for-depth/SKILL.md).
+
+```text
+Weak:   Add caching to the config loader.
+Strong: Cache the parsed config per file path and invalidate when the file's
+        modification time changes. Two loads of an unchanged file parse once;
+        an edit between loads must be seen. A process-lifetime cache looks
+        right and passes a single-load test but serves stale config, so check
+        with an edit between two loads.
+```
+
+A cheaper model applies an escape clause literally, so write requirements as outcomes for named things ("each caller listed below still gets X"), never "unless…" or "as today", and say where the change belongs.
+
+Default: give structure where Executor has shown difficulty or the property is easy to get subtly wrong, and freedom where the mechanics are ordinary. Signals the balance is off:
+
+- Executor returns work that misses an unstated decision: the contract left it implicit.
+- The contract is longer than the change and reads like a patch: Coordinator has done the work at premium price, and Executor only transcribes it.
+- The same misunderstanding recurs: change how you represent the problem, not how forcefully you state it.
+
+## Gather, Then Produce
+
+Goal: Coordinator's contracts rest on evidence without Coordinator doing the reading.
+
+Coordinator may first commission evidence or a proposal, interpret what comes back, and then commission production. Executor gathers; projection carries the selected evidence to Coordinator; the next contract uses it to narrow Executor's search. Do not add a gathering pass when Executor already has an adequate basis, and do not pre-solve every detail before any evidence exists.
+
+Executor forms the execution forecast for production work. Coordinator supplies the governing decisions it rests on.
+
+## Ask For Evidence That Decides
+
+Goal: Coordinator can assess from what projection delivers, without asking for the whole trail.
+
+Request evidence by the claim it must support: the decisive test output, the changed interface, the contradicting observation. Requesting everything moves Executor's trail into Coordinator's context and cancels the saving; requesting too little forces a recovery round. When a return lacks evidence that exists, recover it rather than re-running the work.
+
+## What Coordinator Does Not Do Here
+
+Coordinator writes an artifact itself only when the user explicitly assigns it (see the core skill). Record maintenance goes to Executor, folded into an assignment already going out rather than sent as a handoff of its own. Recovery after context loss is the exception the core skill names: Coordinator reads the Working Record and the artifacts that define the task directly.
+
+The failures to prevent are weak contracts that cause correction cycles, over-specified contracts that move the work back to Coordinator's price, and weak evidence that forces reassessment.

package/capabilities/cognitive-routing/references/helper-mode.md

@@ -0,0 +1,47 @@
+# Helper Mode
+
+Judgment for placing work when Runtime State shows `Delegation: helper`. The core skill's Rules still apply.
+
+Helper mode is for the best output quality. Coordinator implements; Helper takes everything that does not need Coordinator-level reasoning. There is no Executor to invoke or simulate.
+
+## Delegate By Default
+
+Goal: Coordinator's premium compute goes to the work that needs it, and nothing else.
+
+Default: delegate a step unless it needs Coordinator-level reasoning. Keep that category narrow:
+
+- governing decisions and design;
+- substantive implementation, meaning changes whose behavior or failure needs engineering ownership;
+- the conversation with the user.
+
+Helper takes the rest: gathering sources and skills, investigating bounded questions, preparing authorized setup, running existing checks and validations, separate record maintenance, and straightforward settled changes that are local, reversible, and easy to check. Helper can reason, compare evidence, spot contradictions, and choose local mechanics; it is not limited to copying facts.
+
+The failure to prevent is under-delegation: classifying every step as Coordinator-level, so Coordinator does all the gathering, checking, and bookkeeping itself and the mode saves nothing.
+
+## Do Not Split What Belongs Together
+
+Goal: handoffs save more than they cost.
+
+Keep a tightly coupled edit, check, and interpret loop with Coordinator. Moving each check to Helper adds a contract, a ramp-up, and a return, and forces Helper to rebuild the context Coordinator already holds.
+
+Hand off results that stand on their own:
+
+| Situation | Placement |
+| --- | --- |
+| Before implementing, the sources, callers, and conventions for the planned change need gathering. | Helper gathers; Coordinator implements from the result. |
+| Mid-implementation, Coordinator wants to know which acceptance requirements the candidate meets, which lack a check, and which test edits changed coverage. | Helper runs a read-only cross-check against the Slice's acceptance requirements and returns without patching. |
+| After a feature lands, several record entries, a validation run, and a formatting pass are due. | Helper, as one assignment. |
+| Coordinator just ran a failing test and knows the fix. | Coordinator fixes and reruns; no handoff. |
+| One line of the Working Record needs updating in the middle of Coordinator's own work. | Coordinator updates it; a handoff would cost more than the edit. |
+
+If Helper reaches substantive work outside its assignment, it returns findings and partial state, and Coordinator takes the next decision.
+
+## Route Preparation
+
+Helper gathers; Coordinator implements. Gathered evidence must reach Coordinator: with projection on, Helper selects it at return; with projection off, Coordinator sees Helper's work in ordinary history. Coordinator forms the execution forecast itself.
+
+## Coordinator's Own Production
+
+Coordinator's direct implementation passes through no handoff, and handoffs are part of how routing keeps long work on course. Rely on Execute Work's forecast and on Workflow's check before each continuation: does the next change meet a requirement, repair a demonstrated defect, or only add an optional guarantee? Do not invent assignments for your own work to recreate that boundary, and use no ACT_BOUNDED; direct production is what this mode is for.
+
+Coordinator may update the Working Record directly as part of its own work. When closing a Slice, fold the writeback into Helper work already going out, or do it directly when it is one small update.

package/capabilities/compaction/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: "compaction"
+description: "Use when Freeflow says compaction is due or the user asks to compact: prepare what the conversation needs to continue, then compact with freeflow_compact."
+---
+
+# Compaction
+
+Compaction replaces the conversation with what you write, and starts a new cycle: the stretch of conversation until the next compaction. The next cycle starts from your summary, the Working Record and what it points to, the carried context, and the lines Freeflow adds itself; everything else leaves your context, this skill included. Most drift after compaction comes from a summary that lost something the next step needed.
+
+The summary works like a Working Record ([Track Work](../../skills/track-work/SKILL.md)) for one cycle. Ask Track Work's question: if context were lost now, what would the next context need that it could not recover from the Working Record, its defining artifacts, the workspace, or the carried context? Write that, and nothing more. Concise is not lossy: keep a detail when removing it could change the next action.
+
+## Rules
+
+The Rules are binding; if one cannot be met, stop and say why. The rest of this skill is judgment: follow its goal, and adapt when a different choice serves it better.
+
+- With a Working Record, update it first (Track Work, "Prepare For A Context Boundary"), then write the summary, so the two agree. Name the record's path in the summary: Freeflow never names one, and recovery starts from it.
+- Compaction is a context boundary, not a Slice transition or a Checkpoint. Do not rush, close, or pause a Slice to compact, claim an unfinished check passed, or guess the outcome of a running operation.
+- Never write a requested, reported, or expected result as observed. Name every partial or uncommitted change, unverified result, running command, and obligation still waiting on its trigger.
+- Keep exact: paths, identifiers, commands, error text, numbers, and the user's words wherever wording matters. Never paraphrase a decision or a constraint.
+- Material that exists only in the conversation, such as a pasted file or a long message, leaves with it. With a Working Record, save it under the task's `sources/` and point to it; without one, quote what matters in the summary.
+- Under Cognitive Routing with projection, the Coordinator does not compact: its view leaves out what workers did. Delegate an assignment whose contract says to compact with `freeflow_compact` and then return with `freeflow_return`, plus any other work it covers: after compacting, the worker sees the contract again but not its own `freeflow_compact` call. A worker's summary covers the whole session: the user's requests, the Coordinator's decisions, and the state of other work.
+
+## When to compact
+
+Goal: compact where stopping loses nothing that is not written down. That is a safe point: a finished step whose result you know, such as a check you ran and read, a complete set of edits, or a written report. Halfway through an edit set, with a command still running, or partway through a batch of reads you need together is not one.
+
+- At Freeflow's first notice ("compaction is due soon"): if you are at a safe point, compact now. If your work ends within a step or two, with a final answer or a worker's return, finish it instead. Otherwise finish the current step, start nothing large, then compact.
+- At "compact now", or when the user asks: the end of your current step is the safe point. If the step cannot end soon, write its partial state into the record or summary and compact. Under Cognitive Routing a worker compacts before returning: the Coordinator and the next assignment continue the same history, so a return does not stop its growth.
+
+## The summary
+
+The previous cycle's summary is at the top of your context. Fold what still holds into the new one; drop what is done or no longer matters. Write state, not a story: what is true now, not the order things happened in. Leave out what the Working Record holds and what Freeflow states itself: the cycle, the routing profile, running background commands, and the files read and changed.
+
+Read [Summary Format](references/summary-format.md) before writing, and use the shape that matches the work:
+
+- **With a Working Record**, the record holds the task. The record-backed shape (`Task`, `Now`, `In flight`, `Next steps`) lets a fresh context continue the current step correctly on its own; the record lets it continue the task.
+- **Without one**, the summary is the record for this cycle, in the record-shaped shape: the record's own headings.
+
+Compaction never creates a record; whether a task needs one is decided at its start or when facts change its scope.
+
+The limit is about 8,000 tokens. Most summaries need far less. If `freeflow_compact` refuses the call, fix what it names and call it again.
+
+## What to carry
+
+The notice gives the budget. Freeflow carries the newest results of your work in progress itself (under Cognitive Routing, those of your current assignment; otherwise, those of this cycle), filling whatever budget your picks leave, and lists the rest by ref. Pick only what that misses and the next step needs in full: older output you are working from (by routing ref, such as `ctx:1a2b3c4d`, when Cognitive Routing is on; otherwise by the id in the notice's list) and files you are changing (line ranges for large files), which are read fresh at compaction. Leave out what is cheap to re-read or already in the summary or record. The user's latest messages are carried for you. When the notice says context reuse is off, pick nothing.
+
+## After compaction
+
+This skill leaves your context with the rest of the conversation. Freeflow's recovery message, right after the carried context, says how to recover; follow it.