trekoon 0.1.8 → 0.1.9

package/.agents/skills/trekoon/SKILL.md

@@ -35,6 +35,9 @@ data:
     status: in_progress
     createdAt: 1700000001000
     updatedAt: 1700000001000
+metadata:
+  contractVersion: 1.0.0
+  requestId: req-abc12345
 ```
 
 On error:
@@ -43,6 +46,9 @@ On error:
 ok: false
 command: task.show
 data: {}
+metadata:
+  contractVersion: 1.0.0
+  requestId: req-def67890
 error:
   code: not_found
   message: task not found: invalid-id
@@ -55,10 +61,34 @@ error:
 | `ok` | `true` if command succeeded, `false` on error |
 | `command` | The command that was executed (e.g., `task.list`, `epic.create`) |
 | `data` | The response payload (tasks, epics, dependencies, etc.) |
+| `metadata` | Contract metadata (`contractVersion`, `requestId`) |
+| `meta` | Optional command-specific metadata (pagination/defaults/filters/diagnostics) |
 | `error` | Present only on failure, contains `code` and `message` |
 
 Use long flags (`--status`, `--description`, etc.) and ALWAYS append `--toon` to every command.
 
+### Contract details to rely on
+
+- Machine responses include `metadata.contractVersion` and `metadata.requestId`.
+- Command IDs are stable and typically dot namespaced (`task.list`, `sync.status`).
+- Some root commands use single-token IDs (`help`, `init`, `quickstart`, `wipe`, `version`).
+- Unknown options fail fast with deterministic `unknown_option` errors and may include:
+  - `data.option`
+  - `data.allowedOptions`
+  - `data.suggestions`
+
+### Compatibility mode (legacy sync consumers)
+
+Default behavior is strict canonical IDs (for example `sync.status`).
+
+If a legacy consumer still expects underscore sync IDs, compatibility mode can be used:
+
+```bash
+trekoon --toon --compat legacy-sync-command-ids sync status
+```
+
+When enabled, output includes `metadata.compatibility` with migration/deprecation details.
+
 ## 1) Status Management
 
 ### Status values
@@ -205,9 +235,21 @@ trekoon task list --all --toon
 - `--all` cannot be combined with `--cursor`.
 - Machine pagination contract is in `meta.pagination.hasMore` and
   `meta.pagination.nextCursor`.
+- Machine list/show responses may also include:
+  - `meta.defaults`
+  - `meta.filters`
+  - `meta.truncation`
 - `epic show <id> --all --toon`: full epic tree (tasks + subtasks)
 - `task show <id> --all --toon`: task plus its subtasks
 
+### Canonical storage root behavior
+
+- In git repos/worktrees, Trekoon resolves storage from repository top-level so
+  nested cwd invocations use one canonical `.trekoon/trekoon.db`.
+- In non-git directories, Trekoon falls back to invocation cwd.
+- If invocation cwd differs from canonical root, machine output may include
+  `meta.storageRootDiagnostics`.
+
 ### View Options
 
 | Command | `--view` options |

package/README.md

@@ -46,12 +46,15 @@ npm i -g trekoon
 ## Command surface
 
 - `trekoon init`
+- `trekoon help [command]`
 - `trekoon quickstart`
 - `trekoon epic <create|list|show|update|delete>`
 - `trekoon task <create|list|show|ready|next|update|delete>`
 - `trekoon subtask <create|list|update|delete>`
 - `trekoon dep <add|remove|list|reverse>`
-- `trekoon sync <status|pull|resolve>`
+- `trekoon events prune [--dry-run] [--archive] [--retention-days <n>]`
+- `trekoon migrate <status|rollback> [--to-version <n>]`
+- `trekoon sync <status|pull|resolve|conflicts>`
 - `trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]`
 - `trekoon skills update`
 - `trekoon wipe --yes`
@@ -60,6 +63,7 @@ Global output modes:
 
 - `--json` for structured JSON output
 - `--toon` for true TOON-encoded output (not JSON text)
+- `--compat <mode>` for explicit machine compatibility behavior
 - `--help` for root and command help
 - `--version` for CLI version
 
@@ -72,7 +76,8 @@ trekoon --json quickstart
 trekoon quickstart --json
 ```
 
-Trekoon currently accepts long option form (`--option`).
+Trekoon options use long form (`--option`) for command/subcommand flags.
+Root help/version aliases `-h` and `-v` are also supported.
 
 Human view options:
 
@@ -112,8 +117,15 @@ trekoon epic update --ids <epic-1>,<epic-2> --status done
 
 ## Quickstart
 
-Trekoon is local-first: each worktree uses its own `.trekoon/trekoon.db`.
-Git does not merge this DB file; Trekoon sync commands merge tracker state.
+Trekoon is local-first: in git repos/worktrees, Trekoon resolves state to one
+canonical repository root (`git rev-parse --show-toplevel`) so nested
+invocations share the same `.trekoon/trekoon.db`.
+
+Outside git repos, Trekoon falls back to the invocation cwd.
+
+When machine output is enabled (`--json`/`--toon`) and a command resolves
+storage from a non-canonical cwd, Trekoon emits
+`meta.storageRootDiagnostics` to make the divergence explicit for automation.
 
 ### 1) Initialize
 
@@ -183,6 +195,8 @@ trekoon --json task show <task-id>
 ```bash
 trekoon sync status
 trekoon sync pull --from main
+trekoon sync conflicts list
+trekoon sync conflicts show <conflict-id>
 trekoon sync resolve <conflict-id> --use ours
 ```
 
@@ -195,10 +209,31 @@ react deterministically:
 - `diagnostics.conflictEvents`
 - `diagnostics.errorHints`
 
+Compatibility mode for legacy sync command IDs:
+
+```bash
+trekoon --json --compat legacy-sync-command-ids sync status
+trekoon --toon --compat legacy-sync-command-ids sync pull --from main
+```
+
+Behavior:
+
+- Default remains strict canonical IDs (`sync.status`, `sync.pull`, ...).
+- Compatibility mode rewrites sync command IDs to legacy forms
+  (`sync_status`, `sync_pull`, ...).
+- Compatibility mode is machine-only and valid only for `sync` commands.
+- Machine output includes `metadata.compatibility` with:
+  - deprecation warning code
+  - migration guidance
+  - canonical + compatibility command IDs
+  - removal window (`removalAfter: 2026-09-30`)
+- Migration path: remove `--compat legacy-sync-command-ids` and consume dotted
+  command IDs directly.
+
 ### 7) Install project-local Trekoon skill for agents
 
-`trekoon skills install` always writes the bundled skill file into the current
-repository at:
+`trekoon skills install` always writes the bundled skill file under the current
+working directory at:
 
 - `.agents/skills/trekoon/SKILL.md`
 
@@ -220,7 +255,7 @@ Path behavior:
 - Default pi link path: `.pi/skills/trekoon`
 - `--to <path>` overrides the editor root for link creation only.
 - `--to` does **not** move or copy `SKILL.md` to that path.
-- By default, link targets must resolve inside the repository root.
+- By default, link targets must resolve inside the current working directory root.
 - Use `--allow-outside-repo` only for intentional external links.
 - When override is used, install prints a warning and includes confirmation
   fields in machine output.
@@ -237,11 +272,11 @@ Path behavior:
 How `--to` works (step-by-step):
 
 1. Trekoon always installs/copies to:
-   - `<repo>/.agents/skills/trekoon/SKILL.md`
+   - `<cwd>/.agents/skills/trekoon/SKILL.md`
 2. If `--link` is present, Trekoon creates a `trekoon` symlink directory entry.
 3. `--to <path>` sets the symlink root directory.
 4. Final link path is:
-   - `<resolved-to-path>/trekoon -> <repo>/.agents/skills/trekoon`
+   - `<resolved-to-path>/trekoon -> <cwd>/.agents/skills/trekoon`
 
 Example:
 
@@ -251,9 +286,9 @@ trekoon skills install --link --editor opencode --to ./.custom-editor/skills
 
 This produces:
 
-- `<repo>/.agents/skills/trekoon/SKILL.md` (copied file)
-- `<repo>/.custom-editor/skills/trekoon` (symlink)
-- symlink target: `<repo>/.agents/skills/trekoon`
+- `<cwd>/.agents/skills/trekoon/SKILL.md` (copied file)
+- `<cwd>/.custom-editor/skills/trekoon` (symlink)
+- symlink target: `<cwd>/.agents/skills/trekoon`
 
 Trekoon does not mutate global editor config directories.
 
@@ -269,6 +304,27 @@ Trekoon does not mutate global editor config directories.
 Use `--toon` for production agent loops. The examples below show command +
 expected envelope fields.
 
+Base envelope fields (all machine responses):
+
+```text
+ok: true|false
+command: <stable command id>
+data: <payload>
+metadata:
+  contractVersion: "1.0.0"
+  requestId: req-<stable-id>
+```
+
+Most subcommand identifiers are dot-namespaced (`task.list`, `sync.pull`,
+`epic.show`). Root-level commands may use single-token IDs (`help`, `init`,
+`quickstart`, `wipe`, `version`).
+
+Additional metadata can appear when relevant:
+
+- `metadata.compatibility` when `--compat` mode is active
+- `meta.storageRootDiagnostics` when a machine-readable command resolves
+  storage from a non-canonical cwd
+
 ### Ready queue (deterministic candidates)
 
 ```bash
@@ -336,6 +392,9 @@ ok: true
 command: task.list
 data:
   tasks[]: ...
+metadata:
+  contractVersion: "1.0.0"
+  requestId: req-<stable-id>
 meta:
   pagination: { hasMore, nextCursor }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "AI-first local issue tracker CLI.",
   "license": "MIT",
   "type": "module",

package/src/commands/arg-parser.ts

@@ -3,6 +3,7 @@ export interface ParsedArgs {
   readonly options: ReadonlyMap<string, string>;
   readonly flags: ReadonlySet<string>;
   readonly missingOptionValues: ReadonlySet<string>;
+  readonly providedOptions: readonly string[];
 }
 
 const LONG_PREFIX = "--";
@@ -12,6 +13,7 @@ export function parseArgs(args: readonly string[]): ParsedArgs {
   const options = new Map<string, string>();
   const flags = new Set<string>();
   const missingOptionValues = new Set<string>();
+  const providedOptions: string[] = [];
 
   for (let index = 0; index < args.length; index += 1) {
     const token: string | undefined = args[index];
@@ -25,6 +27,7 @@ export function parseArgs(args: readonly string[]): ParsedArgs {
     }
 
     const key = token.slice(LONG_PREFIX.length);
+    providedOptions.push(key);
     const value = args[index + 1];
     if (!value || value.startsWith(LONG_PREFIX)) {
       flags.add(key);
@@ -41,6 +44,7 @@ export function parseArgs(args: readonly string[]): ParsedArgs {
     options,
     flags,
     missingOptionValues,
+    providedOptions,
   };
 }
 
@@ -92,6 +96,84 @@ export function parseStrictNonNegativeInt(rawValue: string | undefined): number
   return parsed;
 }
 
+function levenshteinDistance(source: string, target: string): number {
+  const sourceLength = source.length;
+  const targetLength = target.length;
+  if (sourceLength === 0) {
+    return targetLength;
+  }
+
+  if (targetLength === 0) {
+    return sourceLength;
+  }
+
+  const previous: number[] = Array.from({ length: targetLength + 1 }, (_, index) => index);
+  const current: number[] = new Array<number>(targetLength + 1).fill(0);
+
+  for (let sourceIndex = 1; sourceIndex <= sourceLength; sourceIndex += 1) {
+    current[0] = sourceIndex;
+    for (let targetIndex = 1; targetIndex <= targetLength; targetIndex += 1) {
+      const replacementCost = source[sourceIndex - 1] === target[targetIndex - 1] ? 0 : 1;
+      const insertCost = (current[targetIndex - 1] ?? 0) + 1;
+      const deleteCost = (previous[targetIndex] ?? 0) + 1;
+      const replaceCost = (previous[targetIndex - 1] ?? 0) + replacementCost;
+      current[targetIndex] = Math.min(
+        insertCost,
+        deleteCost,
+        replaceCost,
+      );
+    }
+
+    for (let targetIndex = 0; targetIndex <= targetLength; targetIndex += 1) {
+      previous[targetIndex] = current[targetIndex] ?? previous[targetIndex] ?? 0;
+    }
+  }
+
+  return previous[targetLength] ?? 0;
+}
+
+function normalizeOption(option: string): string {
+  return option.startsWith(LONG_PREFIX) ? option.slice(LONG_PREFIX.length) : option;
+}
+
+export function findUnknownOption(parsed: ParsedArgs, allowedOptions: readonly string[]): string | undefined {
+  const allowed = new Set<string>(allowedOptions.map(normalizeOption));
+  for (const option of parsed.providedOptions) {
+    if (!allowed.has(option)) {
+      return option;
+    }
+  }
+
+  return undefined;
+}
+
+export function suggestOptions(option: string, allowedOptions: readonly string[], limit = 3): string[] {
+  const normalizedOption = normalizeOption(option);
+  const normalizedAllowed = allowedOptions.map(normalizeOption);
+  return normalizedAllowed
+    .map((candidate) => {
+      const distance =
+        candidate.startsWith(normalizedOption) || normalizedOption.startsWith(candidate)
+          ? 0
+          : levenshteinDistance(normalizedOption, candidate);
+      return {
+        candidate,
+        distance,
+      };
+    })
+    .sort((left, right) => {
+      const byDistance = left.distance - right.distance;
+      if (byDistance !== 0) {
+        return byDistance;
+      }
+
+      return left.candidate.localeCompare(right.candidate);
+    })
+    .filter((item) => item.distance <= Math.max(2, Math.floor(normalizedOption.length / 2)))
+    .slice(0, limit)
+    .map((item) => item.candidate);
+}
+
 export function readEnumOption<const T extends readonly string[]>(
   options: ReadonlyMap<string, string>,
   allowed: T,

package/src/commands/epic.ts

@@ -396,7 +396,28 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           command: "epic.list",
           human,
           data: { epics },
-          ...(context.mode === "human" ? {} : { meta: { pagination: listed.pagination } }),
+          ...(context.mode === "human"
+            ? {}
+            : {
+                meta: {
+                  pagination: listed.pagination,
+                  defaults: {
+                    statuses: !includeAll && statuses === undefined ? [...DEFAULT_OPEN_STATUSES] : null,
+                    limit: !includeAll && limit === undefined ? DEFAULT_LIST_LIMIT : null,
+                    cursor: rawCursor === undefined ? 0 : null,
+                    view: view === undefined ? "table" : null,
+                  },
+                  filters: {
+                    statuses: includeAll ? null : (statuses ?? [...DEFAULT_OPEN_STATUSES]),
+                    includeAll,
+                  },
+                  truncation: {
+                    applied: listed.pagination.hasMore,
+                    returned: epics.length,
+                    limit: includeAll ? null : (limit ?? DEFAULT_LIST_LIMIT),
+                  },
+                },
+              }),
         });
       }
       case "show": {
@@ -430,6 +451,22 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
             command: "epic.show",
             human: formatEpic(epic),
             data: { epic, includeAll: false },
+            ...(context.mode === "human"
+              ? {}
+              : {
+                  meta: {
+                    defaults: {
+                      view: view === undefined ? effectiveView : null,
+                    },
+                    filters: {
+                      includeAll: false,
+                    },
+                    truncation: {
+                      applied: true,
+                      scope: "compact",
+                    },
+                  },
+                }),
           });
         }
 
@@ -440,6 +477,22 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
             command: "epic.show",
             human: formatEpicShowCompact(tree),
             data: { tree, includeAll: false },
+            ...(context.mode === "human"
+              ? {}
+              : {
+                  meta: {
+                    defaults: {
+                      view: view === undefined ? effectiveView : null,
+                    },
+                    filters: {
+                      includeAll: false,
+                    },
+                    truncation: {
+                      applied: true,
+                      scope: "tree",
+                    },
+                  },
+                }),
           });
         }
 
@@ -449,6 +502,22 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           command: "epic.show",
           human: effectiveView === "table" ? formatEpicShowTable(tree) : formatEpicShowDetailed(tree),
           data: { tree, includeAll: true },
+          ...(context.mode === "human"
+            ? {}
+            : {
+                meta: {
+                  defaults: {
+                    view: view === undefined ? effectiveView : null,
+                  },
+                  filters: {
+                    includeAll: true,
+                  },
+                  truncation: {
+                    applied: false,
+                    scope: "full",
+                  },
+                },
+              }),
         });
       }
       case "update": {

package/src/commands/help.ts

@@ -12,10 +12,12 @@ const ROOT_HELP = [
   "Global options:",
   "  --json       Emit stable JSON machine output",
   "  --toon       Emit true TOON-encoded output",
+  "  --compat <mode>  Enable explicit machine compatibility mode",
   "  --help       Show root or command help",
   "  --version    Print CLI version",
   "",
   "Commands:",
+  "  help         Show root or command help",
   "  init         Initialize .trekoon storage and local DB",
   "  quickstart   Show AI execution loop + task detail workflow",
   "  wipe         Remove local Trekoon state (requires --yes)",
@@ -88,6 +90,7 @@ const EPIC_HELP = [
   "",
   "Show behavior:",
   "  Views:",
+  "    - table: default view",
   "    - compact: epic summary",
   "    - tree: hierarchy",
   "    - detail: descriptions",
@@ -109,7 +112,7 @@ const TASK_HELP = [
   "    - Open statuses only: in_progress, in-progress, todo",
   "    - Limit: 10",
   "  Flags:",
-  "    --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
+  "    --epic <id> | --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
   "  Pagination:",
   "    - --cursor is offset-like",
   "    - Machine modes expose meta.pagination.hasMore / nextCursor",
@@ -118,6 +121,7 @@ const TASK_HELP = [
   "",
   "Show behavior:",
   "  Views:",
+  "    - table: default view",
   "    - compact: task summary",
   "    - tree: hierarchy",
   "    - detail: descriptions",
@@ -229,6 +233,13 @@ const SYNC_HELP = [
   "  resolve <conflict-id> --use ours|theirs",
   "      Resolve a pending conflict by selecting ours or theirs.",
   "",
+  "Compatibility mode:",
+  "  --compat legacy-sync-command-ids",
+  "      Emits legacy sync command IDs (sync_status, sync_pull, ...)",
+  "      in machine output only and includes deprecation metadata.",
+  "      Migration: remove --compat and consume dotted IDs (sync.status).",
+  "      Planned compatibility window closes after 2026-09-30.",
+  "",
   "Examples:",
   "  trekoon sync status",
   "  trekoon sync status --from main",

package/src/commands/subtask.ts

@@ -323,7 +323,29 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           command: "subtask.list",
           human,
           data: { subtasks },
-          ...(context.mode === "human" ? {} : { meta: { pagination: listed.pagination } }),
+          ...(context.mode === "human"
+            ? {}
+            : {
+                meta: {
+                  pagination: listed.pagination,
+                  defaults: {
+                    statuses: !includeAll && statuses === undefined ? [...DEFAULT_OPEN_SUBTASK_STATUSES] : null,
+                    limit: !includeAll && parsedLimit === undefined ? DEFAULT_SUBTASK_LIST_LIMIT : null,
+                    cursor: parsedCursor === undefined ? 0 : null,
+                    view: view === undefined ? "table" : null,
+                  },
+                  filters: {
+                    taskId: taskId ?? null,
+                    statuses: selectedStatuses ?? null,
+                    includeAll,
+                  },
+                  truncation: {
+                    applied: listed.pagination.hasMore,
+                    returned: subtasks.length,
+                    limit: selectedLimit ?? null,
+                  },
+                },
+              }),
         });
       }
       case "update": {