trekoon 0.4.6 → 0.4.7

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

@@ -139,6 +139,25 @@ 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 `|`.
+
 Spec shape (status optional, defaults to `todo`):
 
 - `--task <temp-key>|<title>|<description>` or `<temp-key>|<title>|<description>|<status>`
@@ -150,8 +169,13 @@ non-`todo` status.
 
 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,15 @@ 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 `\|`. 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.
+
 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.7",
   "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/epic.ts

@@ -776,7 +776,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 +849,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:",