@gitdocket/core 0.0.0 → 0.1.0

package/src/index.ts

@@ -0,0 +1,194 @@
+// @gitdocket/core — the engine. Every surface (CLI, web, MCP, App) is a thin
+// client over this library; there is exactly one write path.
+
+export {
+  type Bundle,
+  findRepoRoot,
+  loadBundle,
+  loadRepo,
+  readyWorkItems,
+} from "./bundle";
+export {
+  CONFIG_FILENAME,
+  DEFAULT_BUNDLE,
+  type DocketConfig,
+  parseConfig,
+} from "./config";
+export {
+  ENGINE_SEMANTICS,
+  READY_QUEUE_DESCRIPTION,
+} from "./engine-semantics";
+export { type FileStore, InMemoryFileStore, LocalFileStore } from "./filestore";
+export { applyIndex, INDEX_MARKER, renderIndex } from "./indexmd";
+export {
+  ALLOW_RULES,
+  composeFreshnessBaseline,
+  composeHook,
+  defaultConfigYaml,
+  deriveProjectKey,
+  ensureGitignore,
+  type InitAction,
+  type InitResult,
+  mergeClaudeSettings,
+  mergeCodexConfig,
+  mergeMcpJson,
+  needsFrontmatter,
+  proposeType,
+  scaffoldFiles,
+  upgradeCodexConfig,
+  upgradeHookBlock,
+} from "./init";
+export {
+  AGENT_INTENT_DISAMBIGUATION,
+  AGENT_INTENT_IDS,
+  AGENT_INTENTS,
+  type AgentIntentContract,
+  type AgentIntentId,
+  agentIntent,
+  DIRECT_WORK_INTENT,
+  DIRECT_WORK_INTENT_ID,
+  DOCKET_INTENT_DISAMBIGUATION,
+  DOCKET_INTENT_IDS,
+  DOCKET_INTENTS,
+  type DocketIntentContract,
+  type DocketIntentId,
+  docketIntent,
+  type IntentEntrypoint,
+  type IntentMode,
+  PICKUP_AUTHORITY_EVIDENCE,
+} from "./intents";
+export {
+  type FreshnessWatermark,
+  findFreshnessWatermark,
+  type LintOptions,
+  lintBundle,
+  resolveLink,
+} from "./lint";
+export {
+  appendLog,
+  type CreateInput,
+  createWorkItem,
+  nextId,
+  setEpic,
+  setPriority,
+  setRank,
+  setStatus,
+  slugify,
+} from "./ops";
+export {
+  buildContextPacket,
+  type CommitRef,
+  type ContextPacket,
+  type PacketDep,
+  type PacketLink,
+} from "./packet";
+export {
+  type Concept,
+  type Decision,
+  type Diagnostic,
+  type GenericConcept,
+  isReserved,
+  type Link,
+  parseConcept,
+  type WorkItem,
+} from "./parse";
+export {
+  type IntentDiscoveryDiagnostic,
+  type IntentDiscoveryDiagnosticCode,
+  PROMPT_ROUTING_FIXTURES,
+  type PromptRoutingDiagnostic,
+  type PromptRoutingDiagnosticCode,
+  type PromptRoutingFixture,
+  type PromptRoutingTrait,
+  validateIntentDiscoveryDescriptions,
+  validatePromptRoutingFixtures,
+} from "./prompt-routing";
+export {
+  buildSchemas,
+  type DecisionFrontmatter,
+  type GenericFrontmatter,
+  type Schemas,
+  type WorkItemFrontmatter,
+} from "./schema";
+export { type SearchHit, searchBundle } from "./search";
+export {
+  formatOrigin,
+  type Origin,
+  parseOrigin,
+  recoverOrigin,
+  type ShippedHistory,
+  shippedHistory,
+  shippedWorkflow,
+} from "./shipped";
+export {
+  type LegacyStateOfPlayNote,
+  parseStateOfPlay,
+  presentStateOfPlay,
+  REENTRY_CONTEXT_FORMAT,
+  REENTRY_CONTEXT_V1_FORMAT,
+  type ReentryAssessment,
+  type ReentryContextNote,
+  type ReentryV1ContextNote,
+  STATE_OF_PLAY_PATH,
+  STATE_OF_PLAY_REVIEW_MAX_DAYS,
+  STATE_OF_PLAY_STALE_COMMITS,
+  type StateOfPlayNote,
+  type StateOfPlayParseResult,
+  type StateOfPlayPresentationOptions,
+  type StateOfPlayReview,
+  type StateOfPlayReviewReason,
+  type StateOfPlayView,
+} from "./state-of-play";
+export {
+  byManualOrder,
+  canTransition,
+  DECISION_STATES,
+  type DecisionStatus,
+  isPriority,
+  isReady,
+  isStatus,
+  isTerminalStatus,
+  PRIORITIES,
+  type Priority,
+  STATES,
+  type Status,
+  TERMINAL_STATES,
+  TRANSITIONS,
+  WORK_ITEM_TYPES,
+  type WorkItemType,
+} from "./states";
+export {
+  type Merge3,
+  markerVersion,
+  type UpgradeAction,
+  type UpgradeResult,
+  upgradeAdapter,
+  upgradeWorkflowFile,
+} from "./upgrade";
+export {
+  resolveVerifyMarkers,
+  scanVerifyMarkers,
+  VERIFY_TOKEN,
+  type VerifyMarker,
+  type VerifySource,
+  type VerifyStatusRow,
+  verifyStatus,
+} from "./verify";
+export { DOCKET_VERSION } from "./version";
+export {
+  ADAPTER_MARKER,
+  composeManagedSection,
+  DOCKET_WORKFLOWS,
+  hasAdapterMarker,
+  hasDocketSection,
+  renderAgentSkillStub,
+  renderClaudeSkillStub,
+  renderDocketSection,
+  renderWorkflow,
+  validateWorkflowSemantics,
+  WORKFLOWS_DIR,
+  type WorkflowDef,
+  type WorkflowSemantic,
+  type WorkflowSemanticDiagnostic,
+  workflowPath,
+} from "./workflows";

package/src/indexmd.ts

@@ -0,0 +1,146 @@
+// Generated index.md: derived content is never hand-maintained.
+// Everything above the marker is human preamble and survives regeneration;
+// everything below is machine-owned and rendered deterministically from the
+// bundle (lockfile pattern — committed, and CI fails on drift).
+
+import type { Bundle } from "./bundle";
+import type { GenericConcept, WorkItem } from "./parse";
+import { isTerminalStatus } from "./states";
+
+export const INDEX_MARKER = "<!-- docket:generated -->";
+
+const idNum = (id: string): number => Number(id.match(/(\d+)$/)?.[1] ?? 0);
+const byId = (a: { fm: { id: string } }, b: { fm: { id: string } }): number =>
+  idNum(a.fm.id) - idNum(b.fm.id);
+
+const link = (text: string, path: string): string => `[${text}](/${path})`;
+
+const taskLine = (t: WorkItem, ready: ReadonlySet<string>): string => {
+  const text = link(`${t.fm.id} — ${t.fm.title ?? t.fm.id}`, t.path);
+  if (t.fm.status === "done") return `- ✅ ${text}`;
+  if (t.fm.status === "closed") return `- ⏹️ ${text} *(closed)*`;
+  if (t.fm.status === "in-progress" || t.fm.status === "in-review")
+    return `- 🔄 ${text}`;
+  if (t.fm.status === "blocked") return `- 🚫 ${text}`;
+  return ready.has(t.fm.id) ? `- ${text} *(ready)*` : `- ${text}`;
+};
+
+const tsOf = (t: WorkItem): string =>
+  typeof t.fm.timestamp === "string" ? t.fm.timestamp : "";
+
+/**
+ * Liveness order: what's moving, then what could move, then the
+ * queue, then terminal history newest-first (timestamp is the transition time; ISO
+ * strings compare chronologically). File-derived and deterministic: no
+ * wall-clock input, so regeneration without a bundle change never diffs.
+ */
+export function byLiveness(
+  ready: ReadonlySet<string>,
+): (a: WorkItem, b: WorkItem) => number {
+  const rank = (t: WorkItem): number => {
+    if (t.fm.status === "in-progress" || t.fm.status === "in-review") return 0;
+    if (ready.has(t.fm.id)) return 1;
+    if (isTerminalStatus(t.fm.status)) return 3;
+    return 2; // todo (unready) + blocked
+  };
+  return (a, b) => {
+    const byRank = rank(a) - rank(b);
+    if (byRank !== 0) return byRank;
+    if (rank(a) === 3) {
+      const byClose = tsOf(b).localeCompare(tsOf(a));
+      if (byClose !== 0) return byClose;
+    }
+    return byId(a, b);
+  };
+}
+
+/** The machine-owned body: generic concepts by directory, decisions, work by epic. */
+export function renderIndex(bundle: Bundle): string {
+  const sections: string[] = [];
+
+  const groups = new Map<string, GenericConcept[]>();
+  for (const c of bundle.concepts) {
+    if (c.kind !== "generic") continue;
+    const dir = c.path.includes("/") ? (c.path.split("/")[0] ?? "") : "";
+    const group = groups.get(dir) ?? [];
+    group.push(c);
+    groups.set(dir, group);
+  }
+  for (const [dir, items] of [...groups.entries()].sort()) {
+    const name = dir ? dir[0]?.toUpperCase() + dir.slice(1) : "Concepts";
+    const lines = items
+      .sort((a, z) => a.path.localeCompare(z.path))
+      .map(
+        (c) =>
+          `- ${link(c.fm.title ?? c.path, c.path)}${c.fm.description ? ` — ${c.fm.description}` : ""}`,
+      );
+    sections.push(`## ${name}\n\n${lines.join("\n")}`);
+  }
+
+  if (bundle.decisions.length > 0) {
+    const lines = [...bundle.decisions].sort(byId).map((d) => {
+      const text = link(`${d.fm.id} — ${d.fm.title ?? d.fm.id}`, d.path);
+      return d.fm.status === "superseded"
+        ? `- ~~${text}~~ *(superseded)*`
+        : `- ${text}`;
+    });
+    sections.push(`## Decisions\n\n${lines.join("\n")}`);
+  }
+
+  const ready = new Set(bundle.readyIds());
+  const epics = bundle.workItems.filter((w) => w.fm.type === "Epic").sort(byId);
+  const tasks = bundle.workItems.filter((w) => w.fm.type === "Task").sort(byId);
+  if (epics.length > 0 || tasks.length > 0) {
+    const work: string[] = ["## Work"];
+    const claimed = new Set<string>();
+    const order = byLiveness(ready);
+    for (const epic of epics) {
+      const own = tasks.filter((t) => t.fm.epic?.includes(`/${epic.fm.id}-`));
+      for (const t of own) claimed.add(t.fm.id);
+      // Fully-done epics collapse to their rollup: the history lives
+      // in git and on the epic page; the index is orientation, not archive.
+      const finished =
+        epic.fm.status === "done" &&
+        own.length > 0 &&
+        own.every((t) => t.fm.status === "done");
+      const head = `### ${link(epic.fm.title ?? epic.fm.id, epic.path)} *(${epic.fm.status})*`;
+      if (finished) {
+        work.push(`${head}\n\n✅ all ${own.length} tasks done`);
+        continue;
+      }
+      work.push(head);
+      if (own.length > 0)
+        work.push(
+          own
+            .sort(order)
+            .map((t) => taskLine(t, ready))
+            .join("\n"),
+        );
+    }
+    const orphans = tasks.filter((t) => !claimed.has(t.fm.id));
+    if (orphans.length > 0) {
+      work.push("### No epic");
+      work.push(
+        orphans
+          .sort(order)
+          .map((t) => taskLine(t, ready))
+          .join("\n"),
+      );
+    }
+    sections.push(work.join("\n\n"));
+  }
+
+  return sections.join("\n\n");
+}
+
+/** Splice the generated body below the marker, preserving the human preamble above it. */
+export function applyIndex(current: string, body: string): string {
+  const at = current.indexOf(INDEX_MARKER);
+  const preamble =
+    at >= 0
+      ? current.slice(0, at)
+      : current.trim()
+        ? `${current.trimEnd()}\n\n`
+        : "# Index\n\n";
+  return `${preamble}${INDEX_MARKER}\n\n${body}\n`;
+}

package/src/init.ts

@@ -0,0 +1,338 @@
+// docket init — pure text transforms for adopt-in-place. Adoption is
+// additive, never a migration: every function here takes what already
+// exists and returns a composed result, so callers can guarantee "never
+// clobbers". Filesystem and git orchestration live in the CLI; this module
+// stays runtime-portable.
+
+import { INDEX_MARKER } from "./indexmd";
+import { findFreshnessWatermark } from "./lint";
+import { DOCKET_VERSION } from "./version";
+
+export type InitAction = "create" | "update" | "skip";
+
+export interface InitResult {
+  action: InitAction;
+  content: string;
+  /** Present when action is "skip" for a reason worth surfacing. */
+  reason?: string;
+}
+
+/** docket.yaml template — mirrors this repo's reference copy. */
+export function defaultConfigYaml(project: string, bundle: string): string {
+  return `# Docket configuration — consumed by the docket CLI and by agents.
+
+bundle: ${bundle}
+
+project: ${project}          # ID key for work items: ${project}-1, ${project}-2, … (epics + tasks share one sequence)
+
+ids:
+  scheme: sequential     # next = max existing + 1
+  decision_prefix: DEC   # decisions number independently: DEC-1, DEC-2, …
+
+workflow:
+  states: [todo, in-progress, blocked, in-review, done, closed]
+  # \`ready\` is never written to a file — it is derived:
+  # status == todo AND every task in depends_on has status == done.
+
+git:
+  trailer: "Task"        # commit trailer key linking commits to tasks
+  branch_prefix: "task/" # branch naming: task/${project}-12-short-slug
+`;
+}
+
+/** Project key from a directory name: letters/digits, uppercased, max 3. */
+export function deriveProjectKey(dirname: string): string {
+  const key = dirname
+    .replace(/[^a-zA-Z0-9]/g, "")
+    .toUpperCase()
+    .slice(0, 3);
+  return key || "DKT";
+}
+
+/** Bundle files scaffolded when missing. Paths are bundle-relative. */
+export function scaffoldFiles(
+  project: string,
+  today: string,
+): { path: string; content: string }[] {
+  return [
+    {
+      path: "index.md",
+      content: `# ${project} — docs & work\n\n<!-- Replace the heading above with the project's full name and add one concise sentence explaining its purpose. Docket preserves this preamble when regenerating the index. -->\n\n${INDEX_MARKER}\n`,
+    },
+    {
+      path: "log.md",
+      content: `# Log\n\n## ${today}\n\n- **Create** — Adopted Docket (\`docket init\`).\n`,
+    },
+  ];
+}
+
+/**
+ * Stamp the freshness baseline watermark into log.md. Adoption is
+ * the baseline: a fresh bundle has nothing to retrospect, so init seeds the
+ * watermark the docket-freshness workflow advances from — instead of lint
+ * nagging for a ritual with nothing to sweep. The entry lands under today's
+ * section (log.md is newest-first). "create" refers to the entry — the file
+ * itself always pre-exists (scaffolded or brownfield).
+ */
+export function composeFreshnessBaseline(
+  log: string,
+  sha: string | undefined,
+  today: string,
+): InitResult {
+  if (findFreshnessWatermark(log))
+    return { action: "skip", content: log, reason: "already stamped" };
+  if (!sha) return { action: "skip", content: log, reason: "no commits yet" };
+  const entry = `- **Freshness** — baseline at adoption; reviewed through \`${sha}\` (nothing to review before Docket).`;
+  const heading = `## ${today}`;
+  const lines = log.split("\n");
+  const at = lines.indexOf(heading);
+  if (at >= 0) {
+    lines.splice(at + 1, 0, "", entry);
+    return { action: "create", content: lines.join("\n") };
+  }
+  // No section for today — open one. The log is newest-first, so it goes
+  // right after the title (or at the very top of a title-less log).
+  const title = lines.findIndex((line) => line.startsWith("# "));
+  lines.splice(title + 1, 0, "", heading, "", entry);
+  return { action: "create", content: lines.join("\n") };
+}
+
+const HOOK_BEGIN = `# >>> docket prepare-commit-msg@${DOCKET_VERSION} >>>`;
+const HOOK_END = "# <<< docket prepare-commit-msg <<<";
+// Matches the begin marker at any version, and the legacy unversioned form.
+const HOOK_MARKER_PREFIX = "# >>> docket prepare-commit-msg";
+
+// Self-contained sh block; variable names are prefixed so appending into an
+// existing hook can't collide, and every failure path exits 0 so a broken
+// docket state never blocks a commit.
+const HOOK_BLOCK = `${HOOK_BEGIN}
+# Inject the active task's trailer into the commit message. Active task is
+# per-checkout state in .docket/active-task (untracked), so git worktrees
+# each carry their own active task.
+docket_msg_file="$1"
+docket_top="$(git rev-parse --show-toplevel 2>/dev/null)" || docket_top=""
+if [ -n "$docket_top" ] && [ -f "$docket_top/.docket/active-task" ]; then
+  docket_task_id="$(head -n1 "$docket_top/.docket/active-task" | tr -d '[:space:]')"
+  if [ -n "$docket_task_id" ] && ! grep -qi "^Task:" "$docket_msg_file"; then
+    git interpret-trailers --in-place --trailer "Task: $docket_task_id" "$docket_msg_file"
+  fi
+fi
+${HOOK_END}
+`;
+
+/**
+ * Compose the trailer-injecting block into a prepare-commit-msg hook.
+ * Missing hook → create; existing without our block → append; already
+ * installed → skip. Never rewrites what's there.
+ */
+export function composeHook(existing: string | undefined): InitResult {
+  if (existing === undefined) {
+    return { action: "create", content: `#!/bin/sh\n${HOOK_BLOCK}` };
+  }
+  // Our marker (any version), or any hand-rolled hook already reading the
+  // active-task file (this repo's Phase 0 hook predates the marker).
+  if (
+    existing.includes(HOOK_MARKER_PREFIX) ||
+    existing.includes(".docket/active-task")
+  ) {
+    return { action: "skip", content: existing, reason: "already installed" };
+  }
+  const base = existing.endsWith("\n") ? existing : `${existing}\n`;
+  return { action: "update", content: `${base}\n${HOOK_BLOCK}` };
+}
+
+// Full block span, any marker version — for upgrade's regenerate-in-place.
+const HOOK_BLOCK_RE =
+  /# >>> docket prepare-commit-msg(@\S+)? >>>[\s\S]*?# <<< docket prepare-commit-msg <<<\n?/;
+
+/**
+ * Upgrade the hook block in place: the marked span (any version) is replaced
+ * with the current block. Hand-rolled hooks — active-task readers without our
+ * marker — are never touched (same rule as composeHook, inverted: compose
+ * skips what upgrade regenerates).
+ */
+export function upgradeHookBlock(existing: string): InitResult {
+  if (!HOOK_BLOCK_RE.test(existing)) {
+    return {
+      action: "skip",
+      content: existing,
+      reason: existing.includes(".docket/active-task")
+        ? "hand-rolled hook — never touched"
+        : "no docket block",
+    };
+  }
+  // Replacer fn: the block contains a literal `$1`, which a string
+  // replacement would eat as a capture-group reference.
+  const content = existing.replace(HOOK_BLOCK_RE, () => HOOK_BLOCK);
+  return content === existing
+    ? { action: "skip", content: existing, reason: "up to date" }
+    : { action: "update", content };
+}
+
+const MCP_SERVER = { command: "docket-mcp" };
+
+const CODEX_MCP_BEGIN = `# >>> docket mcp@${DOCKET_VERSION} >>>`;
+const CODEX_MCP_END = "# <<< docket mcp <<<";
+const CODEX_MCP_BEGIN_RE = /# >>> docket mcp(@\S+)? >>>/;
+const CODEX_MCP_BLOCK = `${CODEX_MCP_BEGIN}
+[mcp_servers.docket]
+command = "docket-mcp"
+${CODEX_MCP_END}
+`;
+const CODEX_MCP_BLOCK_RE =
+  /# >>> docket mcp(@\S+)? >>>[\s\S]*?# <<< docket mcp <<<\n?/;
+
+/** Register the docket MCP server in .mcp.json without touching other entries. */
+export function mergeMcpJson(existing: string | undefined): InitResult {
+  if (existing === undefined) {
+    return {
+      action: "create",
+      content: `${JSON.stringify({ mcpServers: { docket: MCP_SERVER } }, null, 2)}\n`,
+    };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(existing);
+  } catch {
+    return { action: "skip", content: existing, reason: "not valid JSON" };
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return { action: "skip", content: existing, reason: "not a JSON object" };
+  }
+  const root = parsed as Record<string, unknown>;
+  const servers =
+    typeof root.mcpServers === "object" && root.mcpServers !== null
+      ? (root.mcpServers as Record<string, unknown>)
+      : {};
+  if (servers.docket) {
+    return { action: "skip", content: existing, reason: "already registered" };
+  }
+  root.mcpServers = { ...servers, docket: MCP_SERVER };
+  return { action: "update", content: `${JSON.stringify(root, null, 2)}\n` };
+}
+
+/**
+ * Add Docket's marker-managed MCP table to a valid Codex project config.
+ * TOML validation belongs to the runtime caller; this pure transform only
+ * composes text and refuses to replace an existing docket registration.
+ */
+export function mergeCodexConfig(existing: string | undefined): InitResult {
+  if (existing === undefined)
+    return { action: "create", content: CODEX_MCP_BLOCK };
+  if (
+    CODEX_MCP_BEGIN_RE.test(existing) ||
+    /^\s*\[\s*mcp_servers(?:\.|\s*\.\s*)["']?docket["']?\s*\]\s*$/m.test(
+      existing,
+    )
+  ) {
+    return { action: "skip", content: existing, reason: "already registered" };
+  }
+  const base = existing.endsWith("\n") ? existing : `${existing}\n`;
+  return { action: "update", content: `${base}\n${CODEX_MCP_BLOCK}` };
+}
+
+/** Regenerate only Docket's marked Codex MCP block; never add one. */
+export function upgradeCodexConfig(existing: string): InitResult {
+  if (!CODEX_MCP_BLOCK_RE.test(existing)) {
+    return {
+      action: "skip",
+      content: existing,
+      reason: "no docket block",
+    };
+  }
+  const content = existing.replace(CODEX_MCP_BLOCK_RE, () => CODEX_MCP_BLOCK);
+  return content === existing
+    ? { action: "skip", content: existing, reason: "up to date" }
+    : { action: "update", content };
+}
+
+export const ALLOW_RULES = ["mcp__docket", "Bash(docket:*)"] as const;
+
+/**
+ * Ensure .claude/settings.json pre-approves the docket surface:
+ * enableAllProjectMcpServers plus the allow rules. Preserves everything else.
+ */
+export function mergeClaudeSettings(existing: string | undefined): InitResult {
+  let root: Record<string, unknown> = {};
+  if (existing !== undefined) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(existing);
+    } catch {
+      return { action: "skip", content: existing, reason: "not valid JSON" };
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+      return { action: "skip", content: existing, reason: "not a JSON object" };
+    }
+    root = parsed as Record<string, unknown>;
+  }
+
+  const permissions =
+    typeof root.permissions === "object" && root.permissions !== null
+      ? (root.permissions as Record<string, unknown>)
+      : {};
+  const allow = Array.isArray(permissions.allow)
+    ? permissions.allow.filter((r): r is string => typeof r === "string")
+    : [];
+  const missing = ALLOW_RULES.filter((rule) => !allow.includes(rule));
+
+  if (
+    existing !== undefined &&
+    missing.length === 0 &&
+    root.enableAllProjectMcpServers === true
+  ) {
+    return { action: "skip", content: existing, reason: "already configured" };
+  }
+
+  root.enableAllProjectMcpServers = true;
+  root.permissions = { ...permissions, allow: [...allow, ...missing] };
+  return {
+    action: existing === undefined ? "create" : "update",
+    content: `${JSON.stringify(root, null, 2)}\n`,
+  };
+}
+
+const GITIGNORE_BLOCK = `# docket per-checkout state (active task, cache)
+.docket/
+`;
+
+/**
+ * Ensure `.docket/` is ignored. Additive: appends a commented rule unless some
+ * line already covers the directory; never reorders or rewrites existing rules.
+ */
+export function ensureGitignore(existing: string | undefined): InitResult {
+  if (existing === undefined)
+    return { action: "create", content: GITIGNORE_BLOCK };
+  const covered = existing
+    .split("\n")
+    .map((line) => line.trim())
+    .some(
+      (line) =>
+        line === ".docket" ||
+        line === ".docket/" ||
+        line === "/.docket" ||
+        line === "/.docket/",
+    );
+  if (covered)
+    return { action: "skip", content: existing, reason: "already ignored" };
+  const base = existing.endsWith("\n") ? existing : `${existing}\n`;
+  return { action: "update", content: `${base}\n${GITIGNORE_BLOCK}` };
+}
+
+/** True when a markdown source lacks a frontmatter block with a `type` key. */
+export function needsFrontmatter(source: string): boolean {
+  const match = source.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return true;
+  return !/^type:/m.test(match[1] ?? "");
+}
+
+/** Mechanical type proposal from a bundle-relative path — the agent refines it. */
+export function proposeType(path: string): string {
+  if (path.startsWith("work/epics/")) return "Epic";
+  if (path.startsWith("work/tasks/")) return "Task";
+  if (path.startsWith("decisions/")) return "Decision";
+  if (path.startsWith("specs/")) return "Spec";
+  if (path.startsWith("reference/")) return "Reference";
+  if (path.startsWith("workflows/")) return "Workflow";
+  return "Doc";
+}