@hassangameryt/freeflow 0.7.1 → 0.7.3

package/skills/discuss/references/discussion-continuity.md

@@ -2,7 +2,7 @@
 
 Read this before preserving discussion across context loss, creating or updating durable task memory from discussion, or carrying a proposed or selected checkpoint beyond the current conversational context.
 
-Discussion state is not automatically a Working Record, Spec, Plan, checkpoint, or authority.
+Discussion state is not automatically a Working Record, Spec, Plan, checkpoint, or authority. Preserve the required outcome separately from the current approach, and distinguish the user's execution agreement from proposals that have not been selected.
 
 ## Keep It In Conversation When Possible
 
@@ -23,7 +23,7 @@ Authority or decision still needed:
 
 Prefer natural prose. Use structured fields only when they prevent ambiguity or support a transition. Never emit empty or irrelevant fields.
 
-Do not preserve a transcript, repeated rationale, rejected alternatives that no longer matter, or every discussion turn.
+Do not preserve a transcript, repeated rationale, rejected alternatives that no longer matter, or every discussion turn. Retain a rejected approach when losing its reason would cause the next context to repeat it.
 
 ## Choose Durable Memory By Purpose
 
@@ -62,6 +62,10 @@ Preserve only supported state that could affect later interpretation or action.
 
 When the initial record need arises from discussion, preserve the state that justified the record in the first authorized atomic update. Do not create an empty shell and lose the decisions, proposals, or uncertainty that made continuity necessary.
 
+When a rough route is useful, preserve provisional Slices and their actual dependencies without pretending the later implementation is settled. Keep the current unit concrete and later work directional. Use the existing Current Context, Current Work, Future Work, and History fields; do not add a second phase or context-cycle ledger.
+
+Preserve the agreed outcome, scope, and user-facing return condition when losing them could interrupt covered work or permit drift. Authorization to investigate or propose a design is not acceptance of its production consequences. When learning changes the approach, retain the question, strongest evidence and limits, remaining uncertainty, artifact disposition, and affected later work—not the prototype's construction history.
+
 After preservation, return to Discuss unless Workflow established another route. Record mutation does not transfer ownership or authorize execution.
 
 ## Carry Proposed And Selected Checkpoints
@@ -107,7 +111,7 @@ Authority or user decision needed:
 
 Do not restart from zero, rewrite unaffected decisions, or narrate completed work.
 
-After context loss, recover through Track Work’s prescribed view before relying on the record. Compare recovered memory with current user direction and live evidence. Reconcile only what current evidence changed.
+After context loss, recover the complete record through Track Work's `full` view before relying on it. Compare current sections and relevant History with current user direction, accepted artifacts, and live evidence. Reconcile affected meaning and dependent future work; do not repeat a disproved approach or preserve a stale plan merely because the record contains it. With intact context, use `resume` or targeted reads only when needed.
 
 ## Stop
 

package/skills/execute-work/SKILL.md

@@ -1,141 +1,122 @@
 ---
 name: execute-work
-description: Use when carrying out or resuming requested or approved implementation, fixes, prototypes, documentation, configuration, repository maintenance, or other concrete work.
+description: "Use when preparing and carrying out requested or approved concrete work, including implementation, fixes, prototypes, documentation, configuration, and repository maintenance."
 ---
 
 # Execute Work
 
-Turn one accepted outcome into a supported concrete result.
+Produce the agreed concrete result through supported preparation, bounded execution, verification, and correction. Do not make the user supply an implementation plan when the request authorizes you to figure it out.
 
-Workflow establishes the authority envelope and current Slice. Execute Work coordinates bounded execution and in-Slice continuation. It does not redefine intent, own durable task memory, make user decisions, prove claims beyond available evidence, or authorize checkpoints and follow-on work.
+Workflow establishes the work agreement and coordinates authority, ownership, and the user-facing return boundary. Execute Work owns implementation preparation and continuation within it. Task memory belongs to Track Work; governing choices remain with the user.
 
-A **bounded action** is one coherent execution or learning result with a checkable claim. It may include several reads, edits, commands, files, and focused checks. A tool call, file change, or execution-method change is not automatically another bounded action.
+## Establish The Execution Basis
 
-Read [Execute Work Edges](references/execute-work-edges.md) when resuming uncertain prior work, changing the Slice boundary, reaching a selected checkpoint, or exposing separately controlled follow-on work.
+Consume the current request, accepted discussion, governing artifacts, and relevant live state. Establish which assignment and stopping condition currently apply; do not combine older directions with a superseding contract. Resolve material ambiguity before dependent effects. Do not restart discovery because execution was selected.
 
-## Follow The Execution Loop
+Before production changes, establish:
 
-Use this as a feedback loop, not a mandatory phase sequence:
+- **Outcome:** the required result, constraints, non-goals, and acceptance boundary.
+- **Approach:** the supported mechanism, affected code or artifacts, dependencies, and necessary ordering.
+- **Evidence:** a check or observation capable of disagreeing with the result.
+- **Agreement:** covered effects, extent of work, and when to return to the user.
 
-```text
-[Accepted concrete result]
--> [Consume the current Slice and relevant live state]
--> [Choose one bounded action and a check that can disagree]
--> [Choose one primary execution route]
--> [Execute and observe]
--> [Determine what the evidence supports]
-   -> unsupported cause or repeated failure -> Diagnose Failure
-   -> user-owned choice or source conflict -> Decision Gate
-   -> supported -> Verify at the required boundary
-                -> self-review
-                -> accept or correct once
--> [Continue inside the Slice or return the changed boundary to Workflow]
-```
+Before effects, check whether a selected checkpoint or separately controlled boundary is already due. Do not cross it while unresolved.
 
-Implementation beginning does not justify continuation. Continue only while the accepted result, authority, evidence boundary, and Slice remain coherent.
+If the agreement is materially unclear, return to [Workflow](../workflow/SKILL.md) before the unsettled execution. A clear request may already establish it; do not ask again merely to perform a ritual.
 
-## Enter From Established Direction
+An agreement to fix a bug can cover investigation before the remedy is known. An agreement to return a plan does not cover production edits. Distinguish evidence gathering from implementation even when both are authorized.
 
-Consume the understanding already established by the request, [Discuss](../discuss/SKILL.md), Workflow, and accepted source truth. Do not restart discovery or recreate task context merely because execution began.
+Use [Discuss](../discuss/SKILL.md) when outcome or material approach alternatives need reconsideration, [Decision Gate](../decision-gate/SKILL.md) for one blocking user-owned choice or source conflict, and [Diagnose Failure](../diagnose-failure/SKILL.md) when the cause is unsupported.
 
-Before effects:
+## Gather Enough Context For This Unit
 
-- confirm the concrete result and relevant non-goals;
-- inspect the smallest live source set needed to avoid relying on stale context;
-- identify one bounded action;
-- name the claim its result must support;
-- identify a direct check or observation that can disagree;
-- confirm no selected checkpoint or separately controlled boundary is already due.
+Choose the next coherent result, then identify what is missing to implement and check it. Reuse current supported sources; inspect only the live boundaries whose freshness matters.
 
-When a Working Record exists, use [Track Work](../track-work/SKILL.md) for recovery, reconciliation, and write-ahead Current Slice state before relying on or changing it. Do not create durable memory for a short direct result merely because execution was selected.
+Find the relevant mechanism, callers, contracts, and observing seam before changing them. Do not begin substantial implementation from a guessed API, ownership boundary, or failure cause. Do not read every file or settle every later Slice merely to avoid all uncertainty.
 
-Return to [Workflow](../workflow/SKILL.md) when the intended result, authority, or current Slice is missing or materially inconsistent. Use [Decision Gate](../decision-gate/SKILL.md) when one known user-owned choice or source conflict blocks execution.
+Readiness means you can explain what will change, why it should produce the accepted result, and how the result will be checked. It does not require knowing every line or helper in advance. If an unfamiliar fixture or observing stage could invalidate substantial dependent work, establish that observer first through a bounded investigation. Reuse adequate fixtures; do not make a separate prototype mandatory.
 
-## Bound The Action
+Before substantial implementation, read [Design for Depth](../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 applicable design decisions already supplied; distinguish required constraints, suggested mechanisms, and local freedom. A reference to a design is not enough when its relevant content is unavailable. Resolve the consequential unknown, not every future coding detail.
 
-Choose the smallest coherent action that can produce a useful result and evidence.
+Use [Action Selection](../action-selection/SKILL.md) when choosing the next source, observer, or effect is uncertain, broad, or repetitive. Stop gathering when the current unit is sufficiently supported. A mechanical read of a known caller or signature can remain inside execution; discovering an invalidated mechanism requires re-entry before dependent edits.
 
-A bounded action may be:
+When specialized guidance is needed, read [Domain Skill Composition](../workflow/references/domain-skill-composition.md). Before writing or changing code, read [Code Practices](references/code-practices.md). Before designing or materially changing a behavior check, read [Test Design](../verify-work/references/test-design.md); choose its oracle from accepted behavior rather than the implementation.
 
-- one accepted behavior implemented through a vertical test-first loop;
-- one behavior-preserving simplification with before-and-after evidence;
-- one coherent documentation, configuration, or repository change;
-- one reversible learning result with a discard, revise, or promotion condition;
-- one direct mechanical result whose complete effect is already clear.
+## Keep The Unit Coherent
 
-Keep unrelated work and later outcomes outside it. Do not split an action merely because it touches several files or tools. Do not combine results that require different authority, evidence boundaries, or independently useful outcomes.
+A bounded action produces one useful execution or learning result with a checkable claim. It may contain several files, tools, edits, and checks. Do not fragment it by command, file, test, or method change.
 
-Allow routine adaptation of local mechanics, ordering, and focused checks while the accepted result, permitted effects, and acceptance boundary remain unchanged. Return material changes to scope, behavior, evidence quality, persistence, or stop conditions to Workflow before acting.
+Choose work that can be understood, executed, checked, and corrected with a manageable working set. Split when dependencies, uncertainty, or distinct outcomes make one attempt unreliable; retain enough understanding of later constraints to avoid an obvious dead end.
 
-## Choose One Execution Route
+When a Working Record exists, use [Track Work](../track-work/SKILL.md) for recovery and write-ahead Current Slice state before Slice execution. Preserve useful provisional remaining work and dependencies through its existing fields. Do not create memory for a short direct result merely because execution began.
 
-Use one primary execution route at a time:
+Read [Execute Work Edges](references/execute-work-edges.md) when resuming uncertain prior work, changing a Slice boundary, reaching a selected checkpoint, or exposing separately controlled follow-on work.
 
-- execute directly when the effect is known, mechanical, and directly verifiable;
-- use [TDD](../tdd/SKILL.md) when accepted behavior should be guided by an observed failing check;
-- use [Simplify Code](../simplify-code/SKILL.md) when working behavior should become easier to understand or change without altering its contract;
-- use the required domain guidance when technology, risk, or repository conventions need a specialized method;
-- use [Diagnose Failure](../diagnose-failure/SKILL.md) before correction when the cause is unsupported or repeated attempts have failed.
+## Execute Through One Suitable Method
 
-When specialized guidance is needed, read [Domain Skill Composition](../workflow/references/domain-skill-composition.md). Keep one Freeflow owner and return domain evidence to the current route.
+Implement the supported approach directly when the outcome and mechanism are understood. Unfamiliar work may need preparation first; it does not automatically require a separate prototype or a test-first implementation sequence.
 
-Before writing or changing code, read [Code Practices](references/code-practices.md).
+Use one primary method at a time:
 
-Action Selection controls environment interactions, not execution-method choice. When the next interaction is uncertain, broad, or likely to repeat without changing understanding, use [Action Selection](../action-selection/SKILL.md) to select and bound one useful interaction. When the next read, edit, or check is obvious, take its fast path directly.
+- direct implementation for a supported change;
+- [Simplify Code](../simplify-code/SKILL.md) when behavior-preserving complexity reduction is the accepted outcome;
+- specialized domain guidance when the environment or risk needs it;
+- a bounded learning action when an empirical uncertainty must be resolved before production work.
 
-## Execute Without Drifting
+Preserve accepted behavior, failure semantics, repository conventions, and source truth. Do not rewrite tests, Specs, Plans, policies, or acceptance merely to make implementation pass.
 
-Implement the bounded result through the selected route.
+Allow local choices of helpers, editing order, and focused checks while the agreed result and effects remain unchanged. Handle edge cases required by accepted behavior, direct evidence, or material safety; return undefined consequential behavior rather than encode a guess.
 
-Preserve accepted behavior, source truth, repository conventions, and relevant failure semantics. Do not rewrite tests, checks, Specs, Plans, policies, or established behavior merely to make implementation pass.
+For an unfamiliar design boundary that could invalidate later work, establish its first coherent implementation and distinguishing observation before dependent expansion. Compare the actual ownership, identity, ordering, and failure behavior with the selected design—not merely its proposed filenames. Preserve accepted predicates when a sketch proves wrong; stop dependent effects and resolve the affected mechanism through the current owner. Supported local improvements need no automatic handback or separate review.
 
-Handle an edge case only when accepted behavior, observed evidence, or material safety requires it and the expected result is settled. Return undefined observable behavior to Workflow rather than encoding a guess.
+## Execute A Bounded Learning Action
 
-Let experiments fail safely. Keep disposable or diagnostic output outside production behavior until promotion is deliberately selected.
+Consume the declared question, observer, permitted effects, expected evidence, and return condition. If they are insufficient for safe execution, establish the missing basis through the requesting owner before acting. Do not assume Discuss was previously used or repeat framing that is already adequate.
 
-Stop the patch stream when related corrections keep adding caller coordination, public states, flags, retries, test-only seams, or recovery rules. Diagnose the shared cause before another patch. Use [Design for Depth](../design-for-depth/SKILL.md) only when direct evidence establishes structural ownership, interface, state, or failure-unit pressure.
+Build and run only what the observation needs. Correct an understood local observer defect within scope. Before adding scaffolding or a dependency, check whether it serves the current observation or implements a future product. Return before materially expanding effects or pursuing a different question.
 
-Do not turn nearby cleanup, documentation, migration, deprecation, commit, push, integration, release, or launch into implied execution scope.
+Stop when the question is answered or the observing limit is reached. Report support, contradiction, inconclusive evidence, or unavailable evidence honestly; do not keep polishing the prototype to manufacture a favorable result.
 
-## Accept Evidence At The Claim Boundary
+Return evidence, limits, exploratory artifacts, and residual effects to the owner that asked the question, following the agreed artifact disposition. Do not silently promote exploratory code into production, invent acceptance, or claim unobserved integration. The receiving owner assesses what the finding changes and which next action is supported and authorized.
 
-Close the evidence iteration when the bounded action’s claim is ready to be accepted or used by dependent work—not after every edit or command.
+## Re-enter When The Basis Changes
 
-1. Run the focused checks or observations required by the selected method.
-2. Use [Verify Work](../verify-work/SKILL.md) when the claim or observing boundary needs explicit factual classification.
-3. Once fresh evidence supports the claim, use [Review Work](../review-work/SKILL.md) for silent self-review.
-4. Return one clear local defect to the producing route when existing authority covers correction.
-5. Re-run the affected evidence and repeat only the affected review lenses once.
-6. Use Diagnose Failure when the cause is unclear or correction repeats.
-7. Use Decision Gate when evidence exposes unsettled behavior or a user-owned choice.
+Do not continue merely because implementation has begun.
 
-A green check does not prove behavior it did not exercise. Source inspection does not prove runtime behavior. Review judgment does not replace verification.
+- Clear local defect and supported remedy -> correct within the same action.
+- Required outcome clear but mechanism invalidated -> stop dependent edits and re-establish the approach.
+- Failure cause unclear or correction repeats -> Diagnose Failure before another patch.
+- Expected behavior or acceptance unsettled -> Discuss or Decision Gate.
+- New requirement, scope, compatibility, persistence, evidence, or user-facing return boundary -> Workflow before adopting it.
 
-Further polish, advisory warnings, unrelated findings, and optional improvements are feedback to classify—not authority to keep editing.
+Before pursuing a prerequisite, distinguish what the accepted outcome requires from what the current approach happens to need. Choose the smallest supported remedy preserving acceptance. A failed approach does not prove that a host change or stronger guarantee is necessary.
 
-## Continue Or Return
+When corrections keep adding caller coordination, public states, flags, retries, test-only seams, or recovery rules, stop the patch stream. Diagnose the cause; use [Design for Depth](../design-for-depth/SKILL.md) when direct evidence establishes structural pressure. Do not use that lens to broaden ordinary local work.
+
+Preserve unaffected changes and contradictory evidence. An optional improvement is not unfinished work.
+
+## Verify And Self-Review The Result
 
-Continue inside the same Slice when:
+Check at the boundary where a result will be accepted or used—not after every edit or command.
 
-- the next bounded action serves the same accepted result;
-- its authority and evidence boundary remain covered;
-- the combined result can still be verified coherently;
-- no stop condition or selected checkpoint is due.
+1. Run the covered focused checks through the actual behavior or artifact boundary.
+2. Use [Verify Work](../verify-work/SKILL.md) to classify what the observations support and what remains unverified.
+3. Once evidence initially supports the result, use [Review Work](../review-work/SKILL.md) for silent self-review of concrete work. Guiding artifacts use their owning artifact-review route.
+4. Correct a supported local defect within authority, then rerun affected evidence and affected review lenses once.
+5. Route unresolved or repeated failure rather than iterating blindly. Distinguish a code defect from an invalid observer, stale evidence, or a misunderstood assignment before selecting another correction.
 
-A method change, verification run, self-review, correction, or pause does not create or complete a Slice by itself.
+A green check proves only its exercised assertions; a source read does not prove runtime behavior. Tests may be written before or after implementation as appropriate, without a formal test-first loop or invented earlier failure. Review judges suitability without replacing evidence. Evidence gaps in required behavior remain visible; optional stronger claims may be qualified instead of becoming extra work.
 
-When durable memory exists, use Track Work to preserve only material changes to context, authority, Slice boundaries, evidence, blockers, decisions, checkpoints, and the next useful action. Do not record every command, edit, or execution choice.
+Independent review is separately selected. A self-review finding does not require a reviewer, and a reviewer suggestion does not authorize another change.
+
+## Continue Or Return
 
-Return to Workflow before beginning a distinct result, crossing an uncovered boundary, changing the accepted strategy materially, or performing a selected checkpoint or separately controlled follow-on action.
+Continue within the Slice while the next action serves the same outcome, remains covered, and can still be checked coherently. A method change, correction, or verification run does not create or close a Slice.
 
-## Report The Supported State
+When durable memory exists, preserve only material changes to understanding, dependencies, scope, evidence, blockers, and the next useful action. Before context loss, record truthful partial state rather than rushing to completion. Resume only after required reconstruction and relevant live-state reconciliation.
 
-Report proportionately:
+Return to Workflow when a distinct Slice is ready, a selected checkpoint is due, the agreement changes, or no useful covered continuation remains. Workflow can select another already-authorized Slice without asking the user again. Internal method returns and delegation handbacks are not the user-facing endpoint.
 
-- the concrete result;
-- the strongest fresh evidence and what it does not prove;
-- material corrections or route changes;
-- the Current Slice or checkpoint state when relevant;
-- unresolved, deferred, or unverified work.
+Stop at the agreed return condition or an uncovered consequential boundary. Do not add cleanup, documentation, migration, deprecation, commit, push, integration, release, or launch merely because it would be useful.
 
-A supported bounded action is not automatically a completed Slice. A completed Slice does not authorize a checkpoint, another Slice, push, integration, release, or launch.
+Construct the report from inspected resulting files, assertions, and outputs—not requested changes phrased as accomplishments. Distinguish implemented, checked, and still unsupported properties. Account for relevant edits after the checks; do not pair a fresh pass with superseded code or test captures. Reuse applicable evidence and report missing bodies or cases explicitly. A completed action is not automatically a completed Slice, task, or delivery.

package/skills/execute-work/references/execute-work-edges.md

@@ -12,6 +12,8 @@ When durable memory exists, enter [Track Work](../../track-work/SKILL.md) and us
 
 Resume the same Slice only while its intended result, authority, evidence boundary, and stop condition remain coherent. Otherwise preserve supported work and return the changed boundary to [Workflow](../../workflow/SKILL.md).
 
+Recover the user-facing return condition separately from the next internal action. A supported record may preserve approval for the remaining task, but a proposed next action is not that approval. After reconstruction, continue covered work rather than returning solely because a context boundary occurred.
+
 Do not restart discovery, repeat supported work, or infer progress from summaries, Plans, records, handoffs, staged files, or partial artifacts.
 
 ## Distinguish Adaptation From Boundary Change
@@ -24,11 +26,15 @@ Routine changes to local mechanics, implementation order, tools, and focused che
 - the required observing boundary;
 - the stop condition.
 
-Return to Workflow when new evidence changes behavior, scope, persistence, compatibility, public interfaces, risk, evidence quality, or another user-owned outcome.
+A mechanical read of a known caller or a local correction may remain inside execution. If new evidence invalidates the implementation premise, stop dependent edits and re-establish the approach; do not hide renewed investigation inside a patch stream.
+
+Before following a new prerequisite, identify whether it blocks the required outcome, the chosen approach, or only the current observer. Preserve acceptance, compare supported in-scope remedies, and return to Workflow when the remedy changes behavior, scope, persistence, compatibility, public interfaces, risk, evidence quality, or another user-owned outcome.
 
 Keep an accepted extension in the current Slice only when its result remains coherent, explicit authority covers the added effects, and the combined boundary can still be verified as one unit. When a Working Record exists, Track Work records the extension before execution.
 
-Use another Slice when the work has a distinct result, authority source, evidence boundary, independently useful outcome, or explicit abandonment of the original result.
+Use another Slice when the work has a distinct result, authority source, evidence boundary, independently useful outcome, or explicit abandonment of the original result. Context pressure may require an earlier safe continuation boundary without inventing a completed result or new Slice.
+
+A whole-task agreement may already cover later Slices. Return their selection and lifecycle to Workflow and Track Work without requesting redundant user permission. A selected checkpoint or the agreed user-facing endpoint still stops dependent work.
 
 ## Route A Selected Checkpoint
 
@@ -44,7 +50,7 @@ Stop before dependent work, use the checkpoint’s owner, and return its result
 
 When durable memory exists, Track Work preserves the checkpoint’s selection, condition, result, and task effect.
 
-Do not create a checkpoint merely because an action or Slice ended. Do not force a stale checkpoint when its condition, evidence, or protected boundary no longer holds.
+Do not create a checkpoint merely because an action or Slice ended. Do not force a stale checkpoint when its condition, evidence, or protected boundary no longer holds; return the discrepancy for a supported cancellation, replacement, deferral, or revision before dependent work.
 
 ## Separate Follow-On Work
 

package/skills/handoff/SKILL.md

@@ -1,92 +1,82 @@
 ---
 name: handoff
-description: Use when work must continue safely after a pause, context change, or ownership transfer.
+description: "Use when work must continue safely after a pause, context change, or ownership transfer."
 ---
 
 # Handoff
 
-Preserve the smallest point-in-time continuation package another context needs to orient safely.
+Preserve the point-in-time information another context needs to continue the agreed work without restarting discovery or changing its goal.
 
-A **handoff** transfers current context. A [Working Record](../track-work/SKILL.md) is living task memory. When a Working Record exists, reconcile changed task state through Track Work, reference it from the handoff, and add only transfer-specific context the recipient would otherwise miss.
+A [Working Record](../track-work/SKILL.md) maintains living task state. A handoff identifies that record, the relevant sources, and transfer-specific facts the recipient would otherwise miss. Neither is authority, proof of completion, or a replacement for current user direction and live evidence.
 
-A handoff is memory, not authority. It may record where approval or authority came from, but it does not create either, freeze a Plan, override live evidence, or prove completion.
+## Choose The Transfer Boundary
 
-## Choose The Transfer Shape
+Identify the recipient, purpose, and available transfer mechanism before writing.
 
-- **Ephemeral handoff:** use the current response, host continuation mechanism, or a temporary path for immediate transfer after a pause, compaction, session change, or short-lived ownership change. Do not create a file when the response or host mechanism is sufficient.
-- **Repo-memory handoff:** use the repository's established handoff location when durable project continuation context is requested or approved.
+- **Ephemeral handoff:** use the response or host continuation mechanism for immediate transfer, including compaction. Use a temporary file only when the transfer needs it.
+- **Repo-memory handoff:** use the repository's established destination when durable continuation documentation is requested or approved.
 - **User-provided destination:** follow the requested safe location and format.
 
-Do not silently promote ephemeral context into repository memory. Ask one direct question when the destination changes durability, privacy, repository state, intended audience, or authority and the user has not chosen.
+Do not turn an ephemeral transfer into repository memory. If the destination materially changes durability, privacy, repository state, audience, or authority and the user has not chosen it, ask one question and wait.
 
-Read [Handoff Templates](references/handoff-templates.md) after the transfer shape, recipient, and purpose are clear.
+Read [Handoff Templates](references/handoff-templates.md) after the shape, recipient, and purpose are clear. Use only fields that change safe continuation; the template is not a requirement to create another document.
 
-## Prepare From Live State
+## Prepare From The Actual State
 
-Before packaging the handoff:
+Inspect only the relevant worktree, artifacts, processes, and evidence needed to describe what the recipient will encounter. Reconcile an existing Working Record through Track Work when its understanding, current work, dependencies, evidence, or next action changed.
 
-1. Inspect the current worktree, active artifacts, and evidence needed for the transfer.
-2. Reconcile an existing Working Record when its current state, slice, decisions, checkpoints, or next action changed.
-3. Identify the recipient, purpose, and boundary being crossed.
-4. Separate the next accepted action and its authority source from an unapproved recommendation.
+Preserve the execution agreement separately from the immediate assignment: what outcome remains authorized, what this unit covers, what is excluded, and when the user expects a return. Identify the assignment's source and any superseded instruction whose reuse would misdirect continuation. A recommendation to continue is not the same as approval to finish the remaining task.
 
-Do not create a Working Record merely because a handoff exists. Do not change task lifecycle or slice state merely because continuation context is requested.
+Do not create a record merely because a handoff exists or change task/Slice state merely because context will be transferred. Use the host's safe boundary for ongoing operations; do not infer an unobserved result or interrupt a mutation to make a cleaner handoff.
 
-## Capture What Changes Continuation
+Partial work is a valid transfer state. Preserve unverified edits, failing checks, unresolved causes, and residual effects honestly. Do not rush to completion because compaction is near.
 
-Include only what the recipient needs to choose or perform the next sound action:
+## Capture The Next Useful Continuation
 
-- goal, accepted outcome, and owning sources;
-- current state and Workflow route, when one exists;
-- completed work and what fresh evidence supports or does not support;
-- relevant worktree, process, environment, or artifact identity needed to prevent loss or false claims;
-- active decisions and the source that established them;
-- invalidated assumptions, deviations, and affected Spec or Plan sections;
-- unresolved owner decisions, missing evidence, blockers, and stop conditions;
-- next accepted action with its authority source, or the recommended next route when not yet approved;
-- exact pointers the recipient must reopen.
+Include only material information:
 
-A Plan preserves stable strategy. Record live progress and deviations in the Working Record, then point to both rather than copying evolving state into the handoff.
+- the intended outcome, agreed scope, user-facing return condition, and defining sources;
+- current task/Slice and Workflow route when present;
+- completed and partial work, supporting evidence, and what remains unverified;
+- relevant repository, worktree, artifact, configuration, or process identity;
+- accepted decisions and their sources, later amendments, and remaining hypotheses;
+- changed assumptions, consequential rejected approaches, and affected Spec or Plan sections;
+- dependencies for remaining work and which are established versus unresolved;
+- the next accepted action and the minimum sources needed for it, or a recommendation awaiting authority;
+- blockers, selected checkpoints, and conditions requiring return rather than continuation.
 
-For a learning slice, preserve the question, evidence, and discard, revise, or promote result. Exploratory output does not become production behavior through transfer.
+Point to the current Working Record and accepted artifacts instead of duplicating their full contents. A Plan preserves strategy; the record preserves actual work and deviations. The handoff preserves transfer-specific context, not a second mutable task narrative.
 
-For review continuity, preserve the review number, reviewed state identity, reviewer judgment, adjudicated judgment, active-agent item adjudication, material Accepted or Open items, changed state, and whether follow-up review remains selected. A new context or reviewer does not reset the review budget.
+For learning, preserve the question, evidence and limits, the discard/revise/promote/inconclusive result, exploratory-artifact disposition, and consequence for dependent work. A recorded promotion does not grant production authority.
 
-## Keep It Compact And Safe
+For selected independent review, preserve review number, reviewed state, reviewer and adjudicated judgments, material Accepted or Open findings, changed areas, and whether follow-up remains selected. A new context or reviewer does not reset the budget.
 
-Link to live sources instead of copying Specs, Plans, Working Records, diffs, logs, transcripts, or full reviewer output. Include a narrow dirty-state list only when omission risks loss, overwrite, duplicate work, or a false completion claim.
+## Preserve Scope And Evidence
 
-Do not include:
+A newer summary is not necessarily a newer accepted decision. Distinguish source-backed changes from proposals; do not let "next" turn an optional follow-up into an obligation or carry a stronger claim than the evidence supports.
 
-- unsupported completion, verification, review, commit, integration, release, or launch claims;
-- volatile inventories or background that does not change continuation;
-- secrets, credentials, tokens, unrestricted personal data, or unnecessary private payloads;
-- instructions to trust the handoff without reinspection;
-- unapproved work presented as the next executable action.
+Include narrow dirty-state or process details when omission could cause loss, overwrite, duplicate execution, or false completion. Keep check outputs linked to the code/artifact and observer state they examined using available identities or source pointers. Distinguish an actual prior observation from whether it still applies after later changes. A missing output is unavailable evidence, not a reason to invent or automatically repeat the run. Do not copy full diffs, logs, transcripts, or reviewer reports when exact recoverable pointers suffice.
 
-Stop when safe transfer would require inventing intent, authority, evidence, destination, or status. Use [Decision Gate](../decision-gate/SKILL.md) when the remaining choice belongs to the user.
+Exclude secrets, credentials, unrestricted personal data, and private payloads unnecessary for continuation. Do not promise access to unavailable sources or reconstruct their exact content from memory.
 
-## Boundary Examples
+If safe transfer would require inventing intent, approval, evidence, status, or destination, state the missing information. Use [Decision Gate](../decision-gate/SKILL.md) when resolving it needs one user-owned choice.
 
-- A Working Record already contains current state → reference it and add only transfer-specific context.
-- Compaction is immediate and the host can carry context → return an ephemeral handoff; do not create repository documentation.
-- Durable repo continuation is approved → use the established handoff location and stable source pointers.
-- The handoff conflicts with live code or evidence → live evidence wins; return the conflict to Workflow.
+## Reconstruct Before Resuming
 
-## Resume Safely
+Follow current core and capability recovery guidance before task action. A handoff's earlier route or profile description is not current runtime state.
 
-When resuming:
+1. Read the complete Working Record through `view full` when resuming after context loss or into another context. Do not substitute its `resume` view or the handoff's summary. With intact context, follow Track Work's bounded in-session read guidance.
+2. Reconcile the record and handoff with current user direction, defining sources, and the relevant live environment. Follow supersession and corrections without silently reviving historical decisions.
+3. Check important completion, verification, review, commit, and artifact-identity claims against their evidence before repeating them. Reuse adequate current evidence; a transfer alone does not require rerunning every check.
+4. Establish the actual partial state, remaining dependencies, accepted work agreement, current assignment, and next useful action. Resolve contradictory old/new instructions from their sources before acting; do not resume editing when the current unit permits inspection only. Reopen only additional sources whose exact content or freshness changes that action.
+5. Return the recovered state to [Workflow](../workflow/SKILL.md) for the supported route and authority check. Continue covered work through its owner; stop for a genuine blocker or uncovered choice.
 
-1. Reopen the named source truth, the Working Record's bounded `resume` view when present, and current worktree state.
-2. Retrieve exact Working Record entities only when needed, then verify important completion, evidence, review, commit, and artifact-identity claims before repeating them.
-3. Compare the recorded route, decisions, and assumptions with live evidence.
-4. Preserve what still holds and identify only the invalidated layer.
-5. Return the live state and supported next action to [Workflow](../workflow/SKILL.md).
+Without a Working Record, use the available transfer and exact sources to reconstruct enough state; report any missing boundary rather than inventing it. If a required full-record read is incomplete or unavailable, follow Track Work's stop condition instead of claiming recovery succeeded.
 
-Do not edit merely because the handoff names a next action. Workflow confirms the route and authority; Execute Work establishes any next slice.
+Do not edit merely because a handoff names a next action. Do not restart the whole task or ask for another "continue" solely because an already-authorized task crossed a context boundary. Slice selection and lifecycle remain with Workflow and Track Work, not the handoff.
 
 ## Report And Stop
 
-State the transfer shape and destination, evidence and sources preserved, current route, next accepted action and authority or recommended route, and material gaps or intentionally omitted sensitive context.
+Report the transfer shape and destination, sources preserved, actual state and evidence limits, next accepted action or pending recommendation, and material missing or intentionally omitted sensitive information.
 
-At a selected pause or transfer boundary, stop after delivering the handoff. Creating continuity memory by itself does not complete, block, abandon, or supersede the active slice or task.
+At the selected pause or transfer boundary, stop after delivering the handoff. It does not complete, block, abandon, or supersede the task or Slice. On recovery, end Handoff once the next owner can continue with coherent scope, authority, and evidence.

package/skills/handoff/references/handoff-templates.md

@@ -15,6 +15,8 @@ Generated: <optional reliable date or time>
 Recipient / purpose:
 
 ## Goal And Owning Sources
+- Agreed outcome and scope:
+- User-facing return condition:
 
 ## Current State
 - Workflow route:
@@ -43,6 +45,8 @@ Recipient / purpose:
 ## Next Action
 - Accepted action:
 - Authority source:
+- Required dependencies and whether they hold:
+- Sources needed for this action:
 
 Or, when not approved:
 - Recommended route:
@@ -51,7 +55,7 @@ Or, when not approved:
 ## Stop Conditions
 ```
 
-Keep dirty-state details narrow. Include only paths, processes, environments, or artifacts whose omission risks loss, overwrite, duplicate work, or a false claim.
+Keep dirty-state details narrow. Include only paths, processes, environments, or artifacts whose omission risks loss, overwrite, duplicate work, or a false claim. In Current State, preserve the current assignment and source when older instructions could compete. In Completed Work And Evidence, distinguish the state actually checked from later changes whose verification remains unresolved.
 
 ## Repo-Memory Handoff
 
@@ -64,6 +68,8 @@ Generated: <optional reliable date or time>
 Recipient / purpose:
 
 ## Goal And Accepted Outcome
+- Agreed scope and exclusions:
+- User-facing return condition:
 
 ## Owning Sources
 
@@ -84,6 +90,8 @@ Recipient / purpose:
 ## Next Accepted Action
 - Action:
 - Authority source:
+- Required dependencies and whether they hold:
+- Sources needed for this action:
 
 Or:
 
@@ -132,10 +140,11 @@ Do not copy full reviewer output when a stable pointer exists. A new context or
 
 ## Resume Checklist
 
-- Reopen named source truth, the Working Record when present, and live worktree state.
+- After context loss or transfer into another context, read the complete Working Record through `view full` when one exists. A summary or `resume` projection is not a substitute. Use Track Work's bounded reads for intact-session continuation.
+- Reconcile the record and handoff with current user direction and relevant live state; reopen named source truth where exact meaning or freshness matters.
 - Confirm artifact, environment, commit, and configuration identity where claims depend on them.
-- Verify important completion and evidence claims before repeating them.
-- Compare decisions, approval scope, review state, and the proposed route with live evidence.
-- Preserve valid context and identify only the invalidated layer.
-- Return the supported route and authority state to Workflow before editing.
+- Check important completion and evidence claims before repeating them; distinguish that a run occurred from whether it applies to the current candidate. Reuse adequate evidence rather than rerun every check merely because a transfer occurred.
+- Compare the execution agreement, current assignment and its source, return condition, decisions, dependencies, and review state with the next proposed action. Resolve superseded or conflicting directions before acting.
+- Preserve valid and partial work; identify only the invalidated layer. Missing or incomplete recovery remains a reported limit.
+- Return the supported route and authority state to Workflow before editing; do not require another user turn merely to continue an already-covered task.
 - Use Decision Gate for user-owned choices or source conflicts.