trekoon 0.1.6 → 0.1.8

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

@@ -101,6 +101,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 +128,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 +163,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 +192,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,6 +202,9 @@ 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`.
 - `epic show <id> --all --toon`: full epic tree (tasks + subtasks)
 - `task show <id> --all --toon`: task plus its subtasks
 
@@ -236,14 +259,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

@@ -48,11 +48,11 @@ npm i -g trekoon
 - `trekoon init`
 - `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 dep <add|remove|list|reverse>`
 - `trekoon sync <status|pull|resolve>`
-- `trekoon skills install [--link --editor opencode|claude|pi] [--to <path>]`
+- `trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]`
 - `trekoon skills update`
 - `trekoon wipe --yes`
 
@@ -87,8 +87,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`):
 
@@ -140,16 +141,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.
@@ -161,7 +186,16 @@ trekoon sync pull --from main
 trekoon sync resolve <conflict-id> --use ours
 ```
 
-### 6) Install project-local Trekoon skill for agents
+`sync pull` machine output includes diagnostics counters and hints so agents can
+react deterministically:
+
+- `diagnostics.malformedPayloadEvents`
+- `diagnostics.applyRejectedEvents`
+- `diagnostics.quarantinedEvents`
+- `diagnostics.conflictEvents`
+- `diagnostics.errorHints`
+
+### 7) Install project-local Trekoon skill for agents
 
 `trekoon skills install` always writes the bundled skill file into the current
 repository at:
@@ -186,6 +220,10 @@ 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.
+- Use `--allow-outside-repo` only for intentional external links.
+- When override is used, install prints a warning and includes confirmation
+  fields in machine output.
 - Re-running install is idempotent: it refreshes `SKILL.md` and reuses/replaces
   the same symlink target.
 - `trekoon skills update` is idempotent: it refreshes canonical
@@ -219,13 +257,89 @@ This produces:
 
 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.
+
+### 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[]: ...
+meta:
+  pagination: { hasMore, nextCursor }
+```
+
 ## Implementation principles
 
 - Minimal, composable modules

package/package.json

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

package/src/commands/arg-parser.ts

@@ -79,6 +79,19 @@ 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;
+}
+
 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,
           },

package/src/commands/epic.ts

@@ -1,4 +1,12 @@
-import { hasFlag, parseArgs, parseStrictPositiveInt, readEnumOption, readMissingOptionValue, readOption } from "./arg-parser";
+import {
+  hasFlag,
+  parseArgs,
+  parseStrictNonNegativeInt,
+  parseStrictPositiveInt,
+  readEnumOption,
+  readMissingOptionValue,
+  readOption,
+} from "./arg-parser";
 
 import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
@@ -41,21 +49,58 @@ function getStatusPriority(status: string): number {
 }
 
 function sortByStatusPriority(epics: readonly EpicRecord[]): EpicRecord[] {
-  return [...epics].sort((left, right) => getStatusPriority(left.status) - getStatusPriority(right.status));
+  return [...epics].sort((left, right) => {
+    const byStatus = getStatusPriority(left.status) - getStatusPriority(right.status);
+    if (byStatus !== 0) {
+      return byStatus;
+    }
+
+    const byCreatedAt = left.createdAt - right.createdAt;
+    if (byCreatedAt !== 0) {
+      return byCreatedAt;
+    }
+
+    return left.id.localeCompare(right.id);
+  });
 }
 
-function filterSortAndLimitEpics(epics: readonly EpicRecord[], options: { includeAll: boolean; statuses: readonly string[] | undefined; limit: number | undefined }): EpicRecord[] {
-  const { includeAll, statuses, limit } = options;
+interface PaginationMeta {
+  readonly hasMore: boolean;
+  readonly nextCursor: string | null;
+}
+
+function filterSortAndLimitEpics(epics: readonly EpicRecord[], options: {
+  includeAll: boolean;
+  statuses: readonly string[] | undefined;
+  limit: number | undefined;
+  cursor: number;
+}): { epics: EpicRecord[]; pagination: PaginationMeta } {
+  const { includeAll, statuses, limit, cursor } = options;
   const selectedStatuses = includeAll ? undefined : (statuses ?? DEFAULT_OPEN_STATUSES);
   const selectedEpics = selectedStatuses === undefined ? [...epics] : epics.filter((epic) => selectedStatuses.includes(epic.status));
   const sortedEpics = sortByStatusPriority(selectedEpics);
 
   if (includeAll) {
-    return sortedEpics;
+    return {
+      epics: sortedEpics,
+      pagination: {
+        hasMore: false,
+        nextCursor: null,
+      },
+    };
   }
 
   const effectiveLimit = limit ?? DEFAULT_LIST_LIMIT;
-  return sortedEpics.slice(0, effectiveLimit);
+  const pagedEpics = sortedEpics.slice(cursor, cursor + effectiveLimit);
+  const nextIndex = cursor + pagedEpics.length;
+  const hasMore = nextIndex < sortedEpics.length;
+  return {
+    epics: pagedEpics,
+    pagination: {
+      hasMore,
+      nextCursor: hasMore ? `${nextIndex}` : null,
+    },
+  };
 }
 
 function invalidEpicListInput(human: string, message: string, data: Record<string, unknown>): CliResult {
@@ -266,6 +311,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
         const missingListOption =
           readMissingOptionValue(parsed.missingOptionValues, "status", "s") ??
           readMissingOptionValue(parsed.missingOptionValues, "limit", "l") ??
+          readMissingOptionValue(parsed.missingOptionValues, "cursor") ??
           readMissingOptionValue(parsed.missingOptionValues, "view");
         if (missingListOption !== undefined) {
           return failMissingOptionValue("epic.list", missingListOption);
@@ -274,6 +320,7 @@ 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 rawCursor: string | undefined = readOption(parsed.options, "cursor");
         const rawView: string | undefined = readOption(parsed.options, "view");
         const view = readEnumOption(parsed.options, VIEW_MODES, "view");
         if (rawView !== undefined && view === undefined) {
@@ -320,11 +367,28 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           });
         }
 
-        const epics = filterSortAndLimitEpics(domain.listEpics(), {
+        const cursor = parseStrictNonNegativeInt(rawCursor) ?? 0;
+        if (Number.isNaN(cursor)) {
+          return invalidEpicListInput("Invalid --cursor value. Use an integer >= 0.", "Invalid --cursor value", {
+            code: "invalid_input",
+            cursor: rawCursor,
+          });
+        }
+
+        if (includeAll && rawCursor !== undefined) {
+          return invalidEpicListInput("Use either --all or --cursor, not both.", "--all and --cursor are mutually exclusive", {
+            code: "invalid_input",
+            flags: ["all", "cursor"],
+          });
+        }
+
+        const listed = filterSortAndLimitEpics(domain.listEpics(), {
           includeAll,
           statuses,
           limit,
+          cursor,
         });
+        const epics = listed.epics;
         const listView = view ?? "table";
         const human = epics.length === 0 ? "No epics found." : listView === "compact" ? epics.map(formatEpic).join("\n") : formatEpicListTable(epics);
 
@@ -332,6 +396,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           command: "epic.list",
           human,
           data: { epics },
+          ...(context.mode === "human" ? {} : { meta: { pagination: listed.pagination } }),
         });
       }
       case "show": {