Skip to content

Adonis0123/adonis-skills / skills/agentic-review-handoff

agentic-review-handoff

Verified

Validate pasted review findings before fixes; run same-session automatic Git review-fix-re-review with a headless Reviewer and no redundant confirmation; start fresh-eyes Git diff Review Intake; resume review-loop sessions or packets; get a DecisionConsult from another AI; or run first-principles/DDD/high-cohesion review. Requires Git and review/consult intent; ordinary implementation or commit-only requests do not start a review loop.

scripts/review-loop/repositories.mjs

View on GitHub
/**
 * Packet + runtime filesystem adapters. Durable truth only.
 */
import fs from "node:fs";
import path from "node:path";
import crypto from "node:crypto";
import { execFileSync } from "node:child_process";

export function resolveRepoRoot(cwd = process.cwd()) {
  try {
    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
      cwd,
      encoding: "utf8",
    }).trim();
  } catch {
    throw new Error(`Not a git repository: ${cwd}`);
  }
}

/**
 * Branch identity for packet isolation (frontmatter `branch` value).
 * Attached: case-sensitive full branch name from `git rev-parse --abbrev-ref HEAD`.
 * Detached: `detached:<full HEAD SHA>` (never bare `HEAD`).
 */
export function resolveBranch(repoRoot) {
  const abbrev = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
    cwd: repoRoot,
    encoding: "utf8",
  }).trim();
  if (abbrev === "HEAD") {
    const sha = execFileSync("git", ["rev-parse", "HEAD"], {
      cwd: repoRoot,
      encoding: "utf8",
    }).trim();
    return `detached:${sha}`;
  }
  return abbrev;
}

/** Readable prefix max length for v2 branch slugs (hash carries uniqueness). */
const BRANCH_SLUG_PREFIX_MAX = 48;

/**
 * Legacy v1 slug: lowercase + `/` `\` → `-` (no hash). Used only for dual-read lookup.
 * Detached identity maps to historical `head` (old code used abbrev-ref `HEAD` → lowercased).
 */
export function branchSlugLegacy(branch) {
  const identity = String(branch ?? "");
  if (identity.startsWith("detached:")) return "head";
  return identity.toLowerCase().replace(/[/\\]/g, "-");
}

/**
 * v2 branch directory slug: `<readable-prefix>--<sha256(identity)[0:12]>`.
 * Hash is over the case-sensitive identity (or `detached:<full SHA>`), so
 * feature/payment, feature-payment, Feature/Payment never collide.
 */
export function branchSlug(branch) {
  const identity = String(branch ?? "");
  const hash = crypto
    .createHash("sha256")
    .update(identity, "utf8")
    .digest("hex")
    .slice(0, 12);
  let readable;
  if (identity.startsWith("detached:")) {
    const sha = identity.slice("detached:".length);
    readable = `detached-${sha.slice(0, 12).toLowerCase()}`;
  } else {
    readable = identity
      .toLowerCase()
      .replace(/[/\\]/g, "-")
      .replace(/[^a-z0-9._-]+/g, "-")
      .replace(/^[-.]+|[-.]+$/g, "");
    if (readable.length > BRANCH_SLUG_PREFIX_MAX) {
      readable = readable.slice(0, BRANCH_SLUG_PREFIX_MAX).replace(/-+$/g, "");
    }
    if (!readable) readable = "branch";
  }
  return `${readable}--${hash}`;
}

/** Candidate directory slugs for dual-read (v2 first, then legacy if different). */
export function candidateBranchSlugs(branch) {
  const v2 = branchSlug(branch);
  const legacy = branchSlugLegacy(branch);
  return v2 === legacy ? [v2] : [v2, legacy];
}

export function packetIdFromParts(branch, fileBase) {
  return `${branchSlug(branch)}/${fileBase.replace(/\.md$/, "")}`;
}

export function ensureReviewHandoffLayout(repoRoot) {
  const base = path.join(repoRoot, ".review-handoff");
  const active = path.join(base, "active");
  const archive = path.join(base, "archive");
  const runtime = path.join(base, "runtime");
  for (const d of [base, active, archive, runtime]) {
    fs.mkdirSync(d, { recursive: true });
  }
  ensureExclude(repoRoot);
  return { base, active, archive, runtime };
}

function ensureExclude(repoRoot) {
  try {
    const common = execFileSync("git", ["rev-parse", "--git-common-dir"], {
      cwd: repoRoot,
      encoding: "utf8",
    }).trim();
    const commonAbs = path.isAbsolute(common)
      ? common
      : path.join(repoRoot, common);
    const excludePath = path.join(commonAbs, "info", "exclude");
    fs.mkdirSync(path.dirname(excludePath), { recursive: true });
    let text = "";
    if (fs.existsSync(excludePath)) text = fs.readFileSync(excludePath, "utf8");
    if (
      !text.includes("/.review-handoff/") &&
      !/(^|\n)\.review-handoff\//.test(text)
    ) {
      const nl = text.endsWith("\n") || text.length === 0 ? "" : "\n";
      fs.appendFileSync(excludePath, `${nl}/.review-handoff/\n`);
    }
  } catch {
    // best-effort
  }
}

/**
 * List active packets for branch identity.
 * Dual-read: v2 slug dir + legacy slug dir; keep only files whose frontmatter
 * `branch` exactly equals the current identity (never guess legacy HEAD → detached).
 */
export function listActivePackets(repoRoot, branch) {
  return listPacketsUnder(repoRoot, branch, "active");
}

export function latestActivePacket(repoRoot, branch) {
  const list = listActivePackets(repoRoot, branch);
  return list.length ? list[list.length - 1] : null;
}

export function listArchivedPackets(repoRoot, branch) {
  return listPacketsUnder(repoRoot, branch, "archive");
}

/**
 * @param {string} repoRoot
 * @param {string} branch
 * @param {'active'|'archive'} location
 */
function listPacketsUnder(repoRoot, branch, location) {
  /** @type {string[]} */
  const out = [];
  const seen = new Set();
  for (const slug of candidateBranchSlugs(branch)) {
    const dir = path.join(repoRoot, ".review-handoff", location, slug);
    if (!fs.existsSync(dir)) continue;
    const files = fs
      .readdirSync(dir)
      .filter((f) => f.endsWith(".md"))
      .sort();
    for (const f of files) {
      const full = path.join(dir, f);
      try {
        const meta = readPacketMeta(full);
        // Exact frontmatter match only — refuse auto-attach of legacy `branch: HEAD`
        if (meta.frontmatter.branch !== branch) continue;
        const key = meta.packetId || full;
        if (seen.has(key)) continue;
        seen.add(key);
        out.push(full);
      } catch {
        // skip unreadable / malformed candidates
      }
    }
  }
  // Sort by filename (local_minute-scope), NOT full path — otherwise legacy dir names
  // like `main/` sort after `main--hash/` and latestActivePacket picks a stale packet.
  // Same basename: prefer v2 slug so dual-dir collisions resolve deterministically.
  const v2Slug = branchSlug(branch);
  return out.sort((a, b) => {
    const byName = path.basename(a).localeCompare(path.basename(b));
    if (byName !== 0) return byName;
    const aIsV2 = path.basename(path.dirname(a)) === v2Slug;
    const bIsV2 = path.basename(path.dirname(b)) === v2Slug;
    // v2 last (latestActivePacket takes last element)
    return Number(aIsV2) - Number(bIsV2);
  });
}

/** After a PASS archive, active/ is empty — resume from archive for read-only report. */
export function latestArchivedPacket(repoRoot, branch) {
  const list = listArchivedPackets(repoRoot, branch);
  return list.length ? list[list.length - 1] : null;
}

/**
 * Build a concise completion report for humans/agents from the packet body.
 * Used when lifecycle is terminal (archived/stopped) so one agent chat can show "all done + summary".
 */
export function buildCompletionReport({
  packetPath,
  meta,
  packetId,
  stopped = false,
}) {
  const sections = parseH1Sections(meta.text);
  const physical = sections.map((s) => ({ title: s.title, anchor: s.anchor }));
  const last = sections.at(-1) ?? null;
  const lastVerdict = sectionVerdict(last);
  const findings = extractFindingIds(sections);
  const reassessments = extractReassessmentRows(sections);
  const rounds = Number(meta.frontmatter?.round ?? meta.round ?? 1) || 1;
  const location = packetLocation(packetPath);
  const lifecycle = meta.lifecycleState;
  const closedByDecision = meta.lastAnchor === "decision_closure";
  const closeReason = meta.frontmatter?.close_reason ?? null;
  const allTasksComplete =
    lifecycle === "archived" ||
    stopped ||
    location === "archive" ||
    ((lastVerdict === "PASS" || lastVerdict === "NO_FINDINGS") &&
      location === "archive") ||
    (closedByDecision && lifecycle === "archived");

  const headline = allTasksComplete
    ? closedByDecision
      ? "✅ 任务全部完成(用户接受 concerns 并收口)"
      : "✅ 任务全部完成"
    : lifecycle === "awaiting_user_decision"
      ? "⏸ 等待你的决定(PASS_WITH_CONCERNS)"
      : lifecycle === "blocked"
        ? "⛔ 阻塞 — 需 Fixer 继续"
        : "⏳ 进行中";

  const bullets = [];
  if (closedByDecision) {
    bullets.push(`原始 Verdict: PASS_WITH_CONCERNS(未改写为 PASS)`);
    if (closeReason) bullets.push(`Closure reason: ${closeReason}`);
  } else if (lastVerdict) {
    bullets.push(`最终 Verdict: ${lastVerdict}`);
  }
  if (findings.ids.length) {
    bullets.push(
      `Findings 记录: ${findings.ids.join(", ")}(共 ${findings.ids.length})`,
    );
  } else {
    bullets.push("Findings 记录: 无 / 未解析到表格 ID");
  }
  if (reassessments.length) {
    const resolved = reassessments.filter((r) =>
      /resolv/i.test(r.status),
    ).length;
    bullets.push(
      `Re-review 复评: ${resolved}/${reassessments.length} resolved`,
    );
  }
  bullets.push(
    `阶段链: ${physical.map((h) => h.anchor).join(" → ") || "(empty)"}`,
  );
  bullets.push(
    `round=${rounds} | last_anchor=${meta.lastAnchor} | lifecycle=${lifecycle} | loc=${location}`,
  );

  const text = [
    headline,
    "",
    `packet_id: ${packetId ?? meta.packetId ?? "-"}`,
    `packet: ${packetPath}`,
    "",
    "## 简洁总结",
    ...bullets.map((b) => `- ${b}`),
    "",
    allTasksComplete
      ? "下一步: 无需再 continue;需要细节时打开 packet。"
      : "下一步: BLOCKED 时先修复并 review-loop fix-completion,再 run --continue;PASS_WITH_CONCERNS 用 close --reason accept-concerns 收口或 run --continue 继续。",
    "",
  ].join("\n");

  return {
    allTasksComplete: Boolean(allTasksComplete),
    headline,
    lastVerdict: closedByDecision ? "PASS_WITH_CONCERNS" : lastVerdict,
    closeReason,
    findingIds: findings.ids,
    reassessment: reassessments,
    stages: physical,
    round: rounds,
    lastAnchor: meta.lastAnchor,
    lifecycleState: lifecycle,
    location,
    packetPath,
    packetId: packetId ?? meta.packetId ?? null,
    text,
    markdown: text,
  };
}

function extractFindingIds(sections) {
  const ids = [];
  for (const section of sections) {
    if (
      !/review_findings|fix_handoff|fix_completion|re_review/.test(
        section.anchor,
      )
    )
      continue;
    const table = parseMarkdownTable(section.body);
    if (!table.headers.length) continue;
    const idIdx = table.headers.findIndex(
      (h) => h === "id" || h === "finding id",
    );
    if (idIdx === -1) continue;
    for (const row of table.rows) {
      const id = row[idIdx];
      if (id && !/^[-:]+$/.test(id) && !ids.includes(id)) ids.push(id);
    }
  }
  return { ids };
}

function extractReassessmentRows(sections) {
  const out = [];
  for (const section of sections) {
    if (section.anchor !== "re_review") continue;
    const blocks = sectionH2Blocks(section);
    const prior = blocks.find((b) =>
      b.heading.startsWith("prior findings reassessment"),
    );
    if (!prior) continue;
    const table = parseMarkdownTable(prior.body);
    if (!table.headers.length) continue;
    const idIdx = table.headers.findIndex(
      (h) => h === "id" || h === "finding id",
    );
    const statusIdx = table.headers.findIndex((h) =>
      /status|verdict|result/.test(h),
    );
    for (const row of table.rows) {
      out.push({
        id: idIdx >= 0 ? row[idIdx] : row[0],
        status: statusIdx >= 0 ? row[statusIdx] : (row[1] ?? ""),
      });
    }
  }
  return out;
}

export function createPacketFile(
  repoRoot,
  branch,
  scopeSlug = "review-loop",
  initialAnchor = "handoff",
) {
  // Contract: 1–3 kebab-case words, max 24 chars (packet-addressing.md)
  if (
    !/^[a-z0-9]+(?:-[a-z0-9]+){0,2}$/.test(scopeSlug) ||
    scopeSlug.length > 24
  ) {
    throw new Error(
      `invalid packet scope slug: ${scopeSlug} (need 1–3 kebab-case words, max 24 chars)`,
    );
  }
  if (!new Set(["handoff", "intake"]).has(initialAnchor)) {
    throw new Error(
      `invalid initial anchor: ${initialAnchor} (need handoff|intake)`,
    );
  }
  ensureReviewHandoffLayout(repoRoot);
  const slug = branchSlug(branch);
  const activeDir = path.join(repoRoot, ".review-handoff", "active", slug);
  fs.mkdirSync(activeDir, { recursive: true });
  fs.mkdirSync(path.join(repoRoot, ".review-handoff", "archive", slug), {
    recursive: true,
  });

  const minute = localMinuteStamp();
  const archiveDir = path.join(repoRoot, ".review-handoff", "archive", slug);
  let base = `${minute}-${scopeSlug}`;
  let file = path.join(activeDir, `${base}.md`);
  let n = 2;
  // F2: avoid colliding with archived packets or runtime ids from same minute/scope
  while (
    fs.existsSync(file) ||
    fs.existsSync(path.join(archiveDir, `${base}.md`)) ||
    fs.existsSync(
      path.join(
        repoRoot,
        ".review-handoff",
        "runtime",
        packetIdFromParts(branch, base),
      ),
    )
  ) {
    base = `${minute}-${scopeSlug}-${String(n).padStart(2, "0")}`;
    file = path.join(activeDir, `${base}.md`);
    n += 1;
  }

  const now = new Date().toISOString();
  const packetId = packetIdFromParts(branch, base);
  const initialStage =
    initialAnchor === "intake"
      ? {
          anchor: "review_intake",
          markdown: `# Review Intake

## Scope reviewed
- Scope type: working tree / loop orchestration
- Repository: ${repoRoot}
- Branch: ${branch}
- Files inspected: pending frozen Git evidence

## Verification
- Commands run this session: repository and branch resolution by review-loop
- Tools used: review-loop Git adapter

## Inferred Goal
- Review the selected Git diff; provenance: explicit reviewer-initiated intake`,
        }
      : {
          anchor: "review_handoff",
          markdown: `# Review Handoff

## Goal
- User request: review-loop auto loop handoff
- Intended behavior: packet-driven Fixer + headless Reviewer loop
- Non-goals: dual-window coordination; profile=deep blind review

## Review Scope
- Scope type: working tree / loop orchestration
- Repository: ${repoRoot}
- Branch: ${branch}`,
        };
  // Exclusive create (wx) to close TOCTOU window (F2)
  // Exclusive create with multi-retry against active/archive/runtime (F2)
  for (let attempt = 0; attempt < 20; attempt += 1) {
    const tryBase =
      attempt === 0
        ? base
        : `${minute}-${scopeSlug}-${String(n + attempt - 1).padStart(2, "0")}`;
    const tryFile = path.join(activeDir, `${tryBase}.md`);
    const tryId = packetIdFromParts(branch, tryBase);
    if (
      fs.existsSync(tryFile) ||
      fs.existsSync(path.join(archiveDir, `${tryBase}.md`)) ||
      fs.existsSync(path.join(repoRoot, ".review-handoff", "runtime", tryId))
    ) {
      continue;
    }
    const bodyFinal = `---
packet_id: ${tryId}
branch: ${branch}
scope: ${scopeSlug}
created: ${now}
updated: ${now}
last_anchor: ${initialStage.anchor}
lifecycle_state: in_progress
round: 1
loop: on
---

${initialStage.markdown}
`;
    try {
      const fd = fs.openSync(tryFile, "wx");
      fs.writeFileSync(fd, bodyFinal, "utf8");
      fs.closeSync(fd);
      return { packetPath: tryFile, packetId: tryId, fileBase: tryBase };
    } catch (err) {
      if (err?.code === "EEXIST") continue;
      throw err;
    }
  }
  throw new Error("createPacketFile: exhausted unique name retries");
}

export function readPacketMeta(packetPath) {
  const text = fs.readFileSync(packetPath, "utf8");
  const fm = parseFrontmatter(text);
  return {
    text,
    frontmatter: fm,
    lastAnchor: fm.last_anchor ?? null,
    lifecycleState: fm.lifecycle_state ?? "in_progress",
    packetId: fm.packet_id ?? null,
    fingerprint: sha256(text),
  };
}

export function parseFrontmatter(text) {
  if (!text.startsWith("---")) return {};
  const end = text.indexOf("\n---", 3);
  if (end === -1) return {};
  const block = text.slice(4, end).trim();
  /** @type {Record<string, string>} */
  const out = {};
  for (const line of block.split("\n")) {
    const m = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
    if (!m) continue;
    let v = m[2].trim();
    if (
      (v.startsWith('"') && v.endsWith('"')) ||
      (v.startsWith("'") && v.endsWith("'"))
    ) {
      v = v.slice(1, -1);
    }
    out[m[1]] = v;
  }
  return out;
}

export function rewriteFrontmatter(packetPath, updates) {
  const text = fs.readFileSync(packetPath, "utf8");
  if (!text.startsWith("---")) throw new Error("packet missing frontmatter");
  const end = text.indexOf("\n---", 3);
  if (end === -1) throw new Error("packet frontmatter not closed");
  const body = text.slice(end + 4); // after \n---
  const fm = parseFrontmatter(text);
  Object.assign(fm, updates);
  fm.updated = new Date().toISOString();
  const lines = Object.entries(fm).map(([k, v]) => `${k}: ${v}`);
  const next = `---\n${lines.join("\n")}\n---${body.startsWith("\n") ? body : `\n${body}`}`;
  const tmp = temporarySibling(packetPath);
  fs.writeFileSync(tmp, next, "utf8");
  fs.renameSync(tmp, packetPath);
  return readPacketMeta(packetPath);
}

export function appendPacketSection(packetPath, markdownSection) {
  return appendStageAtEof(packetPath, {
    sectionMarkdown: markdownSection,
    // keep existing frontmatter anchors unless caller rewrites after
    preserveFrontmatter: true,
  });
}

/**
 * Atomic append-at-EOF for packet H1 sections.
 * This is the ONLY supported way for workers to add stages — never mid-file patch / fuzzy anchors.
 *
 * @param {string} packetPath
 * @param {{ sectionMarkdown: string, lastAnchor?: string, lifecycleState?: string, extra?: Record<string,string>, preserveFrontmatter?: boolean }} opts
 */
export function appendStageAtEof(packetPath, opts) {
  const section = String(opts.sectionMarkdown ?? "").trim();
  if (!section) throw new Error("appendStageAtEof: empty section");
  if (!/^# [^#\n]/.test(section)) {
    throw new Error(
      "appendStageAtEof: section must start with a top-level H1 (# Title)",
    );
  }

  const text = fs.readFileSync(packetPath, "utf8");
  if (!text.startsWith("---")) throw new Error("packet missing frontmatter");
  const end = text.indexOf("\n---", 3);
  if (end === -1) throw new Error("packet frontmatter not closed");
  const body = text.slice(end + 4);
  const fm = parseFrontmatter(text);

  if (!opts.preserveFrontmatter) {
    if (!opts.lastAnchor)
      throw new Error("appendStageAtEof: lastAnchor required");
    if (!opts.lifecycleState)
      throw new Error("appendStageAtEof: lifecycleState required");
    Object.assign(fm, opts.extra ?? {}, {
      last_anchor: opts.lastAnchor,
      lifecycle_state: opts.lifecycleState,
      updated: new Date().toISOString(),
    });
  } else {
    fm.updated = new Date().toISOString();
    Object.assign(fm, opts.extra ?? {});
  }

  const newBody = `${String(body).replace(/\s*$/, "")}\n\n${section}\n`;
  const fmLines = Object.entries(fm).map(([k, v]) => `${k}: ${v}`);
  const next = `---\n${fmLines.join("\n")}\n---\n${newBody.replace(/^\n/, "")}`;
  const tmp = temporarySibling(packetPath);
  fs.writeFileSync(tmp, next, "utf8");
  fs.renameSync(tmp, packetPath);

  const meta = readPacketMeta(packetPath);
  if (!fs.readFileSync(packetPath).equals(Buffer.from(next, "utf8"))) {
    throw new Error(
      "packet write verification failed: disk bytes differ; inspect packet before retrying",
    );
  }
  const last = lastPhysicalH1(meta.text);
  if (!last) throw new Error("appendStageAtEof: no H1 after write");
  // Last H1 inside the appended chunk must be the packet's last physical H1
  // Fence-aware (N1): ignore `#` lines inside ``` / ~~~ code fences
  const appendedTitles = (() => {
    const lines = section.split("\n");
    /** @type {string[]} */
    const titles = [];
    let fenced = false;
    for (const line of lines) {
      if (/^\s*(```|~~~)/.test(line)) {
        fenced = !fenced;
        continue;
      }
      if (fenced) continue;
      const match = line.match(/^# ([^#].*?)\s*$/);
      if (match) titles.push(match[1].trim());
    }
    return titles;
  })();
  const expectedTitle = appendedTitles.at(-1);
  if (!expectedTitle) throw new Error("appendStageAtEof: section has no H1");
  if (
    last.title !== expectedTitle &&
    last.anchor !== normalizeH1(expectedTitle)
  ) {
    throw new Error(
      `appendStageAtEof integrity failed: expected last H1 "${expectedTitle}", got "${last.title}"`,
    );
  }
  if (!opts.preserveFrontmatter && meta.lastAnchor !== opts.lastAnchor) {
    throw new Error(
      `appendStageAtEof frontmatter last_anchor mismatch: expected ${opts.lastAnchor}, got ${meta.lastAnchor}`,
    );
  }
  return meta;
}

/** Return last physical top-level H1 in packet body (fenced code aware). */
export function lastPhysicalH1(packetText) {
  const sections = parseH1Sections(packetText);
  return sections.at(-1) ?? null;
}

export function listPhysicalH1s(packetText) {
  return parseH1Sections(packetText).map((s) => ({
    title: s.title,
    anchor: s.anchor,
  }));
}

export function archivePacket(packetPath) {
  const normalized = packetPath.split(path.sep).join("/");
  const marker = "/.review-handoff/active/";
  const index = normalized.indexOf(marker);
  if (index === -1) throw new Error("only active packets can be archived");
  const archivePath = `${normalized.slice(0, index)}/.review-handoff/archive/${normalized.slice(index + marker.length)}`;
  fs.mkdirSync(path.dirname(archivePath), { recursive: true });
  fs.renameSync(packetPath, archivePath);
  return archivePath;
}

/** Half-write: write incomplete content without final frontmatter update (for tests). */
export function halfWritePacket(packetPath, incompleteTail) {
  fs.appendFileSync(packetPath, incompleteTail, "utf8");
}

export function runtimeDir(repoRoot, packetId) {
  const segments = validatePacketId(packetId);
  const root = path.resolve(repoRoot, ".review-handoff", "runtime");
  const dir = path.resolve(root, ...segments);
  assertContained(root, dir, "runtime path");
  fs.mkdirSync(dir, { recursive: true });
  return dir;
}

export function readJson(file, fallback = null) {
  if (!fs.existsSync(file)) return fallback;
  return JSON.parse(fs.readFileSync(file, "utf8"));
}

export function writeJson(file, data) {
  fs.mkdirSync(path.dirname(file), { recursive: true });
  const tmp = temporarySibling(file);
  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, "utf8");
  fs.renameSync(tmp, file);
}

/**
 * @param {string} repoRoot
 * @param {string} branch
 * @param {string} packetPath
 * @param {{ activeOnly?: boolean }} [opts]
 */
/**
 * Validate an existing packet path.
 * Uses packet_id's own slug for containment (legacy dirs keep original packet_id;
 * do not recompute slug from current branchSlug algorithm).
 * Frontmatter `branch` must exactly equal current identity.
 */
export function validatePacketPath(repoRoot, branch, packetPath, opts = {}) {
  const resolved = fs.realpathSync(packetPath);
  const resolvedRepoRoot = fs.realpathSync(repoRoot);
  const meta = readPacketMeta(resolved);
  if (!meta.packetId) {
    throw new Error("packet missing packet_id frontmatter");
  }
  const [idSlug, idFileBase] = validatePacketId(meta.packetId);
  const locations = opts.activeOnly ? ["active"] : ["active", "archive"];
  const allowedRoots = locations.map((location) =>
    path.resolve(resolvedRepoRoot, ".review-handoff", location, idSlug),
  );
  if (!allowedRoots.some((root) => isContained(root, resolved))) {
    throw new Error(
      opts.activeOnly
        ? `packet must be under .review-handoff/active/${idSlug} (writes refuse archive)`
        : `packet must be under .review-handoff/active/${idSlug} or .review-handoff/archive/${idSlug}`,
    );
  }
  const fileBase = path.basename(resolved, ".md");
  if (fileBase !== idFileBase) {
    throw new Error(
      `packet filename mismatch: path base ${fileBase} vs packet_id ${idFileBase}`,
    );
  }
  if (meta.frontmatter.branch !== branch) {
    const legacyHint =
      meta.frontmatter.branch === "HEAD" &&
      String(branch).startsWith("detached:")
        ? " (legacy HEAD packet: refuse auto-attach to detached identity; pass explicit --packet only if frontmatter branch is updated intentionally)"
        : "";
    throw new Error(
      `packet branch mismatch: expected ${branch}, got ${meta.frontmatter.branch ?? "<missing>"}${legacyHint}`,
    );
  }
  return { packetPath: resolved, packetId: meta.packetId, meta };
}

export function withRuntimeLock(
  repoRoot,
  packetId,
  operation,
  { timeoutMs = 5000 } = {},
) {
  const lockDir = path.join(runtimeDir(repoRoot, packetId), ".kernel.lock");
  const deadline = Date.now() + timeoutMs;
  while (true) {
    try {
      fs.mkdirSync(lockDir);
      break;
    } catch (error) {
      if (error?.code !== "EEXIST") throw error;
      if (Date.now() >= deadline) {
        throw new Error(`runtime lock timeout for packet ${packetId}`);
      }
      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
    }
  }
  try {
    return operation();
  } finally {
    fs.rmSync(lockDir, { recursive: true, force: true });
  }
}

export function appendEvent(repoRoot, packetId, event) {
  const dir = runtimeDir(repoRoot, packetId);
  const file = path.join(dir, "events.jsonl");
  fs.appendFileSync(
    file,
    `${JSON.stringify({ ...event, at: new Date().toISOString() })}\n`,
  );
}

export function sha256(text) {
  return crypto.createHash("sha256").update(text).digest("hex");
}

function localMinuteStamp() {
  const d = new Date();
  const p = (n) => String(n).padStart(2, "0");
  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}_${p(d.getHours())}-${p(d.getMinutes())}`;
}

export function validateCompletedStage({ packetPath, meta, role }) {
  const sections = parseH1Sections(meta.text);
  const last = sections.at(-1);
  if (!last) throw new Error("packet body has no H1 stage");
  if (last.anchor !== meta.lastAnchor) {
    throw new Error(
      `last physical H1 is ${last.anchor}, but frontmatter last_anchor is ${meta.lastAnchor}. ` +
        `Likely mid-file packet edit — discard that insert; write only via review-loop run / fix-completion (auto stage writer).`,
    );
  }

  const location = packetLocation(packetPath);
  validateLifecycleTuple({ meta, location, sections });

  if (meta.lastAnchor === "fix_handoff") {
    if (role !== "reviewer")
      throw new Error("only Reviewer may complete Fix Handoff");
    const findings = sections.at(-2);
    if (findings?.anchor !== "review_findings") {
      throw new Error(
        "Fix Handoff must immediately follow Review Findings in the same stage group",
      );
    }
    requireH2(findings, [
      "scope reviewed",
      "verification",
      "findings",
      "verdict",
    ]);
    requireH2(last, [
      "scope",
      "validated findings to fix",
      "constraints",
      "verification required",
      "required fix agent output",
    ]);
    const verdict = sectionVerdict(findings);
    if (!["BLOCKED", "PASS_WITH_CONCERNS"].includes(verdict)) {
      throw new Error(
        `Fix Handoff requires BLOCKED or PASS_WITH_CONCERNS, got ${verdict || "<missing>"}`,
      );
    }
  } else if (meta.lastAnchor === "review_findings") {
    if (role !== "reviewer")
      throw new Error("only Reviewer may complete Review Findings");
    requireH2(last, ["scope reviewed", "verification", "findings", "verdict"]);
  } else if (meta.lastAnchor === "fix_completion") {
    if (role !== "fixer")
      throw new Error("only Fixer may complete Fix Completion");
    const h2 = sectionH2(last);
    if (h2.at(0) !== "fix conclusion") {
      throw new Error("Fix Completion first subsection must be Fix Conclusion");
    }
    requireH2(last, [
      "fix conclusion",
      "original findings snapshot",
      "finding status",
      "verification",
      "re-review instructions",
    ]);
  } else if (meta.lastAnchor === "re_review") {
    if (role !== "reviewer")
      throw new Error("only Reviewer may complete Re-review");
    const h2 = sectionH2(last);
    if (!h2.some((heading) => heading.startsWith("scope"))) {
      throw new Error("Re-review missing Scope subsection");
    }
    requireH2(last, [
      "prior findings reassessment",
      "new findings",
      "regression surface",
      "verdict",
    ]);
  } else if (meta.lastAnchor === "decision_closure") {
    if (role !== "fixer" && role !== "user") {
      throw new Error("only Fixer/user may complete Decision Closure");
    }
    requireH2(last, [
      "reason",
      "original verdict",
      "accepted concerns",
      "closure",
    ]);
  } else {
    throw new Error(
      `unsupported completed stage: ${meta.lastAnchor ?? "<missing>"}`,
    );
  }
  return {
    ok: true,
    lastAnchor: meta.lastAnchor,
    lifecycleState: meta.lifecycleState,
  };
}

function validateLifecycleTuple({ meta, location, sections }) {
  const anchor = meta.lastAnchor;
  const lifecycle = meta.lifecycleState;
  const last = sections.at(-1);
  const verdict = sectionVerdict(last);
  // Auto-loop contract: BLOCKED Fix Handoff → blocked; Fix Completion mid-fix → in_progress
  if (anchor === "fix_handoff") {
    if (
      location !== "active" ||
      (lifecycle !== "blocked" && lifecycle !== "in_progress")
    ) {
      throw new Error(
        `fix_handoff requires lifecycle_state=blocked (or in_progress) under active/ (got ${lifecycle}/${location})`,
      );
    }
    return;
  }
  if (anchor === "fix_completion") {
    if (lifecycle !== "in_progress" || location !== "active") {
      throw new Error(
        `${anchor} requires lifecycle_state=in_progress under active/`,
      );
    }
    return;
  }
  if (anchor === "review_findings") {
    const terminal = ["PASS", "NO_FINDINGS"].includes(verdict);
    if (terminal && (lifecycle !== "archived" || location !== "archive")) {
      throw new Error(
        "terminal Review Findings requires lifecycle_state=archived under archive/",
      );
    }
    if (verdict === "PASS_WITH_CONCERNS") {
      if (lifecycle !== "awaiting_user_decision" || location !== "active") {
        throw new Error(
          "PASS_WITH_CONCERNS Review Findings requires lifecycle_state=awaiting_user_decision under active/",
        );
      }
      return;
    }
    if (verdict === "BLOCKED") {
      if (
        location !== "active" ||
        (lifecycle !== "blocked" && lifecycle !== "in_progress")
      ) {
        throw new Error(
          "BLOCKED Review Findings requires lifecycle_state=blocked under active/",
        );
      }
      return;
    }
    if (!terminal && (lifecycle !== "in_progress" || location !== "active")) {
      throw new Error(
        "non-terminal Review Findings requires lifecycle_state=in_progress under active/",
      );
    }
    return;
  }
  if (anchor === "re_review") {
    const strictConcerns =
      verdict === "PASS_WITH_CONCERNS" &&
      String(meta.frontmatter?.completion || "").toLowerCase() === "pass";
    const expected =
      verdict === "PASS" || verdict === "NO_FINDINGS"
        ? ["archived", "archive"]
        : verdict === "PASS_WITH_CONCERNS"
          ? [strictConcerns ? "blocked" : "awaiting_user_decision", "active"]
          : verdict === "BLOCKED"
            ? ["blocked", "active"]
            : null;
    if (!expected || lifecycle !== expected[0] || location !== expected[1]) {
      throw new Error(
        `Re-review verdict/lifecycle/location mismatch: ${verdict || "<missing>"}/${lifecycle}/${location}`,
      );
    }
    return;
  }
  if (anchor === "decision_closure") {
    if (lifecycle !== "archived" || location !== "archive") {
      throw new Error(
        `decision_closure requires lifecycle_state=archived under archive/ (got ${lifecycle}/${location})`,
      );
    }
  }
}

function parseH1Sections(text) {
  const lines = text.split("\n");
  const headings = [];
  let fenced = false;
  for (let index = 0; index < lines.length; index += 1) {
    const line = lines[index];
    if (/^\s*(```|~~~)/.test(line)) {
      fenced = !fenced;
      continue;
    }
    if (fenced) continue;
    const match = line.match(/^# ([^#].*?)\s*$/);
    if (match)
      headings.push({ index, title: match[1], anchor: normalizeH1(match[1]) });
  }
  return headings.map((heading, index) => ({
    ...heading,
    body: lines
      .slice(heading.index + 1, headings[index + 1]?.index ?? lines.length)
      .join("\n"),
  }));
}

function sectionH2(section) {
  return sectionH2Blocks(section).map((block) => block.heading);
}

function requireH2(section, required) {
  const blocks = sectionH2Blocks(section);
  const missing = required.filter(
    (heading) => !blocks.some((block) => block.heading === heading),
  );
  if (missing.length) {
    throw new Error(
      `${section.title} missing required subsections: ${missing.join(", ")}`,
    );
  }
  const empty = required.filter(
    (heading) =>
      !blocks.some(
        (block) => block.heading === heading && block.body.trim().length > 0,
      ),
  );
  if (empty.length) {
    throw new Error(
      `${section.title} has empty required subsections: ${empty.join(", ")}`,
    );
  }
}

function sectionH2Blocks(section) {
  const lines = unfencedLines(section.body);
  const headings = [];
  for (let index = 0; index < lines.length; index += 1) {
    const match = lines[index].match(/^## ([^#].*?)\s*$/);
    if (match) headings.push({ index, heading: match[1].trim().toLowerCase() });
  }
  return headings.map((heading, index) => ({
    ...heading,
    body: lines
      .slice(heading.index + 1, headings[index + 1]?.index ?? lines.length)
      .join("\n"),
  }));
}

function parseMarkdownTable(body) {
  const rows = body
    .split("\n")
    .filter((line) => /^\s*\|.*\|\s*$/.test(line))
    .map((line) =>
      line
        .trim()
        .slice(1, -1)
        .split("|")
        .map((cell) => cell.trim()),
    );
  if (rows.length < 2) return { headers: [], rows: [] };
  const headers = rows[0].map((cell) => cell.toLowerCase());
  const separator = rows[1];
  if (!separator.every((cell) => /^:?-{3,}:?$/.test(cell))) {
    return { headers: [], rows: [] };
  }
  return {
    headers,
    rows: rows.slice(2).filter((row) => row.length === headers.length),
  };
}

function sectionVerdict(section) {
  if (!section) return null;
  const physicalBody = unfencedLines(section.body).join("\n");
  const match = physicalBody.match(
    /(?:^|\n)## Verdict\s*\n+\s*(BLOCKED|PASS_WITH_CONCERNS|PASS|NO_FINDINGS)\s*(?:\n|$)/,
  );
  return match?.[1] ?? null;
}

function unfencedLines(text) {
  const lines = [];
  let fenced = false;
  for (const line of text.split("\n")) {
    if (/^\s*(```|~~~)/.test(line)) {
      fenced = !fenced;
      continue;
    }
    if (!fenced) lines.push(line);
  }
  return lines;
}

function normalizeH1(title) {
  return title
    .replace(/ \(round \d+\)$/i, "")
    .trim()
    .toLowerCase()
    .replace(/-/g, "_")
    .replace(/[^a-z0-9]+/g, "_")
    .replace(/^_|_$/g, "");
}

/** Public: normalize stage titles / CLI --stage into frontmatter anchors. */
export function stageAnchor(name) {
  return normalizeH1(String(name ?? ""));
}

function packetLocation(packetPath) {
  const normalized = packetPath.split(path.sep).join("/");
  if (normalized.includes("/.review-handoff/active/")) return "active";
  if (normalized.includes("/.review-handoff/archive/")) return "archive";
  return "outside";
}

function validatePacketId(packetId) {
  if (typeof packetId !== "string" || path.isAbsolute(packetId)) {
    throw new Error(`invalid packet_id: ${packetId}`);
  }
  const segments = packetId.split("/");
  if (
    segments.length !== 2 ||
    segments.some(
      (segment) =>
        !segment ||
        segment === "." ||
        segment === ".." ||
        !/^[A-Za-z0-9._-]+$/.test(segment),
    )
  ) {
    throw new Error(`invalid packet_id: ${packetId}`);
  }
  return segments;
}

function temporarySibling(file) {
  return `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
}

function isContained(root, candidate) {
  const relative = path.relative(path.resolve(root), path.resolve(candidate));
  return (
    relative === "" ||
    (!relative.startsWith("..") && !path.isAbsolute(relative))
  );
}

function assertContained(root, candidate, label) {
  if (!isContained(root, candidate))
    throw new Error(`${label} escapes ${root}`);
}
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall