@hassangameryt/freeflow 0.8.0 → 0.9.0

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

@@ -1,181 +0,0 @@
-import { createHash } from "node:crypto";
-import { lstatSync, readFileSync, realpathSync } from "node:fs";
-import path from "node:path";
-
-const PATH_TOOLS = new Set(["read", "write", "edit"]);
-
-function parseStringArray(value) {
-  try {
-    const parsed = JSON.parse(value ?? "[]");
-    return Array.isArray(parsed) && parsed.every((entry) => typeof entry === "string") ? parsed : [];
-  } catch {
-    return [];
-  }
-}
-
-function isContained(root, target) {
-  const relative = path.relative(root, target);
-  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
-}
-
-function resolveWritablePath(cwd, requested) {
-  const absolute = path.resolve(cwd, requested);
-  /** @type {string[]} */
-  const missingSegments = [];
-  let candidate = absolute;
-  while (true) {
-    try {
-      return path.join(realpathSync(candidate), ...missingSegments);
-    } catch {
-      try {
-        lstatSync(candidate);
-        throw new Error(`Existing writable path cannot be resolved: ${requested}`);
-      } catch (error) {
-        if (error?.code !== "ENOENT" && error?.code !== "ENOTDIR") throw error;
-      }
-      const parent = path.dirname(candidate);
-      if (parent === candidate) throw new Error(`Cannot resolve writable path: ${requested}`);
-      missingSegments.unshift(path.basename(candidate));
-      candidate = parent;
-    }
-  }
-}
-
-function escapeXml(value) {
-  const entities = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" };
-  return value.replace(/[&<>"']/g, (character) => entities[character]);
-}
-
-function loadDeclaredContext(manifestPath) {
-  if (!manifestPath) return [];
-  let manifest;
-  try {
-    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-  } catch (error) {
-    throw new Error(
-      `Declared context manifest cannot be read: ${error instanceof Error ? error.message : String(error)}`,
-    );
-  }
-  if (manifest?.schema_version !== 1 || !Array.isArray(manifest.entries)) {
-    throw new Error("Declared context manifest must use schema_version 1 and contain entries");
-  }
-  for (const entry of manifest.entries) {
-    if (typeof entry?.declaredPath !== "string" || !Array.isArray(entry.files)) {
-      throw new Error("Declared context manifest entry is malformed");
-    }
-    for (const file of entry.files) {
-      if (
-        typeof file?.path !== "string" ||
-        typeof file.sha256 !== "string" ||
-        typeof file.content !== "string" ||
-        createHash("sha256").update(file.content).digest("hex") !== file.sha256
-      ) {
-        throw new Error(`Declared context file is malformed or changed: ${file?.path ?? "unknown"}`);
-      }
-    }
-  }
-  return manifest.entries;
-}
-
-function buildSubjectSystemPrompt(options, declaredContext) {
-  const tools = options.selectedTools ?? [];
-  const toolLines = tools.map((tool) => `- ${tool}: ${options.toolSnippets?.[tool] ?? "Declared evaluation tool"}`);
-  const lines = [
-    "You are an expert coding assistant operating inside pi, a coding agent harness.",
-    "Help the user with the task using only the tools and resources listed below.",
-    "",
-    "Available tools:",
-    ...(toolLines.length > 0 ? toolLines : ["(none)"]),
-    "",
-    "Guidelines:",
-    "- Use read to load a skill's SKILL.md when the task matches its description.",
-    "- Resolve relative skill resources from the skill directory.",
-    "- Be concise in your response.",
-  ];
-  const skills = (options.skills ?? []).filter((skill) => !skill.disableModelInvocation);
-  if (skills.length > 0) {
-    lines.push("", "<available_skills>");
-    for (const skill of skills) {
-      lines.push(
-        "  <skill>",
-        `    <name>${escapeXml(skill.name)}</name>`,
-        `    <description>${escapeXml(skill.description)}</description>`,
-        `    <location>${escapeXml(skill.filePath)}</location>`,
-        "  </skill>",
-      );
-    }
-    lines.push("</available_skills>");
-  }
-  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("  </context>");
-  }
-  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;
-  if (!writableRootValue) throw new Error("SKILL_EVAL_WRITABLE_ROOT is required");
-  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", beforeAgentStartHandler(promptMode, declaredContext));
-
-  pi.on("tool_call", (event, ctx) => {
-    if (!allowedTools.has(event.toolName)) {
-      return { block: true, reason: `Tool is not declared for this evaluation: ${event.toolName}` };
-    }
-    if (!PATH_TOOLS.has(event.toolName)) return undefined;
-    if (typeof event.input?.path !== "string") {
-      return { block: true, reason: `${event.toolName} requires a path inside the evaluation environment` };
-    }
-
-    const requested = event.input.path.startsWith("@") ? event.input.path.slice(1) : event.input.path;
-    let canonical;
-    try {
-      canonical =
-        event.toolName === "write"
-          ? resolveWritablePath(ctx.cwd, requested)
-          : realpathSync(path.resolve(ctx.cwd, requested));
-    } catch {
-      return {
-        block: true,
-        reason: `${event.toolName} path cannot be resolved inside the evaluation environment: ${requested}`,
-      };
-    }
-    const roots = event.toolName === "read" ? allowedRoots : [writableRoot];
-    if (!roots.some((root) => isContained(root, canonical))) {
-      return { block: true, reason: `${event.toolName} path escapes the evaluation environment: ${requested}` };
-    }
-    return undefined;
-  });
-}

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

@@ -1,182 +0,0 @@
-#!/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 OPTIONS = {
-  run: ["--group", "--variant", "--trials", "--max-cost"],
-  view: ["--group", "--variant"],
-  review: ["--group", "--model", "--thinking"],
-};
-const argv = process.argv.slice(2);
-const [command] = argv;
-
-function printUsage() {
-  process.stdout.write(
-    `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 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>        (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 or aggregate ID or an explicit directory.
-
-Selection:
-  No selectors choose every suite group and both variants.
-  --group is invalid for a direct group definition or result.
-
-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, 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
-`,
-  );
-}
-
-function fail(message, exitCode = 2) {
-  process.stderr.write(`${message}\n`);
-  process.exitCode = exitCode;
-}
-
-function parseOperation(values) {
-  const [target, ...options] = values;
-  if (!target) throw new Error(`skill-eval ${command} requires a target`);
-  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 (!allowed.includes(option)) throw new Error(`Unknown option: ${option}`);
-    if (!value || value.startsWith("--")) throw new Error(`${option} requires a value`);
-    const key = keys[option];
-    if (parsed[key] !== null) throw new Error(`${option} may be supplied only once`);
-    parsed[key] = value;
-    index += 1;
-  }
-  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 (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 {
-      await run(operation);
-    }
-  } catch (error) {
-    fail(error instanceof Error ? error.message : String(error), 1);
-  }
-} else {
-  fail(`Unknown command: ${command}`);
-}

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

@@ -1,78 +0,0 @@
-# Execute Work Edges
-
-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
-
-Recover the source that established the accepted work and compare it with relevant live state.
-
-When durable memory exists, enter [Track Work](../../track-work/SKILL.md) and use its required recovery route before relying on or mutating the Working Record. Memory preserves context; it does not prove live state or recreate authority.
-
-Resume the same Slice only while its intended result, authority, evidence boundary, and stop condition remain coherent. Otherwise preserve supported work and return the changed boundary to [Workflow](../../workflow/SKILL.md).
-
-Recover the user-facing return condition separately from the next internal action. A supported record may preserve approval for the remaining task, but a proposed next action is not that approval. After reconstruction, continue covered work rather than returning solely because a context boundary occurred.
-
-Do not restart discovery, repeat supported work, or infer progress from summaries, Plans, records, handoffs, staged files, or partial artifacts.
-
-## Distinguish Adaptation From Boundary Change
-
-Routine changes to local mechanics, implementation order, tools, and focused checks remain inside the current bounded action when they preserve:
-
-- the accepted result;
-- permitted effects;
-- source truth;
-- the required observing boundary;
-- the stop condition.
-
-A mechanical read of a known caller or a local correction may remain inside execution. If new evidence invalidates the implementation premise, stop dependent edits and re-establish the approach; do not hide renewed investigation inside a patch stream.
-
-Before following a new prerequisite, identify whether it blocks the required outcome, the chosen approach, or only the current observer. Preserve acceptance, compare supported in-scope remedies, and return to Workflow when the remedy changes behavior, scope, persistence, compatibility, public interfaces, risk, evidence quality, or another user-owned outcome.
-
-Keep an accepted extension in the current Slice only when its result remains coherent, explicit authority covers the added effects, and the combined boundary can still be verified as one unit. When a Working Record exists, Track Work records the extension before execution.
-
-Use another Slice when the work has a distinct result, authority source, evidence boundary, independently useful outcome, or explicit abandonment of the original result. Context pressure may require an earlier safe continuation boundary without inventing a completed result or new Slice.
-
-A whole-task agreement may already cover later Slices. Return their selection and lifecycle to Workflow and Track Work without requesting redundant user permission. A selected checkpoint or the agreed user-facing endpoint still stops dependent work.
-
-## Route A Selected Checkpoint
-
-A checkpoint is due only when Workflow, an approved Plan, repository policy, or explicit discussion selected it.
-
-Stop before dependent work, use the checkpoint’s owner, and return its result to Workflow:
-
-- [Decision Gate](../../decision-gate/SKILL.md) for a selected user decision;
-- [Review Work](../../review-work/SKILL.md) for selected independent judgment;
-- [Commit Work](../../commit-work/SKILL.md) for an authorized local commit;
-- [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. 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.
-
-## Separate Follow-On Work
-
-Useful follow-on work is not implied authority.
-
-Return it to Workflow before using:
-
-- Commit Work for an unselected commit or push;
-- [Migration Work](../../migration-work/SKILL.md) for consumer, state, or traffic movement;
-- Finish Branch for integration, preservation, discard, or branch cleanup;
-- Release Work for versioned publication;
-- Launch Work for production exposure, rollback, or recovery;
-- Handoff for point-in-time continuation transfer.
-
-Preserve the supported execution result before routing away. A follow-on owner does not retroactively change the completed action or Current Slice.

package/skills/finish-branch/SKILL.md

@@ -1,117 +0,0 @@
----
-name: finish-branch
-description: Use when deciding how to integrate, preserve, or discard work on a branch or isolated checkout.
----
-
-# Finish Branch
-
-Close a branch or isolated checkout without confusing readiness, integration, publication, and cleanup authority.
-
-A verified branch does not authorize merge or push. A chosen integration route does not automatically authorize branch deletion, worktree removal, release, or deployment.
-
-## Inspect The Exact State
-
-Before offering or executing a route, inspect:
-
-- current branch, detached state, repository root, and worktree ownership;
-- base branch or merge base supported by repository evidence;
-- commits and diff relative to the base;
-- staged, unstaged, and untracked work;
-- upstream, remote, and ahead/behind state;
-- fresh verification, silent self-review, and any selected independent-review status;
-- CI, policy, or repository gates relevant to the intended route.
-
-Do not infer the base, remote destination, pull-request target, or workspace owner when the wrong choice could lose work or affect collaborators.
-
-After inspecting branch, base, remote, dirty state, verification, and workspace ownership, read [integration options](references/integration-options.md) before choosing local integration, pull request, preservation, discard, or cleanup. Use [Commit Work](../commit-work/SKILL.md) when the selected route requires a local commit or simple push; do not commit merely to make branch status look finished.
-
-Use [Release Work](../release-work/SKILL.md) for a separately approved versioned release and [Launch Work](../launch-work/SKILL.md) for a separately approved production deployment or rollout.
-
-## Keep Route Authority Explicit
-
-Loading this skill, asking whether a branch is ready, or approving a general implementation Plan does not authorize merge, rebase, push, pull-request creation, branch deletion, worktree removal, discard, force push, release, or deployment.
-
-The user owns whether to:
-
-- integrate locally and by which repository-supported method;
-- push or create/update a normal or draft pull request;
-- preserve the branch, worktree, or dirty state;
-- discard commits or uncommitted work;
-- delete local or remote branches;
-- rewrite or force-push history;
-- clean up a checkout or worktree.
-
-Present only routes supported by the observed state. Do not force a fixed menu when an option is impossible, unsafe, or irrelevant. Approval of one route covers only the scope shown and accepted.
-
-## State Readiness Honestly
-
-Present a branch as ready for its intended integration boundary only when:
-
-- the accepted branch outcome is clear;
-- intended commits and remaining dirty state are known;
-- fresh direct evidence supports the branch claim;
-- silent self-review has no unresolved material issue;
-- any selected independent review is resolved for the unchanged state;
-- no source conflict, owner decision, required evidence gap, or repository gate blocks the route.
-
-Read [Verify Work](../verify-work/SKILL.md) when matching branch-readiness claims to evidence. A feature-branch pass does not prove the integrated result.
-
-Unverified or failing work may still be preserved, handed off, or shared through an explicitly approved draft route. State the gaps; do not describe it as integration-ready.
-
-## Execute Only The Chosen Route
-
-### Local Integration
-
-- refresh base evidence without overwriting local work;
-- use the repository's accepted merge or rebase policy;
-- stop when a conflict requires a behavior, source, or owner decision;
-- verify the integrated result on the resulting base state;
-- delete branch or worktree state only when cleanup was included in the approved route and integration verification succeeded.
-
-### Pull Request
-
-- inspect remote and upstream state before pushing;
-- push only intended commits to the accepted destination;
-- create or update the pull request using repository conventions;
-- mark incomplete or failing work as draft when that is the approved route;
-- report CI, review, merge, migration, release, or launch requirements still pending;
-- preserve the worktree when iteration or feedback may continue.
-
-A pull-request URL proves creation, not readiness or merge.
-
-### Preserve
-
-Report the branch, worktree, commit and dirty state, evidence status, reason preserved, and next approved route. Read [Handoff](../handoff/SKILL.md) only when continuation needs durable transfer context.
-
-### Discard
-
-Before destructive action, state exactly which commits, paths, branches, worktrees, and remote state would be lost and what remains recoverable. Require explicit confirmation for that concrete scope.
-
-Do not treat “finish,” “clean up,” a menu number, or approval of integration as confirmation for broader destruction.
-
-## Protect Workspace Ownership
-
-Do not remove a worktree, checkout, session, or harness state you did not create or are not authorized to manage. If ownership is unclear, preserve it and report the uncertainty.
-
-Do not run destructive reset, clean, branch deletion, worktree removal, remote deletion, or force push merely to produce a clean status.
-
-## Return Conflicts And Failures
-
-Resolve a conflict locally only when both sides' intended behavior is settled and the resolution is mechanical. Return behavior, source-truth, API, data, security, compatibility, or architecture conflicts to [Workflow](../workflow/SKILL.md).
-
-Use [Diagnose Failure](../diagnose-failure/SKILL.md) when integrated checks fail without a supported cause. Return mixed or unrelated branch contents to [Commit Work](../commit-work/SKILL.md), which owns staging decisions. Preserve branch state before re-entering another owning activity.
-
-## Report The Chosen Outcome
-
-Report:
-
-- branch, base, and selected route;
-- commit and dirty state handled or preserved;
-- integration, push, or pull-request result;
-- verification on the final observed state;
-- selected-review and repository-gate status;
-- cleanup performed or deliberately omitted;
-- unresolved CI, review, migration, release, or deployment work;
-- recoverability and next approved route.
-
-Branch closeout is complete only for the chosen route. A pushed branch is not merged, a merged branch is not released, and a released artifact is not deployed.

package/skills/finish-branch/references/integration-options.md

@@ -1,80 +0,0 @@
-# Integration Options
-
-Read this after inspecting branch, base, remote, dirty state, verification, and workspace ownership and before choosing local integration, pull request, preservation, discard, or cleanup.
-
-## Local Integration
-
-Appropriate when the user wants the branch integrated locally and repository policy permits it.
-
-Before cleanup:
-
-1. preserve or resolve dirty state deliberately;
-2. update base evidence safely;
-3. integrate without rewriting unrelated history;
-4. run the checks that prove the combined result;
-5. inspect final log and status;
-6. remove branch/worktree state only after success.
-
-A feature-branch pass does not prove the merged result.
-
-## Pull Request
-
-Appropriate when review, CI, collaboration, protected branches, or remote integration owns the next gate.
-
-Capture:
-
-- target branch and commit range;
-- intended push/upstream behavior;
-- PR summary and source requirements;
-- verification already run;
-- known residuals, migrations, rollout, or compatibility notes;
-- required reviewers or checks from repo policy.
-
-A draft pull request may preserve or share incomplete work when that route is explicitly approved. State failing or unavailable evidence. Do not claim merge readiness from a pull-request URL alone.
-
-## Keep For Later
-
-Appropriate when work is valid but integration is deferred, feedback is expected, or environment ownership prevents cleanup.
-
-Report:
-
-```text
-Branch / worktree:
-Commit and dirty state:
-Review / verification:
-Reason preserved:
-Next action:
-Stop conditions:
-```
-
-## Discard
-
-Classify what is recoverable before deleting:
-
-- uncommitted changes may be unrecoverable;
-- local commits may be recoverable through reflog for a limited time;
-- pushed commits may affect collaborators;
-- worktrees may be harness-owned;
-- remote branch deletion has a different scope from local cleanup.
-
-Show the exact destructive operations and require explicit confirmation that matches their scope.
-
-## Detached Or Managed Checkouts
-
-Do not assume a detached checkout is disposable. It may be owned by an IDE, CI system, coding harness, or external worktree manager.
-
-Offer only routes supported by that environment, such as creating a named branch, preserving the checkout, exporting a patch, or asking the harness to close it.
-
-## Conflict Handling
-
-Mechanical conflict resolution is safe only when both sides' intended behavior is already settled.
-
-Stop when conflict resolution would choose between:
-
-- competing product or API behavior;
-- changed tests versus changed implementation;
-- incompatible migrations or data ownership;
-- security, privacy, billing, permissions, or compatibility policies;
-- two architecture directions.
-
-Return the conflict and evidence to Workflow. The next route may be review, diagnosis, Decision Gate, Spec revision, or Plan revision—not “take ours” or “take theirs.”