estimetry 0.1.2 → 0.3.0

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 (65) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +88 -16
  3. package/dist/application/contracts/skill-mention.js +20 -0
  4. package/dist/application/estimetry.js +2 -0
  5. package/dist/application/hooks/context-limit.js +10 -2
  6. package/dist/application/hooks/hook-context.js +12 -4
  7. package/dist/application/hooks/receive-session-hook.js +15 -4
  8. package/dist/application/hooks/session-end-import.js +6 -7
  9. package/dist/application/project/init-defaults.js +17 -4
  10. package/dist/application/project/init-project.js +4 -1
  11. package/dist/application/project/install-copy.js +8 -1
  12. package/dist/application/project/show-init-choices.js +1 -1
  13. package/dist/application/project/tool-notices.js +8 -0
  14. package/dist/application/task/import-session-logs.js +4 -1
  15. package/dist/application/task/show-calibration.js +12 -8
  16. package/dist/application/task/task-cards.js +1 -1
  17. package/dist/bootstrap/container.js +23 -6
  18. package/dist/bootstrap/hook-receiver.js +7 -14
  19. package/dist/bootstrap/main.js +1 -1
  20. package/dist/domain/calibration/applicable-coefficient.js +35 -19
  21. package/dist/domain/calibration/calibration-policy.js +39 -0
  22. package/dist/domain/calibration/calibration.js +21 -36
  23. package/dist/domain/calibration/level-parts.js +41 -0
  24. package/dist/domain/calibration/ratio-samples.js +34 -0
  25. package/dist/domain/code/code-classes.js +1 -1
  26. package/dist/domain/estimate/estimate.js +22 -5
  27. package/dist/domain/progress/progress-record-parser.js +6 -0
  28. package/dist/domain/progress/session-log.js +2 -1
  29. package/dist/domain/usage/task-usage.js +24 -7
  30. package/dist/infrastructure/persistence/records.js +1 -1
  31. package/dist/infrastructure/persistence/yaml-config-store.js +6 -5
  32. package/dist/infrastructure/persistence/yaml-estimate-reader.js +20 -12
  33. package/dist/integrations/tools/claude-code/claude-code-adapter.js +29 -48
  34. package/dist/integrations/tools/claude-code/hook-events.js +4 -0
  35. package/dist/integrations/tools/claude-code/hook-translation.js +16 -34
  36. package/dist/integrations/tools/claude-code/importer/claude-code-logs.js +1 -1
  37. package/dist/integrations/tools/claude-code/skill-file.js +7 -19
  38. package/dist/integrations/tools/codex/codex-adapter.js +161 -0
  39. package/dist/integrations/tools/codex/hook-events.js +23 -0
  40. package/dist/integrations/tools/codex/hook-translation.js +76 -0
  41. package/dist/integrations/tools/codex/hook-trust.js +69 -0
  42. package/dist/integrations/tools/codex/importer/codex-logs.js +208 -0
  43. package/dist/integrations/tools/codex/importer/rollout-parser.js +163 -0
  44. package/dist/integrations/tools/codex/sandbox-rules.js +38 -0
  45. package/dist/integrations/tools/codex/skill-file.js +22 -0
  46. package/dist/integrations/tools/codex/trust-tables.js +96 -0
  47. package/dist/integrations/tools/content/commands.js +35 -26
  48. package/dist/integrations/tools/shared/generated-file.js +26 -0
  49. package/dist/integrations/tools/shared/hook-payload.js +33 -0
  50. package/dist/integrations/tools/{claude-code → shared}/hook-settings.js +37 -22
  51. package/dist/integrations/tools/shared/instructions-block.js +39 -0
  52. package/dist/integrations/tools/shared/skills-plan.js +39 -0
  53. package/dist/interface/cli/commands/calibrate-command.js +11 -0
  54. package/dist/interface/cli/commands/hook-command.js +1 -1
  55. package/dist/interface/cli/commands/init-command.js +16 -7
  56. package/dist/interface/cli/commands/status-command.js +5 -2
  57. package/dist/interface/cli/help.js +3 -1
  58. package/dist/interface/cli/presenters/text/closing-text.js +7 -3
  59. package/dist/interface/cli/presenters/text/estimate-text.js +35 -13
  60. package/dist/interface/cli/presenters/text/notices-text.js +1 -0
  61. package/dist/interface/cli/presenters/text/task-text.js +1 -1
  62. package/dist/interface/cli/presenters/text-presenter.js +3 -3
  63. package/package.json +1 -1
  64. package/dist/integrations/tools/claude-code/claude-md.js +0 -28
  65. /package/dist/integrations/tools/{claude-code/importer → shared}/log-lines.js +0 -0
@@ -1,4 +1,8 @@
1
- /** Texts of the estimetry skill and its commands, independent of the AI tool. */
1
+ /**
2
+ * Texts of the estimetry skill and its commands, independent of the AI tool. A body names another skill with
3
+ * `{{skill:<id>}}` (see `skillMention`) and the arguments the user gave with `{{arguments}}`; the tool's renderer
4
+ * turns both into its own form.
5
+ */
2
6
  export const ESTIMETRY_SKILL = {
3
7
  id: 'estimetry',
4
8
  description: 'Estimate tasks and measure the actual effort with the estimetry CLI (emt). Use when the user asks how long a task will take, starts or finishes work on a task, or work goes beyond the plan.',
@@ -8,18 +12,18 @@ estimetry compares estimates with the actual effort of AI-agent development and
8
12
 
9
13
  ## Estimating
10
14
 
11
- Never name an effort or a deadline for a task before \`/emt-estimate\` is done, even when asked casually. The estimate rests on the user's own past tasks, not on a general sense of how long things take:
15
+ Never name an effort or a deadline for a task before \`{{skill:emt-estimate}}\` is done, even when asked casually. The estimate rests on the user's own past tasks, not on a general sense of how long things take:
12
16
  - agree with the user on the task type and the technologies the task really touches;
13
17
  - \`emt similar\` shows closed tasks like it, \`emt calibrate\` the user's coefficients and the one the estimate may apply;
14
- - with a coefficient, multiply the hours of every part by it; without one, say plainly that the estimate is without calibration;
18
+ - with a coefficient, multiply the optimistic and most likely hours of every part by its value, the pessimistic hours by its pessimistic value; without one, say plainly that the estimate is without calibration and why;
15
19
  - give the estimate by parts of the plan, each with optimistic, most likely and pessimistic hours, and save it only after the user approves it.
16
20
 
17
21
  ## Measuring
18
22
 
19
- - \`emt start\` starts the measurement of a task (\`/emt-start\`).
20
- - Work outside the plan is recorded with \`emt extra\` (\`/emt-extra\`).
21
- - Several agents on one task: \`emt parallel on\` and \`emt parallel off\` (\`/emt-parallel\`).
22
- - Time outside agent sessions, such as manual testing: \`emt manual\` (\`/emt-manual\`).
23
+ - \`emt start\` starts the measurement of a task (\`{{skill:emt-start}}\`).
24
+ - Work outside the plan is recorded with \`emt extra\` (\`{{skill:emt-extra}}\`).
25
+ - Several agents on one task: \`emt parallel on\` and \`emt parallel off\` (\`{{skill:emt-parallel}}\`).
26
+ - Time outside agent sessions, such as manual testing: \`emt manual\` (\`{{skill:emt-manual}}\`).
23
27
  - \`emt status\` shows the fact so far against the estimate.
24
28
 
25
29
  ## Revising the estimate
@@ -36,8 +40,8 @@ Write the reason as a short summary agreed with the user, never a quote of the c
36
40
  ## Closing and retro
37
41
 
38
42
  - When estimetry says a change of the task was completed, ask the user whether it was the last one and whether to close the task. Never close a task on your own.
39
- - Close only after the user agrees in the conversation: \`emt close --yes\` (\`/emt-close\`). If the task was dropped, add \`--abandoned\`.
40
- - Right after closing, hold the retro with the user (\`/emt-retro\`): compare the estimate with the fact by parts, agree on the reasons and on one lesson. Write down what the user agrees with, not your own guesses.
43
+ - Close only after the user agrees in the conversation: \`emt close --yes\` (\`{{skill:emt-close}}\`). If the task was dropped, add \`--abandoned\`.
44
+ - Right after closing, hold the retro with the user (\`{{skill:emt-retro}}\`): compare the estimate with the fact by parts, agree on the reasons and on one lesson. Write down what the user agrees with, not your own guesses.
41
45
  - When the customer agrees to more work than estimated, the task closes as it is and the rest becomes a new task: \`emt renegotiate "<new title>" --yes\`, again only after the user agrees.
42
46
  - A task closed by mistake: \`emt reopen <task>\`.
43
47
 
@@ -53,19 +57,21 @@ export const COMMANDS = [
53
57
  id: 'emt-estimate',
54
58
  description: 'Estimate a task by parts of the plan from past tasks and calibration, and save the approved estimate as its plan',
55
59
  argumentHint: '[task title]',
56
- body: `Estimate the task the user describes ($ARGUMENTS) from the user's own past tasks, and save the approved estimate with estimetry. Do not name an effort or a deadline before step 7.
60
+ body: `Estimate the task the user describes ({{arguments}}) from the user's own past tasks, and save the approved estimate with estimetry. Do not name an effort or a deadline before step 7.
57
61
 
58
62
  1. **Type and stack.** Agree with the user on the task type (feature, integration, bugfix, refactor, infra, migration, research) and on the technologies the task really touches — not every technology of the project. They go into the estimate as \`type\` and \`stack\`.
59
63
  2. **The task.** \`emt task list\` shows existing tasks. A new one: \`emt task new "<title>" --type <type>\`, after the type is agreed. A task already in progress is a revision: \`emt task show <task>\` gives the parts of the estimate in force — start from them, keep the parts that stay and add or change the rest; use \`--revise\` in step 5 and \`emt estimate revise\` in step 8.
60
64
  3. **Parts.** Split the work into parts of the plan with hours as optimistic ≤ most likely ≤ pessimistic. Include manual testing and review when the work needs them. Add up a preliminary most likely total.
61
65
  With a development flow (OpenSpec), link every part to its change: \`group\` is the name of the change. When the change does not exist yet, agree its kebab-case name with the user now, put it into \`group\`, and create the change under exactly that name later — otherwise progress, completion of changes and the fact by parts cannot follow the estimate. Several changes give several groups.
62
66
  4. **Similar tasks.** \`emt similar --type <type> --stack <a,b> --hours <preliminary total> --json\`. Compare the parts with the facts of the similar tasks, their extra work and lessons; adjust the parts. Name the tasks you rely on — they go into \`basedOn\`. If there are none, say so.
63
- 5. **Calibration.** \`emt calibrate --type <type> --stack <a,b> --json\`.
64
- - If \`coefficient\` is not null, multiply the optimistic, most likely and pessimistic hours of every part by \`coefficient.value\` and write \`calibrated: true\` and \`calibration: { coefficient: <value> }\`. Say which slice it comes from and how many tasks.
65
- - If \`coefficient\` is null, say plainly that the estimate is **without calibration** and why (too few closed tasks), and write \`calibrated: false\`. Never apply the overall slice or a coefficient of your own.
67
+ 5. **Calibration.** \`emt calibrate --type <type> --stack <a,b> --json\`. Apply only the coefficient \`emt calibrate\` gives, never one of your own.
68
+ - If \`coefficient\` is not null, multiply the optimistic and most likely hours of every part by \`coefficient.value\` and the pessimistic hours by \`coefficient.pessimistic\`, and write \`calibrated: true\` and \`calibration: { coefficient: <value>, pessimistic: <pessimistic> }\`. Name the slice, the number of tasks and the weight, for example "×0.59 from 3 feature tasks, weight 60%". With a weight below 50% (one task at the default \`shrink\`), say that there is little experience yet and the coefficient is cautious; at 50% or more, do not call it cautious.
69
+ - If \`coefficient\` is null, say plainly that the estimate is **without calibration** and why, as \`emt calibrate\` without \`--json\` words it: no closed task yet, fewer closed tasks than the user set in \`calibration.minTasks\`, every closed task left out or none of them has an estimate, or cards it could not read (estimetry needs an update). Write \`calibrated: false\`.
70
+ - A revision (\`--revise\`) follows the same rules with the coefficient of estimates made during work.
66
71
  6. **Reserve.** Put a reserve only into the pessimistic hours, never into the most likely hours or a part of its own, and name its source in \`rationale\`:
67
72
  - with calibration, only for missed scope (\`missedScope\`): extra work absorbed by tasks is already in the coefficient;
68
73
  - without calibration, for extra work (\`extras\`, absorbed) and missed scope.
74
+ The reserve goes on top of the pessimistic hours already multiplied by \`coefficient.pessimistic\`: that coefficient covers how little the ratio is known yet, it is not a reserve for extra work.
69
75
  Cross-check with lines per hour (\`linesPerHour\`, \`codeVolume\`) only as a self-check: if it disagrees strongly, say so and explain, but do not recompute the estimate from lines.
70
76
  7. **Approval.** Show the estimate as a table: parts, hours, what it rests on (similar tasks, coefficient or "without calibration", reserve). Wait for the user to approve or change it.
71
77
  8. **Save.** Write the approved estimate to a YAML file outside the repository, for example in a temporary directory, and save it: \`emt estimate save <file>\` (for a task in progress: \`emt estimate revise <file> ...\`, see the estimetry skill). If it reports errors, fix every listed field and save again.
@@ -76,28 +82,28 @@ export const COMMANDS = [
76
82
  stack: [typescript, node]
77
83
  basedOn: [T-12, T-17]
78
84
  calibrated: true
79
- calibration: { coefficient: 1.3 }
85
+ calibration: { coefficient: 1.23, pessimistic: 1.64 }
80
86
  rationale: Why the numbers are what they are, what they rest on, where the reserve is.
81
87
  parts:
82
88
  - name: implementation
83
89
  kind: implementation # analysis, implementation, auto-tests, manual-testing, review, docs, other
84
90
  who: agents # agents, user or both
85
91
  group: export-invoices-pdf # the change of the part, with a development flow
86
- hours: { optimistic: 2.6, likely: 3.9, pessimistic: 6.5 }
92
+ hours: { optimistic: 2.46, likely: 3.69, pessimistic: 6.56 }
87
93
  \`\`\`
88
94
 
89
- 9. Tell the user that time is not measured until the task starts, and offer to start it now with \`/emt-start\` (\`emt start\`; \`--at "YYYY-MM-DD HH:MM"\` if work already began).
95
+ 9. Tell the user that time is not measured until the task starts, and offer to start it now with \`{{skill:emt-start}}\` (\`emt start\`; \`--at "YYYY-MM-DD HH:MM"\` if work already began).
90
96
  `,
91
97
  },
92
98
  {
93
99
  id: 'emt-start',
94
100
  description: 'Start measuring the effort of a task',
95
101
  argumentHint: '[task id] [--at <time>]',
96
- body: `Start the measurement of a task with \`emt start $ARGUMENTS\`.
102
+ body: `Start the measurement of a task with \`emt start {{arguments}}\`.
97
103
 
98
104
  - Without a task id it starts the only task of this project that can be started; if there are several, ask the user which one and pass its id.
99
105
  - \`--at "YYYY-MM-DD HH:MM"\` backdates the start when work began before it was recorded.
100
- - If the task has no estimate, estimetry warns that it will not be used for calibration; offer \`/emt-estimate\` first.
106
+ - If the task has no estimate, estimetry warns that it will not be used for calibration; offer \`{{skill:emt-estimate}}\` first.
101
107
 
102
108
  Show the user the command output.
103
109
  `,
@@ -116,14 +122,14 @@ Categories:
116
122
 
117
123
  Optional: \`--time <duration>\` (a guess, e.g. \`30m\`; it does not change the measured fact), \`--lines <n>\`, \`--change <name>\`, \`--task <id>\`.
118
124
 
119
- Use the user's words for the description: $ARGUMENTS
125
+ Use the user's words for the description: {{arguments}}
120
126
  `,
121
127
  },
122
128
  {
123
129
  id: 'emt-parallel',
124
130
  description: 'Switch parallel mode of a task on or off',
125
131
  argumentHint: 'on|off [--agents <n>] [--reason <text>]',
126
- body: `Switch parallel mode, when several agents work on one task at once: \`emt parallel $ARGUMENTS\`.
132
+ body: `Switch parallel mode, when several agents work on one task at once: \`emt parallel {{arguments}}\`.
127
133
 
128
134
  - \`emt parallel on --reason "<why>" --agents <n> --parts <ids>\` — \`--parts\` are comma-separated ids of the estimate parts done in parallel.
129
135
  - \`emt parallel off\` when the work is sequential again.
@@ -135,7 +141,7 @@ estimetry records which share of the budget was spent when the mode was switched
135
141
  id: 'emt-manual',
136
142
  description: 'Record time spent outside agent sessions',
137
143
  argumentHint: '<duration> "<description>" [--at <time>] [--agent]',
138
- body: `Record time the hooks could not see: \`emt manual $ARGUMENTS\`.
144
+ body: `Record time the hooks could not see: \`emt manual {{arguments}}\`.
139
145
 
140
146
  - Duration: \`40m\`, \`1h30m\` or \`1.5h\`.
141
147
  - \`--at "YYYY-MM-DD HH:MM"\` is when the work ended; with it the record merges with measured time instead of adding to it.
@@ -152,10 +158,10 @@ If estimetry warns that the time is already partly measured, ask the user whethe
152
158
  argumentHint: '[task id] [--at <time>] [--abandoned]',
153
159
  body: `Close a task only with the user's consent.
154
160
 
155
- 1. Run \`emt status $ARGUMENTS\` and show the user the fact, the share of the estimate and the plan.
161
+ 1. Run \`emt status {{arguments}}\` and show the user the fact, the share of the estimate and the plan.
156
162
  2. Ask the user whether to close the task now. If the work ended earlier, ask when and use \`--at "YYYY-MM-DD HH:MM"\`. If the task was dropped, use \`--abandoned\`.
157
- 3. Only after the user says yes, run \`emt close $ARGUMENTS --yes\`. If they say no, the task stays open and nothing is recorded.
158
- 4. Then go on with \`/emt-retro\`.
163
+ 3. Only after the user says yes, run \`emt close {{arguments}} --yes\`. If they say no, the task stays open and nothing is recorded.
164
+ 4. Then go on with \`{{skill:emt-retro}}\`.
159
165
 
160
166
  Never pass \`--yes\` without the user's explicit agreement in this conversation.
161
167
  `,
@@ -166,13 +172,16 @@ Never pass \`--yes\` without the user's explicit agreement in this conversation.
166
172
  argumentHint: '[task id]',
167
173
  body: `Hold the retro of a closed task with the user.
168
174
 
169
- 1. Run \`emt task show <task>\` (the task closed last if $ARGUMENTS is empty: \`emt task list --closed\`) and compare the estimate with the fact, part by part, and the extra work.
175
+ 1. Run \`emt task show <task>\` (the task closed last if {{arguments}} is empty: \`emt task list --closed\`) and compare the estimate with the fact, part by part, and the extra work.
170
176
  2. Suggest the main reasons for the differences and ask the user to confirm or correct them. A reason about one part starts with its id: \`"manual-testing: two devices instead of one"\`.
171
177
  3. Agree with the user on one lesson for the next estimate.
172
- 4. Record what the user agreed with: \`emt retro $ARGUMENTS --reason "<reason>" --reason "<reason>" --lesson "<lesson>"\`.
178
+ 4. Record what the user agreed with: \`emt retro {{arguments}} --reason "<reason>" --reason "<reason>" --lesson "<lesson>"\`.
173
179
 
174
180
  Running it again replaces the retro.
175
181
  `,
176
182
  },
177
183
  ];
184
+ /** The reminder a shared install puts into the instructions file of the agent (`CLAUDE.md`, `AGENTS.md`). */
185
+ export const ESTIMATE_REMINDER_BLOCK = 'Before you name a deadline or an effort for a task, run `{{skill:emt-estimate}}`: ' +
186
+ 'it bases the estimate on past tasks and saves it as the plan the actual effort is measured against.';
178
187
  //# sourceMappingURL=commands.js.map
@@ -0,0 +1,26 @@
1
+ import { createHash } from 'node:crypto';
2
+ const GENERATED_LINE = /^ {2}generatedBy: .*\n/m;
3
+ const HASH_LINE = /^ {2}contentHash: "[0-9a-f]*"\n/m;
4
+ /**
5
+ * Frontmatter `metadata` of a file estimetry generates: `generatedBy` with the version. `stamp` puts
6
+ * `contentHash` of the whole text after that line, so `ownership` can tell an untouched file from an edited one.
7
+ */
8
+ export function generatedBy(version) {
9
+ return ['metadata:', ` generatedBy: "estimetry ${version}"`];
10
+ }
11
+ /** The text with the hash of itself after its `generatedBy` line. */
12
+ export function stamp(unhashed) {
13
+ return unhashed.replace(GENERATED_LINE, (line) => `${line} contentHash: "${hashOf(unhashed)}"\n`);
14
+ }
15
+ /** Whose the file is: ours and untouched, ours but edited by the user, or the user's own. */
16
+ export function ownership(text) {
17
+ if (!/^ {2}generatedBy: "estimetry /m.test(text)) {
18
+ return 'foreign';
19
+ }
20
+ const stamped = /^ {2}contentHash: "([0-9a-f]*)"$/m.exec(text)?.[1];
21
+ return stamped !== undefined && stamped === hashOf(text.replace(HASH_LINE, '')) ? 'ours' : 'edited';
22
+ }
23
+ function hashOf(text) {
24
+ return createHash('sha256').update(text).digest('hex').slice(0, 12);
25
+ }
26
+ //# sourceMappingURL=generated-file.js.map
@@ -0,0 +1,33 @@
1
+ import { SessionId } from '../../../domain/measurement/session-id.js';
2
+ import { InvalidValue } from '../../../domain/shared/domain-error.js';
3
+ /**
4
+ * The translation of one call: the envelope checked here, the events by the tool's own rules. An empty string is
5
+ * no value. @throws InvalidValue naming the tool and the event, never the content of the payload.
6
+ */
7
+ export function translateHook(tool, event, payload, kinds, events) {
8
+ if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
9
+ throw new InvalidValue(`${tool} ${event}: stdin is not a JSON object`);
10
+ }
11
+ const p = payload;
12
+ if (typeof p['session_id'] !== 'string') {
13
+ throw new InvalidValue(`${tool} ${event}: session_id is missing`);
14
+ }
15
+ const cwd = payloadText(p['cwd']);
16
+ const transcript = payloadText(p['transcript_path']);
17
+ return {
18
+ session: SessionId.parse(p['session_id']),
19
+ ...(cwd === undefined ? {} : { cwd }),
20
+ ...(transcript === undefined ? {} : { transcript }),
21
+ kind: kinds[event] ?? 'other',
22
+ events: events(event, p),
23
+ };
24
+ }
25
+ /** A string field of a payload; an empty one, or anything else, is no value. */
26
+ export function payloadText(value) {
27
+ return typeof value === 'string' && value !== '' ? value : undefined;
28
+ }
29
+ /** Context for the agent in the output both tools read: `hookSpecificOutput.additionalContext`. */
30
+ export function additionalContext(event, text) {
31
+ return JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } });
32
+ }
33
+ //# sourceMappingURL=hook-payload.js.map
@@ -1,27 +1,22 @@
1
1
  import { isEstimetryCommand } from '../../../application/contracts/estimetry-command.js';
2
2
  import { InstallBlocked } from '../../../application/contracts/install-blocked.js';
3
- /**
4
- * Our hooks are recognised by this prefix, or by the command of this installation
5
- * (`estimetryCommand`) that falls back to it; a hook the user rewrote is theirs.
6
- */
7
- const HOOK_ARGS = 'hook claude-code';
8
- export const HOOK_PREFIX = `estimetry ${HOOK_ARGS}`;
3
+ /** Seconds a tool waits for an estimetry hook, unless the hook set names another for an event. */
9
4
  export const HOOK_TIMEOUT_SECONDS = 10;
10
5
  /**
11
6
  * Adds one hook per event and drops our earlier ones; every other key, hook and
12
7
  * their order stay. `displayPath` names the file in the error a broken one gives.
13
8
  */
14
9
  export function withHooks(text, set, displayPath) {
15
- const { events, synchronous } = set;
10
+ const { events, synchronous, ours } = set;
16
11
  const settings = parse(text, displayPath) ?? {};
17
- const hooks = withoutOurHooks(hooksOf(settings, displayPath));
12
+ const hooks = withoutOurHooks(hooksOf(settings, displayPath), ours);
18
13
  for (const event of events) {
19
14
  const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
20
15
  // The agent does not wait for an async hook: only hooks whose context it needs now, or the session end, are synchronous.
21
16
  const handler = {
22
17
  type: 'command',
23
18
  command: set.command(event),
24
- timeout: HOOK_TIMEOUT_SECONDS,
19
+ timeout: set.timeout?.(event) ?? HOOK_TIMEOUT_SECONDS,
25
20
  ...(synchronous.includes(event) ? {} : { async: true }),
26
21
  };
27
22
  hooks[event] = [...groups, { hooks: [handler] }];
@@ -29,12 +24,12 @@ export function withHooks(text, set, displayPath) {
29
24
  return render({ ...settings, hooks }, text);
30
25
  }
31
26
  /** Drops our hooks from a file we no longer install into; `undefined` when nothing else is left. */
32
- export function withoutHooks(text, displayPath) {
27
+ export function withoutHooks(text, ours, displayPath) {
33
28
  const settings = parse(text, displayPath);
34
29
  if (settings === undefined || !isObject(settings['hooks'])) {
35
30
  return text;
36
31
  }
37
- const hooks = withoutOurHooks(settings['hooks']);
32
+ const hooks = withoutOurHooks(settings['hooks'], ours);
38
33
  const { hooks: _old, ...rest } = settings;
39
34
  const next = Object.keys(hooks).length > 0 ? { ...settings, hooks } : rest;
40
35
  if (Object.keys(next).length === 0) {
@@ -55,16 +50,18 @@ export function isBrokenJson(text) {
55
50
  return true;
56
51
  }
57
52
  }
58
- export function hasOurHooks(text) {
53
+ /** Whether the settings hold a hook of ours. */
54
+ export function hasOurHooks(text, ours) {
59
55
  try {
60
56
  const settings = text === undefined ? undefined : JSON.parse(text);
61
- return isObject(settings) && isObject(settings['hooks']) && Object.values(settings['hooks']).some((groups) => groupsHaveOurs(groups));
57
+ const hooks = isObject(settings) ? settings['hooks'] : undefined;
58
+ return isObject(hooks) && Object.values(hooks).some((groups) => groupsHaveOurs(groups, ours));
62
59
  }
63
60
  catch {
64
61
  return false;
65
62
  }
66
63
  }
67
- function withoutOurHooks(hooks) {
64
+ function withoutOurHooks(hooks, ours) {
68
65
  const result = {};
69
66
  for (const [event, groups] of Object.entries(hooks)) {
70
67
  if (!Array.isArray(groups)) {
@@ -75,7 +72,7 @@ function withoutOurHooks(hooks) {
75
72
  if (!isObject(group) || !Array.isArray(group['hooks'])) {
76
73
  return [group];
77
74
  }
78
- const handlers = group['hooks'].filter((handler) => !isOurs(handler));
75
+ const handlers = group['hooks'].filter((handler) => !isOurs(handler, ours));
79
76
  if (handlers.length === group['hooks'].length) {
80
77
  return [group];
81
78
  }
@@ -87,17 +84,15 @@ function withoutOurHooks(hooks) {
87
84
  }
88
85
  return result;
89
86
  }
90
- function groupsHaveOurs(groups) {
91
- return Array.isArray(groups) && groups.some((group) => isObject(group) && Array.isArray(group['hooks']) && group['hooks'].some(isOurs));
87
+ function groupsHaveOurs(groups, ours) {
88
+ return (Array.isArray(groups) &&
89
+ groups.some((group) => isObject(group) && Array.isArray(group['hooks']) && group['hooks'].some((handler) => isOurs(handler, ours))));
92
90
  }
93
- function isOurs(handler) {
91
+ function isOurs(handler, ours) {
94
92
  return (isObject(handler) &&
95
93
  handler['type'] === 'command' &&
96
94
  typeof handler['command'] === 'string' &&
97
- isOurCommand(handler['command']));
98
- }
99
- function isOurCommand(command) {
100
- return isEstimetryCommand(command, HOOK_ARGS);
95
+ isEstimetryCommand(handler['command'], ours));
101
96
  }
102
97
  function hooksOf(settings, displayPath) {
103
98
  const hooks = settings['hooks'];
@@ -133,4 +128,24 @@ function render(settings, previous) {
133
128
  function isObject(value) {
134
129
  return typeof value === 'object' && value !== null && !Array.isArray(value);
135
130
  }
131
+ /** Every handler of ours in the settings, in their order; none when the text does not parse. */
132
+ export function ourHandlers(text, ours) {
133
+ let settings;
134
+ try {
135
+ settings = text === undefined ? undefined : JSON.parse(text);
136
+ }
137
+ catch {
138
+ return [];
139
+ }
140
+ const hooks = isObject(settings) ? settings['hooks'] : undefined;
141
+ if (!isObject(hooks)) {
142
+ return [];
143
+ }
144
+ return Object.entries(hooks).flatMap(([event, groups]) => (Array.isArray(groups) ? groups : []).flatMap((group, groupIndex) => (isObject(group) && Array.isArray(group['hooks']) ? group['hooks'] : []).flatMap((handler, handlerIndex) => isOurs(handler, ours) && isObject(handler) && isObject(group)
145
+ ? [{ event, group: groupIndex, handler: handlerIndex, config: handler, ...matcherOf(group) }]
146
+ : [])));
147
+ }
148
+ function matcherOf(group) {
149
+ return typeof group['matcher'] === 'string' ? { matcher: group['matcher'] } : {};
150
+ }
136
151
  //# sourceMappingURL=hook-settings.js.map
@@ -0,0 +1,39 @@
1
+ import { EMPTY_PLAN } from '../../../application/ports/file-change.js';
2
+ export const BLOCK_START = '<!-- estimetry:start -->';
3
+ export const BLOCK_END = '<!-- estimetry:end -->';
4
+ const EXISTING = new RegExp(`\\n*${escape(BLOCK_START)}[\\s\\S]*?${escape(BLOCK_END)}\\n?`);
5
+ /**
6
+ * A markdown file of instructions for the agent (`CLAUDE.md`, `AGENTS.md`) with one estimetry block at the end:
7
+ * the markers around `## estimetry` and `body`. Text outside the markers stays.
8
+ */
9
+ export function withBlock(text, body) {
10
+ const block = [BLOCK_START, '## estimetry', '', body, BLOCK_END].join('\n');
11
+ const rest = withoutBlock(text ?? '');
12
+ return rest === '' ? `${block}\n` : `${rest.replace(/\n*$/, '')}\n\n${block}\n`;
13
+ }
14
+ /** The file without the block; the text is returned as is when there is none. */
15
+ export function withoutBlock(text) {
16
+ if (!EXISTING.test(text)) {
17
+ return text;
18
+ }
19
+ const rest = text.replace(EXISTING, '\n');
20
+ return rest.trim() === '' ? '' : `${rest.replace(/\n+$/, '')}\n`;
21
+ }
22
+ function escape(text) {
23
+ return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
24
+ }
25
+ /**
26
+ * The block in an instructions file: written with a shared install (the file the team commits), taken out with a
27
+ * personal one; a file left with nothing but the block goes.
28
+ */
29
+ export function instructionsPlan(path, current, shared, body) {
30
+ if (shared) {
31
+ return { changes: [{ path, content: withBlock(current, body) }], skipped: [], warnings: [] };
32
+ }
33
+ const rest = current === undefined ? current : withoutBlock(current);
34
+ if (rest === undefined || rest === current) {
35
+ return EMPTY_PLAN;
36
+ }
37
+ return { changes: [rest === '' ? { path, remove: true } : { path, content: rest }], skipped: [], warnings: [] };
38
+ }
39
+ //# sourceMappingURL=instructions-block.js.map
@@ -0,0 +1,39 @@
1
+ import { join } from 'node:path';
2
+ import { ownership } from './generated-file.js';
3
+ /**
4
+ * Writes every skill to its directory, unless the file there is the user's or was edited after install (then only
5
+ * with `force`). A personal install takes untouched copies out of the project; a shared one keeps the personal ones,
6
+ * which serve other projects.
7
+ */
8
+ export function skillsPlan(skills, target) {
9
+ const { files, shared, force } = target;
10
+ const changes = [];
11
+ const skipped = [];
12
+ const dir = shared ? target.projectDir : target.userDir;
13
+ for (const skill of skills) {
14
+ const path = join(dir, skill.id, 'SKILL.md');
15
+ const current = files.read(path);
16
+ const owner = current === undefined ? 'ours' : ownership(current);
17
+ if (owner === 'foreign') {
18
+ skipped.push({ path, reason: 'not created by estimetry, left as it is' });
19
+ }
20
+ else if (owner === 'edited' && !force) {
21
+ skipped.push({ path, reason: 'edited after install; run init --force to overwrite it' });
22
+ }
23
+ else {
24
+ changes.push({ path, content: target.render(skill) });
25
+ }
26
+ if (!shared) {
27
+ const inProject = join(target.projectDir, skill.id, 'SKILL.md');
28
+ const text = files.read(inProject);
29
+ if (text !== undefined && ownership(text) === 'ours') {
30
+ changes.push({ path: inProject, remove: true });
31
+ }
32
+ else if (text !== undefined && ownership(text) === 'edited') {
33
+ skipped.push({ path: inProject, reason: 'edited after install, so it stays in the project' });
34
+ }
35
+ }
36
+ }
37
+ return { changes, skipped, warnings: [] };
38
+ }
39
+ //# sourceMappingURL=skills-plan.js.map
@@ -1,10 +1,21 @@
1
1
  import { presenterFor } from '../cli-context.js';
2
2
  import { parseLabels } from '../parse-input.js';
3
+ /** The settings `emt calibrate` follows: help names them, the README shows what to expect from each. */
4
+ const SETTINGS_HELP = `
5
+ Settings (config.yaml in ~/.local/share/estimetry, or in $ESTIMETRY_HOME):
6
+ calibration.minTasks a slice counts from this many closed tasks; with fewer
7
+ in all your tasks there is no coefficient (default 1)
8
+ calibration.shrink k in the weight n / (n + k) of a slice: larger is more
9
+ cautious, 0 applies the median as it is (default 2)
10
+ minTasks set without shrink means shrink: 0; minTasks: 5 alone gives the
11
+ coefficients of 0.2. Change them and run calibrate again: it recomputes from
12
+ your cards at once. The README shows what to expect from each setting.`;
3
13
  export function registerCalibrateCommand(program, ctx) {
4
14
  program
5
15
  .command('calibrate')
6
16
  .helpGroup('Tasks and estimates')
7
17
  .description('show your coefficients for a type and a stack, and the one an estimate may apply')
18
+ .addHelpText('after', SETTINGS_HELP)
8
19
  .option('--type <type>', 'task type of the task being estimated')
9
20
  .option('--stack <labels>', 'comma-separated technologies the task touches; defaults to the stack of the project')
10
21
  .option('--revise', 'for a revision of a task in progress: the coefficient of estimates made during work')
@@ -17,7 +17,7 @@ export async function runHook(args, run) {
17
17
  event,
18
18
  payload,
19
19
  cwd: run.cwd,
20
- ...(run.projectDir === undefined || run.projectDir === '' ? {} : { projectDir: run.projectDir }),
20
+ environment: run.environment,
21
21
  });
22
22
  if (output !== undefined) {
23
23
  run.out.print(output);
@@ -3,10 +3,7 @@ import { presenterFor } from '../cli-context.js';
3
3
  import { Prompts } from '../prompts.js';
4
4
  /** Shown in the questions so users see where estimetry is going; not registered until they work. */
5
5
  const COMING_SOON = {
6
- tools: [
7
- { value: 'codex', label: 'Codex' },
8
- { value: 'cursor', label: 'Cursor' },
9
- ],
6
+ tools: [{ value: 'cursor', label: 'Cursor' }],
10
7
  flows: [
11
8
  { value: 'spec-kit', label: 'GitHub Spec Kit' },
12
9
  { value: 'custom', label: 'Your own, from .estimetry/flow.yaml' },
@@ -22,13 +19,15 @@ export function registerInitCommand(program, ctx) {
22
19
  .command('init')
23
20
  .helpGroup('Setup')
24
21
  .description('set up estimetry in this project: hooks, skills and commands of the AI tool, project config')
25
- .option('--tools <ids>', 'AI tools, comma-separated (claude-code)')
22
+ .option('--tools <ids>', 'AI tools, comma-separated: claude-code, codex (default: installed, else found on this machine)')
26
23
  .option('--flow <id>', 'development process: openspec or none (default: detected)')
27
24
  .option('--share <mode>', `sharing with the team: ${SHARE_MODES.join(', ')}`)
28
25
  .option('--track-commits', 'install a git post-commit hook')
29
26
  .option('--no-track-commits', 'remove the git post-commit hook')
30
27
  .option('--shared-hooks', 'install for the whole team, into files the project commits')
31
28
  .option('--no-shared-hooks', 'install for yourself only (default)')
29
+ .option('--trust-hooks', 'trust the hooks in tools that ask for it (Codex) and let its task commands run outside their sandbox')
30
+ .option('--no-trust-hooks', 'trust nothing, take away the rule for the task commands (without either flag: kept as it is)')
32
31
  .option('--force', 'overwrite generated skills you have edited')
33
32
  .option('--no-interactive', 'do not ask; use flags and defaults')
34
33
  .option('--json', 'print JSON')
@@ -46,6 +45,7 @@ function fromFlags(options) {
46
45
  ...(options.share === undefined ? {} : { share: options.share }),
47
46
  ...(options.trackCommits === undefined ? {} : { trackCommits: options.trackCommits }),
48
47
  ...(options.sharedHooks === undefined ? {} : { shared: options.sharedHooks }),
48
+ ...(options.trustHooks === undefined ? {} : { trustHooks: options.trustHooks }),
49
49
  ...(options.force ? { force: true } : {}),
50
50
  };
51
51
  }
@@ -58,7 +58,10 @@ async function ask(ctx, choices, options) {
58
58
  if (input.tools === undefined) {
59
59
  input.tools = await prompts.multiSelect('AI tools', [
60
60
  ...choices.tools.map((tool) => ({ value: tool.id, label: tool.title })),
61
- ...COMING_SOON.tools.map((tool) => ({ ...tool, disabled: true })),
61
+ // A tool that is registered is never "coming soon", even if this list lags behind.
62
+ ...COMING_SOON.tools
63
+ .filter((soon) => !choices.tools.some((tool) => tool.id === soon.value))
64
+ .map((tool) => ({ ...tool, disabled: true })),
62
65
  ], defaults.tools);
63
66
  }
64
67
  if (input.flow === undefined) {
@@ -73,9 +76,15 @@ async function ask(ctx, choices, options) {
73
76
  if (input.trackCommits === undefined) {
74
77
  input.trackCommits = await prompts.confirm('Install a git post-commit hook to link commits to tasks?', defaults.trackCommits);
75
78
  }
79
+ const asking = choices.tools.filter((tool) => tool.asksTrust && (input.tools ?? defaults.tools).includes(tool.id));
80
+ if (input.trustHooks === undefined && asking.length > 0) {
81
+ const titles = asking.map((tool) => tool.title).join(', ');
82
+ input.trustHooks = await prompts.confirm(`${titles} runs a hook only after you trust it, and the agent's commands in a sandbox. ` +
83
+ 'Trust the estimetry hooks and let its task commands (emt start, extra, close…) run outside the sandbox?', true);
84
+ }
76
85
  const shared = input.shared ?? defaults.shared;
77
86
  if (!shared && choices.unignoredPersonalFiles.length > 0) {
78
- input.excludePersonalFiles = await prompts.confirm(`${choices.unignoredPersonalFiles.join(', ')} is not ignored by git. Add it to your global git excludes, as Claude Code does?`, true);
87
+ input.excludePersonalFiles = await prompts.confirm(`${choices.unignoredPersonalFiles.join(', ')} is not ignored by git. Add it to your global git excludes?`, true);
79
88
  }
80
89
  return input;
81
90
  }
@@ -8,8 +8,11 @@ export function registerStatusCommand(program, ctx) {
8
8
  .argument('[task]', 'task id; defaults to the only task in progress in this project')
9
9
  .option('--json', 'print JSON (durations in minutes)')
10
10
  .action(async (id, options) => {
11
- const view = (await ctx.app()).measuring.status({ ...parseTaskOption(id), near: ctx.cwd });
12
- ctx.out.print(presenterFor(options).status(view));
11
+ const app = await ctx.app();
12
+ const view = app.measuring.status({ ...parseTaskOption(id), near: ctx.cwd });
13
+ const presenter = presenterFor(options);
14
+ ctx.out.print(presenter.status(view));
15
+ presenter.notices.tools(app.project.notices()).forEach((line) => ctx.out.error(line));
13
16
  });
14
17
  }
15
18
  //# sourceMappingURL=status-command.js.map
@@ -105,7 +105,9 @@ export function formatHelp(command, helper) {
105
105
  }
106
106
  if (root) {
107
107
  out.push('Options:', ...helper.visibleOptions(command).map((option) => row(` ${optionTerm(option)}`, optionText(option))));
108
- out.push(` Most commands print JSON with --json.`, '');
108
+ out.push(` Most commands print JSON with --json.`);
109
+ out.push(` Settings: config.yaml in ~/.local/share/estimetry, or in $ESTIMETRY_HOME;`);
110
+ out.push(` those of calibration: "${name} help calibrate".`, '');
109
111
  out.push('Examples:', ...EXAMPLES.map((example) => ` ${example.split(' && ').map((part) => `${name} ${part}`).join(' && ')}`), '');
110
112
  out.push(`Run "${name} <command> --help" for details, e.g. "${name} help task new".`);
111
113
  }
@@ -92,14 +92,18 @@ export function usageRows(usage) {
92
92
  if (usage === null) {
93
93
  return [];
94
94
  }
95
- const cost = usage.costUSD === null ? 'unknown' : `$${usage.costUSD.toFixed(2)}${usage.approximate ? ' (approximate: split by tokens)' : ''}`;
95
+ const withCost = usage.withCost ?? usage.withLogs;
96
+ const unknown = withCost === 0 ? 'not reported' : 'unknown';
97
+ const cost = usage.costUSD === null ? unknown : `$${usage.costUSD.toFixed(2)}${usage.approximate ? ' (approximate: split by tokens)' : ''}`;
98
+ // A tool without a cost (Codex): the cost stands for fewer sessions than the tokens.
99
+ const costFrom = withCost < usage.withLogs ? `, cost from ${withCost} of ${usage.sessions} sessions` : '';
96
100
  const models = Object.entries(usage.tokens).map(([model, t]) => {
97
- const cacheWrite = tokenCount(t.cacheWrite5m + t.cacheWrite1h);
101
+ const cacheWrite = tokenCount(t.cacheWrite5m + t.cacheWrite1h + (t.cacheWrite ?? 0));
98
102
  const read = `in ${tokenCount(t.input)}, out ${tokenCount(t.output)}, cache read ${tokenCount(t.cacheRead)}`;
99
103
  return [` ${model}`, `${read}, cache write ${cacheWrite}`];
100
104
  });
101
105
  return [
102
- ['cost', `${cost}, from the logs of ${usage.withLogs} of ${usage.sessions} sessions`],
106
+ ['cost', `${cost}, from the logs of ${usage.withLogs} of ${usage.sessions} sessions${costFrom}`],
103
107
  ...(models.length === 0 ? [] : [['tokens', ''], ...models]),
104
108
  ];
105
109
  }