trekoon 0.1.7 → 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
@@ -101,6 +131,7 @@ Dependencies define what must be completed before a task can start. A task/subta
 trekoon dep add <source-id> <depends-on-id> --toon
 trekoon dep list <source-id> --toon
 trekoon dep remove <source-id> <depends-on-id> --toon
+trekoon dep reverse <task-or-subtask-id> --toon
 ```
 
 - `<source-id>`: The task/subtask that has the dependency
@@ -127,16 +158,32 @@ The response `data.dependencies` array contains entries with:
 
 ## 3) Task Completion Flow
 
-### Before Starting a Task
+### Canonical dependency-aware execution loop
 
-1. Check if task has unmet dependencies:
+Run this sequence every session:
+
+1. Sync branch/worktree status:
    ```bash
-   trekoon dep list <task-id> --toon
+   trekoon sync status --toon
+   ```
+2. Pull deterministic ready candidates (or next candidate):
+   ```bash
+   trekoon task ready --limit 5 --toon
+   trekoon task next --toon
+   ```
+3. Inspect downstream impact before changes:
+   ```bash
+   trekoon dep reverse <task-or-subtask-id> --toon
+   ```
+4. Start work with explicit status updates:
+   ```bash
+   trekoon task update <task-id> --status in_progress --toon
+   ```
+5. Finish or block with appended context + final status:
+   ```bash
+   trekoon task update <task-id> --append "Completed implementation" --status done --toon
+   trekoon task update <task-id> --append "Blocked by <reason>" --status blocked --toon
    ```
-
-2. If dependencies exist and are not `done`, complete those first
-
-3. Only mark `in_progress` when all dependencies are `done`
 
 ### When Completing a Task
 
@@ -146,17 +193,19 @@ The response `data.dependencies` array contains entries with:
    ```
 
 2. To find the next task that was blocked by this one:
-   - List all tasks: `trekoon task list --all --toon`
-   - Check which tasks have dependencies on the completed task
-   - The task(s) with all dependencies now satisfied are ready to start
+   - Inspect downstream nodes: `trekoon dep reverse <task-id> --toon`
+   - Pull ready queue: `trekoon task ready --limit 5 --toon`
+   - Pick one deterministically: `trekoon task next --toon`
 
 ### Finding Next Work
 
 ```bash
-trekoon task list --status todo --limit 20 --toon
+trekoon task ready --limit 5 --toon
+trekoon task next --toon
+trekoon dep reverse <task-or-subtask-id> --toon
 ```
 
-Tasks are sorted with `in_progress` first, then `todo`. Look for tasks with no dependencies or all dependencies satisfied.
+Use `task ready` for ranked candidates and `task next` for the top deterministic pick.
 
 ## 4) Load existing work first
 
@@ -173,6 +222,7 @@ trekoon task show <id> --all --toon
   - open work only (`in_progress`, `in-progress`, `todo`)
   - prioritized as `in_progress`/`in-progress` first, then `todo`
   - default limit `10`
+  - `--cursor <n>` is offset-like pagination for list endpoints
 - Filter list explicitly when needed:
 
 ```bash
@@ -182,9 +232,24 @@ trekoon task list --all --toon
 ```
 
 - `--all` cannot be combined with `--status` or `--limit`.
+- `--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 |
@@ -236,14 +301,15 @@ Rules:
 2. In the target repository/worktree, initialize tracker state:
 
 ```bash
-trekoon init
+trekoon init --toon
 ```
 
-3. You can always run `trekoon quickstart` or `trekoon --help` to get more information.
+3. You can always run `trekoon quickstart --toon` or `trekoon --help --toon` to
+   get more information.
 
 If `.trekoon/trekoon.db` is missing, initialize before any create/update commands.
 
 ## 8) Safety
 
 - Never edit `.trekoon/trekoon.db` directly.
-- `trekoon wipe --yes` is prohibited unless the user explicitly confirms they want a destructive wipe.
+- `trekoon wipe --yes --toon` is prohibited unless the user explicitly confirms they want a destructive wipe.

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|update|delete>`
+- `trekoon task <create|list|show|ready|next|update|delete>`
 - `trekoon subtask <create|list|update|delete>`
-- `trekoon dep <add|remove|list>`
-- `trekoon sync <status|pull|resolve>`
+- `trekoon dep <add|remove|list|reverse>`
+- `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:
 
@@ -87,8 +92,9 @@ List defaults and filters (`epic list`, `task list`, `subtask list`):
 - Default limit: `10`
 - Status filter: `--status in_progress,todo` (CSV)
 - Custom limit: `--limit <n>`
+- Cursor pagination: `--cursor <n>` (offset-like start index for next page)
 - All rows and statuses: `--all`
-- `--all` is mutually exclusive with `--status` and `--limit`
+- `--all` is mutually exclusive with `--status`, `--limit`, and `--cursor`
 
 Bulk updates (`epic update`, `task update`, `subtask update`):
 
@@ -111,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
 
@@ -140,16 +153,40 @@ trekoon dep add <task-id> <depends-on-id>
 trekoon dep list <task-id>
 ```
 
-### 4) Use JSON or TOON output for agents
+### 4) AI execution loop for agents
+
+Run this loop each session to pick next work deterministically:
+
+```bash
+trekoon --toon sync status
+trekoon --toon task ready --limit 5
+trekoon --toon task next
+trekoon --toon dep reverse <task-or-subtask-id>
+trekoon --toon task update <task-id> --status in_progress
+```
+
+When done or blocked, append context and update final status:
+
+```bash
+trekoon --toon task update <task-id> --append "Completed implementation and checks" --status done
+trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
+```
+
+### 5) Use TOON output for agent workflows
 
 ```bash
-trekoon --json epic show <epic-id>
-trekoon --json task show <task-id>
 trekoon --toon epic show <epic-id>
 trekoon --toon task show <task-id>
 ```
 
-### 5) Sync workflow for worktrees
+Optional alternative for integrations that explicitly require JSON:
+
+```bash
+trekoon --json epic show <epic-id>
+trekoon --json task show <task-id>
+```
+
+### 6) Sync workflow for worktrees
 
 - Run `trekoon sync status` at session start and before PR/merge.
 - Run `trekoon sync pull --from main` before merge to align tracker state.
@@ -158,6 +195,8 @@ trekoon --toon 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
 ```
 
@@ -170,10 +209,31 @@ react deterministically:
 - `diagnostics.conflictEvents`
 - `diagnostics.errorHints`
 
-### 6) Install project-local Trekoon skill for agents
+Compatibility mode for legacy sync command IDs:
 
-`trekoon skills install` always writes the bundled skill file into the current
-repository at:
+```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 under the current
+working directory at:
 
 - `.agents/skills/trekoon/SKILL.md`
 
@@ -195,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.
@@ -212,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:
 
@@ -226,19 +286,119 @@ 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.
 
-### 7) Pre-merge checklist
+### 8) Pre-merge checklist
 
 - [ ] `trekoon sync status` shows no unresolved conflicts
 - [ ] done tasks/subtasks are marked completed
 - [ ] dependency graph has no stale blockers
 - [ ] final AI check: `trekoon --toon epic show <epic-id>`
 
+## Machine-contract recipes (--toon)
+
+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
+trekoon --toon task ready --limit 3
+```
+
+Payload fields:
+
+```text
+ok: true
+command: task.ready
+data:
+  candidates[]:
+    task: { id, epicId, title, status, ... }
+    readiness: { isReady, reason }
+    blockerSummary: { blockedByCount, totalDependencies, blockedBy[] }
+    ranking: { rank, blockerCount, statusPriority }
+  blocked[]: (same shape, non-ready items)
+  summary: {
+    totalOpenTasks,
+    readyCount,
+    returnedCount,
+    appliedLimit,
+    blockedCount,
+    unresolvedDependencyCount,
+  }
+```
+
+### Reverse dependency walk (blocker impact)
+
+```bash
+trekoon --toon dep reverse <task-or-subtask-id>
+```
+
+Payload fields:
+
+```text
+ok: true
+command: dep.reverse
+data:
+  targetId: <id>
+  targetKind: task|subtask
+  blockedNodes[]: { id, kind, distance, isDirect }
+```
+
+### Pagination contract for machine list calls
+
+```bash
+trekoon --toon task list --status todo --limit 2
+trekoon --toon task list --status todo --limit 2 --cursor 2
+```
+
+Cursor semantics:
+
+- `--cursor <n>` is offset-like pagination for list endpoints (`epic list`,
+  `task list`, `subtask list`).
+- Do not combine `--all` with `--cursor`.
+- Machine consumers should page using `meta.pagination.hasMore` and
+  `meta.pagination.nextCursor`.
+
+Payload fields:
+
+```text
+ok: true
+command: task.list
+data:
+  tasks[]: ...
+metadata:
+  contractVersion: "1.0.0"
+  requestId: req-<stable-id>
+meta:
+  pagination: { hasMore, nextCursor }
+```
+
 ## Implementation principles
 
 - Minimal, composable modules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.1.7",
+  "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,
   };
 }
 
@@ -79,6 +83,97 @@ export function parseStrictPositiveInt(rawValue: string | undefined): number | u
   return parsed;
 }
 
+export function parseStrictNonNegativeInt(rawValue: string | undefined): number | undefined {
+  if (rawValue === undefined) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(rawValue, 10);
+  if (!Number.isInteger(parsed) || parsed < 0 || `${parsed}` !== rawValue.trim()) {
+    return Number.NaN;
+  }
+
+  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/dep.ts

@@ -86,10 +86,29 @@ export async function runDep(context: CliContext): Promise<CliResult> {
           },
         });
       }
+      case "reverse": {
+        const targetKind = domain.resolveNodeKind(sourceId);
+        const blockedNodes = domain.listReverseDependencies(sourceId);
+
+        return okResult({
+          command: "dep.reverse",
+          human:
+            blockedNodes.length === 0
+              ? `No downstream blockers for ${sourceId}`
+              : blockedNodes
+                  .map((item) => `${item.id} (${item.kind}, distance=${item.distance})`)
+                  .join("\n"),
+          data: {
+            targetId: sourceId,
+            targetKind,
+            blockedNodes,
+          },
+        });
+      }
       default:
         return failResult({
           command: "dep",
-          human: "Usage: trekoon dep <add|remove|list>",
+          human: "Usage: trekoon dep <add|remove|list|reverse>",
           data: {
             args: context.args,
           },