@hassangameryt/freeflow 0.5.0 → 0.7.0

package/skills/tdd/SKILL.md

@@ -1,96 +1,143 @@
 ---
 name: tdd
-description: Use when implementing or changing behavior test-first, fixing a bug with regression evidence, protecting behavior during refactoring, or when a test is difficult to write or starts shaping production design.
+description: Use when implementing or changing settled behavior test-first, reproducing a bug through regression evidence, or protecting existing behavior before a refactor.
 ---
 
 # Test-Driven Development
 
-Use one observed failing behavior check to guide the smallest complete implementation for one accepted behavior.
+Use one observed failing behavior check to guide the smallest complete implementation for one settled behavior.
 
-TDD is an execution method inside [Execute Work](../execute-work/SKILL.md). One vertical RED/GREEN/REFACTOR loop is a bounded action, not automatically a Track Work slice. Several accepted behavior loops may remain inside one coherent current slice.
+TDD provides test-first behavior discipline. It does not define intended behavior, authorize test or production effects, select or close a Slice, or prove claims beyond its observing boundary.
 
-TDD does not define intended behavior. The accepted request, source truth, and user decisions establish what should happen.
+One behavior loop is one coherent method result. It may contain several reads, edits, commands, and focused checks. Finish and return one behavior before starting another.
+
+## Enter With Settled Behavior
+
+Before RED, establish:
+
+- the accepted behavior and caller-visible result;
+- relevant success and failure semantics;
+- the boundary where the behavior must hold;
+- authority covering both the check and production effects;
+- the expected reason RED should fail.
+
+Return unsettled behavior, source conflicts, or user-owned choices to [Workflow](../workflow/SKILL.md). Do not encode a guess as a test.
+
+Use TDD for:
+
+- accepted behavior changes;
+- bug corrections with a supported cause or reliable regression loop;
+- consequential logic whose contract benefits from executable evidence;
+- characterization needed before a protected refactor.
+
+Do not force TDD onto documentation, static content, formatting, generated output, or a disposable prototype that is not selected production behavior.
+
+When a bug lacks a supported cause or reliable reproduction, use [Diagnose Failure](../diagnose-failure/SKILL.md) before selecting a production correction.
+
+## Design The Behavior Check
+
+Before designing or materially changing the check, read [Test Design](references/test-design.md).
+
+Name:
+
+- the behavior concept;
+- the stable caller-visible seam;
+- an oracle independent from the implementation;
+- the expected missing behavior RED should expose;
+- the focused and affected boundaries that must be rerun after GREEN.
+
+Use the smallest test environment that still exercises the real behavior and relevant failure path. Do not choose a smaller boundary that mocks away the claim or a larger one that adds noise without proving more.
+
+Keep one behavior concept per loop. Several assertions are appropriate when they jointly describe one outcome.
 
 ## Follow The Behavior Loop
 
 ```text
-[Accepted behavior with settled expectation]
+[Settled accepted behavior]
 -> [Choose stable seam and independent oracle]
 -> [RED: write and run the smallest behavior check]
-   -> fails for expected missing behavior -> GREEN
-   -> passes immediately -> inspect test, boundary, or existing behavior
-   -> errors for unrelated reason -> correct harness or diagnose
--> [GREEN: smallest complete implementation]
--> [Verify focused behavior]
--> [REFACTOR when useful, without behavior change]
--> [Verify original path and affected boundary]
--> [Route]
-   -> another accepted behavior in this slice -> next TDD loop
-   -> coherent extension -> approve and record when needed
-   -> unclear cause or structural pressure -> Workflow
-   -> supported bounded action -> return to Execute Work
+   -> fails for the intended missing behavior -> GREEN
+   -> passes immediately -> inspect test, boundary, and existing behavior
+   -> errors or fails elsewhere -> correct the harness or diagnose
+-> [GREEN: implement the smallest complete behavior]
+-> [Run the focused behavior check]
+-> [REFACTOR locally when useful]
+-> [Rerun the original path and affected boundary]
+-> [Return the method result and evidence]
 ```
 
-Do not write all tests first and all implementation later. Finish, verify, and route one accepted behavior before starting another.
+Do not write all tests first and implementation later. Finish one behavior loop before another.
 
-## Use Or Exit Deliberately
+## Observe Valid RED
 
-Use TDD for accepted behavior changes, bug fixes with a supported cause, consequential logic, and refactors whose behavior needs protection.
+Run RED before changing production behavior.
 
-Do not force test-first work onto documentation, static content, mechanical formatting, generated output, or a disposable learning prototype whose result is not selected production behavior.
+RED is valid only when:
 
-Stop before RED when expected behavior, failure semantics, or a public contract is unsettled. Return the missing direction to [Workflow](../workflow/SKILL.md) rather than encoding a guess as a test.
+- the check executes through the intended seam;
+- its assertion represents accepted behavior;
+- it fails because the behavior is missing or incorrect;
+- unrelated syntax, setup, environment, or fixture failures do not explain it.
 
-## Choose The Seam And Oracle
+If the check passes immediately, inspect whether:
 
-Test observable behavior through the highest stable interface that exercises the real requirement.
+- the behavior already exists;
+- the assertion is ineffective;
+- the observing boundary is wrong;
+- the test is reproducing a nearby path rather than the reported behavior.
 
-A useful seam:
+Do not proceed automatically to GREEN.
 
-- is used by callers rather than created only for tests;
-- survives internal refactoring;
-- reaches the real behavior or failure path;
-- keeps setup proportionate;
-- can disagree with the implementation.
+Correct a clear local harness defect. When the failure remains unexplained or repeated harness changes do not establish valid RED, return to Diagnose Failure.
 
-Derive expected results from source truth, a worked example, protocol contract, or independent calculation—not the implementation algorithm.
+## Implement Complete GREEN
 
-Read [Test Design](references/test-design.md) when the test level, oracle, double, rejected state, composed failure, time or concurrency boundary, or legacy seam is unclear.
+Before changing production code, read [Code Practices](../execute-work/references/code-practices.md).
 
-If testing requires owned internals, duplicated caller choreography, or production hooks used only by tests, return the evidence to Workflow. Use [Design for Depth](../design-for-depth/SKILL.md) only when it establishes design-bearing interface or ownership pressure; do not redesign merely because one test is inconvenient.
+Implement the smallest complete behavior that satisfies the accepted contract—not merely the visible assertion.
 
-## Enforce The Test-First Evidence
+Do not:
 
-- Observe RED failing for the intended missing behavior before changing production code.
-- If RED passes immediately, inspect the test, observing boundary, and existing behavior; do not proceed to GREEN automatically.
-- If RED fails because of syntax, setup, environment, or unrelated behavior, correct the harness or diagnose before implementation.
-- Implement the smallest complete GREEN behavior. Read [Code Practices](../execute-work/references/code-practices.md) while changing code.
-- Refactor only when it improves the result while the focused behavior check remains green.
-- Re-run the original path and smallest affected boundary before returning the supported action and evidence to Execute Work.
-- Do not claim TDD when the check was written after implementation or RED was never observed for the intended reason.
+- weaken or rewrite a valid test to obtain GREEN;
+- calculate expected values through production logic;
+- add public hooks, states, flags, or branches used only by tests;
+- silently invent fallback, retry, recovery, or edge-case behavior;
+- broaden implementation into another accepted behavior.
 
-## Keep Tests About Accepted Behavior
+If GREEN requires an unsettled behavior, public contract, subsystem, or material scope expansion, return the evidence to Workflow.
 
-Prefer observable outcomes over internal call sequences, real implementations before doubles, independent expected values, descriptive domain names, and one behavior concept per test.
+## Refactor Locally
 
-Use fakes, stubs, mocks, or spies only at a boundary where replacement is necessary and the double preserves the fields, effects, invariants, and failure behavior the test needs.
+Refactor only when it improves the behavior just implemented while its focused check remains green.
 
-Do not copy the implementation into the expected value, add production methods used only by tests, change a valid test merely to make implementation pass, or treat coverage and test count as proof.
+TDD refactoring is immediate local cleanup within the behavior loop. It may improve names, remove nearby duplication, simplify control flow, or clarify ownership without changing the accepted result.
 
-Add an edge-case check only when accepted behavior, observed failure, material safety, or a settled failure contract requires it. If behavior is undefined, return it to Workflow. When related cases keep adding states, flags, setup, or patches, stop the behavior-loop stream and diagnose the shared contract, cause, ownership, or interface.
+Do not turn REFACTOR into a general cleanup stream. When reducing existing complexity is itself an accepted result, return the completed behavior loop and use [Simplify Code](../simplify-code/SKILL.md) as a separate execution route.
+
+When test pressure exposes caller coordination, public states, test-only seams, or ownership problems, preserve that evidence. Use [Design for Depth](../design-for-depth/SKILL.md) only when structural pressure is supported.
 
 ## Fix Bugs Through The Reported Boundary
 
-First reproduce the reported symptom through the correct seam. A nearby failing path is not the bug.
+First reproduce the reported symptom through the correct seam. A nearby failing path is diagnostic evidence, not the bug.
+
+After GREEN, rerun:
 
-If no reliable diagnostic loop or supported cause exists, use [Diagnose Failure](../diagnose-failure/SKILL.md) before selecting a production correction. After RED and GREEN, rerun both the minimized regression check and the original unminimized symptom or strongest available observer.
+1. the minimized regression check;
+2. the original unminimized symptom or strongest available observer;
+3. the smallest affected boundary capable of exposing regression.
 
-## Stop When Tests Start Designing The System
+Do not report a fix when only the minimized check passes and the reported boundary remains unavailable.
 
-Return evidence to Workflow when test setup grows faster than behavior coverage, each case requires another public state or fallback, tests protect machinery introduced by earlier patches, the next check requires an unplanned subsystem, or making it pass expands accepted scope.
+## Return The Method Result
 
-A green local loop does not prove the global design is right. Diagnose repeated or unexplained failure before redesigning.
+Return to the current owner with:
 
-## Report
+- accepted behavior and observing seam;
+- observed RED result and why it was valid;
+- GREEN implementation result;
+- local refactor, when performed;
+- focused, original-path, and affected-boundary evidence;
+- what the evidence supports and does not support;
+- unresolved or unverified behavior.
 
-Report the accepted behavior and seam, observed RED result, GREEN implementation, refactor if any, original-path and broader verification, current slice effect, and remaining unverified behavior. Return route-changing evidence rather than silently beginning another behavior or slice.
+Do not select another behavior, close the Slice, trigger review, commit, or continue merely because GREEN was reached.

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

@@ -1,8 +1,8 @@
 # Test Design
 
-Read this when the right test level is unclear, a dependency needs a double, legacy behavior lacks a seam, or test setup starts driving production design.
+Read this before designing or materially changing a TDD behavior check. Use it to choose the test level, seam, oracle, failure coverage, doubles, time or concurrency boundary, and characterization strategy.
 
-The goal is confidence in accepted behavior, not maximal isolation or a fixed unit/integration/end-to-end ratio. One TDD behavior loop is a bounded action and may remain inside a larger coherent Track Work slice.
+The goal is confidence in accepted behavior, not maximal isolation or a fixed unit/integration/end-to-end ratio.
 
 ## Choose The Confidence Boundary
 
@@ -13,7 +13,7 @@ Start from the highest stable interface used by callers, then choose the smalles
 - **End-to-end or user-path check:** the requirement is a critical flow whose value depends on the assembled system.
 - **Characterization test:** existing behavior must be observed and protected before a behavior-preserving refactor.
 
-A characterization test records current behavior; it does not make that behavior desired or authoritative. Stop when intended behavior conflicts with source truth or remains user-owned.
+A characterization test records current behavior; it does not make that behavior desired or authoritative. When characterization supports Simplify Code, protect only behavior that accepted source truth requires or that must remain unchanged for the selected simplification. Stop when intended behavior conflicts with source truth or remains user-owned.
 
 A smaller environment is not better when it mocks away the behavior being claimed. A larger environment is not better when its extra machinery adds noise without proving more.
 

package/skills/track-work/SKILL.md

@@ -1,84 +1,221 @@
 ---
 name: track-work
-description: Use when deciding whether proposed or ongoing work needs a durable Working Record, or when creating, resuming, or updating one to preserve task state across execution, pauses, or context loss.
+description: Use when ongoing work needs durable task memory, or when creating, recovering, maintaining, transitioning, or closing a Working Record.
 ---
 
 # Track Work
 
-Decide whether proposed or ongoing work needs a durable Working Record, then maintain selected records without turning them into a transcript, fixed Plan, or authority over live evidence and user decisions. Deciding or reading an existing record is read-only; create or update one only when the effective mode permits mutation.
+Maintain one compact Working Record as the current projection of a task. It is memory, not authority, source truth, a Spec, a Plan, or a transcript. Current user direction, accepted artifacts, live evidence, and repository instructions override stale record content.
 
-Use this route to decide whether to wait, return to Workflow, or continue through [Execute Work](../execute-work/SKILL.md):
+## Track Only When Continuity Matters
+
+Use a record when losing current understanding, accepted decisions, future obligations, one active outcome, evidence, or the next useful action could misalign later work. Do not create one for a short disposable result merely because work occurred.
+
+Use one ignored record per task:
 
 ```text
-[Proposed or ongoing work]
--> existing Working Record owns it
-   -> read the required reference
-   -> maintain it
-   -> select an authorized slice and route to Execute Work, or wait
--> no existing Working Record
-   -> would losing context, decisions, evidence, or the next action risk misalignment?
-      -> no
-         -> authorized work in a mutation-permitting mode -> Execute Work
-         -> otherwise -> Workflow or wait
-      -> yes, but a record is unapproved
-         -> recommend a Working Record
-         -> wait
-      -> yes, and a record is approved
-         -> mode permits durable mutation
-            -> read the required reference
-            -> create the record
-            -> first slice already requested or approved
-               -> select the slice
-               -> Execute Work
-            -> only record creation was approved
-               -> Current Slice: None
-               -> wait
-         -> mode does not permit durable mutation
-            -> recommend the required mode change
-            -> wait
+.freeflow/tasks/task-NNN-<short-name>/record.md
 ```
 
-## Read The Required Reference
+[Workflow](../workflow/SKILL.md) establishes record need, authority, ownership, and the route that receives the result. Use [Discuss](../discuss/SKILL.md) when intent, assumptions, alternatives, or task ownership are materially open. Track Work preserves accepted state and returns to that owning activity; it does not take over discussion.
+
+Only the user changes task state. Creating or updating a record never authorizes implementation, evidence generation, commit, publication, deployment, or another controlled action.
+
+## Keep Five Canonical Sections
+
+Keep the record in this order:
+
+1. **Current Context** — concise present understanding.
+2. **Current Work** — one Current Slice or none, plus one next useful action.
+3. **Future Work** — one ordered sequence of Slices and Checkpoints not yet in History.
+4. **History** — Decisions, Checkpoints, and settled Slices, in that order.
+5. **Notes** — inert retained context.
+
+Current Context and Notes remain ordinary Markdown prose and bullets. Structured entities in Current Work, Future Work, and History use compact field-list rows: one value stays inline as `- Field: value`, while multiple values use nested two-space-indented bullets. This changes presentation only; the Schema 4 sections, fields, IDs, states, and lifecycle semantics remain unchanged.
+
+Read [Working Record Format](references/working-record-format.md) before directly editing structured record content or preparing Markdown for a lifecycle command. It owns the exact headings, fields, state tables, omission rules, and compact entity layout. Do not invent fields, headings, IDs, or lifecycle states.
+
+## Create Or Recover Honestly
+
+Initialization creates every canonical heading. Start with at least:
+
+- the task state;
+- a supported Goal;
+- any defining source or material Open question already known;
+- `Current Slice: None`;
+- one next useful action or an honest wait condition.
+
+If the task is too unclear to state a Goal and next action without invention, discuss it before initialization.
+
+The header’s `Last updated` is created by `init` and refreshed by successful lifecycle commands. Direct Markdown edits may leave it stale; it is advisory recency metadata, not proof of validity, freshness, authority, or semantic truth.
+
+Use `resume` after context loss, compaction, session navigation, handoff, an intentional pause, or uncertain continuity. Do not reload it merely because another conversational turn began. Compare the recovered projection with current user direction and the live environment, then reconcile only affected state.
+
+## Reconstruct State Before Action
+
+Before any consequential action, especially after recovery, confirm:
+
+- task State;
+- Current Slice and its state;
+- active Decisions;
+- pending or deferred Checkpoints;
+- the Next useful action;
+- applicable authority, scope, and stop condition;
+- unresolved Evidence or contradictions.
+
+Reconcile the projection from the Working Record, selected exact History, accepted artifacts under `What defines this task`, the live environment, and current human intent and authority. Retrieve only the exact historical block needed for rationale, chronology, supersession, lineage, or Evidence. Do not act from the Working Record alone.
+
+A record from another conversation branch remains memory. It does not transfer branch-local authority. If the record does not use the supported schema, inspect it through `full` and stop before direct edits or lifecycle transitions; migration is a separate explicit operation.
+
+Before an expected compaction, clear, session pause, or handoff, reconcile the record only when material task state changed. The context boundary itself is not a History event, Evidence item, or Checkpoint.
+
+## Keep Current Context Small And Current
+
+Use concise bullets under exactly seven headings:
+
+- Goal
+- What defines this task
+- Settled
+- Tentative
+- Open
+- Current direction
+- Boundaries
+
+`Settled` contains supported present understanding, not duplicate Decision history. `What defines this task` points to accepted artifacts, user decisions, constraints, and source truth that determine interpretation.
+
+Change Context only when its present meaning changes. Do not rewrite it after every Slice, Checkpoint, test, review, or ordinary transition. Add, edit, move, or remove only the affected bullet. Completed-event detail belongs with its Slice; accepted choice and rationale belong to a Decision.
+
+## Edit Content Directly; Script Lifecycles
+
+Use ordinary Markdown reads and edits for content that requires judgment:
+
+- Current Context bullets;
+- allowed wording and optional fields inside Future Work or the Current Slice;
+- proposed-item order or removal;
+- the next useful action;
+- Material updates;
+- Notes;
+- clerical correction of active prose;
+- the defined clerical correction block in terminal History.
+
+A direct edit may change allowed content inside a block. It must not change the block’s durable ID, lifecycle state, entity kind, or owning top-level section. Do not delete or reactivate terminal History or erase its prior value; append a defined correction instead.
+
+Prose-only bullet edits need no extra validation. After editing headings, fields, references, or other structured blocks, run `validate` before consequential work; every lifecycle command validates its source and candidate.
+
+Use a deterministic lifecycle command when an operation creates structured identity or changes lifecycle state:
+
+- initialize the record;
+- propose a Slice or Checkpoint;
+- start, pause, resume, close, or reopen a Slice;
+- activate, defer, resume, or close a Checkpoint;
+- add, supersede, or retire a Decision;
+- change task state.
+
+Commands own placement, ID allocation, legal state transitions, complete multi-block movement, and the script-maintained `Last updated` field. The agent owns meaning and supplies the content. Slice and task-state transitions also require agent-supplied Next useful action text; Checkpoint transitions may update it when supplied. Use [working-record.mjs](scripts/working-record.mjs) directly for the lifecycle boundary. Read the format reference first, then run the complete operation help—`working-record.mjs <group> <operation> --help`—before preparing a fragment; use `--input -` when supplying agent-authored Markdown through stdin. `validate --record` checks the stored Schema 4 record after structured direct edits. Do not inspect the implementation source under `scripts/lib/` unless diagnosing a concrete defect.
+
+A lifecycle command must validate the source and candidate before publication and apply one complete transition or none. If its result is uncertain, stop and re-read `full` before retrying or editing related state.
 
-Before creating, resuming, or updating a Working Record, read the complete [Working Record method and schema](references/working-record-schema.md). This skill and its reference form one method. Do not invent fields, states, or transitions from memory; if the reference is unavailable, do not mutate the record.
+## Keep One Coherent Slice
 
-## Core Contract
+A Slice is one coherent learning, delivery, or deepening outcome. Keep implementation, verification, review, accepted correction, and associated Checkpoints inside the same Slice while its intended result, authority boundary, evidence boundary, and independently useful outcome remain coherent.
 
-- A record preserves current context, one current slice, revisable proposals, durable history, inert Notes, and one next useful action. It is memory; live evidence and user decisions win.
-- `Current understanding` is a present-state summary, not a running task summary or compressed transcript. Replace superseded prose instead of appending completed events.
-- Give detailed facts one schema-owned home. Other sections summarize or point to that owner rather than repeating findings, hashes, commands, or test inventories.
-- Only the user changes task state. Do not infer `Paused`, `Completed`, `Abandoned`, or renewed `Active` state from inactivity, apparent completion, or failure.
-- A **slice** is one bounded piece of learning, delivery, or structural improvement. One slice may span multiple iterations of [Workflow's](../workflow/SKILL.md) Feedback Loop and calls to other owning skills.
-- Record state changes, not every edit or conversation. Apply authorized in-scope steering and reconcile its meaningful final effect when the slice closes.
-- Before work changes the recorded result, scope, authority, evidence boundary, or stop conditions, decide and record whether it extends the current slice or requires a new one.
-- Questions, criticism, and review findings do not authorize changes. Ordinary in-slice feedback is not a checkpoint or history event merely because work pauses for the user.
-- Workflow establishes slice outcomes. Implementation, verification, self-review, or a review report does not end a slice by itself, and review need not Pass.
-- The record may preserve authority sources, decisions, checkpoints, and evidence; it never creates authority or proof.
+Use a new Slice when any of those boundaries materially changes. Do not split ordinary implementation stages, tests, reviews, or corrections into separate Slices.
 
-## Follow The Lifecycle
+A proposed Slice has no durable ID or authority. Its title must be unique across Future Work. It may be edited, reordered, or removed until selected.
 
-After reading the required reference:
+When an immediately authorized outcome does not need Future Work ordering or recovery, use `slice start-direct`. It creates a new Current Slice without consuming or changing any Future Work item. Never silently treat a direct start as proposal selection.
+
+Starting requires current authority and creates one detailed Current Slice with a new `S-NNN` ID before execution. Do not begin Slice work until that start transition has successfully persisted and validated the Current Slice and Next useful action. After a successful start or reopen, return the bounded result to [Execute Work](../execute-work/SKILL.md); the transition itself is not implementation authority.
+
+```text
+Future proposed
+-> Current in_progress
+<-> Current paused
+-> History completed | blocked | abandoned
+```
+
+- `in_progress` means the selected outcome is actively being pursued.
+- `paused` means the outcome remains current but safe continuation is suspended. Ordinary feedback or a turn boundary is not a pause.
+- Historical `blocked` means the unresolved paused attempt deliberately left Current Work.
+- Historical `completed` means the intended result and required evidence boundary were settled.
+- Historical `abandoned` means the outcome is no longer pursued under explicit authority.
+- Close as historical `blocked` only from a paused Current Slice; close as `abandoned` only with explicit authority and a reason; close as `completed` only after required Evidence and applicable Checkpoints are settled.
+
+Append a Material update only when safe continuation or truthful closure would otherwise lose a material change. Use concise labeled bullets for Evidence, pauses and resumptions, accepted extensions, contradictions, review outcomes, or corrections. Routine commands, edits, tests, and conversation turns are not record events.
+
+Record an accepted extension before expanded work begins. Preserve its authority, added scope, added evidence boundary, and changed stop condition when applicable. Questions, criticism, findings, and useful suggestions do not authorize an extension.
+
+A Slice cannot close while a `pending` or `deferred` Checkpoint applies to it. Resolve the Checkpoint first. Closure compacts the active declaration and Material updates into one historical Slice; it does not copy the active block wholesale.
+
+Before closing as `completed`, establish that every material completion claim has supporting Evidence at its required boundary, the live state does not contradict the result, no authority conflict remains, and no material contradiction is unresolved. A Learning Slice may complete by disproving its hypothesis when its question and Evidence boundary are settled. The command can enforce structure, not semantic truth.
+
+Closing never selects or starts another Future Work item. After closure, Current Slice is `None` until another outcome is explicitly selected.
+
+To continue a historical `completed` or `blocked` Slice, create a new Current Slice with a new ID and `Reopened from: S-old`. Supply fresh authority, scope, expected evidence, stop condition, and starting state. Leave the historical entry unchanged. Resuming returns a Current paused Slice to `in_progress`; reopening creates a linked Slice from History.
+
+## Keep Checkpoints Prospective Until Terminal
+
+Every Checkpoint belongs to one Slice. Its title must be unique across Future Work.
+
+```text
+proposed -> pending <-> deferred
+pending | deferred -> completed | cancelled | replaced
+```
+
+- `proposed` is a candidate with no authority or durable ID.
+- `pending` is an accepted unresolved boundary that dependent work must not cross.
+- `deferred` remains accepted but dormant until its recorded condition.
+- `completed` means the boundary occurred; its result may still be adverse or blocking.
+- `cancelled` means it is no longer required.
+- `replaced` names the pending Checkpoint that takes its place.
+
+A proposed Checkpoint may be removed without History. Activate it only when the boundary is explicitly selected or authorized; a proposal or recommendation is not acceptance. Activation assigns `C-NNN`. When its proposed Slice starts, the same transition replaces the exact proposed-title reference with the new `S-NNN`. An accepted Checkpoint leaves Future Work only through a lifecycle command and remains there until terminal.
+
+## Preserve Decisions Without Rewriting Their Meaning
+
+Decisions live under History and receive `D-NNN` when added:
+
+```text
+active -> superseded | retired
+```
+
+A clerical clarification may edit an active Decision directly without changing its meaning. A material change creates a new Decision and supersedes the old one. A superseded Decision names its replacement; a retired Decision records why it no longer governs. Terminal Decisions are not reactivated. Adopting an old choice again creates a new active Decision.
+
+## Keep Evidence And Blockers With Their Slice
+
+Do not create global Evidence or Blocker sections. A material Evidence update states the claim, observing boundary, result, what it proves and does not prove, and a real pointer when available. Later contradictory Evidence is appended rather than silently rewriting the earlier observation.
+
+A pause update states why continuation stopped and what permits resumption. A resume update states the resolution source. At closure, distill the strongest relevant Evidence, proof limits, unresolved blocker, and task effect into the historical Slice.
+
+Evidence supports claims only at its observing boundary. A green check, completed implementation, or review opinion alone does not establish a supported exit. If an attempt fails, is rolled back, or leaves residual effects that change the next decision, preserve that attempt, reason, Evidence, and residual state in Material updates or the historical Slice.
+
+## Change Task State Explicitly
+
+Task states are:
+
+```text
+active <-> paused
+active | paused -> completed | abandoned
+completed | abandoned -> active only by explicit user reopening
+```
 
-1. **Create or resume:** use the established task directory, restore task state after context loss, and orient from live evidence.
-2. **Select or wait:** select a slice only when its concrete work is requested or approved. If only record creation is approved, keep `Current Slice` as `None` and wait. When selected, move one proposal into `Current Slice`, assign its chronological `S-` ID, save the write-ahead state, then route to Execute Work.
-3. **Maintain the slice:** keep small steering out of the event history; record accepted extensions before execution; preserve blockers, review routes, and evidence without replacing a coherent slice.
-4. **Close the slice:** move the Workflow-established outcome to History, preserve the original boundary and accepted extensions, rewrite Current Context from the resulting present state, remove completed-event detail already owned by History, and set `Current Slice` to `None`.
-5. **Preserve what matters:** keep task-local decisions, selected checkpoints, evidence pointers, and Notes in their schema-owned sections.
+Pausing a task pauses its Current Slice first when one exists. Reactivating the task does not automatically resume that Slice. A completed or abandoned task requires Current Slice `None` and no pending or deferred Checkpoint. Proposed Future Work may remain only when it is clearly retained as non-obligating future material; otherwise reconcile or remove it before the terminal transition. Reopening a task does not automatically select work.
 
-## Context Boundaries
+## Keep Notes Inert
 
-Before an expected compaction, summarization, pause, clear, or transfer, reconcile the record only when task state changed. The boundary itself is not a record event.
+Notes have no field schema. Add or edit them directly as ordinary Markdown. Remove a user-authored Note only when the user requests it; remove other Notes only when current maintenance authority clearly covers that correction.
 
-After compaction, summarization, resume, clear, or session navigation, read the complete record before the next task action and compare it with the current conversation and live state. Identify the task from current context or inspect and ask rather than guessing. A record written on another conversation branch is memory, not authority.
+Notes do not authorize, prioritize, schedule, block, unblock, prove, or require follow-up.
 
-## Route Or Stop
+## Read Through Two Views
 
-Use [Discuss](../discuss/SKILL.md) before selecting a slice when a collaborative question could materially change its result, scope, or route.
+- `resume` shows the record header, complete Current Context, active Decisions derived from History, complete Current Work, complete Future Work, and Notes. It omits terminal History.
+- `full` returns the complete canonical Markdown exactly as stored.
 
-Use `Blocked` only when a required decision, dependency, capability, evidence source, stop condition, or other unavailable condition prevents safe continuation. Keep the blocked slice current, record what is needed, then stop. General execution authority does not override a stop condition.
+Both views are direct Markdown text, not JSON. A host may render that Markdown visually. Neither view follows external pointers or mutates the record. When one historical entity is needed, search and read its bounded `S-NNN`, `C-NNN`, or `D-NNN` block instead of loading all History.
 
-When the user requests a separate point-in-time transfer artifact, read [Handoff](../handoff/SKILL.md). Creating a handoff does not replace living Working Record state.
+## Return To The Requesting Activity
 
-## Check The Record
+After maintenance, return to the activity that requested the record operation. Discussion returns to [Discuss](../discuss/SKILL.md) after accepted state is preserved; authorized Slice work returns to [Execute Work](../execute-work/SKILL.md). Point-in-time transfer uses [Handoff](../handoff/SKILL.md). Task-local durable content remains owned by [Write Spec](../write-spec/SKILL.md) and [Write Plan](../write-plan/SKILL.md). Do not continue execution, select Future Work, or treat a recorded proposal, Decision, Checkpoint, or next action as fresh authority merely because it is present.
 
-After every update, silently compare the record with live evidence and the required reference. Correct clear local issues. Remove historical narration from Current Context once its active consequence is captured, and replace duplicated detail with a compact pointer to its owner. Do not create review history or request review merely because the record changed.
+Stop instead of guessing when authority, intended result, scope, evidence, record structure, migration, or a transition is unclear. Track Work ends when the record accurately preserves supported current state and one next useful action. It does not claim implementation, verification, review, commit, release, publication, or task completion on its own.