codeassembly-guidance 0.0.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (204) hide show
  1. package/.meta/changelog.json +563 -0
  2. package/CHANGELOG.md +134 -0
  3. package/LICENSE +7 -0
  4. package/README.md +165 -1
  5. package/content/_partials/README.md +192 -0
  6. package/content/_partials/code-descriptions.md +4 -0
  7. package/content/_partials/code-style.md +7 -0
  8. package/content/_partials/comment-discipline.md +89 -0
  9. package/content/_partials/concision.md +3 -0
  10. package/content/_partials/diff-audit-checklist.md +9 -0
  11. package/content/_partials/file-access.md +4 -0
  12. package/content/_partials/live-repo-writes.md +13 -0
  13. package/content/_partials/plain-speech-calibration.md +66 -0
  14. package/content/_partials/plain-speech.md +13 -0
  15. package/content/_partials/prose-line-breaks.md +3 -0
  16. package/content/_partials/record-marker.md +1 -0
  17. package/content/_partials/reduced-object-relative.md +28 -0
  18. package/content/_partials/shell-commands.md +3 -0
  19. package/content/_partials/target-file-set-resolution.md +22 -0
  20. package/content/_partials/technical-recommendations.md +5 -0
  21. package/content/_partials/test-structure-audit-checklist.md +7 -0
  22. package/content/_partials/ticket-assessment-baseline.md +12 -0
  23. package/content/_partials/ticket-assessment.md +202 -0
  24. package/content/_partials/work-type-choice.md +13 -0
  25. package/content/codeassembly-content.yaml +49 -0
  26. package/content/collections/all.md +11 -0
  27. package/content/collections/atlassian.md +16 -0
  28. package/content/collections/recommended.md +34 -0
  29. package/content/collections/triage.md +77 -0
  30. package/content/collections/williamthorsen.md +25 -0
  31. package/content/guidance/README.md +22 -0
  32. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  33. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  34. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  35. package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
  36. package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
  37. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  38. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  39. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  40. package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
  41. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  42. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  43. package/content/guidance/rulebooks/shell-conventions.md +279 -0
  44. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  45. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
  46. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  47. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  48. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  49. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  50. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  51. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  52. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  53. package/content/guidance/shared/AGENTS.md +43 -0
  54. package/content/scripts/README.md +41 -0
  55. package/content/scripts/describe-change.mjs +165 -0
  56. package/content/scripts/get-ticket-id.sh +131 -0
  57. package/content/scripts/manage-jira-ticket.mjs +209 -0
  58. package/content/scripts/resolve-frontmatter.sh +540 -0
  59. package/content/scripts/resolve-review-run.mjs +12 -0
  60. package/content/scripts/select-lede-exemplars.mjs +208 -0
  61. package/content/skills/_data/action-items.md +83 -0
  62. package/content/skills/_data/artifact-conventions.md +969 -0
  63. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  64. package/content/skills/_data/branch-format.md +34 -0
  65. package/content/skills/_data/change-record.md +163 -0
  66. package/content/skills/_data/complexity-classification.md +58 -0
  67. package/content/skills/_data/concision.md +23 -0
  68. package/content/skills/_data/deployed-file-provenance.md +46 -0
  69. package/content/skills/_data/design-priorities.md +76 -0
  70. package/content/skills/_data/gh-body-file.md +30 -0
  71. package/content/skills/_data/git-commands.md +39 -0
  72. package/content/skills/_data/naming-conventions.md +50 -0
  73. package/content/skills/_data/pr-resolution.md +25 -0
  74. package/content/skills/_data/pr-source-resolution.md +36 -0
  75. package/content/skills/_data/recommendation-gradient.md +90 -0
  76. package/content/skills/_data/scope-and-deferral.md +83 -0
  77. package/content/skills/_data/spike-conventions.md +89 -0
  78. package/content/skills/_data/ticket-evaluation.md +13 -0
  79. package/content/skills/_data/ticket-id-extraction.md +43 -0
  80. package/content/skills/_data/ticket-source-resolution.md +147 -0
  81. package/content/skills/_data/title-templates.md +624 -0
  82. package/content/skills/_data/title-voice.md +17 -0
  83. package/content/skills/_data/work-types.json +168 -0
  84. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  85. package/content/skills/_partials/action-items.md +22 -0
  86. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  87. package/content/skills/_partials/commit-title-rendering.md +14 -0
  88. package/content/skills/_partials/gh-body-file.md +22 -0
  89. package/content/skills/_partials/nested-list-indent.md +9 -0
  90. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  91. package/content/skills/_partials/next-steps-after-review.md +350 -0
  92. package/content/skills/_partials/option-format.md +84 -0
  93. package/content/skills/_partials/plan-template.md +97 -0
  94. package/content/skills/_partials/split-launch-prompts.md +5 -0
  95. package/content/skills/_partials/split-ticket-compose.md +5 -0
  96. package/content/skills/_partials/split-ticket-create.md +3 -0
  97. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  98. package/content/skills/_partials/ticket-concision.md +18 -0
  99. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  100. package/content/skills/_partials/ticket-placement.md +14 -0
  101. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  102. package/content/skills/_partials/ticket-skeleton.md +13 -0
  103. package/content/skills/add-change-record/SKILL.md +136 -0
  104. package/content/skills/add-test-ids/SKILL.md +51 -0
  105. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  106. package/content/skills/anti-patterns/SKILL.md +57 -0
  107. package/content/skills/assess-ticket/SKILL.md +46 -0
  108. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  109. package/content/skills/brainstorming/SKILL.md +107 -0
  110. package/content/skills/capture-event/SKILL.md +108 -0
  111. package/content/skills/capture-event/capture-event.mjs +216 -0
  112. package/content/skills/capture-feedback/SKILL.md +71 -0
  113. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  114. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  115. package/content/skills/classify-complexity/SKILL.md +92 -0
  116. package/content/skills/collaborate/SKILL.md +86 -0
  117. package/content/skills/condense-branch/SKILL.md +83 -0
  118. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  119. package/content/skills/create-commit/SKILL.md +65 -0
  120. package/content/skills/create-devlog/SKILL.md +108 -0
  121. package/content/skills/create-gh-pr/SKILL.md +106 -0
  122. package/content/skills/create-pr/SKILL.md +150 -0
  123. package/content/skills/create-ticket/SKILL.md +350 -0
  124. package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
  125. package/content/skills/design-and-plan/SKILL.md +194 -0
  126. package/content/skills/development-workflows/SKILL.md +41 -0
  127. package/content/skills/get-ticket-id/SKILL.md +67 -0
  128. package/content/skills/groom-backlog/SKILL.md +245 -0
  129. package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
  130. package/content/skills/implement-plan/SKILL.md +164 -0
  131. package/content/skills/index-prototypes/SKILL.md +145 -0
  132. package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
  133. package/content/skills/kb-add/SKILL.md +156 -0
  134. package/content/skills/kb-add/kb-add.mjs +216 -0
  135. package/content/skills/kb-curate/SKILL.md +117 -0
  136. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  137. package/content/skills/kb-edit/SKILL.md +128 -0
  138. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  139. package/content/skills/kb-retrieve/SKILL.md +100 -0
  140. package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
  141. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  142. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
  143. package/content/skills/kb-update-events/SKILL.md +77 -0
  144. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  145. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  146. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  147. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  148. package/content/skills/merge-pr/SKILL.md +368 -0
  149. package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
  150. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  151. package/content/skills/people-report/SKILL.md +208 -0
  152. package/content/skills/plan/SKILL.md +87 -0
  153. package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
  154. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  155. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
  156. package/content/skills/refine-plan/SKILL.md +259 -0
  157. package/content/skills/respond-to-review/SKILL.md +292 -0
  158. package/content/skills/review-bb-pr/SKILL.md +161 -0
  159. package/content/skills/review-branch/SKILL.md +301 -0
  160. package/content/skills/review-criteria/SKILL.md +108 -0
  161. package/content/skills/review-gh-pr/SKILL.md +155 -0
  162. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  163. package/content/skills/review-permissions/SKILL.md +39 -0
  164. package/content/skills/review-pr/SKILL.md +123 -0
  165. package/content/skills/revise-comments/SKILL.md +115 -0
  166. package/content/skills/revise-prose/SKILL.md +197 -0
  167. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  168. package/content/skills/save-artifact/SKILL.md +69 -0
  169. package/content/skills/save-plan/SKILL.md +55 -0
  170. package/content/skills/software-engineering/SKILL.md +74 -0
  171. package/content/skills/streamline-guidance/SKILL.md +174 -0
  172. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  173. package/content/skills/summarize-change/SKILL.md +308 -0
  174. package/content/skills/summarize-chat/SKILL.md +100 -0
  175. package/content/skills/systematic-debugging/SKILL.md +308 -0
  176. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  177. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  178. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  179. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  180. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  181. package/content/skills/systematic-debugging/test-academic.md +16 -0
  182. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  183. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  184. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  185. package/content/skills/testing-conventions/SKILL.md +168 -0
  186. package/content/skills/testing-conventions/mistakes.md +1 -0
  187. package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
  188. package/content/skills/update-jira-ticket/SKILL.md +245 -0
  189. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  190. package/content/skills/update-project-guidance/SKILL.md +300 -0
  191. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  192. package/content/skills/wrap-up/SKILL.md +431 -0
  193. package/content/subagents/_data/claude.yaml +19 -0
  194. package/content/subagents/_data/rovo.yaml +31 -0
  195. package/content/subagents/canary.md +11 -0
  196. package/content/subagents/entry-drafter.md +187 -0
  197. package/content/subagents/handoff-reviewer.md +75 -0
  198. package/content/subagents/plan-reviewer.md +184 -0
  199. package/content/subagents/plan-reviser.md +88 -0
  200. package/content/subagents/prose-reviser.md +130 -0
  201. package/content/subagents/ticket-assessor.md +139 -0
  202. package/package.json +70 -2
  203. package/schemas/preferences.v1.json +294 -0
  204. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,197 @@
1
+ ---
2
+ name: revise-prose
3
+ description: Sweep a repository's prose against the writing rule set, repair it through dispatched subagents, and record what was swept
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Revise prose
8
+
9
+ Sweep a repository's prose against the rules below, repair every clear site, and record what the repository has now been swept for. A bundled helper does the mechanical half: It resolves which files may be swept, extracts their prose, reports over-inclusive candidates, and packs the files into batches. You do the dispatching half: one `{subagent:prose-reviser}` subagent per batch, one commit per batch, and one closing pass over what the subagents would not decide alone.
10
+
11
+ Apply is the default. `--dry-run` produces the report alone.
12
+
13
+ **Announce at start:** "Using revise-prose to {report on | revise} prose in {the repository | the given paths}."
14
+
15
+ ## Arguments
16
+
17
+ | Argument | Description | Required |
18
+ | ------------------------ | ------------------------------------------------------------------------------- | -------- |
19
+ | `<path>` | One or more files or directories narrowing the sweep. Repeatable. | No |
20
+ | `--batch-budget <bytes>` | Ceiling on a batch's combined file bytes. Passed to the helper unchanged. | No |
21
+ | `--dry-run` | Report and stop without dispatching a subagent, editing, or writing the record. | No |
22
+ | `--rule <id>` | One rule that this document declares, narrowing the sweep. Repeatable. | No |
23
+
24
+ Without a path, the sweep covers the whole repository. That is this skill's default, because removing every violation from a repository requires a full sweep. It is how this skill differs from `{skill:revise-comments}`, whose default is the current branch's diff.
25
+
26
+ `--rule` takes a rule's id as step 1 derives it, not a unit's name: `--rule plain-speech` sweeps the rule `plain-speech` without the rules that its calibration declares.
27
+
28
+ ## Ordering with `revise-comments`
29
+
30
+ `{skill:revise-comments}` decides whether a comment exists and what it may say. This skill decides how a span of prose reads, and it never adds, deletes, or shortens a comment. If both are wanted on the same files, run `{skill:revise-comments}` first: It may delete the very comment that this sweep would otherwise polish.
31
+
32
+ ## Process
33
+
34
+ ### 1. Read the units and the rules from this document
35
+
36
+ Both come from this document, never from a list kept elsewhere. Because a rule document declares each rule by a marker beside it rather than by its heading, a heading change cannot silently drop a rule, and a project bound to a different rulebook is swept for the rules that it declares.
37
+
38
+ - **The `plain-speech` unit** is at the version that the `<!-- unit-version: plain-speech <version> -->` marker below names. It contains the rule `plain-speech`, whose sweep version is the same, and each rule that a `<!-- rule: <id> <version> -->` marker in its calibration below declares, at that marker's sweep version.
39
+ - **Each `<!-- rulebook:<slug> -->` block** in the comment-preferences and writing-preferences fills at the end of this document is a unit, at the version that its `<!-- rulebook-version: <version> -->` line names. A block that does not specify a version is not a unit: Do not name its rules to the helper, sweep it without recording anything for it, and name that slug in the closing summary.
40
+ - **Each `<!-- rule: <id> <version> -->` marker** in a unit's body declares a rule at that sweep version, whether or not the helper has a detector for it. The rule's unit is the block containing the marker.
41
+ - **A marker that reads `<!-- rule: <id> -->`** declares a rule without a sweep version. It is swept, but nothing records it: Name it to the helper without a version, and name it in the closing summary.
42
+ - **A rule heading without a marker beneath it** does not declare an id or a sweep version. Its id is the heading's text lowercased, with backticks dropped, each run of characters other than letters and digits replaced by one hyphen, and hyphens trimmed from both ends; its unit is the block containing the heading. Do not name it to the helper, and name it in the closing summary.
43
+
44
+ **The unrecorded rules** are the rules that nothing records: each marker without a sweep version, each heading without a marker, and each rule in a block that is not a unit, whose id is its marker's id or, without a marker, its heading's id derived as above. Keep their ids for step 4, which dispatches them with every batch.
45
+
46
+ The record keys coverage and rejections on each rule's sweep version. A unit's version is passed only to convert a record written before rules had versions.
47
+
48
+ If the fills are empty, nothing is bound here: The run sweeps `plain-speech` alone.
49
+
50
+ **Narrow to the named rules.** Without `--rule`, keep every rule that this step declares. With it, first check each named id against the ids that this step declares, the ids derived from headings included; if one is not among them, stop the run before the helper runs, and name that id. Then keep only the named rules, versioned and unrecorded alike, and keep every unit. Every later step works from the rules that this step kept, and the closing summary does not name any other rule.
51
+
52
+ ### 2. Run the sweep
53
+
54
+ ```bash
55
+ node {harness_home_dir}/skills/revise-prose/revise-prose.mjs detect {paths} \
56
+ --unit plain-speech={version} \
57
+ --rule plain-speech@{version}=plain-speech \
58
+ --rule {calibration-rule-id}@{rule-version}=plain-speech \
59
+ --unit {slug}={version} \
60
+ --rule {rule-id}@{rule-version}={slug} \
61
+ --rule {unversioned-rule-id}={slug}
62
+ ```
63
+
64
+ Pass one `--unit` per unit from step 1, and one `--rule` per rule that step 1 kept: `--rule plain-speech@{version}=plain-speech` for `plain-speech`, `--rule {id}@{rule-version}={unit}` for a rule whose marker declares a version, and `--rule {id}={unit}` for a rule whose marker declares none. Pass nothing for a rule that does not have a marker or whose block is not a unit, as step 1 directs. Add `--batch-budget {bytes}` if the invocation included one. Omit the paths for a whole-repository sweep.
65
+
66
+ The helper prints one JSON object to stdout. On success it contains `ok: true`, the `root` that it swept, a `candidates` array, a `rejections` array containing the sites already adjudicated by an earlier sweep, a `batches` array in which each batch lists as `unswept` the versioned rules that its files still need, a `rules` object listing the named rules that it `detected` and those for which it does not have a detector as `undetected`, and a `summary`. On failure it contains `ok: false` with `invalid-args`, `invalid-record`, or `not-a-repository`, the last because the sweep reads what git tracks and has nothing to read outside a working tree. Report a failure and stop.
67
+
68
+ Read `summary` before anything else. `filesSkipped` counts the files that the sweep excluded, keyed by the reason for each: `generated` and `machine-generated` for output whose edit belongs to its source, `vendored` for a verbatim extract whose edit belongs to the project from which it was extracted, `unreadable` for a file whose prose cannot be read, and `ineligible` for one not read by any extractor. `batchesSkipped` counts the batches that the record already covers; `stale` counts the candidates whose recorded rejection was taken at an older version of its rule.
69
+
70
+ `candidates` and `rejections` contain only the sites in the reported batches' files, under a rule that the batch lists as `unswept` or, for a candidate, under a rule named without a version.
71
+
72
+ An empty `batches` array ends the run: Report the summary in one line and stop. The repository is already swept at every versioned rule's current version.
73
+
74
+ **Under `--dry-run`, the run ends here.** Emit the summary and one candidate table per file, per [Summary format](#summary-format), and stop. Do not dispatch a subagent, do not write a record, and edit nothing. A dry run takes one helper run, whereas a report-then-apply pair would run the sweep twice.
75
+
76
+ **An apply run needs a clean tree.** If `git status --porcelain` reports anything, stop and report it. Because step 4's gate reads `git diff --name-only` as the wave's own work, an edit already in the tree either trips that gate or, if it is inside a batch's file list, is committed with that batch under the sweep's message. A dry run ends before this check and edits nothing; therefore, this stop holds only for an apply run.
77
+
78
+ ### 3. Pilot the first batch
79
+
80
+ Run the pilot if `.agents/revise-prose.yaml` is absent, or if it names none of this run's versioned rules under `rules:` and none of its units under `units:`. A rerun skips this step and goes to step 4.
81
+
82
+ Dispatch batch 0 alone, per step 4's dispatch shape, and run step 4's checks over it as a wave of one. Accumulate its `rejected` and `questionable` entries for step 5, as step 4 directs for every later wave, so that the pilot's questionables appear in the closing table. Then show the user its report and `git diff --stat`, and ask for a go-ahead before committing that batch and before dispatching anything else.
83
+
84
+ On a no-go, ask the user before reverting, then revert that batch's files and stop. A miscalibrated subagent is worth catching once per repository, which is the whole reason the first batch runs alone.
85
+
86
+ ### 4. Dispatch the remaining batches in waves
87
+
88
+ Send up to four `{tool:Task}` calls with `subagent_type: prose-reviser` in one message. A harness that returns each before the next is the series case; do not attempt to detect which one you are on.
89
+
90
+ Before each dispatch, write two files under `{scratch}/revise-prose/`: that batch's candidate objects, exactly as the helper reported them and `stale` flags included, to `batch-{index}.json`, and the run's `rejections` entries whose `file` the batch covers, to `rejections-{index}.json`. Write the second even if it does not contain any entry, so that every dispatch names the same keys. `{scratch}` is a scratch directory created once for the run with `mktemp -d "${TMPDIR:-/tmp}/revise-prose.XXXXXX"`, written out as an absolute path in each place below and in each dispatch block, since these writes and the subagent's reads all go through a file tool that does not expand shell syntax.
91
+
92
+ A batch's `rules` value lists its `unswept` rules and step 1's unrecorded rules, sorted, each named once. A rule without a sweep version is therefore swept in every batch that the helper reports, and it never causes a batch to be dispatched. Dispatch each batch with this block:
93
+
94
+ ```dispatch
95
+ root: {root}
96
+ files: {the batch's files, comma-separated}
97
+ candidates: {scratch}/revise-prose/batch-{index}.json
98
+ rejections: {scratch}/revise-prose/rejections-{index}.json
99
+ rules: {rule-id}, {rule-id}
100
+ ```
101
+
102
+ **The block contains scalars only, and only these keys.** Do not compose prose into it: The subagent has the rule set and reads the files itself, and a sentence written here would bias its judgment toward yours. A content test fails the build on a line that is not a `key: value` scalar and on a key outside this set.
103
+
104
+ **On each return, parse the report.** It is one fenced JSON block containing `applied`, `rejected`, and `questionable`. If the returned value does not contain such a block, or the block is truncated, redispatch the batch rather than editing from it.
105
+
106
+ **Once the whole wave has returned:**
107
+
108
+ 1. **Check the diff against the wave.** Run `git diff --name-only`. Every subagent in the wave has already made its edits by now; therefore, the gate checks against the union of the batches' file lists rather than any one batch's. If the diff names a file outside that union, stop the run and report which file changed; commit nothing.
109
+ 2. **Check each report against its own batch.** If a batch's `applied` entries name a file outside that batch's `files` list, stop the run and report which batch named it; commit nothing. The union check above cannot detect this, because that file is in another batch of the same wave.
110
+ 3. **Commit each batch in index order.** Stage that batch's files alone and commit them per `{skill:create-commit}`, with the type and the scope that `create-commit` derives from those files.
111
+ 4. **Accumulate** the wave's `rejected` and `questionable` entries for step 5.
112
+
113
+ ### 5. Close the run
114
+
115
+ 1. **Adjudicate the questionables.** Decide each entry yourself before asking the user about any of them. Read the context that decides it: the code around the site; the tests and docs that quote the phrase, found by searching the repository for it with {tool:Grep}; other batches' `applied` entries that repair the same wording; and the docs that the site links to. Then accept or reject the repair, and record the reason. Pass a site to the user only if deciding it requires information that the repository does not contain, or if the repair is in the gated class, such as a change to printed output that a consumer outside the repository may parse. Once every other entry is decided, present the passed sites together in the residue table per [Summary format](#summary-format), each with your recommendation and its reason.
116
+ 2. **Apply the accepted repairs**, yours and the user's, with the {tool:Edit} tool, phrase to phrase from each entry's `phrase` and `repair`. If a test expectation or a doc quotes the repaired text, update each quoting file to the repaired text as part of the same repair. Stop at the first edit that does not match, so that the user sees what diverged.
117
+ 3. **Compose the fold** and pipe it to the helper's `record` command, which is the record's only write path:
118
+
119
+ ```bash
120
+ cat <<'EOF' | node {harness_home_dir}/skills/revise-prose/revise-prose.mjs record
121
+ {"sweptAt":"{today}","roots":["{root}"],"units":{"{name}":"{version}"},"rules":{"{rule-id}":{"unit":"{name}","version":"{rule-version}"}},"rejections":[]}
122
+ EOF
123
+ ```
124
+
125
+ `sweptAt` is today's ISO calendar date. `roots` lists the invocation's narrowing paths, or `["."]` for a whole-repository sweep. `units` names every unit from step 1 at its current version. `rules` names every rule that step 2 passed with a version, `plain-speech` included, with its unit and its sweep version; the helper records for each whether it holds the rule's detector.
126
+
127
+ `rejections` contains every subagent rejection plus every questionable rejected in step 5.1, by you or by the user, each containing `rule`, `file`, `phrase` as the text reads after this run's edits, and `ground`. A rejected questionable's `ground` is the reason recorded for its rejection. Leave out a rejection under a rule that `rules` does not name, which is a rule without a sweep version: Nothing records such a rule, and the helper refuses the fold.
128
+
129
+ **Fold every rejection under a rule that `rules` names, whether or not the helper has its detector.** Because a rejection resolves to a site by its rule, its file, and its phrase, a rejection under a rule for which the helper does not have a detector is recorded and re-suppressed like any other. Report the phrase as it reads in the source and long enough to locate the site by eye: The helper masks inline code spans and matches by containment, and therefore a span wider than the one reported by the detector still resolves to it. On the next sweep, step 4 writes the recorded sites to the rejections file of each batch that covers them.
130
+
131
+ 4. **Commit the closing repairs, the quoting files that they updated, and the record together**, per `{skill:create-commit}`.
132
+ 5. **Run the project's quality gate** as `{skill:development-workflows}` resolves it. A test that asserts on a string repaired by a subagent fails there; repair the test expectation and commit that separately.
133
+ 6. **Emit the summary** per [Summary format](#summary-format).
134
+
135
+ <!-- include: ../../_partials/plain-speech.md / -->
136
+
137
+ <!-- include: ../../_partials/plain-speech-calibration.md / -->
138
+
139
+ <!-- include: ../../_partials/target-file-set-resolution.md / -->
140
+
141
+ ## Summary format
142
+
143
+ One table per batch, then the closing lines:
144
+
145
+ ```
146
+ revise-prose summary
147
+
148
+ | Batch | Files | Applied | Rejected | Questionable |
149
+ | ----- | ----- | ------- | -------- | ------------ |
150
+ | 0 | 12 | 31 | 4 | 2 |
151
+ | 1 | 9 | 18 | 1 | 0 |
152
+
153
+ Recorded in `.agents/revise-prose.yaml`: capitalization-after-colon 1, em-dash 1, negative-quantifier 2, plain-speech 9, sentence-case 2.
154
+ Not recorded: other-writing-guidance, prefer-active-voice.
155
+ No detector: capitalization-after-colon, plain-speech, sentence-case.
156
+ 5 files excluded: 1 generated, 1 machine-generated, 3 ineligible.
157
+ ```
158
+
159
+ The recorded line names each rule from the fold's `rules` at its sweep version. Give the line naming what was not recorded only if step 1 kept an unrecorded rule, naming each kept rule without a sweep version and the slug of each block that is not a unit and from which step 1 kept a rule.
160
+
161
+ Give the excluded-files clause only if `filesSkipped` reports a non-zero count, naming each reason and its count, so that a file that the sweep never opened is not mistaken for a clean result. A whole-repository sweep reports a large `ineligible` count, because every image, lockfile, and data file in the repository is one; a narrowed sweep reports the files that it was given and could not read.
162
+
163
+ Give the line naming the rules without a detector only if the helper's `rules.undetected` lists any, naming each. If a marker misspells a detector rule's id, the misspelled id appears only on this line: The subagent still sweeps the rule wherever a batch applies it, and the helper does not run a detector for it.
164
+
165
+ Present every questionable in the adjudicated table, grouped by ground, before the per-batch tables. A site passed to the user has the verdict that the user's answer gave it.
166
+
167
+ ```
168
+ | # | Ground | File | Line | Phrase | Repair | Verdict | Reason |
169
+ | - | ----------------- | ------------- | ---- | ------------------------------- | ----------------------------- | ------- | ---------------------------------------------------- |
170
+ | 1 | plausible exhibit | docs/rules.md | 61 | the source it names | the source that it names | reject | the list above it introduces each line as an exhibit |
171
+ | 2 | changes meaning | src/parse.ts | 22 | the findings arrive as warnings | the function reports warnings | apply | `parse` emits the warnings, per its tests |
172
+ ```
173
+
174
+ Step 5.1 presents the sites passed to the user in the residue table, which has the same columns with a recommendation, `apply` or `reject`, in place of the verdict:
175
+
176
+ ```
177
+ | # | Ground | File | Line | Phrase | Repair | Recommendation | Reason |
178
+ | - | ------------- | ---------- | ---- | -------------------- | ----------------------------- | -------------- | ---------------------------------------------- |
179
+ | 1 | asserted text | src/cli.ts | 40 | no config file found | the config file isn't present | reject | release notes document the message for scripts |
180
+ ```
181
+
182
+ Ask for the numbers of the rows to decide against their recommendation; every unnamed row takes its recommendation.
183
+
184
+ Because there is nothing yet to adjudicate under `--dry-run`, the run reports the candidates instead: one table per file, ordered as the helper reported them, with the rule, the line, and the phrase. If the total is large, the user reads `byFile` and `byShape` to narrow the next run.
185
+
186
+ ```
187
+ | Rule | Line | Phrase |
188
+ | ----------------------- | ---- | ----------------------------------- |
189
+ | reduced-object-relative | 14 | the ticket the branch name encodes |
190
+ | em-dash | 22 | Findings arrive as warnings -- ... |
191
+ ```
192
+
193
+ <!-- include: ../_partials/action-items.md / -->
194
+
195
+ <!-- guidance-hook: comment-preferences -->
196
+
197
+ <!-- guidance-hook: writing-preferences -->