trekoon 0.2.1 → 0.2.5

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

@@ -19,47 +19,67 @@ pick the right command with the fewest reads and mutations.
 - Preview replace before `--apply`.
 - Prefer `--ids` over `--all` for bulk updates.
 - Never edit `.trekoon/trekoon.db` directly.
+- Treat `.trekoon` as shared repo-scoped operational state in git worktrees.
+- Keep `.trekoon` gitignored; do not commit the SQLite DB as a recovery fix.
 - Never run `trekoon wipe --yes --toon` unless the user explicitly asks for it.
 
 ## Default agent loop
 
-Run this loop each session:
+The primary loop is: **session → work → task done → repeat**.
 
-1. Check sync baseline:
+### 1. Orient with a single call
 
-   ```bash
-   trekoon --toon sync status
-   ```
+```bash
+trekoon --toon session
+```
+
+`session` replaces the old five-call bootstrap sequence
+(init + sync status + task next + dep list + task show) with a single DB open.
+It returns diagnostics, sync status, the full next-task tree with subtasks, blocker
+list, and readiness counts in one envelope.
+
+Fail fast if the envelope reports `recoveryRequired`, a storage mismatch, or any
+bootstrap error. In linked worktrees, `sharedStorageRoot` may differ from
+`worktreeRoot`; that is expected because the repo shares one DB across checkouts.
+
+If the session envelope shows `behind > 0`, pull before claiming any task:
+
+```bash
+trekoon --toon sync pull --from main
+```
+
+This syncs tracker events (not git commits) from the source branch so task
+states, dependencies, and subtrees are up to date before you start work.
 
-   If this returns `missing_branch_db` on a fresh branch or worktree, continue
-   with local task selection and treat sync as unavailable for now.
+### 2. Claim work explicitly
 
-2. Pick the next item deterministically:
+```bash
+trekoon --toon task update <task-id> --status in_progress
+```
 
-   ```bash
-   trekoon --toon task next
-   trekoon --toon task ready --limit 5
-   ```
+### 3. Finish or report a block
 
-3. Inspect dependencies or downstream impact when needed:
+```bash
+trekoon --toon task done <task-id>
+trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
+```
 
-   ```bash
-   trekoon --toon dep list <task-id>
-   trekoon --toon dep reverse <task-or-subtask-id>
-   ```
+`task done` replaces the old three-call transition sequence
+(mark done + get next + load deps + show task) with a single call that marks the
+task done and returns the next ready candidate with its full tree and blockers.
 
-4. Claim work explicitly:
+Append a completion note before calling `task done` when useful:
 
-   ```bash
-   trekoon --toon task update <task-id> --status in_progress
-   ```
+```bash
+trekoon --toon task update <task-id> --append "Completed implementation and checks"
+trekoon --toon task done <task-id>
+```
 
-5. Finish or report a block with appended context:
+### 4. Repeat
 
-   ```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
-   ```
+Run `session` again at the start of each new session. After `task done`, the
+returned next-task envelope is sufficient to continue; a fresh `session` call is
+not required mid-loop unless you need updated diagnostics or sync status.
 
 Recommended statuses for consistent workflows: `todo`, `in_progress`, `done`.
 
@@ -69,7 +89,8 @@ Use the narrowest command that answers the question.
 
 | Need | Preferred command |
 |---|---|
-| Next task | `trekoon --toon task next` |
+| Session startup (diagnostics + sync + next task) | `trekoon --toon session` |
+| Next task only | `trekoon --toon task next` |
 | A few ready options | `trekoon --toon task ready --limit 5` |
 | Direct blockers for one task | `trekoon --toon dep list <task-id>` |
 | What this item unblocks | `trekoon --toon dep reverse <task-or-subtask-id>` |
@@ -97,6 +118,28 @@ creates unless only one record is needed.
 | Multiple dependency edges across existing IDs | `trekoon --toon dep add-many --dep ...` |
 | One record only | `epic create`, `task create`, or `subtask create` |
 
+### Compact spec escaping rules
+
+Compact specs (pipe-delimited `--task`, `--subtask`, `--dep` values) use `\` as
+the escape character. Only these sequences are valid:
+
+| Sequence | Produces |
+|---|---|
+| `\|` | literal `|` (not a field separator) |
+| `\\` | literal `\` |
+| `\n` | newline |
+| `\r` | carriage return |
+| `\t` | tab |
+
+Any other `\X` combination (e.g., `\!`, `\=`, `\$`) is rejected with
+`Invalid escape sequence`. To avoid accidental escapes:
+
+- Do not use `!=` or similar operators in description text; rephrase instead
+  (e.g., "null does not equal sourceBranch" instead of "null !== sourceBranch").
+- If a literal backslash is needed, double it: `\\`.
+- When using shell line continuations (`\` at end of line), ensure the next
+  line's first character is not one that forms an invalid escape with `\`.
+
 ### Critical temp-key rule
 
 - Use plain temp keys when declaring records in compact specs, for example
@@ -229,20 +272,35 @@ Guardrails:
 
 ## Setup and fallback
 
-If Trekoon is unavailable or state is missing:
+If Trekoon is unavailable or storage diagnostics require repair:
 
 ```bash
 trekoon --toon init
+trekoon --toon sync status
 trekoon --toon quickstart
-trekoon --help --toon
+trekoon --toon help sync
 ```
 
-Use `quickstart` for the canonical execution loop. Use `--help --toon` when you
-need exact syntax.
+Rules:
+
+- Re-bootstrap first, then re-read diagnostics.
+- Stop if `recoveryRequired` stays true or diagnostics report storage mismatch.
+- Do not continue with task selection after missing shared storage or broken
+  bootstrap.
+- Do not commit `.trekoon/trekoon.db`; remove the tracked DB and keep
+  `.trekoon` ignored instead.
+
+Use `quickstart` for the canonical execution loop. Use help when you need exact
+syntax.
 
 ## Sync reminders
 
-- Run `trekoon --toon sync status` at session start and before PR or merge.
+Same-branch sync is a no-op: `sync pull --from main` while on `main` produces
+zero conflicts and simply advances the cursor. `sync status` returns `behind=0`
+on the source branch. No action is needed.
+
+Cross-branch sync matters before merging a feature branch back:
+
 - Before merge, pull tracker events from the base branch:
 
   ```bash
@@ -257,5 +315,18 @@ need exact syntax.
   trekoon --toon sync resolve <conflict-id> --use ours
   ```
 
+## Worktree diagnostics and destructive scope
+
+- Inspect machine-readable storage fields when debugging worktrees:
+  `storageMode`, `repoCommonDir`, `worktreeRoot`, `sharedStorageRoot`, and
+  `databaseFile`.
+- `sharedStorageRoot` is the repo-scoped source of truth for `.trekoon` in git
+  worktrees.
+- If `trekoon wipe --yes --toon` is explicitly requested, warn that it deletes
+  shared storage for the entire repository and every linked worktree.
+- Wipe is destructive recovery only; it is never the right fix for a tracked DB
+  or gitignore mistake.
+
 Trekoon stores local state in `.trekoon/trekoon.db`. In git repos and
-worktrees, storage resolves from the repository root.
+worktrees, storage resolves from the shared repository root rather than each
+worktree independently.

package/README.md

@@ -40,7 +40,7 @@ npm i -g trekoon
 
 1. Make issue tracking fast enough for daily terminal use.
 2. Make issue data deterministic and machine-readable for AI automation.
-3. Keep branch/worktree-aware state so parallel execution can be coordinated safely.
+3. Keep one repo-scoped state store that every worktree can coordinate through safely.
 4. Stay minimal in code size while preserving robustness and clear boundaries.
 
 ## Command surface
@@ -49,7 +49,8 @@ npm i -g trekoon
 - `trekoon help [command]`
 - `trekoon quickstart`
 - `trekoon epic <create|expand|list|show|search|replace|update|delete>`
-- `trekoon task <create|create-many|list|show|ready|next|search|replace|update|delete>`
+- `trekoon session`
+- `trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete>`
 - `trekoon subtask <create|create-many|list|search|replace|update|delete>`
 - `trekoon dep <add|add-many|remove|list|reverse>`
 - `trekoon events prune [--dry-run] [--archive] [--retention-days <n>]`
@@ -117,15 +118,23 @@ trekoon epic update --ids <epic-1>,<epic-2> --status done
 
 ## Quickstart
 
-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`.
+Trekoon is local-first, but in 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`.
+
+- `worktreeRoot` identifies the current checkout.
+- `sharedStorageRoot` identifies the repository root that owns `.trekoon`.
+- `databaseFile` points at the shared SQLite database.
+- `.trekoon` stays gitignored on purpose because the DB is operational state,
+  not source code.
+- Committing `.trekoon/trekoon.db` is the wrong fix for drift because it bakes
+  machine-local state and stale snapshots into Git.
 
 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.
+`meta.storageRootDiagnostics` so automation can verify the storage contract.
 
 ### 1) Initialize
 
@@ -134,6 +143,15 @@ trekoon init
 trekoon --version
 ```
 
+Bootstrap expectations:
+
+- 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/ignored mismatch, or an
+  ambiguous recovery path, stop and repair setup before continuing.
+- Do **not** continue with task selection after broken bootstrap warnings.
+
 ### 2) Create epic → task → subtask
 
 ```bash
@@ -366,23 +384,52 @@ When to choose which command:
 
 ### 4) AI execution loop for agents
 
-Run this loop each session to pick next work deterministically:
+The primary loop is: **session → work → task done → repeat**.
+
+Orient with a single call that returns diagnostics, sync status, next ready
+task with subtasks, blocker list, and readiness counts:
+
+```bash
+trekoon --toon session
+```
+
+Claim work, then finish or report a block:
 
 ```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
+trekoon --toon task done <task-id>
+trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
 ```
 
-When done or blocked, append context and update final status:
+`task done` marks the task done and returns the next ready task with
+dependencies inline, replacing the old multi-step transition.
+
+Fail-fast rules:
+
+- Treat `meta.storageRootDiagnostics` as the source of truth for worktree
+  storage.
+- In linked worktrees, `sharedStorageRoot` may differ from `worktreeRoot`; that
+  is expected.
+- If `recoveryRequired` is `true`, stop and follow the reported bootstrap or
+  recovery action.
+- Do not fall back to a separate per-worktree DB or continue after missing
+  shared storage.
+
+<details>
+<summary>Legacy manual bootstrap (use <code>session</code> instead)</summary>
 
 ```bash
+trekoon --toon init
+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
 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
 ```
 
+</details>
+
 ### 5) Use TOON output for agent workflows
 
 ```bash
@@ -501,6 +548,19 @@ react deterministically:
 - `diagnostics.conflictEvents`
 - `diagnostics.errorHints`
 
+Worktree diagnostics and recovery:
+
+- Inspect `storageMode`, `repoCommonDir`, `worktreeRoot`, `sharedStorageRoot`,
+  and `databaseFile` in machine output when debugging worktree behavior.
+- If a worktree resolves shared storage outside its checkout, that is expected
+  for linked worktrees and should not be “fixed” by committing `.trekoon`.
+- If Git contains a tracked `.trekoon/trekoon.db`, remove it from Git history or
+  the index as appropriate, keep `.trekoon` ignored, and re-run
+  `trekoon --toon init`.
+- Use `trekoon wipe --yes` only for explicit destructive recovery; it deletes
+  the shared storage root for the entire repository, not just the current
+  worktree.
+
 Compatibility mode for legacy sync command IDs:
 
 ```bash
@@ -590,6 +650,7 @@ Trekoon does not mutate global editor config directories.
 - [ ] done tasks/subtasks are marked completed
 - [ ] dependency graph has no stale blockers
 - [ ] final AI check: `trekoon --toon epic show <epic-id>`
+- [ ] no one tried to commit `.trekoon/trekoon.db` as a worktree fix
 
 ## Machine-contract recipes (--toon)
 

package/package.json

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

package/src/commands/help.ts

@@ -18,15 +18,16 @@ const ROOT_HELP = [
   "",
   "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)",
+  "  init         Initialize repo-shared .trekoon storage and DB",
+  "  quickstart   Show shared-storage bootstrap + AI execution loop",
+  "  wipe         Remove repo-shared Trekoon state (requires --yes)",
   "  epic         Epic lifecycle commands",
   "  task         Task lifecycle commands",
   "  subtask      Subtask lifecycle commands",
   "  dep          Dependency graph commands",
   "  events       Event retention and cleanup commands",
   "  migrate      Migration status and rollback commands",
+  "  session      One-call agent orientation (diagnostics + sync + next task)",
   "  sync         Cross-branch sync commands",
   "  skills       Project-local skill install/update/link",
 ].join("\n");
@@ -35,7 +36,9 @@ const INIT_HELP = [
   "Usage: trekoon init [--json|--toon]",
   "",
   "Purpose:",
-  "  Initialize local Trekoon storage (.trekoon) and database.",
+  "  Initialize repo-scoped Trekoon storage (.trekoon) and database.",
+  "  In git worktrees, every worktree shares the same repository DB.",
+  "  Keep .trekoon gitignored; committing the SQLite DB is not a recovery path.",
   "",
   "Examples:",
   "  trekoon init",
@@ -46,14 +49,16 @@ const QUICKSTART_HELP = [
   "Usage: trekoon quickstart [--json|--toon]",
   "",
   "Purpose:",
-  "  Show the canonical Trekoon AI execution loop and task-detail workflow.",
+  "  Show shared-storage bootstrap, diagnostics, and the canonical AI loop.",
   "",
   "Flow:",
-  "  1) trekoon --toon sync status",
-  "  2) trekoon --toon task ready --limit 5",
-  "  3) trekoon --toon task next",
-  "  4) trekoon --toon dep reverse <task-or-subtask-id>",
-  "  5) trekoon --toon task update <task-id> --status in_progress",
+  "  1) trekoon --toon init",
+  "  2) trekoon --toon sync status",
+  "  3) Fail fast on recoveryRequired or tracked/ignored mismatch diagnostics",
+  "  4) trekoon --toon task ready --limit 5",
+  "  5) trekoon --toon task next",
+  "  6) trekoon --toon dep reverse <task-or-subtask-id>",
+  "  7) trekoon --toon task update <task-id> --status in_progress",
   "",
   "Examples:",
   "  trekoon quickstart",
@@ -64,10 +69,15 @@ const WIPE_HELP = [
   "Usage: trekoon wipe --yes [--json|--toon]",
   "",
   "Purpose:",
-  "  Remove local Trekoon state for the current repository.",
+  "  Remove the repository's shared Trekoon storage directory.",
+  "  In git worktrees this erases the same .trekoon state for every linked worktree.",
   "",
   "Options:",
-  "  --yes  Required safety confirmation.",
+  "  --yes  Required confirmation for destructive repo-wide removal.",
+  "",
+  "Recovery guidance:",
+  "  Use wipe only for explicit destructive recovery.",
+  "  Do not use wipe to fix gitignore mistakes or to replace bootstrap diagnostics.",
   "",
   "Examples:",
   "  trekoon wipe --yes",
@@ -312,6 +322,28 @@ const SYNC_HELP = [
   "  trekoon sync resolve <conflict-id> --use ours",
 ].join("\n");
 
+const SESSION_HELP = [
+  "Usage: trekoon session [--json|--toon]",
+  "",
+  "Purpose:",
+  "  One-call agent orientation. Opens DB once and returns:",
+  "    - diagnostics: storageMode, recoveryRequired, recoveryStatus",
+  "    - sync: ahead/behind counts and pendingConflicts vs main",
+  "    - next: full task tree with subtasks for the top ready candidate (null if none)",
+  "    - nextDeps: blocker list with statuses for the next task (empty if none)",
+  "    - readiness: readyCount and blockedCount across all open tasks",
+  "",
+  "Output modes:",
+  "  human  Multi-section summary (default in TTY)",
+  "  toon   Compact pipe-encoded envelope",
+  "  json   Full structured JSON envelope",
+  "",
+  "Examples:",
+  "  trekoon session",
+  "  trekoon --toon session",
+  "  trekoon --json session",
+].join("\n");
+
 const SKILLS_HELP = [
   "Usage:",
   "  trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]",
@@ -331,7 +363,8 @@ const SKILLS_HELP = [
   "",
   "Update behavior:",
   "  - Refreshes canonical SKILL file in the install path above.",
-  "  - Reports default link states for opencode/claude/pi.",
+  "  - Auto-creates or refreshes editor symlinks when editor config dir exists.",
+  "  - Skips editors with no config dir or conflicting paths.",
   "",
   "Examples:",
   "  trekoon skills install",
@@ -344,6 +377,7 @@ const SKILLS_HELP = [
 const COMMAND_HELP: Record<string, string> = {
   init: INIT_HELP,
   quickstart: QUICKSTART_HELP,
+  session: SESSION_HELP,
   wipe: WIPE_HELP,
   epic: EPIC_HELP,
   task: TASK_HELP,

package/src/commands/init.ts

@@ -1,27 +1,125 @@
 import { unexpectedFailureResult } from "./error-utils";
 
-import { okResult } from "../io/output";
+import { DomainError } from "../domain/types";
+import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
 import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
 
+function buildRecoverySummary(database: TrekoonDatabase): string[] {
+  const diagnostics = database.diagnostics;
+  const lines: string[] = [];
+
+  if (diagnostics.recoveryStatus === "no_legacy_state") {
+    lines.push("Recovery status: no legacy worktree-local state detected.");
+    return lines;
+  }
+
+  if (diagnostics.recoveryStatus === "safe_auto_migrate") {
+    if (diagnostics.autoMigratedLegacyState) {
+      lines.push("Recovery status: safe auto-migrate completed.");
+      lines.push(`Imported from: ${diagnostics.importedFromLegacyDatabase}`);
+      lines.push(`Backups created: ${diagnostics.backupFiles.join(", ")}`);
+    } else {
+      lines.push("Recovery status: legacy worktree-local state detected.");
+      lines.push("Shared storage already exists; no import was required.");
+    }
+
+    lines.push(`Operator action: ${diagnostics.operatorAction}`);
+    return lines;
+  }
+
+  lines.push(`Recovery status: ${diagnostics.recoveryStatus}`);
+  lines.push(`Operator action: ${diagnostics.operatorAction}`);
+  return lines;
+}
+
+function recoveryFailureResult(error: DomainError): CliResult | null {
+  if (error.code !== "ambiguous_legacy_state" && error.code !== "tracked_ignored_mismatch") {
+    return null;
+  }
+
+  const details = error.details ?? {};
+  const status = typeof details.status === "string" ? details.status : error.code;
+  const operatorAction = typeof details.operatorAction === "string" ? details.operatorAction : error.message;
+  const legacyDatabaseFiles = Array.isArray(details.legacyDatabaseFiles) ? details.legacyDatabaseFiles : [];
+  const trackedStorageFiles = Array.isArray(details.trackedStorageFiles) ? details.trackedStorageFiles : [];
+  const humanLines: string[] = [
+    "Trekoon init requires operator action.",
+    `Recovery status: ${status}`,
+    error.message,
+    `Operator action: ${operatorAction}`,
+  ];
+
+  if (legacyDatabaseFiles.length > 0) {
+    humanLines.push(`Legacy databases: ${legacyDatabaseFiles.join(", ")}`);
+  }
+
+  if (trackedStorageFiles.length > 0) {
+    humanLines.push(`Tracked storage files: ${trackedStorageFiles.join(", ")}`);
+  }
+
+  return failResult({
+    command: "init",
+    human: humanLines.join("\n"),
+    data: {
+      status,
+      legacyDatabaseFiles,
+      trackedStorageFiles,
+      operatorAction,
+    },
+    error: {
+      code: error.code,
+      message: error.message,
+    },
+  });
+}
+
 export async function runInit(context: CliContext): Promise<CliResult> {
   let database: TrekoonDatabase | undefined;
 
   try {
     database = openTrekoonDatabase(context.cwd);
+    const diagnostics = database.diagnostics;
+    const humanLines: string[] = [
+      "Trekoon initialized.",
+      `Storage mode: ${diagnostics.storageMode}`,
+      `Worktree root: ${diagnostics.worktreeRoot}`,
+      `Shared storage root: ${diagnostics.sharedStorageRoot}`,
+      `Storage directory: ${database.paths.storageDir}`,
+      `Database file: ${database.paths.databaseFile}`,
+      ...buildRecoverySummary(database),
+    ];
+
     return okResult({
       command: "init",
-      human: [
-        "Trekoon initialized.",
-        `Storage directory: ${database.paths.storageDir}`,
-        `Database file: ${database.paths.databaseFile}`,
-      ].join("\n"),
+      human: humanLines.join("\n"),
       data: {
+        invocationCwd: diagnostics.invocationCwd,
+        storageMode: diagnostics.storageMode,
+        repoCommonDir: diagnostics.repoCommonDir,
+        worktreeRoot: diagnostics.worktreeRoot,
+        sharedStorageRoot: diagnostics.sharedStorageRoot,
         storageDir: database.paths.storageDir,
         databaseFile: database.paths.databaseFile,
+        legacyStateDetected: diagnostics.legacyStateDetected,
+        recoveryRequired: diagnostics.recoveryRequired,
+        recoveryStatus: diagnostics.recoveryStatus,
+        legacyDatabaseFiles: diagnostics.legacyDatabaseFiles,
+        backupFiles: diagnostics.backupFiles,
+        trackedStorageFiles: diagnostics.trackedStorageFiles,
+        autoMigratedLegacyState: diagnostics.autoMigratedLegacyState,
+        importedFromLegacyDatabase: diagnostics.importedFromLegacyDatabase,
+        operatorAction: diagnostics.operatorAction,
       },
     });
   } catch (error: unknown) {
+    if (error instanceof DomainError) {
+      const recoveryFailure = recoveryFailureResult(error);
+      if (recoveryFailure !== null) {
+        return recoveryFailure;
+      }
+    }
+
     return unexpectedFailureResult(error, {
       command: "init",
       human: "Unexpected init command failure",