@gitdocket/core 0.0.0 → 0.1.1

package/src/state-of-play.ts

@@ -0,0 +1,370 @@
+// Agent-authored product context. The engine parses and
+// presents committed judgment; it never authors it. overview.md is a reserved
+// bundle-root file so it stays out of the concept graph and generated index.
+
+import { parse as parseYaml } from "yaml";
+import type { Diagnostic } from "./parse";
+
+export const STATE_OF_PLAY_PATH = "overview.md";
+/** Evidence movement that makes an authored re-entry note worth revisiting. */
+export const STATE_OF_PLAY_STALE_COMMITS = 5;
+/** A quiet project must still review its last-known context occasionally. */
+export const STATE_OF_PLAY_REVIEW_MAX_DAYS = 14;
+export const REENTRY_CONTEXT_FORMAT = "re-entry/v2" as const;
+export const REENTRY_CONTEXT_V1_FORMAT = "re-entry/v1" as const;
+
+interface StateOfPlayBase {
+  /** Commit the authored judgment was written against. */
+  asOf: string;
+  /** Markdown after the machine-readable frontmatter. */
+  body: string;
+}
+
+/** The legacy prose format. It remains readable but is never current. */
+export interface LegacyStateOfPlayNote extends StateOfPlayBase {
+  format: "legacy";
+  updatedAt?: string;
+}
+
+/** The superseded assessment shape, retained for read compatibility. */
+export interface ReentryAssessment {
+  outcome: string;
+  bet: string;
+  evidence: string;
+  risk: string;
+  nextDecision: string;
+  decisions: string;
+  decisionLinks: string[];
+}
+
+export interface ReentryV1ContextNote extends StateOfPlayBase {
+  format: typeof REENTRY_CONTEXT_V1_FORMAT;
+  reviewedAt: string;
+  orientation: string;
+  assessment: ReentryAssessment;
+}
+
+/** A small linked note: recent outcomes, the frontier, and optional context. */
+export interface ReentryContextNote extends StateOfPlayBase {
+  format: typeof REENTRY_CONTEXT_FORMAT;
+  reviewedAt: string;
+  recent: string;
+  next: string;
+  worthKnowing?: string;
+  links: string[];
+  decisionLinks: string[];
+}
+
+export type StateOfPlayNote =
+  | LegacyStateOfPlayNote
+  | ReentryV1ContextNote
+  | ReentryContextNote;
+
+export type StateOfPlayReviewReason =
+  | "legacy-format"
+  | "superseded-format"
+  | "evidence-moved"
+  | "review-expired"
+  | "git-age-unavailable";
+
+export interface StateOfPlayReview {
+  /** Whether the last-known authored context should be revisited. */
+  status: "current" | "needs-review" | "age-unavailable";
+  reasons: StateOfPlayReviewReason[];
+  reviewedDaysAgo: number | null;
+  maxDays: number;
+}
+
+export type StateOfPlayView = StateOfPlayNote & {
+  /** Null when Git cannot resolve the watermark (for example outside a repo). */
+  taskCommitsAgo: number | null;
+  review: StateOfPlayReview;
+};
+
+export interface StateOfPlayParseResult {
+  note?: StateOfPlayNote;
+  diagnostics: Diagnostic[];
+}
+
+export interface StateOfPlayPresentationOptions {
+  now?: Date;
+}
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+const COMMIT_SHA = /^[0-9a-f]{7,40}$/i;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const V1_SECTION_NAMES = {
+  "product orientation": "orientation",
+  "current outcome": "outcome",
+  "current bet": "bet",
+  "evidence and learning": "evidence",
+  "principal risk": "risk",
+  "next decision": "nextDecision",
+  "material decisions": "decisions",
+} as const;
+
+const SECTION_NAMES = {
+  "what we've done recently": "recent",
+  "what's up next": "next",
+  "worth knowing": "worthKnowing",
+} as const;
+
+type V1SectionKey = (typeof V1_SECTION_NAMES)[keyof typeof V1_SECTION_NAMES];
+type SectionKey = (typeof SECTION_NAMES)[keyof typeof SECTION_NAMES];
+
+function structuredSections(
+  body: string,
+  diagnostics: Diagnostic[],
+  names: Record<string, string>,
+  required: string[],
+): Record<string, string> {
+  const sections: Record<string, string> = {};
+  const headings = [...body.matchAll(/^##[ \t]+(.+?)[ \t]*$/gm)];
+  for (const [index, heading] of headings.entries()) {
+    const name = heading[1]?.trim().toLowerCase() ?? "";
+    const key = names[name];
+    if (!key) continue;
+    const start = (heading.index ?? 0) + heading[0].length;
+    const end = headings[index + 1]?.index ?? body.length;
+    const value = body.slice(start, end).trim();
+    if (sections[key] !== undefined) {
+      diagnostics.push({
+        path: STATE_OF_PLAY_PATH,
+        message: `duplicate \`## ${heading[1]?.trim()}\` section`,
+        severity: "error",
+      });
+    } else {
+      sections[key] = value;
+    }
+  }
+
+  for (const heading of required) {
+    const key = names[heading];
+    if (!key || !sections[key]) {
+      diagnostics.push({
+        path: STATE_OF_PLAY_PATH,
+        message: `structured product context requires a non-empty \`## ${heading}\` section`,
+        severity: "error",
+      });
+    }
+  }
+  return sections;
+}
+
+const markdownLinks = (markdown: string): string[] =>
+  [...markdown.matchAll(/\]\(([^)]+)\)/g)].map((link) => link[1] ?? "");
+
+const validIsoDate = (value: unknown): value is string =>
+  typeof value === "string" && !Number.isNaN(Date.parse(value));
+
+/** Parse overview.md without treating it as an OKF concept. */
+export function parseStateOfPlay(source: string): StateOfPlayParseResult {
+  const diagnostics: Diagnostic[] = [];
+  const match = source.match(FRONTMATTER);
+  if (!match) {
+    return {
+      diagnostics: [
+        {
+          path: STATE_OF_PLAY_PATH,
+          message: "missing YAML frontmatter with an `as_of` commit SHA",
+          severity: "error",
+        },
+      ],
+    };
+  }
+
+  let raw: unknown;
+  try {
+    raw = parseYaml(match[1] ?? "");
+  } catch (error) {
+    return {
+      diagnostics: [
+        {
+          path: STATE_OF_PLAY_PATH,
+          message: `invalid YAML: ${String(error)}`,
+          severity: "error",
+        },
+      ],
+    };
+  }
+  const fm =
+    typeof raw === "object" && raw !== null
+      ? (raw as Record<string, unknown>)
+      : {};
+  const asOf = fm.as_of;
+  if (typeof asOf !== "string" || !COMMIT_SHA.test(asOf)) {
+    diagnostics.push({
+      path: STATE_OF_PLAY_PATH,
+      message: "`as_of` must be a 7–40 character hexadecimal commit SHA",
+      severity: "error",
+    });
+  }
+
+  const body = source.slice(match[0].length).trim();
+  if (!body) {
+    diagnostics.push({
+      path: STATE_OF_PLAY_PATH,
+      message: "product-context body is empty",
+      severity: "error",
+    });
+  }
+
+  const format = fm.format;
+  if (format === undefined) {
+    const updatedAt = fm.updated_at;
+    if (updatedAt !== undefined && !validIsoDate(updatedAt)) {
+      diagnostics.push({
+        path: STATE_OF_PLAY_PATH,
+        message: "`updated_at` must be an ISO-8601 string when present",
+        severity: "error",
+      });
+    }
+    if (diagnostics.length > 0 || typeof asOf !== "string")
+      return { diagnostics };
+    return {
+      note: {
+        format: "legacy",
+        asOf,
+        ...(typeof updatedAt === "string" ? { updatedAt } : {}),
+        body,
+      },
+      diagnostics,
+    };
+  }
+
+  if (
+    format !== REENTRY_CONTEXT_FORMAT &&
+    format !== REENTRY_CONTEXT_V1_FORMAT
+  ) {
+    diagnostics.push({
+      path: STATE_OF_PLAY_PATH,
+      message: `unsupported product-context format: ${String(format)}`,
+      severity: "error",
+    });
+    return { diagnostics };
+  }
+
+  const reviewedAt = fm.reviewed_at;
+  if (!validIsoDate(reviewedAt)) {
+    diagnostics.push({
+      path: STATE_OF_PLAY_PATH,
+      message: "`reviewed_at` must be an ISO-8601 string",
+      severity: "error",
+    });
+  }
+  const sections =
+    format === REENTRY_CONTEXT_V1_FORMAT
+      ? structuredSections(
+          body,
+          diagnostics,
+          V1_SECTION_NAMES,
+          Object.keys(V1_SECTION_NAMES),
+        )
+      : structuredSections(body, diagnostics, SECTION_NAMES, [
+          "what we've done recently",
+          "what's up next",
+        ]);
+  if (
+    diagnostics.length > 0 ||
+    typeof asOf !== "string" ||
+    typeof reviewedAt !== "string"
+  )
+    return { diagnostics };
+
+  if (format === REENTRY_CONTEXT_V1_FORMAT) {
+    const legacySections = sections as Partial<Record<V1SectionKey, string>>;
+    const decisions = legacySections.decisions ?? "";
+    return {
+      note: {
+        format: REENTRY_CONTEXT_V1_FORMAT,
+        asOf,
+        reviewedAt,
+        body,
+        orientation: legacySections.orientation ?? "",
+        assessment: {
+          outcome: legacySections.outcome ?? "",
+          bet: legacySections.bet ?? "",
+          evidence: legacySections.evidence ?? "",
+          risk: legacySections.risk ?? "",
+          nextDecision: legacySections.nextDecision ?? "",
+          decisions,
+          decisionLinks: markdownLinks(decisions),
+        },
+      },
+      diagnostics,
+    };
+  }
+
+  const currentSections = sections as Partial<Record<SectionKey, string>>;
+  const recent = currentSections.recent ?? "";
+  const next = currentSections.next ?? "";
+  const worthKnowing = currentSections.worthKnowing;
+  const links = markdownLinks(
+    [recent, next, worthKnowing].filter(Boolean).join("\n"),
+  );
+  return {
+    note: {
+      format: REENTRY_CONTEXT_FORMAT,
+      asOf,
+      reviewedAt,
+      body,
+      recent,
+      next,
+      ...(worthKnowing ? { worthKnowing } : {}),
+      links,
+      decisionLinks: links.filter((link) =>
+        link.replace(/^\//, "").startsWith("decisions/"),
+      ),
+    },
+    diagnostics,
+  };
+}
+
+export function presentStateOfPlay(
+  note: StateOfPlayNote,
+  taskCommitsAgo: number | undefined,
+  options: StateOfPlayPresentationOptions = {},
+): StateOfPlayView {
+  const reviewedAt =
+    note.format === "legacy" ? note.updatedAt : note.reviewedAt;
+  const reviewedTime = reviewedAt ? Date.parse(reviewedAt) : Number.NaN;
+  const reviewedDaysAgo = Number.isNaN(reviewedTime)
+    ? null
+    : Math.max(
+        0,
+        Math.floor(
+          ((options.now ?? new Date()).getTime() - reviewedTime) / DAY_MS,
+        ),
+      );
+  const reasons: StateOfPlayReviewReason[] = [];
+  if (note.format === "legacy") reasons.push("legacy-format");
+  if (note.format === REENTRY_CONTEXT_V1_FORMAT)
+    reasons.push("superseded-format");
+  if ((taskCommitsAgo ?? 0) >= STATE_OF_PLAY_STALE_COMMITS)
+    reasons.push("evidence-moved");
+  if (
+    reviewedDaysAgo !== null &&
+    reviewedDaysAgo >= STATE_OF_PLAY_REVIEW_MAX_DAYS
+  )
+    reasons.push("review-expired");
+  if (taskCommitsAgo === undefined) reasons.push("git-age-unavailable");
+
+  const needsReview = reasons.some(
+    (reason) => reason !== "git-age-unavailable",
+  );
+  return {
+    ...note,
+    taskCommitsAgo: taskCommitsAgo ?? null,
+    review: {
+      status: needsReview
+        ? "needs-review"
+        : taskCommitsAgo === undefined
+          ? "age-unavailable"
+          : "current",
+      reasons,
+      reviewedDaysAgo,
+      maxDays: STATE_OF_PLAY_REVIEW_MAX_DAYS,
+    },
+  };
+}

package/src/states.ts

@@ -0,0 +1,85 @@
+// The task-profile state machine (docs/specs/okf-task-profile.md).
+
+export const STATES = [
+  "todo",
+  "in-progress",
+  "blocked",
+  "in-review",
+  "done",
+  "closed",
+] as const;
+export type Status = (typeof STATES)[number];
+
+export const TERMINAL_STATES = ["done", "closed"] as const;
+
+export const WORK_ITEM_TYPES = ["Epic", "Task"] as const;
+export type WorkItemType = (typeof WORK_ITEM_TYPES)[number];
+
+export const DECISION_STATES = ["proposed", "accepted", "superseded"] as const;
+export type DecisionStatus = (typeof DECISION_STATES)[number];
+
+export const PRIORITIES = ["p0", "p1", "p2", "p3"] as const;
+export type Priority = (typeof PRIORITIES)[number];
+
+export function isStatus(value: string): value is Status {
+  return (STATES as readonly string[]).includes(value);
+}
+
+export function isTerminalStatus(value: string): value is Status {
+  return (TERMINAL_STATES as readonly string[]).includes(value);
+}
+
+export function isPriority(value: string): value is Priority {
+  return (PRIORITIES as readonly string[]).includes(value);
+}
+
+/**
+ * Allowed transitions (normative — mirrored in the task profile spec):
+ * `done` is reachable from any non-blocked state, `closed` from every
+ * non-terminal state, `blocked` from every non-terminal state, and both
+ * `done` and `closed` are terminal.
+ */
+export const TRANSITIONS: Record<Status, readonly Status[]> = {
+  todo: ["in-progress", "blocked", "done", "closed"],
+  "in-progress": ["in-review", "done", "closed", "blocked", "todo"],
+  "in-review": ["done", "closed", "in-progress", "blocked"],
+  blocked: ["todo", "in-progress", "closed"],
+  done: [],
+  closed: [],
+};
+
+export function canTransition(from: Status, to: Status): boolean {
+  return TRANSITIONS[from].includes(to);
+}
+
+/**
+ * Manual order: ranked items first, lower `rank` first, priority as
+ * the tiebreak and the order for the unranked tail. The ready lists (CLI and
+ * MCP) sort with this so "next task" honors hand-set order.
+ */
+export function byManualOrder(
+  a: { id?: string; rank?: number; priority?: Priority },
+  z: { id?: string; rank?: number; priority?: Priority },
+): number {
+  const ar = typeof a.rank === "number" ? a.rank : null;
+  const zr = typeof z.rank === "number" ? z.rank : null;
+  if (ar !== null && zr !== null && ar !== zr) return ar - zr;
+  if ((ar !== null) !== (zr !== null)) return ar !== null ? -1 : 1;
+  const priority = (a.priority ?? "p2").localeCompare(z.priority ?? "p2");
+  if (priority !== 0) return priority;
+  return (a.id ?? "").localeCompare(z.id ?? "", undefined, { numeric: true });
+}
+
+/**
+ * `ready` is derived, never written: a task is ready iff it is `todo` and
+ * every dependency is `done`. Unknown dependency IDs make a task not-ready
+ * (lint flags them separately).
+ */
+export function isReady(
+  status: Status,
+  dependsOn: readonly string[],
+  statusById: ReadonlyMap<string, Status>,
+): boolean {
+  if (status !== "todo") return false;
+  return dependsOn.every((id) => statusById.get(id) === "done");
+}

package/src/upgrade.ts

@@ -0,0 +1,177 @@
+// docket upgrade — pure per-file transforms. Every vendored item retains a
+// provenance story, and each category has an explicit upgrade
+// story: adapters regenerate when marked (never merged), repo-owned workflows
+// 3-way merge against the shipped text at their origin version. Filesystem
+// and git orchestration live in the CLI; the merge itself is injected so this
+// module stays runtime-portable.
+
+import {
+  formatOrigin,
+  parseOrigin,
+  recoverOrigin,
+  type ShippedHistory,
+  shippedHistory,
+  shippedWorkflow,
+} from "./shipped";
+import { DOCKET_VERSION } from "./version";
+import { hasAdapterMarker } from "./workflows";
+
+export type UpgradeAction =
+  | "regenerated"
+  | "replaced"
+  | "merged"
+  | "conflict"
+  | "up-to-date"
+  | "skipped";
+
+export interface UpgradeResult {
+  action: UpgradeAction;
+  /** File content after the upgrade (unchanged for up-to-date/skipped). */
+  content: string;
+  /** Provenance version the file carried before, when determinable. */
+  from?: string;
+  reason?: string;
+}
+
+/**
+ * Three-way merge: base = shipped text at origin, ours = the repo's copy,
+ * theirs = the new shipped text. Returns merged content and whether conflict
+ * markers were left behind. Injected by the caller (`git merge-file` in the
+ * CLI) — core doesn't carry a diff3 implementation.
+ */
+export type Merge3 = (
+  base: string,
+  ours: string,
+  theirs: string,
+) => { content: string; conflict: boolean };
+
+/**
+ * Version carried by a docket marker line (skill stub, section fence, hook
+ * block). Undefined for legacy unversioned markers — report those as
+ * upgradable from an unknown version, never a blocker.
+ */
+export function markerVersion(text: string): string | undefined {
+  return text.match(
+    /(?:docket init|docket prepare-commit-msg|>>> docket(?: mcp)?)@(\d+\.\d+\.\d+)/,
+  )?.[1];
+}
+
+/**
+ * Upgrade a regenerable adapter: marked files are overwritten with the
+ * current generation, hand-authored files are never touched (same rule as
+ * init). `generated` is today's render of the same adapter.
+ */
+export function upgradeAdapter(
+  existing: string,
+  generated: string,
+): UpgradeResult {
+  const from = markerVersion(existing);
+  if (existing === generated)
+    return { action: "up-to-date", content: existing, from };
+  if (hasAdapterMarker(existing))
+    return { action: "regenerated", content: generated, from };
+  return {
+    action: "skipped",
+    content: existing,
+    reason: "hand-authored — remove to regenerate",
+  };
+}
+
+/** Set (or insert) the `origin:` line inside a frontmatter block. */
+function stampOrigin(fm: string, value: string): string {
+  if (/^origin:.*$/m.test(fm))
+    return fm.replace(/^origin:.*$/m, `origin: ${value}`);
+  if (/^tags:/m.test(fm))
+    return fm.replace(/^tags:/m, `origin: ${value}\ntags:`);
+  return fm.replace(/\n---\n$/, `\norigin: ${value}\n---\n`);
+}
+
+/**
+ * Upgrade a repo-owned workflow file. Origin comes from the `origin:`
+ * frontmatter stamp, falling back to text-match recovery for pre-stamp
+ * copies. Unmodified from origin → replace with the new shipped body;
+ * diverged → 3-way merge. Only the body and the origin line change — the
+ * rest of the frontmatter (timestamp, any customized fields) is repo-owned
+ * and never touched. Merges — clean or conflicted — stamp the new version:
+ * after resolution the new shipped text is the base the copy descends from.
+ */
+export function upgradeWorkflowFile(
+  source: string,
+  opts: { merge3: Merge3; history?: ShippedHistory; current?: string },
+): UpgradeResult {
+  const history = opts.history ?? shippedHistory();
+  const current = opts.current ?? DOCKET_VERSION;
+
+  const fmMatch = source.match(/^---\n[\s\S]*?\n---\n/);
+  if (!fmMatch)
+    return { action: "skipped", content: source, reason: "no frontmatter" };
+  const fm = fmMatch[0];
+  const body = source.slice(fm.length).trim();
+
+  const stamped = fm.match(/^origin:\s*(\S+)\s*$/m);
+  const origin = stamped?.[1]
+    ? parseOrigin(stamped[1])
+    : recoverOrigin(source, history);
+  if (!origin) {
+    return {
+      action: "skipped",
+      content: source,
+      reason: stamped
+        ? `malformed origin "${stamped[1]}"`
+        : "origin unknown — customized before stamping, resolve by hand",
+    };
+  }
+
+  const base = shippedWorkflow(origin.slug, origin.version, history);
+  if (base === undefined) {
+    return {
+      action: "skipped",
+      content: source,
+      from: origin.version,
+      reason: `no shipped text for ${formatOrigin(origin)}`,
+    };
+  }
+  const available = shippedWorkflow(origin.slug, current, history);
+  if (available === undefined) {
+    return {
+      action: "skipped",
+      content: source,
+      from: origin.version,
+      reason: `${origin.slug} is not shipped at ${current}`,
+    };
+  }
+
+  const newFm = stampOrigin(fm, `${origin.slug}@${current}`);
+  const rebuild = (newBody: string) => `${newFm}\n${newBody.trim()}\n`;
+
+  if (body === base.trim()) {
+    const content = rebuild(available);
+    return content === source
+      ? { action: "up-to-date", content: source, from: origin.version }
+      : { action: "replaced", content, from: origin.version };
+  }
+
+  const merged = opts.merge3(base.trim(), body, available.trim());
+  const content = rebuild(merged.content);
+  if (merged.conflict)
+    return { action: "conflict", content, from: origin.version };
+  if (content === source) {
+    // Nothing propagated. When the copy still differs from the shipped text,
+    // say so instead of a bare up-to-date — this is either a customization
+    // (fine) or a copy vendored from a since-edited pre-release template
+    // A bare report would hide this change.
+    const reason =
+      body === available.trim()
+        ? {}
+        : {
+            reason: `differs from shipped ${current} — local text kept (customized, or the template changed in place)`,
+          };
+    return {
+      action: "up-to-date",
+      content: source,
+      from: origin.version,
+      ...reason,
+    };
+  }
+  return { action: "merged", content, from: origin.version };
+}