hiiro 0.1.367 → 0.1.368

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +18 -0
  3. data/README.md +36 -48
  4. data/bin/h-alias +28 -0
  5. data/bin/h-env +25 -0
  6. data/bin/h-herdr +156 -0
  7. data/docs/h-herdr.md +41 -0
  8. data/docs/h-task.md +13 -170
  9. data/docs/h.md +1 -0
  10. data/docs/t.md +91 -388
  11. data/docs/why-t.md +21 -23
  12. data/herdr-plugin/herdr-plugin.toml +47 -0
  13. data/lib/hiiro/current_task.rb +3 -3
  14. data/lib/hiiro/task_cli.rb +279 -162
  15. data/lib/hiiro/version.rb +1 -1
  16. data/lib/hiiro.rb +0 -1
  17. metadata +6 -2
  18. data/lib/hiiro/task_scope.rb +0 -51
data/docs/t.md CHANGED
@@ -1,437 +1,140 @@
1
1
  # t command reference
2
2
 
3
- Reference for the `t` executable and `tt` todo shortcut.
3
+ Reference for the `t` executable, the `tt` todo shortcut, and `h task`, which is a symlink to `t`.
4
4
 
5
- `t` manages task records, next actions, todos, waiting-on information, documents, resource references, git worktrees, and task-associated Herdr terminals. `h task` is a symlink to the same executable.
6
-
7
- `exe/t` and `exe/tt` are gem executables installed with Hiiro. Each is a `Hiiro.run` launcher that calls `Hiiro::TaskCli.setup` or `Hiiro::TaskCli.setup_todo`; the command declarations and `Hiiro::TaskCli::Commands` helpers live in `lib/hiiro/task_cli.rb`. `bin/t` and `bin/tt` are symlinks to the `exe/` files. Expected failures raise `Hiiro::Error` and print only `ERROR: message` on stderr with exit status 1.
5
+ `t` manages task records, next actions, todos, waiting-on information, documents, resource references, git worktrees, and task-associated Herdr terminals. `exe/t` and `exe/tt` are gem executables that call `Hiiro::TaskCli.setup` and `Hiiro::TaskCli.setup_todo` from `Hiiro.run`; the commands and `Hiiro::TaskCli::Commands` helpers live in `lib/hiiro/task_cli.rb`. Expected failures raise `Hiiro::Error` and print only `ERROR: message` on stderr with exit status 1.
8
6
 
9
7
  ## Syntax and task selection
10
8
 
11
9
  ```text
12
- t
13
- t help
14
- t TASK [COMMAND...]
15
- t TASK GROUP [COMMAND...]
16
- tt TASK [COMMAND...]
17
- ```
18
-
19
- Uppercase words are values to supply. Square brackets indicate optional arguments, and `...` means multiple words or arguments.
20
-
21
- Bare `t`, `t ls`, and `t list` list every task, including active, waiting, done, and archived records, in aligned columns: name with the open todo count in parentheses (omitted when zero), status, then any `next:` and `waiting:` text. Open todos are those not done or skipped. The listing does not select from context. `t TASK` shows the selected task. Only exact root `t help` displays generic usage and native scoped help without task lookup. Other first words are task references, including `new`, `show`, `edit`, `pry`, and `he`. Only `help`, `ls`, and `list` are reserved root words; a task named `ls` or `list` must be reached by a unique prefix such as `t lis`. There are no root `add`, `rm`, `new`, or `show` actions.
22
-
23
- Named references prefer an exact task name, then a unique case-sensitive prefix. Ambiguous prefixes fail. Unknown names fail except for `t NAME new` and `t NAME todo add TEXT...`. Explicit `new` creates exactly `NAME`, without resolving it as a prefix of another task. Help never creates a task.
24
-
25
- ```bash
26
- t fix-checkout new
27
- t fix-checkout
28
- t fix-checkout next 'Inspect the failing request'
29
- t fix-checkout directory add ~/proj/store --primary
30
- t fix-checkout doc new investigation 'Checkout findings'
31
- t fix-checkout pane run PANE_ID -- git status --short
10
+ t list tasks
11
+ t COMMAND [TASK] [ARGS...] run a command, optionally naming the task first
12
+ t GROUP SUBCOMMAND [TASK] [ARGS...]
13
+ tt [SUBCOMMAND] [TASK] [ARGS...] same as t todo ...
32
14
  ```
33
15
 
34
- ### Current and orphan references
35
-
36
- Use `.` for the current task, including commands with payload arguments:
37
-
38
- ```bash
39
- t . current
40
- t . next 'Inspect the request'
41
- t . todo add Compare retry settings
42
- ```
43
-
44
- Current-task selection uses the first matching priority:
45
-
46
- 1. A task whose normalized workspace label matches the calling Herdr workspace.
47
- 2. A task whose home, primary code directory, fallback worktree, or registered directory contains the current working directory. Paths resolve through symlinks.
48
- 3. The saved task.
16
+ The command comes first. Commands that act on a task take it from the first positional argument using the old `h task` rule:
49
17
 
50
- Workspace context overrides a conflicting current directory. Multiple matches at the same priority are errors. In Herdr, selection uses `HERDR_WORKSPACE_ID`, the workspace of `HERDR_PANE_ID`, or the current workspace when only `HERDR_ENV=1` is available. Invalid, stale, or conflicting Herdr IDs are errors, not reasons to fall back. Herdr context requires a running server. Outside Herdr, an unrelated focused workspace does not affect selection. A named reference bypasses context lookup.
51
-
52
- `t TASK current` prints the resolved name and saves a named selection's ID without focusing a terminal. `t . current` only prints the name. A successful named `t TASK workspace` or `t TASK switch` also saves the selection. Reads, `--show` inspection, and opens through `.` do not replace the saved fallback. A stale saved ID or unresolved `.` is an error.
53
-
54
- `-` selects orphan todos only: `t - todo`, `t - todo add TEXT...`, or `t - todo rm ID`. It is invalid outside the todo scope and never creates a task.
55
-
56
- ### Options and literal arguments
57
-
58
- For ordinary task commands, place options after the leaf command. Use `--` to stop option parsing:
59
-
60
- ```bash
61
- t . next -- --flag-is-literal-text
62
- t fix-checkout pane run PANE_ID -- git status --short
63
- ```
64
-
65
- The current parser silently ignores unknown long options. Unknown short options may remain positional or be partially interpreted if a character matches a known short option. Do not rely on misspelled options producing an error. Leaf help lists accepted flags.
66
-
67
- Todo `add` and AI commands have different argument handling. Every argument after `todo add` is literal text, except that leading `add -h` or `add --help` displays help. Flags later in the text, including `--help`, `--clear`, and `--`, remain literal:
68
-
69
- ```bash
70
- t fix-checkout todo add Check --help and --clear handling
71
- ```
18
+ 1. If the first positional word names a task, exactly or by a unique case-sensitive prefix, it is the task and is removed from the arguments.
19
+ 2. Otherwise the current task is used and the word stays in the payload. So `t todo add fix build` adds to the current task and `t todo add prez fix build` adds to `prez`.
20
+ 3. An ambiguous prefix is an error rather than a guess.
72
21
 
73
- AI arguments pass unchanged to the native CLI, apart from a first-argument resume selector described below. `--help` and `--` are tool arguments, not `t` options.
22
+ `-t TASK` / `--task TASK` forces a task and fails if it does not exist. `-f` / `--find` picks one with `sk` or `fzf`. `.` is the current task, useful when a payload could be mistaken for a name: `t next . Finish slides`. `-` selects orphan todos in todo commands only. Words starting with `-` are never treated as task names. Passthrough commands (`todo add`, `sh`, `pane run`, and the AI launchers) accept `-t`, `--task=NAME`, and `-f` only as their leading arguments.
74
23
 
75
- ## Task data and storage
24
+ The current task is resolved by `Hiiro::CurrentTask`: the calling Herdr workspace when `HERDR_*` variables identify one, then the working directory inside a task home, primary directory, worktree, or registered directory, then the task saved by `t use`. Ambiguous matches and stale or conflicting Herdr IDs are errors. Commands that only list, create, or show help never resolve the current task.
76
25
 
77
- A task can represent coding work, an investigation, or administrative work. It does not require a Git repository.
78
-
79
- | Data | Location or meaning |
80
- |---|---|
81
- | Task records | `tasks` table in `~/.config/hiiro/hiiro.db` |
82
- | Resource references | `task_resources` table in the same database |
83
- | Task and orphan todos | Existing `todos` table, shared with `h todo` |
84
- | Task home | `~/notes/work/NAME` for names created by `t NAME new` or an unmatched named `todo add` |
85
- | Documents and other home files | Files on disk beneath the task home |
86
- | `primary_directory` | Explicit default code directory for terminal creation |
87
- | `tree` | Existing `h task` worktree association; `t NAME new` leaves it unset |
88
- | `session` | Existing workspace label source; task creation sets it to the task name |
89
- | Herdr tab and pane IDs | Looked up live, not saved as durable task identity by `t` |
90
- | Saved task | `PinRecord` with `command='t'`, `key='current_task'`, and a JSON integer task ID in `value_json` |
91
-
92
- The task home is computed, and resources are separate database rows. `t` and `h task` share task records. `h task` also maintains a YAML backup through its configuration code. `t` writes directly to the database and does not refresh that backup or `todo.yml`.
93
-
94
- New names must be 1–120 ASCII letters, digits, dots, underscores, or hyphens, starting with a letter or digit. `t NAME new` does not accept slash-separated subtask names. Existing records with other characters remain selectable by exact name; their computed home directory percent-encodes those characters.
95
-
96
- ## Option catalog
97
-
98
- Options are scoped to commands, not universally available. `TASK` may be a name, prefix, or `.` unless stated otherwise.
99
-
100
- | Long option | Short | Value and default | Used by | Effect |
101
- |---|---|---|---|---|
102
- | `--help` | `-h` | Boolean | Ordinary leaf actions; leading todo `add` argument only | Prints selected options without running the action; AI commands instead forward it to the tool |
103
- | `--clear` | `-c` | Boolean, false | `t TASK next`, `t TASK waiting` | Clears the corresponding text; cannot be combined with text |
104
- | `--primary` | `-p` | Boolean, false | `t TASK directory add` | Makes this directory the default code directory |
105
- | `--label` | None | String, unset | Directory, link, PR, and file `add` | Sets a resource label for display and exact selection |
106
- | `--kind` | None | `general`, `issue`, or `thread`; add defaults to `general` | `t TASK link add`, `list`, `ls`, `open` | Chooses the stored link kind or filters links |
107
- | `--directory` | None | Existing directory; otherwise precedence below | `t TASK workspace`, `switch`, `tab new`, `pane split` | Overrides the new terminal's start directory for this operation |
108
- | `--command` | None | Shell command string, unset | `t TASK tab new`, `t TASK pane split` | Sends a command to the new terminal |
109
- | `--direction` | None | `right` or `down`; default `right` | `t TASK pane split` | Chooses split direction |
110
- | `--show` | `-s` | Boolean, false | `t TASK workspace`, `t TASK switch` | Inspects without creating, focusing, or saving |
111
-
112
- `--command` has no `-c` alias, and neither `--directory` nor `--direction` has a `-d` alias. Boolean flags do not take `true` or `false` values. Bare `t` includes all statuses without an `--all` option.
26
+ Task names may be `parent/child` for subtasks. `t new NAME` creates exactly `NAME`; nothing else creates tasks. Only `help`, `ls`, and `list` are reserved words; a task literally named `show` or `new` is reachable with `-t show`.
113
27
 
114
28
  ## Task record commands
115
29
 
116
30
  | Command | Behavior |
117
31
  |---|---|
118
- | `t`, `t ls`, or `t list` | Lists all tasks alphabetically with open todo counts, regardless of status or context |
119
- | `t TASK` or `t TASK show` | Shows status, home, next action, todos, waiting text, code directory, workspace label, resources, and home Markdown documents |
120
- | `t TASK current` | Prints the resolved name; named references also save the fallback without changing focus |
121
- | `t NAME new` | Creates an active task and notes home; an exact existing name preserves its record and ensures the home exists |
122
- | `t TASK next [TEXT...]` | Stores text, prints it with no text, or removes it with `--clear` |
123
- | `t TASK waiting [TEXT...]` | Stores blocking text and sets waiting status; prints with no text; clears with `--clear` |
124
- | `t TASK status [STATE]` | Prints status or sets `active`, `waiting`, `done`, or `archived` |
125
- | `t TASK path` | Prints the start directory: primary directory, worktree, or task home |
126
- | `t TASK branch` | Prints the worktree's git branch, or `(detached)` |
127
- | `t TASK sh [CMD...]` | Changes to the start directory and execs a shell or the command |
128
- | `t TASK cd` | Sends `cd` to the current Herdr pane (requires `HERDR_PANE_ID`) |
129
- | `t TASK tree` | Prints the worktree name and path; fails when the task has none |
130
- | `t NAME tree new [--app APP] [--sparse GROUP]` | Creates the task if needed, creates or reuses a worktree under `~/work/NAME/main` (or `~/work/parent/child` for a subtask), records it, and opens the workspace when Herdr is running |
131
- | `t TASK tree rm` | Detaches the worktree from the task and its subtasks, keeping the directory and registering it as a directory resource |
132
- | `t TASK tree resume [TREE]` | Attaches an unassigned worktree by name, or via fuzzyfind with no name |
133
- | `t TASK done` | Sets status to done |
134
- | `t TASK archive` | Sets status to archived |
135
-
136
- List rows contain tab-separated name, status, next action, and waiting text. Unset fields are omitted rather than emitted as empty columns, so this is not a fixed-width TSV export schema. There is no JSON output option.
137
-
138
- ### State transitions
139
-
140
- | Operation | Status effect | Other data changes |
141
- |---|---|---|
142
- | `t NAME new` for a new name | `active` | Initializes timestamps; no worktree association |
143
- | `t TASK next TEXT...` or `t TASK next --clear` | Unchanged | Updates or clears next-action text |
144
- | `t TASK waiting TEXT...` | `waiting` | Stores waiting text and clears completion/archive timestamps |
145
- | `t TASK waiting --clear` | `waiting` becomes `active`; other statuses unchanged | Clears waiting text |
146
- | `t TASK status active` | `active` | Clears completion/archive timestamps; preserves next-action and waiting text |
147
- | `t TASK status waiting` | `waiting` | Clears completion/archive timestamps; does not create waiting text |
148
- | `t TASK done` or `t TASK status done` | `done` | Sets completion time if missing and clears archive time |
149
- | `t TASK archive` or `t TASK status archived` | `archived` | Sets archive time if missing; preserves completion time |
150
-
151
- Mutations update `updated_at`. Legacy records with no stored status are treated as active. Reading a field does not update task metadata.
152
-
153
- Completion and archival do not delete todos or files, remove resources, stop commands, close terminals, detach worktrees, or alter Git state. Next-action and waiting text remain unless explicitly cleared. Completed and archived records remain in bare `t` output.
154
-
155
- ## Task todos and tt
156
-
157
- A task can have multiple todos and one independent `next_action`. Adding or removing a todo does not change the next action, task status, or saved selection. There is no todo-completion command or automatic promotion to `next_action`.
158
-
159
- | Command | Behavior |
160
- |---|---|
161
- | `t TASK todo` | Lists todos in the selected scope |
162
- | `t TASK todo list` or `t TASK todo ls` | Same as the default todo action |
163
- | `t TASK todo add TEXT...` | Adds one `not_started` todo; creates an unknown named task if needed |
164
- | `t TASK todo rm ID` | Deletes that exact decimal database ID from the selected scope |
165
- | `tt TASK ...` | Delegates to `t TASK todo ...` |
166
- | `tt` | Delegates to `t . todo` |
167
- | `tt help` | Shows todo help without task lookup |
168
- | `t - todo` or `tt -` | Lists orphan todos; the same `add` and `rm` commands apply |
169
-
170
- ```bash
171
- t fix-checkout todo add Reproduce the payment failure
172
- t fix-check todo add Inspect --help output
173
- t fix-checkout todo
174
- tt fix-checkout rm 42
175
- tt - add Buy printer paper
176
- ```
177
-
178
- The prefix example assumes `fix-checkout` is the only match. `42` must be an ID printed by task display or todo listing, not a list position.
179
-
180
- `add` joins its text arguments with spaces. Missing, empty, or whitespace-only text fails before task creation. An unmatched named task follows the same validation and home rules as `t NAME new`. Task and todo database writes use one immediate SQLite transaction, so failed insertion does not leave a new task record.
181
-
182
- New task todos store the resolved task's full name in `task_name`, with `subtask_name` unset. Orphan todos leave both unset. Association uses `TodoItem.full_task_name` exactly, including legacy rows that combine `task_name` and `subtask_name`. A parent task does not include its subtasks' todos.
183
-
184
- `rm` requires exactly one decimal ID. Missing, invalid, or extra arguments fail. IDs are not suffix matches. An ID belonging to another task or the orphan scope cannot be removed through the wrong scope. Listing prints IDs, statuses, and text in ID order. `show` prints items as `Todo ID [STATUS]: TEXT`.
32
+ | `t`, `t ls`, `t list` | Lists all tasks alphabetically with open todo counts, e.g. `prez (3)`, plus `next:` and `waiting:` text |
33
+ | `t show [TASK]` | Status, home, next action, waiting text, code directory, workspace label, resources, documents, and todos |
34
+ | `t current [TASK]` | Prints the resolved task name; never saves |
35
+ | `t use TASK` (alias `pin`) | Saves TASK as the fallback for when no workspace or directory identifies a task |
36
+ | `t new NAME` | Creates an active task and its notes home under `~/notes/work/NAME`; an existing exact name is preserved |
37
+ | `t next [TASK] [TEXT...] [--clear]` | Stores, prints, or clears the next action |
38
+ | `t waiting [TASK] [TEXT...] [--clear]` | Stores blocking text and sets `waiting`; clearing returns a waiting task to `active` |
39
+ | `t status [TASK] [STATE]` | Prints or sets `active`, `waiting`, `done`, or `archived` |
40
+ | `t done [TASK]`, `t archive [TASK]` | Sets the status, recording `completed_at` or `archived_at` |
185
41
 
186
- These commands share the existing `todos` table with `h todo`. They insert or delete only the requested row and do not refresh `todo.yml`. Completion and archival preserve every todo. The separate `h task` and `h todo` commands are unchanged.
42
+ `done` and `archived` preserve todos, resources, and documents. Setting a status other than done or archived clears those timestamps.
187
43
 
188
- ## Directory references
44
+ ## Todos and tt
189
45
 
190
- | Command | Alias | Options | Behavior |
191
- |---|---|---|---|
192
- | `t TASK directory add PATH` | None | `--label LABEL`, `--primary`, `-p` | Registers an existing directory; optionally makes it the default code directory |
193
- | `t TASK directory list` | `t TASK directory ls` | None | Lists directory references |
194
- | `t TASK directory open [REFERENCE]` | None | None | Opens the selected directory in the OS default application |
195
-
196
- Attaching a directory does not create, move, or copy it, create a worktree, or change sparse checkout. Its canonical absolute path is stored. `directory open` does not change the invoking shell's directory or open a terminal. Replacing the primary directory preserves previous references. No command removes a directory reference or clears `primary_directory`.
197
-
198
- ## Links and pull requests
199
-
200
- | Command | Alias | Options | Behavior |
201
- |---|---|---|---|
202
- | `t TASK link add URL` | None | `--label LABEL`, `--kind KIND` | Stores a general, issue, or thread link; defaults to general |
203
- | `t TASK link list` | `t TASK link ls` | `--kind KIND` | Lists general, issue, thread, and PR resources when unfiltered |
204
- | `t TASK link open [REFERENCE]` | None | `--kind KIND` | Opens the uniquely selected link |
205
- | `t TASK pr add URL` | None | `--label LABEL` | Stores a PR resource |
206
- | `t TASK pr list` | `t TASK pr ls` | None | Lists PR resources |
207
- | `t TASK pr open [REFERENCE]` | None | None | Opens the uniquely selected PR URL |
208
-
209
- URLs must be absolute HTTP or HTTPS URLs with a host. PR registration does not validate a provider-specific URL, contact GitHub, inspect review status, or create a pull request. `--kind pr` is not accepted by link commands. Use `t TASK pr list` or `t TASK pr open` for a PR-only view. Unfiltered link listing and opening include PRs.
210
-
211
- ## File references
212
-
213
- | Command | Alias | Options | Behavior |
214
- |---|---|---|---|
215
- | `t TASK file add PATH` | None | `--label LABEL` | Registers an existing file by canonical absolute path |
216
- | `t TASK file list` | `t TASK file ls` | None | Lists registered files and recursively discovers task-home files |
217
- | `t TASK file open [REFERENCE]` | None | None | Opens a registered or discovered file in the OS default application |
46
+ | Command | Behavior |
47
+ |---|---|
48
+ | `t todo [TASK]`, `t todo ls [TASK] [--plain]` | Lists todos as `Todo ID [STATUS]: TEXT`; `--plain` prints text only |
49
+ | `t todo add [TASK] TEXT...` | Adds a todo; every word after the task is literal text, including flags and `--` |
50
+ | `t todo show [TASK] ID` | Prints only the text of one todo |
51
+ | `t todo rm [TASK] ID` | Deletes one todo by exact decimal ID |
52
+ | `t todo add - TEXT...`, `t todo -` | Orphan todos with no task |
53
+ | `tt ...` | Identical to `t todo ...`; bare `tt` lists the current task's todos |
218
54
 
219
- Adding a file does not copy or move it. Home discovery includes hidden files and Markdown documents. Files discovered only through the home do not acquire database resource IDs; their list output begins with `home`.
55
+ `todo add -h` or `--help`, before or immediately after the task, prints help instead of adding. Empty text fails. IDs must belong to the selected task or the orphan scope. Todos share the `todos` table with `h todo`; `t` never rewrites `todo.yml`.
220
56
 
221
- ### Resource identity and opening
57
+ ## Directory, link, PR, and file references
222
58
 
223
- - A stored resource is unique by task ID, kind, and target. Adding it again reuses the row. Supplying a label updates that row's label.
224
- - Printed IDs are database IDs, not list positions.
225
- - A registered `REFERENCE` can be its exact ID, stored target, or label. Relative attachment paths are not automatically equivalent to canonical stored paths when selecting a resource to open.
226
- - Home files also accept full paths, paths relative to the home, or an unambiguous basename.
227
- - Omitting `REFERENCE` succeeds only for one distinct target. Duplicate labels or basenames require a more specific selector.
228
- - Files and directories must still exist when opened. Completion and archival preserve references.
59
+ ```text
60
+ t directory add [TASK] PATH [--primary] [--label LABEL]
61
+ t directory ls [TASK]
62
+ t directory open [TASK] [ID|PATH|LABEL]
63
+ t link add [TASK] URL [--kind general|issue|thread] [--label LABEL]
64
+ t link ls [TASK] [--kind KIND]
65
+ t link open [TASK] [ID|URL|LABEL]
66
+ t pr add [TASK] URL [--label LABEL]
67
+ t pr ls [TASK]
68
+ t pr open [TASK] [ID|URL|LABEL]
69
+ t file add [TASK] PATH [--label LABEL]
70
+ t file ls [TASK]
71
+ t file open [TASK] [ID|PATH|LABEL]
72
+ ```
229
73
 
230
- Opening uses `open` on macOS or `xdg-open` elsewhere. There are no resource remove, unlink, or dedicated rename commands. Repeat `add` with `--label` to change a label.
74
+ Directories and files must exist and are stored as real paths. `--primary` sets the task's code directory and applies only to directories. URLs must be absolute http or https. `file ls` also lists unregistered files in the task home. `open` accepts an ID, full target, or label, then a unique prefix of any of them; with no reference and several candidates it opens a fuzzy finder. Opening uses `open` on macOS and `xdg-open` elsewhere.
231
75
 
232
76
  ## Documents
233
77
 
234
- | Command | Alias | Behavior |
235
- |---|---|---|
236
- | `t TASK doc new NAME [TITLE...]` | None | Creates a Markdown file in the task home with a heading |
237
- | `t TASK doc list` | `t TASK doc ls` | Lists Markdown files recursively under the home |
238
- | `t TASK doc open [NAME]` | None | Resolves a document and invokes `mdoc` to render/open it |
239
-
240
- Document names follow task-name character rules. One trailing `.md` is accepted and removed before constructing the filename. The title defaults to the name with underscores and hyphens replaced by spaces.
241
-
242
- For task ID 42, `t fix-checkout doc new investigation 'Checkout findings'` creates `~/notes/work/fix-checkout/task-42-investigation.md` with the heading `# Checkout findings`. Creation refuses to overwrite a file and does not open it automatically. The task-ID prefix reduces basename collisions in `mdoc` output.
243
-
244
- `doc open` accepts an exact absolute path, relative path, filename with or without `.md`, or short name without the task-ID prefix. An omitted name requires exactly one document. Existing home Markdown files are included without registration. An external Markdown file registered with `file add` does not become a `doc list` entry.
245
-
246
- `t TASK file open` uses the OS default application. `t TASK doc open` requires `mdoc` and its configuration; rendering may create HTML and update the `mdoc` index.
247
-
248
- ## Herdr workspaces
249
-
250
- A running Herdr server is required for workspace, tab, pane, and AI actions. `t` does not launch the server. Named non-Herdr data commands work independently of Herdr.
251
-
252
- | Command | Options | Behavior |
253
- |---|---|---|
254
- | `t TASK workspace` or `t TASK switch` | `--directory PATH` | Focuses the task workspace or creates and focuses it; saves a named selection only after success |
255
- | `t TASK workspace --show` or `t TASK switch --show` | None | Prints the workspace, tabs, and panes with directories without creating, focusing, or saving |
256
-
257
- `workspace` and `switch` are direct commands, not groups. Native abbreviation matching accepts `t TASK wor`. Workspace identity is an exact label match:
258
-
259
- ```js
260
- workspaceLabel = (task.session ?? task.name).replaceAll(".", "_")
78
+ ```text
79
+ t doc new [TASK] NAME [TITLE...]
80
+ t doc ls [TASK]
81
+ t doc open [TASK] [NAME]
261
82
  ```
262
83
 
263
- Tasks named `release.1` and `release_1` can collide. Workspace actions reject labels shared by multiple task records or multiple live workspaces. They do not select a fuzzy workspace match.
84
+ `doc new` creates `task-ID-NAME.md` in the task home with a heading and never overwrites. `doc open` runs `mdoc` on the matched file; NAME may be the short name, file name, or path.
264
85
 
265
- Opening an existing workspace only focuses it. `--directory` does not change an existing terminal's directory. Inspection and tab/pane actions require the workspace to be open already. AI commands can create a missing workspace.
86
+ ## Worktrees, paths, and shells
266
87
 
267
- ### Starting-directory precedence
268
-
269
- New workspaces, tabs, and split panes choose the first applicable directory:
270
-
271
- 1. The operation's `--directory PATH`, where supported.
272
- 2. The task's `primary_directory`.
273
- 3. Its existing `tree`, absolute as-is or relative to `~/work`.
274
- 4. The task home, creating the home if necessary.
275
-
276
- The chosen directory must exist. An invalid higher-priority path is an error, not a reason to try a lower-priority fallback. `--directory` is temporary and does not update task data. AI arguments do not supply wrapper directory options; they pass to the native tool.
277
-
278
- ## Herdr tabs and panes
279
-
280
- | Command | Alias | Options | Behavior |
281
- |---|---|---|---|
282
- | `t TASK tab list` | `t TASK tab ls` | None | Lists live tabs in the task workspace |
283
- | `t TASK tab new [LABEL]` | None | `--directory PATH`, `--command COMMAND` | Creates and focuses a tab; prints its ID |
284
- | `t TASK tab open REFERENCE` | None | None | Focuses the workspace and matching tab |
285
- | `t TASK pane list` | `t TASK pane ls` | None | Lists live panes in the task workspace |
286
- | `t TASK pane open REFERENCE` | None | None | Focuses the matching pane |
287
- | `t TASK pane read REFERENCE` | None | None | Prints recent unwrapped terminal text |
288
- | `t TASK pane run REFERENCE -- COMMAND...` | None | None | Shell-escapes arguments and submits them to the existing pane |
289
- | `t TASK pane split REFERENCE` | None | `--direction right\|down`, `--directory PATH`, `--command COMMAND` | Splits the pane and focuses the new pane |
88
+ | Command | Behavior |
89
+ |---|---|
90
+ | `t tree [TASK]` | Prints the worktree name and path |
91
+ | `t tree new [NAME] [--app APP] [--sparse GROUP]` | NAME may be an existing task, a new task to create, or omitted for the current task. Creates or reuses a worktree under `~/work/NAME/main` (or `~/work/parent/child`), records it, and opens the workspace when Herdr is running |
92
+ | `t tree rm [TASK]` | Detaches the worktree from the task and its subtasks; the directory stays and is registered as a directory resource |
93
+ | `t tree resume [TASK] [TREE]` | Attaches an unassigned worktree by name, or via fuzzy finder |
94
+ | `t path [TASK]` | Start directory: primary directory, worktree, or task home |
95
+ | `t branch [TASK]` | Worktree branch or `(detached)` |
96
+ | `t sh [TASK] [CMD...]` | Changes to the start directory and execs a shell or CMD |
97
+ | `t cd [TASK]` | Sends `cd` to the calling Herdr pane |
290
98
 
291
- References are exact live IDs or labels within the task workspace, not sidebar positions or prefixes. Duplicate labels require IDs. Do not store these IDs as permanent task identity. Every `tab new` creates another tab, even if the label exists. `pane read` does not expose Herdr's `--lines`, `--source`, or ANSI-format options.
99
+ Worktree creation is `Hiiro::TaskManager#create_tree`, shared with the legacy `h task start` code path.
292
100
 
293
- For `--command`, pass a shell command as one quoted string. For `pane run`, pass an executable and arguments; explicitly invoke a shell for shell operators:
101
+ ## Herdr workspaces, tabs, and panes
294
102
 
295
- ```bash
296
- t fix-checkout tab new tests --command 'bundle exec rake test'
297
- t fix-checkout pane split PANE_ID --direction down --command 'git status --short'
298
- t fix-checkout pane run PANE_ID -- git status --short
299
- t fix-checkout pane run PANE_ID -- zsh -lc 'git status --short && printf "finished\n"'
103
+ ```text
104
+ t switch [TASK] [--directory PATH] [--show] alias: workspace
105
+ t tab ls [TASK]
106
+ t tab new [TASK] [LABEL] [--directory PATH] [--command COMMAND]
107
+ t tab open [TASK] [ID|LABEL]
108
+ t pane ls [TASK]
109
+ t pane open [TASK] [ID|LABEL]
110
+ t pane read [TASK] [ID|LABEL]
111
+ t pane run [TASK] ID|LABEL [--] COMMAND...
112
+ t pane split [TASK] ID|LABEL [--direction right|down] [--directory PATH] [--command COMMAND]
300
113
  ```
301
114
 
302
- These commands do not wait for the submitted job or return its exit status. Creating a terminal does not prove its optional command succeeded. Use `pane read` to inspect output. The foreground program determines how submitted input is interpreted.
303
-
304
- Terminals stay open after commands finish and after task completion. There is no `--no-focus`, closing command, automatic cleanup, or process-stop command. `t` does not manage the `h-bg` workspace. Notification helpers run detached processes rather than creating `h-bg` tabs.
115
+ These require a running Herdr server. The workspace label is the task session or name with `.` replaced by `_`. `switch` focuses the existing workspace or creates it in the start directory (`--directory`, else primary directory, worktree, or home), and saves the task as the fallback when it was named explicitly. `--show` only prints the workspace, tabs, and panes. Tab and pane references match a live ID or label, then a unique prefix; with no reference and several candidates a fuzzy finder opens.
305
116
 
306
117
  ## Native AI sessions
307
118
 
308
- | Command | Alias | Native executable |
309
- |---|---|---|
310
- | `t TASK omp [ARGS...]` | None | `omp` |
311
- | `t TASK codex [ARGS...]` | `t TASK cdx` | `codex` |
312
- | `t TASK claude [ARGS...]` | `t TASK cld` | `claude` |
313
-
314
- Fresh sessions are the default. Each launch creates a focused tab named for the canonical tool in the task workspace, creating the workspace if needed. Arguments are shell-escaped for launch. Claude runs `claude`, never `omp`.
119
+ `t omp [TASK] [ARGS...]`, `t codex` / `cdx`, and `t claude` / `cld` create a new focused tab in the task workspace, creating the workspace if needed, and run the native tool with ARGS forwarded verbatim. A leading argument that is a prefix of `resume` turns into the tool's native resume flag; bare `resume` with exactly one running pane of that tool focuses it instead.
315
120
 
316
- Only the first tool argument can select resume mode. A nonempty prefix of `resume`, such as `r`, `res`, or `resume`, consumes that token. OMP and Claude then receive `--resume`; Codex receives its `resume` subcommand. No other token is reinterpreted.
121
+ ## Help
317
122
 
318
- With no arguments after the resume selector, the launcher looks for genuinely running instances of that tool in the supplied task workspace, using Herdr's `pane.agent` metadata rather than labels:
123
+ `t help` and `t GROUP help` print Hiiro's generated command list with argument names and options. `t COMMAND --help` prints that command's options. Help never resolves a task or writes anything.
319
124
 
320
- - One match: focus that pane.
321
- - Multiple matches: fail and report the IDs rather than choose one.
322
- - No matches: create a tab and launch the native resume picker.
125
+ ## Storage and side effects
323
126
 
324
- If any arguments remain after the selector, always create a new tab and pass them to the native resume command. An explicit session ID or options never cause an existing pane to be focused or their arguments to be discarded.
325
-
326
- ```bash
327
- t fix-checkout omp
328
- t fix-checkout codex 'Inspect the failing checkout test'
329
- t fix-checkout cld r
330
- t fix-checkout omp resume SESSION_ID
331
- t fix-checkout codex resume SESSION_ID --help
332
- t fix-checkout claude --help
333
- ```
334
-
335
- All other arguments, including `--help`, `--`, and native tool flags, pass unchanged. There is no wrapper `--new` or automatic last-session resume. `t` does not inject a model, permission flags, or continue flags. Native tools handle authentication, session IDs, and resume discovery; the launcher makes no auth or API requests.
336
-
337
- Live-pane lookup is workspace-scoped. Persisted sessions follow the native CLI's discovery rules and are not necessarily task-isolated when tasks share a directory. A chosen directory can be an existing worktree. The launcher does not create worktrees or change Git state, though the tool you launch can modify files or run commands.
338
-
339
- ## Help and command dispatch
340
-
341
- | Invocation | Behavior |
342
- |---|---|
343
- | `t` | Lists all tasks and statuses |
344
- | Exact root `t help` | Prints generic usage and native scoped help without task lookup |
345
- | `t TASK` | Shows the selected task |
346
- | `t TASK help` | Prints the task command table |
347
- | `t TASK GROUP help` | Prints that group's command table |
348
- | `t TASK COMMAND --help` | Prints ordinary leaf options without running the action |
349
- | `t TASK GROUP COMMAND --help` | Prints nested leaf options, subject to the todo `add` rule |
350
- | `tt help` | Prints todo help without task lookup |
351
- | `t TASK omp --help`, `codex --help`, or `claude --help` | Launches the native tool with its own help argument |
352
-
353
- Root `edit` and `pry` registrations are not exposed; those words remain task names. Native Hiiro command abbreviations apply inside task and todo scopes, not to root help. Each documented group `list` command has an `ls` alias. Use full names in scripts. Task-prefix selection is separate from command abbreviation matching.
354
-
355
- The launcher uses `run_child` to dispatch nested command scopes. This is the convenience form of `make_child(...).run`. `make_child` returns an unrun child; module-level `build_hiiro` methods are builders that return a child for their caller to run. An inline group does not need a separate builder. Child scopes inherit the bound `task_scope` resolver, so nested commands do not parse the task name again.
356
-
357
- `t` disables external-command discovery. Legacy `t-*` executables are not part of this command set, and `t` does not delegate to `h task`. Command errors produce a nonzero exit; successful terminal delivery does not report the remote job's exit status.
358
-
359
- Native Hiiro command-table help currently exits with status 1; ordinary leaf `--help` exits with status 0. This also applies to `t help` and `tt help`.
360
-
361
- ## Worktrees, branches, and sparse checkout
362
-
363
- Built-in task operations do not create, remove, move, or switch Git worktrees or branches. They do not enable, disable, or update sparse checkout.
364
-
365
- | Operation | Git/worktree effect |
366
- |---|---|
367
- | `t NAME new` | None; creates a record and notes home |
368
- | `t TASK todo add` or `rm` | None; unmatched named add also creates a task and home |
369
- | `t TASK directory add PATH --primary` | Stores an existing path; does not populate `tree` |
370
- | `t TASK workspace`, `switch`, `tab new`, `pane split` | Starts terminals in an existing directory; does not check out code |
371
- | `t TASK done` or `archive` | No checkout, worktree, file, or terminal changes |
372
- | `t TASK pr add URL` | Saves a URL; no GitHub or Git operation |
373
- | `t TASK pane run`, `--command`, or AI tools | The explicitly launched command or tool can change Git, files, or external systems |
374
-
375
- An existing sparse worktree retains its configuration. New terminals see the files already checked out there.
376
-
377
- ### Separate h task commands
378
-
379
- `h task` is registered by the Hiiro launcher and implemented in `lib/hiiro/tasks.rb`. It shares records with `t` but has a different command set and resolver.
380
-
381
- | Command | Existing behavior |
382
- |---|---|
383
- | `h task start TASK [APP] --sparse GROUP` | For a new coding task, reuses/moves an available worktree or creates a detached worktree, then applies sparse groups and opens/focuses Herdr |
384
- | `h task switch TASK [APP]` | Switches to an existing task workspace or creates it using the legacy task path |
385
- | `h task from PATH [TASK]` | Registers an existing worktree and switches to its task |
386
- | `h task sparse --list` or `-l` | Lists configured sparse groups |
387
- | `h task sparse` | Shows sparse-checkout paths for the current task's worktree |
388
- | `h task sparse GROUP...` | Applies configured groups to the current task's worktree |
389
- | `h task sparse --disable` or `-d` | Disables sparse checkout for the current task's worktree |
390
- | `h task stop [TASK]` | Detaches the task and subtasks from worktree associations; preserves records and retains old paths as directory references |
391
- | `h task resume [TREE]` | Associates an available worktree with a task and switches to it |
392
- | `h task prune` | Reports missing associations; default is dry-run |
393
- | `h task prune --force` or `-f` | Detaches missing associations without deleting task records |
394
-
395
- Sparse groups come from `~/.config/hiiro/sparse_groups.yml`. `start` accepts repeated `--sparse GROUP` or `-s GROUP`. The separate `sparse` command acts on the current legacy task and does not use `t` selection.
396
-
397
- - `h task start` uses the repository at `~/work/.git` and normally places a new top-level worktree at `~/work/TASK/main`. It can move an available worktree instead.
398
- - Starting an existing task with a resolved worktree and no sparse groups calls `disable_sparse_checkout`. Use `h task switch` to return without that `start` behavior.
399
- - Starting an existing task without a worktree switches to its home without automatically attaching a worktree.
400
- - `t TASK directory add PATH --primary` affects `t` terminal directories. The legacy resolver uses `tree` or home, not `primary_directory` as an equivalent worktree association.
401
- - `h task stop` is not `t TASK done`. Stopping detaches worktree associations; completing changes status. Neither closes all task terminals.
402
- - A retained directory reference does not reserve a detached worktree path against later legacy reuse.
403
-
404
- ## Side-effect summary
405
-
406
- | Category | Task database | Filesystem | Herdr or external application |
407
- |---|---|---|---|
408
- | Bare task list, show, metadata reads, `t . current` | Reads data; preserves saved fallback | May inspect home files | `.` selection may query Herdr |
409
- | Named `t TASK current` | Saves resolved task ID | No task file changes | No focus change |
410
- | New task | Creates record if absent | Ensures notes home | No workspace creation |
411
- | Todo add/remove | Inserts/deletes scoped row; unmatched named add creates task; preserves saved selection | New task ensures home; no `todo.yml` rewrite | `.` selection may query Herdr |
412
- | Metadata writes, done, archive | Updates metadata | No task file deletion | No terminal cleanup |
413
- | Resource add | Stores reference; may update label or primary directory | Checks paths; no copy/move | No terminal creation |
414
- | Resource open | Reads references | Checks existence | Launches OS opener |
415
- | Document new | Reads task | Ensures home and creates Markdown file | No terminal creation |
416
- | Document open | Reads task | `mdoc` may write output/index | Runs `mdoc` |
417
- | Workspace/tab/pane actions | Reads identity; successful named workspace/switch saves fallback | May ensure home | Queries, creates, focuses, reads, or sends commands; `--show` only queries |
418
- | AI launch/resume | Reads task identity | Native tool controls its own files | Creates workspace if needed; creates tab or focuses unique running pane |
419
-
420
- Hiiro also initializes its database and records CLI invocations. Reading task data does not guarantee that the entire database file remains unchanged.
127
+ Task rows live in the `tasks` table (`Hiiro::TaskRecord`), resources in `task_resources`, todos in `todos`, and the saved fallback in `pins` as `command='t'`, `key='current_task'`. Task homes are `~/notes/work/NAME` with `/` escaped. Hiiro also records every invocation. Only `new`, `tree new`, `doc new`, and `use` write outside their named target; reads never write.
421
128
 
422
129
  ## Source map
423
130
 
424
131
  | Source | Responsibility |
425
132
  |---|---|
426
- | `exe/t`, `exe/tt` | Gem executables; `Hiiro.run` launchers over `Hiiro::TaskCli` (`bin/t`, `bin/tt` are symlinks) |
427
- | `lib/hiiro/task_cli.rb` | `Hiiro::TaskCli.setup`/`setup_todo` and the `Commands` module: task-scoped commands, resources, documents, and Herdr actions |
428
- | `lib/hiiro/current_task.rb` | Shared current-task resolution (Herdr workspace, working directory, saved pin) used by `TaskScope` and `Environment#task` |
429
- | `lib/hiiro/task_scope.rb` | Named/current/orphan reference resolution and cached task context |
430
- | `lib/hiiro/tasks.rb` | `TaskManager#create_tree` worktree creation shared with `t TASK tree new` |
431
- | `lib/hiiro/task_sessions.rb` | Native AI launch/resume dispatch and running-pane focus |
432
- | `lib/hiiro/task_record.rb` | Shared records, states, home naming, and resource identity |
433
- | `lib/hiiro/todo.rb` | Shared `TodoItem` rows and full-task-name association |
434
- | `lib/hiiro/herdr.rb` | Herdr adapter, terminal creation/focus/read behavior |
435
- | `lib/hiiro/tasks.rb` | Separate `h task` worktree and sparse-checkout operations |
436
- | `lib/hiiro/options.rb` | Option parsing, short aliases, and generated option help |
437
- | `lib/hiiro.rb` | Command registration, child dispatch, resolvers, and generated command tables |
133
+ | `exe/t`, `exe/tt`, `bin/h-task` | Launchers (`bin/t`, `bin/tt`, `bin/h-task` are symlinks) |
134
+ | `lib/hiiro/task_cli.rb` | `Hiiro::TaskCli` and the `Commands` module: task resolution rule, all commands |
135
+ | `lib/hiiro/current_task.rb` | Current-task resolution shared with `Environment#task` |
136
+ | `lib/hiiro/task_sessions.rb` | Native AI launch and resume |
137
+ | `lib/hiiro/task_record.rb` | Task and resource models, home naming |
138
+ | `lib/hiiro/tasks.rb` | `TaskManager#create_tree`, `Tree`, `Environment` |
139
+ | `lib/hiiro/todo.rb` | `TodoItem` rows |
140
+ | `lib/hiiro/herdr.rb` | Herdr adapter |