@gitdocket/core 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitdocket/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "The typed file-and-graph engine behind GitDocket.",
   "license": "Apache-2.0",

package/src/cache.ts

@@ -5,8 +5,9 @@
 
 import type { Database } from "bun:sqlite";
 import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { Glob } from "bun";
 import type { Bundle } from "./bundle";
 import type { DocketConfig } from "./config";
@@ -29,6 +30,50 @@ export interface GitCheckpoint {
   time: string;
 }
 
+export interface GitWorktreeEvidence {
+  path: string;
+  head: string;
+  ref: string | null;
+  activeTaskId: string | null;
+  dirty: boolean | null;
+  mergedIntoCurrentHead: boolean | null;
+  current: boolean;
+  available: boolean;
+}
+
+export interface GitActivityObservation extends ActivityRow {
+  /** Unmerged observations are evidence only; current-checkout state stays canonical. */
+  mergedIntoCurrentHead: false;
+  refs: string[];
+  worktrees: string[];
+}
+
+export interface GitEvidence {
+  status: "available" | "history-unavailable";
+  checkpoint: GitCheckpoint | null;
+  /** Canonical activity reachable from the calling checkout's HEAD. */
+  activity: ActivityRow[];
+  /** Bounded task-linked commits reachable from local tips but not current HEAD. */
+  unmergedActivity: GitActivityObservation[];
+  /** Bounded linked-checkout inventory, including checkout-local active markers. */
+  worktrees: GitWorktreeEvidence[];
+  truncated: boolean;
+  reason?: string;
+}
+
+export interface GitEvidenceOptions {
+  commitLimit?: number;
+  refLimit?: number;
+  worktreeLimit?: number;
+  /** Test seam: pinned SHA inventory must survive refs/worktrees disappearing. */
+  afterInventory?: () => void;
+}
+
+export const GIT_EVIDENCE_COMMIT_LIMIT = 50;
+export const GIT_EVIDENCE_REF_LIMIT = 128;
+export const GIT_EVIDENCE_WORKTREE_LIMIT = 64;
+const GIT_EVIDENCE_SCAN_LIMIT_PER_TIP = 500;
+
 /** Current Git revision and commit time, or undefined outside usable history. */
 export function gitCheckpoint(cwd: string): GitCheckpoint | undefined {
   try {
@@ -45,6 +90,271 @@ export function gitCheckpoint(cwd: string): GitCheckpoint | undefined {
   }
 }
 
+const gitOutput = (cwd: string, args: string[]): string =>
+  execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    maxBuffer: 16 * 1024 * 1024,
+  });
+
+function parseActivityRecords(
+  output: string,
+  byId: Bundle["byId"],
+): ActivityRow[] {
+  return output
+    .split("\x1e")
+    .slice(1)
+    .flatMap((record) => {
+      const [sha, date, subject, trailers] = record.split("\x1f");
+      if (!sha || !date) return [];
+      return (trailers ?? "")
+        .split("\n")
+        .map((trailer) => trailer.trim())
+        .filter(Boolean)
+        .map((id) => ({
+          taskId: byId(id)?.fm.id ?? id,
+          sha,
+          date,
+          subject: (subject ?? "").trim(),
+        }));
+    });
+}
+
+function scanHeadActivity(
+  cwd: string,
+  trailerKey: string,
+  byId: Bundle["byId"],
+): ActivityRow[] {
+  return parseActivityRecords(
+    gitOutput(cwd, [
+      "log",
+      "HEAD",
+      `--format=%x1e%H%x1f%cI%x1f%s%x1f%(trailers:key=${trailerKey},valueonly)`,
+    ]),
+    byId,
+  );
+}
+
+interface TipSources {
+  refs: Set<string>;
+  worktrees: Set<string>;
+}
+
+function mergedInto(cwd: string, commit: string, head: string): boolean | null {
+  const result = Bun.spawnSync(
+    ["git", "merge-base", "--is-ancestor", commit, head],
+    { cwd, stdout: "ignore", stderr: "ignore" },
+  );
+  if (result.exitCode === 0) return true;
+  if (result.exitCode === 1) return false;
+  return null;
+}
+
+function worktreeEvidence(
+  cwd: string,
+  currentHead: string,
+): GitWorktreeEvidence[] {
+  const output = gitOutput(cwd, ["worktree", "list", "--porcelain", "-z"]);
+  return output
+    .split("\0\0")
+    .filter(Boolean)
+    .flatMap((record): GitWorktreeEvidence[] => {
+      const fields = record.split("\0");
+      const path = fields
+        .find((field) => field.startsWith("worktree "))
+        ?.slice("worktree ".length);
+      const head = fields
+        .find((field) => field.startsWith("HEAD "))
+        ?.slice("HEAD ".length);
+      if (!path || !head) return [];
+      const ref =
+        fields
+          .find((field) => field.startsWith("branch "))
+          ?.slice("branch ".length) ?? null;
+      let activeTaskId: string | null = null;
+      let dirty: boolean | null = null;
+      let available = true;
+      try {
+        activeTaskId =
+          readFileSync(join(path, ".docket", "active-task"), "utf8").trim() ||
+          null;
+      } catch {
+        // A missing marker is the normal idle state; availability is checked
+        // independently through Git status below.
+      }
+      try {
+        dirty =
+          gitOutput(path, [
+            "status",
+            "--porcelain=v1",
+            "--untracked-files=normal",
+          ]).trim().length > 0;
+      } catch {
+        available = false;
+      }
+      return [
+        {
+          path,
+          head,
+          ref,
+          activeTaskId,
+          dirty,
+          mergedIntoCurrentHead: mergedInto(cwd, head, currentHead),
+          current: resolve(path) === resolve(cwd),
+          available,
+        },
+      ];
+    });
+}
+
+function refTips(cwd: string): { ref: string; head: string }[] {
+  return gitOutput(cwd, [
+    "for-each-ref",
+    "--format=%(refname)%09%(objectname)",
+    "refs/heads",
+    "refs/remotes",
+  ])
+    .split("\n")
+    .filter(Boolean)
+    .flatMap((line) => {
+      const [ref, head] = line.split("\t");
+      return ref && head && /^[0-9a-f]{40}$/i.test(head) ? [{ ref, head }] : [];
+    });
+}
+
+/**
+ * Read-only, local Git evidence. Current-checkout bundle data remains the only
+ * source for identity, status, readiness, rollups, and authored narrative;
+ * these pinned observations never hydrate concepts from another ref.
+ */
+export function scanGitEvidence(
+  cwd: string,
+  trailerKey: string,
+  byId: Bundle["byId"],
+  options: GitEvidenceOptions = {},
+): GitEvidence {
+  const checkpoint = gitCheckpoint(cwd);
+  if (!checkpoint) {
+    return {
+      status: "history-unavailable",
+      checkpoint: null,
+      activity: [],
+      unmergedActivity: [],
+      worktrees: [],
+      truncated: false,
+      reason: "Git history is unavailable from this checkout",
+    };
+  }
+
+  try {
+    const commitLimit = options.commitLimit ?? GIT_EVIDENCE_COMMIT_LIMIT;
+    const refLimit = options.refLimit ?? GIT_EVIDENCE_REF_LIMIT;
+    const worktreeLimit = options.worktreeLimit ?? GIT_EVIDENCE_WORKTREE_LIMIT;
+    const allRefs = refTips(cwd).sort((a, z) => a.ref.localeCompare(z.ref));
+    const allWorktrees = worktreeEvidence(cwd, checkpoint.revision).sort(
+      (a, z) => a.path.localeCompare(z.path),
+    );
+    const refs = allRefs.slice(0, refLimit);
+    const worktrees = allWorktrees.slice(0, worktreeLimit);
+    let truncated =
+      refs.length < allRefs.length || worktrees.length < allWorktrees.length;
+
+    const tips = new Map<string, TipSources>();
+    const sourcesFor = (head: string): TipSources => {
+      const existing = tips.get(head) ?? {
+        refs: new Set<string>(),
+        worktrees: new Set<string>(),
+      };
+      tips.set(head, existing);
+      return existing;
+    };
+    for (const { ref, head } of refs) sourcesFor(head).refs.add(ref);
+    for (const worktree of worktrees) {
+      const sources = sourcesFor(worktree.head);
+      sources.worktrees.add(worktree.path);
+      if (worktree.ref) sources.refs.add(worktree.ref);
+    }
+
+    // Refs may disappear after this point; every subsequent read uses the
+    // immutable object ID captured above.
+    options.afterInventory?.();
+
+    const observations = new Map<
+      string,
+      GitActivityObservation & {
+        refSet: Set<string>;
+        worktreeSet: Set<string>;
+      }
+    >();
+    for (const [tip, sources] of tips) {
+      if (tip === checkpoint.revision) continue;
+      const rows = parseActivityRecords(
+        gitOutput(cwd, [
+          "log",
+          tip,
+          "--not",
+          checkpoint.revision,
+          `--max-count=${GIT_EVIDENCE_SCAN_LIMIT_PER_TIP + 1}`,
+          `--format=%x1e%H%x1f%cI%x1f%s%x1f%(trailers:key=${trailerKey},valueonly)`,
+        ]),
+        byId,
+      );
+      if (rows.length > GIT_EVIDENCE_SCAN_LIMIT_PER_TIP) truncated = true;
+      for (const row of rows.slice(0, GIT_EVIDENCE_SCAN_LIMIT_PER_TIP)) {
+        const key = `${row.sha}\x1f${row.taskId}`;
+        const observation = observations.get(key) ?? {
+          ...row,
+          mergedIntoCurrentHead: false as const,
+          refs: [],
+          worktrees: [],
+          refSet: new Set<string>(),
+          worktreeSet: new Set<string>(),
+        };
+        for (const ref of sources.refs) observation.refSet.add(ref);
+        for (const path of sources.worktrees) observation.worktreeSet.add(path);
+        observations.set(key, observation);
+      }
+    }
+
+    const unmergedActivity = [...observations.values()]
+      .sort(
+        (a, z) =>
+          z.date.localeCompare(a.date) ||
+          a.sha.localeCompare(z.sha) ||
+          a.taskId.localeCompare(z.taskId),
+      )
+      .map(({ refSet, worktreeSet, ...observation }) => ({
+        ...observation,
+        refs: [...refSet].sort(),
+        worktrees: [...worktreeSet].sort(),
+      }));
+    if (unmergedActivity.length > commitLimit) truncated = true;
+
+    const allActivity = scanHeadActivity(cwd, trailerKey, byId);
+    if (allActivity.length > commitLimit) truncated = true;
+
+    return {
+      status: "available",
+      checkpoint,
+      activity: allActivity.slice(0, commitLimit),
+      unmergedActivity: unmergedActivity.slice(0, commitLimit),
+      worktrees,
+      truncated,
+    };
+  } catch (error) {
+    return {
+      status: "history-unavailable",
+      checkpoint,
+      activity: [],
+      unmergedActivity: [],
+      worktrees: [],
+      truncated: false,
+      reason: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
 /**
  * Scan configured repo files for verification markers. This lives beside the
  * cache because both `docket index` and `docket serve` populate the same
@@ -82,28 +392,7 @@ export function scanActivity(
   byId: Bundle["byId"],
 ): ActivityRow[] {
   try {
-    const records = execFileSync(
-      "git",
-      [
-        "log",
-        `--format=%x1e%H%x1f%cI%x1f%s%x1f%(trailers:key=${trailerKey},valueonly)`,
-      ],
-      { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
-    ).split("\x1e");
-    return records.slice(1).flatMap((record) => {
-      const [sha, date, subject, trailers] = record.split("\x1f");
-      if (!sha || !date) return [];
-      return (trailers ?? "")
-        .split("\n")
-        .map((t) => t.trim())
-        .filter(Boolean)
-        .map((id) => ({
-          taskId: byId(id)?.fm.id ?? id, // aliases resolve to the canonical id
-          sha,
-          date,
-          subject: (subject ?? "").trim(),
-        }));
-    });
+    return scanHeadActivity(cwd, trailerKey, byId);
   } catch {
     return [];
   }

package/src/id-allocation.ts

@@ -0,0 +1,288 @@
+// Optional local-Git coordination for sequential work-item creation. The core
+// create path accepts this boundary explicitly so in-memory, filesystem-only,
+// and future hosted stores keep deterministic max+1 behavior without needing
+// a system Git binary.
+
+import { execFile } from "node:child_process";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { parseConfig } from "./config";
+import { LocalFileStore } from "./filestore";
+
+const execFileAsync = promisify(execFile);
+
+export interface WorkItemIdCoordinator {
+  allocate<T>(
+    project: string,
+    create: (knownIds: ReadonlySet<string>) => Promise<T>,
+  ): Promise<T>;
+}
+
+export interface GitWorktreeIdCoordinatorOptions {
+  lockTimeoutMs?: number;
+  staleLockMs?: number;
+  retryDelayMs?: number;
+}
+
+const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
+const DEFAULT_STALE_LOCK_MS = 5 * 60_000;
+const DEFAULT_RETRY_DELAY_MS = 25;
+const LOCK_DIRECTORY = "docket/id-allocation.lock";
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+
+const errorCode = (error: unknown): string | undefined =>
+  typeof error === "object" && error !== null && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+
+async function git(
+  repoRoot: string,
+  args: string[],
+): Promise<{ stdout: string; stderr: string }> {
+  return execFileAsync("git", ["-C", repoRoot, ...args], {
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+  });
+}
+
+async function gitCommonDirectory(repoRoot: string): Promise<string | null> {
+  try {
+    const { stdout } = await git(repoRoot, ["rev-parse", "--git-common-dir"]);
+    const value = stdout.trim();
+    if (!value) throw new Error("git returned an empty common directory");
+    return isAbsolute(value) ? value : resolve(repoRoot, value);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/not a git repository/i.test(message)) return null;
+    throw new Error(`cannot resolve Git common directory: ${message}`);
+  }
+}
+
+async function linkedWorktrees(repoRoot: string): Promise<string[]> {
+  const { stdout } = await git(repoRoot, [
+    "worktree",
+    "list",
+    "--porcelain",
+    "-z",
+  ]);
+  const paths = stdout
+    .split("\0")
+    .filter((line) => line.startsWith("worktree "))
+    .map((line) => line.slice("worktree ".length));
+  return [...new Set(paths)];
+}
+
+function readableWorkItemId(source: string): string | null {
+  const frontmatter = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!frontmatter?.[1]) return null;
+  const id = frontmatter[1].match(/^id:\s*['"]?([^\s'"#]+)['"]?\s*(?:#.*)?$/m);
+  return id?.[1] ?? null;
+}
+
+async function idsInWorktree(
+  worktree: string,
+  project: string,
+): Promise<string[]> {
+  let configSource: string;
+  try {
+    configSource = await readFile(join(worktree, "docket.yaml"), "utf8");
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      try {
+        await stat(worktree);
+      } catch (worktreeError) {
+        if (errorCode(worktreeError) === "ENOENT") {
+          throw new Error(
+            `linked worktree disappeared during ID allocation: ${worktree}; prune or restore it, then retry`,
+          );
+        }
+        throw worktreeError;
+      }
+      // A live worktree from before Docket adoption does not participate in
+      // this repository's work-item namespace.
+      return [];
+    }
+    throw error;
+  }
+
+  const config = parseConfig(configSource);
+  const store = new LocalFileStore(resolve(worktree, config.bundle));
+  let paths: string[];
+  try {
+    paths = await store.list();
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      throw new Error(
+        `cannot scan configured bundle ${config.bundle} in linked worktree ${worktree}; restore it or remove the stale worktree`,
+      );
+    }
+    throw error;
+  }
+
+  const ids: string[] = [];
+  for (const path of paths) {
+    if (!/^work\/(?:tasks|epics)\/.+\.md$/.test(path)) continue;
+    const source = await store.read(path).catch((error: unknown) => {
+      throw new Error(
+        `cannot read linked work item ${join(worktree, config.bundle, path)}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    });
+    const id = readableWorkItemId(source);
+    if (!id) {
+      throw new Error(
+        `cannot allocate an ID while linked work item ${join(worktree, config.bundle, path)} has no readable frontmatter id`,
+      );
+    }
+    if (id.startsWith(`${project}-`)) ids.push(id);
+  }
+  return ids;
+}
+
+async function repositoryIds(
+  repoRoot: string,
+  project: string,
+): Promise<Set<string>> {
+  const ids = new Set<string>();
+  for (const worktree of await linkedWorktrees(repoRoot)) {
+    for (const id of await idsInWorktree(worktree, project)) ids.add(id);
+  }
+  return ids;
+}
+
+interface LockOwner {
+  pid?: number;
+  host?: string;
+  startedAt?: string;
+}
+
+async function readOwner(lockDirectory: string): Promise<LockOwner | null> {
+  try {
+    return JSON.parse(
+      await readFile(join(lockDirectory, "owner.json"), "utf8"),
+    ) as LockOwner;
+  } catch {
+    return null;
+  }
+}
+
+function processIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return errorCode(error) === "EPERM";
+  }
+}
+
+async function lockIsStale(
+  lockDirectory: string,
+  staleLockMs: number,
+): Promise<boolean> {
+  const owner = await readOwner(lockDirectory);
+  if (
+    owner?.host === hostname() &&
+    typeof owner.pid === "number" &&
+    Number.isInteger(owner.pid)
+  ) {
+    return !processIsAlive(owner.pid);
+  }
+  const metadata = await stat(lockDirectory);
+  return Date.now() - metadata.mtimeMs >= staleLockMs;
+}
+
+async function acquireLock(
+  commonDirectory: string,
+  options: Required<GitWorktreeIdCoordinatorOptions>,
+): Promise<string> {
+  const parent = join(commonDirectory, "docket");
+  const lockDirectory = join(commonDirectory, LOCK_DIRECTORY);
+  await mkdir(parent, { recursive: true });
+  const started = Date.now();
+
+  for (;;) {
+    try {
+      await mkdir(lockDirectory);
+      await writeFile(
+        join(lockDirectory, "owner.json"),
+        `${JSON.stringify({
+          pid: process.pid,
+          host: hostname(),
+          startedAt: new Date().toISOString(),
+        })}\n`,
+        "utf8",
+      );
+      return lockDirectory;
+    } catch (error) {
+      if (errorCode(error) !== "EEXIST") throw error;
+
+      if (
+        await lockIsStale(lockDirectory, options.staleLockMs).catch(() => true)
+      ) {
+        const staleDirectory = `${lockDirectory}.stale-${process.pid}-${Date.now()}`;
+        try {
+          await rename(lockDirectory, staleDirectory);
+          await rm(staleDirectory, { recursive: true, force: true });
+          continue;
+        } catch (recoveryError) {
+          if (
+            errorCode(recoveryError) === "ENOENT" ||
+            errorCode(recoveryError) === "EEXIST"
+          ) {
+            continue;
+          }
+          throw new Error(
+            `cannot recover stale Docket ID-allocation lock ${lockDirectory}: ${recoveryError instanceof Error ? recoveryError.message : String(recoveryError)}`,
+          );
+        }
+      }
+
+      if (Date.now() - started >= options.lockTimeoutMs) {
+        const owner = await readOwner(lockDirectory);
+        throw new Error(
+          `timed out after ${options.lockTimeoutMs}ms waiting for Docket ID-allocation lock ${lockDirectory}${owner ? ` (owner ${owner.host ?? "unknown"}:${owner.pid ?? "unknown"}, started ${owner.startedAt ?? "unknown"})` : ""}`,
+        );
+      }
+      await sleep(options.retryDelayMs);
+    }
+  }
+}
+
+/**
+ * Same-repository coordinator for LocalFileStore creation. The lock lives in
+ * Git's common directory, so every linked worktree uses one allocation
+ * boundary. The scan reads each live worktree's own docket.yaml and working
+ * files, which includes staged, unstaged, and untracked concepts.
+ */
+export class GitWorktreeIdCoordinator implements WorkItemIdCoordinator {
+  private readonly options: Required<GitWorktreeIdCoordinatorOptions>;
+
+  constructor(
+    private readonly repoRoot: string,
+    options: GitWorktreeIdCoordinatorOptions = {},
+  ) {
+    this.options = {
+      lockTimeoutMs: options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS,
+      staleLockMs: options.staleLockMs ?? DEFAULT_STALE_LOCK_MS,
+      retryDelayMs: options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS,
+    };
+  }
+
+  async allocate<T>(
+    project: string,
+    create: (knownIds: ReadonlySet<string>) => Promise<T>,
+  ): Promise<T> {
+    const commonDirectory = await gitCommonDirectory(this.repoRoot);
+    if (!commonDirectory) return create(new Set());
+
+    const lockDirectory = await acquireLock(commonDirectory, this.options);
+    try {
+      return await create(await repositoryIds(this.repoRoot, project));
+    } finally {
+      await rm(lockDirectory, { recursive: true, force: true });
+    }
+  }
+}

package/src/index.ts

@@ -19,6 +19,11 @@ export {
   READY_QUEUE_DESCRIPTION,
 } from "./engine-semantics";
 export { type FileStore, InMemoryFileStore, LocalFileStore } from "./filestore";
+export {
+  GitWorktreeIdCoordinator,
+  type GitWorktreeIdCoordinatorOptions,
+  type WorkItemIdCoordinator,
+} from "./id-allocation";
 export { applyIndex, INDEX_MARKER, renderIndex } from "./indexmd";
 export {
   ALLOW_RULES,

package/src/ops.ts

@@ -7,6 +7,7 @@ import { stringify as stringifyYaml } from "yaml";
 import { type Bundle, loadBundle } from "./bundle";
 import type { DocketConfig } from "./config";
 import type { FileStore } from "./filestore";
+import type { WorkItemIdCoordinator } from "./id-allocation";
 import { resolveLink } from "./lint";
 import {
   canTransition,
@@ -42,11 +43,17 @@ export function slugify(title: string): string {
 }
 
 /** Next work-item number: max over ids matching `<project>-<n>`, plus one. */
-export function nextId(bundle: Bundle): string {
+export function nextId(
+  bundle: Bundle,
+  knownIds: ReadonlySet<string> = new Set(),
+): string {
   const pattern = new RegExp(`^${bundle.config.project}-(\\d+)$`);
   let max = 0;
-  for (const item of bundle.workItems) {
-    const match = item.fm.id.match(pattern);
+  for (const id of [
+    ...bundle.workItems.map((item) => item.fm.id),
+    ...knownIds,
+  ]) {
+    const match = id.match(pattern);
     if (match?.[1]) max = Math.max(max, Number(match[1]));
   }
   return `${bundle.config.project}-${max + 1}`;
@@ -59,41 +66,54 @@ export async function createWorkItem(
   store: FileStore,
   config: DocketConfig,
   input: CreateInput,
+  coordinator?: WorkItemIdCoordinator,
 ): Promise<{ id: string; path: string }> {
-  const bundle = await loadBundle(store, config);
-  const id = nextId(bundle);
-  if (bundle.byId(id))
-    throw new Error(`id collision on ${id} — bundle has duplicate ids?`);
+  const create = async (
+    knownIds: ReadonlySet<string>,
+  ): Promise<{ id: string; path: string }> => {
+    // Load inside the coordination boundary: another caller may have created
+    // an item while this process waited for the shared lock.
+    const bundle = await loadBundle(store, config);
+    const id = nextId(bundle, knownIds);
+    if (bundle.byId(id) || knownIds.has(id))
+      throw new Error(`id collision on ${id} — bundle has duplicate ids?`);
+
+    const type = input.type ?? "Task";
+    const slug = input.slug ?? slugify(input.title);
+    const dir = type === "Epic" ? "work/epics" : "work/tasks";
+    const path = `${dir}/${id}-${slug}.md`;
 
-  const type = input.type ?? "Task";
-  const slug = input.slug ?? slugify(input.title);
-  const dir = type === "Epic" ? "work/epics" : "work/tasks";
-  const path = `${dir}/${id}-${slug}.md`;
+    const lines = [
+      yamlLine("type", type),
+      yamlLine("title", input.title),
+      ...(input.description
+        ? [yamlLine("description", input.description)]
+        : []),
+      yamlLine("id", id),
+      yamlLine("status", "todo"),
+      ...(input.epic ? [yamlLine("epic", input.epic)] : []),
+      ...(input.dependsOn?.length
+        ? [`depends_on: [${input.dependsOn.join(", ")}]`]
+        : []),
+      yamlLine("priority", input.priority ?? "p2"),
+      ...(input.rank !== undefined ? [yamlLine("rank", input.rank)] : []),
+      ...(input.assignee ? [yamlLine("assignee", input.assignee)] : []),
+      ...(input.tags?.length ? [`tags: [${input.tags.join(", ")}]`] : []),
+      yamlLine("timestamp", new Date().toISOString().replace(/\.\d{3}Z$/, "Z")),
+    ];
 
-  const lines = [
-    yamlLine("type", type),
-    yamlLine("title", input.title),
-    ...(input.description ? [yamlLine("description", input.description)] : []),
-    yamlLine("id", id),
-    yamlLine("status", "todo"),
-    ...(input.epic ? [yamlLine("epic", input.epic)] : []),
-    ...(input.dependsOn?.length
-      ? [`depends_on: [${input.dependsOn.join(", ")}]`]
-      : []),
-    yamlLine("priority", input.priority ?? "p2"),
-    ...(input.rank !== undefined ? [yamlLine("rank", input.rank)] : []),
-    ...(input.assignee ? [yamlLine("assignee", input.assignee)] : []),
-    ...(input.tags?.length ? [`tags: [${input.tags.join(", ")}]`] : []),
-    yamlLine("timestamp", new Date().toISOString().replace(/\.\d{3}Z$/, "Z")),
-  ];
+    const context = input.epic
+      ? `See [epic](${input.epic}).`
+      : "(links to specs/docs here)";
+    const body = `# Context\n\n${context}\n\n# Acceptance Criteria\n\n- [ ] …\n`;
 
-  const context = input.epic
-    ? `See [epic](${input.epic}).`
-    : "(links to specs/docs here)";
-  const body = `# Context\n\n${context}\n\n# Acceptance Criteria\n\n- [ ] …\n`;
+    await store.write(path, `---\n${lines.join("\n")}\n---\n\n${body}`);
+    return { id, path };
+  };
 
-  await store.write(path, `---\n${lines.join("\n")}\n---\n\n${body}`);
-  return { id, path };
+  return coordinator
+    ? coordinator.allocate(config.project, create)
+    : create(new Set());
 }
 
 function splitFrontmatter(source: string): { fm: string; rest: string } {

package/src/orientation.ts

@@ -7,8 +7,9 @@ import { Database } from "bun:sqlite";
 import type { Bundle } from "./bundle";
 import {
   buildCache,
-  gitCheckpoint,
+  type GitEvidence,
   scanActivity,
+  scanGitEvidence,
   taskLinkedCommitsSince,
 } from "./cache";
 import type { DocketConfig } from "./config";
@@ -25,6 +26,7 @@ import {
 
 export type RepositoryOverview = OverviewModel & {
   narrative?: StateOfPlayView;
+  git: GitEvidence;
 };
 
 export interface RepositoryOverviewInput {
@@ -43,6 +45,17 @@ export async function deriveRepositoryOverview({
 }: RepositoryOverviewInput): Promise<RepositoryOverview> {
   const db = new Database(":memory:");
   try {
+    const git = root
+      ? scanGitEvidence(root, config.git.trailer, bundle.byId)
+      : {
+          status: "history-unavailable" as const,
+          checkpoint: null,
+          activity: [],
+          unmergedActivity: [],
+          worktrees: [],
+          truncated: false,
+          reason: "repository root was not provided",
+        };
     buildCache(
       db,
       bundle,
@@ -50,10 +63,9 @@ export async function deriveRepositoryOverview({
     );
     const source = await store.read(STATE_OF_PLAY_PATH).catch(() => undefined);
     const note = source ? parseStateOfPlay(source).note : undefined;
-    const checkpoint = root ? gitCheckpoint(root) : undefined;
     const model = deriveOverview(bundle, db, {
-      checkpoint,
-      historyAvailable: Boolean(checkpoint),
+      checkpoint: git.checkpoint ?? undefined,
+      historyAvailable: git.status === "available",
       decisionLinks:
         note?.format === REENTRY_CONTEXT_FORMAT
           ? note.decisionLinks
@@ -69,7 +81,7 @@ export async function deriveRepositoryOverview({
             : undefined,
         )
       : undefined;
-    return narrative ? { narrative, ...model } : model;
+    return narrative ? { narrative, ...model, git } : { ...model, git };
   } finally {
     db.close();
   }

package/src/shipped-history.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.1.1",
+    "bodies": {
+      "docket-pickup": "Use this workflow only for authorized tracked Docket work. Pickup authority requires positive evidence: a Docket ID, an unambiguous reference to an existing tracked item, or an explicit request to select the next Docket or backlog item. Generic implementation language does not select pickup. A concrete direct request proceeds in the user's stated scope without creating, starting, or adopting Docket work; do not invoke this workflow for it.\n\n1. **Resolve the target and command**: a Docket ID authorizes `docket task start <ID> --json`. Resolve an unambiguous tracked-item reference to its ID, then use the same named command. Only explicit next-Docket-task or backlog-selection language authorizes bare `docket task start --json`. If an apparent tracked reference remains ambiguous, perform only focused resolution or ask for clarification; never omit the ID, substitute the top ready item, or mutate `.docket/active-task`.\n2. **Start through the engine**: run only the command authorized in step 1. If the command fails, stop; do not rename the session or begin tracked work.\n3. **Use the returned title intent**: read `suggestedSessionTitle` from the successful structured result. Do not rebuild it from prompt text or separately queried task fields.\n4. **Best-effort rename**: ask the current harness's native adapter to name the calling session with that exact value. If the host has no current-session naming capability, the capability is unavailable, or the rename fails, continue silently without retrying or treating pickup as failed.\n5. **Hand off context**: use the returned task, epic, dependency, linked-concept, and commit fields as the context packet, then begin the requested tracked work.\n\nStored status changes go through the engine's canonical transition table; invalid transitions are rejected, `done` and `closed` are terminal, and moving to `closed` requires a disposition note. Only `done` satisfies dependencies or counts as completion.\n\nThe engine owns task selection, the state-machine-checked status transition, active-task state, title derivation, and the context packet; the pickup workflow owns only their sequence, and a native adapter owns only its bounded rename binding.",
+      "docket-epic": "Supervise the named epic until its acceptance criteria support explicit closure or one concrete blocker prevents safe progress. Docket files and task-linked Git history are the durable source of truth. Native worker, wait, follow-up, notification, and isolated-checkout capabilities are optional accelerators; they never change readiness or completion semantics.\n\n## 1. Establish the authoritative graph\n\n1. Confirm the user named an epic and authorized running it, not merely reviewing it. Read the epic file, verify that it is an Epic with an ID and title, then run `docket task list --epic <EPIC-ID> --all --json` and `docket ready --json`.\n2. Derive one manager title from those authoritative epic fields, exactly `Epic <ID> — <title>`, and retain it for the entire supervision run. Ask the current harness's native adapter to apply it to the calling manager session. Unsupported, unavailable, or failed rename capability is a silent no-op; it never blocks supervision.\n3. Record the manager baseline: current Git commit and branch, working-tree state, epic status and acceptance criteria, every child status and dependency, already-linked task commits, and the stopping condition. Preserve unrelated user changes; do not hide, overwrite, or move them into a worker checkout.\n4. Use the engine's ready result as authoritative. Ready is derived, never written: a task is ready only when its stored status is `todo` and every dependency resolves to `done`; an unknown dependency blocks it. The ready queue puts ranked tasks first by ascending `rank`; rank ties and the unranked tail use priority (`p0` through `p3`), then ascending task ID as the stable fallback. Filter that result to the named epic; never dispatch from a remembered or hand-derived ready list.\n5. If no child is ready but unfinished children remain, inspect their dependency and blocked-state evidence. Continue only when Docket state identifies a resolvable in-scope next action; otherwise prepare the blocker receipt in section 6.\n\n## 2. Preflight isolation and likely write overlap\n\nBefore creating any worker, inspect each ready child's context, acceptance criteria, linked concepts, and likely implementation/test/generated-document surfaces. Parallel writing is allowed only when every selected child is dependency-independent, likely write sets are materially distinct, each worker has a separate checkout at the exact accepted manager ref, and the manager can integrate and verify results one at a time. Treat shared workflow templates, generated adapters, dependency manifests, schemas, migrations, indexes, and central registries as likely overlap unless evidence shows otherwise.\n\nIf any condition is unknown or false—or if the host lacks a verified worker, wait/follow-up, notification, or isolated-checkout binding—use the mandatory serial fallback: run exactly one child at a time in the calling session or one isolated worker, integrate it fully, refresh Docket state, and only then choose the next child. Never run concurrent writers in one checkout. A shared `.docket/active-task` is single-checkout state, not a coordination mechanism.\n\n## 3. Dispatch one bounded child contract\n\nFor each selected child, provide the exact task ID, accepted baseline commit, isolated checkout or serial location, permitted scope, acceptance criteria, relevant linked concepts, expected verification, and these constraints:\n\n- follow [the pickup workflow](/workflows/docket-pickup.md) before implementation and [the close workflow](/workflows/docket-close.md) only after the task is actually complete;\n- change only the named child and required reconciliation surfaces; do not start siblings, close the epic, or invent orchestration infrastructure;\n- preserve unrelated changes, use task-linked commits, clear the checkout's active-task marker after close, and return commit hashes, verification results, interventions, and exact blockers;\n- do not claim integration or readiness changes from the worker checkout—the manager re-establishes those facts after accepting the result.\n\nWhen no native worker binding is available, execute this same contract serially in the calling session. The contract, not process count, defines supervision.\n\nAn isolated child session follows pickup normally and keeps its own `<ID> — <title>` task name; never apply the manager title to that child. In the serial fallback, child pickup can temporarily rename the shared calling session, so immediately after every successful child pickup reapply the retained `Epic <ID> — <title>` manager title before implementation continues. A failed or unsupported restoration remains a silent no-op and does not change task state or the child contract.\n\n## 4. Inspect and integrate one result at a time\n\n1. Treat a worker report as a lead, not authority. Inspect its checkout or ref, diff, task file, checked or explicitly waived criteria, Outcome, Log, commit trailers, verification output, and clean active-task state.\n2. Reject or return incomplete, out-of-scope, unverified, or ambiguously based work. Keep the branch/worktree/ref recoverable and state the required correction. Never mark the child done merely because the worker said it finished.\n3. Integrate one accepted commit series into the manager checkout. Resolve only understood in-scope conflicts; otherwise stop integration, preserve both refs and the conflict evidence, and produce a blocker receipt. Do not integrate a second result against unresolved or unverified state.\n4. Run the verification proportionate to the accepted diff, regenerate derived state with `docket index`, then rerun `docket task list --epic <EPIC-ID> --all --json` and `docket ready --json`. Re-read the epic and Git history. Select further work only from this refreshed state.\n5. At every accepted boundary, durable task files plus integrated Git commits must be sufficient for a replacement manager to resume. Native task IDs and wait cursors are useful transient handles, never the recovery source of truth.\n\n## 5. Review and close the epic explicitly\n\nAll children being done is necessary evidence, not epic completion. When no unfinished child remains, review every epic acceptance criterion against integrated task Outcomes, diffs, tests, decisions, and reconciled docs. Run final repository verification. If any criterion lacks evidence, create or identify the smallest in-scope follow-on child and continue; do not check or waive a criterion silently.\n\nWhen every criterion is satisfied or explicitly waived with a reason, apply the close workflow to the epic itself: write its Outcome with commit evidence, reconcile affected concepts, close through the engine, regenerate the index, update the log, and commit with the epic's task trailer. Verify the integrated epic status rather than inferring it from the close command's prose.\n\n## 6. Return one consolidated receipt\n\nReturn only after verified epic closure or a concrete blocker. Before returning, ask the native adapter to reapply the retained manager title once so the calling session ends on the epic rather than incidental child work; unsupported or failed rename remains a silent no-op. A completion receipt names the epic, integrated child and epic commits, verification performed, serial-versus-parallel choice and why, interventions or conflicts, and any deliberately deferred follow-up. A blocker receipt names the exact failing child or epic criterion, dependency/decision/error, last accepted manager commit, preserved worker refs or worktrees, current Docket state, checks already attempted, and the single action needed to resume.\n\nDo not create an orchestration database, scheduler, permanent runner, or synthetic epic status. On interruption, restart this workflow from section 1: Docket and Git reveal completed children and the next authoritative ready set; absent native lifecycle state simply selects the serial fallback.",
+      "docket-task": "Create a work item conformant with the OKF task profile (bundled at `specs/okf-task-profile.md` when the repo carries it). The request describes the item (\"task: add X to Y, epic phase-1, depends on KEY-8\").\n\n**Prefer the engine**: `docket task create --title \"…\" --epic /work/epics/… --deps KEY-x,KEY-y --priority p1 --description \"…\"` handles ID assignment, file placement, and a conformant template. Then edit the created file to fill in real `# Context` links and `# Acceptance Criteria`, and run `docket index`. The manual steps below are the fallback when the engine is unavailable.\n\n1. **Assign the ID**: work items (tasks AND epics) take the next number in the project sequence under the key from `docket.yaml` — `grep -rh \"^id: KEY-\" <bundle>/`, max + 1. Decisions likewise on their own prefix (default `DEC-`). Verify the result is unused.\n2. **Write the file** at `work/tasks/<ID>-<short-slug>.md` (epics → `work/epics/`, decisions → `decisions/`) with frontmatter: `type`, `title`, `description` (one sentence), `id`, `status: todo`, `epic` (bundle-absolute link — ask or infer; a task without an epic is allowed but noted), `depends_on` (task IDs, omit if none), `priority` (default `p2`), `assignee`, `tags`, `timestamp` (current UTC ISO 8601).\n3. **Body**: `# Context` — link the relevant specs/docs/decisions (bundle-absolute paths); `# Acceptance Criteria` — checkboxes, verifiable, few. Omit `# Log` until there's something to log.\n4. **Regenerate the index** (`docket index`) and add a `log.md` entry when the item is notable.\n5. If work starts now, follow [the pickup workflow](/workflows/docket-pickup.md). It delegates task state and context-packet mechanics to `docket task start <ID> --json`; never set the active task without the status move or vice versa. Pausing later is `docket task stop` (clears the active task, status stays).\n\nNever skip or reuse numbers, never hand-maintain task lists inside epic files, never mark `status` beyond `todo` at creation.",
+      "docket-groom": "Run this full backlog-hygiene audit only when the user explicitly asks to groom or audit the backlog, find stale or inconsistent work, or review task hygiene. Ordinary status, orientation, what-is-next, and review requests use `docket overview --json` instead and stop when that structured response is sufficient.\n\nRead every file in `work/` and report, then apply agreed fixes. Start from the engine: `docket ready --json` and `docket task list --json`.\n\nThe engine owns ready/list derivation and task mutation mechanics; the groom workflow owns audit judgment, proposed changes, and the authorization boundary.\n\n1. **Derive ready**: `docket ready` (never compute by hand). Ready is derived, never written: a task is ready only when its stored status is `todo` and every dependency resolves to `done`; an unknown dependency blocks it. The ready queue puts ranked tasks first by ascending `rank`; rank ties and the unranked tail use priority (`p0` through `p3`), then ascending task ID as the stable fallback.\n2. **Flag inconsistencies**:\n   - `in-progress` tasks with no commits trailer-matching their ID (`git log --grep \"Task: <ID>\"`) and no Log entry in 7+ days → probably stalled; propose `blocked` or `todo`.\n   - `done` tasks with unchecked acceptance criteria or missing `# Outcome`.\n   - `closed` tasks without a concrete `# Disposition` and replacement links when applicable.\n   - `depends_on` pointing at nonexistent or done-and-superseded IDs; broken bundle links (`docket lint`).\n   - Epics without a `spec` link; tasks without an `epic` link.\n   - `index.md` out of sync (`docket index` fixes; report if it changes anything).\n3. **Propose, then apply**: present findings compactly; on confirmation (or when running autonomously, for mechanical fixes only) update files via `docket task move`/`docket task log`, regenerate the index, and add a `**YYYY-MM-DD**` line to affected `# Log` sections explaining status changes.\n4. Commit as `chore(docket): groom backlog` (no task trailer — `docket task stop` first).\n\nNever change priorities or close tasks without saying so; grooming narrates every mutation.",
+      "docket-close": "Conclude the given task (default: the ID in `.docket/active-task`). A terminal move is the moment the wiki gets paid — don't skip steps.\n\nStored status changes go through the engine's canonical transition table; invalid transitions are rejected, `done` and `closed` are terminal, and moving to `closed` requires a disposition note. Only `done` satisfies dependencies or counts as completion.\n\nThe engine owns the state-machine-checked terminal move and dated Log mutation; the close workflow owns the choice between completion (`done`) and non-completion (`closed`), Outcome or Disposition judgment, documentation review, and derived index/log reconciliation.\n\n1. **Choose the terminal meaning explicitly**. Completion is the backward-compatible default: every acceptance criterion is checked (or explicitly waived in the Outcome with a reason), and the target state is `done`. Use non-completion only when the user explicitly intends to abandon, decline, supersede, or otherwise discontinue the work; leave unmet criteria unchecked, target `closed`, and require a concrete disposition reason. If neither meaning is supported, say so and stop.\n2. **Write the terminal narrative**. For completion, write `# Outcome`: what actually shipped, citing commit hashes found via `git log --grep \"Task: <ID>\" --oneline` plus the task file's history, with anything descoped or discovered. For non-completion, write `# Disposition`: why the work ended, what remains unmet, and any replacement task or decision links; do not claim that work shipped.\n3. **Reconcile the docs** (the LLM-first step): from the task diff and terminal narrative, identify wiki concepts (`specs/`, `reference/`, `decisions/`, plan documents) the conclusion invalidates or extends. Update them now. If a choice foreclosed alternatives, record it as a `type: Decision` concept and link it from the Outcome or Disposition.\n4. **Update state**: for completion, run `docket task close <ID> --note \"…\"`; for non-completion, run `docket task close <ID> --without-completion --note \"<disposition>\"`. Then run `docket index`, add a `log.md` entry that says completed or closed, and check dependency and epic effects. Only `done` unblocks dependents or counts toward epic completion; a terminal epic may be `closed` without all children being done.\n5. **Commit everything together** — task file + reconciled docs + index/log — with the `Task: <ID>` trailer (keep the task active so the hook injects it, or add it manually), then `docket task stop` to clear the active task.\n\nThe commit that concludes a task must contain the doc reconciliation — that's the product's core promise.",
+      "docket-standup": "Report project status from files + git. **Mutate nothing.** Pull state from the engine (`docket task list --json`, `docket ready --json`); use git for the activity window.\n\n1. **Window**: since the last standup or the range given (default: 7 days).\n2. **Done**: tasks whose status flipped to `done` in the window — from `git log -p --since=<window> -- <bundle>/work/tasks/` (status line changes) — one line each: ID, title, outcome gist.\n3. **Closed without completion**: tasks whose status flipped to `closed` in the window — one line each: ID, title, and disposition; keep them separate from shipped work.\n4. **In flight**: `in-progress` tasks with their latest Log entry and commit count from `git log --grep \"Task: <ID>\" --since=<window>`. Call out any with zero commits and no Log movement.\n5. **Ready next**: derived ready list (`docket ready`), top 5. Ready is derived, never written: a task is ready only when its stored status is `todo` and every dependency resolves to `done`; an unknown dependency blocks it. The ready queue puts ranked tasks first by ascending `rank`; rank ties and the unranked tail use priority (`p0` through `p3`), then ascending task ID as the stable fallback.\n6. **Blocked**: `blocked` tasks with the blocking reason from their Log.\n7. **Epic pulse**: one line per active epic — fraction of its tasks done, with closed children called out separately (derive by grep, don't trust hand-maintained lists).\n\nOutput: compact markdown suitable for pasting into a chat. Flag (don't fix) any inconsistencies noticed along the way — fixing belongs to [docket-groom](/workflows/docket-groom.md).",
+      "docket-state-of-play": "Refresh the optional bundle-root `overview.md` re-entry note. The engine parses, ages, and renders this authored summary but never writes it; live task status, readiness, progress, and activity stay in the derived overview.\n\n1. **Read the evidence**: run `docket overview --json`; read the product spec, current epics and tasks, recent Outcomes, explicit Decision concepts, `log.md`, recent task-linked commits, and the existing `overview.md` when present. Treat the derived overview as execution truth and the product spec/decisions as direction truth.\n2. **Write only the re-entry through-line**: summarize a few recent outcomes rather than commits, then name the one or few current/next epics or frontiers—including work already underway—with enough context to understand the move. Put the canonical resume target first when one exists; multiple real frontiers remain multiple authored links rather than an engine-selected winner. Add Worth knowing only for a decision, constraint, discovery, risk, parked thread, or useful wiki destination that materially helps re-entry. Use concrete nouns and consequences, link claims to bundle evidence, and omit empty material instead of writing filler. The preserved project preamble owns the recognizable full name, concise purpose, and other durable product introduction; do not repeat it here, and do not infer missing identity. Repeat a derived fact only when it explains why something matters, never to copy an inventory.\n3. **Write the linked note**: use the full output of `git rev-parse HEAD` as `as_of` and the current UTC ISO-8601 time as `reviewed_at`. What we've done recently and What's up next are required and non-empty. Worth knowing is optional; omit the heading when it would be empty.\n\n   ```markdown\n   ---\n   format: re-entry/v2\n   as_of: <full commit sha>\n   reviewed_at: <timestamp>\n   ---\n\n   # Project re-entry\n\n   ## What we've done recently\n\n   - <outcome and consequence with a link to evidence>\n\n   ## What's up next\n\n   - <current or next frontier and why it matters, linked to its epic or task>\n\n   ## Worth knowing\n\n   - <optional decision, constraint, discovery, risk, or parked thread with a useful link>\n   ```\n\n4. **Apply freshness honestly**: five task-linked commits after `as_of` or fourteen days after `reviewed_at` makes the note need review. Renderers keep the visibly dated last-known context readable rather than hiding it or presenting it as fresh. Refresh when the re-entry through-line materially changes, not merely to reset a clock. After a task close that changes the note, stamp the close commit in a separate tracker-only refresh so it starts at zero task-linked commits behind.\n5. **Verify and commit**: run `docket overview` and `docket lint`; confirm the linked sections and freshness are accurate. Commit as `chore(docket): refresh product context` with no Task trailer (`docket task stop` first).\n\nA missing `overview.md` is valid and renders no placeholder. Earlier formats remain readable and unchanged, but renderers label legacy prose and `re-entry/v1` as needing review. Never migrate them automatically; the next meaningful refresh replaces the file with the linked form above.",
+      "docket-freshness": "Close-time reconciliation is prospective — it fires only when a task closes, and only for that task's diff. This workflow is the retrospective complement: periodically re-ask \"what does this invalidate?\" across everything that happened since the last sweep.\n\n1. **Find the anchor**: the most recent `**Freshness**` entry in `log.md` holds the watermark sha. If none exists (first run), sweep the full history.\n2. **Collect the range**: `git log <sha>..HEAD --name-only` (keep trailers). Partition the commits:\n   - **Trailerless** — the high-risk bucket: nobody ever asked the reconciliation question. Give each the full treatment: from its changed paths, which concepts (`specs/`, `reference/`, `decisions/`, plan documents) does it invalidate or extend?\n   - **Trailered** (`Task: KEY-n`) — reconciliation should have happened at close. Spot-check: did closes that plausibly invalidated docs actually touch them?\n3. **Rotate a deep read**: pick the 1–2 concepts in `specs/` and `reference/` with the oldest last-modified commit and verify their content against current reality (code, plan). This catches drift that has no local commit at all — don't skip it just because the commit range is clean.\n4. **Propose, then apply**: present findings compactly (per doc: what's stale, which commit made it so). On confirmation — or autonomously for unambiguous factual fixes only — update the docs.\n5. **Stamp the watermark**: append to today's section of `log.md`:\n\n   ```\n   - **Freshness** — reviewed through `<short-sha of HEAD>` (<n> commits, <k> trailerless): <one-line findings summary, or \"no drift found\">.\n   ```\n\n   A \"no drift found\" stamp is a real result — record it; the recorded null finding is what makes the next sweep cheap.\n6. Commit doc fixes and the watermark together as `chore(docket): freshness review` (`docket task stop` first — no task trailer).\n\nNever end a sweep without stamping the watermark, even when nothing changed."
+    }
+  },
   {
     "version": "0.1.0",
     "bodies": {

package/src/version.ts

@@ -3,4 +3,4 @@
 // lines, workflow `origin:` frontmatter, and the CLI's --version all read it
 // from here.
 
-export const DOCKET_VERSION = "0.1.0";
+export const DOCKET_VERSION = "0.1.1";