@hassangameryt/freeflow 0.8.0 → 0.9.0

package/skills/track-work/references/handoff.md

@@ -0,0 +1,190 @@
+# Handoff
+
+This reference is judgment, with the Rules below. A handoff preserves the point-in-time information another context needs to continue the agreed work without restarting discovery or changing its goal.
+
+The Working Record keeps living task state. A handoff identifies that record, the relevant sources, and the 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 recipient resumes through Track Work's [Recover After Context Loss](../SKILL.md#recover-after-context-loss): the handoff points to the record and never replaces it.
+
+## Rules
+
+- When the destination would change durability, privacy, repository state, audience, or authority and the user has not chosen it, ask one question and wait. Never turn an ephemeral transfer into repository memory.
+- If safe transfer would require inventing intent, approval, evidence, status, or destination, state what is missing instead. Use [Discuss Work](../../discuss-work/SKILL.md) when resolving it needs a user-owned choice.
+- Exclude secrets, credentials, unrestricted personal data, and private payloads the continuation does not need. Do not promise access to unavailable sources or reconstruct their exact content from memory.
+- A handoff changes no task or Slice state: it does not complete, block, abandon, or supersede either. Do not create a record merely because a handoff exists.
+
+## Choose The Transfer Boundary
+
+Identify the recipient, purpose, and available transfer mechanism before writing.
+
+- **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.
+
+## Prepare From The Actual State
+
+When a Working Record exists, make it sufficient first ([Prepare For A Context Boundary](../SKILL.md#prepare-for-a-context-boundary)). Then inspect only the relevant worktree, artifacts, processes, and evidence needed to describe what the recipient will encounter.
+
+Preserve the work agreement separately from the immediate assignment: what outcome remains authorized, what this assignment 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 approval to finish the remaining task.
+
+Use the host's safe boundary for ongoing operations; do not infer an unobserved result or interrupt a mutation to make a cleaner handoff. Partial work is a valid transfer state: preserve unverified edits, failing checks, unresolved causes, and residual effects honestly.
+
+## Capture The Next Useful Continuation
+
+Include only material information:
+
+- the intended outcome, agreed scope, user-facing return condition, and defining sources;
+- current task/Slice and 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.
+
+Point to the current Working Record and accepted artifacts instead of duplicating their contents. A Plan preserves strategy; the record preserves actual work and deviations; the handoff preserves transfer-specific context, not a second mutable task narrative.
+
+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.
+
+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 or artifact and observer state they examined. 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.
+
+## Templates
+
+Use only the fields that change safe continuation; a template is not a requirement to create another document.
+
+### Ephemeral Handoff
+
+For the current response, a host continuation mechanism, or a temporary file.
+
+```md
+# Continuation Handoff
+
+Generated: <optional reliable date or time>
+Recipient / purpose:
+
+## Goal And Owning Sources
+- Agreed outcome and scope:
+- User-facing return condition:
+
+## Current State
+- Route:
+- Working Record, Spec, or Plan pointers:
+- Relevant source or artifact identity:
+
+## Completed Work And Evidence
+- Result:
+- Evidence:
+- Supports:
+- Does not support:
+
+## Decisions And Authority
+- Decision:
+- Established by:
+- Scope:
+
+## Deviations Or Invalidated Assumptions
+
+## Worktree, Process, Or Environment Watchouts
+
+## Review Continuity
+
+## Open Decisions, Evidence, Or Blockers
+
+## Next Action
+- Accepted action:
+- Authority source:
+- Required dependencies and whether they hold:
+- Sources needed for this action:
+
+Or, when not approved:
+- Recommended route:
+- Approval or decision needed:
+
+## Stop Conditions
+```
+
+In Current State, preserve the current assignment and its 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
+
+For durable project continuation in the repository's established location.
+
+```md
+# Project Handoff
+
+Generated: <optional reliable date or time>
+Recipient / purpose:
+
+## Goal And Accepted Outcome
+- Agreed scope and exclusions:
+- User-facing return condition:
+
+## Owning Sources
+
+## Stable Context
+
+## Current State And Evidence
+
+## Working Record, Spec, And Plan Pointers
+
+## Decisions, Authority, And Approval Scope
+
+## Deviations, Invalidated Assumptions, Or Superseded Direction
+
+## Review Continuity
+
+## Open Decisions, Evidence Gaps, And Stop Conditions
+
+## Next Accepted Action
+- Action:
+- Authority source:
+- Required dependencies and whether they hold:
+- Sources needed for this action:
+
+Or:
+
+## Recommended Next Route
+- Route:
+- Approval or decision needed:
+```
+
+Do not copy living progress from a Working Record or turn directional Plan content into committed work.
+
+### Learning Addendum
+
+Include when an experiment, prototype, benchmark, or investigation changed the route. A recorded promotion does not grant production authority.
+
+```md
+Question:
+Competing hypotheses or designs:
+Evidence captured:
+Result: discard | revise | promote | inconclusive
+Exploratory artifacts retained:
+Affected Working Record, Spec, Plan, or later work:
+Next accepted action and authority, or recommended route:
+```
+
+### Review-Continuity Addendum
+
+Include only when selected independent review state must survive the transfer. A new context or reviewer continues the existing review budget, as [Review Work](../../review-work/SKILL.md)'s Rules say.
+
+```md
+Review number: 1 | 2 | 3
+Reviewed state identity:
+Reviewer judgment: Pass | Non-blocking | Inconclusive | Blocking
+Adjudicated judgment: Pass | Non-blocking | Inconclusive | Blocking
+Material review items and evidence pointers:
+Active-agent item adjudication:
+- <item>: Accepted | Rejected | Open — <reason>
+Accepted Blocking or Non-blocking Issues:
+Material Open items:
+Changed areas after review:
+Follow-up review status and authority:
+```
+
+Do not copy full reviewer output when a stable pointer exists.
+
+## Report And Stop
+
+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 the selected pause or transfer boundary, stop after delivering the handoff.

package/skills/track-work/references/projects.md

@@ -0,0 +1,51 @@
+# Projects And Child Records
+
+Read this when the work involves a registered task: a task ID such as `my-project/task-003`, a child record, a project, or the user asking to group tasks, split a task across parallel sessions, or move a record out of a repository.
+
+The **Rules** below are binding; everything else is judgment.
+
+## Rules
+
+- Create or link a project, import a record into one, and change a task's directories, only when the user asks, when the user confirms your proposal in a harness dialog, or when the user's auto-approve setting covers that change (Pi Task Memory).
+- Write a record only from the session that owns it. A parent task's record is written by the parent's session; a child's record by the child's session.
+- A child has no children.
+- Remove a task or a project only when the user asks for it to be removed, or confirms your proposal in a harness dialog. Removal moves records to the trash under the Freeflow home; never empty the trash or delete records another way: that is the user's.
+
+## What A Project Is
+
+A project groups related tasks, possibly across several repositories. Its records live in a store under the Freeflow home (`FREEFLOW_HOME`, default `~/.freeflow`), at `projects/<project>/tasks/task-NNN-<short-name>/record.md`, outside any repository, so removing a worktree does not delete them. A registered record is not in the repository's `.freeflow/tasks/`, and that is expected. Each registered task has an ID, `<project>/task-NNN`, and every command that takes `--record` also takes the ID. The registry also records which session owns each record and which task is a child of which.
+
+```text
+working-record.mjs project new --name <name> [--worktrees <dir>]     create; link this repository
+working-record.mjs project link --name <name> [--worktrees <dir>]    link another repository
+working-record.mjs project show [--name <name>]                     a project's tasks (default: this repository's)
+working-record.mjs project list                                      every project
+working-record.mjs task create --title <t> --goal <g> [--parent <id>] a registered task, or a child
+working-record.mjs task fanout --parent <id> --title <t> --goal <g> --agent <cmd>  a child with its own worktree
+working-record.mjs task here                                         the task this directory belongs to
+working-record.mjs task env --id <id>                                where a task's work happens
+working-record.mjs task import --record <record.md> --project <name> move an existing record in
+working-record.mjs task search --query <q> --id <id> --scope task|tree|project
+working-record.mjs task remove --id <id>                             a task and its children, to the trash
+working-record.mjs project remove --name <name>                      a project and its tasks, to the trash
+```
+
+Run each command with `--help` before preparing its input. A record that is not registered keeps working where it is.
+
+## Other Tasks In The Project
+
+Each task keeps its own record. Read another task's record (`view resume --record <id>`, `task search --id <id> --scope project --query <words>`) when it bears on what you are about to decide or build; record what matters to this task in this task's own record, never in the other one.
+
+## Where A Task's Work Happens
+
+A registered task records its primary directory (the repository or worktree where its effects belong) and any additional directories; `task env` shows them with the current Git branch. When a session starts with no task in hand, `task here` names the task the directory belongs to: recover that one. Make the task's changes in its primary directory; work in another directory belongs to another workstream unless the user says otherwise.
+
+## Child Records
+
+Goal: parallel work on one task, each workstream with its own memory, and one writer per record.
+
+A child is a record for one workstream of a task that runs in parallel in another interactive session the user starts. When the child will change files, create it with `task fanout`, which also creates its Git worktree on a branch named for it and copies the repository's personal Freeflow config. Pass `--agent` with the command that starts this host's agent (such as `claude` or `codex`); the output ends with a command for a new terminal. Give the user that command exactly. A child that only reads or researches needs no worktree: use `task create --parent <id>`. Most tasks never need a child. A subagent is not a child: it works inside its session, on that session's task, and needs no record.
+
+After creating a child, record the delegation in the parent's record (for example as a Slice whose result is the child's). Read a child's progress with `view resume --record <child-id>` or `task search --scope tree`; when its result matters to the parent, record it in the parent as you would a finished Slice. The child's own session writes the child's record.
+
+Owners are recorded on every host, but only a harness that gates writes enforces them. Without one, check `project show` before writing a registered record another session owns, and ask the user.

package/skills/track-work/references/working-record-format.md

@@ -1,6 +1,6 @@
 # Working Record Format
 
-This reference owns the exact Schema 4 shape: sections, fields, states, lifecycle transitions, and the command contract. Read it before editing structure or preparing input for a command. It defines format, not what is worth recording; [Track Work](../SKILL.md) owns that judgment.
+This reference owns the exact Schema 4 shape: sections, fields, states, lifecycle transitions, and the command contract. It defines format, not what is worth recording; [Track Work](../SKILL.md) owns that judgment.
 
 ## Task Directory
 
@@ -17,6 +17,8 @@ Each task has one directory:
 
 `NNN` is three or more digits. A new task takes the next number after the highest existing one; numbers are never reused. `specs/`, `plans/`, and `sources/` are created only when needed; `init` creates `scratch/`. Nothing in `scratch/` is part of the record unless the record points to it, and it may be deleted when the task ends. The directory must be ignored by Git and untracked.
 
+A registered task's directory lives in its project's store instead (`<Freeflow home>/projects/<project>/tasks/task-NNN-<short-name>/`, outside any repository; the store is marked by its `store.json`), with the same contents; see [Projects And Child Records](projects.md).
+
 A Spec or Plan may instead live in the repository's own documentation; the record points to it either way.
 
 ## Skeleton
@@ -69,7 +71,7 @@ None
 ## Notes
 ```
 
-The five top-level sections are fixed, in this order: Current Context, Current Work, Future Work, History, Notes. `### Recovery sources` is optional; records created before it existed remain valid without it.
+The five top-level sections are fixed, in this order: Current Context, Current Work, Future Work, History, Notes. `### Recovery sources` is optional; records created before it existed remain valid without it. `### Work agreement` is optional and not in the skeleton: `init` writes it, directly after Goal, only when its input has one.
 
 The header holds the task name, `Schema`, task `State`, and `Last updated`. `init` and every successful lifecycle command set `Last updated`; views, validation, failed commands, and direct edits do not. It records recency only, not validity or truth.
 
@@ -93,17 +95,32 @@ Structured entities use compact field rows:
 
 ## Current Context
 
-Present understanding, as bullets under exactly these seven headings:
+Present understanding, as bullets under these seven headings, plus an optional Work agreement directly after Goal:
 
 | Heading | Holds |
 | --- | --- |
 | Goal | The outcome or central question; not the current mechanism. |
+| Work agreement (optional) | The current work agreement, as far as it is known: what done looks like, what the agent does without asking, what needs the user's yes first, where it comes back, and how long it holds. |
 | What defines this task | Pointers to the artifacts that define the task, such as its Spec, Plan, issue, or user-supplied brief. Every entry is read on each recovery. |
 | Settled | Facts and accepted understanding that still affect the work. |
 | Tentative | Hypotheses and provisional approaches. |
 | Open | Unresolved questions that could change the work. |
 | Current direction | The remaining approach and why; not a history of completed work. |
-| Boundaries | Scope exclusions, constraints, evidence limits, user-facing return conditions, and separately controlled actions. |
+| Boundaries | Scope exclusions, constraints, evidence limits, user-facing return conditions, and separately controlled actions. When the record has a Work agreement, return conditions and separately controlled actions belong there, and Boundaries keeps the rest. |
+
+Start each line with the lead words for the part it states: `Done when`, `Without asking:`, `Ask first:`, `Back`, `Holds until`. Write only the parts that are known; one line is often enough, and `validate` does not check the lead words. Each line that rests on the user's reply quotes it, beside what it answered:
+
+```markdown
+### Work agreement
+
+- Done when the reported bug is fixed and its PR is open.
+- Without asking: fix it, commit on a branch, open the PR. You said "yeah, do that" to that route (2026-10-12).
+- Ask first: merging, anything outside the bug.
+- Back at the PR.
+- Holds until the PR merges.
+```
+
+The heading is never empty: omit it until something is agreed. `validate` rejects it when it is empty or anywhere but directly after Goal.
 
 Keep only pointers under `What defines this task`; accepted choices go in Decisions and constraints in Boundaries. Change Current Context only when present meaning changes; a lifecycle transition alone does not require it. Remove narration once its consequence is recorded elsewhere.
 
@@ -154,10 +171,13 @@ Current Work holds one Current Slice or `None`, optional Recovery sources, and o
 - Resumed — resolution source: ...
 - Blocker — why unsafe: ...; required resolution: ...
 - Contradiction — ...
-- Review — judgment and effect: ...
+- Review gate — mode: auto | off | always; tier: ...; because: <trigger> | no trigger; result: dispatched | proposed | skipped
+- Review — round: R1 | R2 | R3; reviewer: <model> (<family>); judgment: ...; Accepted: <n>; Rejected: <n>; Open: <n>; reviewed: <commit or version>; report: <path>; effect: ...
 - Correction — ...
 ```
 
+A Review entry is written after adjudication, one per independent review, so outcomes and rounds can be counted later; its report and brief live in the task's `scratch/reviews/` (`R1-brief.md`, `R1-report.md`). Self-review writes no Review entry.
+
 An Evidence entry identifies the state it observed well enough to tell it apart from later versions. When later edits leave a result's applicability unresolved, say so rather than carrying the earlier result forward. Append counterevidence as a new entry instead of rewriting the earlier one. A missing output is unavailable evidence, not proof the check never ran. Label a report you did not observe as a report.
 
 When no Slice is current, the section contains the single line `None`.
@@ -217,13 +237,7 @@ A proposed Checkpoint has no ID in its heading (`### Checkpoint — <title>`). R
 
 An accepted Checkpoint leaves Future Work only through `checkpoint close`; never drop one by editing.
 
-| Type | Boundary | Earlier name, still read |
-| --- | --- | --- |
-| `preserve` | Save a recoverable point: commit, draft version, snapshot. | `local_commit` |
-| `publish` | Make work available beyond the workspace: push, pull request, publication, sending. | |
-| `review` | Independent judgment of the work. | `independent_review` |
-| `decision` | A user-owned choice that later work depends on. | `user_decision` |
-| `continuity` | A planned pause, handoff, or transfer. | |
+`Type` is one of the five in Track Work's Checkpoint table: `preserve`, `publish`, `review`, `decision`, `continuity`. Earlier names are still read: `local_commit` as `preserve`, `independent_review` as `review`, `user_decision` as `decision`.
 
 ## History
 
@@ -234,7 +248,7 @@ Three subsections in this order: Decisions, Checkpoints, Slices. History is appe
 ```markdown
 #### D-001 — Keep the Markdown record canonical
 - State: active
-- Decision: record.md remains the canonical task memory.
+- Decision: record.md remains the canonical task record.
 - Established by: The user's accepted direction on 2026-09-25.
 - Rationale: Agents need one readable recovery surface.
 - Consequences: Views project the same file.
@@ -257,7 +271,7 @@ A closed Checkpoint keeps its future fields and adds `Result` and `Task effect`.
 
 A closed Slice keeps `Intended result` and, when present, `Type`, `Authority source`, and `Reopened from`. It adds `Result`, `Evidence and limits`, and `Task effect`. `State` is `completed`, `blocked`, or `abandoned`; `Resume when` is required for blocked and `Reason` for abandoned. `Residual effects` is optional.
 
-Closing does not keep Scope, Stop condition, Starting state, Dependencies, Material updates, or Recovery sources. Anything among them that still matters belongs in `Evidence and limits` or `Task effect` before closing.
+Closing does not keep Scope, Stop condition, Starting state, Dependencies, Material updates, or Recovery sources. Anything among them that still matters belongs in `Evidence and limits` or `Task effect` before closing; Review entries always do, copied whole, so review outcomes stay countable.
 
 | State | Meaning |
 | --- | --- |
@@ -348,14 +362,18 @@ Edit directly:
 
 Never edit directly: IDs, `State` fields, which section an entity is in, or any terminal History entry apart from Corrections. `validate` checks structure only; it cannot detect a hand-made state change or a deleted entry, so those edits are forbidden rather than checked.
 
-After editing headings, fields, or entity structure, run `validate --record <record.md>`. Prose-only edits need no validation.
+After editing headings, fields, or entity structure, run `validate --record <record.md>`. Prose-only edits need no validation. `validate` also lists Material updates pointers (paths from the repository root or the task folder, and commits) that do not resolve, as warnings, since a line may name a planned path or a commit not fetched yet; `--strict` fails on those an Evidence or Result line names. Pointers outside the repository are listed, not checked.
 
 ## Views
 
-Both views are plain Markdown and change nothing.
+Views are plain Markdown and change nothing.
+
+- `view resume` returns the header, Current Context, active Decisions, Current Work, Future Work, a History index, and Notes. The index has one line per closed History entry (superseded and retired Decisions, closed Checkpoints, closed Slices) in record order: ID, state, `by D-NNN` for a superseded Decision, `recorded retroactively` for a `slice record` entry, the title, and `(corrected)` when the entry has Corrections. It is the view to use while the conversation is still in context.
+- `view recover` returns the `resume` view, then each `What defines this task` artifact and Recovery source with its trigger, whether its pointer resolves and its size, then live Git state (branch, HEAD, uncommitted paths, commits since `Last updated`) and where it disagrees with the record: a branch the record names that HEAD is not on, or a commit the Current Slice names that HEAD's history lacks. It is the recovery view after context loss.
+- `view entry <ID> [<ID> ...]` returns the named `S-NNN`, `C-NNN`, or `D-NNN` entries exactly as stored, in the order given. An unknown ID prints nothing and fails.
+- `view full` returns the file exactly as stored. It does not require the record to be valid, so use it to inspect malformed or unsupported records, after an uncertain write, or for an audit.
 
-- `view full` returns the file exactly as stored. It does not require the record to be valid, so use it to inspect malformed or unsupported records.
-- `view resume` returns the header, Current Context, active Decisions, Current Work, Future Work, and Notes. It omits terminal History and is not sufficient after context loss.
+`view resume`, `view recover` and `view entry` require a valid Schema 4 record.
 
 ## Notes
 

package/skills/track-work/scripts/lib/document.mjs

@@ -1,6 +1,7 @@
 import {
   ACTIVE_SLICE_FIELDS,
   CHECKPOINT_TYPES,
+  CONTEXT_HEADINGS,
   CURRENT_SLICE_STATES,
   DECISION_FIELDS,
   DECISION_STATES,
@@ -19,6 +20,7 @@ import {
   SLICE_TYPES,
   TASK_STATES,
   TOP_LEVEL_SECTIONS,
+  WORK_AGREEMENT_HEADING,
   isCalendarDate,
   joinLines,
   nextId,
@@ -255,24 +257,20 @@ function parseTopLevelSections(lines) {
   );
 }
 
+const CONTEXT_LAYOUTS = [CONTEXT_HEADINGS, [CONTEXT_HEADINGS[0], WORK_AGREEMENT_HEADING, ...CONTEXT_HEADINGS.slice(1)]];
+
 function parseContext(lines, section) {
   const headings = findHeadings(lines, section.start, section.end, 3);
-  if (headings.length !== 7)
-    fail("invalid-context", "Current Context must contain exactly the seven canonical headings");
+  const titles = headings.map((heading) => heading.title);
+  if (!CONTEXT_LAYOUTS.some((layout) => layout.join("\n") === titles.join("\n")))
+    fail(
+      "invalid-context",
+      `Current Context must contain the seven canonical headings, with an optional ${WORK_AGREEMENT_HEADING} directly after Goal`,
+    );
   const statements = new Map();
   for (let index = 0; index < headings.length; index += 1) {
-    const expected = [
-      "Goal",
-      "What defines this task",
-      "Settled",
-      "Tentative",
-      "Open",
-      "Current direction",
-      "Boundaries",
-    ][index];
-    if (headings[index].title !== expected) fail("invalid-context", `Expected Current Context heading ${expected}`);
     const end = headings[index + 1]?.index ?? section.end;
-    statements.set(expected, { headingIndex: headings[index].index, start: headings[index].index + 1, end });
+    statements.set(titles[index], { headingIndex: headings[index].index, start: headings[index].index + 1, end });
   }
   return { ...section, headings: statements };
 }
@@ -517,6 +515,12 @@ export function validateDocument(document) {
   const goal = context.headings.get("Goal");
   if (!hasMeaningfulContent(document.lines, goal.start, goal.end))
     fail("missing-field", "Current Context Goal must contain meaningful content");
+  const agreement = context.headings.get(WORK_AGREEMENT_HEADING);
+  if (agreement && !hasMeaningfulContent(document.lines, agreement.start, agreement.end))
+    fail(
+      "missing-field",
+      `Current Context ${WORK_AGREEMENT_HEADING} must contain meaningful content; omit the heading until something is agreed`,
+    );
   if (!hasMeaningfulContent(document.lines, current.nextAction.start, current.nextAction.end))
     fail("missing-field", "Next useful action must contain meaningful content");
   for (const block of allBlocks(document)) {

package/skills/track-work/scripts/lib/format.mjs

@@ -10,6 +10,8 @@ export const CONTEXT_HEADINGS = [
   "Current direction",
   "Boundaries",
 ];
+// Optional: allowed only directly after Goal, and never empty.
+export const WORK_AGREEMENT_HEADING = "Work agreement";
 export const HISTORY_HEADINGS = ["Decisions", "Checkpoints", "Slices"];
 
 export const TASK_STATES = new Set(["active", "paused", "completed", "abandoned"]);