trekoon 0.1.8 → 0.2.0

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 |
@@ -253,7 +295,80 @@ Rules:
 - In bulk mode, do not pass a positional ID.
 - Bulk update supports `--append` and/or `--status`.
 
-## 7) Setup/install/init (if `trekoon` is unavailable)
+## 7) Scoped search/replace recipes for agents
+
+Use scoped search/replace instead of repeated `show` scans when you need to
+locate or migrate repeated text inside one issue tree.
+
+```bash
+trekoon epic search <epic-id> "path/to/somewhere" --toon
+trekoon task search <task-id> "path/to/somewhere" --toon
+trekoon subtask search <subtask-id> "path/to/somewhere" --toon
+
+trekoon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --toon
+trekoon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --apply --toon
+```
+
+Guardrails:
+
+- Use `search` first when you only need to confirm whether the text exists.
+- Use preview `replace` next to confirm the exact candidate set.
+- Use `--apply` only after preview matches the intended scope.
+- Prefer the narrowest root that satisfies the task: `subtask` → `task` →
+  `epic`.
+- Keep prompts deterministic: literal search text, explicit IDs, no regex
+  assumptions.
+
+Agent contract for epic-scoped replace:
+
+- Exact search command:
+  `trekoon epic search <epic-id> "path/to/somewhere" --toon`
+- Exact replace command:
+  `trekoon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --toon`
+- Apply command:
+  `trekoon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --apply --toon`
+- Epic scope includes the epic title/description plus every task and subtask
+  title/description in that epic tree.
+
+Compact TOON fields to expect:
+
+```text
+ok: true
+command: epic.search
+data:
+  scope: epic
+  query: { search, fields[], mode: preview }
+  matches[]: { kind, id, fields[]: { field, count, snippet } }
+  summary: { matchedEntities, matchedFields, totalMatches }
+metadata:
+  contractVersion: 1.0.0
+  requestId: req-<id>
+```
+
+```text
+ok: true
+command: epic.replace
+data:
+  scope: epic
+  query: { search, replace, fields[], mode: preview|apply }
+  matches[]: { kind, id, fields[]: { field, count, snippet } }
+  summary: { matchedEntities, matchedFields, totalMatches, mode }
+metadata:
+  contractVersion: 1.0.0
+  requestId: req-<id>
+```
+
+Background behavior to assume:
+
+- Scope traversal is deterministic: epic first, then descendant tasks, then
+  descendant subtasks.
+- Field traversal is deterministic: `title` before `description`.
+- Preview reads and summarizes candidates without mutation.
+- `--apply` reuses the same scoped traversal, mutates only rows with real text
+  changes, and returns matched rows with `query.mode` and `summary.mode` set
+  to `"apply"`.
+
+## 8) Setup/install/init (if `trekoon` is unavailable)
 
 1. Install Trekoon (or make sure it is on `PATH`).
 2. In the target repository/worktree, initialize tracker state:
@@ -267,7 +382,7 @@ trekoon init --toon
 
 If `.trekoon/trekoon.db` is missing, initialize before any create/update commands.
 
-## 8) Safety
+## 9) Safety
 
 - Never edit `.trekoon/trekoon.db` directly.
 - `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|ready|next|update|delete>`
-- `trekoon subtask <create|list|update|delete>`
+- `trekoon epic <create|list|show|search|replace|update|delete>`
+- `trekoon task <create|list|show|ready|next|search|replace|update|delete>`
+- `trekoon subtask <create|list|search|replace|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
 
@@ -174,7 +186,88 @@ trekoon --json epic show <epic-id>
 trekoon --json task show <task-id>
 ```
 
-### 6) Sync workflow for worktrees
+### 6) Scoped search for repeated text
+
+Use scoped search before manual tree reads when you need to locate repeated
+paths, labels, or migration targets.
+
+```bash
+trekoon --toon epic search <epic-id> "path/to/somewhere"
+trekoon --toon task search <task-id> "path/to/somewhere"
+trekoon --toon subtask search <subtask-id> "path/to/somewhere"
+```
+
+Scope rules:
+
+- `epic search` scans the epic title/description plus every task and subtask
+  title/description in that epic tree.
+- `task search` scans the task title/description plus descendant subtask
+  title/description.
+- `subtask search` scans only that subtask's title/description.
+- Add `--fields title`, `--fields description`, or
+  `--fields title,description` when you need a narrower scan.
+
+### 7) Preview first, then apply scoped replace
+
+Use search first to confirm the scope, then run replace in preview mode, and
+only use `--apply` after the preview matches the intended migration.
+
+```bash
+trekoon --toon epic search <epic-id> "path/to/somewhere"
+trekoon --toon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path"
+trekoon --toon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --apply
+```
+
+Use this loop for low-risk agent workflows:
+
+1. `search` when you need the smallest possible read before deciding whether a
+   migration is needed.
+2. preview `replace` to verify the exact candidate set and changed fields.
+3. `replace --apply` only after the preview output matches the intended scope.
+
+Epic-scoped replace applies across the epic title/description and every task and
+subtask title/description in that epic tree.
+
+Compact TOON expectations for agents:
+
+```text
+ok: true
+command: epic.search
+data:
+  scope: epic
+  query: { search, fields[], mode: preview }
+  matches[]: { kind, id, fields[]: { field, count, snippet } }
+  summary: { matchedEntities, matchedFields, totalMatches }
+metadata:
+  contractVersion: 1.0.0
+  requestId: req-<id>
+```
+
+```text
+ok: true
+command: epic.replace
+data:
+  scope: epic
+  query: { search, replace, fields[], mode: preview|apply }
+  matches[]: { kind, id, fields[]: { field, count, snippet } }
+  summary: { matchedEntities, matchedFields, totalMatches, mode }
+metadata:
+  contractVersion: 1.0.0
+  requestId: req-<id>
+```
+
+Background behavior:
+
+- `epic search` and preview `epic replace` traverse the epic first, then
+  descendant tasks, then descendant subtasks.
+- Within each record, Trekoon checks `title` before `description` so output stays
+  deterministic and low-token.
+- Preview reports the candidate set without mutating records.
+- `--apply` reuses the same scoped traversal, updates only rows with real text
+  changes, and returns the matched rows with `query.mode` and `summary.mode`
+  set to `"apply"`.
+
+### 8) 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.
@@ -183,6 +276,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 +290,31 @@ react deterministically:
 - `diagnostics.conflictEvents`
 - `diagnostics.errorHints`
 
-### 7) Install project-local Trekoon skill for agents
+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
+```
 
-`trekoon skills install` always writes the bundled skill file into the current
-repository at:
+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.
+
+### 9) 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`
 
@@ -220,7 +336,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 +353,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,13 +367,13 @@ 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.
 
-### 8) Pre-merge checklist
+### 10) Pre-merge checklist
 
 - [ ] `trekoon sync status` shows no unresolved conflicts
 - [ ] done tasks/subtasks are marked completed
@@ -269,6 +385,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 +473,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.2.0",
   "description": "AI-first local issue tracker CLI.",
   "license": "MIT",
   "type": "module",

package/src/commands/arg-parser.ts

@@ -3,6 +3,22 @@ export interface ParsedArgs {
   readonly options: ReadonlyMap<string, string>;
   readonly flags: ReadonlySet<string>;
   readonly missingOptionValues: ReadonlySet<string>;
+  readonly providedOptions: readonly string[];
+}
+
+export const SEARCH_REPLACE_FIELDS = ["title", "description"] as const;
+
+export type SearchReplaceField = (typeof SEARCH_REPLACE_FIELDS)[number];
+
+export interface ParsedCsvEnumOption<T extends string> {
+  readonly values: readonly T[];
+  readonly invalidValues: readonly string[];
+  readonly empty: boolean;
+}
+
+export interface PreviewApplyModeSelection {
+  readonly mode: "preview" | "apply";
+  readonly conflict: boolean;
 }
 
 const LONG_PREFIX = "--";
@@ -12,6 +28,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 +42,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 +59,7 @@ export function parseArgs(args: readonly string[]): ParsedArgs {
     options,
     flags,
     missingOptionValues,
+    providedOptions,
   };
 }
 
@@ -92,6 +111,151 @@ export function parseStrictNonNegativeInt(rawValue: string | undefined): number
   return parsed;
 }
 
+export function parseCsvOption(rawValue: string | undefined): string[] | undefined {
+  if (rawValue === undefined) {
+    return undefined;
+  }
+
+  return rawValue
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
+}
+
+export function parseCsvEnumOption<const T extends readonly string[]>(
+  rawValue: string | undefined,
+  allowed: T,
+): ParsedCsvEnumOption<T[number]> {
+  const values = parseCsvOption(rawValue);
+  if (values === undefined) {
+    return {
+      values: [...allowed],
+      invalidValues: [],
+      empty: false,
+    };
+  }
+
+  if (values.length === 0) {
+    return {
+      values: [...allowed],
+      invalidValues: [],
+      empty: true,
+    };
+  }
+
+  const allowedValues = new Set<string>(allowed);
+  const validValues: T[number][] = [];
+  const invalidValues: string[] = [];
+
+  for (const value of values) {
+    if (!allowedValues.has(value)) {
+      invalidValues.push(value);
+      continue;
+    }
+
+    if (!validValues.includes(value as T[number])) {
+      validValues.push(value as T[number]);
+    }
+  }
+
+  return {
+    values: validValues.length > 0 ? validValues : [...allowed],
+    invalidValues,
+    empty: false,
+  };
+}
+
+export function resolvePreviewApplyMode(
+  flags: ReadonlySet<string>,
+  previewKey = "preview",
+  applyKey = "apply",
+): PreviewApplyModeSelection {
+  const preview = flags.has(previewKey);
+  const apply = flags.has(applyKey);
+  return {
+    mode: apply ? "apply" : "preview",
+    conflict: preview && apply,
+  };
+}
+
+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,