@brainervirus/workit-core 0.8.1 → 0.8.2

package/src/core/handoff-context.ts

@@ -124,5 +124,13 @@ export const buildHandoffContract = ({
     .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

@@ -2,6 +2,7 @@ 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>>;
@@ -33,13 +34,21 @@ export type HandoffRequest = {
   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" | "select";
+  stage?: "create" | "seed" | "mark" | "select";
 };
 
 export const message = (error: unknown) =>
@@ -78,6 +87,17 @@ export async function handoffSession(
     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 {

package/src/core/menu.ts

@@ -0,0 +1,68 @@
+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",
+] as const;
+
+/** Display labels a marked destination presents — exactly four, no Handoff (CA-08). */
+export const DESTINATION_MENU_LABELS = [
+  "Subagent-driven",
+  "Inline",
+  "Review spec first",
+  "Review plan 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/reminder.ts

@@ -1,11 +1,41 @@
+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).
+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: Subagent-driven, Inline, Handoff (new session only), Review spec first, Review plan first.
+- 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 \`workflow_spec_approve\`/\`workflow_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 \`workflow_spec_approve\`/\`workflow_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).

package/src/core/sdd.ts

@@ -34,6 +34,63 @@ export function todosFromTasks(
   return todos;
 }
 
+/** SDD ledger completeness facts shared by lifecycle migration, completion,
+ *  and active-plan detection (Task 2). */
+export type LedgerCompletion = {
+  /** True only when progress.md contains at least one `Task N:` record. */
+  started: boolean;
+  /** True only when every canonical plan task id appears completed. */
+  complete: boolean;
+  required: number[];
+  completed: number[];
+  missing: number[];
+};
+
+/**
+ * Read the canonical `docs/<slug>/sdd/progress.md` ledger and the plan's
+ * `### Task N:` headings. Fail-closed: a missing or unreadable ledger yields
+ * `started: false`, and a missing/unreadable plan yields an empty `required`
+ * set (never a partial trust of a stale ledger). `complete` requires a
+ * non-empty required set fully covered by completed task ids, so an empty plan
+ * can never read as "done".
+ */
+export function ledgerCompletion(root: string, slug: string): LedgerCompletion {
+  let started = false;
+  const completed: number[] = [];
+  const absProgress = path.join(root, "docs", slug, "sdd", "progress.md");
+  if (existsSync(absProgress)) {
+    try {
+      for (const line of readFileSync(absProgress, "utf8").split("\n")) {
+        const match = /^Task\s+(\d+):/i.exec(line);
+        if (match) {
+          started = true;
+          if (/^Task\s+\d+:\s*complete\b/i.test(line)) completed.push(Number(match[1]));
+        }
+      }
+    } catch {
+      // unreadable ledger: started stays false (fail-closed)
+    }
+  }
+  const required: number[] = [];
+  try {
+    const absPlan = path.join(root, "docs", slug, "plan.md");
+    if (existsSync(absPlan)) {
+      for (const task of parseTasksFromPlan(readFileSync(absPlan, "utf8"))) required.push(task.id);
+    }
+  } catch {
+    // unreadable/missing plan: required stays empty (fail-closed)
+  }
+  const completedSet = new Set(completed);
+  const missing = required.filter((id) => !completedSet.has(id));
+  return {
+    started,
+    complete: required.length > 0 && missing.length === 0,
+    required,
+    completed,
+    missing,
+  };
+}
+
 export function sddContext({
   slug,
   plan_path,

package/templates/execution-contract.md

@@ -5,6 +5,17 @@ Load `using-superpowers`, `subagent-driven-development`, `test-driven-developmen
 **Branch:** <BRANCH>
 **SDD:** `<SDD_DIR>`
 
+## Handoff destination
+
+This session is a handoff destination for a continued plan. The originating session already recorded the post-plan menu choice; present exactly these four choices and never re-offer the originating handoff option:
+
+- Subagent-driven
+- Inline
+- Review spec first
+- Review plan first
+
+<workflow-handoff-destination>true</workflow-handoff-destination>
+
 ## Hard gates
 
 - The parent is coordinator-only: it does not edit product code or perform delegated exploration.

package/templates/superpowers-doc-contract.md

@@ -63,6 +63,8 @@ On success, use native `question` / Cursor `AskQuestion` with exactly these opti
 
 Never emit Superpowers text beginning “Two execution options”.
 
+A handoff destination session (the seeded contract carries `<workflow-handoff-destination>true</workflow-handoff-destination>`) presents exactly four choices — Subagent-driven, Inline, Review spec first, Review plan first — and never re-offers the originating handoff option.
+
 - Specs/plans must follow `templates/spec-template.md` / `templates/plan-template.md` (mandated diagrams, tables, CA-XX).
 
 ## Doc delivery