@davidbyoung/software-factory 0.1.1 → 0.1.3

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 (83) hide show
  1. package/README.md +8 -9
  2. package/dist/agent/claude-code.d.mts +3 -0
  3. package/dist/agent/claude-code.mjs +89 -0
  4. package/dist/agent/index.d.mts +2 -0
  5. package/dist/agent/index.mjs +5 -0
  6. package/dist/board.mjs +1 -1
  7. package/dist/cli.mjs +17 -2
  8. package/dist/code-host/github-setup.d.mts +5 -0
  9. package/dist/code-host/github-setup.mjs +133 -0
  10. package/dist/code-host/github.mjs +4 -0
  11. package/dist/code-host/index.d.mts +1 -1
  12. package/dist/code-host/index.mjs +2 -1
  13. package/dist/code-host/types.d.mts +2 -0
  14. package/dist/config.d.mts +26 -7
  15. package/dist/config.mjs +79 -26
  16. package/dist/doctor.d.mts +6 -14
  17. package/dist/doctor.mjs +52 -64
  18. package/dist/explain.d.mts +2 -0
  19. package/dist/explain.mjs +127 -0
  20. package/dist/init.d.mts +8 -12
  21. package/dist/init.mjs +179 -131
  22. package/dist/lib/has-command.d.mts +5 -0
  23. package/dist/lib/has-command.mjs +8 -0
  24. package/dist/lib/listed.d.mts +2 -0
  25. package/dist/lib/listed.mjs +4 -0
  26. package/dist/lib/work-status.d.mts +12 -2
  27. package/dist/lib/work-status.mjs +14 -3
  28. package/dist/parts.d.mts +18 -15
  29. package/dist/parts.mjs +15 -43
  30. package/dist/poller.d.mts +20 -3
  31. package/dist/poller.mjs +62 -15
  32. package/dist/remove.d.mts +11 -0
  33. package/dist/remove.mjs +156 -0
  34. package/dist/runner/github-actions.d.mts +1 -1
  35. package/dist/runner/github-actions.mjs +12 -0
  36. package/dist/runner/index.d.mts +1 -1
  37. package/dist/runner/index.mjs +2 -1
  38. package/dist/runner/setup.d.mts +2 -0
  39. package/dist/runner/setup.mjs +22 -0
  40. package/dist/runner/types.d.mts +3 -0
  41. package/dist/runner/types.mjs +0 -2
  42. package/dist/setup.d.mts +98 -0
  43. package/dist/setup.mjs +3 -0
  44. package/dist/status.d.mts +4 -4
  45. package/dist/status.mjs +8 -7
  46. package/dist/sync.d.mts +22 -3
  47. package/dist/sync.mjs +144 -11
  48. package/dist/tickets/github-setup.d.mts +2 -0
  49. package/dist/tickets/github-setup.mjs +50 -0
  50. package/dist/tickets/github.mjs +0 -2
  51. package/dist/tickets/index.mjs +2 -1
  52. package/dist/tickets/transport.mjs +1 -3
  53. package/dist/tickets/types.mjs +0 -2
  54. package/dist/tool-names.d.mts +11 -0
  55. package/dist/tool-names.mjs +20 -0
  56. package/dist/tools.d.mts +56 -0
  57. package/dist/tools.mjs +76 -0
  58. package/docs/builds.md +103 -51
  59. package/docs/cli.md +42 -42
  60. package/docs/configuration.md +38 -32
  61. package/docs/design.md +1 -1
  62. package/docs/developing.md +156 -67
  63. package/docs/existing-repo.md +20 -9
  64. package/docs/github/by-hand.md +321 -0
  65. package/docs/github/reference.md +65 -61
  66. package/docs/github/setup.md +83 -267
  67. package/docs/glossary.md +5 -4
  68. package/docs/limitations.md +12 -10
  69. package/docs/plugins.md +12 -17
  70. package/docs/quick-start.md +62 -105
  71. package/docs/removing.md +36 -16
  72. package/docs/skills.md +47 -37
  73. package/docs/updating.md +2 -6
  74. package/docs/workflow.md +13 -12
  75. package/package.json +5 -3
  76. package/poller.Dockerfile +10 -18
  77. package/rules.md +14 -12
  78. package/settings.schema.json +24 -0
  79. package/skills/factory-build/SKILL.md +1 -1
  80. package/skills/factory-trace/SKILL.md +79 -0
  81. package/workflows/factory-build.yml +5 -4
  82. package/workflows/factory-deps-auto-merge.yml +3 -2
  83. package/workflows/factory-poller.yml +46 -0
package/docs/builds.md CHANGED
@@ -6,7 +6,7 @@ the cloud does the same with nobody at the keyboard: it runs on your code
6
6
  host's cloud runner, and you read its log or its pull request afterward.
7
7
 
8
8
  On GitHub, the cloud runner is GitHub Actions.
9
- [Setting up on GitHub](github/setup.md#builds-in-the-cloud) has the steps,
9
+ [Setting up on GitHub](github/setup.md) has the steps,
10
10
  and the [reference](github/reference.md#workflows) has what runs there.
11
11
 
12
12
  ## Three ways a build starts
@@ -15,16 +15,17 @@ and the [reference](github/reference.md#workflows) has what runs there.
15
15
  | ----------------------------------- | --------------------------------------- | ----------------------------------------------------------------- |
16
16
  | Ask a session: "build ticket 12" | In that session, wherever you opened it | Nothing |
17
17
  | Run `factory build 12` | In the cloud | Builds in the cloud set up |
18
- | Move the ticket to Ready on a board | In the cloud, within a minute | Builds in the cloud set up, and [the poller](#the-poller) running |
18
+ | Move the ticket to Ready on a board | In the cloud, at the poller's next pass | Builds in the cloud set up, and [the poller](#the-poller) running |
19
19
 
20
- Which of the last two you use is `builds.trigger` in your
20
+ Which of the last two you use is
21
+ [`builds.trigger`](configuration.md#builds) in your
21
22
  [settings](configuration.md#builds):
22
23
 
23
- | `trigger` | Moving a ticket to Ready |
24
- | --------------- | -------------------------------------------------------------------------------------------------------- |
25
- | `manual` | Records your approval and starts nothing. The default |
26
- | `own-server` | Starts a build within a minute, through the poller you host |
27
- | `github-action` | _[Planned](developing.md#what-is-built)_: starts one within minutes, from a schedule on the cloud runner |
24
+ | `trigger` | Moving a ticket to Ready |
25
+ | --------------- | ----------------------------------------------------------------------------------------------------------------- |
26
+ | `manual` | Records your approval and starts nothing. The default |
27
+ | `own-server` | Starts a build within a minute, through the poller you host |
28
+ | `github-action` | Starts one at the next pass of a schedule on the cloud runner, every `poll-minutes` minutes, with nothing to host |
28
29
 
29
30
  `manual` is a fine place to stay. Asking a session and running
30
31
  `factory build` work whatever the trigger.
@@ -54,8 +55,9 @@ so a failed run does not hold its ticket.
54
55
 
55
56
  **What it needs.** Two credentials, stored as secrets on the code host:
56
57
  the agent's token, which pays for the session, and an access token for the
57
- code host, which the build acts as. [Setting up on
58
- GitHub](github/setup.md#secrets) says how to make and store each.
58
+ code host, which the build acts as.
59
+ [`factory init`](github/setup.md#run-factory-init) asks for each and
60
+ stores it.
59
61
 
60
62
  **Who it acts as.** The build acts as whoever owns that access token. Its
61
63
  commits name your coding agent as their author and that account as their
@@ -92,9 +94,10 @@ yours in them and stop.
92
94
 
93
95
  ## The poller
94
96
 
95
- The poller is a small program of the factory's that never exits. Once a
96
- minute it reads your board, and for each ticket in Ready with no open
97
- blocker it:
97
+ The poller is a small program of the factory's. It runs on a server you
98
+ host, reading your board once a minute and never exiting, or as one pass
99
+ at a time on a schedule in the cloud. Each time it reads the board, for
100
+ each ticket in Ready with no open blocker it:
98
101
 
99
102
  1. posts a comment on the ticket saying a build is starting, carrying a
100
103
  marker;
@@ -111,9 +114,10 @@ does no further check.
111
114
 
112
115
  ### What it reads from its environment
113
116
 
114
- The poller runs with no copy of your repository, so it takes everything
115
- from environment variables. All four are required; it exits at startup
116
- naming any that is missing.
117
+ On a server you host, the poller runs with no copy of your repository, so
118
+ it takes everything from environment variables. All four are required; it
119
+ exits at startup naming any that is missing. On a schedule it has a
120
+ checkout, and needs only the token.
117
121
 
118
122
  | Variable | What it is |
119
123
  | ---------------------- | ------------------------------------------------------------------- |
@@ -122,10 +126,11 @@ naming any that is missing.
122
126
  | `FACTORY_BOARD_NUMBER` | Which board |
123
127
  | `FACTORY_BOARD_TOKEN` | An access token that can read the board, comment, and start a build |
124
128
 
125
- One more is optional. `FACTORY_READY_COLUMN` is the name of the column that
126
- approves a build, and defaults to Ready. The poller has no settings file,
127
- so a repository whose `tickets.columns.ready` names another column sets it
128
- where the poller runs. `factory board check` reminds you
129
+ One more is optional. `FACTORY_READY_COLUMN` is the name of the column
130
+ that approves a build, and defaults to Ready. The poller has no settings
131
+ file, so a repository whose
132
+ [`tickets.columns.ready`](configuration.md#ticketscolumns) names another
133
+ column sets it where the poller runs. `factory board check` reminds you
129
134
  when it applies.
130
135
 
131
136
  The repository and the board's number repeat what your settings file says,
@@ -135,8 +140,9 @@ a board owned by another account is not supported yet.
135
140
 
136
141
  ### Its limits
137
142
 
138
- - **It starts at most 20 builds an hour.** A ticket past that waits, and
139
- the poller's log says so. Each build may run as long as
143
+ - **It starts at most 20 builds an hour,** counted from the start comments
144
+ it posted, so a restart or a scheduled pass still knows them. A ticket
145
+ past that waits, and the poller's log says so. Each build may run as long as
140
146
  [`session-minutes`](configuration.md#session-minutes) allows, so several
141
147
  can run at once: each pays for its own minutes, and the cloud runner
142
148
  limits how many run at the same time.
@@ -151,25 +157,39 @@ a board owned by another account is not supported yet.
151
157
  The poller needs one always-on container with outbound network access and
152
158
  half a gigabyte of memory. It serves no traffic.
153
159
 
154
- The factory ships a Dockerfile for it, `poller.Dockerfile`. It installs
155
- nothing but Node and the poller, and runs as an unprivileged user. To try it
156
- on your machine, from the root of the factory's own repository:
160
+ Each release of the factory publishes the poller as a container image,
161
+ `ghcr.io/davidbyoung/software-factory-poller`, tagged with its version and
162
+ `latest`. It holds nothing but Node and that version of the factory, runs
163
+ as an unprivileged user, and needs no sign-in to pull. Run the version your
164
+ repository installs, with the variables above; `factory init` prints the
165
+ exact line. To try it on your machine:
157
166
 
158
167
  ```bash
159
- docker build -f poller.Dockerfile -t factory-poller .
160
168
  docker run \
161
169
  -e FACTORY_REPOSITORY=your-name/your-repo \
162
170
  -e FACTORY_BOARD_OWNER=your-name \
163
171
  -e FACTORY_BOARD_NUMBER=1 \
164
172
  -e FACTORY_BOARD_TOKEN \
165
- factory-poller
173
+ ghcr.io/davidbyoung/software-factory-poller:0.2.0
166
174
  ```
167
175
 
168
- _[Planned](developing.md#what-is-built)_: building it from an installed
169
- package, whose files are under `node_modules/`. Until then, the Dockerfile
170
- builds only from the factory's own repository, and a repository that uses
171
- the factory writes its own: a Node image that runs `npm ci` and then
172
- `npx --no-install factory poller`.
176
+ **A host that builds from your repository,** rather than running an image,
177
+ needs a Dockerfile there. Add one of a single line, such as
178
+ `poller/Dockerfile`:
179
+
180
+ ```dockerfile
181
+ FROM ghcr.io/davidbyoung/software-factory-poller:0.2.0
182
+ ```
183
+
184
+ and this entry in `.github/dependabot.yml`, so each new version of the
185
+ factory updates it, alongside the factory's own update:
186
+
187
+ ```yaml
188
+ - package-ecosystem: docker
189
+ directory: /poller
190
+ schedule:
191
+ interval: weekly
192
+ ```
173
193
 
174
194
  As an example, one setup runs it as a worker on DigitalOcean's App
175
195
  Platform, in the same app as the site it builds, for about $5 a month. Its
@@ -184,33 +204,65 @@ the factory never deploys it.
184
204
 
185
205
  | What you see | What happened | What to do |
186
206
  | --------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------- |
187
- | `factory status` flags a Ready ticket "not started" | The poller is down or stuck | Read its log |
188
- | A comment saying a build could not start, with a refusal from the code host | The token cannot start a build | Give it what [the setup](github/setup.md#secrets) names, then move the ticket to Ready again |
207
+ | `factory status` flags a Ready ticket "not started, is the poller running?" | The poller is down or stuck | Read its log |
208
+ | A comment saying a build could not start, with a refusal from the code host | The token cannot start a build | Give it what [Secrets](github/by-hand.md#secrets) names, then move the ticket to Ready again |
189
209
  | The board stops updating | The board's token is missing or expired | Replace it. The poller uses the same token |
190
- | A ticket in Ready is skipped | It is blocked by an open ticket | It starts within a minute of the blocker closing |
191
-
192
- ## A scheduled poller: `github-action` _[Planned](developing.md#what-is-built)_
210
+ | A ticket in Ready is skipped | It is blocked by an open ticket | It starts at the poller's first pass after the blocker closes |
193
211
 
194
- Until it is built, use the poller above, or `manual`.
212
+ ## A scheduled poller: `github-action`
195
213
 
196
- For a repository with nowhere to run a container. Setup would add a
197
- scheduled job on the cloud runner that runs the poller for one pass:
214
+ For a repository with nowhere to run a container. `factory sync` writes a
215
+ workflow, `factory-poller.yml`, that runs one pass of the poller on a
216
+ schedule, and by hand:
198
217
 
199
218
  ```bash
200
219
  factory poller --once
201
220
  ```
202
221
 
203
- It is a weaker poller, and you should know how before choosing it:
204
-
205
- - **It is slower.** The shortest schedule is every few minutes, and
206
- scheduled runs can start late.
207
- - **It can cost money on a private repository.** A run every five minutes
208
- is roughly 8,600 runs a month, each billed as at least a minute. That is
209
- an estimate, not a measurement.
210
- - **A scheduled job can be switched off** by the code host in a repository
211
- that goes quiet.
212
- - **The hourly cap needs a new home.** The poller keeps its count of recent
213
- builds in memory, which a run that exits loses.
222
+ It reads your board and the Ready column from your settings, and the
223
+ board's token from the secret the board sync already uses. Each build it
224
+ starts is a run of its own, so several build at once, as with the poller
225
+ you host. Two passes never overlap: a late one waits for the one before.
226
+
227
+ It is slower and can cost more than the poller you host, so know how
228
+ before choosing it:
229
+
230
+ - **It starts a build at its next pass.** The schedule runs every
231
+ `builds.poll-minutes` minutes, 5 at the fastest, and the cloud runner
232
+ starts scheduled runs late when it is busy: at 5, a build starts 5 to 15
233
+ minutes after the card moves, and longer at a longer interval.
234
+ - **It costs Actions minutes on a private repository.** Each pass is billed
235
+ as at least a minute, whether or not a card was Ready. A public
236
+ repository pays nothing.
237
+
238
+ | `poll-minutes` | Passes a month |
239
+ | -------------- | -------------- |
240
+ | 5, the default | 8,640 |
241
+ | 10 | 4,320 |
242
+ | 15 | 2,880 |
243
+ | 30 | 1,440 |
244
+ | 60 | 720 |
245
+
246
+ `factory init` asks the interval on a private repository, suggesting 30.
247
+
248
+ - **The code host can switch a schedule off** in a public repository that
249
+ goes quiet. `factory doctor` fails when it has, and says how to switch it
250
+ back on.
251
+
252
+ `factory status` flags a Ready card "not started, is the factory-poller
253
+ workflow running?" once it has waited the interval and 15 minutes more.
254
+
255
+ **Moving from a poller you host to the schedule,** stop the one you host:
256
+ both would start builds, and each start comment counts toward the 20 an
257
+ hour.
258
+
259
+ ### When the schedule fails
260
+
261
+ | What you see | What happened | What to do |
262
+ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------ |
263
+ | `factory status` flags a Ready ticket "not started, is the factory-poller workflow running?" | The workflow failed, or the code host switched it off | Run `factory doctor`, and read the workflow's last run |
264
+ | `factory doctor` says `factory-poller.yml is disabled` | The code host switched the schedule off in a quiet repository | Do what `doctor` says to switch it back on |
265
+ | A failed run of the workflow saying `not polling: FACTORY_BOARD_TOKEN not set` | The board's token is not a secret here | Run `factory init` to add it |
214
266
 
215
267
  [The reference](github/reference.md#limits) has GitHub's own numbers.
216
268
 
package/docs/cli.md CHANGED
@@ -26,14 +26,14 @@ such as "refine ticket 12". [Skills](skills.md) lists them.
26
26
 
27
27
  ## Setting up
28
28
 
29
- | Command | When you run it |
30
- | ---------------------- | ------------------------------------------------------------------------------------ |
31
- | `factory init` | Once, to set a repository up. Again, to turn a part on or off |
32
- | `factory sync` | After installing, updating, or editing `.claude/factory.yaml` |
33
- | `factory sync --check` | To see that the factory's files match your settings. It also runs in CI |
34
- | `factory config check` | To validate your settings. It also runs in CI |
35
- | `factory board check` | After pointing `tickets.board` at your board, to see how it reads it |
36
- | `factory doctor` | When something seems off. It checks the settings, files, version, secrets, and board |
29
+ | Command | When you run it |
30
+ | ---------------------- | ----------------------------------------------------------------------------------------------------------- |
31
+ | `factory init` | Once, to set a repository up. Again, to turn a part on or off |
32
+ | `factory sync` | After installing, updating, or editing `.claude/factory.yaml` |
33
+ | `factory sync --check` | To see that the factory's files match your settings. It also runs in CI |
34
+ | `factory config check` | To validate your settings. It also runs in CI |
35
+ | `factory board check` | After pointing [`tickets.board`](configuration.md#tickets) at your board, to see how it reads it |
36
+ | `factory doctor` | When something seems off. It checks the settings, files, version, secrets, board, and each tool's own setup |
37
37
 
38
38
  `init` asks its questions in the terminal, and reads each token in a
39
39
  masked prompt. `doctor` exits 1 when a check fails. GitHub never lets a
@@ -51,18 +51,18 @@ read is set.
51
51
 
52
52
  ## Now and then
53
53
 
54
- | Command | When you run it | State |
55
- | ------------------------ | ----------------------------------------------------------------- | ------- |
56
- | `factory config get KEY` | To print one setting in effect, such as `tickets.board` | Built |
57
- | `factory config explain` | To see every setting in effect, defaults included | Planned |
58
- | `factory plugins` | To see your plug-ins by role | Built |
59
- | `factory site compare` | To picture a website's pages before and after a change. See below | Built |
60
- | `factory site stop` | To end the sites `compare --keep` left running | Built |
61
- | `factory remove` | To take the factory out of a repository | Planned |
54
+ | Command | When you run it | State |
55
+ | ------------------------ | ----------------------------------------------------------------- | ----- |
56
+ | `factory config get KEY` | To print one setting in effect, such as `tickets.board` | Built |
57
+ | `factory config explain` | To see every setting in effect, defaults included | Built |
58
+ | `factory plugins` | To see your plug-ins by role | Built |
59
+ | `factory site compare` | To picture a website's pages before and after a change. See below | Built |
60
+ | `factory site stop` | To end the sites `compare --keep` left running | Built |
61
+ | `factory remove` | To take the factory out of a repository | Built |
62
62
 
63
63
  A new version is installed with npm and applied with `factory sync`, as
64
- [Updating](updating.md) says; until `remove` is built,
65
- [Removing](removing.md) lists what to delete by hand.
64
+ [Updating](updating.md) says. [Removing](removing.md) says what `remove`
65
+ deletes and what it leaves to you.
66
66
 
67
67
  ## Run for you
68
68
 
@@ -148,24 +148,23 @@ prints `no checks` and exits 0. A failure exits 3.
148
148
 
149
149
  ### Workflows and hooks
150
150
 
151
- | Command | Run by | What it does | State |
152
- | ------------------------------ | ----------------------------- | --------------------------------------------------------------------------------------- | ------- |
153
- | `factory migrate` | `factory-deps`, on an update | Converts your settings after a release changes their shape | Planned |
154
- | `factory board collect` | The board-sync workflow | Reads the tickets and posts the comments a closed pull request or the nightly run needs | Built |
155
- | `factory board apply` | The board-sync workflow | Sets each ticket's column and fields from its comments | Built |
156
- | `factory board sync --dry-run` | You, to see what it would set | The same, writing nothing | Planned |
157
- | `factory merge-policy N` | The merge-policy workflow | Decides whether N may merge without you, and why | Built |
158
- | `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit | Built |
159
- | `factory review cost` | The review workflow | Adds what the CI review cost to its summary | Built |
160
- | `factory review tools` | The review workflow | Prints the tools the CI review may use, from `ci-review.commands` | Built |
161
- | `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md) | Built |
162
- | `factory poller --once` | A schedule | One pass of the poller | Planned |
163
- | `factory guard` | A hook, before each command | Runs both guards below on one Bash call | Built |
164
- | `factory guard commit` | Within `factory guard` | Blocks a commit on your main branch, a force push, or a failing `before-commit` command | Built |
165
- | `factory guard ticket-text` | Within `factory guard` | Refuses ticket text with a bare `<tag>`, which the ticket system would swallow | Built |
166
- | `factory reviewers start` | A hook, when an agent starts | Records a reviewer's run on the ticket, for its cost | Built |
167
- | `factory reviewers stop` | A hook, when an agent stops | The same | Built |
168
- | `factory session-start` | A hook, when a session starts | Shows unfinished branches and each ticket's state | Built |
151
+ | Command | Run by | What it does | State |
152
+ | --------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----- |
153
+ | `factory board collect` | The board-sync workflow | Reads the tickets and posts the comments a closed pull request or the nightly run needs | Built |
154
+ | `factory board apply` | The board-sync workflow | Sets each ticket's column and fields from its comments | Built |
155
+ | `factory board --dry-run` | You, to see what it would set | Reads the tickets and the board, prints what the sync would set, and writes nothing | Built |
156
+ | `factory merge-policy N` | The merge-policy workflow | Decides whether N may merge without you, and why | Built |
157
+ | `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit | Built |
158
+ | `factory review cost` | The review workflow | Adds what the CI review cost to its summary | Built |
159
+ | `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`ci-review.commands`](configuration.md#ci-review) | Built |
160
+ | `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md) | Built |
161
+ | `factory poller --once` | The scheduled poller's workflow | One pass of the poller, with the board and Ready column from your settings | Built |
162
+ | `factory guard` | A hook, before each command | Runs both guards below on one Bash call | Built |
163
+ | `factory guard commit` | Within `factory guard` | Blocks a commit on your main branch, a force push, or a failing [`before-commit`](configuration.md#before-commit) command | Built |
164
+ | `factory guard ticket-text` | Within `factory guard` | Refuses ticket text with a bare `<tag>`, which the ticket system would swallow | Built |
165
+ | `factory reviewers start` | A hook, when an agent starts | Records a reviewer's run on the ticket, for its cost | Built |
166
+ | `factory reviewers stop` | A hook, when an agent stops | The same | Built |
167
+ | `factory session-start` | A hook, when a session starts | Shows unfinished branches and each ticket's state | Built |
169
168
 
170
169
  The board sync runs `collect` and `apply` as two steps, so the board's
171
170
  token reaches only the second. The board's number comes from
@@ -183,13 +182,14 @@ token reaches only the second. The board's number comes from
183
182
 
184
183
  ## `factory site`
185
184
 
186
- `factory site compare` starts the working tree with `site.start`, starts the
187
- default branch from a temporary git worktree on another port, shoots each page
188
- at each width in light and dark, and prints the pages that changed, with the
189
- pixels and rows. It writes the pictures before, after, and with what changed
185
+ `factory site compare` starts the working tree with
186
+ [`site.start`](configuration.md#site), starts the default branch from a
187
+ temporary git worktree on another port, shoots each page at each width in
188
+ light and dark, and prints the pages that changed, with the pixels and
189
+ rows. It writes the pictures before, after, and with what changed
190
190
  outlined, and `report.json`, under `node_modules/.cache/factory/site/`. It
191
- exits 0 whether or not anything changed, and non-zero only when it could not do
192
- its job.
191
+ exits 0 whether or not anything changed, and non-zero only when it could
192
+ not do its job.
193
193
 
194
194
  - **Three measurements** are made on each view that changed, a view being one
195
195
  page at one width in one scheme, on the base and on the branch, and only what
@@ -48,7 +48,7 @@ default.
48
48
  - **A board,** to see every ticket's state. Set `tickets.board` to your
49
49
  board's number, and when your columns have other names, map them under
50
50
  `tickets.columns`. [`tickets`](#tickets) has both. On GitHub,
51
- [Setting up on GitHub](github/setup.md#a-board) has the steps around
51
+ [Setting up on GitHub](github/setup.md) has the steps around
52
52
  them.
53
53
  - **What merges without you.** List the files that may under
54
54
  `auto-merge.allow`, such as your docs. [`auto-merge`](#auto-merge).
@@ -109,6 +109,10 @@ tickets:
109
109
  when you tell a session.
110
110
  - **If `board` is wrong:** the board sync fails and names the board it could
111
111
  not read.
112
+ - **One board can hold more than one repository's tickets.** Give each
113
+ repository the same `board`: each one's sync, `status`, and poller read
114
+ only the cards for its own issues, and GitHub's Repository field tells
115
+ them apart on the board.
112
116
 
113
117
  A board shows the six states of [Workflow](workflow.md) as columns, and
114
118
  keeps three fields the factory writes. A repository that writes nothing
@@ -141,8 +145,9 @@ state.
141
145
  when you tell a session to build the ticket or run
142
146
  `factory build N`, so
143
147
  `factory config check` requires `builds.trigger: manual`.
144
- - **If a repository's `ready` column has another name,** the poller needs it
145
- too: see `FACTORY_READY_COLUMN` in [Builds](builds.md).
148
+ - **If a repository's `ready` column has another name,** a poller you host
149
+ needs it too: see `FACTORY_READY_COLUMN` in [Builds](builds.md). A
150
+ scheduled one reads it from here.
146
151
  - `factory config get tickets.columns.ready` prints the
147
152
  name in effect, or `none`.
148
153
 
@@ -202,8 +207,6 @@ It reads no board.
202
207
  else. Only `github` is built. Any other value fails
203
208
  `factory config check` and every ticket command with:
204
209
  `tickets.type "X" is not supported. "github" is the only ticket system built.`
205
- A type that names a package, for an adapter you write yourself, is
206
- planned, not built.
207
210
 
208
211
  ### `code-host`
209
212
 
@@ -233,10 +236,11 @@ builds:
233
236
  runner: github-actions
234
237
  ```
235
238
 
236
- | Key | Meaning | Allowed | Default |
237
- | --------- | --------------------------------------------------- | --------------------------------------- | ---------------- |
238
- | `trigger` | What starts a build for a ticket you moved to Ready | `own-server`, `github-action`, `manual` | `manual` |
239
- | `runner` | Where a build in the cloud runs | `github-actions` | `github-actions` |
239
+ | Key | Meaning | Allowed | Default |
240
+ | -------------- | -------------------------------------------------------------------- | --------------------------------------- | ---------------- |
241
+ | `trigger` | What starts a build for a ticket you moved to Ready | `own-server`, `github-action`, `manual` | `manual` |
242
+ | `runner` | Where a build in the cloud runs | `github-actions` | `github-actions` |
243
+ | `poll-minutes` | How often the scheduled poller reads the board, with `github-action` | 5, 10, 15, 30, or 60 | 5 |
240
244
 
241
245
  `trigger` is what notices a card moved to Ready, and `runner` is where the
242
246
  build it starts then runs: a poller on your own server still starts its
@@ -247,13 +251,17 @@ the settings and reaches the runner, with:
247
251
 
248
252
  - **`manual`:** nothing watches the board. You tell a session "work 12".
249
253
  - **`own-server`:** a small poller you host reads the board once a minute.
250
- - **`github-action`:** a schedule on the cloud runner does the same, more
251
- slowly.
252
- _[Planned](developing.md#what-is-built)_: until it is built, use `own-server` or `manual`.
254
+ - **`github-action`:** a schedule on the cloud runner does the same every
255
+ `poll-minutes` minutes, with nothing to host. On a private repository,
256
+ each pass is billed as at least an Actions minute.
253
257
 
254
- [Builds](builds.md) explains each. **If `trigger` says `own-server` and no
255
- poller is running,** a ticket moved to Ready sits there, and
256
- `factory status` flags it "not started".
258
+ `factory config check` fails on `poll-minutes` beside any other trigger,
259
+ and on any value but the five above.
260
+
261
+ [Builds](builds.md) explains each. **If no poller is running,** a ticket
262
+ moved to Ready sits there, and `factory status` flags it "not started":
263
+ after 5 minutes with `own-server`, and after `poll-minutes` and 15 more
264
+ with `github-action`.
257
265
 
258
266
  ### `specs`
259
267
 
@@ -514,8 +522,7 @@ The automated review of every pull request: Claude reads each one once it
514
522
  is marked ready, comments on what it finds, and posts a verdict. It is on
515
523
  while `ci-review` is written, even with nothing under it, and `factory
516
524
  sync` then writes its workflow, `.github/workflows/factory-claude-review.yml`.
517
- [The automated review](github/setup.md#the-automated-review) has the steps
518
- it needs on GitHub.
525
+ [Setting up on GitHub](github/setup.md) has what it needs on GitHub.
519
526
 
520
527
  ```yaml
521
528
  # The automated review of every pull request, on while this is written.
@@ -565,10 +572,9 @@ and never takes one as an instruction.
565
572
 
566
573
  ### `rules`
567
574
 
568
- _[Planned](developing.md#what-is-built)_: `factory config check`
569
- refuses this key until it is built.
570
-
571
575
  Numbers the process rules use, for a repository that wants different ones.
576
+ `factory sync` writes each into the copies of the rules and skills that
577
+ state it, so run it after changing one.
572
578
 
573
579
  ```yaml
574
580
  rules:
@@ -576,10 +582,10 @@ rules:
576
582
  review-rounds: 2
577
583
  ```
578
584
 
579
- | Key | Meaning | Default |
580
- | -------------------- | --------------------------------------------------------------------- | ------- |
581
- | `small-change-lines` | A change under this many lines, outside tests, takes the lighter path | `30` |
582
- | `review-rounds` | Rounds a session works a review before it hands what is left to you | `2` |
585
+ | Key | Meaning | Default |
586
+ | -------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------- |
587
+ | `small-change-lines` | A change under this many lines outside tests, specs, and content, adding no component and no state, takes the lighter path | `30` |
588
+ | `review-rounds` | Rounds a session works a review before it hands what is left to you | `2` |
583
589
 
584
590
  - **If a value is not a whole number above zero:**
585
591
  `factory config check` fails and names the key.
@@ -590,12 +596,12 @@ factory's rules.
590
596
 
591
597
  ## Checking the file
592
598
 
593
- | Command | What it does |
594
- | ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
595
- | Your editor | The first line of the file points at the factory's schema, which flags a misspelled key as you type it |
596
- | `factory config check` | Fails on an unknown key, a wrong type, a plug-in with no file, and warns on a pattern matching nothing. Runs in CI |
597
- | `factory config explain` | _[Planned](developing.md#what-is-built)_: Prints every setting in effect, with whether it is the default or yours |
598
- | `factory doctor` | Checks the file against the real board, and that each secret your parts read is set |
599
+ | Command | What it does |
600
+ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
601
+ | Your editor | The first line of the file points at the factory's schema, which flags a misspelled key as you type it |
602
+ | `factory config check` | Fails on an unknown key, a wrong type, a plug-in with no file, and warns on a pattern matching nothing. Runs in CI |
603
+ | `factory config explain` | Prints every setting in effect, as the file would read with every default written out, each default marked `# default` |
604
+ | `factory doctor` | Checks the file against the real board, and that each secret your parts read is set |
599
605
 
600
606
  The first line of the file, which the three files below start with:
601
607
 
@@ -798,8 +804,8 @@ auto-merge:
798
804
  ```
799
805
 
800
806
  If this team moved its tickets to Jira, only the `tickets` block would
801
- change. **No Jira support is built or planned**; the block below shows the
802
- shape the design leaves room for.
807
+ change. **Only GitHub is built**; the block below shows the shape the
808
+ design leaves room for.
803
809
 
804
810
  ```yaml
805
811
  tickets:
package/docs/design.md CHANGED
@@ -87,7 +87,7 @@ They are separate on purpose.
87
87
 
88
88
  | Number | Where it is | Changes when |
89
89
  | ------------------- | -------------------------------------------- | ------------------------------------ |
90
- | The factory's | `package.json` and `.claude/factory.lock` | Every release |
90
+ | The factory's | The installed package and `factory.lock` | Every release |
91
91
  | The settings file's | `version:` at the top of `factory.yaml` | A key is renamed or moved |
92
92
  | The markers' | In the comments the factory posts on tickets | The format of those comments changes |
93
93