@hassangameryt/freeflow 0.7.3 → 0.8.0

package/skills/evaluate-skill/scripts/pi-guard.mjs

@@ -106,21 +106,36 @@ function buildSubjectSystemPrompt(options, declaredContext) {
     }
     lines.push("</available_skills>");
   }
-  if (declaredContext.length > 0) {
-    lines.push("", "<declared_context>");
-    for (const entry of declaredContext) {
-      lines.push(`  <context declared-path="${escapeXml(entry.declaredPath)}">`);
-      for (const file of entry.files) {
-        lines.push(`    <file path="${escapeXml(file.path)}">\n${file.content}</file>`);
-      }
-      lines.push("  </context>");
+  if (declaredContext.length > 0) lines.push("", renderDeclaredContext(declaredContext));
+  lines.push(`Current working directory: ${options.cwd}`);
+  return lines.join("\n");
+}
+
+function renderDeclaredContext(declaredContext) {
+  const lines = ["<declared_context>"];
+  for (const entry of declaredContext) {
+    lines.push(`  <context declared-path="${escapeXml(entry.declaredPath)}">`);
+    for (const file of entry.files) {
+      lines.push(`    <file path="${escapeXml(file.path)}">\n${file.content}</file>`);
     }
-    lines.push("</declared_context>");
+    lines.push("  </context>");
   }
-  lines.push(`Current working directory: ${options.cwd}`);
+  lines.push("</declared_context>");
   return lines.join("\n");
 }
 
+// "isolated" replaces the host prompt with an evaluator-owned one; "host" keeps the host's own prompt
+// (and anything declared extensions compose onto it) so evidence reflects the production prompt.
+function beforeAgentStartHandler(promptMode, declaredContext) {
+  if (promptMode === "isolated") {
+    return (event) => ({ systemPrompt: buildSubjectSystemPrompt(event.systemPromptOptions, declaredContext) });
+  }
+  return (event) =>
+    declaredContext.length === 0
+      ? undefined
+      : { systemPrompt: `${event.systemPrompt}\n\n${renderDeclaredContext(declaredContext)}` };
+}
+
 export default function registerSkillEvalGuard(pi) {
   const allowedRoots = parseStringArray(process.env.SKILL_EVAL_ALLOWED_ROOTS).map((root) => realpathSync(root));
   const writableRootValue = process.env.SKILL_EVAL_WRITABLE_ROOT;
@@ -128,10 +143,12 @@ export default function registerSkillEvalGuard(pi) {
   const writableRoot = realpathSync(writableRootValue);
   const allowedTools = new Set(parseStringArray(process.env.SKILL_EVAL_ALLOWED_TOOLS));
   const declaredContext = loadDeclaredContext(process.env.SKILL_EVAL_CONTEXT_MANIFEST);
+  const promptMode = process.env.SKILL_EVAL_PROMPT_MODE || "isolated";
+  if (promptMode !== "isolated" && promptMode !== "host") {
+    throw new Error(`SKILL_EVAL_PROMPT_MODE must be isolated or host: ${promptMode}`);
+  }
 
-  pi.on("before_agent_start", (event) => ({
-    systemPrompt: buildSubjectSystemPrompt(event.systemPromptOptions, declaredContext),
-  }));
+  pi.on("before_agent_start", beforeAgentStartHandler(promptMode, declaredContext));
 
   pi.on("tool_call", (event, ctx) => {
     if (!allowedTools.has(event.toolName)) {

package/skills/evaluate-skill/scripts/skill-eval.mjs

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
 
 import { runEvaluation } from "./lib/runner.mjs";
+import { reviewResult } from "./lib/review.mjs";
+import { runTrials } from "./lib/trials.mjs";
 import { renderResult } from "./lib/view.mjs";
 
-const commands = new Set(["run", "view"]);
+const OPTIONS = {
+  run: ["--group", "--variant", "--trials", "--max-cost"],
+  view: ["--group", "--variant"],
+  review: ["--group", "--model", "--thinking"],
+};
 const argv = process.argv.slice(2);
 const [command] = argv;
 
@@ -12,20 +18,30 @@ function printUsage() {
     `Usage:
   skill-eval run <suite-or-group-path> [options]
   skill-eval view <result-id-or-directory> [options]
+  skill-eval review <result-id-or-directory> --model <provider/model> [options]
 
 Commands:
-  run    Execute selected evaluation groups
-  view   Render selected stored evidence
+  run     Execute selected evaluation groups
+  view    Render selected stored evidence or a trial aggregate
+  review  Record an advisory, variant-blind model answer to each group's review questions
 
 Selectors:
   --group <id-or-position>
-  --variant <baseline|candidate>
+  --variant <baseline|candidate>        (run, view)
+
+Run options:
+  --trials <n>        Run n independent complete invocations and record an aggregate
+  --max-cost <total>  Stop starting subjects once host-reported cost reaches the total
+
+Review options:
+  --model <provider/model>   Required reviewer model
+  --thinking <level>         Optional reviewer thinking level
 
 Paths:
   Definition paths resolve from the current working directory.
   Suite group references resolve relative to the suite file.
   Results are stored under <cwd>/.skill-eval/runs/<result-id>.
-  view accepts a stored result ID or an explicit result directory.
+  view accepts a stored result or aggregate ID or an explicit directory.
 
 Selection:
   No selectors choose every suite group and both variants.
@@ -34,8 +50,8 @@ Selection:
 Current run support:
   Description and explicit-body groups with prompt or ordered turns
   Working-tree or Git-backed ordered skills/context; optional fresh fixture copies
-  Description tools: read; body tools: read, write, edit, or declared extension tools
-  Runtime profiles: Pi or PiFlow hosts, ordered immutable extension bundles, environment overrides
+  Description tools: read; body tools: read, write, edit, run_command for declared commands, or declared extension tools
+  Runtime profiles: Pi hosts, isolated or host system prompt, ordered immutable extension bundles, environment overrides
   Deterministic reads, paths, changed paths, text, JSON, tool calls, context observations, and factual comparisons
   Ordered suites run serially and continue after isolated variant, group, or post-processing failures
   Grade-first views show compact criterion details, usage, and result-relative artifact paths
@@ -51,48 +67,112 @@ function fail(message, exitCode = 2) {
 function parseOperation(values) {
   const [target, ...options] = values;
   if (!target) throw new Error(`skill-eval ${command} requires a target`);
-  let group = null;
-  let variant = null;
+  const allowed = OPTIONS[command];
+  const parsed = { group: null, variant: null, trials: null, maxCost: null, model: null, thinking: null };
+  const keys = {
+    "--group": "group",
+    "--variant": "variant",
+    "--trials": "trials",
+    "--max-cost": "maxCost",
+    "--model": "model",
+    "--thinking": "thinking",
+  };
   for (let index = 0; index < options.length; index += 1) {
     const option = options[index];
     const value = options[index + 1];
-    if (option !== "--group" && option !== "--variant") throw new Error(`Unknown option: ${option}`);
+    if (!allowed.includes(option)) throw new Error(`Unknown option: ${option}`);
     if (!value || value.startsWith("--")) throw new Error(`${option} requires a value`);
-    if (option === "--group") {
-      if (group !== null) throw new Error("--group may be supplied only once");
-      group = value;
-    } else {
-      if (variant !== null) throw new Error("--variant may be supplied only once");
-      variant = value;
-    }
+    const key = keys[option];
+    if (parsed[key] !== null) throw new Error(`${option} may be supplied only once`);
+    parsed[key] = value;
     index += 1;
   }
-  return { target, selectors: { group, variant } };
+  let trials = 1;
+  if (parsed.trials !== null) {
+    trials = Number(parsed.trials);
+    if (!/^\d+$/.test(parsed.trials) || trials < 1) throw new Error("--trials must be a positive integer");
+  }
+  let maxCost = null;
+  if (parsed.maxCost !== null) {
+    maxCost = Number(parsed.maxCost);
+    if (!Number.isFinite(maxCost) || maxCost <= 0) throw new Error("--max-cost must be a positive number");
+  }
+  if (command === "review" && parsed.model === null) throw new Error("skill-eval review requires --model");
+  return {
+    target,
+    selectors: { group: parsed.group, variant: parsed.variant },
+    trials,
+    maxCost,
+    model: parsed.model,
+    thinking: parsed.thinking,
+  };
+}
+
+async function withCancellation(run) {
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.once("SIGINT", abort);
+  process.once("SIGTERM", abort);
+  try {
+    return await run(controller.signal);
+  } finally {
+    process.removeListener("SIGINT", abort);
+    process.removeListener("SIGTERM", abort);
+  }
+}
+
+function printResult(result) {
+  process.stdout.write(`Result: ${result.id}\nPath: ${result.path}\nState: ${result.state}\n`);
+}
+
+async function run(operation) {
+  const root = process.cwd();
+  await withCancellation(async (signal) => {
+    if (operation.trials === 1) {
+      const budget = operation.maxCost === null ? null : { maxCost: operation.maxCost, spent: 0, exhausted: false };
+      const result = await runEvaluation(operation.target, operation.selectors, { root, signal, budget });
+      printResult(result);
+      if (result.state !== "complete") process.exitCode = 1;
+      return;
+    }
+    const aggregate = await runTrials(operation.target, operation.selectors, {
+      root,
+      signal,
+      trials: operation.trials,
+      maxCost: operation.maxCost,
+      onTrial: printResult,
+    });
+    process.stdout.write(`Aggregate: ${aggregate.id}\nPath: ${aggregate.path}\nState: ${aggregate.state}\n`);
+    if (aggregate.state !== "complete") process.exitCode = 1;
+  });
+}
+
+async function review(operation) {
+  const outcome = await withCancellation((signal) =>
+    reviewResult(operation.target, operation.selectors, {
+      root: process.cwd(),
+      signal,
+      model: operation.model,
+      thinking: operation.thinking,
+    }),
+  );
+  for (const group of outcome.groups) {
+    process.stdout.write(`Review ${group.id}: ${group.state}${group.artifact ? ` (${group.artifact})` : ""}\n`);
+  }
+  if (outcome.groups.some((group) => group.state === "review-error")) process.exitCode = 1;
 }
 
 if (!command || command === "--help" || command === "-h") {
   printUsage();
-} else if (commands.has(command)) {
+} else if (Object.hasOwn(OPTIONS, command)) {
   try {
     const operation = parseOperation(argv.slice(1));
     if (command === "view") {
       process.stdout.write(await renderResult(operation.target, operation.selectors, { root: process.cwd() }));
+    } else if (command === "review") {
+      await review(operation);
     } else {
-      const controller = new AbortController();
-      const abort = () => controller.abort();
-      process.once("SIGINT", abort);
-      process.once("SIGTERM", abort);
-      try {
-        const result = await runEvaluation(operation.target, operation.selectors, {
-          root: process.cwd(),
-          signal: controller.signal,
-        });
-        process.stdout.write(`Result: ${result.id}\nPath: ${result.path}\nState: ${result.state}\n`);
-        if (result.state !== "complete") process.exitCode = 1;
-      } finally {
-        process.removeListener("SIGINT", abort);
-        process.removeListener("SIGTERM", abort);
-      }
+      await run(operation);
     }
   } catch (error) {
     fail(error instanceof Error ? error.message : String(error), 1);

package/skills/execute-work/SKILL.md

@@ -9,8 +9,22 @@ Produce the agreed concrete result through supported preparation, bounded execut
 
 Workflow establishes the work agreement and coordinates authority, ownership, and the user-facing return boundary. Execute Work owns implementation preparation and continuation within it. Task memory belongs to Track Work; governing choices remain with the user.
 
+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
+
+- Stay inside the work agreement. An agreement to return a plan does not cover production edits. Before adopting a new requirement, scope, compatibility, persistence, evidence, or return boundary, return to [Workflow](../workflow/SKILL.md).
+- Never cross a selected checkpoint or separately controlled boundary while it is due and unresolved.
+- Never rewrite tests, Specs, Plans, policies, or acceptance merely to make implementation pass.
+- Return undefined consequential behavior to its owner rather than encode a guess.
+- When a Working Record exists, record the Current Slice through [Track Work](../track-work/SKILL.md) before its first effect.
+- Never promote exploratory code into production, invent acceptance, or claim integration that was not observed.
+- Build the report from inspected resulting files, assertions, and outputs, not from requested changes phrased as accomplishments. Do not add cleanup, documentation, migration, deprecation, commit, push, integration, release, or launch merely because it would be useful.
+
 ## Establish The Execution Basis
 
+Goal: before any effect, you know which assignment applies, what it requires, and how its result will be checked.
+
 Consume the current request, accepted discussion, governing artifacts, and relevant live state. Establish which assignment and stopping condition currently apply; do not combine older directions with a superseding contract. Resolve material ambiguity before dependent effects. Do not restart discovery because execution was selected.
 
 Before production changes, establish:
@@ -20,22 +34,26 @@ Before production changes, establish:
 - **Evidence:** a check or observation capable of disagreeing with the result.
 - **Agreement:** covered effects, extent of work, and when to return to the user.
 
-Before effects, check whether a selected checkpoint or separately controlled boundary is already due. Do not cross it while unresolved.
+Before effects, check whether a selected checkpoint or separately controlled boundary is already due.
 
 If the agreement is materially unclear, return to [Workflow](../workflow/SKILL.md) before the unsettled execution. A clear request may already establish it; do not ask again merely to perform a ritual.
 
-An agreement to fix a bug can cover investigation before the remedy is known. An agreement to return a plan does not cover production edits. Distinguish evidence gathering from implementation even when both are authorized.
+An agreement to fix a bug can cover investigation before the remedy is known. Distinguish evidence gathering from implementation even when both are authorized.
 
 Use [Discuss](../discuss/SKILL.md) when outcome or material approach alternatives need reconsideration, [Decision Gate](../decision-gate/SKILL.md) for one blocking user-owned choice or source conflict, and [Diagnose Failure](../diagnose-failure/SKILL.md) when the cause is unsupported.
 
 ## Gather Enough Context For This Unit
 
-Choose the next coherent result, then identify what is missing to implement and check it. Reuse current supported sources; inspect only the live boundaries whose freshness matters.
+Goal: implementation starts from understanding, not from guesses, without researching more than the work needs.
+
+Start from the route and context prepared before execution ([Workflow](../workflow/SKILL.md)); gather here only what the route could not predict. Choose the next coherent result, then identify what is missing to implement and check it. Reuse current supported sources; inspect only the live boundaries whose freshness matters.
 
 Find the relevant mechanism, callers, contracts, and observing seam before changing them. Do not begin substantial implementation from a guessed API, ownership boundary, or failure cause. Do not read every file or settle every later Slice merely to avoid all uncertainty.
 
 Readiness means you can explain what will change, why it should produce the accepted result, and how the result will be checked. It does not require knowing every line or helper in advance. If an unfamiliar fixture or observing stage could invalidate substantial dependent work, establish that observer first through a bounded investigation. Reuse adequate fixtures; do not make a separate prototype mandatory.
 
+For substantial dependent work, make a compact, usually internal forecast of the known changes that belong together, their supported order, and the earliest observation that could invalidate further work. Keep outcome-dependent steps conditional, and proceed with settled work without replanning after routine tool calls. When material feedback changes the basis, revise only the affected part while preserving the accepted outcome. Skip the forecast for straightforward local work; do not enumerate future tool calls.
+
 Before substantial implementation, read [Design for Depth](../design-for-depth/SKILL.md) and use its Implementation Decisions method when unresolved representation, identity, ownership, algorithm, or failure choices could invalidate significant dependent work. Reuse applicable design decisions already supplied; distinguish required constraints, suggested mechanisms, and local freedom. A reference to a design is not enough when its relevant content is unavailable. Resolve the consequential unknown, not every future coding detail.
 
 Use [Action Selection](../action-selection/SKILL.md) when choosing the next source, observer, or effect is uncertain, broad, or repetitive. Stop gathering when the current unit is sufficiently supported. A mechanical read of a known caller or signature can remain inside execution; discovering an invalidated mechanism requires re-entry before dependent edits.
@@ -44,16 +62,20 @@ When specialized guidance is needed, read [Domain Skill Composition](../workflow
 
 ## Keep The Unit Coherent
 
+Goal: each unit of work produces one checkable result with a manageable working set.
+
 A bounded action produces one useful execution or learning result with a checkable claim. It may contain several files, tools, edits, and checks. Do not fragment it by command, file, test, or method change.
 
 Choose work that can be understood, executed, checked, and corrected with a manageable working set. Split when dependencies, uncertainty, or distinct outcomes make one attempt unreliable; retain enough understanding of later constraints to avoid an obvious dead end.
 
-When a Working Record exists, use [Track Work](../track-work/SKILL.md) for recovery and write-ahead Current Slice state before Slice execution. Preserve useful provisional remaining work and dependencies through its existing fields. Do not create memory for a short direct result merely because execution began.
+When a Working Record exists, use Track Work for recovery and write-ahead Slice state. Preserve useful provisional remaining work and dependencies through its existing fields. At meaningful boundaries, record results with an identity, such as a commit SHA or document version, in the Slice's Material updates, and add Recovery sources as the work reveals what a resume would need. Do not create memory for a short direct result merely because execution began.
 
 Read [Execute Work Edges](references/execute-work-edges.md) when resuming uncertain prior work, changing a Slice boundary, reaching a selected checkpoint, or exposing separately controlled follow-on work.
 
 ## Execute Through One Suitable Method
 
+Goal: the accepted result, produced by the simplest method that fits, with accepted behavior intact.
+
 Implement the supported approach directly when the outcome and mechanism are understood. Unfamiliar work may need preparation first; it does not automatically require a separate prototype or a test-first implementation sequence.
 
 Use one primary method at a time:
@@ -63,24 +85,28 @@ Use one primary method at a time:
 - specialized domain guidance when the environment or risk needs it;
 - a bounded learning action when an empirical uncertainty must be resolved before production work.
 
-Preserve accepted behavior, failure semantics, repository conventions, and source truth. Do not rewrite tests, Specs, Plans, policies, or acceptance merely to make implementation pass.
+Preserve accepted behavior, failure semantics, repository conventions, and source truth.
 
-Allow local choices of helpers, editing order, and focused checks while the agreed result and effects remain unchanged. Handle edge cases required by accepted behavior, direct evidence, or material safety; return undefined consequential behavior rather than encode a guess.
+Allow local choices of helpers, editing order, and focused checks while the agreed result and effects remain unchanged. Handle edge cases required by accepted behavior, direct evidence, or material safety.
 
 For an unfamiliar design boundary that could invalidate later work, establish its first coherent implementation and distinguishing observation before dependent expansion. Compare the actual ownership, identity, ordering, and failure behavior with the selected design—not merely its proposed filenames. Preserve accepted predicates when a sketch proves wrong; stop dependent effects and resolve the affected mechanism through the current owner. Supported local improvements need no automatic handback or separate review.
 
 ## Execute A Bounded Learning Action
 
+Goal: answer the declared question with the least building that can answer it.
+
 Consume the declared question, observer, permitted effects, expected evidence, and return condition. If they are insufficient for safe execution, establish the missing basis through the requesting owner before acting. Do not assume Discuss was previously used or repeat framing that is already adequate.
 
 Build and run only what the observation needs. Correct an understood local observer defect within scope. Before adding scaffolding or a dependency, check whether it serves the current observation or implements a future product. Return before materially expanding effects or pursuing a different question.
 
 Stop when the question is answered or the observing limit is reached. Report support, contradiction, inconclusive evidence, or unavailable evidence honestly; do not keep polishing the prototype to manufacture a favorable result.
 
-Return evidence, limits, exploratory artifacts, and residual effects to the owner that asked the question, following the agreed artifact disposition. Do not silently promote exploratory code into production, invent acceptance, or claim unobserved integration. The receiving owner assesses what the finding changes and which next action is supported and authorized.
+Return evidence, limits, exploratory artifacts, and residual effects to the owner that asked the question, following the agreed artifact disposition. The receiving owner assesses what the finding changes and which next action is supported and authorized.
 
 ## Re-enter When The Basis Changes
 
+Goal: stop building on a basis that no longer holds, and return only as far as the change requires.
+
 Do not continue merely because implementation has begun.
 
 - Clear local defect and supported remedy -> correct within the same action.
@@ -97,6 +123,8 @@ Preserve unaffected changes and contradictory evidence. An optional improvement
 
 ## Verify And Self-Review The Result
 
+Goal: the result is supported by evidence at the boundary where it will be used, and judged suitable before it is accepted.
+
 Check at the boundary where a result will be accepted or used—not after every edit or command.
 
 1. Run the covered focused checks through the actual behavior or artifact boundary.
@@ -109,14 +137,18 @@ A green check proves only its exercised assertions; a source read does not prove
 
 Independent review is separately selected. A self-review finding does not require a reviewer, and a reviewer suggestion does not authorize another change.
 
+If the result makes existing documentation say something no longer true, such as a user guide, a subsystem doc, or a folder README, correcting it is part of this work: use [Write Docs](../write-docs/SKILL.md). New documentation still needs a request.
+
 ## Continue Or Return
 
+Goal: covered work continues without unnecessary stops, and the report describes exactly what exists.
+
 Continue within the Slice while the next action serves the same outcome, remains covered, and can still be checked coherently. A method change, correction, or verification run does not create or close a Slice.
 
 When durable memory exists, preserve only material changes to understanding, dependencies, scope, evidence, blockers, and the next useful action. Before context loss, record truthful partial state rather than rushing to completion. Resume only after required reconstruction and relevant live-state reconciliation.
 
 Return to Workflow when a distinct Slice is ready, a selected checkpoint is due, the agreement changes, or no useful covered continuation remains. Workflow can select another already-authorized Slice without asking the user again. Internal method returns and delegation handbacks are not the user-facing endpoint.
 
-Stop at the agreed return condition or an uncovered consequential boundary. Do not add cleanup, documentation, migration, deprecation, commit, push, integration, release, or launch merely because it would be useful.
+Stop at the agreed return condition or an uncovered consequential boundary.
 
-Construct the report from inspected resulting files, assertions, and outputs—not requested changes phrased as accomplishments. Distinguish implemented, checked, and still unsupported properties. Account for relevant edits after the checks; do not pair a fresh pass with superseded code or test captures. Reuse applicable evidence and report missing bodies or cases explicitly. A completed action is not automatically a completed Slice, task, or delivery.
+Distinguish implemented, checked, and still unsupported properties. Account for relevant edits after the checks; do not pair a fresh pass with superseded code or test captures. Reuse applicable evidence and report missing bodies or cases explicitly. A completed action is not automatically a completed Slice, task, or delivery.

package/skills/execute-work/references/code-practices.md

@@ -2,6 +2,8 @@
 
 Read this before a bounded action writes or changes code. Follow the repository's language, style, testing, and documentation conventions before generic advice.
 
+This reference is judgment: adapt it to the work. Its binding statements restate [Execute Work](../SKILL.md) or Workflow Rules.
+
 ## Make Intent Legible
 
 - Use names that express domain meaning rather than implementation trivia.

package/skills/execute-work/references/execute-work-edges.md

@@ -2,6 +2,8 @@
 
 Read this when execution resumes from uncertain prior state, changes the Slice boundary, reaches a selected checkpoint, or exposes separately controlled follow-on work.
 
+This reference is judgment: adapt it to the work. Its binding statements restate [Execute Work](../SKILL.md) or Workflow Rules.
+
 The main skill owns the normal bounded-action loop. This reference covers transitions that leave, resume, or constrain that loop.
 
 ## Resume Safely
@@ -48,7 +50,15 @@ Stop before dependent work, use the checkpoint’s owner, and return its result
 - [Handoff](../../handoff/SKILL.md) for selected continuity transfer;
 - [Finish Branch](../../finish-branch/SKILL.md), [Release Work](../../release-work/SKILL.md), or [Launch Work](../../launch-work/SKILL.md) for their separately authorized boundaries.
 
-When durable memory exists, Track Work preserves the checkpoint’s selection, condition, result, and task effect.
+When durable memory exists, Track Work preserves the checkpoint’s selection, condition, result, and task effect. Its Checkpoint types map to these owners:
+
+| Type | Owner |
+| --- | --- |
+| `preserve` | Commit Work |
+| `publish` | Commit Work for a simple push; otherwise Finish Branch or Release Work |
+| `review` | Review Work or Review Artifact |
+| `decision` | Decision Gate |
+| `continuity` | Handoff |
 
 Do not create a checkpoint merely because an action or Slice ended. Do not force a stale checkpoint when its condition, evidence, or protected boundary no longer holds; return the discrepancy for a supported cancellation, replacement, deferral, or revision before dependent work.
 

package/skills/handoff/SKILL.md

@@ -65,7 +65,7 @@ If safe transfer would require inventing intent, approval, evidence, status, or
 
 Follow current core and capability recovery guidance before task action. A handoff's earlier route or profile description is not current runtime state.
 
-1. Read the complete Working Record through `view full` when resuming after context loss or into another context. Do not substitute its `resume` view or the handoff's summary. With intact context, follow Track Work's bounded in-session read guidance.
+1. Read the complete Working Record through `view full` when resuming after context loss or into another context, then the artifacts listed under its `What defines this task` and its Recovery sources. Do not substitute its `resume` view or the handoff's summary. With intact context, follow Track Work's bounded in-session read guidance.
 2. Reconcile the record and handoff with current user direction, defining sources, and the relevant live environment. Follow supersession and corrections without silently reviving historical decisions.
 3. Check important completion, verification, review, commit, and artifact-identity claims against their evidence before repeating them. Reuse adequate current evidence; a transfer alone does not require rerunning every check.
 4. Establish the actual partial state, remaining dependencies, accepted work agreement, current assignment, and next useful action. Resolve contradictory old/new instructions from their sources before acting; do not resume editing when the current unit permits inspection only. Reopen only additional sources whose exact content or freshness changes that action.

package/skills/handoff/references/handoff-templates.md

@@ -140,7 +140,7 @@ Do not copy full reviewer output when a stable pointer exists. A new context or
 
 ## Resume Checklist
 
-- After context loss or transfer into another context, read the complete Working Record through `view full` when one exists. A summary or `resume` projection is not a substitute. Use Track Work's bounded reads for intact-session continuation.
+- After context loss or transfer into another context, read the complete Working Record through `view full` when one exists, then its defining artifacts and Recovery sources. A summary or `resume` projection is not a substitute. Use Track Work's bounded reads for intact-session continuation.
 - Reconcile the record and handoff with current user direction and relevant live state; reopen named source truth where exact meaning or freshness matters.
 - Confirm artifact, environment, commit, and configuration identity where claims depend on them.
 - Check important completion and evidence claims before repeating them; distinguish that a run occurred from whether it applies to the current candidate. Reuse adequate evidence rather than rerun every check merely because a transfer occurred.