@davidbyoung/software-factory 0.1.11 → 0.1.13

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 (85) hide show
  1. package/agents/factory-e2e-reviewer.md +1 -1
  2. package/agents/factory-test-reviewer.md +1 -1
  3. package/agents/factory-ui-reviewer.md +2 -2
  4. package/dist/board.d.mts +9 -7
  5. package/dist/board.mjs +59 -36
  6. package/dist/build.d.mts +4 -0
  7. package/dist/build.mjs +9 -4
  8. package/dist/cli.mjs +8 -1
  9. package/dist/code-host/github.mjs +9 -4
  10. package/dist/code-host/types.d.mts +4 -2
  11. package/dist/commands.d.mts +1 -1
  12. package/dist/commands.mjs +16 -7
  13. package/dist/config.d.mts +7 -0
  14. package/dist/config.mjs +68 -5
  15. package/dist/explain.mjs +6 -0
  16. package/dist/guard-commit.d.mts +3 -3
  17. package/dist/guard-commit.mjs +31 -6
  18. package/dist/guard-ticket-text.d.mts +3 -2
  19. package/dist/guard-ticket-text.mjs +7 -4
  20. package/dist/labels.d.mts +28 -0
  21. package/dist/labels.mjs +36 -0
  22. package/dist/lib/clock.d.mts +3 -1
  23. package/dist/lib/clock.mjs +12 -6
  24. package/dist/lib/pull-tickets.d.mts +15 -0
  25. package/dist/lib/pull-tickets.mjs +12 -0
  26. package/dist/lib/refined-check.d.mts +1 -1
  27. package/dist/lib/refined-check.mjs +3 -5
  28. package/dist/lib/usage.d.mts +3 -1
  29. package/dist/lib/usage.mjs +4 -2
  30. package/dist/lib/work-status.d.mts +29 -23
  31. package/dist/lib/work-status.mjs +30 -33
  32. package/dist/merge-policy.d.mts +9 -7
  33. package/dist/merge-policy.mjs +13 -11
  34. package/dist/poller.d.mts +5 -3
  35. package/dist/poller.mjs +27 -17
  36. package/dist/pr.d.mts +22 -0
  37. package/dist/pr.mjs +60 -10
  38. package/dist/remove.mjs +16 -9
  39. package/dist/review-tickets.d.mts +12 -0
  40. package/dist/review-tickets.mjs +59 -0
  41. package/dist/review-verdict.d.mts +6 -1
  42. package/dist/review-verdict.mjs +15 -9
  43. package/dist/reviewers.d.mts +7 -4
  44. package/dist/reviewers.mjs +19 -12
  45. package/dist/runner/github-actions.mjs +6 -7
  46. package/dist/runner/types.d.mts +7 -6
  47. package/dist/status.d.mts +19 -7
  48. package/dist/status.mjs +38 -23
  49. package/dist/sync.d.mts +8 -0
  50. package/dist/sync.mjs +30 -1
  51. package/dist/ticket-fields.d.mts +4 -2
  52. package/dist/ticket-fields.mjs +10 -3
  53. package/dist/ticket.d.mts +14 -7
  54. package/dist/ticket.mjs +121 -72
  55. package/dist/tickets/github.d.mts +10 -2
  56. package/dist/tickets/github.mjs +74 -20
  57. package/dist/tickets/index.d.mts +9 -2
  58. package/dist/tickets/index.mjs +20 -5
  59. package/dist/tickets/types.d.mts +59 -30
  60. package/dist/tickets/types.mjs +13 -3
  61. package/dist/tool-names.d.mts +7 -0
  62. package/dist/tool-names.mjs +1 -0
  63. package/dist/tools.d.mts +4 -1
  64. package/dist/tools.mjs +5 -0
  65. package/docs/cli.md +12 -8
  66. package/docs/configuration.md +179 -9
  67. package/docs/developing.md +17 -9
  68. package/docs/github/by-hand.md +2 -2
  69. package/docs/github/reference.md +22 -22
  70. package/docs/plugins.md +6 -6
  71. package/docs/workflow.md +8 -6
  72. package/package.json +1 -1
  73. package/review.md +11 -11
  74. package/rules.md +25 -16
  75. package/settings.schema.json +45 -0
  76. package/skills/factory-address-review/SKILL.md +7 -6
  77. package/skills/factory-build/SKILL.md +28 -22
  78. package/skills/factory-refine/SKILL.md +1 -1
  79. package/skills/factory-resolve-conflicts/SKILL.md +5 -4
  80. package/workflows/factory-build.yml +6 -5
  81. package/workflows/factory-claude-review.yml +38 -1
  82. package/workflows/factory-conflicts.yml +1 -1
  83. package/workflows/factory-merge-policy.yml +8 -7
  84. package/workflows/factory-review-verdict.yml +1 -1
  85. package/workflows/factory-review.yml +1 -1
package/dist/config.mjs CHANGED
@@ -18,7 +18,8 @@ import { matchesAny } from "./lib/glob.mjs";
18
18
  import { listed } from "./lib/listed.mjs";
19
19
  import { DEFAULT_RUNNER, unsupportedRunner } from "./runner/index.mjs";
20
20
  import { FACTORY_FIELDS } from "./ticket-fields.mjs";
21
- import { BUILT, unsupported } from "./tool-names.mjs";
21
+ import { PR_LABELS, sameLabel, TICKET_LABELS } from "./labels.mjs";
22
+ import { BUILT, unsupported, } from "./tool-names.mjs";
22
23
  import { DEFAULT_COLUMNS, STATE_KEYS, sameName, watchOf, } from "./lib/work-status.mjs";
23
24
  export class SettingsError extends Error {
24
25
  }
@@ -144,13 +145,15 @@ export const SETTINGS_KEYS = {
144
145
  "session-minutes",
145
146
  "rules",
146
147
  ],
147
- tickets: ["type", "board", "columns", "fields"],
148
+ tickets: ["type", "board", "columns", "fields", "labels"],
149
+ "tickets.labels": Object.keys(TICKET_LABELS),
148
150
  "tickets.columns": Object.keys(STATE_KEYS),
149
151
  "tickets.fields": [
150
152
  ...Object.keys(FIELD_DEFAULTS),
151
153
  ...FACTORY_FIELDS.map((f) => f.key),
152
154
  ],
153
- "code-host": ["type", "branch-name"],
155
+ "code-host": ["type", "branch-name", "labels"],
156
+ "code-host.labels": Object.keys(PR_LABELS),
154
157
  builds: ["trigger", "runner", "poll-minutes"],
155
158
  specs: ["type", "check"],
156
159
  commands: [
@@ -317,6 +320,46 @@ function names(v, key, defaults) {
317
320
  return [k, value.trim()];
318
321
  }));
319
322
  }
323
+ /** One side's label names: each key the file sets, checked by the tool
324
+ * that shows it, and the rest at their defaults. */
325
+ function labelsOf(v, key, defaults, fault) {
326
+ const o = object(v, key);
327
+ const set = Object.keys(defaults).filter((k) => o[k] !== undefined);
328
+ const names = { ...defaults };
329
+ for (const k of set) {
330
+ const value = o[k];
331
+ if (typeof value !== "string")
332
+ fail(`${key}.${k}`, "must be text");
333
+ const name = value.trim();
334
+ if (!name)
335
+ fail(`${key}.${k}`, "must not be empty");
336
+ const why = fault?.(name);
337
+ if (why)
338
+ fail(`${key}.${k}`, why);
339
+ names[k] = name;
340
+ }
341
+ return { names, set };
342
+ }
343
+ /** Fails on two labels with one name, ignoring capitals, naming a key the
344
+ * file sets: of two it sets, the later. Ticket and pull request labels are
345
+ * compared only when one tool holds both. */
346
+ function sameNames(sides, oneTool) {
347
+ const groups = oneTool ? [sides] : sides.map((side) => [side]);
348
+ for (const group of groups) {
349
+ const all = group.flatMap((side) => Object.entries(side.names).map(([k, name]) => ({
350
+ at: `${side.key}.${k}`,
351
+ name,
352
+ set: side.set.includes(k),
353
+ })));
354
+ for (const [i, b] of all.entries())
355
+ for (const a of all.slice(0, i)) {
356
+ if (!sameLabel(a.name, b.name))
357
+ continue;
358
+ const [blamed, other] = b.set ? [b, a] : [a, b];
359
+ fail(blamed.at, `"${blamed.name}" is already ${other.at}. Give each label its own name`);
360
+ }
361
+ }
362
+ }
320
363
  /** A key under `tickets.fields` naming a heading of the repository's own. */
321
364
  export const OWN_HEADING = /^[a-z0-9]+(-[a-z0-9]+)*$/;
322
365
  /** The ticket-side keys under `tickets.fields`: the four factory fields,
@@ -600,6 +643,12 @@ export function parseSettings(raw, exists, built = BUILT, { partial = false } =
600
643
  if (typeof codeHost !== "string" || !built.codeHost.includes(codeHost))
601
644
  throw new SettingsError(`${SETTINGS_FILE}: ${unsupportedCodeHost(String(codeHost), built.codeHost)}`);
602
645
  const branchName = branchNameOf(codeHostBlock["branch-name"], partial);
646
+ const ticketLabels = labelsOf(tickets.labels, "tickets.labels", TICKET_LABELS, built.labelFaults.tickets[ticketType]);
647
+ const prLabels = labelsOf(codeHostBlock.labels, "code-host.labels", PR_LABELS, built.labelFaults.codeHost[codeHost]);
648
+ sameNames([
649
+ { key: "tickets.labels", ...ticketLabels },
650
+ { key: "code-host.labels", ...prLabels },
651
+ ], ticketType === codeHost);
603
652
  const builds = object(top.builds, "builds");
604
653
  const trigger = oneOf(builds.trigger, "builds.trigger", TRIGGERS, "manual");
605
654
  const minutes = builds["poll-minutes"];
@@ -682,8 +731,9 @@ export function parseSettings(raw, exists, built = BUILT, { partial = false } =
682
731
  columns,
683
732
  fields: fieldNames,
684
733
  ticketFields,
734
+ labels: ticketLabels.names,
685
735
  },
686
- codeHost: { type: codeHost, branchName },
736
+ codeHost: { type: codeHost, branchName, labels: prLabels.names },
687
737
  builds: { trigger, runner, pollMinutes },
688
738
  specs,
689
739
  specCheck,
@@ -769,6 +819,18 @@ export function parseChoices(text, load) {
769
819
  throw bad();
770
820
  return v;
771
821
  }
822
+ /** js-yaml's error for `key: a: b`, said as the fix: the value needs
823
+ * quotes. Null for any other error. */
824
+ function needsQuotes(e, text) {
825
+ const { reason, mark } = e;
826
+ if (reason !== "bad indentation of a mapping entry" || !mark)
827
+ return null;
828
+ const m = /^\s*([^\s:#][^:]*): (\S.*: .*?)\s*$/.exec(text.split("\n")[mark.line] ?? "");
829
+ if (!m || /^["'[{]/.test(m[2]))
830
+ return null;
831
+ const [, key, value] = m;
832
+ return `line ${mark.line + 1}: ${key}: ${value} needs quotes around the name, such as ${key}: "${value}"`;
833
+ }
772
834
  /** The settings combined from the factory's defaults, each preset in
773
835
  * `presets`, and `.claude/factory.yaml`, as `factory sync` combines them
774
836
  * into the lock. `factoryFile` and `ownFile` say which preset files are
@@ -782,7 +844,7 @@ export async function resolveFiles(d, { partial = false, ...keep } = {}) {
782
844
  own = load(ownText);
783
845
  }
784
846
  catch (e) {
785
- throw new SettingsError(`${SETTINGS_FILE}: ${e.message}`);
847
+ throw new SettingsError(`${SETTINGS_FILE}: ${needsQuotes(e, ownText) ?? e.message}`);
786
848
  }
787
849
  const P = await import("./preset.mjs");
788
850
  const top = isObj(own) ? own : {};
@@ -1193,6 +1255,7 @@ export function targetOf(s, env) {
1193
1255
  : s.tickets.board,
1194
1256
  watch: watchOf(s.builds.trigger, s.builds.pollMinutes),
1195
1257
  columns: columnsOf(s),
1258
+ followUp: s.tickets.labels["follow-up"],
1196
1259
  };
1197
1260
  }
1198
1261
  /** The repository, code host, and runner for a command a workflow runs
package/dist/explain.mjs CHANGED
@@ -75,6 +75,9 @@ export async function explainLines(s, marks, exists) {
75
75
  block(["tickets", "fields"]);
76
76
  for (const [k, v] of Object.entries(s.tickets.ticketFields))
77
77
  put(["tickets", "fields", k], v ?? "none");
78
+ block(["tickets", "labels"]);
79
+ for (const [k, v] of Object.entries(s.tickets.labels))
80
+ put(["tickets", "labels", k], v);
78
81
  block(["code-host"]);
79
82
  put(["code-host", "type"], s.codeHost.type);
80
83
  // Quoted always: YAML reads a pattern that starts with `{` as a map.
@@ -82,6 +85,9 @@ export async function explainLines(s, marks, exists) {
82
85
  text: `${pad(1)}branch-name: ${JSON.stringify(s.codeHost.branchName)}`,
83
86
  mark: marks.value(["code-host", "branch-name"]),
84
87
  });
88
+ block(["code-host", "labels"]);
89
+ for (const [k, v] of Object.entries(s.codeHost.labels))
90
+ put(["code-host", "labels", k], v);
85
91
  block(["builds"]);
86
92
  put(["builds", "trigger"], s.builds.trigger);
87
93
  put(["builds", "runner"], s.builds.runner);
@@ -10,16 +10,16 @@ export type HookInput = {
10
10
  * part of a command. A quoted single word is unquoted instead: the shell
11
11
  * passes "main" to git as main. */
12
12
  export declare function blankQuoted(cmd: string): string;
13
- /** "verdict: override" is the owner's approval of one commit, and agents act
13
+ /** The override is the owner's approval of one commit, and agents act
14
14
  * through the owner's account, so GitHub cannot tell their override from the
15
15
  * owner's. This is a tripwire, not a lock: it stops the ordinary gh ways of
16
16
  * adding it, not a script written to get around it. It reads each command of
17
- * the chain as typed, since the spaced name is always quoted, and blocks one
17
+ * the chain as typed, since a name with a space in it is quoted, and blocks one
18
18
  * that adds the override as --add-label's value or a labels[]= field, or that
19
19
  * writes to the labels API with the override anywhere in the command, as a
20
20
  * body sent with --input does. Removing the override, alone or beside adding
21
21
  * another label, is allowed. */
22
- export declare function addsOverride(raw: string): boolean;
22
+ export declare function addsOverride(raw: string, name: string): boolean;
23
23
  export type GitCall = {
24
24
  kind: "push" | "commit";
25
25
  segment: string;
@@ -17,6 +17,7 @@ import { homedir } from "node:os";
17
17
  import { dirname, isAbsolute, join, relative } from "node:path";
18
18
  import { fileURLToPath } from "node:url";
19
19
  import { defaultDeps, loadSettings, settingsPath } from "./config.mjs";
20
+ import { PR_LABELS } from "./labels.mjs";
20
21
  import { branchDeps, CANNOT_TELL, defaultBranch, } from "./lib/default-branch.mjs";
21
22
  /** Heredoc bodies and quoted strings blanked, so a commit message, grep
22
23
  * pattern, or file body that mentions "git push -f" or "main" is not read as
@@ -29,17 +30,23 @@ export function blankQuoted(cmd) {
29
30
  .replace(/"(?:[^"\\]|\\[\s\S])*"/g, '""')
30
31
  .replace(/'[^']*'/g, "''");
31
32
  }
32
- const OVERRIDE = String.raw `verdict(:|%3A)( |%20|\+)override`;
33
- /** "verdict: override" is the owner's approval of one commit, and agents act
33
+ /** The override's name as a pattern that also matches it URL-encoded: a
34
+ * colon as %3A, and a space as %20 or +. */
35
+ const overridePattern = (name) => name
36
+ .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
37
+ .replace(/:/g, "(:|%3A)")
38
+ .replace(/ /g, "( |%20|\\+)");
39
+ /** The override is the owner's approval of one commit, and agents act
34
40
  * through the owner's account, so GitHub cannot tell their override from the
35
41
  * owner's. This is a tripwire, not a lock: it stops the ordinary gh ways of
36
42
  * adding it, not a script written to get around it. It reads each command of
37
- * the chain as typed, since the spaced name is always quoted, and blocks one
43
+ * the chain as typed, since a name with a space in it is quoted, and blocks one
38
44
  * that adds the override as --add-label's value or a labels[]= field, or that
39
45
  * writes to the labels API with the override anywhere in the command, as a
40
46
  * body sent with --input does. Removing the override, alone or beside adding
41
47
  * another label, is allowed. */
42
- export function addsOverride(raw) {
48
+ export function addsOverride(raw, name) {
49
+ const OVERRIDE = overridePattern(name);
43
50
  const segments = raw
44
51
  .split(/\|\||&&|[;&|()]|\n/)
45
52
  .filter((s) => /^\s*gh\s/.test(s));
@@ -50,6 +57,21 @@ export function addsOverride(raw) {
50
57
  segments.some((s) => /\/labels(\s|$)/.test(s) &&
51
58
  /--input|-X\s*(POST|PUT)|--method\s+(POST|PUT)/.test(s)));
52
59
  }
60
+ /** The override's name in the lock of the checkout at `dir`, or its
61
+ * default where there is no lock to read. */
62
+ async function overrideName(dir) {
63
+ const top = checkoutOf(dir);
64
+ const lock = join(top, ".claude/factory.lock");
65
+ if (!existsSync(lock))
66
+ return PR_LABELS["verdict-override"];
67
+ try {
68
+ const s = await loadSettings(defaultDeps(top, { FACTORY_LOCK: lock }));
69
+ return s.codeHost.labels["verdict-override"];
70
+ }
71
+ catch {
72
+ return PR_LABELS["verdict-override"];
73
+ }
74
+ }
53
75
  function resolvePath(dir, to) {
54
76
  if (isAbsolute(to))
55
77
  return to;
@@ -162,8 +184,11 @@ const pushesTo = (segment, branch) => new RegExp(String.raw `\s(\S*:)?(refs\/hea
162
184
  export async function checkCommit(input, err, defaultOf = branchOf) {
163
185
  const raw = input.tool_input?.command ?? "";
164
186
  const cwd = input.cwd ?? ".";
165
- if (addsOverride(raw))
166
- return '"verdict: override" is the owner\'s label. Ask them to add it.';
187
+ if (/\bgh\s/.test(raw) && /label/i.test(raw)) {
188
+ const name = await overrideName(cwd);
189
+ if (addsOverride(raw, name))
190
+ return `"${name}" is the owner's label. Ask them to add it.`;
191
+ }
167
192
  const calls = gitCalls(blankQuoted(raw), cwd);
168
193
  if (calls.length === 0)
169
194
  return null;
@@ -23,5 +23,6 @@ export declare function checkTicketText(input: {
23
23
  * tag, so `factory ticket` and `factory pr comment` post nothing. */
24
24
  export declare function refuseBareTags(text: string): void;
25
25
  /** The owner's pass of the review verdict for one commit, which no agent
26
- * adds ("What merges without the owner" in rules.md). */
27
- export declare function refuseOverride(label: string): void;
26
+ * adds ("What merges without the owner" in rules.md), by its key or by
27
+ * `name`, the name the settings give it. */
28
+ export declare function refuseOverride(label: string, name: string): void;
@@ -15,6 +15,7 @@
15
15
  // forms, which is how a session posts without `gh issue`.
16
16
  // GitHub serves a pull request's conversation comments, and its body, as
17
17
  // an issue's, so those paths are read too; `gh pr` and `pulls/N` are not.
18
+ import { PR_LABELS, sameLabel } from "./labels.mjs";
18
19
  import { readFileSync } from "node:fs";
19
20
  import { resolve } from "node:path";
20
21
  /** The tags GitHub renders on purpose, which issue text may use bare. Not
@@ -281,8 +282,10 @@ export function refuseBareTags(text) {
281
282
  throw new Error(refusal(tags));
282
283
  }
283
284
  /** The owner's pass of the review verdict for one commit, which no agent
284
- * adds ("What merges without the owner" in rules.md). */
285
- export function refuseOverride(label) {
286
- if (label.trim().toLowerCase() === "verdict: override")
287
- throw new Error("Refused: the verdict: override label is the owner's pass of the review verdict, which an agent never adds.");
285
+ * adds ("What merges without the owner" in rules.md), by its key or by
286
+ * `name`, the name the settings give it. */
287
+ export function refuseOverride(label, name) {
288
+ const given = label.trim();
289
+ if ([PR_LABELS["verdict-override"], name].some((n) => sameLabel(n, given)))
290
+ throw new Error(`Refused: the ${name} label is the owner's pass of the review verdict, which an agent never adds.`);
288
291
  }
@@ -0,0 +1,28 @@
1
+ /** The labels on tickets, each key with its default name. */
2
+ export declare const TICKET_LABELS: {
3
+ readonly spec: "spec";
4
+ readonly "follow-up": "follow-up";
5
+ };
6
+ /** The labels on pull requests, each key with its default name. */
7
+ export declare const PR_LABELS: {
8
+ readonly "merge-automatic": "merge-automatic";
9
+ readonly "merge-manual": "merge-manual";
10
+ readonly "verdict-override": "verdict-override";
11
+ };
12
+ export type TicketLabel = keyof typeof TICKET_LABELS;
13
+ export type PrLabel = keyof typeof PR_LABELS;
14
+ /** The name in effect for each key. */
15
+ export type Labels = {
16
+ tickets: Record<TicketLabel, string>;
17
+ codeHost: Record<PrLabel, string>;
18
+ };
19
+ export declare const DEFAULT_LABELS: Labels;
20
+ /** A key's name on one side, or `word` unchanged when it is not one of
21
+ * that side's keys, so a label of the repository's own passes through. */
22
+ export declare function labelOf(names: Readonly<Record<string, string>>, word: string): string;
23
+ /** Two names that differ only in capitals count as one label. */
24
+ export declare const sameLabel: (a: string, b: string) => boolean;
25
+ /** Labels as a person or a session reads them: one whose name is not its
26
+ * key carries the key after it, as `needs-spec (spec)`, so a session that
27
+ * knows only the key can tell which it is. */
28
+ export declare function shownLabels(labels: readonly string[], names: Readonly<Record<string, string>>): string[];
@@ -0,0 +1,36 @@
1
+ // The labels the factory adds to tickets and pull requests. Each has a key,
2
+ // which the skills, rules, and commands use, and a name, which the ticket
3
+ // system or code host shows: the key unless `tickets.labels` or
4
+ // `code-host.labels` sets another. It imports nothing that imports the
5
+ // settings, so the hooks can read it without them.
6
+ /** The labels on tickets, each key with its default name. */
7
+ export const TICKET_LABELS = {
8
+ spec: "spec",
9
+ "follow-up": "follow-up",
10
+ };
11
+ /** The labels on pull requests, each key with its default name. */
12
+ export const PR_LABELS = {
13
+ "merge-automatic": "merge-automatic",
14
+ "merge-manual": "merge-manual",
15
+ "verdict-override": "verdict-override",
16
+ };
17
+ export const DEFAULT_LABELS = {
18
+ tickets: { ...TICKET_LABELS },
19
+ codeHost: { ...PR_LABELS },
20
+ };
21
+ /** A key's name on one side, or `word` unchanged when it is not one of
22
+ * that side's keys, so a label of the repository's own passes through. */
23
+ export function labelOf(names, word) {
24
+ return Object.hasOwn(names, word) ? names[word] : word;
25
+ }
26
+ /** Two names that differ only in capitals count as one label. */
27
+ export const sameLabel = (a, b) => a.toLowerCase() === b.toLowerCase();
28
+ /** Labels as a person or a session reads them: one whose name is not its
29
+ * key carries the key after it, as `needs-spec (spec)`, so a session that
30
+ * knows only the key can tell which it is. */
31
+ export function shownLabels(labels, names) {
32
+ const keyOf = new Map(Object.entries(names)
33
+ .filter(([key, name]) => key !== name)
34
+ .map(([key, name]) => [name, key]));
35
+ return labels.map((l) => (keyOf.has(l) ? `${l} (${keyOf.get(l)})` : l));
36
+ }
@@ -2,7 +2,7 @@
2
2
  * claimed or refined an issue: its spend is counted once, but its reviewer
3
3
  * runs belong to no issue. */
4
4
  export type Clock = {
5
- issue: number | null;
5
+ issue: string | null;
6
6
  start: string;
7
7
  };
8
8
  /** The repository's shared git directory, so a session that moves to
@@ -11,4 +11,6 @@ export declare function commonDir(): string;
11
11
  export declare const clockPath: (session: string) => string;
12
12
  /** The clock, or null when none was started or it cannot be read. */
13
13
  export declare function readClock(session: string): Clock | null;
14
+ /** A clock file's text as the clock, or null when it is not one. */
15
+ export declare function parseClock(text: string): Clock | null;
14
16
  export declare function writeClock(session: string, clock: Clock): void;
@@ -18,13 +18,19 @@ export const clockPath = (session) => join(commonDir(), `work-clock-${session}`)
18
18
  /** The clock, or null when none was started or it cannot be read. */
19
19
  export function readClock(session) {
20
20
  const path = clockPath(session);
21
- if (!existsSync(path))
22
- return null;
21
+ return existsSync(path) ? parseClock(readFileSync(path, "utf8")) : null;
22
+ }
23
+ /** A clock file's text as the clock, or null when it is not one. */
24
+ export function parseClock(text) {
23
25
  try {
24
- const clock = JSON.parse(readFileSync(path, "utf8"));
25
- return (clock.issue === null || Number.isInteger(clock.issue)) &&
26
- !Number.isNaN(Date.parse(clock.start))
27
- ? clock
26
+ const clock = JSON.parse(text);
27
+ if (Number.isNaN(Date.parse(clock.start)))
28
+ return null;
29
+ // A clock written before tickets had keys holds the issue's number.
30
+ if (typeof clock.issue === "number" && Number.isInteger(clock.issue))
31
+ return { issue: String(clock.issue), start: clock.start };
32
+ return clock.issue === null || typeof clock.issue === "string"
33
+ ? { issue: clock.issue, start: clock.start }
28
34
  : null;
29
35
  }
30
36
  catch {
@@ -0,0 +1,15 @@
1
+ import type { Settings } from "../config.mts";
2
+ import type { Links, Tickets } from "../tickets/types.mts";
3
+ import type { PullRequest } from "./work-status.mts";
4
+ /** Whether the code host keeps the tickets itself, so its own links, such
5
+ * as GitHub's closing references, say which tickets a pull request closes. */
6
+ export declare const ownLinks: (settings: Settings) => boolean;
7
+ /** The tickets a pull request closes and builds part of. `closes` is the
8
+ * code host's list as it read it. */
9
+ export declare function ticketsOf(pull: {
10
+ body: string;
11
+ closes: Links["closes"];
12
+ }, tickets: Pick<Tickets, "linksIn">, own: boolean): Links;
13
+ /** The pull requests with `closes` and `partOf` read as `ticketsOf` reads
14
+ * them. */
15
+ export declare const linkPulls: <P extends PullRequest>(pulls: P[], tickets: Pick<Tickets, "linksIn">, own: boolean) => P[];
@@ -0,0 +1,12 @@
1
+ /** Whether the code host keeps the tickets itself, so its own links, such
2
+ * as GitHub's closing references, say which tickets a pull request closes. */
3
+ export const ownLinks = (settings) => settings.tickets.type === "github" && settings.codeHost.type === "github";
4
+ /** The tickets a pull request closes and builds part of. `closes` is the
5
+ * code host's list as it read it. */
6
+ export function ticketsOf(pull, tickets, own) {
7
+ const links = tickets.linksIn(pull.body);
8
+ return { closes: own ? pull.closes : links.closes, partOf: links.partOf };
9
+ }
10
+ /** The pull requests with `closes` and `partOf` read as `ticketsOf` reads
11
+ * them. */
12
+ export const linkPulls = (pulls, tickets, own) => pulls.map((pull) => ({ ...pull, ...ticketsOf(pull, tickets, own) }));
@@ -4,4 +4,4 @@
4
4
  * the `spec` label needs its decisions and at least one acceptance
5
5
  * criterion. One with it needs its decisions, a spec with a capability
6
6
  * and a numbered line, and the builder's design and tasks. */
7
- export declare function missingParts(body: string, labels: string[]): string[];
7
+ export declare function missingParts(body: string, labels: string[], names: Readonly<Record<"spec" | "follow-up", string>>): string[];
@@ -2,8 +2,6 @@
2
2
  // `factory ticket refined` makes before it posts the marker, for the
3
3
  // factory's own refiner as for a plugin's. It reads headings only, never
4
4
  // what a section says.
5
- const SPEC_LABEL = "spec";
6
- const FOLLOW_UP_LABEL = "follow-up";
7
5
  /** The body's lines outside its fenced code blocks, so a sample body in a
8
6
  * code block is not read as the ticket's own. */
9
7
  function proseLines(body) {
@@ -39,8 +37,8 @@ function under(lines, heading, toEnd = false) {
39
37
  * the `spec` label needs its decisions and at least one acceptance
40
38
  * criterion. One with it needs its decisions, a spec with a capability
41
39
  * and a numbered line, and the builder's design and tasks. */
42
- export function missingParts(body, labels) {
43
- if (labels.includes(FOLLOW_UP_LABEL))
40
+ export function missingParts(body, labels, names) {
41
+ if (labels.includes(names["follow-up"]))
44
42
  return [];
45
43
  const lines = proseLines(body);
46
44
  const missing = [];
@@ -49,7 +47,7 @@ export function missingParts(body, labels) {
49
47
  missing.push(`missing: ${part}`);
50
48
  };
51
49
  need(lines.includes("## Decisions"), "## Decisions");
52
- if (!labels.includes(SPEC_LABEL)) {
50
+ if (!labels.includes(names.spec)) {
53
51
  const criteria = under(lines, "## Acceptance criteria");
54
52
  if (criteria === null)
55
53
  need(false, "## Acceptance criteria");
@@ -24,7 +24,9 @@ export declare const dollars: (amount: number) => string;
24
24
  export declare const bothPrices: (listPrice: number) => string;
25
25
  /** The cost note's visible line and hidden marker, or the line that says
26
26
  * why the cost could not be measured. */
27
- export declare function costNote(measured: Measured, issue: number, session: string): string;
27
+ export declare function costNote(measured: Measured,
28
+ /** Where the note is posted, as written in prose, such as `#12`. */
29
+ on: string, session: string): string;
28
30
  /** Where Claude Code keeps its transcripts. */
29
31
  export declare function projectsDir(env: Record<string, string | undefined>): string;
30
32
  /** The session's own transcript and its subagents', or null when the
@@ -81,7 +81,9 @@ function unpricedClause(spend) {
81
81
  }
82
82
  /** The cost note's visible line and hidden marker, or the line that says
83
83
  * why the cost could not be measured. */
84
- export function costNote(measured, issue, session) {
84
+ export function costNote(measured,
85
+ /** Where the note is posted, as written in prose, such as `#12`. */
86
+ on, session) {
85
87
  const failed = (reason) => `This session's cost could not be measured: ${reason}.`;
86
88
  if (!measured.ok)
87
89
  return failed(measured.reason);
@@ -91,7 +93,7 @@ export function costNote(measured, issue, session) {
91
93
  ? "its transcript records no usage since its last note"
92
94
  : `no token in it is on a model with a list price${unpricedClause(spend).replace(/^, plus/, ":")}`);
93
95
  const amount = spend.dollars.toFixed(2);
94
- return `This session used ${bothPrices(spend.dollars)} on #${issue} since its last note${unpricedClause(spend)}.\n\n<!-- cost: ${amount} session=${session} -->`;
96
+ return `This session used ${bothPrices(spend.dollars)} on ${on} since its last note${unpricedClause(spend)}.\n\n<!-- cost: ${amount} session=${session} -->`;
95
97
  }
96
98
  /** Where Claude Code keeps its transcripts. */
97
99
  export function projectsDir(env) {
@@ -1,4 +1,4 @@
1
- import type { Board, Ticket, TicketComment } from "../tickets/types.mts";
1
+ import type { Board, Key, Ticket, TicketComment } from "../tickets/types.mts";
2
2
  export type { Board, BoardField, BoardItem } from "../tickets/types.mts";
3
3
  export declare const AGENT_MARK = "<!-- agent -->";
4
4
  export declare const STATUSES: readonly ["Backlog", "In refinement", "Ready", "In progress", "In review", "Done"];
@@ -79,9 +79,6 @@ export declare function hasCostMarker(body: string): boolean;
79
79
  * agent mark, whoever posted it, as a claim or a release does, or when the
80
80
  * pull request review's bot posted it. */
81
81
  export declare function parseCosts(comment: IssueComment): number[];
82
- /** Whether a pull request's body says it builds this issue, as "Closes #N"
83
- * or "Part of #N". */
84
- export declare function buildsIssue(body: string, number: number): boolean;
85
82
  /** The issue's Cost: every cost marker on it and on each pull request, open,
86
83
  * merged, or closed, that builds it, to the cent. Null when there are none. */
87
84
  export declare function issueCost(issue: Issue, pulls: PullRequest[]): number | null;
@@ -129,8 +126,13 @@ export type PullRequest = {
129
126
  number: number;
130
127
  createdAt: string;
131
128
  body: string;
132
- /** Issue numbers GitHub links as closed by this pull request. */
133
- closes: number[];
129
+ /** The tickets it closes when it merges. The code host fills it with its
130
+ * own links, and `linkPulls` (`lib/pull-tickets.mts`) with what the
131
+ * factory counts. */
132
+ closes: Key[];
133
+ /** The tickets its body says it builds part of, once `linkPulls` has
134
+ * read it; empty before. */
135
+ partOf: Key[];
134
136
  isDraft: boolean;
135
137
  checks: string | null;
136
138
  openThreads: number;
@@ -151,19 +153,17 @@ export type Derived = {
151
153
  /** Open pull requests that put the issue In review. */
152
154
  pulls: number[];
153
155
  };
154
- /** Whether a pull request's body says it builds part of the follow-ups
155
- * issue, as "Part of #N". A plain mention, such as a build linking the issue
156
- * it added a line to, does not count. */
157
- export declare function buildsPartOf(body: string, number: number): boolean;
158
- /** The pull requests that put this issue In review. */
159
- export declare function reviewingPulls(issue: Issue, pulls: PullRequest[]): PullRequest[];
156
+ /** The pull requests that put this issue In review: those that close it,
157
+ * and on the follow-ups ticket, labeled `followUp`, those that build part
158
+ * of it. */
159
+ export declare function reviewingPulls(issue: Issue, pulls: PullRequest[], followUp?: string): PullRequest[];
160
160
  /** The page of an Actions run, from the board's or the view's session: the
161
161
  * run's ID, which `runPage` turns into its page. Null for any other
162
162
  * session. */
163
163
  export declare function actionsRunLink(derived: Pick<Derived, "session" | "runsIn">, runPage: (id: string) => string): string | null;
164
164
  /** An issue's Status is the first rule that applies: Done, In review,
165
165
  * In progress, Ready, In refinement, Backlog. */
166
- export declare function derive(issue: Issue, card: BoardCard | null, pulls: PullRequest[], columns?: Columns): Derived;
166
+ export declare function derive(issue: Issue, card: BoardCard | null, pulls: PullRequest[], columns?: Columns, followUp?: string): Derived;
167
167
  /** Over 24 hours In progress or In refinement with a session. */
168
168
  export declare function isStale(derived: Derived, now: Date): boolean;
169
169
  /** How long a card may sit in Ready before the poller should have started
@@ -177,10 +177,10 @@ export type Watch = {
177
177
  export declare function watchOf(trigger: "own-server" | "github-action" | "manual", pollMinutes: number): Watch | null;
178
178
  /** Ready for longer than the poller takes, with no start: it should have
179
179
  * fired. */
180
- export declare function isNotStarted(derived: Derived, openBlockers: number[], now: Date, minutes?: number): boolean;
180
+ export declare function isNotStarted(derived: Derived, openBlockers: Key[], now: Date, minutes?: number): boolean;
181
181
  /** A claim or start over 24 hours old with no pull request, which the
182
182
  * nightly sync clears. Null when there is nothing to clear. */
183
- export declare function toClear(issue: Issue, pulls: PullRequest[], now: Date): {
183
+ export declare function toClear(issue: Issue, pulls: PullRequest[], now: Date, followUp?: string): {
184
184
  kind: "claim" | "start";
185
185
  since: string;
186
186
  } | null;
@@ -195,6 +195,12 @@ export type Identity = {
195
195
  };
196
196
  /** The comments sessions, the poller, and the sync post: one visible
197
197
  * sentence, then its marker line and the agent mark. */
198
+ /** A ticket as a comment names it: its key, for a command, and its written
199
+ * form, for prose. */
200
+ export type Named = {
201
+ key: Key;
202
+ ref: string;
203
+ };
198
204
  export type CommentKind = {
199
205
  kind: "refining";
200
206
  who: Identity;
@@ -203,7 +209,7 @@ export type CommentKind = {
203
209
  cost?: string;
204
210
  } | {
205
211
  kind: "refined";
206
- issue: number;
212
+ issue: Named;
207
213
  before?: string;
208
214
  cost?: string;
209
215
  } | {
@@ -211,7 +217,7 @@ export type CommentKind = {
211
217
  marker: string;
212
218
  } | {
213
219
  kind: "dispatch-failed";
214
- issue: number;
220
+ issue: Named;
215
221
  status: string;
216
222
  reason: string;
217
223
  } | {
@@ -220,7 +226,7 @@ export type CommentKind = {
220
226
  } | {
221
227
  kind: "stopped";
222
228
  where: SessionKind;
223
- issue: number;
229
+ issue: Named;
224
230
  reason: string;
225
231
  cost?: string;
226
232
  } | {
@@ -228,21 +234,21 @@ export type CommentKind = {
228
234
  cost: string;
229
235
  } | {
230
236
  kind: "ended";
231
- issue: number;
237
+ issue: Named;
232
238
  } | {
233
239
  kind: "cleared-claim";
234
- issue: number;
240
+ issue: Named;
235
241
  since: string;
236
242
  } | {
237
243
  kind: "cleared-start";
238
- issue: number;
244
+ issue: Named;
239
245
  since: string;
240
246
  } | {
241
247
  kind: "follow-ups-merged";
242
248
  pull: number;
243
249
  } | {
244
250
  kind: "pull-closed";
245
- issue: number;
251
+ issue: Named;
246
252
  pull: number;
247
253
  };
248
254
  export declare function commentBody(c: CommentKind, columns?: Columns): string;
@@ -261,4 +267,4 @@ export declare function toSnapshot(tickets: Issue[], pulls: PullRequest[], now:
261
267
  /** A ticket's card, its column read as the state that column shows. A
262
268
  * card with no Status has none; one in a column no state names is
263
269
  * "Unmapped". */
264
- export declare const cardOf: (board: Board, number: number, columns?: Columns) => BoardCard | null;
270
+ export declare const cardOf: (board: Board, key: Key, columns?: Columns) => BoardCard | null;