@brainervirus/workit-core 0.10.0 → 1.0.0

package/src/core/handoff-context.ts

@@ -1,136 +0,0 @@
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import path from "node:path";
-import { docsValidate } from "./docs-validate";
-import { resolveBranch } from "./branch";
-import { parseTasksFromPlan } from "./docs-validate";
-
-const DOC_RE = /docs\/([A-Za-z0-9][A-Za-z0-9._-]*)\/(spec|plan)\.md/g;
-
-const listMd = (dir: string): string[] => {
-  try {
-    return readdirSync(dir)
-      .filter((f) => f.endsWith(".md"))
-      .sort();
-  } catch {
-    return [];
-  }
-};
-
-type Resolved = { spec: string; plan: string; source: string } | { error: string };
-
-const extractMessagePaths = (message: string): string[] =>
-  [...new Set(message.match(DOC_RE) ?? [])].sort();
-
-const resolveFromMessagePaths = (root: string, message: string): Resolved => {
-  const paths = extractMessagePaths(message);
-  if (paths.length === 0) return { error: "no paths" };
-  const slugs = [...new Set(paths.map((p) => p.split("/")[1]))];
-  if (slugs.length !== 1)
-    return { error: "multiple features in message — use exactly one docs/<slug>/ pair" };
-  const slug = slugs[0];
-  const plan = `docs/${slug}/plan.md`;
-  const spec = `docs/${slug}/spec.md`;
-  if (!existsSync(path.join(root, plan)) || !existsSync(path.join(root, spec))) {
-    return { error: `docs/${slug}/ must contain both plan.md and spec.md` };
-  }
-  return { spec, plan, source: "message_paths" };
-};
-
-const resolveActivePair = (root: string): Resolved => {
-  const docsDir = path.join(root, "docs");
-  let best: { score: number; spec: string; plan: string; source: string } | null = null;
-  let entries: string[] = [];
-  try {
-    entries = readdirSync(docsDir);
-  } catch {
-    return { error: "no pair" };
-  }
-  for (const slug of entries) {
-    if (slug.startsWith(".")) continue;
-    const plan = path.join("docs", slug, "plan.md");
-    const spec = path.join("docs", slug, "spec.md");
-    if (!existsSync(path.join(root, plan)) || !existsSync(path.join(root, spec))) continue;
-    const score = Math.max(
-      statSync(path.join(root, spec)).mtimeMs,
-      statSync(path.join(root, plan)).mtimeMs,
-    );
-    if (
-      best === null ||
-      score > best.score ||
-      (score === best.score && slug < best.spec.split("/")[1])
-    ) {
-      best = { score, spec, plan, source: "active_pair" };
-    }
-  }
-  if (best === null) return { error: "no pair" };
-  return { spec: best.spec, plan: best.plan, source: best.source };
-};
-
-export const resolveWorkflowPaths = (root: string, message: string): Resolved => {
-  const fromMessage = resolveFromMessagePaths(root, message);
-  if (!("error" in fromMessage)) return fromMessage;
-  if (fromMessage.error !== "no paths") return fromMessage;
-  const active = resolveActivePair(root);
-  if (!("error" in active)) return active;
-
-  const docsDir = path.join(root, "docs");
-  if (!existsSync(docsDir) || listMd(docsDir).length === 0) {
-    return { error: "no docs/<slug>/ features found under docs/" };
-  }
-  return {
-    error:
-      "could not resolve spec and plan — mention docs/<slug>/plan.md or create docs/<slug>/{spec.md,plan.md}",
-  };
-};
-
-export const buildHandoffContract = ({
-  root,
-  spec,
-  plan,
-  templatePath,
-}: {
-  root: string;
-  spec: string;
-  plan: string;
-  templatePath: string;
-}): { prompt: string } | { error: string } => {
-  const validated = docsValidate({ spec_path: spec, plan_path: plan, workspace_root: root });
-  if (validated.ok === false) {
-    return {
-      error: `docs validation failed\n${JSON.stringify({ ok: false, errors: validated.errors })}`,
-    };
-  }
-  const branchResolved = resolveBranch({ spec_path: spec, plan_path: plan, workspace_root: root });
-  if ("error" in branchResolved) return { error: branchResolved.error as string };
-  const branch = branchResolved.branch;
-  const slug = path.basename(path.dirname(plan));
-  const sddDir = `docs/${slug}/sdd`;
-
-  const planText = readFileSync(path.join(root, plan), "utf8");
-  const tasks = parseTasksFromPlan(planText);
-  const taskList = tasks.map((t) => `- Task ${t.id}: ${t.title}`).join("\n");
-
-  let contract: string;
-  try {
-    contract = readFileSync(templatePath, "utf8");
-  } catch {
-    return { error: "missing template templates/execution-contract.md" };
-  }
-  contract = contract
-    .replace(/<SPEC_PATH>/g, spec)
-    .replace(/<PLAN_PATH>/g, plan)
-    .replace(/<BRANCH>/g, branch)
-    .replace(/<SLUG>/g, slug)
-    .replace(/<SDD_DIR>/g, sddDir)
-    .replace(/<TASK_LIST>/g, taskList);
-
-  // Every generated destination contract carries the marker on its OWN LINE
-  // (CA-07): a canonical template that loses the sentinel — or embeds it
-  // mid-line — is a broken contract, not a handoff prompt. Anchored to the
-  // line start/end so a substring mid-line cannot satisfy the guard.
-  if (!/^<workflow-handoff-destination>true<\/workflow-handoff-destination>$/m.test(contract)) {
-    return { error: "handoff destination contract missing its destination marker" };
-  }
-
-  return { prompt: contract };
-};

package/src/core/handoff-tools.ts

@@ -1,133 +0,0 @@
-import path from "node:path";
-import { fail, ok, type Result } from "../core";
-import { resolveWorkflowPaths, buildHandoffContract } from "./handoff-context";
-import { assetRoot } from "./package-root";
-import type { FlowGateResult } from "./flow-state";
-
-type ApiResponse<T> = { data?: T; error?: unknown };
-type ApiResult<T> = Promise<ApiResponse<T>>;
-type ApiVoidResult = Promise<ApiResponse<void> | void>;
-type ApiUnknownResult = Promise<ApiResponse<unknown> | void>;
-
-export type HandoffClient = {
-  session: {
-    create(input: {
-      body: { title: string };
-      query: { directory: string };
-    }): ApiResult<{ id: string }>;
-    promptAsync(input: {
-      path: { id: string };
-      query: { directory: string };
-      body: { parts: [{ type: "text"; text: string }] };
-    }): ApiVoidResult;
-  };
-  tui: {
-    selectSession(input: {
-      body: { sessionID: string };
-      query: { directory: string };
-    }): ApiUnknownResult;
-  };
-};
-
-export type HandoffRequest = {
-  directory: string;
-  title: string;
-  prompt: string;
-  stay: boolean;
-  /**
-   * Destination marking hook (CA-07): invoked only after `promptAsync` succeeds
-   * and before any optional selection. The adapter supplies the core
-   * `markHandoffDestination` binding so destination state is marked atomically
-   * after the child session is seeded — never before creation/seed succeed and
-   * never undone by a later selection failure.
-   */
-  afterSeed?: () => FlowGateResult | Promise<FlowGateResult>;
-};
-
-type HandoffData = {
-  sessionID?: string;
-  seeded?: boolean;
-  selected?: boolean;
-  stage?: "create" | "seed" | "mark" | "select";
-};
-
-export const message = (error: unknown) =>
-  error instanceof Error
-    ? error.message
-    : typeof error === "object" && error !== null && "message" in error
-      ? String(error.message)
-      : String(error);
-export const apiError = (response: ApiResponse<unknown> | void) => response?.error;
-
-export async function handoffSession(
-  client: HandoffClient,
-  request: HandoffRequest,
-): Promise<Result<HandoffData>> {
-  let sessionID: string | undefined;
-  try {
-    const created = await client.session.create({
-      body: { title: request.title },
-      query: { directory: request.directory },
-    });
-    if (apiError(created)) throw apiError(created);
-    sessionID = created.data?.id;
-    if (!sessionID) return fail("session create returned no ID", { stage: "create" });
-  } catch (error) {
-    return fail(message(error), { stage: "create" });
-  }
-
-  try {
-    const seeded = await client.session.promptAsync({
-      path: { id: sessionID },
-      query: { directory: request.directory },
-      body: { parts: [{ type: "text", text: request.prompt }] },
-    });
-    if (apiError(seeded)) throw apiError(seeded);
-  } catch (error) {
-    return fail(message(error), { sessionID, seeded: false, selected: false, stage: "seed" });
-  }
-
-  if (request.afterSeed) {
-    try {
-      const marked = await request.afterSeed();
-      if (!marked.ok) {
-        return fail(marked.error, { sessionID, seeded: true, selected: false, stage: "mark" });
-      }
-    } catch (error) {
-      return fail(message(error), { sessionID, seeded: true, selected: false, stage: "mark" });
-    }
-  }
-
-  if (request.stay) return ok({ sessionID, seeded: true, selected: false });
-
-  try {
-    const selected = await client.tui.selectSession({
-      body: { sessionID },
-      query: { directory: request.directory },
-    });
-    if (apiError(selected)) throw apiError(selected);
-    if (selected?.data !== true) throw new Error("session selection unavailable");
-    return ok({ sessionID, seeded: true, selected: true });
-  } catch (error) {
-    return fail(message(error), { sessionID, seeded: true, selected: false, stage: "select" });
-  }
-}
-
-export type HandoffContextResult =
-  | { prompt: string; spec: string; plan: string; sdd: string }
-  | { error: string };
-
-export const buildHandoffPrompt = (root: string, message: string): HandoffContextResult => {
-  const resolved = resolveWorkflowPaths(root, message);
-  if ("error" in resolved) return { error: resolved.error };
-  const templatePath = path.join(assetRoot(), "templates", "execution-contract.md");
-  const contract = buildHandoffContract({
-    root,
-    spec: resolved.spec,
-    plan: resolved.plan,
-    templatePath,
-  });
-  if ("error" in contract) return { error: contract.error };
-  const sdd = `docs/${path.basename(path.dirname(resolved.plan))}/sdd`;
-  return { prompt: contract.prompt, spec: resolved.spec, plan: resolved.plan, sdd };
-};

package/src/core/menu.ts

@@ -1,70 +0,0 @@
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import path from "node:path";
-
-/**
- * Host-neutral post-plan menu wording and the handoff destination marker
- * (CA-07, CA-08). Import-light by design: session-start hooks and reminder
- * selection consume these constants WITHOUT dragging in the full flow-state
- * graph (approval digests, verification, repo-context), so a read-only hook
- * stays network-free by source inspection (RL-09/CA-25).
- */
-
-/** Display labels the source menu presents (CA-08). */
-export const SOURCE_MENU_LABELS = [
-  "Subagent-driven",
-  "Inline",
-  "Handoff",
-  "Review spec first",
-  "Review plan first",
-  "Change model first",
-] as const;
-
-/** Display labels a marked destination presents — exactly five, no Handoff (CA-08). */
-export const DESTINATION_MENU_LABELS = [
-  "Subagent-driven",
-  "Inline",
-  "Review spec first",
-  "Review plan first",
-  "Change model first",
-] as const;
-
-/**
- * The exact sentinel every generated destination contract carries on its own
- * line (CA-07). Host-neutral by design (CA-10): OpenCode seeded sessions,
- * Cursor copy/paste prompts, and CLI output all detect a destination by this
- * marker alone — no session IDs, parent IDs, or host metadata.
- */
-export const HANDOFF_DESTINATION_MARKER =
-  "<workflow-handoff-destination>true</workflow-handoff-destination>";
-
-/**
- * Marked handoff destinations in a workspace (CA-07, CA-08): the persisted
- * `handoff_destination: true` flag that `markHandoffDestination` sets atomically
- * AFTER a genuine generated destination prompt succeeds. Hosts use this at
- * session start to select the destination reminder (four choices, no Handoff)
- * without session or parent IDs. The flag is cleared by approval-drift resets
- * AND by completion (a completed flow is never a destination); only a new-flow
- * `prepareFlowState` initializes it (false), and `markHandoffDestination` is
- * the sole true-setter. Raw read only: a session-start hook must never
- * reconcile or rewrite flow state, so a stale flag may read true until the
- * next effective read resets it — safe bias toward destination wording.
- * ponytail: raw flag scan, not readEffectiveFlowState — a hook is read-only;
- * reconcile-on-drift is the mutation path's job.
- */
-export const findMarkedDestinations = (root: string): string[] => {
-  const docsDir = path.join(root, "docs");
-  if (!existsSync(docsDir)) return [];
-  const slugs: string[] = [];
-  for (const slug of readdirSync(docsDir)) {
-    const file = path.join(docsDir, slug, "sdd", "flow.json");
-    if (!existsSync(file)) continue;
-    try {
-      const parsed = JSON.parse(readFileSync(file, "utf8")) as { handoff_destination?: unknown };
-      if (parsed.handoff_destination === true) slugs.push(slug);
-    } catch {
-      // a malformed flow.json excludes the entry without touching it
-      continue;
-    }
-  }
-  return slugs;
-};

package/src/core/plan-tasks.ts

@@ -1,43 +0,0 @@
-import { readFileSync } from "node:fs";
-import path from "node:path";
-import { parseTasksFromPlan } from "./docs-validate";
-import { resolveBranch } from "./branch";
-
-const readSafe = (p: string): string | null => {
-  try {
-    return readFileSync(p, "utf8");
-  } catch {
-    return null;
-  }
-};
-
-export function parsePlanTasks(
-  planPath: string,
-  workspaceRoot: string,
-):
-  | { task_count: number; tasks: { id: number; title: string; section_text: string }[] }
-  | { error: string } {
-  const cwd = path.resolve(workspaceRoot);
-  const resolved = path.isAbsolute(planPath) ? planPath : path.join(cwd, planPath);
-  const text = readSafe(resolved);
-  if (text === null) return { error: `plan file not found: ${planPath}` };
-  const tasks = parseTasksFromPlan(text);
-  if (tasks.length === 0) {
-    return { error: "no ### Task N sections found — plan must follow writing-plans format" };
-  }
-  return { task_count: tasks.length, tasks };
-}
-
-export function resolveHandoffBranch(
-  specPath: string,
-  planPath: string,
-  workspaceRoot: string,
-): { branch: string } | { error: string } {
-  const resolved = resolveBranch({
-    spec_path: specPath,
-    plan_path: planPath,
-    workspace_root: workspaceRoot,
-  });
-  if ("error" in resolved) return { error: resolved.error as string };
-  return { branch: resolved.branch };
-}

package/src/core/reminder.ts

@@ -1,124 +0,0 @@
-import { DESTINATION_MENU_LABELS, HANDOFF_DESTINATION_MARKER, SOURCE_MENU_LABELS } from "./menu";
-
-// Display-only source label list: the "(new session only)" qualifier appears in
-// the reminder PROSE like the other source surfaces (bootstrap.ts, session-start,
-// superpowers-doc-contract.md, ask-question-only.mdc), never in the machine
-// label tuple `SOURCE_MENU_LABELS` — the receipt label must stay exactly
-// `Handoff` for the native-question match (AR-12). Exported so contract tests
-// assert the rendered reminder against this single source of truth instead of
-// re-deriving the mapping.
-export const SOURCE_MENU_LABELS_DISPLAY = SOURCE_MENU_LABELS.map((label) =>
-  label === "Handoff" ? "Handoff (new session only)" : label,
-);
-
-export const REMINDER_TEXT = `<workflow-contract-reminder>
-- Bounded user choices → call the native \`question\` tool (never A/B/C or 1/2/3 lists in prose).
-- After a plan is approved → native \`question\` menu with exactly: ${SOURCE_MENU_LABELS_DISPLAY.join(", ")}.
-- Tools with \`confirmed\` → call them; never fabricate their result.
-- Before the first \`workit_spec_approve\`/\`workit_plan_approve\` (self-review) run the superpowers writing-plans Self-Review checklist: spec coverage (every spec requirement maps to a task), placeholder scan, type consistency; fix findings inline.
-- Delivering docs → clickable markdown link \`[spec.md](docs/<slug>/spec.md)\` + 3-5 bullet summary.
-</workflow-contract-reminder>`;
-
-/**
- * Destination reminder (CA-07, CA-08): a marked handoff destination carries the
- * exact marker and the four-label allow-list — never the originating Handoff
- * choice. Hosts select source vs destination wording via `reminderTextFor`
- * from `FlowState.handoff_destination`; the strings live here, not in adapters.
- */
-export const DESTINATION_REMINDER_TEXT = `<workflow-contract-reminder>
-- Bounded user choices → call the native \`question\` tool (never A/B/C or 1/2/3 lists in prose).
-- This session is a handoff destination: present the post-plan menu with exactly: ${DESTINATION_MENU_LABELS.join(", ")}.
-- Tools with \`confirmed\` → call them; never fabricate their result.
-- Before the first \`workit_spec_approve\`/\`workit_plan_approve\` (self-review) run the superpowers writing-plans Self-Review checklist: spec coverage (every spec requirement maps to a task), placeholder scan, type consistency; fix findings inline.
-- Delivering docs → clickable markdown link \`[spec.md](docs/<slug>/spec.md)\` + 3-5 bullet summary.
-${HANDOFF_DESTINATION_MARKER}
-</workflow-contract-reminder>`;
-
-/** Select source vs destination reminder wording from the flow's destination flag (CA-08). */
-export const reminderTextFor = (destination: boolean): string =>
-  destination ? DESTINATION_REMINDER_TEXT : REMINDER_TEXT;
-
-export const DETECTION_TEXT = `<workflow-detection>
-Your previous message presented choices as a numbered/bulleted list in prose.
-That is a bounded user choice — use the native \`question\` tool instead (re-ask with \`question\` if still relevant).
-</workflow-detection>`;
-
-export const DOC_DELIVERY_TEXT = `<workflow-doc-delivery>
-You referenced a doc with a backtick-only path. Deliver docs with a clickable markdown link \`[spec.md](docs/<slug>/spec.md)\` and a 3-5 bullet summary of the content.
-</workflow-doc-delivery>`;
-
-export const SDD_REMINDER_TEXT = `<workflow-sdd-reminder>
-An approved plan is subagent-driven — execute it via \`wk-implement\` / \`task\` delegation. Never implement the approved plan inline in the main session.
-</workflow-sdd-reminder>`;
-
-/**
- * Worker-only context (CA-16): an authorized direct child of the activating
- * coordinator receives ONLY this compact contract — never the coordinator
- * bootstrap or SDD_REMINDER_TEXT. It carries the worker duties (brief, TDD,
- * commit range, report) and no coordination instructions.
- */
-export const SDD_WORKER_REMINDER_TEXT = `<workflow-sdd-worker>
-You are an authorized delegated worker for an active subagent-driven plan.
-Execute only the supplied task brief: follow TDD (failing test first), land exactly one contiguous non-empty commit range for your task, then report status, commits, and test results to the coordinator. Do not manage coordinator bookkeeping or launch another agent harness.
-</workflow-sdd-worker>`;
-
-export const DOC_RENDER_TEXT = `<workflow-doc-render>
-When delivering a spec or plan, by default render the full markdown content of the doc in chat (headings, tables, mermaid fences preserved) — NOT a backtick-wrapped raw block.
-If the doc exceeds the render threshold (more than 150 lines, over 8KB, or more than 3 mermaid diagrams), deliver only the clickable link \`[spec.md](docs/<slug>/spec.md)\` + a 3-5 bullet summary.
-On an explicit raw request ("raw", "para copiar", "sin render"), show the full fenced block instead.
-Platform note: always use the standard \`\`\`mermaid fence — Cursor CLI renders it as an ASCII diagram, editors/GitHub render it natively; OpenCode TUI shows it as code text (renderer limitation, not a defect). Inline markdown links are not clickable in the OpenCode TUI.
-</workflow-doc-render>`;
-
-export const ISSUE_RAIL_TEXT = `<workflow-issue-rail>
-A clickable \`question\` option whose label is an instruction (e.g. "Type the issue URL/ID") returns the label literal when clicked, not free text — ask for free text in plain prose with the custom answer field enabled instead.
-</workflow-issue-rail>`;
-
-export const CONFIG_GUARD_TEXT = `<workflow-config-guard>
-A tool failed with a config-gap error (\`workflow config missing\`). Never configure without asking — ask with the native \`question\` tool, exactly three options: (1) configure only what's missing (guided, via the /wk-init skill flow for those actions), (2) run the full wizard (\`npx workit init\`), (3) skip — report the final error naming the missing items and how to configure them.
-</workflow-config-guard>`;
-
-export const VERIFICATION_TEXT = `<workflow-verification-rail>
-Skill: verification-before-completion. NO completion claims without fresh verification evidence — run the check command (e.g. \`bun run check\` / \`workit_verify\`) and show its output before claiming done/fixed/passing. If you haven't run the verification command in this message, you cannot claim it passes.
-</workflow-verification-rail>`;
-
-export const TDD_TEXT = `<workflow-tdd-rail>
-Skill: test-driven-development. NO production code without a failing test first — write the test, watch it fail, then write the minimal code to pass.
-</workflow-tdd-rail>`;
-
-export const BRAINSTORM_TEXT = `<workflow-brainstorm-rail>
-Skill: brainstorming. NO implementation until a design is presented and approved — explore intent, ask clarifying questions one at a time, present the design, and get user approval before writing any code.
-</workflow-brainstorm-rail>`;
-
-export const DEBUG_TEXT = `<workflow-debug-rail>
-Skill: systematic-debugging. NO fixes without root cause investigation first — read the error, reproduce consistently, find the root cause, then fix. Symptom fixes are failure.
-</workflow-debug-rail>`;
-
-export const REVIEW_RECEPTION_TEXT = `<workflow-review-reception-rail>
-Skill: receiving-code-review. Verify before implementing — evaluate review feedback against codebase reality (read, restate, verify) before accepting or acting on it.
-</workflow-review-reception-rail>`;
-
-export const shouldInjectVerification = (currentText: string): boolean =>
-  !currentText.includes(VERIFICATION_TEXT);
-
-export const shouldInjectTdd = (currentText: string): boolean => !currentText.includes(TDD_TEXT);
-
-export const shouldInjectBrainstorm = (currentText: string): boolean =>
-  !currentText.includes(BRAINSTORM_TEXT);
-
-export const shouldInjectDebug = (currentText: string): boolean =>
-  !currentText.includes(DEBUG_TEXT);
-
-export const shouldInjectReviewReception = (currentText: string): boolean =>
-  !currentText.includes(REVIEW_RECEPTION_TEXT);
-
-export const shouldInjectDocRender = (currentText: string): boolean =>
-  !currentText.includes(DOC_RENDER_TEXT);
-
-export const shouldInjectSddReminder = (currentText: string): boolean =>
-  !currentText.includes(SDD_REMINDER_TEXT);
-
-export const shouldInjectConfigGuard = (currentText: string): boolean =>
-  !currentText.includes(CONFIG_GUARD_TEXT);
-
-export const shouldInjectIssueRail = (currentText: string): boolean =>
-  !currentText.includes(ISSUE_RAIL_TEXT);