@hassangameryt/freeflow 0.8.0 → 0.9.0

package/skills/deliver-work/scripts/release-preflight.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// Local release preflight (references/release.md, "Preflight The Exact Release"): the declared version and whether it
+// is valid and new, whether its tag already exists locally and where it points, the changelog's state for it, the
+// source (branch, clean tree, HEAD), and for an npm package what `npm pack --dry-run` would publish. It changes
+// nothing and publishes nothing. Registry state needs the network and is reported unavailable.
+// Usage: release-preflight.mjs [--version <x.y.z>] [--tag-prefix <v>] [--root <repository>] [--no-pack] [--json]
+// --version defaults to the declared version. Exit code 0 when no problem was found, 1 when one was, 2 on a usage
+// error or outside a Git repository.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import {
+  branchState,
+  changelog,
+  git,
+  latestTag,
+  projectVersion,
+  repositoryRoot,
+  workingState,
+} from "./lib/git-state.mjs";
+
+const USAGE =
+  "Usage: release-preflight.mjs [--version <x.y.z>] [--tag-prefix <v>] [--root <repository>] [--no-pack] [--json]";
+let values;
+try {
+  ({ values } = parseArgs({
+    options: {
+      version: { type: "string" },
+      "tag-prefix": { type: "string", default: "v" },
+      root: { type: "string" },
+      "no-pack": { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+    },
+  }));
+} catch (error) {
+  console.error(`${error.message}\n${USAGE}`);
+  process.exit(2);
+}
+const root = repositoryRoot(values.root ?? ".");
+if (!root) {
+  console.error("not inside a Git repository");
+  process.exit(2);
+}
+
+const problems = [];
+const facts = [];
+const declared = projectVersion(root);
+const version = values.version ?? declared?.version ?? null;
+const SEMVER = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
+if (!version) problems.push("no version: none declared (package.json, pyproject.toml, Cargo.toml) and none given");
+else {
+  if (!SEMVER.test(version)) problems.push(`version ${version} is not a valid x.y.z version`);
+  if (values.version && declared?.version && declared.version !== values.version)
+    problems.push(`version ${values.version} differs from the declared ${declared.version} (${declared.source})`);
+}
+
+const tagName = version ? `${values["tag-prefix"]}${version}` : null;
+const tagCommit = tagName ? git(root, ["rev-list", "-n", "1", `refs/tags/${tagName}`]) : null;
+const branch = branchState(root);
+if (tagCommit) {
+  if (tagCommit === branch.head)
+    facts.push(`tag ${tagName} exists locally and points at HEAD: a release of this commit may already be tagged`);
+  else problems.push(`tag ${tagName} already exists locally at ${tagCommit.slice(0, 12)}, not HEAD: never move it`);
+}
+const previous = latestTag(root);
+if (previous && version && SEMVER.test(version)) {
+  const parse = (text) =>
+    text
+      .replace(/^[^\d]*/, "")
+      .split(/[-+]/)[0]
+      .split(".")
+      .map(Number);
+  const [a, b] = [parse(version), parse(previous.tag)];
+  const newer = a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+  if (newer < 0 && previous.tag !== tagName)
+    problems.push(`version ${version} is older than the latest tag ${previous.tag}`);
+}
+
+const notes = changelog(root);
+if (!notes) facts.push("no changelog found");
+else {
+  const released = version && notes.versions.includes(version);
+  if (released) facts.push(`${notes.file} has a section for ${version}`);
+  else if (notes.unreleased?.entries)
+    facts.push(`${notes.file}: ${notes.unreleased.entries} Unreleased entries, no ${version} section yet`);
+  else problems.push(`${notes.file} has no ${version ?? "version"} section and no Unreleased entries`);
+}
+
+const working = workingState(root);
+const dirty = working.staged.length + working.unstaged.length + working.conflicted.length;
+if (branch.detached) facts.push(`detached HEAD at ${branch.head.slice(0, 12)}`);
+if (dirty) problems.push(`${dirty} uncommitted change(s): a release is built from a commit`);
+if (working.untracked.length) facts.push(`${working.untracked.length} untracked path(s): check none would be packed`);
+if (branch.upstream && branch.ahead) facts.push(`${branch.ahead} commit(s) not on ${branch.upstream} (local refs)`);
+
+// What npm would publish, from a dry run that runs no lifecycle scripts.
+let pack = null;
+if (!values["no-pack"] && existsSync(join(root, "package.json"))) {
+  const run = spawnSync("npm", ["pack", "--dry-run", "--ignore-scripts", "--json"], {
+    cwd: root,
+    encoding: "utf8",
+    maxBuffer: 256 * 1024 * 1024,
+  });
+  try {
+    const [result] = JSON.parse(run.stdout);
+    const files = result.files.map((file) => file.path);
+    const unexpected = files.filter((path) =>
+      /(^|\/)(\.env(\..*)?|\.npmrc|.*\.(pem|key|p12)|\.freeflow\/|node_modules\/|.*\.log)$|(^|\/)\.freeflow\//.test(
+        path,
+      ),
+    );
+    pack = {
+      name: result.name,
+      version: result.version,
+      files: files.length,
+      size: result.size,
+      unpackedSize: result.unpackedSize,
+      unexpected,
+    };
+    if (result.version !== version) problems.push(`npm would pack version ${result.version}, not ${version}`);
+    if (unexpected.length)
+      problems.push(`npm would publish files that look private: ${unexpected.slice(0, 10).join(", ")}`);
+    const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    for (const entry of [
+      manifest.main,
+      ...Object.values(typeof manifest.bin === "string" ? { bin: manifest.bin } : (manifest.bin ?? {})),
+    ].filter(Boolean))
+      if (!files.includes(entry.replace(/^\.\//, "")))
+        problems.push(`package entry ${entry} is not in the packed files`);
+  } catch {
+    pack = { error: (run.stderr || run.stdout || "npm pack failed").trim().split("\n").slice(-3).join(" ") };
+    problems.push(`npm pack --dry-run failed: ${pack.error}`);
+  }
+}
+
+const report = {
+  command: "release-preflight",
+  root,
+  version,
+  declared,
+  tag: { name: tagName, exists: Boolean(tagCommit), commit: tagCommit?.slice(0, 12) ?? null },
+  latestTag: previous,
+  source: {
+    branch: branch.branch,
+    head: branch.head,
+    subject: branch.subject,
+    dirty,
+    untracked: working.untracked.length,
+  },
+  changelog: notes,
+  pack,
+  problems,
+  facts,
+  unavailable: [
+    "whether the version is already on the registry",
+    "remote tags",
+    "CI on the release commit",
+    "signing and publish permissions",
+  ],
+};
+if (values.json) console.log(JSON.stringify(report, null, 2));
+else {
+  console.log(
+    `Release ${version ?? "(no version)"} as ${tagName ?? "(no tag)"} from ${branch.branch ?? "detached HEAD"} ${branch.head?.slice(0, 12) ?? ""} ${branch.subject ?? ""}`,
+  );
+  if (pack && !pack.error)
+    console.log(`npm pack: ${pack.name}@${pack.version}, ${pack.files} files, ${pack.size} bytes packed`);
+  for (const fact of facts) console.log(`- ${fact}`);
+  console.log(
+    problems.length
+      ? `Problems (${problems.length}):\n${problems.map((each) => `- ${each}`).join("\n")}`
+      : "No problem found locally.",
+  );
+  console.log(`Unavailable without the network: ${report.unavailable.join("; ")}.`);
+}
+process.exit(problems.length ? 1 : 0);

package/skills/discuss-work/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: discuss-work
+description: "Use whenever what to do, or how, is not settled yet: exploring a problem, comparing options or approaches, questioning assumptions, brainstorming, planning an approach, or revisiting a direction after new evidence. Read it at a task's first request, before your first tool call, to decide with the user what you will do, where you stop and which choices are theirs before anything is built, fixed or changed. Also use mid-work when a choice the user owns comes up (behavior, names, defaults, scope, cost, risk) or sources conflict; when a question needs a quick experiment before building on it; when a discussion or its decisions must outlast the conversation; and when the user asks to skip or lighten optional steps such as a plan, a review or a record."
+---
+
+# Discuss Work
+
+Work out with the user what to do, and how, while that is still open; agree the work and every choice that is the user's before building; keep those choices in one decision list through the work; and account for them at the end.
+
+A **user-owned choice** changes something the user will see or live with: behavior, names, text or public interfaces the user meets, defaults, what happens on error, data written or lost, scope, compatibility or migration, permissions, security, privacy, cost, or other risk. Mechanics that change none of these are yours to choose. The [Interaction Contract](../../runtime/prompts/interaction-contract.md) governs what the user's turn asks for.
+
+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 |
+| --- | --- |
+| What to do, or how, is still open | Explore, below |
+| A task that builds or changes behavior, before the first edit | Agree Before Building, below |
+| A user-owned choice or conflicting sources mid-work | Choices During The Work, below |
+| Writing or checking the decision list, or the agreement, handover or catch-up built from it | Run [choices](scripts/choices.mjs), as Build The Decision List says |
+| A question existing evidence cannot settle but running something could | [learning action](references/learning-action.md) |
+| Discussion state, an emerging route or its Checkpoints must outlast the conversation | [discussion continuity](references/discussion-continuity.md) |
+| Representation, interfaces, ownership, state or failure behavior could materially change a technical recommendation | Execute Work's [design](../execute-work/references/design.md) |
+| A reported or recurring failure needs a cause rather than options | Execute Work's [diagnose](../execute-work/references/diagnose.md) |
+| Agreed, concrete work | [Execute Work](../execute-work/SKILL.md) |
+
+## Rules
+
+- Conversation, convergence, a recommendation or a recorded proposal never authorizes building. On a task that builds or changes behavior, send the agreement before the first edit and wait for the user's answer, unless a case in "When To Skip" applies.
+- Leave priorities, behavior, constraints and tradeoffs the user owns to the user. After asking, stop: do not perform the blocked action until the user answers, and never settle a user-owned choice by proceeding.
+- Never ask the user to choose between factual claims that evidence can settle; look them up.
+- An answer decides only what it answers. A question, criticism, hypothesis, condition, or request for more information is not a decision: respond to it and keep waiting. Urgency, prior effort, or general approval to continue settles no choice that was not named.
+- Keep supported facts and the user's decisions apart from hypotheses, proposals and open choices. Your recommendation or default never becomes a requirement or a Decision because it is repeated, recorded or built; record as a Decision only what the user accepted.
+- Every user-owned choice the work makes goes in the decision list, whether or not anyone answered it. A technical choice that changes something the user will see goes in the plain list.
+- Never weaken required behavior to make an approach look simpler.
+
+## Explore
+
+Goal: enough shared understanding to choose the next sound action, at the depth the user asked for.
+
+Respond to the substance before steering the process. A request to discuss keeps the user involved: gather what the question needs, say what it implies, and come back at the next meaningful question or supported conclusion. A direct request that settles the outcome and leaves the approach to you needs no discussion when existing evidence can resolve the remaining facts and reversible local choices.
+
+Name which understanding is missing, and establish only that: **what** (the problem, desired result, accepted behavior, constraints, non-goals, what counts as success) or **how** (mechanism, dependencies, affected boundaries, tradeoffs, the evidence needed in the actual environment). When reopening, name what changed and keep what still holds; a new local obstacle does not reopen the whole task.
+
+Before inspecting, name the missing fact and how its answer could change the discussion, and check whether current evidence already answers it. Read the focused source, caller, contract or observation that answers it, not a survey, and read more only when the result leaves a material question open; inspect code, tests, docs, supplied material and current primary sources for external versions or interfaces rather than asking the user for facts you can find. Source inspection cannot establish unobserved runtime behavior. Stop when the evidence supports the next decision; do not collect every later dependency or plan the exact implementation while the outcome is still open.
+
+Carry your share of the thinking: say what the evidence and intent imply, challenge unsupported claims and consequential assumptions, compare only materially different paths that could realistically be chosen with what each sacrifices and assumes, recommend the best-supported one and what would change it, and revise when evidence changes. Keep one consequential uncertainty in focus; no questionnaire, no invented alternatives for ordinary choices. Before recommending a new obligation, tell a requirement from a limitation of the current approach, and give its consequence in the user's terms ("requires changing and distributing a patched host," not "needs a provenance interface"), with a simpler in-scope alternative when one is supported.
+
+When the likely work is clear, propose coherent outcomes and their dependencies, near-term work concrete and later work directional. End the discussion when the next sound action no longer depends on open direction, or a learning action, user decision, wait or stop is clear; not because more could be explored. Return what the next step needs: supported understanding, tentative approach, open questions that matter, evidence, the recommended or accepted next action, and what is still unauthorized. Stable accepted content that needs a durable source becomes a Spec, and an ordered strategy that must outlast the conversation a Plan, through [Write Docs](../write-docs/SKILL.md); neither is mandatory. When the user asks to build, agree it below; when they leave the rest of the investigation and implementation to you, do not make them finish planning it or gather again what the discussion found.
+
+## Agree Before Building
+
+### Build The Decision List
+
+Goal: before editing, every place where the request, the repository and the developer docs leave a user-owned choice open is written down with your default.
+
+Read the request in the layers Execute Work's [Read The Request](../execute-work/SKILL.md#read-the-request) lists, and find what the change touches; each open choice becomes one item, and what those sources settle is not listed. Write technical items too (names, files, data structures, the code you will copy, exact messages): listing them is how you notice choices you would otherwise make unseen.
+
+Each item has:
+
+- an ID: `P1`, `P2`… for plain items the user sees, `T1`, `T2`… for technical ones;
+- the choice, for a plain item phrased as what the user will see or live with ("When several jobs pile up, should the oldest run first or the newest?", not "Queue or stack?");
+- your default and why: what matches existing behavior and is easiest to reverse, citing where;
+- for a technical item, the plain item it serves (`T3 -> P1`);
+- its state: `proposed`, `agreed` (the user answered; quote them), `default` (no one answered), `changed` (with why), `new` (found after the agreement; the user has not seen it), or `dropped`.
+
+Write one line per item, plain items first:
+
+```markdown
+- P1 [agreed] When jobs pile up, which runs first? -> oldest first (the scheduler does, src/sched.ts:40). You: "go" (2026-10-20). Shows at: src/queue.ts:12
+- P2 [new] Text when the queue is full -> "Queue full, try later". Shows at: src/queue.ts:30
+- T1 [default] FIFO array in queue.ts -> serves P1
+```
+
+Check the list with [choices](scripts/choices.mjs): `node <discuss-work-directory>/scripts/choices.mjs validate --list <file|->`, or `--record <record.md>` for the task's `sources/decisions.md`. It refuses a bad ID, state or `T -> P` link, or a plain item without a default.
+
+### Send The Agreement
+
+Goal: the user can agree in one word or correct one line.
+
+Send one reply, not a dialog, before the first edit:
+
+```text
+What I'll do:   <the outcome>
+Where I stop:   <done when; what I won't touch>
+Your decisions: 1. <a choice the request leaves open, as the user meets it>. I'd go with <default>, because <reason>.
+                2. ...
+Technical:      <N> more choices; say "show technical" to see them.
+```
+
+`choices.mjs agreement --do <outcome> --stop <where you stop>` renders this reply from the list. Show the technical list in full when the user asks or has said they always want it, and leave the line out when they have said never. With no plain items, say so and still wait.
+
+`Where I stop` names the endpoint the user can hold you to, and where you come back. After discussing several possible Slices, an ambiguous "proceed" needs it settled: the next Slice and return, or the whole task? Do not ask when the user already named the endpoint.
+
+"Go", "fine", "your call" and "just do it" accept every default: those items become `agreed`. A correction changes only the item it names. Then build within the agreement, through to where you stop.
+
+### When To Skip
+
+Goal: stop wherever an unseen choice could change the result, and nowhere else.
+
+- A question, discussion or review that changes nothing needs no agreement.
+- A change the user specified exactly ("change `state=draft` to `state=final` in target.txt"), or a run where no one can answer (a routed worker, an unattended run), counts as the agreement: take your defaults for anything it leaves open (state `default`) and put the whole list in your final report.
+
+A request that looks clear is not a skip: the choices it leaves open are the ones you have not noticed yet.
+
+When the user explicitly asks to skip an optional step, such as waiting for this agreement, a plan, a review or a record, skip only what they named, for as long as they said. It changes no authority, no checkpoint they selected, and no claim: a check they decline leaves its claim unverified. Without the wait, take your defaults (state `default`), still ask one question before a hard-to-reverse choice, and put the whole list in your final report. When a standing skip must survive context loss and a Working Record exists, record it in the Work agreement through Track Work.
+
+### Keep The List
+
+Goal: after an interruption or compaction, the next context knows what the user decided and what you only assumed.
+
+Without a Working Record, the list lives in the conversation; never create a record only to hold it. With one, [Track Work](../track-work/SKILL.md) says where the agreement, the user's answers and the list live.
+
+Under [Cognitive Routing](../../capabilities/cognitive-routing/SKILL.md), only Coordinator keeps the list and asks the user; a worker returns the choices it made.
+
+## Choices During The Work
+
+Goal: no choice is made silently, and the user is interrupted only when the work cannot go on without them.
+
+- A new choice that blocks the next step: settle its facts first, then ask one question (Ask One Question) and wait.
+- A new choice that does not block: take your default, add it as `new`, and continue.
+- A default that proves wrong: mark it `changed` with why; if it changes an `agreed` item, that needs the user's yes.
+- Several at once: ask the earliest one whose answer decides whether the others matter. Mid-work questions come one at a time; the agreement is the only list you send.
+- Work that turns out larger with the same outcome stays covered: continue without asking.
+- A remedy that makes a user-owned choice needs a new yes: explain its concrete consequence and the realistic alternatives, then ask.
+- New evidence that reopens the direction itself, not one bounded choice: go back to Explore for what changed.
+
+When sources the work relies on disagree, state each one's exact claim, scope and status (current, accepted, draft, historical, generated) and apply the repository's own precedence; code is not right because it runs, and tests are not requirements because they fail. Ask only when precedence does not settle it and the answer changes the result.
+
+## Ask One Question
+
+Goal: the user decides from one look, knows what you recommend, and their answer settles exactly what you asked.
+
+When the host has a question tool (`ask_user` on Pi with Freeflow, `AskUserQuestion` on Claude Code), a bounded choice of two to four real options usually goes in its dialog, with what you found and why it matters in your reply. Ask in your reply when the choice needs more explanation, or no dialog can be shown.
+
+- The question is one full sentence about the outcome the user owns ("Ship Task Memory on or off by default?"), not the mechanics ("Which value for `taskMemory.enabled`?").
+- Give two to four real options, each a few words with what choosing it does and costs; leave out dominated, unsafe, unavailable and hypothetical ones, and never add "Other".
+- Put your recommendation first, its label ending in "(Recommended)", when evidence supports one.
+- If the user closes the dialog, ask in your reply and do not act on the choice meanwhile.
+
+Record the question and the user's answer in their words.
+
+## Account At The End
+
+Goal: before you claim done, the user sees every choice they have not seen.
+
+The decision check runs in [Review Work](../review-work/SKILL.md)'s self-review of work, against this list. Find the choices the work made that the agreement did not settle, reading the change for anything the user would see: names, messages, defaults, behavior on error or in cases nobody specified, data written, and conventions copied from nearby code. Bring each `agreed` item with where the user agreed it (the work agreement, a Decision such as `D-003`, or their message) and the `file:line`, test or output that shows it was done as agreed, and each `changed` item with its reason; add each choice the diff shows that no item covers as `new`. Choices for the user stay in this list, never in a Decision, which holds only what the user accepted; building a choice does not settle it. The hand-over (the pull request through [Deliver Work](../deliver-work/SKILL.md), or the final report) shows what done looks like against what was done, and only the `new`, `changed` and `default` items. Agreed items stay out. `choices.mjs handover` lists those items; after an unattended run, `choices.mjs catch-up --record <record.md>` lists the defaults taken, the choices waiting and what ran.

package/skills/{discuss → discuss-work}/references/discussion-continuity.md

@@ -1,10 +1,10 @@
 # Discussion Continuity
 
-Read this before preserving discussion across context loss, creating or updating durable task memory from discussion, or carrying a proposed or selected checkpoint beyond the current conversational context.
+Read this when discussion state, an emerging route or its Checkpoints must outlast the conversation: before preserving discussion across context loss, creating or updating a Working Record or another durable source from discussion, or carrying a proposed or selected Checkpoint beyond the current context.
 
-This reference is judgment: adapt it to the discussion. Its binding statements restate [Discuss](../SKILL.md), Workflow, or Track Work Rules.
+This reference is judgment: adapt it to the discussion. Its binding statements restate [Discuss Work](../SKILL.md) or Track Work Rules.
 
-Discussion state is not automatically a Working Record, Spec, Plan, checkpoint, or authority. Preserve the required outcome separately from the current approach, and distinguish the user's execution agreement from proposals that have not been selected.
+Discussion state is not automatically a Working Record, Spec, Plan, checkpoint, or authority. Preserve the required outcome separately from the current approach, and distinguish the user's work agreement from proposals that have not been selected.
 
 ## Keep It In Conversation When Possible
 
@@ -27,7 +27,7 @@ Prefer natural prose. Use structured fields only when they prevent ambiguity or
 
 Do not preserve a transcript, repeated rationale, rejected alternatives that no longer matter, or every discussion turn. Retain a rejected approach when losing its reason would cause the next context to repeat it.
 
-## Choose Durable Memory By Purpose
+## Choose A Durable Destination By Purpose
 
 Use a durable destination only when losing the state could cause later misalignment:
 
@@ -42,15 +42,7 @@ Do not create an artifact merely because discussion occurred. Prefer an existing
 
 ## Preserve Through Track Work
 
-Discuss owns exploration and meaning. [Track Work](../../track-work/SKILL.md) owns the Working Record and its lifecycle.
-
-```text
-Discuss
--> supported state worth preserving
--> Track Work performs one atomic update
--> Discuss confirms the preserved meaning
--> continue discussion or return to Workflow
-```
+Discuss Work owns exploration and meaning. [Track Work](../../track-work/SKILL.md) owns the Working Record and its lifecycle: preserve supported state in one atomic update through it, then confirm the preserved meaning.
 
 A Working Record is appropriate when:
 
@@ -62,17 +54,17 @@ A Working Record is appropriate when:
 
 Preserve only supported state that could affect later interpretation or action. Give each detailed fact one canonical owner. Track Work should store current meaning rather than append discussion chronology.
 
-When the initial record need arises from discussion, preserve the state that justified the record in the first authorized atomic update. Do not create an empty shell and lose the decisions, proposals, or uncertainty that made continuity necessary.
+When the initial record need arises from discussion, preserve the state that justified the record in the first authorized atomic update. Do not create an empty shell and lose the decisions, proposals, or uncertainty that made continuity necessary. Once a record exists, use it as working memory during the discussion, updating it at meaningful boundaries (accepted choices, open questions, options still considered, material the user supplies, the route as it emerges) as Track Work describes.
 
-When a rough route is useful, preserve provisional Slices, the Checkpoints between them, and their actual dependencies without pretending the later implementation is settled. Keep the current unit concrete and later work directional. Use the existing Current Context, Current Work, Future Work, and History fields; do not add a second phase or context-cycle ledger.
+When a rough route is useful, preserve provisional Slices, the Checkpoints between them, and their actual dependencies without pretending the later implementation is settled. Keep the current Slice concrete and later work directional. Use the existing Current Context, Current Work, Future Work, and History fields; do not add a second phase or context-cycle ledger.
 
 Preserve the agreed outcome, scope, and user-facing return condition when losing them could interrupt covered work or permit drift. Authorization to investigate or propose a design is not acceptance of its production consequences. When learning changes the approach, retain the question, strongest evidence and limits, remaining uncertainty, artifact disposition, and affected later work—not the prototype's construction history.
 
-After preservation, return to Discuss unless Workflow established another route. Record mutation does not transfer ownership or authorize execution.
+After preservation, return to the discussion unless the user chose another route. Record mutation does not transfer ownership or authorize execution.
 
 ## Carry Checkpoints On The Route
 
-A commit, publication, review, user decision, or planned handoff that the discussion anticipates is a Checkpoint on the route, not a Slice. With a record, propose it in Future Work using Track Work's Checkpoint types and states: `proposed` while only anticipated, `pending` once Workflow selects it. Without a record, keep it in the conversation.
+A commit, publication, review, user decision, or planned handoff that the discussion anticipates is a Checkpoint on the route, not a Slice. With a record, propose it in Future Work using Track Work's Checkpoint types and states: `proposed` while only anticipated, `pending` once the user selects it. Without a record, keep it in the conversation.
 
 Keep local commit authority separate from push or publication, and keep migration, release, and launch separately controlled.
 
@@ -91,17 +83,8 @@ Authority or user decision needed:
 
 Do not restart from zero, rewrite unaffected decisions, or narrate completed work.
 
-After context loss, recover through Track Work's recovery order before relying on the record: the complete record, its defining artifacts, then its Recovery sources. Compare current sections and relevant History with current user direction, accepted artifacts, and live evidence. Reconcile affected meaning and dependent future work; do not repeat a disproved approach or preserve a stale plan merely because the record contains it. With intact context, use `resume` or targeted reads only when needed.
+After context loss, recover the record as Track Work's "Recover After Context Loss" says before relying on it. Compare current sections and relevant History with current user direction, accepted artifacts, and live evidence. Reconcile affected meaning and dependent future work; do not repeat a disproved approach or preserve a stale plan merely because the record contains it. With intact context, use `resume` or targeted reads only when needed.
 
 ## Stop
 
 Stop preserving when the current meaning and one next useful action can be reconstructed safely.
-
-Do not turn continuity into:
-
-- a transcript;
-- a mandatory artifact;
-- a second source of authority;
-- a frozen architecture;
-- an automatic checkpoint;
-- a reason to begin execution.

package/skills/discuss-work/references/learning-action.md

@@ -0,0 +1,36 @@
+# Learning Action
+
+Read this when existing evidence cannot settle a material question and running something could: before proposing an experiment or prototype, while running one, and when its evidence comes back.
+
+This reference is judgment: adapt it to the question. Its binding statements restate [Discuss Work](../SKILL.md) or [Execute Work](../../execute-work/SKILL.md) Rules.
+
+## Decide Whether To Run One
+
+Use an experiment or prototype when existing evidence cannot settle a material question and exercising behavior can distinguish the remaining answers. A separate prototype should isolate the uncertainty more safely or economically than changing production; unfamiliarity alone does not require one.
+
+If the work is an accepted useful outcome regardless of what it teaches, treat it as delivery work, not an experiment; do not disguise implementation as learning. Incidental learning does not change its authority or acceptance boundary.
+
+## Frame It
+
+Frame the action before proposing it:
+
+- the question and its consequence for the accepted outcome or approach;
+- plausible answers and the observation that would distinguish them;
+- the smallest adequate prototype or observer;
+- permitted effects, environment, and production exclusion;
+- expected evidence and return conditions: question answered, observing limit reached, or further work requiring a different question or expanded scope;
+- what would justify discarding, revising, or proposing promotion.
+
+Add a time or cost boundary when repetition or setup could grow; do not demand an exact token prediction. If no adequate observer is available within scope, state the limitation rather than inventing a proof.
+
+Check that the agreement covers the framed action, preserve it through [Track Work](../../track-work/SKILL.md) when needed, then run it through Execute Work. Existing authority may already cover the experiment; its name does not create another approval gate.
+
+## Run It
+
+Answer the one declared question with the least building that can, within the limits the framing set. Report a negative or inconclusive result as plainly as a positive one, and do not polish a prototype toward a favorable answer. A successful demonstration is not production acceptance: never promote exploratory code into production unless that promotion is deliberately selected and its effects authorized.
+
+## Assess What It Showed
+
+Assess returned evidence against the original question. Negative or inconclusive evidence is a valid result; one failed technique does not prove every alternative impossible. When it reports a new prerequisite, tell a limitation of the observer or chosen approach from a requirement of the intended outcome before recommending more work.
+
+Revise only the affected understanding. When continuity matters, preserve the consequence for the task, the remaining uncertainty, and what happens to the exploratory artifacts, as [discussion continuity](discussion-continuity.md) describes. Stop assessing when the supported next direction or the unresolved decision is clear.

package/skills/discuss-work/scripts/choices.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// Checks and renders Discuss Work's decision list (SKILL.md, "Build The Decision List"), so its format is a tool's job
+// and the agent's attention stays on the choices:
+//   validate   IDs, states, T -> P links, a default on every plain item, the user's words on agreed items, a reason on
+//              changed ones;
+//   agreement  the reply sent before building: What I'll do / Where I stop / Your decisions / Technical: N;
+//   handover   the items the hand-over shows: new, changed and default;
+//   catch-up   after an unattended run: defaults taken, choices waiting, changes, and what ran, from the Working
+//              Record's current Slice Material updates (read through Track Work's `working-record.mjs view resume`).
+// Usage: choices.mjs <validate|agreement|handover|catch-up> (--list <file|-> | --record <record.md>)
+//                    [--do <outcome> --stop <where you stop>] [--show-technical] [--json]
+// --list reads a file or stdin (no Working Record: the list lives in the conversation); --record reads the task's
+// sources/decisions.md beside the record. Each item is one line, "- P1 [state] choice -> default ..." (a technical
+// item "-> serves P1"); other lines are ignored. Every view validates first. Exit code 0 when the list is valid
+// (warnings do not fail it), 1 when it has errors, 2 on a usage error.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { parseChoices, renderChoices } from "./lib/choices.mjs";
+
+const USAGE = [
+  "Usage: choices.mjs <validate|agreement|handover|catch-up> (--list <file|-> | --record <record.md>)",
+  "                   [--do <outcome> --stop <where you stop>] [--show-technical] [--json]",
+].join("\n");
+const VIEWS = new Set(["validate", "agreement", "handover", "catch-up"]);
+const WORKING_RECORD = resolve(dirname(fileURLToPath(import.meta.url)), "../../track-work/scripts/working-record.mjs");
+
+function fail(message) {
+  console.error(message);
+  process.exit(2);
+}
+
+let parsed;
+try {
+  parsed = parseArgs({
+    allowPositionals: true,
+    options: {
+      list: { type: "string" },
+      record: { type: "string" },
+      do: { type: "string" },
+      stop: { type: "string" },
+      "show-technical": { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+    },
+  });
+} catch (error) {
+  fail(`${error.message}\n${USAGE}`);
+}
+const { values, positionals } = parsed;
+const [view] = positionals;
+if (!VIEWS.has(view) || positionals.length !== 1) fail(USAGE);
+if (Boolean(values.list) === Boolean(values.record)) fail(`give --list <file|-> or --record <record.md>\n${USAGE}`);
+if (view === "agreement" && (!values.do || !values.stop)) fail(`agreement needs --do and --stop\n${USAGE}`);
+
+let listText;
+let recordView = null;
+if (values.record) {
+  const record = resolve(values.record);
+  if (!existsSync(record)) fail(`no such record: ${values.record}`);
+  const listPath = join(dirname(record), "sources", "decisions.md");
+  if (!existsSync(listPath)) fail(`no decision list at ${listPath}; Track Work keeps it there`);
+  listText = readFileSync(listPath, "utf8");
+  if (view === "catch-up") {
+    const run = spawnSync(process.execPath, [WORKING_RECORD, "view", "resume", "--record", record], {
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    if (run.status !== 0) fail(`working-record.mjs view resume failed: ${(run.stderr || run.stdout).trim()}`);
+    recordView = run.stdout;
+  }
+} else if (values.list === "-") listText = readFileSync(0, "utf8");
+else if (!existsSync(resolve(values.list))) fail(`no such list: ${values.list}`);
+else listText = readFileSync(resolve(values.list), "utf8");
+
+const list = parseChoices(listText);
+const notes = [...list.errors.map((each) => `error: ${each}`), ...list.warnings.map((each) => `warning: ${each}`)];
+if (!list.ok) {
+  if (values.json)
+    console.log(
+      JSON.stringify({ command: `choices ${view}`, ok: false, errors: list.errors, warnings: list.warnings }, null, 2),
+    );
+  else console.log(`Decision list has ${list.errors.length} error(s):\n${notes.map((each) => `- ${each}`).join("\n")}`);
+  process.exit(1);
+}
+const rendered = renderChoices(view, list, {
+  outcome: values.do,
+  stop: values.stop,
+  showTechnical: values["show-technical"],
+  recordText: recordView,
+});
+if (values.json)
+  console.log(
+    JSON.stringify(
+      { command: `choices ${view}`, ok: true, warnings: list.warnings, ...rendered.data, text: rendered.text },
+      null,
+      2,
+    ),
+  );
+else console.log(`${notes.length ? `${notes.map((each) => `- ${each}`).join("\n")}\n\n` : ""}${rendered.text}`);