@davidbyoung/software-factory 0.1.10 → 0.1.12

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/agents/factory-e2e-reviewer.md +1 -1
  2. package/agents/factory-test-reviewer.md +1 -1
  3. package/agents/factory-ticket-readiness.md +20 -15
  4. package/agents/factory-ui-reviewer.md +2 -2
  5. package/dist/board.d.mts +8 -8
  6. package/dist/board.mjs +53 -37
  7. package/dist/build.d.mts +4 -0
  8. package/dist/build.mjs +9 -4
  9. package/dist/cli.mjs +25 -5
  10. package/dist/code-host/github.mjs +11 -4
  11. package/dist/code-host/types.d.mts +8 -2
  12. package/dist/commands.d.mts +7 -2
  13. package/dist/commands.mjs +96 -17
  14. package/dist/config.d.mts +3 -4
  15. package/dist/config.mjs +7 -8
  16. package/dist/init.d.mts +11 -0
  17. package/dist/init.mjs +56 -1
  18. package/dist/lib/clock.d.mts +3 -1
  19. package/dist/lib/clock.mjs +12 -6
  20. package/dist/lib/pull-tickets.d.mts +15 -0
  21. package/dist/lib/pull-tickets.mjs +12 -0
  22. package/dist/lib/usage.d.mts +3 -1
  23. package/dist/lib/usage.mjs +4 -2
  24. package/dist/lib/work-status.d.mts +28 -24
  25. package/dist/lib/work-status.mjs +21 -35
  26. package/dist/merge-policy.mjs +7 -3
  27. package/dist/poller.d.mts +3 -3
  28. package/dist/poller.mjs +18 -14
  29. package/dist/pr.d.mts +26 -6
  30. package/dist/pr.mjs +92 -28
  31. package/dist/review-tickets.d.mts +12 -0
  32. package/dist/review-tickets.mjs +59 -0
  33. package/dist/review-verdict.d.mts +22 -4
  34. package/dist/review-verdict.mjs +55 -17
  35. package/dist/reviewers.d.mts +7 -4
  36. package/dist/reviewers.mjs +19 -12
  37. package/dist/runner/github-actions.mjs +6 -7
  38. package/dist/runner/types.d.mts +7 -6
  39. package/dist/specs/index.d.mts +6 -0
  40. package/dist/specs/index.mjs +15 -0
  41. package/dist/specs/openspec.d.mts +2 -0
  42. package/dist/specs/openspec.mjs +78 -0
  43. package/dist/specs/types.d.mts +53 -0
  44. package/dist/specs/types.mjs +4 -0
  45. package/dist/status.d.mts +17 -7
  46. package/dist/status.mjs +35 -23
  47. package/dist/sync.d.mts +4 -0
  48. package/dist/sync.mjs +14 -1
  49. package/dist/ticket.d.mts +15 -7
  50. package/dist/ticket.mjs +128 -61
  51. package/dist/tickets/github-access.d.mts +5 -0
  52. package/dist/tickets/github-access.mjs +22 -0
  53. package/dist/tickets/github.d.mts +10 -2
  54. package/dist/tickets/github.mjs +76 -20
  55. package/dist/tickets/index.d.mts +7 -1
  56. package/dist/tickets/index.mjs +15 -1
  57. package/dist/tickets/types.d.mts +63 -30
  58. package/dist/tickets/types.mjs +13 -3
  59. package/dist/tool-names.d.mts +2 -0
  60. package/dist/tool-names.mjs +3 -0
  61. package/dist/tools.d.mts +2 -0
  62. package/dist/tools.mjs +3 -0
  63. package/docs/builds.md +4 -1
  64. package/docs/cli.md +30 -11
  65. package/docs/configuration.md +51 -39
  66. package/docs/developing.md +115 -62
  67. package/docs/existing-repo.md +4 -3
  68. package/docs/github/reference.md +1 -1
  69. package/docs/github/setup.md +20 -3
  70. package/docs/glossary.md +7 -6
  71. package/docs/limitations.md +8 -5
  72. package/docs/plugins.md +6 -6
  73. package/docs/updating.md +18 -0
  74. package/docs/workflow.md +25 -8
  75. package/package.json +1 -1
  76. package/review.md +11 -11
  77. package/rules.md +52 -42
  78. package/skills/factory-address-review/SKILL.md +44 -42
  79. package/skills/factory-build/SKILL.md +71 -72
  80. package/skills/factory-refine/SKILL.md +31 -23
  81. package/skills/factory-resolve-conflicts/SKILL.md +12 -10
  82. package/workflows/factory-build.yml +6 -5
  83. package/workflows/factory-claude-review.yml +38 -1
@@ -27,9 +27,11 @@ as a code host's billing or what its workflows can see, are in
27
27
  there. A change to those settings is a person's to make.
28
28
  - **One ticket, one repository.** A change that spans repositories is two
29
29
  tickets.
30
- - **It is written for one approver.** `approvers` lets a team list several
31
- people (_[Planned](developing.md#what-is-built)_), but review by teams, required reviewers per folder, and monorepos
32
- with several owners are not designed.
30
+ - **Review by teams is your code host's to enforce.** A session obeys
31
+ anyone who can write to the repository. Required reviewers for a
32
+ folder, and a number of approvals before a merge, are rules you set on
33
+ the code host, and the factory's pull requests are held by them like
34
+ any other.
33
35
  - **The order of the workflow is fixed.** A [plugin](plugins.md) of
34
36
  yours can replace how a ticket is refined, how a ticket with one of your
35
37
  labels is built, how a test is proved able to fail, which agents review
@@ -127,8 +129,9 @@ as a code host's billing or what its workflows can see, are in
127
129
  - **It amplifies the checks it is given.** A repository with weak tests gets
128
130
  confident, wrong pull requests faster.
129
131
  - **Ticket text, review comments, and changelogs are read by sessions.**
130
- Only an approver's comments are treated as instructions, and that rests on
131
- one account's login.
132
+ Only an approver's words are treated as instructions, and that rests on
133
+ who your code host says can write to the repository. Give write access
134
+ as carefully as you would give a session its orders.
132
135
  - **An update delivers instructions that run with your tokens.** Read update
133
136
  pull requests as carefully as code.
134
137
  - **It sits on tools that change.** Several parts work around how today's
package/docs/plugins.md CHANGED
@@ -74,12 +74,12 @@ plugins:
74
74
  skill: acme-refine
75
75
  ```
76
76
 
77
- | Step | What happens |
78
- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
- | **Called** | When you run `/factory-refine N` in a session: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited |
80
- | **Handed** | The ticket's number. From `factory-build`, for a round of questions you approved while it waited on your answers, also the words "approved while waiting: fold the owner's replies into the body, post no marker". They tell the refiner to write your replies into the ticket's body and to post no [marker](glossary.md), the hidden comment line the board reads |
81
- | **Returns** | A ticket a build can start from: everything in the list below |
82
- | **Then** | The ticket waits for your approval, and the build reads what the refiner left |
77
+ | Step | What happens |
78
+ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
+ | **Called** | When you run `/factory-refine N` in a session: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited |
80
+ | **Handed** | The ticket's key. From `factory-build`, for a round of questions you approved while it waited on your answers, also the words "approved while waiting: fold the owner's replies into the body, post no marker". They tell the refiner to write your replies into the ticket's body and to post no [marker](glossary.md), the hidden comment line the board reads |
81
+ | **Returns** | A ticket a build can start from: everything in the list below |
82
+ | **Then** | The ticket waits for your approval, and the build reads what the refiner left |
83
83
 
84
84
  **What a refiner must deliver.** The board and the build read these, so a
85
85
  refiner that leaves one out leaves a ticket that cannot be built.
package/docs/updating.md CHANGED
@@ -332,6 +332,24 @@ again, and you close the issue `factory-deps` opened.
332
332
  `✓ The settings are valid.`, and `factory ticket branch 12` prints the
333
333
  branch a build of ticket 12 would push.
334
334
 
335
+ ## A spec for every visible change
336
+
337
+ From this release, a change your users will see, and that isn't small,
338
+ gets the `spec` label and a [Spec, a design, and a list of
339
+ tasks](workflow.md#a-change-your-users-will-see) in its ticket, whatever
340
+ [`specs`](configuration.md#specs) says. Before it, a repository with
341
+ `specs: none`, or no `specs` line, which means the same, got only a list
342
+ of acceptance criteria. Nothing stops on the update: tickets refined
343
+ earlier build as they are, and the next one refinement writes has the
344
+ longer shape.
345
+
346
+ `factory specs change-name N` is gone. A script of yours that ran it
347
+ runs `factory specs new N` and `factory specs finish N` instead
348
+ ([Your repository's commands](cli.md#your-repositorys-commands)).
349
+
350
+ The next time you run `factory init`, it asks once which spec tool you
351
+ use, and writes your answer; choosing OpenSpec installs it.
352
+
335
353
  ## The commands
336
354
 
337
355
  | Command | When |
package/docs/workflow.md CHANGED
@@ -188,11 +188,28 @@ verdict.
188
188
 
189
189
  ## A change your users will see
190
190
 
191
- With [`specs: openspec`](configuration.md#specs), a change that adds or
192
- alters behavior someone can see, and is not small, carries the `spec`
193
- label. Its ticket holds a "Spec" section of plain "When this, then that"
194
- lines. The build turns those lines into an OpenSpec change, builds to
195
- them, and folds them into `openspec/specs/` in the same pull request, so
196
- that folder always describes what the project does now.
197
-
198
- With `specs: none`, the ticket's acceptance criteria are the whole spec.
191
+ A change that adds or alters behavior someone can see, and is not
192
+ [small](#sizing-the-work-to-the-change), gets the `spec` label, which
193
+ refinement adds and the build reads. Refinement writes three things into
194
+ its ticket, after your own text:
195
+
196
+ - **Spec:** what the change must do, as numbered "When this, then that"
197
+ lines, such as "3. When a visitor sends the form with no email, the
198
+ form still sends." To change one, name it by its number where
199
+ refinement asks you, in the session or in a comment on the ticket,
200
+ such as "3: and when the email is not valid, it says so."
201
+ - **Design:** where the change goes and the cases it must handle.
202
+ - **Tasks:** the steps to build it, each naming the test that checks it.
203
+
204
+ The design and tasks sit in a collapsed "For the builder" section, so
205
+ you can read the Spec and approve the ticket as you approve any other
206
+ ([From a ticket to a merge](#from-a-ticket-to-a-merge)). The build works
207
+ from the ticket alone, and its pull request's description lists the
208
+ test that checks each Spec line.
209
+
210
+ A [spec tool](configuration.md#specs), such as OpenSpec, also keeps the
211
+ Spec in your repository.
212
+
213
+ Every other ticket, such as a bug fix, a copy change, or a small change,
214
+ has a list of acceptance criteria instead: what must be true for it to
215
+ be done.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davidbyoung/software-factory",
3
- "version": "0.1.10",
3
+ "version": "0.1.12",
4
4
  "description": "Refines, builds, and reviews tickets with Claude Code sessions, from a board to a merged pull request.",
5
5
  "license": "MIT",
6
6
  "repository": {
package/review.md CHANGED
@@ -56,21 +56,21 @@ defend.
56
56
  the facts; if you still disagree, say so once in the summary, with your
57
57
  evidence, rather than opening a new thread.
58
58
 
59
- 4. Read what the pull request was asked to do. Its body, and the issues it
60
- closes:
59
+ 4. Read what the pull request was asked to do: its body, and the tickets it
60
+ builds, which the workflow has read for you into the file TICKETS names.
61
+ Read that file with the Read tool. Each ticket there starts with a `## `
62
+ line naming it and its title. When the file says the tickets could not be
63
+ read, say so in the summary and go by the body.
61
64
 
62
65
  ```bash
63
- gh pr view PR_NUMBER --json body,closingIssuesReferences
64
- gh api graphql -F n=ISSUE_NUMBER -f query='query($n: Int!) { repository(owner: "OWNER", name: "NAME") { issue(number: $n) { body } } }' --jq .data.repository.issue.body
66
+ gh pr view PR_NUMBER --json body
65
67
  ```
66
68
 
67
- OWNER and NAME are the two halves of REPO.
68
-
69
- The issue's "Spec" and "Acceptance criteria" sections are what the
70
- change must do, and its "Decisions" are settled. An issue with neither
69
+ The ticket's "Spec" and "Acceptance criteria" sections are what the
70
+ change must do, and its "Decisions" are settled. A ticket with neither
71
71
  is held only to what it plainly asks for: a fix it suggests is not a
72
- criterion. The follow-ups issue, closed or only linked, is held to the lines the
73
- body says this pull request built. A pull request that closes no issue,
72
+ criterion. The follow-ups ticket is held to the lines the
73
+ body says this pull request built. A pull request that builds no ticket,
74
74
  such as a source audit, has only its body to go by.
75
75
 
76
76
  ## What to look for
@@ -79,7 +79,7 @@ defend.
79
79
  that is silently dropped.
80
80
  - **What it was asked to do.** A Spec line or criterion from step 4 that
81
81
  the whole pull request, `git diff origin/DEFAULT...HEAD`, does not meet, or
82
- meets only in part, is a finding, since the merge closes the issue as
82
+ meets only in part, is a finding, since the merge closes the ticket as
83
83
  done: High when a user would see the gap, Medium otherwise. Behavior
84
84
  no line asked for is Medium, unless the body or the owner's comments on
85
85
  the pull request explain it. Quote the line either way.
package/rules.md CHANGED
@@ -30,11 +30,11 @@ here rather than restate it.
30
30
  such as "small: one test, red first, one UI reviewer read", so the
31
31
  owner can overrule it before the work starts rather than halfway through.
32
32
  - **No `spec` label**, even when a user sees it: the issue's acceptance
33
- criteria are the spec. No OpenSpec change either, unless the change makes
34
- a line of `openspec/specs/` false, as renaming a label a spec quotes
35
- would. That issue also carries a Spec section of the changed line, and
36
- the build archives a proposal and spec delta in the same pull request,
37
- which then waits for the owner. A fix that restores what a spec says
33
+ criteria are the spec. No spec tool change either, unless the change
34
+ makes a line of a spec `npx --no-install factory specs list` prints
35
+ false, as renaming a label a spec quotes would. That issue also carries
36
+ a Spec section of the changed line, and the build folds it into the
37
+ specs in the same pull request, which then waits for the owner. A fix that restores what a spec says
38
38
  changes no line of it.
39
39
  - **No `factory-ticket-readiness` read and no read by the test reviewers**
40
40
  (`npx --no-install factory plugins test-reviewer` lists them), with two
@@ -109,8 +109,9 @@ discovering it at push time.
109
109
  `npx --no-install factory pr state N --wait`, and does not run it, since
110
110
  nothing can wake it once it stops.
111
111
  - **A pull request that resolves an issue closes it.** When asked to open
112
- one, start the body with `Closes #N` for each issue the branch resolves,
113
- so the merge closes them. Check that GitHub registered the link.
112
+ one, start the body with the line `npx --no-install factory ticket link N`
113
+ prints for each issue the branch resolves, so the merge closes them. Check that `npx --no-install factory pr closes PR`
114
+ prints each one.
114
115
  - **After pushing, check for review automatically.** The `Claude review`
115
116
  workflow reviews every push to a PR. If an open PR exists for the branch,
116
117
  wait for the review of that push, then work it with the `factory-address-review` skill
@@ -167,28 +168,34 @@ always the owner's.
167
168
 
168
169
  ## Spec track
169
170
 
170
- The spec track applies only when
171
- `npx --no-install factory config get specs` prints `openspec`. Then the GitHub
172
- issue is the spec: `factory-refine` writes it, the owner approves it by
173
- moving its card to Ready or telling a session to build it, and
174
- `factory-build` turns it into an OpenSpec change, builds it, and archives it
175
- into `openspec/specs/` in the same pull request. `openspec/specs/` is the
176
- current description of what the repository does; a change to it starts by
177
- reading its spec.
178
-
179
- A change that adds or alters behavior a user can see carries the
180
- `spec` label, which `factory-refine` adds, unless it is small ("Small
181
- changes" above). Everything else, such as copy, bug fixes that
182
- restore intended behavior, style tweaks, tooling, CI, and docs, builds
183
- from the issue's "Acceptance criteria" with no spec files and no "For the
184
- builder" section, since the area's `CLAUDE.md` says how it is built. A
185
- small change that makes a spec line false is the one exception ("Small
186
- changes" above). Neither skill removes `spec` or adds it back once
187
- the owner removed it: both act through the owner's GitHub account, so a
188
- label already decided is the owner's call.
189
-
190
- OpenSpec collects anonymous usage statistics unless told not to. Run it with
191
- `DO_NOT_TRACK=1`.
171
+ The ticket is the spec: `factory-refine` writes it, the owner
172
+ approves it by moving its card to Ready or telling a session to build
173
+ it, and `factory-build` builds it. A change that adds or alters behavior
174
+ a user can see carries the `spec` label, which `factory-refine` adds,
175
+ unless it is small ("Small changes" above), whatever spec tool the
176
+ repository uses. Its issue holds "Decisions", numbered "Spec" lines, and
177
+ "For the builder" with a design and tasks, so a build needs nothing
178
+ else.
179
+
180
+ Everything else, such as copy, bug fixes that restore intended behavior,
181
+ style tweaks, tooling, CI, and docs, builds from the issue's "Acceptance
182
+ criteria" with no spec files and no "For the builder" section, since the
183
+ area's `CLAUDE.md` says how it is built. A small change that makes a
184
+ spec line false is the one exception ("Small changes" above). Neither
185
+ skill removes `spec` or adds it back once the owner removed it: both act
186
+ through the owner's GitHub account, so a label already decided is the
187
+ owner's call.
188
+
189
+ A spec tool, which `npx --no-install factory config get specs` names,
190
+ also keeps each Spec in the repository: `factory-build` starts it with
191
+ `npx --no-install factory specs new N` and folds it in with
192
+ `npx --no-install factory specs finish N`, in the same pull request.
193
+ `npx --no-install factory specs list` prints the specs the repository
194
+ keeps, its current description of what it does; a change to one starts
195
+ by reading it. With `specs: none` each of these says each ticket holds
196
+ its own spec, and the issue is the only copy. No skill, agent, rule, or
197
+ workflow runs a spec tool's own commands: the `factory specs` commands
198
+ reach it.
192
199
 
193
200
  ## Issues that wait on another
194
201
 
@@ -211,8 +218,8 @@ npx --no-install factory ticket blockers N
211
218
  npx --no-install factory ticket unblock N --by M
212
219
  ```
213
220
 
214
- `blockers` prints one line per ticket N waits on, its number and whether
215
- it is open. A ticket system without blockers says so: check with
221
+ `blockers` prints one line per ticket N waits on, as the ticket system
222
+ writes it, and whether it is open. A ticket system without blockers says so: check with
216
223
  `npx --no-install factory ticket supports blockers`.
217
224
 
218
225
  ## Follow-ups
@@ -229,18 +236,20 @@ labeled `follow-up`, holding a checklist. A line leads with the file or
229
236
  page it is about:
230
237
 
231
238
  ```
232
- - [ ] <file or page>: <what is wrong, as a user or a maintainer sees it>. Found by <who> while building #N. <The rule it breaks, by its section in the guide that states it (an area's guide under "Rules by area" in CLAUDE.md, CLAUDE.md, or this file), or "Needs a decision: <the question>".>
239
+ - [ ] <file or page>: <what is wrong, as a user or a maintainer sees it>. Found by <who> while building <ticket>. <The rule it breaks, by its section in the guide that states it (an area's guide under "Rules by area" in CLAUDE.md, CLAUDE.md, or this file), or "Needs a decision: <the question>".>
233
240
  ```
234
241
 
235
242
  It is added with the file and the rest of the line as two arguments, and
236
243
  the script opens the issue when none is open:
237
244
 
238
245
  ```bash
239
- npx --no-install factory follow-up FILE "What is wrong. Found by WHO while building #N. The rule it breaks."
246
+ npx --no-install factory follow-up FILE "What is wrong. Found by WHO while building TICKET. The rule it breaks."
240
247
  ```
241
248
 
242
- A reviewer that does not know the issue or pull request number writes
243
- `#N` as it stands, and whoever appends the line fills it in.
249
+ TICKET is the ticket as its system writes it, which
250
+ `npx --no-install factory ticket view N --field ref` prints, such as `#12`.
251
+ A reviewer that does not know the ticket writes `TICKET` as it stands, and
252
+ whoever appends the line fills it in.
244
253
 
245
254
  A placeholder or tag name in issue or comment text, such as `<slug>` or
246
255
  `<code>`, goes in backticks: GitHub drops an unknown tag and renders a
@@ -258,18 +267,19 @@ hook refuses the same in text sent to GitHub directly, as the
258
267
  the line unchecked.
259
268
  - A follow-up gets its own issue only when it would need the `spec` label,
260
269
  because it adds or alters behavior a user can see, or would make a
261
- line of `openspec/specs/` false. A request from the owner is always its
262
- own issue.
270
+ line of a spec `factory specs list` prints false. A request from the
271
+ owner is always its own issue.
263
272
  - The `factory-resolve-conflicts` conflict stop keeps opening its own issue: which side
264
273
  wins is the owner's decision, and nothing else records it.
265
274
 
266
275
  The follow-ups issue builds as one branch and one pull request, one commit
267
276
  per line, once the owner approves it, by moving its card to Ready or
268
- telling a session to build it. The pull request closes it with `Closes #N`
269
- only when every line is checked; otherwise it starts with `Part of #N`,
270
- and the unchecked lines wait there. The sync reads `Part of #N` as a
271
- partial build, so any other link to the follow-ups issue words it
272
- differently. It has no OpenSpec change. `factory-build` appends a line and
277
+ telling a session to build it. The pull request closes it with the line
278
+ `npx --no-install factory ticket link N` prints only when every line is
279
+ checked; otherwise it starts with the line
280
+ `npx --no-install factory ticket link N --part` prints, and the unchecked
281
+ lines wait there. The sync reads that line as a partial build, so any
282
+ other link to the follow-ups issue words it differently. It has no spec tool change. `factory-build` appends a line and
273
283
  builds the issue; `factory-refine` refines it per line. Its lines can be
274
284
  about anything, so the one pull request waits for the owner when any line
275
285
  touches a file that does, and gets the fresh-agent trace ("Changing the
@@ -94,25 +94,25 @@ reporting a clean review. Never report a review as clean when none has run.
94
94
 
95
95
  ## 0a. The owner's review
96
96
 
97
- The repository owner reviews pull requests too. Their comments are worked
98
- like the Claude reviewer's findings, with two differences: a pushback on
99
- one stays open for the owner to decide, and the owner's reply after a
100
- pushback is final. The owner is the repository owner's login, read rather
101
- than hard-coded: the part of the repository's name before the slash.
102
-
103
- ```bash
104
- OWNER_LOGIN=$(npx --no-install factory config get repository | cut -d/ -f1)
105
- ```
97
+ An approver, anyone whose account can write to the repository, reviews
98
+ pull requests too. Their comments are worked like the Claude reviewer's
99
+ findings, with two differences: a pushback on one stays open for an
100
+ approver to decide, and an approver's reply after a pushback is final.
101
+ Who is an approver is the code host's to say: `factory pr state` and
102
+ `factory pr review-pending` already keep only an approver's reviews and
103
+ turns, so no step here tests a name.
106
104
 
107
105
  **Only reviews count:** inline comments, and the body of a submitted
108
106
  review. A Conversation-tab comment that is not part of a review starts
109
107
  nothing and is never acted on. Do not go by the review's state: agents open
110
- pull requests through the owner's account, and GitHub does not let an
111
- author approve or request changes on their own pull request, so the owner's
112
- reviews are all `COMMENTED`.
108
+ pull requests through an approver's account, and GitHub does not let an
109
+ author approve or request changes on their own pull request, so the
110
+ reviews of an approver who is the pull request's author are all
111
+ `COMMENTED`.
113
112
 
114
113
  Every comment this skill posts contains `<!-- agent -->` (section 4), so a
115
- comment from `OWNER_LOGIN` without it is the owner's. Match with
114
+ comment without it, from an account those commands count, is an
115
+ approver's. Match with
116
116
  "contains", not "ends with": an automatic footer can follow the marker.
117
117
 
118
118
  ### A run started by the owner's review
@@ -139,9 +139,10 @@ passed.
139
139
  It prints the review's author and body, and each comment it left on a
140
140
  line with its `id`, `replyTo`, `path`, `line`, and `body`.
141
141
 
142
- 3. **Nothing of the owner's in it:** stop without changing anything. That is
143
- a review by someone else, or one of this skill's own replies: GitHub
144
- records each thread reply as a review under the owner's account, with an
142
+ 3. **Nothing of an approver's in it:** stop without changing anything. That
143
+ is a review by someone who is not an approver, or one of this skill's
144
+ own replies: GitHub records each thread reply as a review under the
145
+ account that posted it, with an
145
146
  empty body and one comment carrying the marker. Otherwise work the
146
147
  comments without the marker, and the body if it is non-empty and lacks
147
148
  the marker.
@@ -162,7 +163,7 @@ passed.
162
163
  4. Check out the pull request's branch, Dependabot's included. Read whether
163
164
  it can merge as `factory-address-review` section 0 does, and if that is `dirty`
164
165
  and the pull request is one the conflict sweep's queue admits, run "A
165
- conflict with the default branch" in the `factory-resolve-conflicts` skill first, then work each comment as "Each owner comment"
166
+ conflict with the default branch" in the `factory-resolve-conflicts` skill first, then work each comment as "Each approver comment"
166
167
  below says. Run the gate ("Gate" under "A
167
168
  conflict with the default branch" in that skill), commit, and push to that branch
168
169
  only, never with force. **A push refused because the branch moved**
@@ -176,13 +177,13 @@ passed.
176
177
  section 8, reporting as section 8 lays out. Otherwise no review is
177
178
  coming: work the review threads that already exist, and end with the
178
179
  same report. In this loop, section 1 works only the threads
179
- `github-actions[bot]` opened; owner threads belong to the runs their
180
+ `github-actions[bot]` opened; approver threads belong to the runs their
180
181
  reviews started.
181
182
  6. **Only the latest push's run goes on.** In step 5's loop only, before
182
183
  working a Claude review and again before each push it makes, compare the pull request's head with your
183
184
  last commit (`npx --no-install factory pr view N --field head`). If
184
185
  another run has pushed since, stop: its push starts the next Claude
185
- review, and that run works it, open threads included. A push of owner
186
+ review, and that run works it, open threads included. A push of approver
186
187
  fixes in step 4 that is refused is still pulled and pushed again.
187
188
 
188
189
  Each run works only its own review, and only the run that pushed last
@@ -197,19 +198,19 @@ This run never merges, enables auto-merge, marks a draft ready, or adds the
197
198
  branch.
198
199
 
199
200
  **Outside a run started by a review,** as in a local session working the
200
- pull request, the owner comments to work are the unresolved threads whose
201
- last comment is the owner's and lacks the marker, and the non-empty owner
202
- review bodies submitted after the last Conversation comment carrying the
201
+ pull request, the approver comments to work are the unresolved threads
202
+ whose last comment is an approver's and lacks the marker, and the non-empty
203
+ approver review bodies submitted after the last Conversation comment carrying the
203
204
  marker. A comment that also carries `<!-- conflict-fix -->`,
204
205
  `conflict-stop`, or `<!-- session-handoff -->`, the `factory-resolve-conflicts` skill's
205
206
  comment markers, does not count as that last comment, so a sweep's comment
206
- does not hide an owner's unanswered review body. Thread replies do not count there, since a reply on one thread does
207
- not answer a review body. The report lists these as "owner review bodies
208
- to answer", and marks an unresolved thread "owner's turn" when its last
209
- comment is the owner's without the marker. Read a review body in full
207
+ does not hide an approver's unanswered review body. Thread replies do not count there, since a reply on one thread does
208
+ not answer a review body. The report lists these as "approver review bodies
209
+ to answer", and marks an unresolved thread "approver's turn" when its last
210
+ comment is an approver's without the marker. Read a review body in full
210
211
  with `npx --no-install factory pr review N ID`.
211
212
 
212
- ### Each owner comment
213
+ ### Each approver comment
213
214
 
214
215
  A comment with a `replyTo` is a reply in an existing thread: read
215
216
  the whole thread first (`npx --no-install factory pr threads N --all`
@@ -223,19 +224,19 @@ to see whether it follows a pushback of yours.
223
224
  - **Agreed:** fix it (section 3), push, reply with what changed and the
224
225
  commit, and resolve the thread.
225
226
  - **Disagreed:** reply once with the evidence, a quoted source, a failing
226
- test, or the code, and leave the thread open. Never resolve an owner
227
+ test, or the code, and leave the thread open. Never resolve an approver
227
228
  thread you did not fix, except as the next bullet says.
228
- - **The owner replied after your pushback.** That reply is final; do not
229
+ - **An approver replied after your pushback.** That reply is final; do not
229
230
  push back again.
230
231
  - **It asks for the change:** make it, reply that you are following the
231
- owner's call, with the commit, and resolve the thread.
232
+ approver's call, with the commit, and resolve the thread.
232
233
  - **It accepts the pushback:** reply that you are leaving the code as it
233
- is, per the owner's reply, and resolve the thread.
234
+ is, per that reply, and resolve the thread.
234
235
  - **You cannot tell which:** ask in one line and leave it open.
235
236
  - **A review body.** Handle each point in it the same way, and answer it in
236
237
  the end comment (section 4); there is no thread to resolve.
237
238
 
238
- Owner threads are outside section 6's round count and its escalation.
239
+ Approver threads are outside section 6's round count and its escalation.
239
240
 
240
241
  ## 1. Collect
241
242
 
@@ -392,8 +393,9 @@ Never accept or reject from reading alone. Each finding gets evidence:
392
393
  there, say so rather than reasoning from memory.
393
394
  - **A claim about the codebase** gets a grep or a file read at the cited line.
394
395
  - **A finding that would reverse a choice** also gets the recorded reason:
395
- read the commit message, the pull request's body, and the issue's Decisions
396
- before accepting it. A session without the build context has only these. If
396
+ read the commit message, the pull request's body, and the Decisions of
397
+ each ticket `npx --no-install factory pr closes PR` prints, with
398
+ `npx --no-install factory ticket view N`, before accepting it. A session without the build context has only these. If
397
399
  the finding conflicts with a recorded decision and the evidence does not
398
400
  settle it, reply with both and leave the thread open for the owner.
399
401
 
@@ -425,7 +427,7 @@ the reasoning survives, and the user reads these instead of the transcript.
425
427
 
426
428
  **Every comment this skill posts, a thread reply or a conversation comment,
427
429
  contains `<!-- agent -->` on its own line.** That marker is how the next
428
- run tells its own words from the owner's (section 0a). Put it at the end of
430
+ run tells its own words from an approver's (section 0a). Put it at the end of
429
431
  the body; an automatic footer may follow it.
430
432
 
431
433
  ```bash
@@ -446,9 +448,9 @@ npx --no-install factory pr resolve N COMMENT_ID
446
448
  ```
447
449
 
448
450
  Resolve accepted and rejected threads alike, with one exception: **an
449
- owner thread is resolved only when you fixed it, the owner overruled your
450
- pushback, or the owner accepted it** (section 0a). A pushback on an owner
451
- thread stays open for the owner. GitHub has no "ignored" state:
451
+ approver thread is resolved only when you fixed it, or an approver
452
+ overruled or accepted your pushback** (section 0a). A pushback on an
453
+ approver thread stays open for an approver. GitHub has no "ignored" state:
452
454
  a rejection is a reply carrying the evidence, followed by the same resolve.
453
455
  Resolving without replying destroys the reasoning, which is the only reason
454
456
  the user can audit the decision later.
@@ -506,9 +508,9 @@ other push: pull with
506
508
 
507
509
  ## 6. Two rounds, then escalate
508
510
 
509
- Owner threads (section 0a) are outside this count, and this section's
510
- escalation does not apply to them: an open owner thread is already the
511
- owner's to decide. A run started by the owner's review has no memory of
511
+ Approver threads (section 0a) are outside this count, and this section's
512
+ escalation does not apply to them: an open approver thread is already an
513
+ approver's to decide. A run started by the owner's review has no memory of
512
514
  earlier sessions, so it counts rounds from the `claude-review sha=`
513
515
  summaries of the commits it pushed itself.
514
516
 
@@ -550,7 +552,7 @@ again. Add whether the tests are good enough to make a swap verifiable.
550
552
  First, note what this round of work cost, on the pull request:
551
553
 
552
554
  ```bash
553
- npx --no-install factory ticket cost PR
555
+ npx --no-install factory pr cost PR
554
556
  ```
555
557
 
556
558
  It posts what the session spent at API list prices since its last note, or