estimetry 0.2.0 → 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.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,17 @@ All notable changes to estimetry. Versions follow [semantic versioning](https://
4
4
 
5
5
  ## Unreleased
6
6
 
7
+ ## 0.3.0 — 2026-11-22
8
+
9
+ - **Calibration from the first closed task.** The coefficient an estimate applies is the median of fact over estimate shrunk towards 1 with the weight n / (n + k) (`calibration.shrink`, 2 by default), instead of nothing until a slice has 5 tasks. The slices form a chain — all your tasks, the technology of the query with the most tasks, the task type — each shrunk towards the one above by the tasks no deeper slice holds, so every task counts once; the deepest applies, and the overall slice now counts too. `emt calibrate` names the slice, the number of tasks and the weight.
10
+ - **Pessimistic coefficient.** `c · e^(ln 2 / √n)`, at most 1 while your estimates run high: the agent multiplies the pessimistic hours by it and the optimistic and most likely hours by the coefficient. The estimate file takes it as `calibration.pessimistic`; the base calibration compares with is still likely over the coefficient.
11
+ - **Without calibration** an estimate is now only when no task is closed yet, every closed task is left out or has no estimate, there are fewer tasks than your `calibration.minTasks`, or some cards come from a newer estimetry; `emt calibrate` says which.
12
+ - New defaults: `calibration.minTasks: 1`, `calibration.shrink: 2`. A `minTasks` you set without `shrink` means `shrink: 0`; `minTasks: 5` alone gives the coefficient of earlier versions wherever they gave one, and the median of all your tasks where neither the type nor a technology has 5; the pessimistic hours get the pessimistic coefficient there too, a reserve earlier versions did not give. The README shows what to expect from each setting.
13
+ - `calibration.json` has schema 3: `weight` instead of `applicable` in every slice, and `shrink`. It is rewritten by the next closing or `emt rebuild`.
14
+ - `emt calibrate --json` has `schemaVersion: 2`: `coefficient` is `{ value, pessimistic, slice: { kind, key? }, n, weight }`, slices carry `weight` instead of `applicable`, and `shrink` sits beside `minTasks`.
15
+ - `emt calibrate --help` names `calibration.minTasks` and `calibration.shrink` with their defaults, and `emt --help` says where `config.yaml` lives.
16
+ - Run `emt upgrade` once: the skills are written again.
17
+
7
18
  ## 0.2.0 — 2026-11-21
8
19
 
9
20
  - **Codex.** `estimetry init --tools codex`, or picking Codex in `init`, sets up the hooks of Codex (in `~/.codex/hooks.json`, or `.codex/hooks.json` of the project with `--shared-hooks`) and the `emt-…` skills (in `~/.agents/skills`, or `.agents/skills`), called as `$emt-…`. Sessions of Codex are measured like those of Claude Code, and both tools may serve one task. Codex runs a hook only once you trust it, and the agent's commands in a sandbox: in a terminal `init` asks whether to trust the estimetry hooks and to let the task commands (`emt start`, `extra`, `close`…) out of the sandbox, and records both with yes or `--trust-hooks` (`~/.codex/config.toml`, `~/.codex/rules/estimetry.rules`). `emt upgrade` trusts again the hooks it changes when you trusted them before; `emt status` warns while they are not trusted. Requires Codex 0.145 or newer.
package/README.md CHANGED
@@ -33,7 +33,7 @@ To update later: `npm install -g estimetry@latest`, then `emt upgrade` once (see
33
33
 
34
34
  The skills are the same in both tools: Claude Code calls them as `/emt-…`, Codex as `$emt-…` (`$emt-estimate`, `$emt-start`). This README names them the Claude Code way.
35
35
 
36
- Every closed task makes the next estimate more grounded: `emt similar` finds past tasks like the new one, and `emt calibrate` gives your own coefficient once there are enough of them.
36
+ Every closed task makes the next estimate more grounded: `emt similar` finds past tasks like the new one, and `emt calibrate` gives your own coefficient from the first closed task, more confident with every next one.
37
37
 
38
38
  ## Help
39
39
 
@@ -134,8 +134,10 @@ emt calibrate --type feature --revise # for a revision of a task in progress
134
134
  ```
135
135
 
136
136
  - **Similarity** weighs the shared technologies (half), the type of the first estimate and, with `--hours`, the size. Each task shows what its similarity is made of. Without `--stack`, the stack of the project counts.
137
- - **The coefficient** is the median of fact over estimate of the first slice with enough closed tasks: by type, then by technology. The overall slice mixes every kind of work and is shown for reference only. With fewer tasks than `calibration.minTasks` (5 by default) the estimate is **without calibration**, and the agent says so.
138
- - **A calibrated estimate** multiplies all three numbers of every part by the coefficient and records it (`calibrated: true`, `calibration.coefficient`), so the next coefficient is computed from the estimate before it. A reserve goes only into the pessimistic hours: extra work you absorbed is already in the coefficient.
137
+ - **The coefficient** comes from the first closed task. It is the median of fact over estimate, shrunk towards 1 with the weight n / (n + k), `k` being `calibration.shrink` (2 by default): one task weighs ⅓, two ½, six ¾. The slices form a chain: all your tasks, the technology of the query with the most tasks, the task type. Each is shrunk towards the one above by the tasks no deeper slice holds, so every task counts once, and the deepest one applies. `emt calibrate` names the slice, the number of tasks and the weight; below 50% the agent tells you the coefficient is still cautious.
138
+ - **The pessimistic coefficient**, `c · e^(ln 2 / √n)`, keeps a reserve while the tasks are few; while your estimates run high (`c < 1`) it is at most 1.
139
+ - **Without calibration** the estimate is only when no task is closed yet, every closed task is left out or has no estimate, there are fewer than your `calibration.minTasks`, or some cards come from a newer estimetry. `emt calibrate` says which, and the agent tells you.
140
+ - **A calibrated estimate** multiplies the optimistic and most likely hours of every part by the coefficient and the pessimistic hours by the pessimistic coefficient, and records both (`calibrated: true`, `calibration.coefficient`, `calibration.pessimistic`), so the next coefficient is computed from the estimate before it. A reserve goes only into the pessimistic hours, on top of that: extra work you absorbed is already in the coefficient.
139
141
  - **Nothing is written** by `emt similar` and `emt calibrate`; `calibration.json` is updated by closings and `emt rebuild`.
140
142
  - **A changed email.** Calibration is personal, by `author.id` in `config.yaml`. List earlier ids so that their cards stay yours:
141
143
 
@@ -309,13 +311,53 @@ Names, descriptions and the retro sit in a separate `text` section of the card,
309
311
  - how well the code volume was forecast;
310
312
  - which kinds of parts run over.
311
313
 
312
- A coefficient based on fewer than 5 tasks is shown but not applied. Set the minimum in `config.yaml`:
314
+ Every slice has a weight, n / (n + k), next to its median and mean (see [Estimating a task](#estimating-a-task) for how the coefficient is built from them):
315
+
316
+ ```json
317
+ {
318
+ "schemaVersion": 3,
319
+ "minTasks": 1,
320
+ "shrink": 2,
321
+ "authors": {
322
+ "you@example.com": {
323
+ "tasks": 4,
324
+ "ratio": {
325
+ "overall": { "n": 4, "median": 0.5, "mean": 0.55, "weight": 0.667 },
326
+ "byType": { "feature": { "n": 3, "median": 0.6, "mean": 0.62, "weight": 0.6 } }
327
+ }
328
+ }
329
+ }
330
+ }
331
+ ```
332
+
333
+ **Settings.** Two settings in `~/.local/share/estimetry/config.yaml` (under `ESTIMETRY_HOME` if you set it) decide how soon calibration starts and how strongly it acts:
313
334
 
314
335
  ```yaml
315
336
  calibration:
316
- minTasks: 5
337
+ minTasks: 1 # a slice counts from this many closed tasks; below it in all your tasks, no coefficient
338
+ shrink: 2 # k in n / (n + k): larger is more cautious, 0 applies the median as it is
317
339
  ```
318
340
 
341
+ Setting `minTasks` without `shrink` means `shrink: 0`: a threshold you chose yourself keeps the coefficient it gave.
342
+
343
+ **What to expect.** Say every closed task took half of its estimate (fact over estimate 0.5), all of one type and technology. The coefficient and the pessimistic coefficient after 1, 3, 5 and 10 closed tasks (— is without calibration):
344
+
345
+ | Settings | 1 task | 3 tasks | 5 tasks | 10 tasks |
346
+ |---|---|---|---|---|
347
+ | default: `minTasks: 1`, `shrink: 2` | ×0.79 / ×1.00 | ×0.66 / ×0.98 | ×0.61 / ×0.83 | ×0.56 / ×0.70 |
348
+ | faster: `shrink: 1` | ×0.71 / ×1.00 | ×0.59 / ×0.89 | ×0.56 / ×0.77 | ×0.53 / ×0.66 |
349
+ | more cautious: `shrink: 5` | ×0.89 / ×1.00 | ×0.77 / ×1.00 | ×0.71 / ×0.96 | ×0.63 / ×0.78 |
350
+ | later start: `minTasks: 3`, `shrink: 2` | — | ×0.66 / ×0.98 | ×0.61 / ×0.83 | ×0.56 / ×0.70 |
351
+ | as in 0.2: `minTasks: 5` | — | — | ×0.50 / ×0.68 | ×0.50 / ×0.62 |
352
+ | the median as it is: `shrink: 0` | ×0.50 / ×1.00 | ×0.50 / ×0.75 | ×0.50 / ×0.68 | ×0.50 / ×0.62 |
353
+
354
+ - The coefficient moves from 1 towards your median as tasks close; `shrink` sets how fast. The pessimistic coefficient stays at 1 while there is little experience and comes down to the coefficient with it.
355
+ - When your estimates run low, nothing caps the pessimistic coefficient: with fact over estimate 1.5 the default gives ×1.14 / ×2.29 after one task and ×1.40 / ×1.75 after ten.
356
+ - With tasks of several types and technologies the coefficient comes from the chain of slices: the tasks of the type weigh by their number, your other tasks fill in the rest of the weight, and what is still missing stays at 1.
357
+ - `minTasks: 5` gives the coefficient of earlier versions wherever they gave one, with two differences. When neither the type nor a technology has 5 tasks, the median of all your tasks applies, where earlier versions gave none. The pessimistic hours are multiplied by the pessimistic coefficient, not by the coefficient, so they keep a reserve earlier versions did not give.
358
+
359
+ **Changing them.** Edit `config.yaml` and run `emt calibrate --type <type> --stack <a,b>`: it computes from your cards at once and names the coefficient, the slice, the number of tasks and the weight. Estimates already saved keep their coefficient. `calibration.json` follows at the next closing or with `emt rebuild`, which also rewrites a `calibration.json` of an earlier schema.
360
+
319
361
  Tasks in parallel mode count with their sequential equivalent. Abandoned tasks and tasks with manual time only are left out.
320
362
 
321
363
  Revised tasks give two accuracies:
@@ -1,13 +1,14 @@
1
1
  import { applicableCoefficient } from '../../domain/calibration/applicable-coefficient.js';
2
- import { calibrate, normalized, } from '../../domain/calibration/calibration.js';
2
+ import { authorCards, calibrate, } from '../../domain/calibration/calibration.js';
3
3
  import { otherAuthors } from '../../domain/calibration/other-authors.js';
4
4
  import { estimateQuery } from './estimate-query.js';
5
- export const CALIBRATION_VIEW_SCHEMA_VERSION = 1;
5
+ /** 2: the coefficient with its pessimistic value and weight, the weight of a slice instead of `applicable` (dynamic-calibration). */
6
+ export const CALIBRATION_VIEW_SCHEMA_VERSION = 2;
6
7
  const NO_TASKS = {
7
8
  n: 0,
8
9
  median: null,
9
10
  mean: null,
10
- applicable: false,
11
+ weight: 0,
11
12
  excluded: {},
12
13
  uncertain: 0,
13
14
  backgroundAgents: 0,
@@ -35,10 +36,10 @@ export class ShowCalibration {
35
36
  const { cards, skipped } = this.cards.allCards();
36
37
  const author = this.authors.current();
37
38
  const aliases = this.authors.toCurrent();
38
- const minTasks = this.settings.minTasks();
39
+ const policy = this.settings.policy();
39
40
  // Only the author's section is shown: other authors' cards are not computed at all.
40
- const own = normalized(cards, aliases).filter((card) => card.author === author);
41
- const mine = calibrate(own, { minTasks }).authors[author];
41
+ const own = authorCards(cards, author, aliases);
42
+ const mine = calibrate(own, { policy }).authors[author];
42
43
  const revise = input.revise === true;
43
44
  const type = query.type?.value;
44
45
  const pick = (slices, empty) => ({
@@ -50,8 +51,11 @@ export class ShowCalibration {
50
51
  schemaVersion: CALIBRATION_VIEW_SCHEMA_VERSION,
51
52
  query: { type: type ?? null, stack: [...query.stack.values], revise },
52
53
  // A calibration from an incomplete set of cards could give a wrong coefficient.
53
- coefficient: skipped.length > 0 ? null : applicableCoefficient(mine, { ...(type === undefined ? {} : { type }), stack: query.stack, revise }),
54
- minTasks,
54
+ coefficient: skipped.length > 0
55
+ ? null
56
+ : applicableCoefficient(cards, { author, aliases, estimate: query, revise }, policy),
57
+ minTasks: policy.minTasks,
58
+ shrink: policy.shrink,
55
59
  tasks: mine?.tasks ?? 0,
56
60
  ratio: pick(mine?.ratio, NO_TASKS),
57
61
  revised: pick(mine?.revised, { ...NO_TASKS, countedAtShare: null }),
@@ -53,7 +53,7 @@ export class TaskCards {
53
53
  }
54
54
  const cards = stored.map((card) => card.schema === 'current' ? card.card : card.schema === 'newer' ? undefined : this.upgrade(card.card));
55
55
  // A card that cannot be read even by its fields is left out, as a broken file is.
56
- return calibrate(cards.filter((card) => card !== undefined), { minTasks: this.settings.minTasks(), aliases: this.aliases.toCurrent() });
56
+ return calibrate(cards.filter((card) => card !== undefined), { policy: this.settings.policy(), aliases: this.aliases.toCurrent() });
57
57
  });
58
58
  }
59
59
  /**
@@ -1,26 +1,42 @@
1
+ import { authorCards } from './calibration.js';
2
+ import { levelParts } from './level-parts.js';
3
+ import { ratioSampling } from './ratio-samples.js';
4
+ import { median, round } from './statistics.js';
5
+ /** The spread of the ratio in logarithms the pessimistic coefficient reserves for: a factor of 2 at one task. */
6
+ const SIGMA = Math.log(2);
1
7
  /**
2
- * The coefficient an estimate may apply (calibration-query spec): the first
3
- * slice with enough tasks — by type, then by the technology with the most
4
- * tasks. The overall slice mixes every type and stack, so it is never applied.
5
- * A new estimate takes the main ratio; a revision of a task in progress, `revised`.
8
+ * The coefficient an estimate may apply (calibration-query spec), from all the
9
+ * cards: the author's are taken as calibration takes them (`authorCards`).
10
+ * Going down the levels (`levelParts`), each part shrinks towards the level
11
+ * above in logarithms by the weight of its own tasks; the overall part towards
12
+ * 1, an empty part equals the level above. The deepest level is applied: its
13
+ * part is its whole slice. A new estimate takes the main ratio; a revision of
14
+ * a task in progress, `revised`.
6
15
  */
7
- export function applicableCoefficient(author, query) {
8
- if (author === undefined) {
16
+ export function applicableCoefficient(cards, query, policy) {
17
+ const own = authorCards(cards, query.author, query.aliases);
18
+ const parts = levelParts(ratioSampling(own, query.revise === true), query.estimate, policy);
19
+ const applied = parts.at(-1);
20
+ if (applied === undefined) {
9
21
  return null;
10
22
  }
11
- const slices = query.revise ? author.revised : author.ratio;
12
- const usable = (stats) => stats?.applicable === true && stats.median !== null;
13
- const byType = query.type === undefined ? undefined : slices.byType[query.type];
14
- if (query.type !== undefined && usable(byType)) {
15
- return { value: byType.median, slice: { kind: 'type', key: query.type }, n: byType.n };
23
+ let logarithm = 0;
24
+ for (const part of parts) {
25
+ const middle = median(part.ratios);
26
+ if (middle !== null) {
27
+ const weight = policy.partWeight(part.ratios.length);
28
+ logarithm = weight * Math.log(middle) + (1 - weight) * logarithm;
29
+ }
16
30
  }
17
- const stacks = query.stack.values
18
- .flatMap((key) => {
19
- const stats = slices.byStack[key];
20
- return usable(stats) ? [{ key, stats }] : [];
21
- })
22
- .sort((a, b) => b.stats.n - a.stats.n || a.key.localeCompare(b.key));
23
- const best = stacks[0];
24
- return best === undefined ? null : { value: best.stats.median, slice: { kind: 'stack', key: best.key }, n: best.stats.n };
31
+ const n = applied.ratios.length;
32
+ const value = Math.exp(logarithm);
33
+ const upper = value * Math.exp(SIGMA / Math.sqrt(n));
34
+ return {
35
+ value: round(value),
36
+ pessimistic: round(value < 1 ? Math.min(1, upper) : upper),
37
+ slice: applied.slice,
38
+ n,
39
+ weight: round(policy.partWeight(n)),
40
+ };
25
41
  }
26
42
  //# sourceMappingURL=applicable-coefficient.js.map
@@ -0,0 +1,39 @@
1
+ export const DEFAULT_MIN_TASKS = 1;
2
+ export const DEFAULT_SHRINK = 2;
3
+ /**
4
+ * How calibration weighs a slice (calibration spec): from `calibration.minTasks`
5
+ * tasks a slice has the weight n / (n + k) with k = `calibration.shrink` and is a
6
+ * level of the coefficient; each level is shrunk towards the one above by the
7
+ * weight of its own tasks (`partWeight`).
8
+ */
9
+ export class CalibrationPolicy {
10
+ minTasks;
11
+ shrink;
12
+ constructor(minTasks, shrink) {
13
+ this.minTasks = minTasks;
14
+ this.shrink = shrink;
15
+ }
16
+ static DEFAULT = new CalibrationPolicy(DEFAULT_MIN_TASKS, DEFAULT_SHRINK);
17
+ /**
18
+ * The settings of `config.yaml`; an invalid value counts as not given. A
19
+ * threshold chosen without `shrink` means no shrinking: the user who picked
20
+ * the sample a coefficient needs keeps the coefficient they had.
21
+ */
22
+ static fromConfig(given) {
23
+ const minTasks = given.minTasks !== undefined && Number.isInteger(given.minTasks) && given.minTasks >= 1 ? given.minTasks : undefined;
24
+ const shrink = given.shrink !== undefined && Number.isFinite(given.shrink) && given.shrink >= 0 ? given.shrink : undefined;
25
+ return new CalibrationPolicy(minTasks ?? DEFAULT_MIN_TASKS, shrink ?? (minTasks === undefined ? DEFAULT_SHRINK : 0));
26
+ }
27
+ /** The weight of the observations of a slice of n tasks: 0 below `minTasks`. */
28
+ weight(n) {
29
+ return n < this.minTasks ? 0 : this.partWeight(n);
30
+ }
31
+ /**
32
+ * The weight of the own tasks of a level in the chain, n / (n + k), without
33
+ * the threshold: `minTasks` is checked on the whole slice. 0 without tasks.
34
+ */
35
+ partWeight(n) {
36
+ return n === 0 ? 0 : n / (n + this.shrink);
37
+ }
38
+ }
39
+ //# sourceMappingURL=calibration-policy.js.map
@@ -1,22 +1,22 @@
1
1
  import { stackLabels } from '../estimate/stack-labels.js';
2
- import { exclusion, ratioOf, revisedExclusion, revisedRatioOf } from './task-ratio.js';
2
+ import { ratioSampling } from './ratio-samples.js';
3
3
  import { EXTRA_CATEGORIES } from '../measurement/extra.js';
4
4
  import { isRevised, linesPerHour, partsByKind, volumeAccuracy, } from './code-and-parts.js';
5
5
  import { median, round } from './statistics.js';
6
- /** 2: the sections of revised tasks and revisions (estimate-revision-cards); readers check the version. */
7
- export const CALIBRATION_SCHEMA_VERSION = 2;
8
- export const DEFAULT_MIN_TASKS = 5;
6
+ import { CalibrationPolicy } from './calibration-policy.js';
7
+ /** 3: the weight of a slice instead of `applicable`, and `shrink` (dynamic-calibration); readers check the version. */
8
+ export const CALIBRATION_SCHEMA_VERSION = 3;
9
9
  const UNCERTAINTY_LIMIT = 0.05;
10
10
  /** Calibration from the cards of closed tasks, by author (design §10, calibration spec). */
11
11
  export function calibrate(all, options = {}) {
12
- const minTasks = options.minTasks ?? DEFAULT_MIN_TASKS;
12
+ const policy = options.policy ?? CalibrationPolicy.DEFAULT;
13
13
  const cards = normalized(all, options.aliases);
14
14
  const authors = {};
15
15
  const byId = new Map(cards.map((card) => [card.task.id, card]));
16
16
  for (const author of [...new Set(cards.map((card) => card.author))].sort()) {
17
- authors[author] = forAuthor(cards.filter((card) => card.author === author), byId, minTasks);
17
+ authors[author] = forAuthor(cards.filter((card) => card.author === author), byId, policy);
18
18
  }
19
- return { schemaVersion: CALIBRATION_SCHEMA_VERSION, minTasks, authors };
19
+ return { schemaVersion: CALIBRATION_SCHEMA_VERSION, minTasks: policy.minTasks, shrink: policy.shrink, authors };
20
20
  }
21
21
  /**
22
22
  * Cards as calibration compares them: a card of an alias is the author's
@@ -29,20 +29,23 @@ export function normalized(cards, aliases = new Map()) {
29
29
  task: { ...card.task, stack: stackLabels(card.task.stack) },
30
30
  }));
31
31
  }
32
- function forAuthor(cards, byId, minTasks) {
32
+ /** The cards of one author as calibration compares them (`normalized`): the cards of their aliases included. */
33
+ export function authorCards(cards, author, aliases) {
34
+ return normalized(cards, aliases).filter((card) => card.author === author);
35
+ }
36
+ function forAuthor(cards, byId, policy) {
33
37
  const estimated = cards.filter((card) => card.estimate !== null);
34
- const main = sampled(estimated, exclusion, ratioOf);
35
- const revisedCards = estimated.filter(isRevised);
36
- const later = sampled(revisedCards, revisedExclusion, revisedRatioOf);
38
+ const main = ratioSampling(cards, false);
39
+ const later = ratioSampling(cards, true);
37
40
  const kept = main.samples.map((sample) => sample.card);
38
41
  // Rolled back work leaves lines that say nothing about the volume of the task.
39
42
  const volumeCards = kept.filter((card) => !hasExclude(card) && !(card.convertedFrom === 1 && card.revised));
40
43
  const volumeExcluded = kept.length - volumeCards.length;
41
44
  return {
42
45
  tasks: cards.length,
43
- ratio: slices(main, (card) => card.estimate?.type, (samples, reasons) => ratioStats(samples, reasons, minTasks)),
44
- revised: slices(later, (card) => card.currentEstimate?.type, (samples, reasons) => ({
45
- ...ratioStats(samples, reasons, minTasks, (card) => card.fact.counted.uncertaintyShare),
46
+ ratio: slices(main, (samples, reasons) => ratioStats(samples, reasons, policy)),
47
+ revised: slices(later, (samples, reasons) => ({
48
+ ...ratioStats(samples, reasons, policy, (card) => card.fact.counted.uncertaintyShare),
46
49
  countedAtShare: median(samples.flatMap(({ card }) => {
47
50
  const at = card.revisions.at(-1)?.countedAtMinutes;
48
51
  return at === undefined || card.fact.counted.totalMinutes === 0 ? [] : [at / card.fact.counted.totalMinutes];
@@ -63,29 +66,11 @@ function forAuthor(cards, byId, minTasks) {
63
66
  function hasExclude(card) {
64
67
  return card.revisions.some((revision) => revision.spent === 'exclude');
65
68
  }
66
- function sampled(cards, exclude, ratio) {
67
- const samples = [];
68
- const excluded = [];
69
- for (const card of cards) {
70
- const reason = exclude(card);
71
- if (reason !== undefined) {
72
- excluded.push({ card, reason });
73
- continue;
74
- }
75
- const value = ratio(card);
76
- if (value === undefined) {
77
- excluded.push({ card, reason: 'renegotiated-without-groups' });
78
- }
79
- else {
80
- samples.push({ card, ratio: value });
81
- }
82
- }
83
- return { samples, excluded };
84
- }
85
69
  /** Overall, by type and by each technology of the stack. */
86
- function slices(sampled, typeOf, stats) {
70
+ function slices(sampled, stats) {
87
71
  const all = [...sampled.samples.map((s) => s.card), ...sampled.excluded.map((e) => e.card)];
88
72
  const slice = (keep) => stats(sampled.samples.filter((sample) => keep(sample.card)), sampled.excluded.filter((item) => keep(item.card)).map((item) => item.reason));
73
+ const typeOf = sampled.typeOf;
89
74
  const types = [...new Set(all.flatMap((card) => typeOf(card) ?? []))].sort();
90
75
  const stacks = [...new Set(all.flatMap((card) => card.task.stack))].sort();
91
76
  return {
@@ -129,7 +114,7 @@ function revisionStats(cards) {
129
114
  }
130
115
  return { byType, excluded: fromV1 === 0 ? {} : { 'card-v1': fromV1 } };
131
116
  }
132
- function ratioStats(samples, reasons, minTasks, uncertaintyOf = (card) => card.fact.uncertaintyShare) {
117
+ function ratioStats(samples, reasons, policy, uncertaintyOf = (card) => card.fact.uncertaintyShare) {
133
118
  const ratios = samples.map((sample) => sample.ratio);
134
119
  const excluded = {};
135
120
  for (const reason of reasons) {
@@ -139,7 +124,7 @@ function ratioStats(samples, reasons, minTasks, uncertaintyOf = (card) => card.f
139
124
  n: ratios.length,
140
125
  median: median(ratios),
141
126
  mean: ratios.length === 0 ? null : round(ratios.reduce((a, b) => a + b, 0) / ratios.length),
142
- applicable: ratios.length >= minTasks,
127
+ weight: round(policy.weight(ratios.length)),
143
128
  excluded,
144
129
  uncertain: samples.filter((sample) => (uncertaintyOf(sample.card) ?? 0) > UNCERTAINTY_LIMIT).length,
145
130
  backgroundAgents: samples.filter((sample) => sample.card.backgroundAgents).length,
@@ -0,0 +1,41 @@
1
+ /**
2
+ * The levels of the coefficient, from overall to the deepest, each with the
3
+ * tasks it alone counts (calibration-query spec). A level counts when its whole
4
+ * slice has a weight above 0; the overall slice, the technology of the query
5
+ * with the most tasks (the first alphabetically on a tie), the type of the
6
+ * query. The deepest level takes all of its tasks, each level above only those
7
+ * no deeper level holds: every task counts once. Without a weight in the
8
+ * overall slice there are no levels.
9
+ */
10
+ export function levelParts(sampling, query, policy) {
11
+ const levels = levelsOf(sampling, query, policy);
12
+ const deeper = new Set();
13
+ const parts = [];
14
+ for (const level of [...levels].reverse()) {
15
+ const own = level.samples.filter((sample) => !deeper.has(sample.card));
16
+ own.forEach((sample) => deeper.add(sample.card));
17
+ parts.unshift({ slice: level.slice, ratios: own.map((sample) => sample.ratio) });
18
+ }
19
+ return parts;
20
+ }
21
+ function levelsOf(sampling, query, policy) {
22
+ const level = (slice, keep) => {
23
+ const samples = sampling.samples.filter((sample) => keep(sample.card));
24
+ return policy.weight(samples.length) > 0 ? [{ slice, samples }] : [];
25
+ };
26
+ const overall = level({ kind: 'overall' }, () => true);
27
+ if (overall.length === 0) {
28
+ return [];
29
+ }
30
+ const technology = query.stack.values
31
+ .flatMap((key) => level({ kind: 'stack', key }, (card) => card.task.stack.includes(key)))
32
+ .sort((a, b) => b.samples.length - a.samples.length || keyOf(a.slice).localeCompare(keyOf(b.slice)))
33
+ .slice(0, 1);
34
+ const type = query.type?.value;
35
+ const byType = type === undefined ? [] : level({ kind: 'type', key: type }, (card) => sampling.typeOf(card) === type);
36
+ return [...overall, ...technology, ...byType];
37
+ }
38
+ function keyOf(slice) {
39
+ return slice.kind === 'overall' ? '' : slice.key;
40
+ }
41
+ //# sourceMappingURL=level-parts.js.map
@@ -0,0 +1,34 @@
1
+ import { isRevised } from './code-and-parts.js';
2
+ import { exclusion, ratioOf, revisedExclusion, revisedRatioOf } from './task-ratio.js';
3
+ /**
4
+ * Which cards a ratio counts and with what value (calibration spec): the main
5
+ * ratio — whole fact over the first estimate; `revised` — counted fact over the
6
+ * current estimate of revised tasks. Calibration slices and the applicable
7
+ * coefficient both take it from here.
8
+ */
9
+ export function ratioSampling(cards, revised) {
10
+ const estimated = cards.filter((card) => card.estimate !== null);
11
+ return revised
12
+ ? { ...sampled(estimated.filter(isRevised), revisedExclusion, revisedRatioOf), typeOf: (card) => card.currentEstimate?.type }
13
+ : { ...sampled(estimated, exclusion, ratioOf), typeOf: (card) => card.estimate?.type };
14
+ }
15
+ function sampled(cards, exclude, ratio) {
16
+ const samples = [];
17
+ const excluded = [];
18
+ for (const card of cards) {
19
+ const reason = exclude(card);
20
+ if (reason !== undefined) {
21
+ excluded.push({ card, reason });
22
+ continue;
23
+ }
24
+ const value = ratio(card);
25
+ if (value === undefined) {
26
+ excluded.push({ card, reason: 'renegotiated-without-groups' });
27
+ }
28
+ else {
29
+ samples.push({ card, ratio: value });
30
+ }
31
+ }
32
+ return { samples, excluded };
33
+ }
34
+ //# sourceMappingURL=ratio-samples.js.map
@@ -19,9 +19,12 @@ export class Estimate {
19
19
  basedOn;
20
20
  calibrated;
21
21
  coefficient;
22
+ pessimisticCoefficient;
22
23
  constructor(parts, type, stack, codeVolume, rationale, basedOn, calibrated,
23
- /** What calibration multiplied the estimate by; undefined when it was not applied. */
24
- coefficient) {
24
+ /** What calibration multiplied the optimistic and likely hours by; undefined when it was not applied. */
25
+ coefficient,
26
+ /** What calibration multiplied the pessimistic hours by; not part of the base of the estimate. */
27
+ pessimisticCoefficient) {
25
28
  this.parts = parts;
26
29
  this.type = type;
27
30
  this.stack = stack;
@@ -30,13 +33,23 @@ export class Estimate {
30
33
  this.basedOn = basedOn;
31
34
  this.calibrated = calibrated;
32
35
  this.coefficient = coefficient;
36
+ this.pessimisticCoefficient = pessimisticCoefficient;
33
37
  }
34
38
  /** @throws InvalidEstimate when there are no parts or part ids repeat. */
35
39
  static of(input) {
36
40
  const issues = [];
37
- if (input.coefficient !== undefined && !(Number.isFinite(input.coefficient) && input.coefficient > 0)) {
41
+ const positive = (value) => Number.isFinite(value) && value > 0;
42
+ if (input.coefficient === undefined ? input.pessimisticCoefficient !== undefined : !positive(input.coefficient)) {
38
43
  issues.push({ path: 'calibration.coefficient', message: 'expected a number greater than 0' });
39
44
  }
45
+ const pessimistic = input.pessimisticCoefficient;
46
+ if (pessimistic !== undefined && !positive(pessimistic)) {
47
+ issues.push({ path: 'calibration.pessimistic', message: 'expected a number greater than 0' });
48
+ }
49
+ else if (pessimistic !== undefined && input.coefficient !== undefined && pessimistic < input.coefficient) {
50
+ // `emt calibrate` never gives one below the other: the two are swapped.
51
+ issues.push({ path: 'calibration.pessimistic', message: 'expected no less than calibration.coefficient' });
52
+ }
40
53
  if (input.parts.length === 0) {
41
54
  issues.push({ path: 'parts', message: 'the estimate needs at least one part' });
42
55
  }
@@ -54,7 +67,7 @@ export class Estimate {
54
67
  throw new InvalidEstimate(issues);
55
68
  }
56
69
  const rationale = input.rationale?.trim() || undefined;
57
- return new Estimate([...input.parts], input.type?.trim() || undefined, stackLabels(input.stack ?? []), input.codeVolume, rationale, [...(input.basedOn ?? [])], input.calibrated ?? false, input.coefficient);
70
+ return new Estimate([...input.parts], input.type?.trim() || undefined, stackLabels(input.stack ?? []), input.codeVolume, rationale, [...(input.basedOn ?? [])], input.calibrated ?? false, input.coefficient, input.pessimisticCoefficient);
58
71
  }
59
72
  static fromData(data) {
60
73
  return Estimate.of({
@@ -66,6 +79,7 @@ export class Estimate {
66
79
  ...(data.basedOn === undefined ? {} : { basedOn: data.basedOn }),
67
80
  calibrated: data.calibrated,
68
81
  ...(data.calibration === undefined ? {} : { coefficient: data.calibration.coefficient }),
82
+ ...(data.calibration?.pessimistic === undefined ? {} : { pessimisticCoefficient: data.calibration.pessimistic }),
69
83
  });
70
84
  }
71
85
  /**
@@ -92,6 +106,9 @@ export class Estimate {
92
106
  get groups() {
93
107
  return groupsOf(this.parts);
94
108
  }
109
+ calibrationData(coefficient) {
110
+ return this.pessimisticCoefficient === undefined ? { coefficient } : { coefficient, pessimistic: this.pessimisticCoefficient };
111
+ }
95
112
  toData() {
96
113
  return {
97
114
  schemaVersion: ESTIMATE_SCHEMA_VERSION,
@@ -102,7 +119,7 @@ export class Estimate {
102
119
  ...(this.rationale === undefined ? {} : { rationale: this.rationale }),
103
120
  ...(this.basedOn.length === 0 ? {} : { basedOn: [...this.basedOn] }),
104
121
  calibrated: this.calibrated,
105
- ...(this.coefficient === undefined ? {} : { calibration: { coefficient: this.coefficient } }),
122
+ ...(this.coefficient === undefined ? {} : { calibration: this.calibrationData(this.coefficient) }),
106
123
  };
107
124
  }
108
125
  }
@@ -142,7 +142,7 @@ function isEstimateData(value) {
142
142
  !optional(value['basedOn'], isStringArray) ||
143
143
  !optionalString(value['rationale']) ||
144
144
  !optional(value['codeVolume'], isObject) ||
145
- !optional(value['calibration'], (c) => isObject(c) && typeof c['coefficient'] === 'number')) {
145
+ !optional(value['calibration'], (c) => isObject(c) && typeof c['coefficient'] === 'number' && optional(c['pessimistic'], (p) => typeof p === 'number'))) {
146
146
  return false;
147
147
  }
148
148
  try {
@@ -1,4 +1,4 @@
1
- import { DEFAULT_MIN_TASKS } from '../../domain/calibration/calibration.js';
1
+ import { CalibrationPolicy } from '../../domain/calibration/calibration-policy.js';
2
2
  import { isShareMode } from '../../application/ports/sharing-preference.js';
3
3
  import { IdlePolicy } from '../../domain/measurement/idle-policy.js';
4
4
  import { Author } from '../../domain/shared/author.js';
@@ -60,11 +60,12 @@ export class YamlConfigStore {
60
60
  problem: `${this.layout.configFile}: measurement.checkpointMinutes must be a whole number from 10 to 30; using ${DEFAULT_CHECKPOINT_MINUTES}`,
61
61
  };
62
62
  }
63
- /** `calibration.minTasks`: a whole number ≥ 1, 5 by default; anything else gives the default. */
64
- minTasks() {
63
+ /** `calibration.minTasks` and `calibration.shrink`; a value that is not a number counts as not given. */
64
+ policy() {
65
65
  const calibration = this.read()['calibration'];
66
- const value = typeof calibration === 'object' && calibration !== null ? calibration['minTasks'] : undefined;
67
- return typeof value === 'number' && Number.isInteger(value) && value >= 1 ? value : DEFAULT_MIN_TASKS;
66
+ const settings = typeof calibration === 'object' && calibration !== null ? calibration : {};
67
+ const number = (value) => (typeof value === 'number' ? value : undefined);
68
+ return CalibrationPolicy.fromConfig({ minTasks: number(settings['minTasks']), shrink: number(settings['shrink']) });
68
69
  }
69
70
  /** `author.aliases`: strings other than the author's own id; anything but a list counts as none. */
70
71
  authorAliases() {
@@ -74,7 +74,7 @@ class EstimateParser {
74
74
  this.issue('calibrated', 'expected true or false');
75
75
  }
76
76
  const codeVolume = this.codeVolume(value['codeVolume']);
77
- const coefficient = this.coefficient(value['calibration']);
77
+ const calibration = this.calibration(value['calibration']);
78
78
  if (this.issues.length > 0 || parts.some((part) => part === undefined)) {
79
79
  return undefined;
80
80
  }
@@ -86,24 +86,32 @@ class EstimateParser {
86
86
  ...(rationale === undefined ? {} : { rationale }),
87
87
  ...(codeVolume === undefined ? {} : { codeVolume }),
88
88
  calibrated: calibrated === true,
89
- ...(coefficient === undefined ? {} : { coefficient }),
89
+ ...calibration,
90
90
  }));
91
91
  }
92
- coefficient(value) {
92
+ calibration(value) {
93
93
  if (value === undefined) {
94
- return undefined;
94
+ return {};
95
95
  }
96
96
  if (!isObject(value)) {
97
97
  this.issue('calibration', 'expected a mapping with `coefficient`');
98
- return undefined;
99
- }
100
- this.unknownFields(value, ['coefficient'], 'calibration.');
101
- const coefficient = value['coefficient'];
102
- if (typeof coefficient !== 'number' || !(coefficient > 0)) {
103
- this.issue('calibration.coefficient', 'expected a number greater than 0');
104
- return undefined;
98
+ return {};
105
99
  }
106
- return coefficient;
100
+ this.unknownFields(value, ['coefficient', 'pessimistic'], 'calibration.');
101
+ const positive = (field) => {
102
+ const number = value[field];
103
+ if (typeof number !== 'number' || !(number > 0)) {
104
+ this.issue(`calibration.${field}`, 'expected a number greater than 0');
105
+ return undefined;
106
+ }
107
+ return number;
108
+ };
109
+ const coefficient = positive('coefficient');
110
+ const pessimistic = value['pessimistic'] === undefined ? undefined : positive('pessimistic');
111
+ return {
112
+ ...(coefficient === undefined ? {} : { coefficient }),
113
+ ...(pessimistic === undefined ? {} : { pessimisticCoefficient: pessimistic }),
114
+ };
107
115
  }
108
116
  part(value, path) {
109
117
  if (!isObject(value)) {
@@ -15,7 +15,7 @@ estimetry compares estimates with the actual effort of AI-agent development and
15
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:
16
16
  - agree with the user on the task type and the technologies the task really touches;
17
17
  - \`emt similar\` shows closed tasks like it, \`emt calibrate\` the user's coefficients and the one the estimate may apply;
18
- - 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;
19
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.
20
20
 
21
21
  ## Measuring
@@ -64,12 +64,14 @@ export const COMMANDS = [
64
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.
65
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.
66
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.
67
- 5. **Calibration.** \`emt calibrate --type <type> --stack <a,b> --json\`.
68
- - 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.
69
- - 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.
70
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\`:
71
72
  - with calibration, only for missed scope (\`missedScope\`): extra work absorbed by tasks is already in the coefficient;
72
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.
73
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.
74
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.
75
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.
@@ -80,14 +82,14 @@ export const COMMANDS = [
80
82
  stack: [typescript, node]
81
83
  basedOn: [T-12, T-17]
82
84
  calibrated: true
83
- calibration: { coefficient: 1.3 }
85
+ calibration: { coefficient: 1.23, pessimistic: 1.64 }
84
86
  rationale: Why the numbers are what they are, what they rest on, where the reserve is.
85
87
  parts:
86
88
  - name: implementation
87
89
  kind: implementation # analysis, implementation, auto-tests, manual-testing, review, docs, other
88
90
  who: agents # agents, user or both
89
91
  group: export-invoices-pdf # the change of the part, with a development flow
90
- hours: { optimistic: 2.6, likely: 3.9, pessimistic: 6.5 }
92
+ hours: { optimistic: 2.46, likely: 3.69, pessimistic: 6.56 }
91
93
  \`\`\`
92
94
 
93
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).
@@ -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')
@@ -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
  }
@@ -71,7 +71,7 @@ function queried(slices) {
71
71
  }
72
72
  export function calibrationText(view) {
73
73
  const slices = queried(view.ratio);
74
- const lines = [coefficientLine(view, slices)];
74
+ const lines = [coefficientLine(view)];
75
75
  lines.push('', 'Fact over the first estimate:');
76
76
  const ratioRows = [
77
77
  ['overall', statsText(view.ratio.overall)],
@@ -102,25 +102,41 @@ export function calibrationText(view) {
102
102
  lines.push(...cardNotes({ skipped: [], otherAuthors: view.otherAuthors }));
103
103
  return lines.join('\n');
104
104
  }
105
- /** The coefficient to apply, or why there is none. */
106
- function coefficientLine(view, slices) {
105
+ /** The coefficient to apply with what it rests on, or why there is none. */
106
+ function coefficientLine(view) {
107
107
  const coefficient = view.coefficient;
108
- const what = view.query.revise ? 'estimates made during work' : 'first estimates';
109
108
  if (coefficient !== null) {
110
- return (`Coefficient ×${coefficient.value} (${coefficient.slice.kind} ${coefficient.slice.key}, ${coefficient.n} tasks, ${what}): ` +
111
- 'multiply the optimistic, most likely and pessimistic hours of every part.');
109
+ const what = view.query.revise ? 'estimates made during work' : 'first estimates';
110
+ const slice = coefficient.slice.kind === 'overall' ? 'overall' : `${coefficient.slice.kind} ${coefficient.slice.key}`;
111
+ const value = times(coefficient.value);
112
+ const pessimistic = times(coefficient.pessimistic);
113
+ return (`Coefficient ${value} from ${coefficient.n} ${coefficient.n === 1 ? 'task' : 'tasks'} (weight ${percent(coefficient.weight)}), ` +
114
+ `slice ${slice}; pessimistic ${pessimistic} (${what}): ` +
115
+ `multiply the optimistic and most likely hours of every part by ${value}, the pessimistic hours by ${pessimistic}.`);
112
116
  }
113
117
  if (view.skipped.length > 0) {
114
118
  // Not the sample: calibration without some cards could name a wrong coefficient.
115
119
  return (`Without calibration: cards of a newer estimetry (${view.skipped.join(', ')}) cannot be read, ` +
116
120
  'so no coefficient is given — update estimetry.');
117
121
  }
118
- const counts = (view.query.revise ? queried(view.revised) : slices).map(([name, stats]) => `${name} ${stats.n} of ${view.minTasks}`);
119
122
  const overall = view.query.revise ? view.revised.overall : view.ratio.overall;
120
- return ((counts.length === 0
121
- ? 'Without calibration: give --type or --stack; only slices by type or technology are applied.'
122
- : `Without calibration: ${counts.join(', ')} tasks needed.`) +
123
- (overall.median === null ? '' : ` Overall ×${overall.median} (${overall.n} tasks) is for reference only.`));
123
+ if (view.tasks === 0) {
124
+ return 'Without calibration: no closed task yet.';
125
+ }
126
+ if (overall.n === 0) {
127
+ if (view.query.revise) {
128
+ return 'Without calibration: no revised task counts yet.';
129
+ }
130
+ // A card without an estimate is neither a sample nor left out: there is nothing below to point to.
131
+ return Object.keys(overall.excluded).length === 0
132
+ ? 'Without calibration: none of the closed tasks has an estimate.'
133
+ : 'Without calibration: none of the closed tasks counts (see what is left out below).';
134
+ }
135
+ return `Without calibration: ${overall.n} of ${view.minTasks} tasks needed (calibration.minTasks).`;
136
+ }
137
+ /** A coefficient in text: two decimals are enough to read; `--json` keeps three. */
138
+ function times(value) {
139
+ return `×${Math.round(value * 100) / 100}`;
124
140
  }
125
141
  /** Revisions by category and `spent`, and extra work by category: shares of the base. */
126
142
  function revisionAndExtraLines(view) {
@@ -148,7 +164,9 @@ function statsText(stats) {
148
164
  return 'no tasks';
149
165
  }
150
166
  const excluded = Object.entries(stats.excluded).map(([reason, n]) => `${reason} ${n}`);
151
- return (`${stats.n} tasks, median ×${stats.median}, mean ×${stats.mean}${stats.applicable ? '' : ', too few to apply'}` +
167
+ // The weight of a whole slice is not what its level weighs in the coefficient: only the coefficient line names one.
168
+ const tooFew = stats.weight > 0 ? '' : ', too few to apply';
169
+ return (`${stats.n} tasks, median ×${stats.median}, mean ×${stats.mean}${tooFew}` +
152
170
  `${stats.revised > 0 ? `, ${stats.revised} revised` : ''}${stats.uncertain > 0 ? `, ${stats.uncertain} uncertain` : ''}` +
153
171
  `${excluded.length > 0 ? `; left out: ${excluded.join(', ')}` : ''}`);
154
172
  }
@@ -170,7 +188,7 @@ export function estimateText(estimate) {
170
188
  const context = [
171
189
  estimate.type,
172
190
  estimate.stack === undefined ? undefined : estimate.stack.join(', '),
173
- estimate.calibrated ? `calibrated ×${estimate.calibration?.coefficient ?? '?'}` : 'without calibration',
191
+ estimate.calibrated ? calibratedText(estimate.calibration) : 'without calibration',
174
192
  estimate.basedOn === undefined ? undefined : `based on ${estimate.basedOn.join(', ')}`,
175
193
  ].filter((part) => part !== undefined);
176
194
  return table([
@@ -182,4 +200,8 @@ export function estimateText(estimate) {
182
200
  }),
183
201
  ]);
184
202
  }
203
+ function calibratedText(calibration) {
204
+ const pessimistic = calibration?.pessimistic === undefined ? '' : `, pessimistic ×${calibration.pessimistic}`;
205
+ return `calibrated ×${calibration?.coefficient ?? '?'}${pessimistic}`;
206
+ }
185
207
  //# sourceMappingURL=estimate-text.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "estimetry",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Compares work estimates with actual effort in AI-agent development and reuses that experience in the next estimate",
5
5
  "keywords": [
6
6
  "estimation",