trekoon 0.4.7 → 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

@@ -158,6 +158,11 @@ fires on a different shape — a single bare middle pipe like
 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>`
@@ -167,6 +172,12 @@ 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-api-tests`.

package/docs/quickstart.md

@@ -100,7 +100,19 @@ trekoon --toon epic create \
 
 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 `\|`. A bare `|` on a spec without an explicit `|<status>` field 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. See the planning skill for full rules.
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.4.7",
+  "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,

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,