@xzzpig/pi-openspec-x 0.1.0

package/src/task-sync.ts

@@ -0,0 +1,226 @@
+/**
+ * tasks.md ⇄ goal task tree reconciliation (design D10; openspec change
+ * add-pi-openspec-x, task 6.3).
+ *
+ * `tasks.md` is the openspec contract and the authoritative task source; the
+ * goal task tree is the execution base's state. Synchronization is
+ * ONE-DIRECTIONAL: the assembler mirrors tasks.md through `set_goal_tasks`,
+ * the main agent ticks tasks.md after review and follows with
+ * `update_goal_task`, and a goal-tree-only change (a manual edit in the
+ * dashboard) never flows back into tasks.md.
+ *
+ * This module is the pure reconciliation core: it compares the parsed
+ * tasks.md against the current goal tree, reports every divergence with
+ * tasks.md as the winner, and produces the two payloads the caller needs —
+ * the authoritative flat mirror for `set_goal_tasks` and the ordered
+ * `update_goal_task` follow-ups that align task status.
+ *
+ * Two goal states cannot be reconciled automatically because goal-x forbids
+ * them: a completed task is immutable, so a goal task that is `complete` while
+ * tasks.md says it is not done cannot be reopened. That divergence is surfaced
+ * as a blocking warning instead of a silent half-sync.
+ */
+import {
+  assembleOpsxObjective,
+  type FlatGoalTaskInput,
+  type OpsxBoundaries,
+} from "./objective.ts";
+import { goalStatusForTask, parseTasksMarkdown } from "./tasks-md.ts";
+
+/** Minimal structural view of goal-x's GoalTask (no runtime import). */
+export interface GoalTaskLike {
+  id: string;
+  title?: string;
+  /** pending | complete | skipped (goal-x has no distinct "start" status). */
+  status?: string;
+  subtasks?: GoalTaskLike[];
+}
+
+/** One ordered `update_goal_task` follow-up. */
+export interface TaskSyncUpdate {
+  taskId: string;
+  status: "pending" | "complete";
+  /** True when completing a contracted task needs evidence. */
+  requiresEvidence: boolean;
+}
+
+export interface TaskSyncPlan {
+  /** True when ids, titles and done status all agree. */
+  consistent: boolean;
+  /** The authoritative flat mirror to pass to `set_goal_tasks`. */
+  mirror: FlatGoalTaskInput[];
+  /** Ordered follow-ups to align the goal tree's status with tasks.md. */
+  updates: TaskSyncUpdate[];
+  /** tasks.md ids missing from the goal tree (the mirror adds them). */
+  missingGoalIds: string[];
+  /** Goal-tree ids with no tasks.md counterpart (the mirror removes them). */
+  goalOnlyIds: string[];
+  /** Same id, different title (the mirror rewrites the title). */
+  titleMismatches: string[];
+  /** Same id, different done state (an update aligns it, or a warning blocks). */
+  statusMismatches: string[];
+  /** Divergences that cannot be reconciled automatically. */
+  blockingIds: string[];
+  /** Human-readable warnings; empty when consistent. */
+  warnings: string[];
+}
+
+/** Flatten a goal task tree into roots-first document order. */
+export function flattenGoalTasks(
+  tasks: readonly GoalTaskLike[] | undefined,
+): GoalTaskLike[] {
+  const flat: GoalTaskLike[] = [];
+  const walk = (list: readonly GoalTaskLike[]): void => {
+    for (const task of list) {
+      flat.push(task);
+      if (task.subtasks && task.subtasks.length > 0) walk(task.subtasks);
+    }
+  };
+  if (tasks) walk(tasks);
+  return flat;
+}
+
+/**
+ * Reconcile tasks.md against the current goal task tree. tasks.md always wins:
+ * a goal-only id is removed by the mirror, a missing id is added, a title
+ * mismatch is rewritten, and a status mismatch is corrected by the emitted
+ * updates (unless goal-x forbids it, which is reported as blocking).
+ */
+export function planTaskSync(input: {
+  tasksMarkdown: string | undefined;
+  goalTasks: readonly GoalTaskLike[] | undefined;
+}): TaskSyncPlan {
+  const tasks = input.tasksMarkdown
+    ? parseTasksMarkdown(input.tasksMarkdown)
+    : [];
+  const goalFlat = flattenGoalTasks(input.goalTasks);
+  const goalById = new Map(goalFlat.map((task) => [task.id, task]));
+  const taskIds = new Set(tasks.map((task) => task.id));
+
+  const mirror = tasks.map((task) => ({
+    id: task.id,
+    title: task.title,
+    ...(task.verificationContract
+      ? { verification_contract: task.verificationContract }
+      : {}),
+  }));
+
+  const missingGoalIds: string[] = [];
+  const titleMismatches: string[] = [];
+  const statusMismatches: string[] = [];
+  const blockingIds: string[] = [];
+  const updates: TaskSyncUpdate[] = [];
+
+  for (const task of tasks) {
+    const goalTask = goalById.get(task.id);
+    if (!goalTask) {
+      missingGoalIds.push(task.id);
+      continue;
+    }
+    if (goalTask.title !== undefined && goalTask.title !== task.title) {
+      titleMismatches.push(task.id);
+    }
+    const expected = goalStatusForTask(task);
+    const actual = goalTask.status ?? "pending";
+    if (actual === expected) continue;
+    statusMismatches.push(task.id);
+    if (actual === "complete") {
+      // goal-x: completed tasks are immutable, so tasks.md cannot win here.
+      blockingIds.push(task.id);
+      continue;
+    }
+    if (actual === "skipped" && expected === "complete") {
+      // skipped cannot complete directly; reopen, then complete.
+      updates.push({
+        taskId: task.id,
+        status: "pending",
+        requiresEvidence: false,
+      });
+      updates.push({
+        taskId: task.id,
+        status: "complete",
+        requiresEvidence: Boolean(task.verificationContract),
+      });
+      continue;
+    }
+    updates.push({
+      taskId: task.id,
+      status: expected,
+      requiresEvidence:
+        expected === "complete" && Boolean(task.verificationContract),
+    });
+  }
+
+  const goalOnlyIds = goalFlat
+    .filter((task) => !taskIds.has(task.id))
+    .map((task) => task.id);
+
+  const warnings: string[] = [];
+  if (missingGoalIds.length > 0) {
+    warnings.push(
+      `tasks.md has ${missingGoalIds.length} task(s) missing from the goal tree (${missingGoalIds.join(", ")}); tasks.md is authoritative, so re-mirroring adds them.`,
+    );
+  }
+  if (goalOnlyIds.length > 0) {
+    warnings.push(
+      `The goal tree has ${goalOnlyIds.length} task(s) that tasks.md does not (${goalOnlyIds.join(", ")}); goal-tree-only edits never flow back, so re-mirroring removes them.`,
+    );
+  }
+  if (titleMismatches.length > 0) {
+    warnings.push(
+      `Task title(s) differ from tasks.md (${titleMismatches.join(", ")}); tasks.md wins and re-mirroring rewrites them.`,
+    );
+  }
+  if (statusMismatches.length > 0) {
+    warnings.push(
+      `Task status differs from tasks.md (${statusMismatches.join(", ")}); tasks.md wins and update_goal_task follows to align it.`,
+    );
+  }
+  if (blockingIds.length > 0) {
+    warnings.push(
+      `Task(s) ${blockingIds.join(", ")} are complete in the goal tree but not done in tasks.md; goal-x never reopens a completed task, so this cannot be auto-reconciled — fix tasks.md or start a fresh goal.`,
+    );
+  }
+
+  return {
+    consistent:
+      missingGoalIds.length === 0 &&
+      goalOnlyIds.length === 0 &&
+      titleMismatches.length === 0 &&
+      statusMismatches.length === 0,
+    mirror,
+    updates,
+    missingGoalIds,
+    goalOnlyIds,
+    titleMismatches,
+    statusMismatches,
+    blockingIds,
+    warnings,
+  };
+}
+
+/**
+ * Assemble the objective and derive the authoritative mirror in one step. The
+ * task-count gate stays in the assembler (a change over the `set_goal_tasks`
+ * limit is refused there, never mirrored partially).
+ */
+export function assembleAndPlanSync(input: {
+  changeId: string;
+  tasksMarkdown: string | undefined;
+  boundaries: OpsxBoundaries;
+  goalTasks: readonly GoalTaskLike[] | undefined;
+}): {
+  assembly: ReturnType<typeof assembleOpsxObjective>;
+  sync: TaskSyncPlan;
+} {
+  const assembly = assembleOpsxObjective({
+    changeId: input.changeId,
+    tasksMarkdown: input.tasksMarkdown,
+    boundaries: input.boundaries,
+  });
+  const sync = planTaskSync({
+    tasksMarkdown: input.tasksMarkdown,
+    goalTasks: input.goalTasks,
+  });
+  return { assembly, sync };
+}

package/src/tasks-md.ts

@@ -0,0 +1,136 @@
+/**
+ * Parser for openspec's `tasks.md` tracking format (design D10; openspec
+ * change add-pi-openspec-x, task 6.2).
+ *
+ * openspec's apply phase tracks progress by parsing checkbox lines, and its
+ * instruction is explicit about the rule: a box whose content trims to `x`
+ * (any case, any spacing) is done; every other box marker (`- [~]`, `- [-]`,
+ * an empty `- []`, ...) reads as unfinished; a line with no checkbox is not
+ * tracked at all. This parser implements exactly that rule, so the plugin's
+ * mirror of the task list can never disagree with `openspec apply` about what
+ * is done.
+ *
+ * The authoritative source is `tasks.md`: this module only reads it. Nothing
+ * here writes, and no goal-x type leaks in — the goal task tree is built by
+ * ./objective.ts from the parsed tasks.
+ */
+
+/** One tracked task parsed out of tasks.md. */
+export interface OpsxTask {
+  /** The `X.Y` identifier openspec puts in front of the description. */
+  id: string;
+  /** Task description with the id and any explicit verification suffix removed. */
+  title: string;
+  /** True when the checkbox content trims to `x` (openspec's done rule). */
+  done: boolean;
+  /** Nearest `## ...` group heading, when the task sits under one. */
+  section?: string;
+  /**
+   * The verification requirement, when the description carries an explicit
+   * `验证：` / `Verification:` marker. openspec asks authors to state the
+   * verification inside the description; when it is marked off, the goal task
+   * carries it as its verification contract so the completion gate can demand
+   * evidence.
+   */
+  verificationContract?: string;
+}
+
+/**
+ * A checkbox list item. The `(?:\s+(.*))?` tail is deliberate: a markdown
+ * link (`- [text](url)`) has no whitespace after `]`, so it never parses as a
+ * task.
+ */
+const CHECKBOX_RE = /^(\s*)[-*]\s+\[([^\]]*)\](?:\s+(.*))?\s*$/;
+
+/** A group heading: `## 1. Setup`, `### 2.3 ...` (any depth). */
+const GROUP_HEADING_RE = /^#{1,6}\s+(.*\S)\s*$/;
+
+/** The `X.Y` id prefix openspec writes: `1.1`, `2.3.4`. */
+const ID_PREFIX_RE = /^(\d+(?:\.\d+)*)[.)]?\s+(.*)$/;
+
+/** Explicit verification marker (Chinese or English, colon required). */
+const VERIFICATION_MARKER_RE = /(?:验证|Verification|Verify)\s*[:：]/i;
+
+function splitVerification(text: string): {
+  title: string;
+  verificationContract?: string;
+} {
+  const match = VERIFICATION_MARKER_RE.exec(text);
+  if (!match || match.index === 0) return { title: text.trim() };
+  const title = text
+    .slice(0, match.index)
+    .replace(/[；;]\s*$/, "")
+    .trim();
+  const contract = text.slice(match.index + match[0].length).trim();
+  if (!title || !contract) return { title: text.trim() };
+  return { title, verificationContract: contract };
+}
+
+function parseTaskDescription(
+  description: string,
+  index: number,
+): { id: string; title: string; verificationContract?: string } {
+  // The id prefix is extracted first: the verification marker may follow it
+  // directly (`1.1 验证：...`), which would otherwise hide the id.
+  const idMatch = ID_PREFIX_RE.exec(description);
+  const id = idMatch ? idMatch[1]! : `task-${index + 1}`;
+  const rest = (idMatch ? idMatch[2]! : description).trim();
+  const { title, verificationContract } = splitVerification(rest);
+  return { id, title, verificationContract };
+}
+
+/**
+ * Parse tasks.md into the ordered tracked task list. Lines that are not
+ * checkboxes (prose, headings, blank lines) are ignored, matching openspec's
+ * "a line with no checkbox is not tracked at all" rule. Checkboxes with an
+ * empty description are skipped too: they track nothing a goal task could
+ * mirror.
+ */
+export function parseTasksMarkdown(markdown: string): OpsxTask[] {
+  const tasks: OpsxTask[] = [];
+  let section: string | undefined;
+  for (const raw of markdown.replace(/\r\n?/g, "\n").split("\n")) {
+    const heading = GROUP_HEADING_RE.exec(raw);
+    if (heading) {
+      section = heading[1]!.trim();
+      continue;
+    }
+    const checkbox = CHECKBOX_RE.exec(raw);
+    if (!checkbox) continue;
+    const description = (checkbox[3] ?? "").trim();
+    if (!description) continue;
+    const parsed = parseTaskDescription(description, tasks.length);
+    tasks.push({
+      id: parsed.id,
+      title: parsed.title,
+      done: checkbox[2]!.trim().toLowerCase() === "x",
+      ...(section ? { section } : {}),
+      ...(parsed.verificationContract
+        ? { verificationContract: parsed.verificationContract }
+        : {}),
+    });
+  }
+  return tasks;
+}
+
+/**
+ * openspec's done rule as a goal task status: the mirror uses the binary
+ * pending/complete mapping only (design D10; no `start`/`skipped` middle
+ * states ever cross the boundary).
+ */
+export function goalStatusForTask(
+  task: Pick<OpsxTask, "done">,
+): "pending" | "complete" {
+  return task.done ? "complete" : "pending";
+}
+
+/** Ids of every parsed task, in order; used for duplicate detection. */
+export function duplicateTaskIds(tasks: readonly OpsxTask[]): string[] {
+  const seen = new Set<string>();
+  const duplicates = new Set<string>();
+  for (const task of tasks) {
+    if (seen.has(task.id)) duplicates.add(task.id);
+    else seen.add(task.id);
+  }
+  return [...duplicates];
+}

package/src/worker-dispatch.ts

@@ -0,0 +1,152 @@
+/**
+ * Worker dispatch contract and post-dispatch review gate (design D10; openspec
+ * change add-pi-openspec-x, task 8.2).
+ *
+ * Agent mode implements every task through a full-write `opsx-worker`
+ * dispatch. Two deterministic pieces make that safe:
+ *
+ * 1. the six-section dispatch contract (Task, Expected output, Tools, Must do,
+ *    Must not do, Context) — plan files stay read-only for the worker, and
+ *    ticking tasks.md stays with the main agent;
+ * 2. the tick gate: a task may be ticked only after the worker's
+ *    `report_work` is reconciled, file by file, with the diff the dispatch
+ *    actually produced, and the stated verification actually ran and passed.
+ *    An unreviewed or unverified dispatch leaves the task unticked, and a
+ *    report that claims files nobody changed (or omits files that changed) is
+ *    a finding, not a completion.
+ *
+ * The gate returns a decision; the caller performs the tasks.md write and the
+ * goal-task sync (task 6.3). Nothing here writes files.
+ */
+
+/**
+ * Structural view of the opsx-worker `report_work` payload (the schema lives
+ * in report-tools.ts; only the fields the gate reconciles are named here).
+ */
+export interface WorkReportLike {
+  taskId: string;
+  changedFiles: string[];
+  claims: string;
+  selfVerification: { command?: string; result?: string };
+  /** Structured verdict; the gate trusts it over the result text. */
+  verificationPassed?: boolean;
+}
+
+/**
+ * The standard prohibitions every worker dispatch carries. The single source
+ * the agent objective's prose reuses: plan files stay read-only for the
+ * worker, ticking tasks.md stays with the main agent, and drive-by changes
+ * are out.
+ */
+export const STANDARD_WORKER_MUST_NOT_DO = [
+  "Do not modify anything under openspec/ (tasks.md, proposal.md, specs/, design.md); plan files are read-only for you.",
+  "Do not tick tasks.md or any checkbox; the main agent ticks after reviewing your diff.",
+  "Do not touch files outside the task scope or make drive-by changes.",
+];
+
+/** The review facts the main agent gathered after a dispatch. */
+export interface DispatchReview {
+  /** Repository-relative files the dispatch actually changed (window delta). */
+  observedChangedFiles: string[];
+  /** Whether the stated verification ran, and whether it passed. */
+  verification: { ran: boolean; passed: boolean; evidence?: string };
+}
+
+export type TaskTickDecision =
+  | { kind: "tick"; taskId: string; evidence: string }
+  | { kind: "hold"; taskId: string; reason: string };
+
+function normalize(filePath: string): string {
+  return filePath.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+/**
+ * Decide whether a task may be ticked. Holds (never ticks) when:
+ * - no report was submitted;
+ * - the report claims files the diff does not contain (phantom work);
+ * - the diff contains files the report omitted (unclaimed work);
+ * - the verification did not run or did not pass.
+ */
+export function decideTaskTick(
+  report: WorkReportLike | undefined,
+  review: DispatchReview,
+): TaskTickDecision {
+  const taskId = report?.taskId ?? "<unknown>";
+  if (!report) {
+    return {
+      kind: "hold",
+      taskId,
+      reason:
+        "No report_work was submitted; review the dispatch output before ticking.",
+    };
+  }
+
+  const claimed = new Set(report.changedFiles.map(normalize));
+  const observed = new Set(review.observedChangedFiles.map(normalize));
+  const phantom = [...claimed].filter((file) => !observed.has(file));
+  const unclaimed = [...observed].filter((file) => !claimed.has(file));
+  if (phantom.length > 0) {
+    return {
+      kind: "hold",
+      taskId,
+      reason: `The report claims file(s) the dispatch did not change: ${phantom.join(", ")}. Reconcile before ticking.`,
+    };
+  }
+  if (unclaimed.length > 0) {
+    return {
+      kind: "hold",
+      taskId,
+      reason: `The dispatch changed file(s) the report omitted: ${unclaimed.join(", ")}. Review and correct the report before ticking.`,
+    };
+  }
+
+  if (!review.verification.ran) {
+    return {
+      kind: "hold",
+      taskId,
+      reason:
+        "The task's verification has not been run; tick only after it passes.",
+    };
+  }
+  if (!review.verification.passed) {
+    return {
+      kind: "hold",
+      taskId,
+      reason: `The task's verification failed${review.verification.evidence ? `: ${review.verification.evidence}` : ""}. Fix and re-verify before ticking.`,
+    };
+  }
+
+  return {
+    kind: "tick",
+    taskId,
+    evidence:
+      review.verification.evidence ??
+      report.selfVerification.result ??
+      "verification passed",
+  };
+}
+
+/**
+ * A bounded dispatch trace used to detect a spinning goal: a dispatch that
+ * changed nothing and reported nothing is a stall, not progress.
+ */
+export interface DispatchTrace {
+  taskId: string;
+  changedFiles: number;
+  ticked: boolean;
+}
+
+export function detectStalledDispatch(
+  traces: readonly DispatchTrace[],
+  threshold = 2,
+): { stalled: boolean; taskIds: string[] } {
+  const counts = new Map<string, number>();
+  for (const trace of traces) {
+    if (trace.ticked || trace.changedFiles > 0) continue;
+    counts.set(trace.taskId, (counts.get(trace.taskId) ?? 0) + 1);
+  }
+  const taskIds = [...counts.entries()]
+    .filter(([, count]) => count >= threshold)
+    .map(([taskId]) => taskId);
+  return { stalled: taskIds.length > 0, taskIds };
+}