@hassangameryt/freeflow 0.7.3 → 0.8.0

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

@@ -11,11 +11,15 @@ import {
   HISTORICAL_SLICE_FIELDS,
   HISTORICAL_SLICE_STATES,
   HISTORY_HEADINGS,
+  LEGACY_CHECKPOINT_TYPES,
+  OCCURRED_PATTERN,
   PROPOSED_SLICE_FIELDS,
+  RECORDED_PATTERN,
   SCHEMA_VERSION,
   SLICE_TYPES,
   TASK_STATES,
   TOP_LEVEL_SECTIONS,
+  isCalendarDate,
   joinLines,
   nextId,
   parseId,
@@ -273,12 +277,35 @@ function parseContext(lines, section) {
   return { ...section, headings: statements };
 }
 
+const CURRENT_WORK_LAYOUTS = [
+  ["Current Slice", "Next useful action"],
+  ["Current Slice", "Recovery sources", "Next useful action"],
+];
+
 function parseCurrentWork(lines, section) {
   const headings = findHeadings(lines, section.start, section.end, 3);
-  if (headings.length !== 2 || headings[0].title !== "Current Slice" || headings[1].title !== "Next useful action")
-    fail("invalid-current-work", "Current Work must contain Current Slice followed by Next useful action");
+  const titles = headings.map((heading) => heading.title);
+  if (!CURRENT_WORK_LAYOUTS.some((layout) => layout.join("\n") === titles.join("\n")))
+    fail(
+      "invalid-current-work",
+      "Current Work must contain Current Slice, optional Recovery sources, then Next useful action",
+    );
+  const nextActionHeading = headings[headings.length - 1];
+  const recoveryHeading = headings.length === 3 ? headings[1] : null;
   const sliceContentStart = headings[0].index + 1;
   const sliceContentEnd = headings[1].index;
+  let recoverySources = null;
+  if (recoveryHeading) {
+    recoverySources = {
+      headingIndex: recoveryHeading.index,
+      start: recoveryHeading.index + 1,
+      end: nextActionHeading.index,
+    };
+    for (let index = recoverySources.start; index < recoverySources.end; index += 1) {
+      if (lineHeading(lines[index]))
+        fail("invalid-recovery-sources", `Recovery sources cannot contain headings: ${lines[index]}`);
+    }
+  }
   const content = nonBlankLines(lines.slice(sliceContentStart, sliceContentEnd));
   let currentSlice = null;
   if (content.length === 1 && content[0] === "None") {
@@ -304,9 +331,11 @@ function parseCurrentWork(lines, section) {
   return {
     ...section,
     sliceHeadingIndex: headings[0].index,
-    nextActionHeadingIndex: headings[1].index,
+    sliceEnd: sliceContentEnd,
+    nextActionHeadingIndex: nextActionHeading.index,
     currentSlice,
-    nextAction: { start: headings[1].index + 1, end: section.end },
+    recoverySources,
+    nextAction: { start: nextActionHeading.index + 1, end: section.end },
   };
 }
 
@@ -385,6 +414,8 @@ function parseHistory(lines, section) {
   };
 }
 
+const READABLE_CHECKPOINT_TYPES = new Set([...CHECKPOINT_TYPES, ...LEGACY_CHECKPOINT_TYPES]);
+
 function validateChoice(block, field, choices, required = true) {
   const value = scalarValue(block, field);
   if (!value && !required) return "";
@@ -459,6 +490,27 @@ function validateReferences(document) {
   }
 }
 
+export function validateOccurred(value, path) {
+  const match = OCCURRED_PATTERN.exec(value ?? "");
+  if (!match || !isCalendarDate(match[1]) || (match[2] && !isCalendarDate(match[2])))
+    fail("invalid-occurred", `Occurred in ${path} must be YYYY-MM-DD or YYYY-MM-DD to YYYY-MM-DD: ${value}`);
+  if (match[2] && match[2] < match[1]) fail("invalid-occurred", `Occurred in ${path} ends before it starts: ${value}`);
+  return match[2] ?? match[1];
+}
+
+function validateRecordedTime(slice) {
+  const occurred = scalarValue(slice, "Occurred");
+  const recorded = scalarValue(slice, "Recorded");
+  if (!occurred && !recorded) return;
+  if (!occurred || !recorded)
+    fail("missing-field", `Occurred and Recorded appear together in ${slice.path}; only slice record writes them`);
+  const end = validateOccurred(occurred, slice.path);
+  const match = RECORDED_PATTERN.exec(recorded);
+  if (!match || !isCalendarDate(match[1]))
+    fail("invalid-recorded", `Recorded in ${slice.path} must be "retroactively on YYYY-MM-DD": ${recorded}`);
+  if (end > match[1]) fail("invalid-occurred", `Occurred in ${slice.path} ends after it was recorded: ${occurred}`);
+}
+
 export function validateDocument(document) {
   const { header, context, current, future, history } = document;
   if (!header.name) fail("malformed-header", "Task name cannot be empty");
@@ -469,6 +521,9 @@ export function validateDocument(document) {
     fail("missing-field", "Next useful action must contain meaningful content");
   for (const block of allBlocks(document)) {
     if (block.id && !parseId(block.id, block.kind)) fail("invalid-id", `Invalid ${block.kind} ID ${block.id}`);
+    for (const [name, field] of block.fields) {
+      if (!valueText(field)) fail("empty-field", `Empty field ${name} in ${block.path}; omit fields without a value`);
+    }
   }
 
   const ids = new Set();
@@ -489,7 +544,7 @@ export function validateDocument(document) {
     } else {
       validateFields(item, ["State"], {});
       validateChoice(item, "State", FUTURE_CHECKPOINT_STATES);
-      validateChoice(item, "Type", CHECKPOINT_TYPES);
+      validateChoice(item, "Type", READABLE_CHECKPOINT_TYPES);
       validateFields(item, ["Condition", "Applies to"]);
       if (item.id && !parseId(item.id, "checkpoint")) fail("invalid-id", `Invalid Checkpoint ID ${item.id}`);
       const checkpointState = scalarValue(item, "State");
@@ -530,7 +585,7 @@ export function validateDocument(document) {
 
   for (const checkpoint of history.checkpoints.blocks) {
     validateChoice(checkpoint, "State", HISTORICAL_CHECKPOINT_STATES);
-    validateChoice(checkpoint, "Type", CHECKPOINT_TYPES);
+    validateChoice(checkpoint, "Type", READABLE_CHECKPOINT_TYPES);
     validateFields(checkpoint, ["Condition", "Applies to", "Result", "Task effect"]);
     const state = scalarValue(checkpoint, "State");
     if (state === "cancelled" || state === "replaced") requiredValue(checkpoint, "Reason");
@@ -543,6 +598,7 @@ export function validateDocument(document) {
     const state = scalarValue(slice, "State");
     if (state === "blocked") requiredValue(slice, "Resume when");
     if (state === "abandoned") requiredValue(slice, "Reason");
+    validateRecordedTime(slice);
   }
 
   if (header.state === "paused" && current.currentSlice && scalarValue(current.currentSlice, "State") !== "paused")

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

@@ -16,7 +16,9 @@ export const TASK_STATES = new Set(["active", "paused", "completed", "abandoned"
 export const SLICE_TYPES = new Set(["learning", "delivery", "deepening"]);
 export const CURRENT_SLICE_STATES = new Set(["in_progress", "paused"]);
 export const HISTORICAL_SLICE_STATES = new Set(["completed", "blocked", "abandoned"]);
-export const CHECKPOINT_TYPES = new Set(["independent_review", "local_commit", "user_decision", "continuity"]);
+export const CHECKPOINT_TYPES = new Set(["preserve", "publish", "review", "decision", "continuity"]);
+// Earlier type names remain readable so existing records stay valid.
+export const LEGACY_CHECKPOINT_TYPES = new Set(["local_commit", "independent_review", "user_decision"]);
 export const FUTURE_CHECKPOINT_STATES = new Set(["proposed", "pending", "deferred"]);
 export const HISTORICAL_CHECKPOINT_STATES = new Set(["completed", "cancelled", "replaced"]);
 export const DECISION_STATES = new Set(["active", "superseded", "retired"]);
@@ -60,6 +62,8 @@ export const DECISION_FIELDS = new Set([
 export const HISTORICAL_SLICE_FIELDS = new Set([
   "State",
   "Type",
+  "Occurred",
+  "Recorded",
   "Intended result",
   "Authority source",
   "Result",
@@ -71,6 +75,15 @@ export const HISTORICAL_SLICE_FIELDS = new Set([
   "Residual effects",
 ]);
 
+// A Slice recorded after the fact carries when it happened and the date it was recorded.
+export const OCCURRED_PATTERN = /^(\d{4}-\d{2}-\d{2})(?: to (\d{4}-\d{2}-\d{2}))?$/;
+export const RECORDED_PATTERN = /^retroactively on (\d{4}-\d{2}-\d{2})$/;
+
+export function isCalendarDate(value) {
+  const date = new Date(`${value}T00:00:00Z`);
+  return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}
+
 export const IDS = {
   slice: /^S-(\d{3,})$/,
   checkpoint: /^C-(\d{3,})$/,
@@ -111,6 +124,8 @@ export function canonicalLines(name, state = "active", lastUpdated = new Date().
     "",
     "None",
     "",
+    "### Recovery sources",
+    "",
     "### Next useful action",
     "",
     "## Future Work",

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

@@ -94,9 +94,9 @@ export function resolveRecordPath(root, supplied) {
   const recordPath = basename(candidate) === "record.md" ? candidate : join(candidate, "record.md");
   const canonicalRecord = canonicalPath(recordPath);
   if (!inside(tasks, canonicalRecord) || basename(canonicalRecord) !== "record.md")
-    fail("unsafe-path", `Record must be a record.md below ${tasks}`);
+    fail("unsafe-path", `Record must be a record.md below ${tasks}; pass --root or an absolute --record path`);
   const taskDirectory = basename(dirname(canonicalRecord));
-  if (!/^task-\d{3}-[a-z0-9][a-z0-9-]*$/.test(taskDirectory))
+  if (!/^task-\d{3,}-[a-z0-9][a-z0-9-]*$/.test(taskDirectory))
     fail("unsafe-path", `Invalid task directory: ${taskDirectory}`);
   return canonicalRecord;
 }
@@ -144,14 +144,13 @@ async function nextTaskNumber(tasks) {
   } catch (error) {
     if (error?.code !== "ENOENT") throw error;
   }
-  const used = new Set();
+  // Numbers are never reused, so an old reference to a deleted task cannot point at a new one.
+  let highest = 0;
   for (const entry of entries) {
-    const match = /^task-(\d{3})-/.exec(entry.name);
-    if (entry.isDirectory() && match) used.add(Number(match[1]));
+    const match = /^task-(\d{3,})-/.exec(entry.name);
+    if (entry.isDirectory() && match) highest = Math.max(highest, Number(match[1]));
   }
-  let number = 1;
-  while (used.has(number)) number += 1;
-  return number;
+  return highest + 1;
 }
 
 export async function createRecordPath(root, taskName, slug) {
@@ -169,6 +168,8 @@ export async function createRecordPath(root, taskName, slug) {
     if (error?.code === "EEXIST") fail("task-already-exists", `Task directory already exists: ${directory}`);
     throw error;
   }
+  // The task's place for temporary work, ignored by Git with the rest of the task directory.
+  await mkdir(join(directory, "scratch"));
   return { path, taskName };
 }
 

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

@@ -1,5 +1,6 @@
 import {
   ACTIVE_SLICE_FIELDS,
+  CHECKPOINT_TYPES,
   DECISION_FIELDS,
   HISTORICAL_CHECKPOINT_FIELDS,
   HISTORICAL_CHECKPOINT_STATES,
@@ -18,6 +19,7 @@ import {
   parseDocument,
   parseFragment,
   renderBlock,
+  validateOccurred,
 } from "./document.mjs";
 import { writeAtomically } from "./store.mjs";
 
@@ -60,6 +62,8 @@ const DECISION_ORDER = [
 const HISTORICAL_SLICE_ORDER = [
   "State",
   "Type",
+  "Occurred",
+  "Recorded",
   "Intended result",
   "Authority source",
   "Result",
@@ -331,7 +335,7 @@ async function startSlice(options, input, loaded) {
     { start: proposal.start, end: proposal.end, lines: [] },
     {
       start: document.current.sliceHeadingIndex + 1,
-      end: document.current.nextActionHeadingIndex,
+      end: document.current.sliceEnd,
       lines: ["", ...currentLines, ""],
     },
     nextActionReplacement(document, nextAction),
@@ -393,7 +397,7 @@ async function startDirectSlice(options, input, loaded) {
   const candidate = withLineChanges(document, [
     {
       start: document.current.sliceHeadingIndex + 1,
-      end: document.current.nextActionHeadingIndex,
+      end: document.current.sliceEnd,
       lines: ["", ...currentLines, ""],
     },
     nextActionReplacement(document, nextAction),
@@ -476,7 +480,7 @@ async function closeSlice(options, input, loaded) {
   const candidate = withLineChanges(document, [
     {
       start: document.current.sliceHeadingIndex + 1,
-      end: document.current.nextActionHeadingIndex,
+      end: document.current.sliceEnd,
       lines: ["", "None", ""],
     },
     { start: document.history.slices.end, end: document.history.slices.end, lines: historical },
@@ -485,6 +489,65 @@ async function closeSlice(options, input, loaded) {
   return publish(loaded, candidate, `Closed Slice: ${slice.id} — ${state}`);
 }
 
+function localDate(date = new Date()) {
+  const pad = (value) => String(value).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+async function recordSlice(options, input, loaded) {
+  const document = parseDocument(loaded.text);
+  if (!["active", "paused"].includes(document.header.state))
+    fail("invalid-task-state", `Cannot record a Slice while task state is ${document.header.state}`);
+  const title = requiredStringOption(options, "--title");
+  const state = requiredStringOption(options, "--state");
+  if (!HISTORICAL_SLICE_STATES.has(state)) fail("invalid-state", `Invalid historical Slice state: ${state}`);
+  const fragment = parseInput(
+    input,
+    new Set([
+      "Type",
+      "Occurred",
+      "Intended result",
+      "Authority source",
+      "Result",
+      "Evidence and limits",
+      "Task effect",
+      "Resume when",
+      "Reason",
+      "Residual effects",
+    ]),
+    "slice record",
+  );
+  const values = { State: state };
+  for (const field of [
+    "Occurred",
+    "Intended result",
+    "Authority source",
+    "Result",
+    "Evidence and limits",
+    "Task effect",
+  ])
+    values[field] = requireFragment(fragment, field, "slice record");
+  for (const field of ["Type", "Resume when", "Reason", "Residual effects"]) {
+    const lines = fragmentValue(fragment, field);
+    if (lines?.length) values[field] = lines;
+  }
+  if (state === "blocked") values["Resume when"] = requireFragment(fragment, "Resume when", "slice record");
+  if (state === "abandoned") values.Reason = requireFragment(fragment, "Reason", "slice record");
+  const recordedOn = localDate();
+  const occurredEnd = validateOccurred(fragmentText(fragment, "Occurred"), "slice record input");
+  if (occurredEnd > recordedOn) fail("invalid-occurred", `Occurred cannot end after today (${recordedOn})`);
+  values.Recorded = [`retroactively on ${recordedOn}`];
+  const id = nextEntityId(document, "slice");
+  const candidate = withLineChanges(document, [
+    {
+      start: document.history.slices.end,
+      end: document.history.slices.end,
+      lines: renderHistoricalSlice(values, title, id),
+    },
+  ]);
+  return publish(loaded, candidate, `Recorded Slice: ${id} — ${title} (${state}, retroactive)`);
+}
+
 async function reopenSlice(options, input, loaded) {
   const document = parseDocument(loaded.text);
   assertTaskActive(document, "reopen a Slice");
@@ -528,7 +591,7 @@ async function reopenSlice(options, input, loaded) {
   const candidate = withLineChanges(document, [
     {
       start: document.current.sliceHeadingIndex + 1,
-      end: document.current.nextActionHeadingIndex,
+      end: document.current.sliceEnd,
       lines: ["", ...currentLines, ""],
     },
     nextActionReplacement(document, nextAction),
@@ -546,6 +609,9 @@ async function proposeCheckpoint(options, input, loaded) {
   assertUniqueFutureTitle(document, title);
   const fragment = checkpointInput(input, "checkpoint propose");
   requireFragment(fragment, "Type", "checkpoint propose");
+  const type = fragmentText(fragment, "Type");
+  if (!CHECKPOINT_TYPES.has(type))
+    fail("invalid-type", `Checkpoint Type must be one of ${[...CHECKPOINT_TYPES].join(", ")}; found ${type}`);
   requireFragment(fragment, "Condition", "checkpoint propose");
   requireFragment(fragment, "Applies to", "checkpoint propose");
   const values = {
@@ -616,6 +682,7 @@ async function closeCheckpoint(options, input, loaded) {
     new Set(["Result", "Evidence", "Task effect", "Reason", "Replaced by"]),
     "checkpoint close",
   );
+  if (state === "replaced") assertOpenReplacement(document, id, fragmentText(fragment, "Replaced by"));
   const values = {
     State: state,
     Type: fieldLines(checkpoint, "Type"),
@@ -640,6 +707,13 @@ async function closeCheckpoint(options, input, loaded) {
   return publish(loaded, candidate, `Closed Checkpoint: ${id} — ${state}`);
 }
 
+// A replacement must still be able to carry the boundary; a closed Checkpoint cannot.
+function assertOpenReplacement(document, id, replacementId) {
+  const replacement = document.future.items.find((item) => item.kind === "checkpoint" && item.id === replacementId);
+  if (!replacement || replacementId === id || !["pending", "deferred"].includes(fieldValue(replacement, "State")))
+    fail("invalid-reference", `Replaced by must name another Checkpoint that is pending or deferred: ${replacementId}`);
+}
+
 function decisionInput(input, command) {
   return parseInput(
     input,
@@ -772,6 +846,7 @@ export async function runTransition(command, positionals, options, input, loaded
     if (operation === "resume") return resumeSlice(options, input, loaded);
     if (operation === "close") return closeSlice(options, input, loaded);
     if (operation === "reopen") return reopenSlice(options, input, loaded);
+    if (operation === "record") return recordSlice(options, input, loaded);
   }
   if (command === "checkpoint") {
     if (operation === "propose") return proposeCheckpoint(options, input, loaded);

package/skills/track-work/scripts/working-record.mjs

@@ -2,8 +2,8 @@
 
 import { rm } from "node:fs/promises";
 import { cwd } from "node:process";
-import { dirname } from "node:path";
-import { canonicalLines, joinLines, slugify, TASK_STATES } from "./lib/format.mjs";
+import { dirname, isAbsolute, sep } from "node:path";
+import { canonicalLines, joinLines, slugify } from "./lib/format.mjs";
 import { parseDocument, validateDocument } from "./lib/document.mjs";
 import { runTransition } from "./lib/transitions.mjs";
 import {
@@ -16,6 +16,9 @@ import {
 } from "./lib/store.mjs";
 import { renderFull, renderResume } from "./lib/views.mjs";
 
+const ROOT_HELP =
+  "--record is resolved against --root, which defaults to the current directory; an absolute --record path finds its own root.";
+
 function usage() {
   return [
     "Usage:",
@@ -23,6 +26,8 @@ function usage() {
     "  working-record.mjs view resume|full --record <record.md>",
     "  working-record.mjs validate --record <record.md>",
     "  working-record.mjs <slice|checkpoint|decision|task> <operation> ...",
+    "",
+    ROOT_HELP,
   ].join("\n");
 }
 
@@ -31,7 +36,7 @@ const COMMAND_HELP = new Map([
     "slice",
     [
       "Usage: working-record.mjs slice <operation> ...",
-      "Operations: slice propose, slice start, slice start-direct, slice pause, slice resume, slice close, slice reopen.",
+      "Operations: slice propose, slice start, slice start-direct, slice pause, slice resume, slice close, slice reopen, slice record.",
       "Run working-record.mjs <group> <operation> --help for options and input fields.",
       "Use --input - to read Markdown fragments from stdin.",
     ].join("\n"),
@@ -64,13 +69,13 @@ const COMMAND_HELP = new Map([
   ],
   [
     "init",
-    "Usage: init --root <path> --name <task name> [--state <state>] [--input <file|->]\nInput: Goal and Next useful action required; the seven Current Context headings are accepted. Use --input - to read Markdown fragments from stdin.",
+    "Usage: init --root <path> --name <task name> [--input <file|->]\nInput: Goal and Next useful action required; the seven Current Context headings and Recovery sources are accepted, and every line must sit under one of them. The record starts active. Use --input - to read Markdown fragments from stdin.",
   ],
   ["view", "Usage: view resume|full --record <record.md>"],
   ["validate", "Usage: validate --record <record.md>"],
   [
     "slice propose",
-    "Usage: slice propose --record <record.md> --title <title> --input <file|->\nInput: Intended result required; Type, Expected evidence, and Dependencies optional. Use --input - to read the fragment from stdin.",
+    "Usage: slice propose --record <record.md> --title <title> --input <file|->\nInput: Intended result required; Type, Expected evidence, and Dependencies optional. Commands set State; input never includes it. Use --input - to read the fragment from stdin.",
   ],
   [
     "slice start",
@@ -93,9 +98,13 @@ const COMMAND_HELP = new Map([
     "slice reopen",
     "Usage: slice reopen --record <record.md> --id <S-NNN> --next-action <text> --input <file|->\nInput: fresh Authority source, Scope, Expected evidence, Stop condition, and Starting state required. Use --input - to read the fragment from stdin.",
   ],
+  [
+    "slice record",
+    "Usage: slice record --record <record.md> --title <title> --state <completed|blocked|abandoned> --input <file|->\nRecords a Slice that finished before it could be recorded, directly into History. The Current Slice, Future Work, and Next useful action are unchanged; the ID follows recording order and the command adds Recorded: retroactively on <today>.\nInput: Occurred (YYYY-MM-DD or YYYY-MM-DD to YYYY-MM-DD), Intended result, Authority source, Result, Evidence and limits, and Task effect required; Type and Residual effects optional; Resume when required for blocked; Reason required for abandoned. Use --input - to read the fragment from stdin.",
+  ],
   [
     "checkpoint propose",
-    "Usage: checkpoint propose --record <record.md> --title <title> --input <file|->\nInput: Type, Condition, and Applies to required. Use --input - to read the fragment from stdin.",
+    "Usage: checkpoint propose --record <record.md> --title <title> --input <file|->\nInput: Type (preserve, publish, review, decision, or continuity), Condition, and Applies to required. Use --input - to read the fragment from stdin.",
   ],
   [
     "checkpoint activate",
@@ -123,7 +132,9 @@ const COMMAND_HELP = new Map([
 ]);
 
 function commandHelp(command, operation) {
-  return `${COMMAND_HELP.get([command, operation].filter(Boolean).join(" ")) ?? COMMAND_HELP.get(command) ?? usage()}\n`;
+  const help = COMMAND_HELP.get([command, operation].filter(Boolean).join(" ")) ?? COMMAND_HELP.get(command);
+  if (!help) return `${usage()}\n`;
+  return command === "init" ? `${help}\n` : `${help}\n${ROOT_HELP}\n`;
 }
 
 class CliError extends Error {
@@ -159,7 +170,7 @@ function parseOptions(args) {
 function allowedOptions(command, operation) {
   const common = new Set(["--root", "--record", "--input", "--help"]);
   const withNextAction = new Set([...common, "--next-action"]);
-  if (command === "init") return new Set(["--root", "--name", "--state", "--input", "--help"]);
+  if (command === "init") return new Set(["--root", "--name", "--input", "--help"]);
   if (command === "view") return new Set(["--root", "--record", "--view", "--help"]);
   if (command === "validate") return new Set(["--root", "--record", "--help"]);
   if (command === "slice") {
@@ -169,6 +180,7 @@ function allowedOptions(command, operation) {
     if (operation === "resume") return new Set([...withNextAction, "--resolution"]);
     if (operation === "close") return new Set([...withNextAction, "--state"]);
     if (operation === "reopen") return new Set([...withNextAction, "--id", "--title"]);
+    if (operation === "record") return new Set([...common, "--title", "--state"]);
   }
   if (command === "checkpoint") {
     if (operation === "propose") return new Set([...common, "--title"]);
@@ -202,7 +214,14 @@ function requireOption(options, name) {
 }
 
 function rootOption(options) {
-  return options["--root"] ?? cwd();
+  if (options["--root"]) return options["--root"];
+  const record = options["--record"];
+  if (record && isAbsolute(record)) {
+    const marker = `${sep}.freeflow${sep}tasks${sep}`;
+    const index = record.lastIndexOf(marker);
+    if (index > 0) return record.slice(0, index);
+  }
+  return cwd();
 }
 
 function initialContent(skeletonLines, input) {
@@ -217,15 +236,20 @@ function initialContent(skeletonLines, input) {
     "Open",
     "Current direction",
     "Boundaries",
+    "Recovery sources",
     "Next useful action",
   ];
   const allowed = new Set(names);
+  let seenHeading = false;
   for (let index = 0; index < inputLines.length; index += 1) {
     const levelThree = /^### (.+?)\s*$/.exec(inputLines[index]);
+    if (!levelThree && !seenHeading && inputLines[index].trim() !== "")
+      throw new CliError(`Initialization text outside a heading would be lost: ${inputLines[index].trim()}`);
     if (levelThree) {
       const name = levelThree[1];
       if (!allowed.has(name)) throw new CliError(`Unknown initialization heading: ${name}`);
       if (targets.has(name)) throw new CliError(`Duplicate initialization heading: ${name}`);
+      seenHeading = true;
       const content = [];
       for (let next = index + 1; next < inputLines.length; next += 1) {
         if (/^### /.test(inputLines[next]) || /^## /.test(inputLines[next])) break;
@@ -255,10 +279,8 @@ function initialContent(skeletonLines, input) {
 async function initialize(options) {
   const root = rootOption(options);
   const name = requireOption(options, "--name");
-  const state = options["--state"] ?? "active";
-  if (!TASK_STATES.has(state)) throw new CliError(`Invalid task state: ${state}`);
   const input = await readInput(options["--input"], cwd());
-  const text = initialContent(canonicalLines(name, state), input);
+  const text = initialContent(canonicalLines(name), input);
   parseDocument(text);
   const created = await createRecordPath(root, name, slugify(name));
   try {

package/skills/verify-work/SKILL.md

@@ -7,29 +7,35 @@ description: "Use when verifying work or a claim after implementation, tests, bu
 
 Determine what fresh direct evidence establishes about a specific claim at the boundary where it must hold.
 
-Verification establishes facts, not review judgment, authority, or permission to continue. A passing command is not automatically a supported outcome. Test order is not evidence of test validity or implementation correctness.
+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.
+
+## Rules
+
+- Verification establishes facts, not review judgment, authority, or permission to continue. A Supported claim permits judgment of the result; it does not establish a review Pass, close a Slice, or authorize delivery.
+- Never encode a guess as an expected result. When expected behavior is unsettled or sources conflict, return the issue through [Workflow](../../skills/workflow/SKILL.md) or [Decision Gate](../../skills/decision-gate/SKILL.md).
+- Run active checks (tests, reproductions, benchmarks, instrumentation) only when the current agreement covers them. Otherwise return the purpose, observer, expected evidence, and stop condition to Workflow and wait.
+- Never rerun until unfavorable evidence disappears, and never change valid tests, implementation, Specs, policy, or acceptance merely to make a signal green. Preserve failures, contradictions, and partial or reduced-fidelity results.
+- If a revised check establishes less than the original, the original claim stays Inconclusive unless other evidence establishes it at the required boundary; expose that limitation before acceptance rather than carry the stronger claim into the report.
+- Missing evidence is not zero, safe, passed, or probably correct. Never invent a receipt or an earlier failing run that was not observed. If the user skips a check, leave the corresponding claim unverified.
+- Base reports on actual assertions, outputs, and the state examined, not on test names or on the requested work phrased as accomplishments.
 
 ## Establish The Claim And Its Source
 
-Before choosing a check, identify the behavior or property, the required observing boundary, and the source of its expectation. Keep this compact when obvious; do not let an available test silently narrow a broader claim.
+Goal: know exactly what is being claimed, where it must hold, and why it is expected, before choosing a check.
 
-Claims may concern behavior, a reported failure, structural validity, interfaces, integration, host lifecycle, installed artifacts, failure or recovery semantics, performance, or repository state.
+Identify the behavior or property, the required observing boundary, and the source of its expectation. Keep this compact when obvious; do not let an available test silently narrow a broader claim. Claims may concern behavior, a reported failure, structural validity, interfaces, integration, host lifecycle, installed artifacts, failure or recovery semantics, performance, or repository state.
 
 Distinguish required acceptance from an optional stronger assertion. If evidence for an optional claim is unavailable, qualify or withdraw that claim rather than automatically add implementation. A required guarantee remains unresolved until supported or explicitly changed by its owner.
 
-When expected behavior is unsettled or sources conflict, return the issue through [Workflow](../../skills/workflow/SKILL.md) or [Decision Gate](../../skills/decision-gate/SKILL.md). Do not encode a guess as an expected result.
-
 ## Choose Sufficient Evidence
 
-Use the smallest direct observation that can disagree with the claim. Before relying on an unfamiliar fixture for substantial dependent work, establish that it reaches the required observing stage and distinguishes the relevant wrong behavior. Reuse an adequate existing fixture; observer preparation is not a mandatory separate prototype.
-
-For saved evidence, identify what code/artifact, check, configuration, and environment it examined, using existing outputs and source identities where available. Compare relevant subsequent changes, including new files and generated output. HEAD alone does not identify an uncommitted candidate. Reuse results whose applicability remains supported; rerun only affected evidence when authorized. Do not repeat checks merely because another activity or context began.
+Goal: the smallest observation that could actually disagree with the claim, at the right boundary.
 
-Keep two facts separate: the observation occurred, and it applies to the current state. A later edit does not erase an earlier pass; uncertain applicability does not certify the new candidate. Report missing identity or output rather than inventing a receipt or building a new evidence store.
+Use the smallest direct observation that can disagree with the claim. Before relying on an unfamiliar fixture for substantial dependent work, establish that it reaches the required observing stage and distinguishes the relevant wrong behavior. Reuse an adequate existing fixture; observer preparation is not a mandatory separate prototype.
 
-Run active checks only when covered by the current agreement, including contained verification. Otherwise return the purpose, observer, expected evidence, and stop condition to Workflow and wait. A test, reproduction, benchmark, or instrumentation is active evidence generation even before production edits.
+For saved evidence, identify what code or artifact, check, configuration, and environment it examined, using existing outputs and source identities where available. Compare relevant later changes, including new files and generated output; HEAD alone does not identify an uncommitted candidate. Keep two facts separate: the observation occurred, and it applies to the current state. A later edit does not erase an earlier pass, and uncertain applicability does not certify the new candidate. Report missing identity or output rather than building a new evidence store. Reuse results whose applicability remains supported; rerun only affected evidence, and do not repeat checks merely because another activity or context began.
 
-Use [Action Selection](../../skills/action-selection/SKILL.md) when several observers are plausible or the likely interaction is broad. It selects and bounds the interaction; Verify Work retains the claim and interprets support. An already-selected focused check needs no extra tool-selection ceremony.
+Use [Action Selection](../../skills/action-selection/SKILL.md) when several observers are plausible or the likely interaction is broad; Verify Work keeps the claim and interprets support. An already-selected focused check needs no extra selection.
 
 Read the relevant reference before designing or selecting evidence:
 
@@ -40,10 +46,12 @@ Read the relevant reference before designing or selecting evidence:
 
 Browser-performance claims need both browser fidelity and performance methodology. Loading a reference does not expand the required claim.
 
-Passing tests do not prove behavior they do not exercise. Source inspection does not prove runtime execution; a helper call does not prove registration, native dispatch, or installed-package behavior. A happy path does not establish failure handling.
+Passing tests do not prove behavior they do not exercise. Source inspection does not prove runtime execution; a helper call does not prove registration, native dispatch, or installed-package behavior; a happy path does not establish failure handling.
 
 ## Run Without Manufacturing A Signal
 
+Goal: the observation reflects the candidate, not the harness or the schedule.
+
 Before parallel checks, compare what each may write or remove. Serialize checks that share generated directories, caches, outputs, package roots, fixture state, ports, databases, or intentionally stale artifacts. Reproduce a concurrency-induced failure under a non-overlapping schedule before attributing it to production code.
 
 For each covered check:
@@ -52,14 +60,15 @@ For each covered check:
 2. Inspect output, exit status, assertions, and lower-level evidence that could contradict its summary.
 3. Confirm that the intended path ran and the observer matched the claim.
 4. Compare the observation with the independent expectation and its source.
-5. Preserve failures, contradictions, and partial or reduced-fidelity results.
 
-Do not rerun until unfavorable evidence disappears or change valid tests, implementation, Specs, policy, or acceptance merely to make a signal green. Before revising a material assertion after failure, use Test Design to compare what the old and new checks establish. Repair source-backed observer or expectation errors; a weaker replacement leaves the original claim Inconclusive unless other evidence establishes it. Expose that limitation before acceptance rather than carry the stronger claim into the report.
+Before revising a material assertion after failure, use Test Design to compare what the old and new checks establish. Repair source-backed observer or expectation errors.
 
-Tests may be written before or after implementation as the task warrants. No formal test-first sequence is required. If using a failure to support diagnosis or regression claims, actually observe it at the relevant boundary; do not invent an earlier failing run from a later passing test.
+Tests may be written before or after implementation as the task warrants; no test-first sequence is required, and test order is not evidence of validity. When a failure supports a diagnosis or regression claim, actually observe it at the relevant boundary.
 
 ## Classify Execution And Support Separately
 
+Goal: never let a check's outcome stand in for what the evidence proves.
+
 **Check result** describes the selected check's defined assertion:
 
 - **Passed:** it executed validly and the assertion held.
@@ -76,15 +85,15 @@ A check may Pass by observing an expected rejection or failure.
 - **Inconclusive:** available evidence cannot establish or refute it at that boundary.
 - **Unavailable:** required evidence cannot currently be obtained safely or reliably.
 
-A Passed check can leave the claim Inconclusive. A Failed check can expose a defect, invalid expectation, environment problem, or source conflict. Classify only the supported conclusion. Missing evidence is not zero, safe, passed, or probably correct.
-
-If the user skips a check, respect that choice and leave the corresponding claim unverified. Use [Diagnose Failure](../../skills/diagnose-failure/SKILL.md) when contradictions are unexplained or failure repeats.
+A Passed check can leave the claim Inconclusive. A Failed check can expose a defect, an invalid expectation, an environment problem, or a source conflict; classify only the supported conclusion. Use [Diagnose Failure](../../skills/diagnose-failure/SKILL.md) when contradictions are unexplained or failure repeats.
 
 ## Return Evidence To Its Owner
 
-Return the observation and its limits to the activity using the claim. Base the report on actual assertions, outputs, and the state examined—not test names or the requested work phrased as accomplishments. Distinguish implemented behavior, exercised checks, and supported claims; list missing material cases even when the suite passes. Supported verification permits judgment of the result; it does not itself establish review Pass, close a Slice, or authorize delivery.
+Goal: the activity using the claim gets the observation and its limits, and nothing it did not ask for.
+
+Return the observation and its limits to the activity using the claim. Distinguish implemented behavior, exercised checks, and supported claims, and list missing material cases even when the suite passes.
 
-When answering a review Needs evidence item, preserve its pointer, claim, required observing boundary, previous evidence limit, and why the gap mattered. Return the result to the receiving agent for adjudication:
+When answering a review Needs evidence item, preserve its pointer, claim, required observing boundary, previous evidence limit, and why the gap mattered, and return the result to the receiving agent for adjudication:
 
 - Supported may settle the factual gap without settling the review.
 - Contradicted may establish or invalidate a finding or expose a source conflict.