trekoon 0.2.5 → 0.2.7

package/docs/quickstart.md

@@ -0,0 +1,134 @@
+# Quickstart
+
+Use this guide for the shortest path from an empty repo to an active Trekoon
+workflow.
+
+## Understand the storage model first
+
+Trekoon is local-first, but inside git repos and worktrees it is **repo-shared**.
+Every worktree for the same repository resolves to one shared `.trekoon`
+directory and one shared `.trekoon/trekoon.db` database.
+
+- `worktreeRoot` identifies the current checkout.
+- `sharedStorageRoot` identifies the repository root that owns `.trekoon`.
+- `databaseFile` points at the shared SQLite database.
+- `.trekoon` stays gitignored because the DB is operational state, not source
+  code.
+
+Outside git repos, Trekoon falls back to the current working directory.
+
+## Initialize
+
+```bash
+trekoon init
+trekoon --version
+```
+
+If an agent is driving the workflow, use the machine-readable form:
+
+```bash
+trekoon --toon init
+trekoon --toon sync status
+```
+
+Bootstrap rules:
+
+- Run `trekoon --toon init` once per repository to create or re-bootstrap the
+  shared storage root.
+- Run `trekoon --toon sync status` before agent work to inspect diagnostics.
+- If diagnostics report `recoveryRequired`, a tracked or ignored mismatch, or an
+  ambiguous recovery path, stop and repair setup before continuing.
+
+## Create an epic, task, and subtask
+
+```bash
+trekoon epic create --title "Agent backlog stabilization" --description "Track stabilization work" --status todo
+trekoon task create --title "Implement sync status" --description "Add status reporting" --epic <epic-id> --status todo
+trekoon subtask create --task <task-id> --title "Add cursor model" --status todo
+```
+
+Useful follow-up reads:
+
+```bash
+trekoon task list
+trekoon task list --status done
+trekoon task list --limit 25
+trekoon task list --all --view compact
+```
+
+## Prefer one-shot planning when the graph is already known
+
+If you already know the epic tree, create the epic, tasks, subtasks, and
+dependencies in one call:
+
+```bash
+trekoon epic create \
+  --title "Batch command rollout" \
+  --description "Ship one-shot planning workflows" \
+  --task "task-a|First task|First description|todo" \
+  --task "task-b|Second task|Second description|todo" \
+  --subtask "@task-a|sub-a|First subtask|Subtask description|todo" \
+  --dep "@task-b|@task-a" \
+  --dep "@sub-a|@task-a"
+```
+
+Use this when:
+
+- the epic does not exist yet
+- later records need to reference earlier records with `@temp-key`
+- you want one atomic create step and one machine response with mappings and
+  counts
+
+## Add dependencies
+
+```bash
+trekoon dep add <task-id> <depends-on-id>
+trekoon dep list <task-id>
+```
+
+## Use batch commands for larger updates
+
+When one call needs to create or link multiple records, prefer the transactional
+batch commands:
+
+| Need | Command |
+| --- | --- |
+| Create multiple tasks under one epic | `trekoon task create-many --epic <epic-id> --task ...` |
+| Create multiple subtasks under one task | `trekoon subtask create-many <task-id> --subtask ...` |
+| Add multiple dependency edges | `trekoon dep add-many --dep ...` |
+| Expand an existing epic with linked records | `trekoon epic expand <epic-id> ...` |
+
+These commands validate the whole batch before applying changes, so a bad input
+fails the whole operation instead of leaving partial state behind.
+
+## Close or reopen a whole tree in one update
+
+When you need to manually finish or reopen an entire epic or task tree, use the
+positional-ID cascade form of `update --all`:
+
+```bash
+trekoon epic update <epic-id> --all --status done
+trekoon epic update <epic-id> --all --status todo
+trekoon task update <task-id> --all --status done
+trekoon task update <task-id> --all --status todo
+trekoon subtask update <subtask-id> --all --status done
+```
+
+Rules:
+
+- `epic update <id> --all --status done|todo` updates the epic and all
+  descendants atomically
+- `task update <id> --all --status done|todo` updates the task and all
+  descendant subtasks atomically
+- `subtask update <id> --all --status done|todo` is accepted for consistency,
+  but it only updates that one subtask
+- Positional-ID cascade mode is status-only; do not combine it with `--append`,
+  `--description`, `--title`, or `--ids`
+- If any epic/task descendant is blocked by an unresolved external dependency,
+  the whole cascade fails with no partial writes
+
+## What to read next
+
+- [Command reference](commands.md)
+- [AI agents and the Trekoon skill](ai-agents.md)
+- [Machine contracts](machine-contracts.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "AI-first local issue tracker CLI.",
   "license": "MIT",
   "type": "module",
@@ -9,6 +9,7 @@
   },
   "files": [
     "bin",
+    "docs",
     "src",
     ".agents/skills/trekoon/SKILL.md",
     "README.md",

package/src/commands/epic.ts

@@ -30,6 +30,7 @@ import {
   type CompactTaskSpec,
   type EpicRecord,
   type SearchEntityMatch,
+  type StatusCascadePlan,
 } from "../domain/types";
 import { formatHumanTable } from "../io/human-table";
 import { failResult, okResult } from "../io/output";
@@ -45,9 +46,13 @@ const LIST_VIEW_MODES = ["table", "compact"] as const;
 const DEFAULT_LIST_LIMIT = 10;
 const DEFAULT_OPEN_STATUSES = ["in_progress", "in-progress", "todo"] as const;
 const CREATE_OPTIONS = ["title", "t", "description", "d", "status", "s", "task", "subtask", "dep"] as const;
+const LIST_OPTIONS = ["status", "s", "limit", "l", "cursor", "all", "view"] as const;
+const SHOW_OPTIONS = ["view", "all"] as const;
 const SEARCH_OPTIONS = ["fields", "preview"] as const;
 const REPLACE_OPTIONS = ["search", "replace", "fields", "preview", "apply"] as const;
 const EXPAND_OPTIONS = ["task", "subtask", "dep"] as const;
+const UPDATE_OPTIONS = ["all", "ids", "append", "description", "d", "status", "s", "title", "t"] as const;
+const STATUS_CASCADE_UPDATE_STATUSES = ["done", "todo"] as const;
 
 function parseStatusCsv(rawStatuses: string | undefined): string[] | undefined {
   if (rawStatuses === undefined) {
@@ -218,6 +223,44 @@ function appendLine(existing: string, line: string): string {
   return existing.length > 0 ? `${existing}\n${line}` : line;
 }
 
+function isStatusCascadeUpdateStatus(status: string | undefined): status is (typeof STATUS_CASCADE_UPDATE_STATUSES)[number] {
+  return status === "done" || status === "todo";
+}
+
+function buildStatusCascadeData(plan: StatusCascadePlan): Record<string, unknown> {
+  return {
+    mode: "descendants",
+    root: {
+      kind: plan.rootKind,
+      id: plan.rootId,
+    },
+    targetStatus: plan.targetStatus,
+    atomic: plan.atomic,
+    changedIds: plan.changedIds,
+    unchangedIds: plan.unchangedIds,
+    counts: plan.counts,
+  };
+}
+
+function formatStatusCascadeHuman(entityLabel: string, plan: StatusCascadePlan): string {
+  return `Cascade updated ${entityLabel} ${plan.rootId} to ${plan.targetStatus} (${plan.counts.changed} changed, ${plan.counts.unchanged} unchanged; epics=${plan.counts.changedEpics}, tasks=${plan.counts.changedTasks}, subtasks=${plan.counts.changedSubtasks})`;
+}
+
+function failCascadeStatusUpdate(command: string, entityLabel: string, data: Record<string, unknown>): CliResult {
+  return failResult({
+    command,
+    human: `${entityLabel} descendant cascade requires --status done or --status todo and does not support --append, --description, or --title.`,
+    data: {
+      code: "invalid_input",
+      ...data,
+    },
+    error: {
+      code: "invalid_input",
+      message: `${entityLabel} descendant cascade requires status-only done/todo mode`,
+    },
+  });
+}
+
 function formatEpicListTable(epics: readonly EpicRecord[]): string {
   const rows = epics.map((epic) => [epic.id, epic.title, epic.status]);
   return formatHumanTable(["ID", "TITLE", "STATUS"], rows, { wrapColumns: [1] });
@@ -826,6 +869,16 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
         });
       }
       case "list": {
+        const listUnknownOption = findUnknownOption(parsed, LIST_OPTIONS);
+        if (listUnknownOption !== undefined) {
+          return unknownOption("epic.list", listUnknownOption, LIST_OPTIONS);
+        }
+
+        const unexpectedListPositionals = readUnexpectedPositionals(parsed, 1);
+        if (unexpectedListPositionals.length > 0) {
+          return failUnexpectedPositionals("epic.list", unexpectedListPositionals);
+        }
+
         const missingListOption =
           readMissingOptionValue(parsed.missingOptionValues, "status", "s") ??
           readMissingOptionValue(parsed.missingOptionValues, "limit", "l") ??
@@ -836,8 +889,8 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
         }
 
         const includeAll: boolean = hasFlag(parsed.flags, "all");
-        const rawStatuses: string | undefined = readOption(parsed.options, "status");
-        const rawLimit: string | undefined = readOption(parsed.options, "limit");
+        const rawStatuses: string | undefined = readOption(parsed.options, "status", "s");
+        const rawLimit: string | undefined = readOption(parsed.options, "limit", "l");
         const rawCursor: string | undefined = readOption(parsed.options, "cursor");
         const rawView: string | undefined = readOption(parsed.options, "view");
         const view = readEnumOption(parsed.options, VIEW_MODES, "view");
@@ -939,6 +992,16 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
         });
       }
       case "show": {
+        const showUnknownOption = findUnknownOption(parsed, SHOW_OPTIONS);
+        if (showUnknownOption !== undefined) {
+          return unknownOption("epic.show", showUnknownOption, SHOW_OPTIONS);
+        }
+
+        const unexpectedShowPositionals = readUnexpectedPositionals(parsed, 2);
+        if (unexpectedShowPositionals.length > 0) {
+          return failUnexpectedPositionals("epic.show", unexpectedShowPositionals);
+        }
+
         const missingShowOption = readMissingOptionValue(parsed.missingOptionValues, "view");
         if (missingShowOption !== undefined) {
           return failMissingOptionValue("epic.show", missingShowOption);
@@ -1167,6 +1230,16 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
         });
       }
       case "update": {
+        const updateUnknownOption = findUnknownOption(parsed, UPDATE_OPTIONS);
+        if (updateUnknownOption !== undefined) {
+          return unknownOption("epic.update", updateUnknownOption, UPDATE_OPTIONS);
+        }
+
+        const unexpectedUpdatePositionals = readUnexpectedPositionals(parsed, 2);
+        if (unexpectedUpdatePositionals.length > 0) {
+          return failUnexpectedPositionals("epic.update", unexpectedUpdatePositionals);
+        }
+
         const missingUpdateOption =
           readMissingOptionValue(parsed.missingOptionValues, "ids") ??
           readMissingOptionValue(parsed.missingOptionValues, "append") ??
@@ -1209,7 +1282,35 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           });
         }
 
-        const hasBulkTarget = updateAll || ids.length > 0;
+        const cascadeMode = updateAll && epicId.length > 0;
+        if (cascadeMode) {
+          if (title !== undefined || description !== undefined || append !== undefined || !isStatusCascadeUpdateStatus(status)) {
+            return failCascadeStatusUpdate("epic.update", "Epic", {
+              id: epicId,
+              status,
+              allowedStatuses: [...STATUS_CASCADE_UPDATE_STATUSES],
+              fields: {
+                title: title !== undefined,
+                description: description !== undefined,
+                append: append !== undefined,
+              },
+            });
+          }
+
+          const cascade = mutations.updateEpicStatusCascade(epicId, status);
+          const epic = domain.getEpicOrThrow(epicId);
+
+          return okResult({
+            command: "epic.update",
+            human: formatStatusCascadeHuman("epic", cascade),
+            data: {
+              epic,
+              cascade: buildStatusCascadeData(cascade),
+            },
+          });
+        }
+
+        const hasBulkTarget = (updateAll && epicId.length === 0) || ids.length > 0;
         if (hasBulkTarget) {
           if (epicId.length > 0) {
             return failResult({

package/src/commands/help.ts

@@ -131,14 +131,20 @@ const EPIC_HELP = [
   "    - --preview and --apply are mutually exclusive",
   "",
   "Update behavior:",
-  "  Bulk target flags:",
-  "    --all | --ids <csv>",
-  "  Bulk fields:",
-  "    --append <text> and/or --status <status>",
+  "  Repo-wide bulk mode:",
+  "    trekoon epic update --all --append <text> [--status <status>]",
+  "    trekoon epic update --ids <csv> --append <text> [--status <status>]",
+  "    - preserves existing per-row bulk behavior; not one atomic multi-row update",
+  "  Descendant cascade mode:",
+  "    trekoon epic update <epic-id> --all --status done|todo",
+  "    - cascades atomically through descendant tasks and subtasks",
+  "    - blocked descendants abort the whole update",
+  "    - cascade mode supports only --status done|todo",
+  "    - do not combine positional id + --all with --ids, --append, --description, or --title",
 ].join("\n");
 
 const TASK_HELP = [
-  "Usage: trekoon task <create|create-many|list|show|ready|next|search|replace|update|delete> [options]",
+  "Usage: trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete> [options]",
   "",
   "Create-many behavior:",
   "  trekoon task create-many --epic <epic-id> --task <spec> [--task <spec> ...]",
@@ -188,10 +194,16 @@ const TASK_HELP = [
   "    - --preview and --apply are mutually exclusive",
   "",
   "Update behavior:",
-  "  Bulk target flags:",
-  "    --all | --ids <csv>",
-  "  Bulk fields:",
-  "    --append <text> and/or --status <status>",
+  "  Repo-wide bulk mode:",
+  "    trekoon task update --all --append <text> [--status <status>]",
+  "    trekoon task update --ids <csv> --append <text> [--status <status>]",
+  "    - preserves existing per-row bulk behavior; not one atomic multi-row update",
+  "  Descendant cascade mode:",
+  "    trekoon task update <task-id> --all --status done|todo",
+  "    - cascades atomically through descendant subtasks",
+  "    - blocked descendants abort the whole update",
+  "    - cascade mode supports only --status done|todo",
+  "    - do not combine positional id + --all with --ids, --append, --description, or --title",
 ].join("\n");
 
 const SUBTASK_HELP = [
@@ -228,10 +240,16 @@ const SUBTASK_HELP = [
   "    - --preview and --apply are mutually exclusive",
   "",
   "Update behavior:",
-  "  Bulk target flags:",
-  "    --all | --ids <csv>",
-  "  Bulk fields:",
-  "    --append <text> and/or --status <status>",
+  "  Repo-wide bulk mode:",
+  "    trekoon subtask update --all --append <text> [--status <status>]",
+  "    trekoon subtask update --ids <csv> --append <text> [--status <status>]",
+  "    - preserves existing per-row bulk behavior; not one atomic multi-row update",
+  "  Positional-id cascade syntax:",
+  "    trekoon subtask update <subtask-id> --all --status done|todo",
+  "    - accepted for contract consistency",
+  "    - behaves like a normal single-subtask status update",
+  "    - positional id + --all supports only --status done|todo",
+  "    - do not combine positional id + --all with --ids, --append, --description, or --title",
 ].join("\n");
 
 const DEP_HELP = [

package/src/commands/skills.ts

@@ -215,6 +215,11 @@ function resolveDefaultLinkPath(cwd: string, editor: EditorName): string {
   return join(resolveLinkRoot(cwd, editor, undefined), "trekoon");
 }
 
+function toRelativeSymlinkTarget(linkPath: string, targetPath: string): string {
+  const relativeTarget: string = relative(dirname(linkPath), resolve(targetPath));
+  return relativeTarget === "" ? "." : relativeTarget;
+}
+
 function resolveEditorConfigDir(cwd: string, editor: EditorName): string {
   if (editor === "opencode") {
     return join(cwd, ".opencode");
@@ -279,13 +284,15 @@ function replaceOrCreateSymlink(
   repoRoot: string,
   allowOutsideRepo: boolean,
 ): CliResult | null {
+  const symlinkTarget: string = toRelativeSymlinkTarget(linkPath, targetPath);
+
   if (!existsSync(linkPath)) {
     mkdirSync(dirname(linkPath), { recursive: true });
     const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
     if (boundaryFailure) {
       return boundaryFailure;
     }
-    symlinkSync(targetPath, linkPath, "dir");
+    symlinkSync(symlinkTarget, linkPath, "dir");
     return null;
   }
 
@@ -331,7 +338,7 @@ function replaceOrCreateSymlink(
   if (boundaryFailure) {
     return boundaryFailure;
   }
-  symlinkSync(targetPath, linkPath, "dir");
+  symlinkSync(symlinkTarget, linkPath, "dir");
   return null;
 }
 
@@ -489,6 +496,7 @@ function updateEditorLink(
 ): UpdateLinkEntry {
   const linkPath: string = resolveDefaultLinkPath(cwd, editor);
   const expectedTarget: string = resolve(installedDir);
+  const symlinkTarget: string = toRelativeSymlinkTarget(linkPath, expectedTarget);
   const editorConfigDir: string = resolveEditorConfigDir(cwd, editor);
 
   if (!existsSync(editorConfigDir)) {
@@ -504,7 +512,7 @@ function updateEditorLink(
 
   if (!existsSync(linkPath)) {
     mkdirSync(dirname(linkPath), { recursive: true });
-    symlinkSync(expectedTarget, linkPath, "dir");
+    symlinkSync(symlinkTarget, linkPath, "dir");
     return {
       editor,
       linkPath,
@@ -542,7 +550,7 @@ function updateEditorLink(
   }
 
   rmSync(linkPath, { force: true });
-  symlinkSync(expectedTarget, linkPath, "dir");
+  symlinkSync(symlinkTarget, linkPath, "dir");
   return {
     editor,
     linkPath,

package/src/commands/subtask.ts

@@ -33,9 +33,13 @@ function formatSubtask(subtask: SubtaskRecord): string {
 const VIEW_MODES = ["table", "compact"] as const;
 const DEFAULT_SUBTASK_LIST_LIMIT = 10;
 const DEFAULT_OPEN_SUBTASK_STATUSES = ["in_progress", "in-progress", "todo"] as const;
+const CREATE_OPTIONS = ["task", "t", "title", "description", "d", "status", "s"] as const;
+const LIST_OPTIONS = ["task", "t", "status", "s", "limit", "l", "cursor", "all", "view"] as const;
 const SEARCH_OPTIONS = ["fields", "preview"] as const;
 const REPLACE_OPTIONS = ["search", "replace", "fields", "preview", "apply"] as const;
 const CREATE_MANY_OPTIONS = ["task", "t", "subtask"] as const;
+const UPDATE_OPTIONS = ["all", "ids", "append", "description", "d", "status", "s", "title"] as const;
+const STATUS_CASCADE_UPDATE_STATUSES = ["done", "todo"] as const;
 
 function parseIdsOption(rawIds: string | undefined): string[] {
   if (rawIds === undefined) {
@@ -168,6 +172,25 @@ function appendLine(existing: string, line: string): string {
   return existing.length > 0 ? `${existing}\n${line}` : line;
 }
 
+function isStatusCascadeUpdateStatus(status: string | undefined): status is (typeof STATUS_CASCADE_UPDATE_STATUSES)[number] {
+  return status === "done" || status === "todo";
+}
+
+function failCascadeStatusUpdate(command: string, entityLabel: string, data: Record<string, unknown>): CliResult {
+  return failResult({
+    command,
+    human: `${entityLabel} cascade mode requires --status done or --status todo and does not support --append, --description, or --title.`,
+    data: {
+      code: "invalid_input",
+      ...data,
+    },
+    error: {
+      code: "invalid_input",
+      message: `${entityLabel} cascade mode requires status-only done/todo input`,
+    },
+  });
+}
+
 function formatSubtaskListTable(subtasks: readonly SubtaskRecord[]): string {
   return formatHumanTable(
     ["ID", "TASK", "TITLE", "STATUS"],
@@ -359,6 +382,16 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
 
     switch (subcommand) {
       case "create": {
+        const createUnknownOption = findUnknownOption(parsed, CREATE_OPTIONS);
+        if (createUnknownOption !== undefined) {
+          return unknownOption("subtask.create", createUnknownOption, CREATE_OPTIONS);
+        }
+
+        const unexpectedCreatePositionals = readUnexpectedPositionals(parsed, 3);
+        if (unexpectedCreatePositionals.length > 0) {
+          return failUnexpectedPositionals("subtask.create", unexpectedCreatePositionals);
+        }
+
         const missingCreateOption =
           readMissingOptionValue(parsed.missingOptionValues, "task", "t") ??
           readMissingOptionValue(parsed.missingOptionValues, "description", "d") ??
@@ -447,6 +480,16 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
         });
       }
       case "list": {
+        const listUnknownOption = findUnknownOption(parsed, LIST_OPTIONS);
+        if (listUnknownOption !== undefined) {
+          return unknownOption("subtask.list", listUnknownOption, LIST_OPTIONS);
+        }
+
+        const unexpectedListPositionals = readUnexpectedPositionals(parsed, 2);
+        if (unexpectedListPositionals.length > 0) {
+          return failUnexpectedPositionals("subtask.list", unexpectedListPositionals);
+        }
+
         const missingListOption =
           readMissingOptionValue(parsed.missingOptionValues, "view") ??
           readMissingOptionValue(parsed.missingOptionValues, "status", "s") ??
@@ -731,6 +774,16 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
         });
       }
       case "update": {
+        const updateUnknownOption = findUnknownOption(parsed, UPDATE_OPTIONS);
+        if (updateUnknownOption !== undefined) {
+          return unknownOption("subtask.update", updateUnknownOption, UPDATE_OPTIONS);
+        }
+
+        const unexpectedUpdatePositionals = readUnexpectedPositionals(parsed, 2);
+        if (unexpectedUpdatePositionals.length > 0) {
+          return failUnexpectedPositionals("subtask.update", unexpectedUpdatePositionals);
+        }
+
         const missingUpdateOption =
           readMissingOptionValue(parsed.missingOptionValues, "ids") ??
           readMissingOptionValue(parsed.missingOptionValues, "append") ??
@@ -773,7 +826,31 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           });
         }
 
-        const hasBulkTarget = updateAll || ids.length > 0;
+        const cascadeMode = updateAll && subtaskId.length > 0;
+        if (cascadeMode) {
+          if (title !== undefined || description !== undefined || append !== undefined || !isStatusCascadeUpdateStatus(status)) {
+            return failCascadeStatusUpdate("subtask.update", "Subtask", {
+              id: subtaskId,
+              status,
+              allowedStatuses: [...STATUS_CASCADE_UPDATE_STATUSES],
+              fields: {
+                title: title !== undefined,
+                description: description !== undefined,
+                append: append !== undefined,
+              },
+            });
+          }
+
+          const subtask = mutations.updateSubtask(subtaskId, { status });
+
+          return okResult({
+            command: "subtask.update",
+            human: `Updated subtask ${formatSubtask(subtask)}`,
+            data: { subtask },
+          });
+        }
+
+        const hasBulkTarget = (updateAll && subtaskId.length === 0) || ids.length > 0;
         if (hasBulkTarget) {
           if (subtaskId.length > 0) {
             return failResult({