@hassangameryt/freeflow 0.8.0 → 0.9.0

package/skills/review-work/scripts/review-packet.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// Prefills a work reviewer's pointer brief (references/work.md, "The Brief") from the repository and the task folder,
+// then runs check-brief.mjs on it, so the brief points at the requirements, the right diff and the prior report
+// without being assembled by hand. It also reports the review gate's triggers the diff shows and the review-round
+// budget. Lines it cannot fill (the Boundary, unless given) stay empty, so check-brief refuses the brief until the
+// initiator fills them.
+// Usage: review-packet.mjs --review <1|2|3> --base <ref> [--head <ref>] [--task <task folder>] [--out <brief.md>]
+//                          [--boundary <text>] [--agreement <path>]... [--evidence <path>]... [--may-run <text>]
+//                          [--root <repository>] [--json]
+// With --task, the brief is written to <task>/scratch/reviews/R<n>-brief.md, the report path is R<n>-report.md beside
+// it, the agreement defaults to the task's record.md, and Review 2 or 3 takes its diff from the previous brief's
+// reviewed state and points to R<n-1>-report.md. Docs come from Write Docs' docs-check.mjs --covering on the changed
+// files. Exit code: check-brief's (0 passes, 1 has problems); 2 on a usage or Git error.
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+const USAGE =
+  "Usage: review-packet.mjs --review <1|2|3> --base <ref> [--head <ref>] [--task <task folder>] [--out <brief.md>] [--boundary <text>] [--agreement <path>]... [--evidence <path>]... [--may-run <text>] [--root <repository>] [--json]";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CHECK_BRIEF = join(HERE, "check-brief.mjs");
+const DOCS_CHECK = resolve(HERE, "../../write-docs/scripts/docs-check.mjs");
+const SKILL = resolve(HERE, "../SKILL.md");
+
+function fail(message) {
+  console.error(message);
+  process.exit(2);
+}
+
+let values;
+try {
+  ({ values } = parseArgs({
+    options: {
+      review: { type: "string" },
+      base: { type: "string" },
+      head: { type: "string", default: "HEAD" },
+      task: { type: "string" },
+      out: { type: "string" },
+      boundary: { type: "string" },
+      agreement: { type: "string", multiple: true, default: [] },
+      evidence: { type: "string", multiple: true, default: [] },
+      "may-run": { type: "string" },
+      root: { type: "string" },
+      json: { type: "boolean", default: false },
+    },
+  }));
+} catch (error) {
+  fail(`${error.message}\n${USAGE}`);
+}
+const round = Number(values.review);
+if (![1, 2, 3].includes(round) || !values.base) fail(USAGE);
+if (!values.task && !values.out) fail(`give --task or --out for where the brief goes\n${USAGE}`);
+
+const git = (cwd, args) =>
+  execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+let root;
+try {
+  root = resolve(git(resolve(values.root ?? "."), ["rev-parse", "--show-toplevel"]).trim());
+} catch {
+  fail("not inside a Git repository");
+}
+const commitOf = (ref) => {
+  try {
+    return git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]).trim();
+  } catch {
+    return null;
+  }
+};
+const head = commitOf(values.head);
+if (!head) fail(`no such commit: ${values.head}`);
+if (!commitOf(values.base)) fail(`no such commit: ${values.base}`);
+
+// Paths in the brief: relative to the repository when inside it, absolute otherwise.
+const show = (path) => {
+  const relativePath = relative(root, resolve(path));
+  return relativePath.startsWith("..") ? resolve(path) : relativePath;
+};
+const tick = (paths) => paths.map((path) => `\`${show(path)}\``).join(", ");
+
+const task = values.task ? resolve(values.task) : null;
+const reviews = task ? join(task, "scratch", "reviews") : dirname(resolve(values.out));
+const briefPath = values.out ? resolve(values.out) : join(reviews, `R${round}-brief.md`);
+const reportPath = join(task ? reviews : dirname(briefPath), `R${round}-report.md`);
+const notes = [];
+
+// Review 2 or 3 reviews the range since the previous review's reviewed state.
+let diffBase = values.base;
+let previousReport = null;
+if (round > 1) {
+  const previousBrief = join(reviews, `R${round - 1}-brief.md`);
+  const reviewed = existsSync(previousBrief)
+    ? /^\s*(?:[-*]\s+)?(?:\*\*)?Reviewed state:(?:\*\*)?\s*`?([0-9a-fA-F]{7,40}|\S+?)`?(\s|$)/m.exec(
+        readFileSync(previousBrief, "utf8"),
+      )?.[1]
+    : null;
+  if (reviewed && commitOf(reviewed)) diffBase = reviewed;
+  else notes.push(`no previous brief with a Reviewed state at ${show(previousBrief)}: the diff starts at --base`);
+  const candidate = join(reviews, `R${round - 1}-report.md`);
+  if (existsSync(candidate)) previousReport = candidate;
+  else notes.push(`no previous report at ${show(candidate)}: add its path and adjudication to "Previous report"`);
+}
+
+const agreement = values.agreement.length
+  ? values.agreement
+  : task && existsSync(join(task, "record.md"))
+    ? [join(task, "record.md")]
+    : [];
+if (!agreement.length) notes.push("no agreement found: pass --agreement (the record, or the accepted requirements)");
+
+const changed = git(root, ["-c", "core.quotePath=false", "diff", "--name-only", diffBase, head])
+  .split("\n")
+  .filter(Boolean);
+
+// Developer docs covering the changed files.
+let docs = [];
+if (changed.length && existsSync(DOCS_CHECK)) {
+  const run = spawnSync(
+    process.execPath,
+    [DOCS_CHECK, ...changed.flatMap((path) => ["--covering", path]), "--root", root, "--json"],
+    { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 },
+  );
+  if (run.status === 0)
+    docs = [...new Set(JSON.parse(run.stdout).paths.flatMap((entry) => entry.documents.map((doc) => doc.path)))];
+  else notes.push("docs-check could not run: fill Docs by hand");
+}
+
+// The project's Review Rules, when it keeps them in a file.
+const rules = git(root, ["ls-files"])
+  .split("\n")
+  .filter((path) => /(^|\/)(REVIEW\.md|review-rules\.md|REVIEW_RULES\.md)$/i.test(path));
+
+// The project's declared checks, for "May run".
+let mayRun = values["may-run"] ?? "";
+if (!mayRun && existsSync(join(root, "package.json"))) {
+  try {
+    const scripts = Object.keys(JSON.parse(readFileSync(join(root, "package.json"), "utf8")).scripts ?? {});
+    const declared = ["test", "check", "lint", "typecheck"].filter((name) => scripts.includes(name));
+    if (declared.length)
+      mayRun = `the project's declared checks: ${declared.map((name) => `\`npm ${name === "test" ? "test" : `run ${name}`}\``).join(", ")}`;
+  } catch {
+    // An unreadable package.json leaves May run for the initiator.
+  }
+}
+if (!mayRun) notes.push('fill "May run": the declared checks, or "nothing"');
+
+// Review gate triggers the diff shows; the agreement's own review triggers and Review Rules paths need a reader.
+const TRIGGERS = [
+  [
+    "security, authentication, authorization or secrets",
+    /(^|[/_.-])(auth[nz]?|oauth|login|passwords?|secrets?|credentials?|tokens?|permissions?|crypto|sessions?)([/_.-]|$)|authenticat|authoriz|(^|\/)\.env/i,
+  ],
+  ["possible data loss or a migration of stored data", /(migrat|schema|\.sql$|database|(^|\/)db\/|storage|persist)/i],
+  [
+    "CI or release files",
+    /(^\.github\/workflows\/|^\.gitlab-ci|^\.circleci\/|(^|\/)release|CHANGELOG|^scripts\/release)/i,
+  ],
+  [
+    "a public interface",
+    /(^package\.json$|(^|\/)bin\/|\.d\.ts$|(^|\/)SKILL\.md$|command-surface|(^|\/)index\.[cm]?[jt]s$|\.proto$|openapi|(^|\/)api\/)/i,
+  ],
+];
+const triggers = TRIGGERS.flatMap(([trigger, pattern]) => {
+  const paths = changed.filter((path) => pattern.test(path));
+  return paths.length ? [{ trigger, paths: paths.slice(0, 10), more: Math.max(0, paths.length - 10) }] : [];
+});
+const budget =
+  round === 1
+    ? "Review 1 of at most 3: the first selected independent review, broad by default."
+    : round === 2
+      ? "Review 2 of at most 3: a focused follow-up on the range since Review 1; if it stays Blocking, adjudicate and diagnose before any Review 3."
+      : "Review 3 of 3: exceptional, separately authorized and final; if it stays Blocking, rethink the approach rather than correct again.";
+
+const lines = [
+  `Review: ${round}`,
+  `Boundary: ${values.boundary ?? ""}`,
+  `Reviewed state: ${head.slice(0, 12)}`,
+  `Method: ${tick([SKILL, join(dirname(SKILL), "references", "work.md")])}`,
+  `Agreement: ${tick(agreement)}`,
+  `Docs: ${docs.length ? tick(docs) : "none"}`,
+  `Review rules: ${rules.length ? tick(rules) : "none"}`,
+  `Diff: ${commitOf(diffBase).slice(0, 12)}..${head.slice(0, 12)}`,
+  `Evidence: ${values.evidence.length ? tick(values.evidence) : "none"}`,
+  `May run: ${mayRun}`,
+  ...(round > 1 ? [`Previous report: ${previousReport ? tick([previousReport]) : ""}`] : []),
+  `Report: ${tick([reportPath])}`,
+];
+mkdirSync(dirname(briefPath), { recursive: true });
+writeFileSync(briefPath, `${lines.join("\n")}\n`);
+mkdirSync(dirname(reportPath), { recursive: true });
+
+const check = spawnSync(process.execPath, [CHECK_BRIEF, briefPath, "--root", root, "--json"], { encoding: "utf8" });
+let checked;
+try {
+  checked = JSON.parse(check.stdout);
+} catch {
+  fail(`check-brief failed: ${(check.stderr || check.stdout).trim()}`);
+}
+
+const result = {
+  command: "review-packet",
+  root,
+  brief: briefPath,
+  review: round,
+  diff: `${diffBase}..${values.head}`,
+  changedFiles: changed.length,
+  gateTriggers: triggers,
+  gateNotDetected: ["anything the work agreement names for review", "paths the Review Rules mark sensitive"],
+  budget,
+  notes,
+  checkBrief: { ok: checked.ok, problems: checked.problems },
+};
+if (values.json) console.log(JSON.stringify(result, null, 2));
+else {
+  console.log(`Brief: ${briefPath}`);
+  console.log(lines.map((line) => `  ${line}`).join("\n"));
+  console.log(`Changed files: ${changed.length}.`);
+  console.log(
+    triggers.length
+      ? `Gate triggers in the diff:\n${triggers.map((each) => `- ${each.trigger}: ${each.paths.join(", ")}${each.more ? ` and ${each.more} more` : ""}`).join("\n")}`
+      : "Gate triggers in the diff: none detected by path.",
+  );
+  console.log(`Not detected here: ${result.gateNotDetected.join("; ")}.`);
+  console.log(`Round budget: ${budget}`);
+  for (const note of notes) console.log(`Note: ${note}`);
+  console.log(
+    checked.ok
+      ? "check-brief: passes. Dispatch this brief."
+      : `check-brief: refused. Fill these, then rerun check-brief:\n${checked.problems.map((each) => `- ${each.line}: ${each.problem}`).join("\n")}`,
+  );
+}
+process.exit(checked.ok ? 0 : 1);

package/skills/setup-freeflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-freeflow
-description: Use when activating Freeflow in a repository, repairing its repository or personal configuration, or checking whether the current host is delivering Freeflow context.
+description: "Use when installing, activating or turning off Freeflow in a repository, changing or repairing its repository or personal configuration (.freeflow/config.json, .freeflow/local.json), or checking whether the current host is loading Freeflow's guidance and skills."
 ---
 
 # Setup Freeflow
@@ -9,21 +9,28 @@ Create or repair the smallest valid layered setup. Keep repository activation, p
 
 - `.freeflow/config.json` is the required shared repository activation config.
 - `.freeflow/local.json` is an optional per-checkout personal override. It cannot activate Freeflow by itself.
-- Runtime delivery depends on the current host's installed and trusted adapter.
+- Runtime delivery depends on the current host's installed and trusted adapter. Configuration does not prove runtime delivery.
 
 Answer setup questions and delivery checks read-only. An explicit action request authorizes the smallest selected setup change under the state rules below. When repository config is missing, first activation authorizes minimal shared config; it does not authorize personal overrides, optional capabilities, replacement of invalid config, or edits to repo-owned host instructions.
 
-Read [the activation contract](references/activation-contract.md) before changing setup state. Read [host setup](references/host-setup.md) when runtime delivery, lifecycle, or host trust matters.
+## Routes
+
+| Situation | Go to |
+| --- | --- |
+| Activating, or changing shared or personal setup | Establish Mutation Authority, then Inspect The Layers, then the section for that layer |
+| Repository config invalid, or conflicting with accepted source truth or repository instructions | [Discuss Work](../discuss-work/SKILL.md), before replacing or reinterpreting it |
+| Whether the host delivers Freeflow, or which host action refreshes it | Hosts, below |
+| Cognitive Routing or Tool Execution values | Their explicit settings surface (on Pi, `/freeflow settings`), only when the user requests them |
 
 ## Establish Mutation Authority
 
 Classify the current state before editing:
 
-- **Unconfigured:** repository config is missing or invalid, so Freeflow is not effective. An explicit setup request may create minimal config when it is missing. Replacing or reinterpreting invalid config still requires the specific authority described below.
-- **Configured but ineffective:** valid repository activation exists, but Freeflow is disabled or an invalid local config blocks runtime. No Freeflow guidance is effective. An explicit request governs the selected enablement, configuration, or repair.
-- **Effective:** Freeflow core guidance, the Interaction Contract, and base skills are effective. An explicit setup or repair request may be carried out within its authority; optional capability behavior remains independently gated.
+- **Unconfigured:** repository config is missing or invalid, so repository activation is absent and Freeflow is not effective. An explicit setup request may create minimal config when it is missing. Replacing or reinterpreting invalid config requires specific authorization and resolving the source conflict.
+- **Configured but ineffective:** valid repository activation exists, but effective `enabled` is `false` or an invalid local config blocks runtime. No Freeflow guidance is effective. An explicit request governs the selected enablement, configuration, or repair.
+- **Effective:** Freeflow core guidance, the Interaction Contract, and base skills are effective; obey them. An explicit setup or repair request may be carried out within its authority; optional capability behavior remains independently gated.
 
-User-operated host settings are direct user actions, not agent-performed config edits. Prefer them when available and do not claim their state changed until the host reports it.
+User-operated host settings are direct user actions, not agent-performed config edits. Prefer them when available, do not claim their state changed until the host reports it, and verify the resulting source and effective state afterward.
 
 ## Inspect The Layers
 
@@ -36,6 +43,14 @@ Before editing:
 
 A valid repository config establishes activation. A missing local config inherits repository settings. An invalid existing local config blocks effective Freeflow instead of falling back silently.
 
+Resolve each configurable value in this order:
+
+```text
+host session override -> personal override -> repository value -> built-in default
+```
+
+Host session overrides are host state, not config, and cannot bypass missing or invalid repository activation. Pi may temporarily override Freeflow enablement, and Cognitive Routing has its own host-managed session control. Effective Freeflow requires a valid repository config, a missing or valid local config, session-resolved `enabled: true`, and the prompt files the host delivers (Hosts, below).
+
 If setup is already valid and no change was requested, preserve it and report the effective sources. Do not rewrite config merely to normalize formatting or materialize defaults.
 
 ## Configure Shared Activation
@@ -46,32 +61,62 @@ For a new setup, write the minimal activation boundary:
 {}
 ```
 
-Add `enabled: false` only when the user explicitly requests Freeflow to be disabled. Add optional capability configuration only when the user explicitly requests it.
+Missing core keys use the built-in default `enabled: true`. Add `enabled: false` only when the user explicitly requests Freeflow to be disabled. Add optional capability configuration only when the user explicitly requests it. Do not add task state, phase, file inventories, plans, version metadata, activation paths, empty optional sections, host instruction copies, or generated workflow text.
 
-If repository config is invalid or conflicts with accepted source truth, use [Decision Gate](../decision-gate/SKILL.md) before replacing or reinterpreting it.
+These keys are unsupported in either config file and make it invalid until repaired: `defaultMode`, `interactionContract`, `skills`, `contextVirtualization`, and `conversationHistory`. The user deletes them wherever present; setup never migrates or removes them automatically.
 
-Do not create or append Freeflow instructions in `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, or another host-owned instruction surface.
+Do not create or append Freeflow instructions in `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, or another host-owned instruction surface, including to compensate for unavailable or unconfirmed delivery. Existing repo instructions remain live source truth within host precedence. They are not activation markers, but they can conflict with Freeflow behavior: name a conflict and ask through Discuss Work before changing setup or behavior when it would alter the next action, rather than overwriting them to make Freeflow appear active. Do not install repo-local hooks, CLI commands, lint rules, global standards, documentation inventories, or state files during setup.
 
 ## Add Personal Overrides Only When Requested
 
-Use `.freeflow/local.json` for an explicitly selected per-checkout override of `enabled`. Omitted values inherit from repository config and built-in defaults. Configure optional Cognitive Routing values only through its explicit settings surface.
+Use `.freeflow/local.json` for an explicitly selected per-checkout override of `enabled`:
 
-The legacy context keys `contextVirtualization` and `conversationHistory` are no longer supported. Delete either key from `.freeflow/config.json` or `.freeflow/local.json` wherever present; the containing file is invalid until repaired. Setup never removes them automatically.
+```json
+{
+  "enabled": false
+}
+```
 
-In Pi, `/freeflow settings` edits personal overrides and `/freeflow settings repo` edits shared settings. Prefer those controls when available.
+Omitted values inherit from repository config and built-in defaults; local precedence is per property, not whole-file replacement. Configure optional Cognitive Routing values only through its explicit settings surface.
 
-Before writing local config in a Git checkout, verify it is untracked and ignored. Do not modify shared ignore policy merely to store a personal preference; use the host's safe settings path or local Git exclusion. Refuse to overwrite a tracked local config.
+Before writing local config in a Git checkout, verify it is untracked and ignored. Do not modify shared ignore policy merely to store a personal preference: prefer the host's safe settings path, `.git/info/exclude`, or an existing ignore rule. Refuse to overwrite a tracked local config.
 
 If local config is invalid, report that it blocks effective runtime. Repair or remove it only with authorization; never discard it and fall back silently.
 
+## Hosts
+
+When Freeflow is effective, host adapters deliver `runtime/prompts/core.md`, `interaction-contract.md` and `working-method.md`, the base Freeflow skill surface, and compact current capability state; on Pi also `tool-execution.md` and `cognitive-routing.md` while those capabilities are effective, with their skills and tools. Adapters load context only; they do not enforce policy, block tools, grant permissions, or replace repo instructions. Context Virtualization and Conversation History are removed.
+
+### Pi
+
+The Pi extension reads both config layers before each agent turn. When Freeflow is enabled it always delivers the core prompt, Interaction Contract and Working Method together, keeping the existing system prompt. Runtime State is refreshed at session start, after context reconstruction or loss, and when displayed state changes; unchanged state remains in the provider context. Skill and capability bodies stay discoverable rather than delivered as hidden persistent messages.
+
+Settings scopes:
+
+```text
+/freeflow settings          personal overrides
+/freeflow settings session  temporary Freeflow and Cognitive Routing session controls
+/freeflow settings repo     shared repository settings
+```
+
+Session settings can temporarily inherit, enable, or disable Freeflow and override Cognitive Routing profiles and delegation; one reset action clears them. They persist in the active Pi session branch, never write either config file, and cannot bypass missing or invalid repository activation. The personal settings path uses omission to inherit, refuses to overwrite invalid or tracked local config, and establishes local Git exclusion when needed. These user-operated controls update state before the next model turn and reload Pi resources when supported.
+
+A config written during setup is visible to the adapter on the next agent turn. After first activation, tell the user to run `/reload` so Pi refreshes skills and resources fully; without it, core runtime context loads on the next turn but resource discovery waits. Confirm automatic delivery through current extension status or runtime evidence.
+
+### Codex And Claude Code
+
+The packaged runtime hook reads the same two layers. At supported `SessionStart` boundaries (startup, resume, clear, and compact) it loads `core.md`, `interaction-contract.md` and `working-method.md`, each unless `prompts` (`core`, `interactionContract`, `workingMethod`; each a boolean, on by default, personal overriding shared per prompt) turns it off, and emits a compact active Runtime State. It does not process submitted prompts, persist session controls, inject skill bodies, or inspect Pi-only capabilities.
+
+After first-time setup, tell the user to trigger the least disruptive supported host-native lifecycle boundary: resume, clear, compact, or a new session or startup, as available. Name the exact control the current host supports; do not prescribe Pi's `/reload`.
+
 ## Establish Same-Turn Context
 
 After successful verification, apply newly effective context directly for the remainder of the setup turn:
 
 - read the [Interaction Contract](../../runtime/prompts/interaction-contract.md);
-- read [Workflow](../workflow/SKILL.md) when Freeflow is effective.
+- read the [core guidance](../../runtime/prompts/core.md) and the [Working Method](../../runtime/prompts/working-method.md) when Freeflow is effective.
 
-These direct reads establish same-turn guidance; they do not prove that a lifecycle adapter ran. After first activation, use [host setup](references/host-setup.md) to name the exact host-native lifecycle action for automatic delivery and resource refresh, state what applies before that boundary, and keep delivery confirmed, unavailable, or unconfirmed from evidence.
+These direct reads establish same-turn guidance; they do not prove that a lifecycle adapter ran, and no further adapter invocation has occurred yet. After first activation, name the exact host-native lifecycle action for automatic delivery and resource refresh (Hosts, above), and state what applies before that boundary.
 
 ## Verify And Report
 
@@ -80,10 +125,16 @@ Verify:
 - repository config parses and is the required activation boundary;
 - local config is missing or valid, personal, untracked, and ignored when applicable;
 - effective `enabled`, core guidance, and optional capability values have the expected sources;
-- no repo-owned host instructions or unrelated files changed.
+- no repo-owned host instructions or unrelated files changed, and running setup again would change nothing.
 
 After verification supports a setup result, silently self-review the final observed or changed state before accepting, reusing, or reporting it. Correct clear local issues within the existing setup authority and re-verify the affected boundary; stop on ambiguity, route change, or an out-of-envelope correction.
 
+Classify automatic runtime delivery from evidence:
+
+- **confirmed:** trustworthy evidence shows the current host adapter ran for the current lifecycle;
+- **unavailable:** the adapter, plugin or hook is absent, disabled, denied, untrusted, or unsupported;
+- **unconfirmed:** the adapter may be installed and trusted, but the host exposes no trustworthy evidence that it ran. Installed and trusted registration establishes availability for the next lifecycle action, not delivery.
+
 Report separately:
 
 1. shared repository activation;

package/skills/track-work/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: track-work
-description: "Use when work needs durable task memory: starting, updating, recovering, or closing a Working Record, or preparing for compaction, a pause, or a handoff."
+description: "Use when a task needs memory beyond the conversation: starting, updating or recovering its Working Record; after a compaction, a summary, a clear or a move into a new session; when the context limit is near; before pausing, handing off or transferring work to a later session or another person; when a task ID, a project of tasks, child records or parallel sessions are involved; and when editing a record or running its working-record script. It decides what the record says, and every lifecycle change goes through its script."
 ---
 
 # Track Work
@@ -11,7 +11,7 @@ The record is not authority, a Spec, a Plan, or a transcript. It works for any k
 
 The record has five sections:
 
-- **Current Context:** present understanding, including `What defines this task`, which points to the task's defining artifacts such as its Spec and Plan.
+- **Current Context:** present understanding, including the optional `Work agreement` (what the user agreed you may do, and until when) and `What defines this task`, which points to the task's defining artifacts such as its Spec and Plan.
 - **Current Work:** the Current Slice (the unit of work in progress, with its `Material updates` log), `Recovery sources` to read when resuming, and one Next useful action.
 - **Future Work:** the rough route ahead, as proposed Slices and Checkpoints.
 - **History:** accepted Decisions, closed Checkpoints, and closed Slices.
@@ -19,13 +19,24 @@ The record has five sections:
 
 The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better.
 
+## Routes
+
+| Situation | Go to |
+| --- | --- |
+| Context loss: compaction, a summary that replaces the conversation, clear, a transfer into another context | Recover After Context Loss, below |
+| A context limit is near | Prepare For A Context Boundary, below |
+| Handing work to a later session or someone else, or a pause | Prepare For A Context Boundary, then [handoff](references/handoff.md) |
+| 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 | [projects](references/projects.md) |
+| Editing record structure or preparing input for a command | [working record format](references/working-record-format.md) |
+| On Pi with Task Memory on: attaching, creating, focusing or switching records, or a refused record write | The `task_memory` tool; the task-memory skill says how |
+
 ## Rules
 
 - The record is memory, not authority. It never authorizes work, and current user direction, live state, and accepted artifacts override it.
 - Record a Slice before causing effects outside the record: edits, commands, generated files, sent messages, or changes to external systems.
 - Use [working-record.mjs](scripts/working-record.mjs) for every lifecycle change: IDs, states, and moves between sections. Edit only meaning directly.
 - Only the user changes task state.
-- After context loss, recover in this order before any task action: the complete record through `view full`, then every artifact listed under `What defines this task`, then `Recovery sources`. If any of them cannot be read completely, report that and stop affected work.
+- After context loss, recover in this order before any task action: the record through `view recover` (not by opening `record.md`, which loads all of History), then every artifact listed under `What defines this task`, then `Recovery sources`, then the History entries the next action depends on through `view entry`. If any of them cannot be read completely, report that and stop affected work.
 - Recover only a record that the context you still have ties to the current work, such as the user's direction, or a summary or handoff that names it. A recent change does not show that a record belongs to the current work. When a record's task and the current work disagree, report it instead of recovering the record.
 - Never record a requested, reported, or expected result as observed. Keep unverified work, failures, and contradictions visible.
 - Never claim that state will survive context loss unless it is written in the record or in a source the record points to.
@@ -40,6 +51,7 @@ Ask: **if context were lost now, what would the next context need that it could
 | --- | --- |
 | Understanding changes: a fact is settled, a hypothesis forms, a question opens | Current Context |
 | The user accepts a choice | a Decision |
+| The user agrees to a route or part of one, or changes it | the Work agreement |
 | Work with partial state is about to begin | a Slice |
 | You learn something needed to resume: a file, attachment, message, or section | Recovery sources |
 | A Spec, Plan, or other defining artifact is created or accepted for the task | What defines this task |
@@ -63,17 +75,30 @@ The record serves both halves of the work; update it at meaningful boundaries, n
 - Start a record, with the understanding gathered so far, once the task is likely to outlast the current context or span sessions.
 - When the user makes a choice, record a Decision. Put options under consideration in Tentative and unanswered questions in Open.
 - Use Open to choose what to ask next, and check Settled and Decisions before asking the user something again.
+- When you propose a route and the user has not answered, put it under Open as a bullet starting `Proposed:` with its date. An unanswered proposal is not agreed.
 - When the user supplies material that governs the work, point to it from Recovery sources, or from `What defines this task` if it defines the task.
 - When what and how are settled, propose the route in Future Work.
 
 **Executing:** the record is bookkeeping.
 
-- Record the Slice before its first effect.
+- Record the Slice before its first effect. Its Authority source names the Work agreement line, or the user's reply, it rests on.
 - Add Material updates at boundaries: evidence, identities such as commit SHAs or document versions, scope extensions, and contradictions.
 - Add Recovery sources as the work reveals what a resume would need.
 - Close Checkpoints as their boundaries happen, then close the Slice with a distilled result.
 - Keep temporary files for the task, such as throwaway scripts, saved command output, and downloads, in the task directory's `scratch/`. They stay with the task and out of version control; nothing in them is memory unless the record points to it.
 
+## Keep The Work Agreement
+
+Goal: after context loss, the next context knows what the user agreed it may do, and until when, in the user's words.
+
+Write the Work agreement section when something is agreed, at `init` if it is known then; never as a placeholder, and never ask the user for it just because a record is being created. Write only what is known: what done looks like, what you do without asking, what needs the user's yes first, where you come back, and how long it holds. Quote the user's reply beside what it answered. A one-line agreement is often enough.
+
+When the agreement grows or changes, replace the lines it changes, as a direct edit: the user's message that changed it covers the edit, so do not ask first or wait for a command. When the user narrows it for now ("just diagnose first", "don't edit yet"), add that line at once, in their words: it governs over the rest of the section until the user lifts it, and a later context sees only what is written. When a `Proposed:` item is answered, move it into the Work agreement, record it as a Decision if it decided something about the work, or drop it. A change to the agreement is not a Decision; a choice about the work is.
+
+For a long or unattended run, or once the agreement has changed several times, also keep `sources/work-agreement-log.md`: one dated, numbered entry per exchange that set or changed the agreement, the proposal in one line and the user's reply verbatim, append-only. It holds only those exchanges, not discussion. List it under Recovery sources with the trigger "read when changing the Work agreement or when its wording is in question".
+
+[Discuss Work](../discuss-work/SKILL.md)'s decision list lives in `sources/decisions.md` in the task folder, listed under Recovery sources with the trigger "read when deciding, self-reviewing, or handing over"; update it directly as items change. Each item the user answered also becomes a Decision quoting their words; the rest are what you assumed, never what the user accepted.
+
 ## Use Slices For Work With Partial State
 
 A Slice is a unit of work that would leave something to reconcile if interrupted: half-applied edits, a draft in progress, findings from 12 of 20 sources, a running process.
@@ -100,6 +125,8 @@ Future Work is your route at this moment, not a commitment. When you know roughl
 
 Before starting a proposal, check its dependencies against what actually happened and against the current agreement. Being next in Future Work is not a reason to take on its obligations.
 
+Before starting or reopening a Slice, check the History index for closed work on the same result and read it with `view entry`. A failed or abandoned approach lives there.
+
 A **Checkpoint** is a boundary on the route that is not itself a unit of work: a commit, a publication, a review, a decision, a continuity point. It belongs to the Slice it follows. Do not make a Checkpoint into a Slice.
 
 ```text
@@ -111,34 +138,38 @@ Future Work:
 Not: a separate "Commit the parser" Slice.
 ```
 
-| Type | Code | Other work |
-| --- | --- | --- |
-| `preserve` | local commit | save a draft version or snapshot |
-| `publish` | push, pull request | publish, send to a client |
-| `review` | independent code review | editor or reviewer sign-off |
-| `decision` | owner chooses a design | owner chooses between options |
-| `continuity` | pause or handoff point | pause or handoff point |
+| Type | Code | Other work | Owner when due |
+| --- | --- | --- | --- |
+| `preserve` | local commit | save a draft version or snapshot | Deliver Work (commit) |
+| `publish` | push, pull request | publish, send to a client | Deliver Work (push, pull request or release) |
+| `review` | independent code review | editor or reviewer sign-off | Review Work |
+| `decision` | owner chooses a design | owner chooses between options | Discuss Work |
+| `continuity` | pause or handoff point | pause or handoff point | Track Work ([handoff](references/handoff.md)) |
+
+When a pending Checkpoint is due, stop dependent work, use its owner, and continue from the result. Do not force a Checkpoint whose condition, evidence or protected boundary no longer holds; return the discrepancy for cancellation, replacement, deferral or revision.
 
-A Checkpoint is `proposed` while it is only anticipated and `pending` once the user authorizes or selects it. Activate it as soon as authority exists. A pending or deferred Checkpoint must be closed before its Slice closes; `completed` means the boundary happened, even when its judgment was adverse.
+Propose a Checkpoint only where it protects a dependency, decision, rollback, transfer, integration, or delivery; self-review is not one. A Checkpoint is `proposed` while it is only anticipated and `pending` once the user authorizes or selects it. Activate it as soon as authority exists. A pending or deferred Checkpoint must be closed before its Slice closes; `completed` means the boundary happened, even when its judgment was adverse.
 
 On long tasks, a `preserve` Checkpoint every few Slices keeps a recoverable point without a Slice of its own.
 
 ## Recover After Context Loss
 
-Context loss includes compaction, summarization that replaces context, clear, session resume or navigation, transfer to another context, or uncertain continuity. Recover before task work (Rules), in order:
+Context loss means the conversation about the current work is no longer in context: after compaction, a summary that replaces it, clear, a transfer to another context, or a session or branch that continues the work without it. Recover before task work (Rules), in order:
 
-1. `view full`: read the complete record, including History and Notes. If output is truncated, keep reading the same file until complete. `view resume` and summaries are not full recovery.
+1. `view recover`: the `resume` view (the record's present state and a one-line index of closed History), then each defining artifact and Recovery source with its trigger, whether it resolves and its size, then where live Git state disagrees with the record. If output is truncated, keep reading until complete. Do not open `record.md` itself for this: it loads the whole History, which the index lets you read only where needed. A summary is not recovery.
 2. Every artifact listed under `What defines this task`, such as the task's Spec and Plan.
 3. Every entry under `Recovery sources`, except one whose stated trigger ("read when …") does not apply yet; read that one when it does.
+4. The History entries the next action depends on, through `view entry <ID>`: closed work on the same result or area, a blocked or abandoned attempt at what you are about to do, a superseded Decision behind a current one, and any entry the record or a source names by ID. Do not read entries just because they exist.
 
-Then reconcile before acting. Establish the task and Slice state, the agreed outcome and return condition, active Decisions, pending Checkpoints, completed and partial effects, whether the next action's prerequisites hold, and what authorizes it.
+Then reconcile before acting. Establish the task and Slice state, the Work agreement (or, without one, the agreed outcome and return condition) and whether the user's latest direction has changed it, active Decisions, pending Checkpoints, completed and partial effects, whether the next action's prerequisites hold, and what authorizes it.
 
 - Current user direction supersedes older instructions in the record, including a record written on another conversation branch.
 - Compare the record with the live state the next action depends on. If they disagree, resolve it from sources; do not follow whichever version lets work continue.
 - If the record conflicts with a defining Spec or Plan, the record does not win. Return the conflict to that artifact's owner before dependent work.
-- Reuse evidence that still applies instead of repeating the investigation. Reopen further sources only when their exact content or freshness changes the next action.
+- Check an important completion, verification, review, or commit claim, and the identity of what it examined, before repeating it; a run that happened may not apply to the current state. Reuse evidence that still applies instead of repeating the investigation. Reopen further sources only when their exact content or freshness changes the next action.
+- A next action a handoff names authorizes nothing by itself. Without a record, as when resuming from a handoff alone, reconstruct from it and the exact sources it names, and report a missing boundary instead of inventing it.
 
-With context intact, use `view resume` or read the relevant section. Another turn or an ordinary pause is not context loss.
+With that conversation still in context, use `view resume` or read the relevant section; a new message, a pause or a resumed session is not context loss.
 
 ## Prepare For A Context Boundary
 
@@ -148,6 +179,7 @@ When a context limit is near or a pause or transfer is coming, make the record s
 - Update `Recovery sources` with what the next context must read, and why each matters. Drop entries the current work no longer needs; give a source needed only in some situation a trigger ("read when …").
 - Material that exists only in the conversation, such as a pasted image, file, or long message, will not survive. Save a copy under the task's `sources/` directory and point to it, or point to host-retrievable history when the host provides it.
 - Leave one Next useful action that a fresh context can act on.
+- For a pause or a transfer to another session or person, write the handoff with [handoff](references/handoff.md) once the record is sufficient.
 
 Do not rush a Slice to completion, claim an unfinished check passed, or guess the outcome of a running operation.
 
@@ -155,9 +187,9 @@ A context boundary is not a Slice transition or a Checkpoint. Pause the Slice on
 
 ## Maintain The Record
 
-Read [Working Record Format](references/working-record-format.md) before editing structure or preparing input for a command. It owns the exact shape, fields, states, and command contract.
+[Working Record Format](references/working-record-format.md) owns the exact shape, fields, states, and command contract; read it before editing structure or preparing input for a command.
 
-Edit meaning directly: Current Context bullets, optional fields, Material updates, Recovery sources, proposal order or removal, the Next useful action, and Notes. After a structural edit, run `validate`. It checks structure only; it cannot tell whether an edit changed history or skipped a lifecycle step, so never make those edits by hand.
+Edit meaning directly: Current Context bullets, optional fields, Material updates, Recovery sources, proposal order or removal, the Next useful action, and Notes. After a structural edit, run `validate`. It checks structure, and warns about Material updates pointers (files, commits) that do not resolve (`--strict` fails on those an Evidence or Result line names); it cannot tell whether an edit changed history or skipped a lifecycle step, so never make those edits by hand.
 
 Run `working-record.mjs <group> <operation> --help` before preparing a command's input; the help and the format reference are the contract, so read `scripts/lib/` only when diagnosing a defect. If a command exits with code 2, the write may have happened: read `view full` before retrying or editing. Never duplicate an entity to recover from an uncertain result.
 
@@ -177,6 +209,6 @@ Closing selects nothing. Set the Next useful action from the actual result.
 
 ## Return
 
-Return to the activity that asked for the update: [Discuss](../discuss/SKILL.md) for discussion, [Execute Work](../execute-work/SKILL.md) for Slice work, [Workflow](../workflow/SKILL.md) for routing. [Handoff](../handoff/SKILL.md) owns point-in-time transfer; [Write Spec](../write-spec/SKILL.md) and [Write Plan](../write-plan/SKILL.md) own the task's artifacts.
+Return to the activity that asked for the update: [Discuss Work](../discuss-work/SKILL.md) for discussion, [Execute Work](../execute-work/SKILL.md) for Slice work. [Write Docs](../write-docs/SKILL.md) owns the task's Specs and Plans.
 
 Stop when the record lets a fresh context continue correctly. Stop and report, rather than invent, when authority, structure, or the meaning of a transition is missing. A record update never completes the work it describes.