trekoon 0.4.6 → 0.4.8

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

@@ -106,6 +106,9 @@ continue broader epic execution only when it matches the user intent.
   current state.
 - Append progress, verification, and blocker notes with `--append`; do not
   rewrite descriptions unless fixing the plan itself.
+- Compact specs are pipe-split. Before any `--task`/`--subtask`/`--dep`,
+  rephrase or escape bare `|` (especially `||` and trailing `|`) as `\|`.
+  See `reference/planning.md` "CAUTION — bare-pipe footguns".
 - Preview search/replace before `--apply`.
 - Never edit `.trekoon/trekoon.db` directly. Keep `.trekoon` gitignored.
 - Never run `trekoon wipe --yes --toon` unless the user explicitly asks.

package/.agents/skills/trekoon/reference/harness-primitives.md

@@ -115,3 +115,28 @@ trekoon --toon task done <task-id>
 
 `task done` auto-walks `todo` or `blocked` through `in_progress`. For subtasks,
 move through `in_progress` (claim or status) before `done`.
+
+## Compact Spec Hazards
+
+Any batch creation command (`epic create`, `epic expand`, `task create-many`,
+`subtask create-many`, `dep add-many`) splits `--task`/`--subtask`/`--dep`
+values on raw `|`. Three recurring footguns — applies in plan and execute
+modes (e.g. mid-execution `epic expand`):
+
+1. **Single mid-value `|`** with no explicit `|<status>` field: trailing
+   text silently lands in the status slot. Creation succeeds, fails on next
+   transition.
+2. **`||`** (JS logical-OR, shell OR): adds two extra fields per occurrence,
+   overshoots the field-count gate. Rephrase as "or" or escape as `\|\|`.
+3. **Trailing `|`** is not a terminator: creates an empty final field; on a
+   4-field subtask shape that becomes an empty description and the parser
+   rejects with "is missing a description".
+
+Escape literal `|` as `\|`. Pre-flight specs:
+
+```bash
+grep -nE '(^|[^\\])\|\||\|$' specs.txt
+```
+
+Full rules and the silent/loud failure matrix live in
+`reference/planning.md` "CAUTION — bare-pipe footguns".

package/.agents/skills/trekoon/reference/planning.md

@@ -139,6 +139,30 @@ compact specs: `\?`, `\.`, `\{`, `\(`, `\[` etc. fail before records are
 created. Prefer prose over exact regex in descriptions. Rephrase operators
 like `!=` as words to avoid escaping confusion.
 
+Bare `|` inside field values is a field separator and will silently corrupt
+records when the spec omits an explicit `|<status>` field. A single shell
+pipe (`cmd a | cmd b`) in a Verify line on a 3-field task spec or 4-field
+subtask spec (epic create/expand) splits into one extra field, and the parser
+treats that trailing fragment as the status — but does not validate it.
+Creation succeeds and the record only breaks on the next status transition.
+Concrete failure: `--task "task-x|API|Verify: bun test foo | tail -20"`
+splits to `[task-x, API, "Verify: bun test foo ", " tail -20"]`; ` tail -20`
+becomes the status, and the bad status only surfaces on the next update.
+
+Escape literal `|` as `\|` or rephrase to avoid the character. `||` fallbacks
+(`cmd a || cmd b`) and other multi-pipe constructs are caught loudly by the
+parser: every unescaped `|` adds a field, so multi-pipe input overshoots the
+field-count gate and fails before any record is written. The empty-field gate
+fires on a different shape — a single bare middle pipe like
+`key|title||desc`. Either way, the silent failure mode is specifically the
+single-pipe / no-explicit-status case. Specs that already pass `|<status>`
+fail loudly even on a single unescaped `|`.
+
+A bare `|` at the very end of a spec (trailing pipe) is **not** a terminator.
+It produces an empty final field. On a `<...>|<title>|<description>` shape
+that empty field becomes the description and the parser rejects the spec with
+"is missing a description". Drop trailing `|`; never use it as a "done" marker.
+
 Spec shape (status optional, defaults to `todo`):
 
 - `--task <temp-key>|<title>|<description>` or `<temp-key>|<title>|<description>|<status>`
@@ -148,10 +172,21 @@ Spec shape (status optional, defaults to `todo`):
 Prefer the shorter form. Pass an explicit `|<status>` only when seeding a
 non-`todo` status.
 
+The three bare-pipe footguns (`||`, single mid-value `|`, trailing `|`) and
+the pre-flight `grep -nE '(^|[^\\])\|\||\|$'` recipe live in
+`reference/harness-primitives.md` "Compact Spec Hazards". The paragraphs
+above add the silent-vs-loud detail that the quick-ref points at. When in
+doubt, build descriptions as plain prose without operator characters.
+
 One-shot rules:
 
-- Declare tasks/subtasks with plain temp keys, e.g. `task-api`, `sub-tests`.
-- Refer to records created in the same command as `@task-api` or `@sub-tests`.
+- Declare tasks/subtasks with plain temp keys, e.g. `task-api`, `sub-api-tests`.
+- Temp keys form a flat namespace per command. Every `--task` and `--subtask`
+  key must be unique across the whole `epic create` / `epic expand` call, not
+  per parent task. Prefix subtask keys with the parent task key
+  (`sub-api-tests`, `sub-ui-states`) to stay safe across re-runs.
+- Refer to records created in the same command as `@task-api` or
+  `@sub-api-tests`.
 - Use `@task-key` as the subtask parent ref and in `--dep` specs.
 - `--dep <source>|<depends-on>` points from blocked item to prerequisite.
 - `epic create` returns `result.mappings` and counts. Use those real UUIDs in

package/docs/commands.md

@@ -179,6 +179,25 @@ Rules:
 - Subtask cascade is accepted for consistency but just updates one subtask
 - Success response includes `data.cascade` with changed/unchanged IDs and counts
 
+## Epic create and expand
+
+### Temp-key rules
+
+Temp keys in `--task` and `--subtask` share one flat namespace per `epic create` / `epic expand` invocation — reusing a key across any two records in the same call fails the batch. Prefix subtask keys with the parent task key to keep them unique (e.g. `task-a-sub-1` under `task-a`).
+
+`task create-many` and `subtask create-many` use their own scoped namespaces, independent of each other and of `epic create`.
+
+Escape any literal `|` inside field values as `\|`. A single bare `|` in a spec without an explicit `|<status>` field silently pushes the trailing text into the status slot — creation succeeds and the record only breaks on the next status update. Multi-pipe constructs like `||` fail loudly on the field-count check. See the planning skill for the full pipe-escape rules.
+
+```bash
+trekoon epic create \
+  --title "Launch" \
+  --task "task-a|First task|Description|todo" \
+  --task "task-b|Second task|Description|todo" \
+  --subtask "@task-a|task-a-sub-1|First subtask|Description|todo" \
+  --subtask "@task-b|task-b-sub-1|Second subtask|Description|todo"
+```
+
 ## Status machine
 
 Statuses: `todo`, `in_progress`, `done`, `blocked`. The hyphenated `in-progress`

package/docs/quickstart.md

@@ -93,11 +93,27 @@ trekoon --toon epic create \
   --description "Ship one-shot planning workflows" \
   --task "task-a|First task|First description|todo" \
   --task "task-b|Second task|Second description|todo" \
-  --subtask "@task-a|sub-a|First subtask|Subtask description|todo" \
+  --subtask "@task-a|sub-a-first|First subtask|Subtask description|todo" \
   --dep "@task-b|@task-a" \
-  --dep "@sub-a|@task-a"
+  --dep "@sub-a-first|@task-a"
 ```
 
+All temp keys (task and subtask) must be unique across the whole command — they share one flat namespace. Prefix subtask keys with the parent task key to stay unique.
+
+Escape any literal `|` inside field values as `\|`. Three recurring footguns:
+
+- **Single mid-value `|`** on a spec without explicit `|<status>` silently pushes trailing text into the status slot (e.g. `Verify: bun test foo | tail` lets `tail` become the status, and creation still succeeds). Specs that already pass `|<status>` fail loudly on the same input.
+- **`||`** (JS logical-OR `a || b`, shell OR `cmd || cmd`) adds two extra fields per occurrence; the field-count gate rejects with `Task specs must use ...` / `Subtask specs must use ...`. Rephrase `||` as "or" or escape as `\|\|`.
+- **Trailing `|`** is not a terminator. It creates an empty final field; on a 4-field subtask shape that empty field becomes the description and the parser rejects with "is missing a description". Drop trailing pipes.
+
+Pre-flight any batch before invoking `epic create`/`epic expand`/`task create-many`/`subtask create-many`:
+
+```bash
+grep -nE '(^|[^\\])\|\||\|$' specs.txt
+```
+
+See the planning skill for full rules.
+
 This is better than sequential creates because later records can reference
 earlier ones with `@temp-key`, and you get one atomic operation with mappings
 and counts in the response.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "AI-first task tracking that lives in your repo. You describe what to build, your agent plans it as a dependency graph, then executes it task by task",
   "keywords": [
     "ai",

package/src/commands/arg-parser.ts

@@ -285,6 +285,58 @@ export function parseCompactFields(rawValue: string): ParsedCompactFields {
   };
 }
 
+export function endsWithBareCompactPipe(rawSpec: string): boolean {
+  if (!rawSpec.endsWith("|")) {
+    return false;
+  }
+  let backslashes = 0;
+  for (let i = rawSpec.length - 2; i >= 0 && rawSpec[i] === "\\"; i--) {
+    backslashes++;
+  }
+  return backslashes % 2 === 0;
+}
+
+export function containsBareDoubleCompactPipe(rawSpec: string): boolean {
+  let escaping = false;
+  let prevBarePipe = false;
+  for (const character of rawSpec) {
+    if (escaping) {
+      escaping = false;
+      prevBarePipe = false;
+      continue;
+    }
+    if (character === "\\") {
+      escaping = true;
+      prevBarePipe = false;
+      continue;
+    }
+    if (character === "|") {
+      if (prevBarePipe) {
+        return true;
+      }
+      prevBarePipe = true;
+      continue;
+    }
+    prevBarePipe = false;
+  }
+  return false;
+}
+
+export function describeCompactPipeIssue(rawSpec: string): string {
+  const doublePipe = containsBareDoubleCompactPipe(rawSpec);
+  const trailingPipe = endsWithBareCompactPipe(rawSpec);
+  if (doublePipe && trailingPipe) {
+    return "Spec has bare `||` and ends with a trailing `|`. `||` (logical-OR or back-to-back pipes) adds two extra fields per occurrence; a trailing `|` creates an empty final field. Escape literal pipes as `\\|` or rephrase (e.g. `||` -> `or`), and drop the trailing `|`.";
+  }
+  if (doublePipe) {
+    return "Spec has bare `||` (two pipes back-to-back) — common with JS logical-OR (`a || b`) or shell OR (`cmd a || cmd b`). Every unescaped `|` adds a field, so `||` adds two extra fields. Escape literal pipes as `\\|` or rephrase the operator (e.g. `||` -> `or`).";
+  }
+  if (trailingPipe) {
+    return "Spec ends with a bare `|`. The trailing `|` is not a terminator — it creates an empty final field. Drop the trailing `|`.";
+  }
+  return "Bare `|` inside a field value is a field separator. Escape literal pipes as `\\|` or rephrase the value to avoid `|`.";
+}
+
 export function parseCompactEntityRef(rawValue: string): CompactEntityRef {
   if (rawValue.startsWith(COMPACT_TEMP_KEY_PREFIX)) {
     const tempKey = rawValue.slice(COMPACT_TEMP_KEY_PREFIX.length);

package/src/commands/epic.ts

@@ -1,5 +1,7 @@
 import {
   SEARCH_REPLACE_FIELDS,
+  describeCompactPipeIssue,
+  endsWithBareCompactPipe,
   findUnknownOption,
   hasFlag,
   isValidCompactTempKey,
@@ -397,7 +399,11 @@ function failUnexpectedPositionals(command: string, unexpected: readonly string[
 
 function failEmptyCompactField(command: string, option: string, index: number, rawSpec: string, field: string): CliResult {
   const label = option === "task" ? "Task" : "Subtask";
-  return failBatchSpec(command, `${label} spec ${index + 1} is missing a ${field}.`, {
+  let human = `${label} spec ${index + 1} is missing a ${field}.`;
+  if (field === "description" && endsWithBareCompactPipe(rawSpec)) {
+    human += " Spec ends with a bare `|` — the trailing `|` is not a terminator and creates an empty description field. Drop the trailing `|` and write an actual description.";
+  }
+  return failBatchSpec(command, human, {
     option,
     index,
     rawSpec,
@@ -465,7 +471,7 @@ function parseExpandTaskSpecs(rawSpecs: readonly string[]): { specs: CompactTask
     if (parsed.fields.length !== 3 && parsed.fields.length !== 4) {
       return {
         specs: [],
-        error: failBatchSpec("epic.expand", `Task specs must use <temp-key>|<title>|<description> or <temp-key>|<title>|<description>|<status> in --task spec ${index + 1}.`, {
+        error: failBatchSpec("epic.expand", `Task specs must use <temp-key>|<title>|<description> or <temp-key>|<title>|<description>|<status> in --task spec ${index + 1}. ${describeCompactPipeIssue(rawSpec)}`, {
           option: "task",
           index,
           rawSpec,
@@ -561,7 +567,7 @@ function parseExpandSubtaskSpecs(rawSpecs: readonly string[]): { specs: CompactS
     if (parsed.fields.length !== 4 && parsed.fields.length !== 5) {
       return {
         specs: [],
-        error: failBatchSpec("epic.expand", `Subtask specs must use <parent-ref>|<temp-key>|<title>|<description> or <parent-ref>|<temp-key>|<title>|<description>|<status> in --subtask spec ${index + 1}.`, {
+        error: failBatchSpec("epic.expand", `Subtask specs must use <parent-ref>|<temp-key>|<title>|<description> or <parent-ref>|<temp-key>|<title>|<description>|<status> in --subtask spec ${index + 1}. ${describeCompactPipeIssue(rawSpec)}`, {
           option: "subtask",
           index,
           rawSpec,
@@ -776,7 +782,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
 
         const duplicateTempKey = findDuplicateExpandTempKey(parsedTasks.specs, parsedSubtasks.specs);
         if (duplicateTempKey !== null) {
-          return failBatchSpec("epic.create", `Duplicate temp key '${duplicateTempKey}' across --task and --subtask specs.`, {
+          return failBatchSpec("epic.create", `Duplicate temp key '${duplicateTempKey}' across --task and --subtask specs. Temp keys share one flat namespace per epic create — prefix subtask temp keys with the parent task key (e.g. sub-<task-key>-tests) to disambiguate.`, {
             tempKey: duplicateTempKey,
           });
         }
@@ -849,7 +855,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
 
         const duplicateTempKey = findDuplicateExpandTempKey(parsedTasks.specs, parsedSubtasks.specs);
         if (duplicateTempKey !== null) {
-          return failBatchSpec("epic.expand", `Duplicate temp key '${duplicateTempKey}' across --task and --subtask specs.`, {
+          return failBatchSpec("epic.expand", `Duplicate temp key '${duplicateTempKey}' across --task and --subtask specs. Temp keys share one flat namespace per epic expand — prefix subtask temp keys with the parent task key (e.g. sub-<task-key>-tests) to disambiguate.`, {
             tempKey: duplicateTempKey,
           });
         }

package/src/commands/help.ts

@@ -126,7 +126,9 @@ const EPIC_HELP = [
   "  --task <temp-key>|<title>|<description>|<status>   (explicit status)",
   `  --subtask <parent-ref>|<temp-key>|<title>|<description>            (status defaults to todo) (${"@"}<temp-key> for new parents)`,
   `  --subtask <parent-ref>|<temp-key>|<title>|<description>|<status>   (explicit status)`,
+  "  Temp keys in --task and --subtask share one namespace per command. Prefix subtask keys with parent task key.",
   `  --dep <source-ref>|<depends-on-ref>  (refs can be IDs or ${"@"}<temp-key>)`,
+  "  Escape literal | inside field values (\\|); bare | is a field separator and will silently corrupt records.",
   "  Escapes in compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
   "",
   "List:",

package/src/commands/quickstart.ts

@@ -88,7 +88,30 @@ const QUICKSTART_TEXT = [
   "  field/value details; batch prompts use a count-only confirmation (30s",
   "  timeout, defaults to reject).",
   "",
-  "8) Wipe (destructive recovery only)",
+  "8) Batch planning with compact specs",
+  "  One-shot create:  trekoon --toon epic create --title \"...\" --description \"...\" \\",
+  "                      --task \"<temp-key>|<title>|<description>\" \\",
+  "                      --subtask \"@<task-temp-key>|<temp-key>|<title>|<description>\" \\",
+  "                      --dep \"@<source>|@<depends-on>\"",
+  "  Status is optional; append |<status> only when seeding non-todo.",
+  "  Temp keys (--task and --subtask) share one flat namespace per command; prefix",
+  "  subtask keys with the parent task key (e.g. sub-<task-key>-tests).",
+  "",
+  "  Compact specs split on raw |. CAUTION — three bare-pipe footguns:",
+  "    a) Single mid-value | with no explicit |<status>: trailing text silently",
+  "       lands in the status slot. e.g. `Verify: bun test foo | tail` makes",
+  "       \" tail\" the status; creation succeeds, fails on next transition.",
+  "    b) || (JS logical-OR or shell OR) adds two extra fields per occurrence and",
+  "       overshoots the field-count gate (Task/Subtask specs must use ...).",
+  "       Rephrase as \"or\" or escape as \\|\\|.",
+  "    c) Trailing | is NOT a terminator. It creates an empty final field; on a",
+  "       4-field subtask shape that becomes an empty description and the parser",
+  "       rejects with \"is missing a description\". Drop trailing pipes.",
+  "  Escape literal | as \\|. Pre-flight specs before submitting:",
+  "    grep -nE '(^|[^\\\\])\\|\\||\\|$' specs.txt",
+  "  Full rules: .agents/skills/trekoon/reference/planning.md (CAUTION block).",
+  "",
+  "9) Wipe (destructive recovery only)",
   "  trekoon wipe --yes",
   "  Removes the shared .trekoon directory for every worktree in the repo.",
   "  Don't use this for routine cleanup, sync fixes, or gitignore issues.",

package/src/commands/subtask.ts

@@ -1,5 +1,7 @@
 import {
   SEARCH_REPLACE_FIELDS,
+  describeCompactPipeIssue,
+  endsWithBareCompactPipe,
   findUnknownOption,
   hasFlag,
   isValidCompactTempKey,
@@ -249,7 +251,11 @@ function failConflictingTaskIds(optionTaskId: string, positionalTaskId: string):
 }
 
 function failEmptyCompactField(command: string, option: string, index: number, rawSpec: string, field: string): CliResult {
-  return failBatchSpec(command, `${option === "subtask" ? "Subtask" : "Spec"} spec ${index + 1} is missing a ${field}.`, {
+  let human = `${option === "subtask" ? "Subtask" : "Spec"} spec ${index + 1} is missing a ${field}.`;
+  if (field === "description" && endsWithBareCompactPipe(rawSpec)) {
+    human += " Spec ends with a bare `|` — the trailing `|` is not a terminator and creates an empty description field. Drop the trailing `|` and write an actual description.";
+  }
+  return failBatchSpec(command, human, {
     option,
     index,
     rawSpec,
@@ -289,7 +295,7 @@ function parseSubtaskCreateManySpecs(parentTaskId: string, rawSpecs: readonly st
     if (parsed.fields.length !== 3 && parsed.fields.length !== 4) {
       return {
         specs: [],
-        error: failBatchSpec("subtask.create-many", `Subtask specs must use <temp-key>|<title>|<description> or <temp-key>|<title>|<description>|<status> in --subtask spec ${index + 1}.`, {
+        error: failBatchSpec("subtask.create-many", `Subtask specs must use <temp-key>|<title>|<description> or <temp-key>|<title>|<description>|<status> in --subtask spec ${index + 1}. ${describeCompactPipeIssue(rawSpec)}`, {
           option: "subtask",
           index,
           rawSpec,

package/src/commands/task.ts

@@ -1,5 +1,7 @@
 import {
   SEARCH_REPLACE_FIELDS,
+  describeCompactPipeIssue,
+  endsWithBareCompactPipe,
   findUnknownOption,
   hasFlag,
   isValidCompactTempKey,
@@ -338,7 +340,11 @@ function failUnexpectedPositionals(command: string, unexpected: readonly string[
 }
 
 function failEmptyCompactField(command: string, option: string, index: number, rawSpec: string, field: string): CliResult {
-  return failBatchSpec(command, `${option === "task" ? "Task" : "Spec"} spec ${index + 1} is missing a ${field}.`, {
+  let human = `${option === "task" ? "Task" : "Spec"} spec ${index + 1} is missing a ${field}.`;
+  if (field === "description" && endsWithBareCompactPipe(rawSpec)) {
+    human += " Spec ends with a bare `|` — the trailing `|` is not a terminator and creates an empty description field. Drop the trailing `|` and write an actual description.";
+  }
+  return failBatchSpec(command, human, {
     option,
     index,
     rawSpec,
@@ -378,7 +384,7 @@ function parseTaskCreateManySpecs(rawSpecs: readonly string[]): { specs: Compact
     if (parsed.fields.length !== 3 && parsed.fields.length !== 4) {
       return {
         specs: [],
-        error: failBatchSpec("task.create-many", `Task specs must use <temp-key>|<title>|<description> or <temp-key>|<title>|<description>|<status> in --task spec ${index + 1}.`, {
+        error: failBatchSpec("task.create-many", `Task specs must use <temp-key>|<title>|<description> or <temp-key>|<title>|<description>|<status> in --task spec ${index + 1}. ${describeCompactPipeIssue(rawSpec)}`, {
           option: "task",
           index,
           rawSpec,