@hassangameryt/freeflow 0.5.0 → 0.6.0

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { CommittedResultError } from "./lib/record-store.mjs";
+import { WorkingRecordError, fail } from "./lib/model.mjs";
+import { baseEnvelope, errorItems } from "./lib/result.mjs";
+import { executeCommand, readJsonInput } from "./lib/commands.mjs";
+
+function parseCliArgs(args) {
+  const positionals = [];
+  const options = {};
+  const flags = new Set(["--dry-run", "--help"]);
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (!argument.startsWith("--")) {
+      positionals.push(argument);
+      continue;
+    }
+    const equals = argument.indexOf("=");
+    const key = equals >= 0 ? argument.slice(0, equals) : argument;
+    if (Object.hasOwn(options, key)) fail("duplicate-option", `Option may be supplied once: ${key}`);
+    if (flags.has(key)) {
+      options[key] = true;
+      if (equals >= 0) fail("invalid-option", `${key} does not accept a value`);
+      continue;
+    }
+    const value = equals >= 0 ? argument.slice(equals + 1) : args[++index];
+    if (value === undefined || value.startsWith("--")) fail("missing-option-value", `Option requires a value: ${key}`);
+    options[key] = value;
+  }
+  return { positionals, options };
+}
+function usage() {
+  return `Usage: node skills/track-work/scripts/working-record.mjs <command> [options]
+
+Commands:
+  init     --root <repo> --name <short-name> [--input <json-file|->] [--dry-run]
+  view     --record <record.md> --view <resume|discuss|execute|recent|entity|full> [--entity <id-or-title>]
+  schema   --command <init|update|start|block|resume|reopen|close|unlock|migrate|compress|all> [--help]
+  update   --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
+  start    --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
+  block    --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
+  resume   --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
+  reopen   --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
+  close    --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
+  unlock   --record <record.md> --input <json-file|->
+  migrate  --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
+  compress --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
+  validate --record <record.md>
+  inspect  --record <record.md>
+
+Views emit bounded Markdown text. Other commands emit one JSON result. Existing-record mutations require the current SHA-256. Use --input - to read semantic JSON from stdin.
+`;
+}
+
+export { executeCommand };
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  if (!command || command === "--help" || command === "-h") {
+    process.stdout.write(usage());
+    return;
+  }
+  const { positionals, options } = parseCliArgs(args);
+  if (options["--help"]) {
+    process.stdout.write(usage());
+    return;
+  }
+  const root = options["--root"] ? resolve(options["--root"]) : process.cwd();
+  if (positionals.length > 1) fail("invalid-arguments", "Only one positional record or task path is supported");
+  if (positionals.length === 1 && !options["--record"] && !options["--task"]) options["--record"] = positionals[0];
+  const input = await readJsonInput(options);
+  const result = await executeCommand(command, { root, options, input });
+  if (command === "view" || command === "resume-view") {
+    process.stdout.write(result.view?.content ?? "");
+  } else if (command === "schema") {
+    process.stdout.write(result.content ?? "");
+  } else {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  }
+  if (result.status === "committed-unconfirmed") process.exitCode = 2;
+  else if (result.status === "failed") process.exitCode = 1;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    await main();
+  } catch (error) {
+    if (error instanceof CommittedResultError) {
+      process.stdout.write(`${JSON.stringify(error.result, null, 2)}\n`);
+      process.exitCode = 2;
+    } else {
+      const knownError = error instanceof WorkingRecordError;
+      const command = process.argv[2] ?? null;
+      if (command === "view" || command === "resume-view") {
+        process.stdout.write(`Track Work view failed [${error.code ?? "view-failed"}]: ${error.message}\n`);
+        process.exitCode = error instanceof WorkingRecordError ? error.exitCode : 1;
+      } else if (command === "schema") {
+        process.stdout.write(`Track Work schema failed [${error.code ?? "schema-failed"}]: ${error.message}\n`);
+        process.exitCode = error instanceof WorkingRecordError ? error.exitCode : 1;
+      } else {
+        const result = baseEnvelope(command, command, knownError ? error.record : null);
+        if (!result.record && knownError && error.details?.path) {
+          result.record = {
+            path: error.details.path,
+            confirmation: "unavailable",
+            sha256: error.details.sha256 ?? null,
+            schemaVersion: null,
+            taskState: null,
+            lastUpdated: null,
+            currentSlice: null,
+            unavailable: ["recordProjectionUnavailable"],
+          };
+        }
+        result.errors = errorItems(knownError ? error : new WorkingRecordError("unexpected-error", error.message));
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        process.exitCode = error instanceof WorkingRecordError ? error.exitCode : 1;
+      }
+    }
+  }
+}

package/skills/verify-work/SKILL.md

@@ -7,7 +7,7 @@ description: Use when verifying work or a claim after implementation, tests, bui
 
 Determine whether fresh evidence supports a specific claim at the required observing boundary.
 
-Verification is factual: what ran, what happened, and what that result proves. The active agent owns verification and routes from its result. Reading or invoking this skill changes neither role nor authority; it creates no review judgment or permission to continue.
+Verification is factual: what ran, what happened, and what that result proves. The active agent owns verification and routes from its result. Reading or invoking this skill changes neither role nor authority and creates no review judgment or permission to continue.
 
 ## Name The Claim
 
@@ -28,14 +28,26 @@ Do not let an available check silently narrow a broader claim.
 
 Use the smallest direct evidence that can falsify the claim. Evidence must be fresh for the code, configuration, environment, and artifact being assessed.
 
+Verification inherits the current authority envelope. Existing evidence may be inspected without a new run. Run a new active check only when that envelope covers it directly or as contained verification; otherwise return its purpose, expected evidence, and stop condition to Workflow and wait.
+
+Verify Work owns the claim and required evidence boundary. When several covered observers can falsify the same claim, or the likely check is broad, use [Action Selection](../action-selection/SKILL.md) to choose and bound one environment interaction. It returns the observation; Verify Work interprets and classifies support. Skip it when one exact check is already selected.
+
 Passing tests do not prove behavior they do not exercise. A happy path does not prove failure handling. Source inspection does not prove runtime execution. A helper call does not prove registration, host dispatch, or installed-package behavior.
 
-Read [integration evidence](references/integration-evidence.md) for callback, host-lifecycle, installed-artifact, absence, or mutation-footprint claims. Read [browser runtime evidence](references/browser-runtime-evidence.md) for rendered, interactive, network, accessibility, console, or visual claims. Read [performance evidence](references/performance-evidence.md) for latency, throughput, memory, CPU, bundle, query, or resource claims.
+Before selecting or running evidence:
+
+- read [integration evidence](references/integration-evidence.md) when a claim depends on a registered callback or executor, host lifecycle, producer invocation, fallback protocol, installed package, absence counter, or a check that may mutate shared state;
+- read [browser runtime evidence](references/browser-runtime-evidence.md) when a claim depends on rendered UI, browser behavior, accessibility, client networking, console state, visual output, or browser runtime performance;
+- read [performance evidence](references/performance-evidence.md) when verifying latency, throughput, memory, CPU, bundle, query, rendering, capacity, or resource-regression claims.
+
+For browser-performance claims, read both Browser Runtime Evidence for runtime fidelity and Performance Evidence for workload, baseline, variance, and metrics.
 
 Review may judge whether evidence is sufficient, but review does not prove that behavior occurred.
 
 ## Run And Interpret
 
+Once the selected check is authorized:
+
 1. Run the complete selected check.
 2. Read the relevant output, exit status, and lower-level evidence that can contradict a summary.
 3. Confirm the intended success or failure path and observing boundary were exercised.

package/skills/verify-work/references/browser-runtime-evidence.md

@@ -1,6 +1,6 @@
 # Browser Runtime Evidence
 
-Read this when a claim depends on rendered UI, browser behavior, accessibility, client networking, console state, visual output, or browser performance.
+Read this before selecting or running evidence when a claim depends on rendered UI, browser behavior, accessibility, client networking, console state, visual output, or browser runtime performance.
 
 Use the available browser or DevTools capability for the host. This reference defines evidence quality, not tool-specific commands.
 

package/skills/verify-work/references/integration-evidence.md

@@ -1,6 +1,6 @@
 # Integration Evidence
 
-Use this when a claim depends on a registered callback or executor, host lifecycle, producer invocation, fallback protocol, installed package, absence counter, or checks that may mutate shared state.
+Read this before selecting or running evidence when a claim depends on a registered callback or executor, host lifecycle, producer invocation, fallback protocol, installed package, absence counter, or a check that may mutate shared state.
 
 ## Match The Boundary
 

package/skills/verify-work/references/performance-evidence.md

@@ -1,6 +1,6 @@
 # Performance Evidence
 
-Read this when verifying latency, throughput, memory, CPU, bundle, query, rendering, capacity, or resource-regression claims.
+Read this before selecting or running evidence when verifying latency, throughput, memory, CPU, bundle, query, rendering, capacity, or resource-regression claims.
 
 A faster synthetic operation does not prove the reported path improved. Preserve correctness while measuring representative work.
 

package/skills/workflow/SKILL.md

@@ -1,91 +1,143 @@
 ---
-name: workflow
-description: Use when coordinating discussion, decisions, durable task memory, execution, verification, review, or a route change from feedback.
+name: "workflow"
+description: "Use when authority, ownership, route changes, context recovery, selected checkpoints, or Supported Exit must be coordinated across Freeflow methods."
 ---
 
 # Workflow
 
-Use feedback to choose the smallest useful next action. Treat work as an **Interaction Lifecycle** with an internal **Feedback Loop**, not a fixed sequence.
+Own the outer Interaction Lifecycle. Establish authority, keep one owner for the current bounded activity, route from evidence, and decide when a Supported Exit is justified.
 
-The active agent owns understanding, routing, authorized work, verification, correction, and completion. It adjudicates selected review; independent judgment does not take over workflow control.
+Workflow coordinates methods; it does not replace their detailed jobs. Selecting a skill, tool, artifact, review, or compute profile never widens authority.
 
-Read the [expanded Workflow loop](references/workflow-loop.md) when the complete lifecycle, skill relationships, or exits are unclear. Read [domain skill composition](references/domain-skill-composition.md) when specialized engineering guidance must run inside the active route.
+## Enter Through Authority
 
-## Route The Interaction
+Interpret the whole user turn and still-valid prior approval. Establish or confirm the authority envelope before consequential action.
+
+Classify effects cumulatively:
+
+- **Passive observation:** inspect existing evidence without exercising target behavior or intentionally changing task state.
+- **Active evidence generation:** exercise target behavior to produce new evidence.
+- **Mutation or delivery:** change repository, durable task or session, or external state.
+
+A direct request authorizes its bounded outcome and entailed tools, checks, and reversible local choices. A Spec, Plan, task-memory artifact, review, recommendation, silence, mode, or newly useful evidence does not create authority.
+
+Before an uncovered action, return one bounded proposal:
 
 ```text
-[Entry] -> [Feedback Loop when needed] -> [Supported Exit]
-   ^              ^        |                  |
-   |              |________|                  |
-   |__________________________________________|
-            later user turn or evidence
+Purpose:
+Action:
+Expected evidence or result:
+Stop condition:
 ```
 
-Entry begins with a user turn or new evidence interpreted through the Interaction Contract and effective mode. It may route directly to an answer, wait, deferment, or stop. When work is needed, choose the narrowest owner:
+Ask one direct authorization question and wait. Do not perform the proposed action or a dependent step while waiting.
+
+## Choose One Owner
 
-- **Understand and decide:** [Discuss](../discuss/SKILL.md), [Decision Gate](../decision-gate/SKILL.md), [Bypass](../bypass/SKILL.md), with [Design for Depth](../design-for-depth/SKILL.md) when the direction is design-bearing.
-- **Preserve memory or accepted artifacts:** [Track Work](../track-work/SKILL.md), [Write Spec](../write-spec/SKILL.md), [Write Plan](../write-plan/SKILL.md), and [Review Artifact](../review-artifact/SKILL.md).
-- **Execute and learn:** [Execute Work](../execute-work/SKILL.md), [Migration Work](../migration-work/SKILL.md), [Diagnose Failure](../diagnose-failure/SKILL.md), [Verify Work](../verify-work/SKILL.md), and [Review Work](../review-work/SKILL.md).
-- **Preserve or close out:** [Commit Work](../commit-work/SKILL.md), [Handoff](../handoff/SKILL.md), [Finish Branch](../finish-branch/SKILL.md), [Release Work](../release-work/SKILL.md), and [Launch Work](../launch-work/SKILL.md).
+Choose the narrowest discoverable owner whose job matches the current need:
 
-These are owners, not mandatory phases. Method and domain skills compose inside one active route without overriding accepted behavior, live evidence, or user authority.
+- **Understand and decide:** [Discuss](../discuss/SKILL.md), [Decision Gate](../decision-gate/SKILL.md), or [Bypass](../bypass/SKILL.md), with [Design for Depth](../design-for-depth/SKILL.md) as a lens when direction is design-bearing.
+- **Preserve task state or accepted artifacts:** [Track Work](../track-work/SKILL.md), [Write Spec](../write-spec/SKILL.md), [Write Plan](../write-plan/SKILL.md), or [Review Artifact](../review-artifact/SKILL.md).
+- **Execute and learn:** [Execute Work](../execute-work/SKILL.md), [Migration Work](../migration-work/SKILL.md), [Diagnose Failure](../diagnose-failure/SKILL.md), [Verify Work](../verify-work/SKILL.md), or [Review Work](../review-work/SKILL.md).
+- **Preserve or close out:** [Commit Work](../commit-work/SKILL.md), [Handoff](../handoff/SKILL.md), [Finish Branch](../finish-branch/SKILL.md), [Release Work](../release-work/SKILL.md), or [Launch Work](../launch-work/SKILL.md).
 
-## Authorize Or Wait
+These are owners, not mandatory phases. Keep the current owner while its question, authority, and evidence boundary remain coherent.
 
-Before any state-changing or separately controlled action, identify the bounded action, confirm that the effective mode permits it, and establish its authority source. Authority may come from a clear direct request, explicit approval, or an action or checkpoint explicitly authorized through a user-approved Plan or discussion. An accepted Spec or Plan alone establishes direction, not execution authority. A Working Record may preserve authority but cannot create it.
+Recommend Discuss before authorized work only when user input could materially change the outcome, boundary, tradeoff, approach, or acceptance. Inspect facts and choose reversible local details without asking.
 
-If the action is not covered, recommend its exact purpose and scope, ask one direct authorization question, and wait for the user's response. Waiting means do not perform the proposed mutation, dispatch, or dependent next action. Mode, settled direction, a recommendation, review findings, silence, and task memory do not authorize work.
+When the owner needs an environment interaction and the action or tool choice is not already obvious, use [Action Selection](../action-selection/SKILL.md). Return its observation and state change to the same owner.
 
-Authorization covers the bounded outcome, not each tool call. Do not ask again for contained edits, tests, verification, or reversible local choices. Ask again when the result, scope, evidence boundary, stop condition, or separately controlled action changes.
+Read [Domain Skill Composition](./references/domain-skill-composition.md) when specialized engineering guidance must operate inside the current owner.
 
-Before authorized work begins, recommend Discuss only when user input could materially change the outcome, boundary, tradeoff, approach, or acceptance. Name the question and wait. Use Design for Depth while the direction remains design-bearing. Inspect facts and choose reversible local details without asking. If the user declines optional discussion, do not ask again without new evidence. A discussion recommendation creates no artifact or slice.
+## Run The Feedback Loop
 
-## Run One Feedback Loop
+For each bounded activity:
 
-For one bounded activity:
+1. orient to accepted intent, the authority envelope, relevant task memory, and live evidence;
+2. use the owner to discuss, preserve, implement, observe, verify, or judge;
+3. determine what the result proves at the required evidence boundary;
+4. after initial support, perform the stable self-review once;
+5. correct a clear local defect inside existing authority and re-verify the affected boundary;
+6. otherwise re-enter only the owner whose responsibility changed;
+7. continue only while authority, evidence, checkpoints, and convergence support the route.
 
-1. Orient to accepted intent, relevant task memory, and live evidence.
-2. Use the owning skill to discuss, implement, test, observe, or otherwise act.
-3. Verify what the evidence proves at the required boundary.
-4. When supported, self-review once for alignment, suitability, and unnecessary complexity.
-5. Continue, correct, diagnose, revise, ask, defer, or stop from the result.
+Do not review unsupported work as ready, continue because implementation began, or restart the task because one responsibility changed.
 
-Self-review is silent and creates no formal judgment or cycle. Correct clear local issues within authority, re-verify, then freeze the supported state. Freezing does not itself close a current Track Work slice; selected review, checkpoints, discussion, and accepted in-scope correction may continue inside it. Further polish, advisory warnings, and unrelated issues require another selected slice.
+## Route From Evidence
 
-If verification fails, correct one clear local defect or diagnose an unsupported cause. Do not review unsupported work as ready. Handle only edge cases required by accepted behavior, observed evidence, or material safety. A stream of related patches routes to diagnosis of the shared requirement, cause, ownership, or interface.
+- **Continue:** evidence supports the current owner and authority envelope.
+- **Correct:** one clear local defect preserves accepted intent and effects.
+- **Broaden evidence:** the claim exceeds the current observer.
+- **Diagnose:** a cause is unclear or failure repeats.
+- **Discuss:** options, assumptions, or direction materially changed.
+- **Decision Gate:** a user-owned choice or source conflict blocks progress.
+- **Track Work:** durable task state must be created, reconciled, or recovered.
+- **Revise an artifact:** accepted content, strategy, decision, or handoff changed.
+- **Verify Work:** a material claim needs fresh direct evidence.
+- **Review:** selected judgment is needed after factual support.
+- **Stop or defer:** no safe worthwhile continuation remains.
 
-Continue only while authority remains clear, evidence supports the route, no checkpoint is due, and the work converges.
+Preserve unaffected decisions, artifacts, work, and evidence. New evidence changes the route only where its consequence applies.
 
-## Preserve Necessary State
+## Preserve Continuity Deliberately
 
-When authorized work is concrete and direction is settled, use Track Work to decide whether continuity needs a Working Record, then follow its result to Execute Work or wait. Create durable memory only when forgetting would risk misalignment: a Working Record for living task state, a Spec for stable accepted content, a Plan for ordered strategy, an ADR for a surprising hard-to-reverse decision, or a Handoff for point-in-time transfer.
+Track Work owns a **Working Record** for durable task memory. Decide whether durable task memory is needed before routing to Track Work. Use it when losing decisions, evidence, authority, current work, blockers, or the next useful action could cause later misalignment. Do not create task memory for a short disposable action merely because work occurred.
 
-When an ongoing task resumes after compaction, summarization, clear, resume, or session navigation, read the complete owning Working Record before continuing and compare it with the conversation and live state. Another conversation branch may preserve memory, not authority.
+After compaction, summarization, session navigation, or ownership transfer:
 
-Synchronize durable architecture, plugin, setup, or similar documentation when stabilized behavior or dependent work requires it—not after every slice. Never finish with a known required-doc inconsistency.
+1. use the current runtime state and user turn;
+2. recover the bounded current task view when one exists;
+3. re-read an owning skill whose body is absent when its exact method still matters;
+4. reopen only the accepted artifacts or exact history needed for the next decision;
+5. compare memory with live repository or environment state;
+6. re-establish authority from valid current-session sources.
 
-## Control Reviews And Checkpoints
+When a Working Record exists after context loss, treat its recovery, reconciliation, and mutation as a bounded Track Work activity even when another method owns the surrounding outcome. Read Track Work before the first record operation, begin with its bounded `resume` view, and obtain the current command schema before mutation. Do not read the full record or reconstruct record commands from memory.
 
-A local commit, independent review, correction, follow-up review, push, integration, release, or launch is separately controlled unless existing authority explicitly covers it. At a supported boundary, recommend a local commit only when it materially improves rollback, provenance, handoff, integration, or preservation; a slice ending alone is insufficient. When a useful boundary is unapproved, recommend its exact purpose and scope, then wait; do not stage, edit, dispatch, or cross the boundary from the recommendation.
+A summary, historical skill body, Working Record, Plan, or Handoff preserves context but does not become current authority or live source truth.
 
-Specs and Plans receive separate independent Review Artifact after author self-review. Working Records do not by default. Select independent work review for sensitive, hard-to-reverse, architecture-bearing, strongly interacting, plan-selected, or explicitly requested boundaries—not merely because a slice ended. Reading a review skill does not create independence.
+## Route Reviews And Checkpoints
 
-Independent review ends with **Pass**, **Non-blocking**, **Inconclusive**, or **Blocking**. The active agent adjudicates the items and routes accordingly: proceed, proceed with explicit deferrals, gather missing evidence or a decision, or stop before the blocked boundary.
+Select a checkpoint only when it materially protects dependent work, rollback, provenance, transfer, integration, or delivery. Examples include a user decision, independent review, local commit, handoff, integration, release, or launch. Do not select one merely because work paused or a bounded activity ended.
 
-Review findings are evidence, not commands, and do not authorize edits. Ask once for unapproved corrections plus any warranted focused follow-up, or corrections alone, then wait. A review budget caps dispatches; it does not authorize them. Return implementation corrections to Execute Work and artifact revisions to their owner, verify them, and run a focused follow-up only when needed and authorized. Never create an automatic review-fix-review loop or keep editing merely to obtain Pass.
+Self-review belongs to the Feedback Loop and is not a checkpoint. Use Review Work for implementation or integrated work. Use Review Artifact for a Working Record, Spec, Plan, decision record, handoff, or another durable guide.
 
-## Route And Exit From Evidence
+An independent reviewer reports without editing. The active agent adjudicates every material finding against source truth and evidence:
 
-- **Continue:** evidence supports the current route.
-- **Correct:** one clear local defect preserves intent and scope.
-- **Broaden evidence:** the claim exceeds the check.
-- **Diagnose:** the cause is unclear or failure repeats.
-- **Discuss:** new options or invalid assumptions change direction.
-- **Track Work:** task memory or history must be reconciled.
-- **Revise Spec or Plan:** accepted content, contract, order, mechanism, dependencies, or checks changed.
-- **Decision Gate:** a user-owned choice or source conflict blocks progress.
-- **Stop or defer:** no safe worthwhile continuation remains.
+- **Accept:** the problem is supported and applicable.
+- **Reject:** the item is stale, duplicate, resolved, preference-only, out of scope, or unsupported.
+- **Open:** evidence or a user decision is missing.
+
+Review methods return:
+
+- **Pass:** continue within existing authority.
+- **Non-blocking:** continue with explicit deferrals.
+- **Inconclusive:** obtain the missing evidence or decision.
+- **Blocking:** do not cross the boundary; re-enter the narrowest owner, defer, or stop.
+
+A finding, judgment, suggested remedy, or useful checkpoint does not authorize correction or continuation. Establish the problem, consequence, remedy basis, verification boundary, and authority before acting.
+
+When findings interact, assumptions are challenged, materially different remedies remain, or user input could change the approach, report a problem checkpoint and stop before selecting a remedy.
+
+A local commit, handoff, user decision, integration, push, release, or launch remains separately controlled unless the authority envelope explicitly covers it.
+
+Do not create an automatic review–fix–review loop or keep editing merely to obtain Pass. Review skills own their exact role rules, item taxonomy, evidence lenses, reviewer contracts, reports, and cycle limits.
+
+## Reach A Supported Exit
+
+A Supported Exit may answer, wait, pause, hand off, defer, stop, preserve a controlled boundary, or complete.
+
+Claim completion only when:
+
+- fresh evidence supports the accepted outcome at the required boundary;
+- every completed bounded activity crossed self-review with no unresolved material issue;
+- selected reviews and checkpoints are resolved;
+- task memory and required artifacts are accurate;
+- no material contradiction, source conflict, or user-owned decision remains hidden;
+- no separately controlled action is being implied as complete.
+
+Report the outcome, evidence, proof limits, unresolved gaps, and current route. A recommendation for a next action does not authorize it.
 
-Preserve valid work and revise only the affected layer. A supported exit may answer, wait, pause, hand off, defer, stop, preserve a controlled boundary, or complete the task.
+## Stop
 
-Claim completion only when fresh verification supports the outcome, self-review has no unresolved material issue, selected reviews are resolved, task memory is accurate, required artifacts are synchronized, and no user-owned decision or source conflict remains hidden. Report the outcome, evidence, gaps, and route. Use `Next:` only when one useful recommendation remains; it does not authorize action.
+Stop Workflow when a Supported Exit is reached or one owner can continue without an unresolved authority, ownership, checkpoint, or route question. Resume it only when feedback changes one of those boundaries.

package/skills/workflow/references/domain-skill-composition.md

@@ -1,57 +1,37 @@
 # Domain Skill Composition
 
-Read this when specialized engineering guidance must operate inside a Freeflow route.
+Read this when specialized engineering guidance must operate inside the current Workflow owner.
 
-Freeflow chooses **what owns the current action**. Domain guidance supplies **how to perform the specialized engineering safely**. Do not turn a domain skill into a second workflow.
+Freeflow owns authority, ownership, route changes, evidence honesty, checkpoints, and Supported Exit. Domain guidance supplies specialized engineering method. It does not become another workflow or widen authority.
 
-## Keep Ownership Clear
+## Compose One Owner
 
-Freeflow owns:
+For the current bounded activity:
 
-- effective mode, authority, and route;
-- user decisions and source conflicts;
-- discussion, durable artifacts, slices, and route changes;
-- verification honesty, review calibration, checkpoints, and exits.
+1. keep one Freeflow owner;
+2. add only the domain guidance required by the concrete technology, behavior, or risk;
+3. use one primary implementation or diagnostic method at a time;
+4. add Design for Depth only when direction is already design-bearing or evidence establishes structural pressure;
+5. add independent specialist review only when it materially protects a selected boundary.
 
-Domain guidance may own techniques for frontend, accessibility, browser tools, security, performance, databases, APIs, CI/CD, observability, cloud platforms, migration, release, or deployment.
-
-Domain guidance never overrides accepted behavior, repository policy, owner decisions, failure contracts, or evidence requirements. When it conflicts with live source truth, inspect the conflict and use [Decision Gate](../../decision-gate/SKILL.md) if resolution changes behavior or material risk.
-
-## Compose One Route
+Prefer repository policy and current primary sources over generic examples. Do not load a handbook because one keyword appears.
 
-For one current action:
+## Preserve Boundaries
 
-1. Keep one owning Freeflow skill.
-2. Use [Design for Depth](../../design-for-depth/SKILL.md) as a lens only when the direction is already design-bearing or evidence establishes structural pressure.
-3. Use one primary implementation or diagnostic method at a time, such as [TDD](../../tdd/SKILL.md), [Simplify Code](../../simplify-code/SKILL.md), or [Diagnose Failure](../../diagnose-failure/SKILL.md).
-4. Load only the domain guidance needed for the concrete technology or risk.
-5. Add specialist independent review only when its lens materially protects the selected boundary.
-
-Changing method from evidence does not automatically change the current Track Work slice. Do not load a handbook because one keyword appears. Prefer repository policy and current primary sources over generic examples.
-
-## Common Shapes
+Domain guidance may own techniques for frontend, accessibility, browser tools, security, performance, databases, APIs, CI/CD, observability, cloud platforms, migration, release, or deployment.
 
-```text
-UI change:
-Workflow -> frontend/accessibility guidance -> TDD when useful
--> browser verification
+It never overrides:
 
-Security- or integrity-sensitive work:
-Decision Gate when policy is unsettled -> Design for Depth -> security guidance
--> TDD at the real boundary -> failure-path verification
--> selected security review
+- user-owned product or risk decisions;
+- repository instructions or accepted behavior;
+- the authority envelope;
+- source truth, failure contracts, or evidence requirements;
+- the active owner's stop and return conditions.
 
-Performance regression:
-Diagnose Failure -> profiler/query guidance -> bounded correction
--> representative performance verification
+When domain guidance conflicts with live source truth or accepted intent, return the conflict to Workflow. Use Decision Gate when resolving it changes user-owned behavior or material risk.
 
-CI/CD change:
-Workflow or Plan -> provider/repository guidance -> pipeline verification
--> Launch Work only for separately authorized production rollout
+## Return
 
-Migration:
-Migration Work -> storage/API guidance -> verify each unit
--> Launch Work for separately authorized production cutover
-```
+Return domain results and evidence to the same owner. A method change does not automatically change durable task state, accepted scope, or the current owner.
 
-If no suitable domain skill exists, inspect current primary sources and repository conventions. State expertise or environment limits rather than inventing a universal checklist.
+If no suitable domain guidance exists, inspect current primary sources and repository conventions. State expertise or environment limits rather than inventing a universal checklist.

package/skills/write-plan/SKILL.md

@@ -57,7 +57,7 @@ Each slice should produce a coherent result that can be checked. A validation st
 
 ## Select Useful Checkpoints
 
-Every meaningful slice is verified and silently self-reviewed during execution; do not restate that default unless its evidence boundary is unusual.
+During execution, every bounded activity is verified and silently self-reviewed before its result is accepted, reused, or claimed complete; do not restate that default unless its evidence boundary is unusual.
 
 At meaningful slice, phase, integration, risk, or continuity boundaries, consider independent review, a local commit, a user decision, or a continuity checkpoint. Record only selected checkpoints and their conditions. A slice ending or a fixed count alone does not justify a commit; prefer one when supported work forms a coherent rollback point or the next work may destabilize it.
 

package/skills/write-skill/SKILL.md

@@ -69,13 +69,14 @@ Keep examples general enough to transfer beyond one fixture. Do not turn the bod
 
 ## Add Resources Only When Needed
 
-Read [progressive disclosure](references/progressive-disclosure.md) before adding or reorganizing references and scripts.
+Before adding or reorganizing references and scripts, read [progressive disclosure](references/progressive-disclosure.md) to classify each read as entry-required, activity-required, or conditional. References do not activate independently: `SKILL.md` directs each read at its first useful point, and required means necessary rather than recommended.
 
 Start with one `SKILL.md`. Remove repeated prose and low-value checklists before expanding the file set.
 
-- Add a required reference when normal execution genuinely needs separately owned depth; link it before the dependency is used.
+- Add a required reference when normal execution genuinely needs separately owned depth; state whether it is read at entry or before its normal activity.
 - Add a conditional reference when a distinct branch needs depth that would obscure the normal route; state the observable condition for reading it.
 - Add a script for repeated deterministic work or a feature the skill owns when automation is safer, clearer, or materially less wasteful than retyping it.
+- Make the body instruction and reference introduction name the same read condition; neither may silently narrow or widen it.
 - Link every agent-facing reference, asset, declared dependency, and executable entrypoint from `SKILL.md`; internal implementation modules need not be linked.
 - Keep owned resources inside the skill package unless a declared package dependency is required.
 - Treat unlinked-file inspection as factual inventory, not an automatic defect.

package/skills/write-skill/references/progressive-disclosure.md

@@ -12,10 +12,24 @@ description
 -> required or conditional reference or script
 ```
 
-The description routes the first useful read. `SKILL.md` establishes the job, normal method, necessary terms, and stop conditions. A required resource must be linked before the body relies on it. A conditional resource may rely on language already established by the body.
+The description routes the first useful skill read. `SKILL.md` establishes the job, normal method, necessary terms, and stop conditions, then explicitly directs any reference read. References do not activate independently, and an introduction inside an unread reference cannot activate itself.
 
 Do not hide a definition, rule, or step needed to recognize the normal route in an unannounced reference. That is progressive reconstruction, not disclosure.
 
+## State The Read Point
+
+Use one of three explicit read points:
+
+- **Entry-required:** read before following the skill's normal route.
+- **Activity-required:** read before performing a named activity on the normal route.
+- **Conditional:** read only when an observable branch occurs.
+
+Entry-required and activity-required resources are required references. Conditional resources are conditional references. The word “when” does not determine the class: “When designing a test, read Test Design” is activity-required because test design is normal TDD work.
+
+Do not call a required read recommended or optional. If skipping it preserves correct normal execution, it is not required. Avoid “read when unclear” when the reference teaches how to recognize or make the underlying decision; either make the read activity-required or keep enough recognition guidance in `SKILL.md`.
+
+The body instruction and reference introduction must describe the same read point. An introduction may explain purpose, but must not narrow or widen the condition established by `SKILL.md`.
+
 ## Add A Required Reference When
 
 - normal execution genuinely needs separately owned depth;
@@ -23,7 +37,7 @@ Do not hide a definition, rule, or step needed to recognize the normal route in
 - keeping the material inline would obscure the skill’s controlling rules;
 - the dependency is delivered and validated with the skill package.
 
-Required does not mean implicit. The body must say when to read the resource and must not act as if unread content were already known.
+Required does not mean implicit or merely recommended. The body must command the read at entry or before the named normal activity and must not act as if unread content were already known.
 
 ## Add A Conditional Reference When
 
@@ -32,7 +46,7 @@ Required does not mean implicit. The body must say when to read the resource and
 - the active body can name an observable condition for reading it;
 - the reference has one clear job and does not restate the full skill or Workflow.
 
-Keep compact examples that teach the normal boundary in `SKILL.md`. Move a larger example set only when it serves a conditional branch and would obscure the normal route.
+The condition must be observable before the read. Keep compact examples that teach the normal boundary in `SKILL.md`. Move a larger example set only when it serves a conditional branch and would obscure the normal route.
 
 ## Add A Script When