hiiro 0.1.365 → 0.1.366

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 (12) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +24 -343
  3. data/README.md +73 -14
  4. data/bin/t +526 -0
  5. data/bin/tt +20 -0
  6. data/docs/h-task.md +120 -56
  7. data/docs/t.md +427 -0
  8. data/docs/why-t.md +306 -0
  9. data/lib/hiiro/task_scope.rb +92 -0
  10. data/lib/hiiro/task_sessions.rb +51 -0
  11. data/lib/hiiro/version.rb +1 -1
  12. metadata +8 -2
data/docs/h-task.md CHANGED
@@ -4,108 +4,172 @@
4
4
 
5
5
  Task records and resource references live in `~/.config/hiiro/hiiro.db`, in the existing `tasks` table and the `task_resources` table. `h task` uses the same records. Its YAML file is a backup, not a separate task store.
6
6
 
7
+ Task todos use the existing `todos` table shared with `h todo`. `t` writes to the database directly and does not rewrite the task YAML backup or `todo.yml`.
8
+
7
9
  ## t
8
10
 
9
- The command implementation lives in `~/bin/t`, not a `Hiiro::TaskCLI` library class. Commands use `add_cmd` with per-command argument and option declarations. Running `t` or `t doc` displays Hiiro's generated subcommand table, including declaration locations. Leaf help, such as `t directory add --help`, displays only that command's options without executing it. There is no separate task help template. `t` does not run `h task` or discover legacy `t-*` executables.
11
+ The command implementation lives in the repository's `bin/t`, not a `Hiiro::TaskCLI` library class. `~/bin/t` is a symlink to that executable, which loads the repository library. Installing the gem does not install this launcher. `bin/tt` delegates to its todo scope. `t` does not run `h task` or discover legacy `t-*` executables.
12
+
13
+ The grammar is `t TASK COMMAND...`. Bare `t` lists all tasks, including done and archived tasks. `t TASK` shows the task. Only exact root `t help` displays generic usage and native scoped help without looking up a task. First words such as `new`, `show`, `edit`, `pry`, and `he` are task references, not root commands or help abbreviations.
10
14
 
11
- Every task command accepts `-t TASK` or `--task TASK` before or after the command. Explicit task names are exact and take precedence over the current directory or workspace. Conflicting explicit names are errors.
15
+ Named references match an exact name first, then a unique case-sensitive prefix. Ambiguous prefixes are errors. Unknown names fail except with `t NAME new` or `t NAME todo add TEXT...`. Explicit `new` creates exactly `NAME` without prefix resolution. `t TASK help` shows task commands, and `t TASK todo help` shows todo commands. Native command abbreviations apply inside these scopes.
12
16
 
13
- Without a selector, `t` considers the current directory inside a task home, an attached directory, or a legacy worktree. In a Herdr terminal, it also queries the current workspace. If the contexts identify different tasks, the command fails without changing task data. A shared directory therefore requires an explicit selector. Outside Herdr, an unrelated focused workspace does not affect task selection.
17
+ Use `.` to select the current task, including when supplying a payload: `t . next 'Compare the export'`. Selection checks the calling Herdr workspace, then the current directory inside a task home, code directory, or registered directory, then the saved task. Workspace context wins over a conflicting directory. Ambiguous matches and invalid, stale, or conflicting Herdr IDs are errors. Outside Herdr, an unrelated focused workspace does not affect selection. An explicit name bypasses context lookup.
18
+
19
+ `t TASK current` prints the resolved name and saves a named selection without changing terminal focus. `t . current` only prints it. The fallback is a `PinRecord` with `command='t'`, `key='current_task'`, and the task ID as a JSON integer in `value_json`. A missing saved task is an error when selection reaches that fallback. Reads and workspace opens through `.` do not replace it.
14
20
 
15
21
  ### Task records
16
22
 
17
23
  ```text
18
- t list [--all]
19
- t show [TASK]
20
- t current
21
- t new TASK
22
- t next [TEXT...] [--clear]
23
- t status [active|waiting|done|archived]
24
- t waiting [TEXT...] [--clear]
25
- t done
26
- t archive
24
+ t
25
+ t TASK
26
+ t TASK show
27
+ t TASK current
28
+ t NAME new
29
+ t TASK next [TEXT...] [--clear]
30
+ t TASK status [active|waiting|done|archived]
31
+ t TASK waiting [TEXT...] [--clear]
32
+ t TASK done
33
+ t TASK archive
34
+ ```
35
+
36
+ Bare `t` lists tasks regardless of context or the saved task. There is no root `list`, `ls`, `new`, or `show` action. `next`, `waiting`, and `status` without a payload display the selected task's current value.
37
+
38
+ `t NAME new` creates a record and `~/notes/work/NAME`. It never creates a Git worktree, moves code, or launches Herdr. Repeating `new` keeps the exact existing record and ensures its home exists. Names contain 1-120 ASCII letters, digits, dots, underscores, or hyphens and start with a letter or digit. Existing names that contain other characters remain usable, with those characters percent-encoded in the computed home directory name.
39
+
40
+ Setting waiting text changes status to `waiting`. Clearing that text changes a waiting task back to `active`. `done` and `archive` change status and record timestamps. They never remove todos, a task home, a file, a directory, a link, or a workspace. `t TASK status active` reopens a task.
41
+
42
+ ```bash
43
+ t audit-invoices new
44
+ t audit-invoices next 'Compare the September export'
45
+ t audit-invoices waiting 'Finance approval'
46
+ t audit-invoices waiting --clear
47
+ t audit-invoices done
48
+ t audit-invoices
49
+ ```
50
+
51
+ ### Task todos
52
+
53
+ ```text
54
+ t TASK todo
55
+ t TASK todo list
56
+ t TASK todo ls
57
+ t TASK todo add TEXT...
58
+ t TASK todo rm ID
59
+ tt TASK [COMMAND...]
60
+ tt
61
+ tt help
27
62
  ```
28
63
 
29
- `list` shows active and waiting tasks. `--all` includes completed and archived tasks. `next`, `waiting`, and `status` without arguments display the current value.
64
+ `tt TASK ...` delegates to `t TASK todo ...`. Bare `tt` means `t . todo`, and `tt help` shows todo help without task lookup. The default todo action is listing. `t - todo` and `tt -` select orphan todos, with `add` and `rm` available in that scope. `-` is invalid outside todo commands and never creates a task.
30
65
 
31
- `new TASK` creates a record and `~/notes/work/TASK`. It never creates a Git worktree, moves code, or launches Herdr. Repeating `new` keeps the existing record and ensures its home exists. Names contain 1-120 ASCII letters, digits, dots, underscores, or hyphens and start with a letter or digit. Existing names that contain other characters remain usable, with those characters percent-encoded in the computed home directory name.
66
+ If a named `todo add` finds no match, it creates the task using `new` validation and home rules, then adds one todo with status `not_started`. Task and todo database writes use one immediate SQLite transaction. Other todo actions never create tasks.
32
67
 
33
- Setting waiting text changes status to `waiting`. Clearing that text changes a waiting task back to `active`. `done` and `archive` change status and record timestamps. They never remove a task home, a file, a directory, a link, or a workspace. `status active` reopens a task.
68
+ Every token after `add` is literal text, including flags and `--`, except that leading `add -h` or `add --help` displays native option help. The tokens are joined with spaces. Missing, empty, or whitespace-only text fails before task creation.
34
69
 
35
70
  ```bash
36
- t new audit-invoices
37
- t next -t audit-invoices 'Compare the September export'
38
- t waiting -t audit-invoices 'Finance approval'
39
- t waiting -t audit-invoices --clear
40
- t done -t audit-invoices
41
- t show audit-invoices
71
+ t audit-invoices todo add Compare the September export
72
+ tt audit-invoices add Inspect --help output
73
+ t audit-invoices todo
74
+ t audit-invoices todo rm 42
75
+ tt - add Buy printer paper
42
76
  ```
43
77
 
78
+ Use an ID printed by `show` or todo listing in place of `42`. `rm` accepts exactly one decimal database ID belonging to the selected scope, not a list position or suffix. Missing, invalid, or extra arguments fail.
79
+
80
+ Task display and todo listing print each matching item's ID, status, and text in ID order. Matching uses the full task name exactly, including legacy rows with both `task_name` and `subtask_name`. A parent task does not include its subtasks' todos. New task todos store the full task name in `task_name` and leave `subtask_name` unset. Orphan rows leave both unset.
81
+
82
+ Each task still has one independent `next_action`. Adding or removing todos does not change that field, task status, or saved selection. `t` has no todo-completion command or automatic next-action promotion. The separate `h task` and `h todo` commands keep their existing behavior.
83
+
44
84
  ### Directory, link, PR, and file references
45
85
 
46
86
  ```text
47
- t directory add PATH [--primary] [--label LABEL]
48
- t directory list
49
- t directory open [ID|PATH|LABEL]
50
- t link add URL [--kind general|issue|thread] [--label LABEL]
51
- t link list [--kind general|issue|thread]
52
- t link open [ID|URL|LABEL]
53
- t pr add URL [--label LABEL]
54
- t pr list
55
- t pr open [ID|URL|LABEL]
56
- t file add PATH [--label LABEL]
57
- t file list
58
- t file open [ID|PATH|LABEL]
59
- ```
60
-
61
- Directory and file attachments must already exist. `add` stores their canonical paths without moving or copying anything. Repeating an identical attachment does not create another reference. `--primary` marks an attached directory as the default code directory for new workspace tabs and panes.
87
+ t TASK directory add PATH [--primary] [--label LABEL]
88
+ t TASK directory list
89
+ t TASK directory open [ID|PATH|LABEL]
90
+ t TASK link add URL [--kind general|issue|thread] [--label LABEL]
91
+ t TASK link list [--kind general|issue|thread]
92
+ t TASK link open [ID|URL|LABEL]
93
+ t TASK pr add URL [--label LABEL]
94
+ t TASK pr list
95
+ t TASK pr open [ID|URL|LABEL]
96
+ t TASK file add PATH [--label LABEL]
97
+ t TASK file list
98
+ t TASK file open [ID|PATH|LABEL]
99
+ ```
100
+
101
+ Directory and file attachments must already exist. `add` stores their canonical paths without moving or copying anything. Repeating an identical attachment does not create another reference. `--primary` marks an attached directory as the default code directory for new workspace tabs and panes. An existing directory can be a Git worktree. Registering it does not create a worktree or alter sparse checkout.
62
102
 
63
103
  Links must be absolute HTTP or HTTPS URLs. `link list` includes PR references unless a kind filter is present. PRs use the same resource storage as other links and do not require a Git repository or provider API.
64
104
 
65
105
  `file list` also discovers files in the task home, including documents, without registration. Home files can be opened by a relative path or an unambiguous basename. An omitted open selector works only when exactly one resource matches. Otherwise, the command requires an ID, path, URL, or unique label.
66
106
 
67
- `open` uses the operating system's default application. Attachments remain references even after task completion.
107
+ `open` uses the operating system's default application. Attachments remain references even after task completion. List commands also accept `ls`. Leaf help, such as `t audit-invoices directory add --help`, lists options without running the action.
68
108
 
69
109
  ### Documents
70
110
 
71
111
  ```text
72
- t doc new NAME [TITLE...]
73
- t doc list
74
- t doc open [NAME]
112
+ t TASK doc new NAME [TITLE...]
113
+ t TASK doc list
114
+ t TASK doc open [NAME]
75
115
  ```
76
116
 
77
- `doc new` creates a Markdown file in the task home with an initial heading. It never overwrites an existing file. Documents have a stable task-ID prefix, such as `task-42-investigation.md`, to avoid collisions in `mdoc`'s shared HTML output directory. `doc open investigation` accepts the short name and invokes `mdoc`. Existing Markdown files in the task home also appear without registration.
117
+ `doc new` creates a Markdown file in the task home with an initial heading. It never overwrites an existing file. Documents have a stable task-ID prefix, such as `task-42-investigation.md`, to avoid collisions in `mdoc`'s shared HTML output directory. `t TASK doc open investigation` accepts the short name and invokes `mdoc`. Existing Markdown files in the task home also appear without registration.
78
118
 
79
- Task creation, metadata, references, and document creation/listing work without Git or Herdr. Document reading requires `mdoc` on `PATH` and its existing configuration.
119
+ Task creation, metadata, references, and document creation/listing work without Git or Herdr when a named task is supplied. Document reading requires `mdoc` on `PATH` and its existing configuration.
80
120
 
81
121
  ### Herdr workspaces, tabs, and panes
82
122
 
83
123
  ```text
84
- t workspace open [--directory PATH]
85
- t workspace show
86
- t tab list
87
- t tab new [LABEL] [--directory PATH] [--command COMMAND]
88
- t tab open ID|LABEL
89
- t pane list
90
- t pane open ID|LABEL
91
- t pane read ID|LABEL
92
- t pane run ID|LABEL COMMAND...
93
- t pane split ID|LABEL [--direction right|down] [--directory PATH] [--command COMMAND]
124
+ t TASK workspace [--directory PATH]
125
+ t TASK switch [--directory PATH]
126
+ t TASK workspace --show
127
+ t TASK switch --show
128
+ t TASK tab list
129
+ t TASK tab new [LABEL] [--directory PATH] [--command COMMAND]
130
+ t TASK tab open ID|LABEL
131
+ t TASK pane list
132
+ t TASK pane open ID|LABEL
133
+ t TASK pane read ID|LABEL
134
+ t TASK pane run ID|LABEL -- COMMAND...
135
+ t TASK pane split ID|LABEL [--direction right|down] [--directory PATH] [--command COMMAND]
94
136
  ```
95
137
 
96
- These commands require a running Herdr server. `workspace open` focuses the workspace with the task's label or creates one. A new workspace starts in the explicit directory, the primary code directory, the legacy worktree, or the task home, in that order. `--directory` changes that operation's start directory without changing stored attachments.
138
+ These commands require a running Herdr server. `t TASK workspace` and its `switch` alias focus the workspace with the task's label or create one. They save a named task only after a successful switch. `t . workspace` leaves the saved fallback unchanged. A new workspace starts in the explicit directory, the primary code directory, the legacy worktree, or the task home, in that order. `--directory` changes that operation's start directory without changing stored attachments.
139
+
140
+ `--show` queries the current tabs and panes without saving, focusing, or creating a workspace. `workspace` and `switch` are direct commands, not groups. Native Hiiro abbreviation matching accepts `t TASK wor`.
97
141
 
98
- `workspace show` queries the current tabs and panes. Tab and pane selectors must belong to the selected task's workspace. Duplicate labels require a live ID. No pane or tab ID is stored as durable task identity. Task workspace labels follow Herdr's dot-to-underscore normalization. Colliding task or workspace labels are errors rather than fuzzy matches.
142
+ Tab and pane selectors must belong to the selected task's workspace. Duplicate labels require a live ID. No pane or tab ID is stored as durable task identity. Task workspace labels follow Herdr's dot-to-underscore normalization. Colliding task or workspace labels are errors rather than fuzzy matches.
99
143
 
100
144
  Use `--` before literal command arguments that begin with a dash:
101
145
 
102
146
  ```bash
103
- t pane run -t audit-invoices PANE_ID -- printf '%s\n' --example
147
+ t audit-invoices pane run PANE_ID -- printf '%s\n' --example
104
148
  ```
105
149
 
150
+ ### Native AI sessions
151
+
152
+ `t TASK omp`, `t TASK codex` or `cdx`, and `t TASK claude` or `cld` create new focused tabs in the task workspace. They launch the native `omp`, `codex`, and `claude` executables, respectively. The workspace is created if needed. Fresh sessions are the default.
153
+
154
+ 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 receive `--resume`; Codex receives its `resume` subcommand.
155
+
156
+ With no remaining arguments, resume focuses the unique genuinely running tool in that workspace, using Herdr's agent metadata rather than the tab label. Multiple running matches are an error that reports their IDs. If none is running, a new tab launches the native resume picker.
157
+
158
+ With any remaining arguments, resume always opens a new tab and forwards those arguments unchanged. Session IDs and options belong to the native CLI. Other arguments, including `--help` and `--`, also pass through unchanged. `t` does not inject model, permission, continue, or fresh-session flags.
159
+
160
+ ```bash
161
+ t audit-invoices omp
162
+ t audit-invoices cdx r
163
+ t audit-invoices cld resume SESSION_ID
164
+ t audit-invoices codex resume --help
165
+ t audit-invoices claude --help
166
+ ```
167
+
168
+ The launcher scopes live-pane lookup to the task workspace. Persisted session discovery remains native CLI behavior and is not necessarily task-isolated when tasks share a directory. `t` performs no auth or API requests and makes no automatic Git changes.
169
+
106
170
  ## h task
107
171
 
108
- The existing `h task` commands below retain their coding-worktree operations. Unlike `t new`, `h task start` can create a worktree for a new task. For a task without a worktree, path resolution uses its task home. Starting an existing noncoding task switches to that home without creating a worktree.
172
+ The existing `h task` commands below retain their coding-worktree operations. Unlike `t NAME new`, `h task start` can create a worktree for a new task. For a task without a worktree, path resolution uses its task home. Starting an existing noncoding task switches to that home without creating a worktree.
109
173
 
110
174
  ## Synopsis
111
175