codeassembly-guidance 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. package/.meta/changelog.json +984 -0
  2. package/CHANGELOG.md +240 -0
  3. package/README.md +45 -99
  4. package/bin/codeassembly-validate-preferences.js +18 -0
  5. package/content/_partials/README.md +21 -5
  6. package/content/_partials/comment-discipline.md +1 -1
  7. package/content/_partials/diff-audit-checklist.md +1 -0
  8. package/content/_partials/kb-standard-tags.md +7 -0
  9. package/content/_partials/plain-speech-calibration.md +4 -0
  10. package/content/_partials/technical-recommendations.md +1 -0
  11. package/content/codeassembly-content.yaml +17 -1
  12. package/content/collections/all.md +2 -2
  13. package/content/collections/atlassian.md +2 -1
  14. package/content/collections/recommended.md +9 -2
  15. package/content/collections/triage.md +3 -67
  16. package/content/collections/williamthorsen.md +2 -1
  17. package/content/guidance/README.md +1 -1
  18. package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
  19. package/content/guidance/rulebooks/cli-conventions.md +206 -0
  20. package/content/guidance/rulebooks/codeassembly-content-specification.md +50 -10
  21. package/content/guidance/rulebooks/commit-conventions.md +5 -4
  22. package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
  23. package/content/guidance/rulebooks/readme-conventions.md +3 -3
  24. package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
  25. package/content/guidance/rulebooks/shell-conventions.md +17 -23
  26. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  27. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +18 -12
  28. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
  29. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
  30. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
  31. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
  32. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
  33. package/content/guidance/shared/AGENTS.md +39 -4
  34. package/content/scripts/README.md +5 -2
  35. package/content/scripts/check-branch-currency.mjs +11 -0
  36. package/content/scripts/check-prose.mjs +171 -0
  37. package/content/scripts/describe-change.mjs +98 -98
  38. package/content/scripts/manage-jira-ticket.mjs +99 -94
  39. package/content/scripts/resolve-frontmatter.sh +1 -1
  40. package/content/scripts/resolve-review-run.mjs +9 -9
  41. package/content/scripts/select-lede-exemplars.mjs +87 -87
  42. package/content/scripts/validate-preferences.mjs +146 -0
  43. package/content/skills/_data/action-items.md +2 -0
  44. package/content/skills/_data/artifact-conventions.md +64 -16
  45. package/content/skills/_data/branch-currency.md +36 -0
  46. package/content/skills/_data/change-record.md +2 -2
  47. package/content/skills/_data/complexity-classification.md +1 -1
  48. package/content/skills/_data/design-priorities.md +15 -4
  49. package/content/skills/_data/project-stage.md +32 -0
  50. package/content/skills/_data/recommendation-gradient.md +9 -7
  51. package/content/skills/_data/scope-and-deferral.md +1 -1
  52. package/content/skills/_data/spike-conventions.md +21 -6
  53. package/content/skills/_data/ticket-evaluation.md +2 -2
  54. package/content/skills/_data/ticket-source-resolution.md +36 -3
  55. package/content/skills/_data/title-templates.md +22 -12
  56. package/content/skills/_partials/action-items.md +2 -2
  57. package/content/skills/_partials/apply-guidance-edits.md +5 -0
  58. package/content/skills/_partials/commit-title-rendering.md +1 -1
  59. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  60. package/content/skills/_partials/next-steps-after-plan.md +11 -11
  61. package/content/skills/_partials/option-format.md +18 -17
  62. package/content/skills/_partials/plan-template.md +7 -5
  63. package/content/skills/_partials/split-ticket-compose.md +1 -1
  64. package/content/skills/_partials/split-ticket-create.md +1 -1
  65. package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
  66. package/content/skills/_partials/ticket-composition.md +40 -0
  67. package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
  68. package/content/skills/_partials/ticket-skeleton.md +15 -1
  69. package/content/skills/add-change-record/SKILL.md +2 -2
  70. package/content/skills/align-ticket-with-implementation/SKILL.md +3 -7
  71. package/content/skills/anti-patterns/SKILL.md +1 -1
  72. package/content/skills/assess-code-health/SKILL.md +127 -0
  73. package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
  74. package/content/skills/assess-usability/SKILL.md +98 -0
  75. package/content/skills/capture-event/SKILL.md +4 -2
  76. package/content/skills/capture-event/capture-event.mjs +89 -89
  77. package/content/skills/capture-feedback/SKILL.md +1 -1
  78. package/content/skills/capture-lede-decision/SKILL.md +4 -4
  79. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
  80. package/content/skills/collaborate/SKILL.md +3 -3
  81. package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
  82. package/content/skills/create-commit/SKILL.md +1 -1
  83. package/content/skills/create-gh-pr/SKILL.md +28 -10
  84. package/content/skills/create-pr/SKILL.md +7 -6
  85. package/content/skills/create-ticket/SKILL.md +64 -23
  86. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  87. package/content/skills/derive-session-context/derive-session-context.mjs +83 -82
  88. package/content/skills/design-and-plan/SKILL.md +17 -18
  89. package/content/skills/groom-backlog/SKILL.md +8 -6
  90. package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
  91. package/content/skills/implement-plan/SKILL.md +27 -23
  92. package/content/skills/index-prototypes/SKILL.md +86 -31
  93. package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
  94. package/content/skills/kb-add/SKILL.md +4 -1
  95. package/content/skills/kb-add/kb-add.mjs +128 -128
  96. package/content/skills/kb-curate/SKILL.md +9 -7
  97. package/content/skills/kb-curate/kb-curate.mjs +103 -103
  98. package/content/skills/kb-edit/SKILL.md +5 -3
  99. package/content/skills/kb-edit/kb-edit.mjs +94 -94
  100. package/content/skills/kb-retrieve/kb-retrieve.mjs +86 -85
  101. package/content/skills/kb-retrieve-events/SKILL.md +20 -11
  102. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +86 -85
  103. package/content/skills/kb-update-events/SKILL.md +10 -7
  104. package/content/skills/kb-update-events/kb-update-events.mjs +110 -109
  105. package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
  106. package/content/skills/merge-bb-pr/SKILL.md +1 -1
  107. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
  108. package/content/skills/merge-pr/SKILL.md +11 -11
  109. package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
  110. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
  111. package/content/skills/plan/SKILL.md +2 -2
  112. package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
  113. package/content/skills/pull-from-backlog/SKILL.md +3 -3
  114. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
  115. package/content/skills/refine-guidance/SKILL.md +97 -0
  116. package/content/skills/refine-plan/SKILL.md +7 -3
  117. package/content/skills/refine-prototype/SKILL.md +113 -0
  118. package/content/skills/respond-to-review/SKILL.md +1 -1
  119. package/content/skills/review-bb-pr/SKILL.md +1 -1
  120. package/content/skills/review-branch/SKILL.md +354 -3
  121. package/content/skills/review-criteria/SKILL.md +36 -3
  122. package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
  123. package/content/skills/revise-comments/SKILL.md +38 -5
  124. package/content/skills/revise-prose/SKILL.md +1 -1
  125. package/content/skills/revise-prose/revise-prose.mjs +119 -119
  126. package/content/skills/save-artifact/SKILL.md +3 -1
  127. package/content/skills/streamline-guidance/SKILL.md +11 -16
  128. package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
  129. package/content/skills/summarize-change/SKILL.md +23 -14
  130. package/content/skills/testing-conventions/SKILL.md +81 -8
  131. package/content/skills/triage-feedback/SKILL.md +150 -0
  132. package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
  133. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  134. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +73 -0
  135. package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
  136. package/content/skills/update-jira-ticket/SKILL.md +20 -8
  137. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
  138. package/content/skills/update-project-guidance/SKILL.md +12 -12
  139. package/content/subagents/_data/claude.yaml +6 -0
  140. package/content/subagents/_data/rovo.yaml +12 -2
  141. package/content/subagents/canary.md +2 -1
  142. package/content/subagents/code-health-assessor.md +98 -0
  143. package/content/subagents/disposition-challenger.md +78 -0
  144. package/content/subagents/entry-drafter.md +14 -10
  145. package/content/subagents/feedback-triage-challenger.md +81 -0
  146. package/content/subagents/handoff-reviewer.md +2 -2
  147. package/content/subagents/lesson-clusterer.md +68 -0
  148. package/content/subagents/plan-reviewer.md +1 -1
  149. package/content/subagents/prose-reviser.md +4 -2
  150. package/content/subagents/ticket-assessor.md +9 -6
  151. package/content/subagents/usability-assessor.md +157 -0
  152. package/package.json +21 -17
  153. package/schemas/preferences.v1.json +50 -7
  154. package/schemas/work-types.v1.json +1 -1
  155. package/content/_partials/code-descriptions.md +0 -4
  156. package/content/_partials/code-style.md +0 -7
  157. package/content/_partials/live-repo-writes.md +0 -13
  158. package/content/_partials/reduced-object-relative.md +0 -28
  159. package/content/_partials/test-structure-audit-checklist.md +0 -7
  160. package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
  161. package/content/skills/_partials/next-steps-after-review.md +0 -350
  162. package/content/skills/_partials/ticket-concision.md +0 -18
  163. package/content/skills/_partials/ticket-placement.md +0 -14
  164. package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
  165. package/content/skills/testing-conventions/mistakes.md +0 -1
@@ -103,6 +103,55 @@ it('processes user data correctly', () => {
103
103
  });
104
104
  ```
105
105
 
106
+ ## DOM environment
107
+
108
+ A test that renders into a DOM runs under happy-dom, which starts and runs faster than jsdom. Under Vitest, set `environment: 'happy-dom'` or open the file with the `// @vitest-environment happy-dom` pragma; under Jest, use the `@happy-dom/jest-environment` package. A test that constructs a window directly uses happy-dom's `Window` rather than `JSDOM`.
109
+
110
+ Use jsdom only for a test that depends on a behavior that happy-dom lacks, and name that behavior in a comment at the opt-in, so that a reader can check whether happy-dom has since gained it.
111
+
112
+ ```typescript
113
+ // ✅ Good: The opt-in names what happy-dom lacks
114
+ // @vitest-environment jsdom
115
+ // happy-dom lacks <the behavior on which this test depends>.
116
+
117
+ // ❌ Avoid: jsdom by habit
118
+ // @vitest-environment jsdom
119
+ ```
120
+
121
+ ## External programs
122
+
123
+ The `testing-conventions` skill states the rule: Code calls an external program through an adapter, and its tests pass a fake. In TypeScript, the adapter is a type, the code takes it as a parameter whose default is the real adapter, and the test passes an object literal. Prefer the parameter to module mocking (`vi.mock`), which leaves the dependency out of the signature and lets the code keep calling the program directly.
124
+
125
+ ```typescript
126
+ // ✅ Good: The code receives git, and the test supplies its answers
127
+ export interface Git {
128
+ listTrackedFiles(root: string): string[];
129
+ }
130
+
131
+ export const realGit: Git = {
132
+ listTrackedFiles: (root) =>
133
+ execFileSync('git', ['ls-files'], { cwd: root, encoding: 'utf8' }).split('\n').filter(Boolean),
134
+ };
135
+
136
+ export function findSkillFiles(root: string, git: Git = realGit): string[] {
137
+ return git.listTrackedFiles(root).filter((path) => path.endsWith('/SKILL.md'));
138
+ }
139
+
140
+ it('returns only the tracked SKILL.md files', () => {
141
+ const git: Git = { listTrackedFiles: () => ['a/SKILL.md', 'a/notes.md'] };
142
+ expect(findSkillFiles('/repo', git)).toStrictEqual(['a/SKILL.md']);
143
+ });
144
+
145
+ // ❌ Avoid: The test builds a real repository to produce the same input
146
+ it('returns only the tracked SKILL.md files', () => {
147
+ execFileSync('git', ['init'], { cwd: scratch });
148
+ // ...write the files, then `git add` and `git commit`...
149
+ expect(findSkillFiles(scratch)).toStrictEqual(['a/SKILL.md']);
150
+ });
151
+ ```
152
+
153
+ Only `realGit` has a test that runs git, and that test checks that `listTrackedFiles` parses the output of `git ls-files`.
154
+
106
155
  ## Console and stream output
107
156
 
108
157
  The `testing-conventions` skill states the rule: A passing test prints nothing beyond the runner's report. These are the TypeScript techniques for applying it. Each helper restores what it replaced when its `using` scope ends.
@@ -120,7 +169,7 @@ it('if a deprecated option is passed, warns once', () => {
120
169
  });
121
170
  ```
122
171
 
123
- Where the project does not depend on these packages, spy on the method with the runner, and restore the spy in `afterEach` or through the runner's `restoreMocks` option:
172
+ When the project does not depend on these packages, spy on the method with the runner, and restore the spy in `afterEach` or through the runner's `restoreMocks` option:
124
173
 
125
174
  ```typescript
126
175
  const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: update-jira-ticket
3
- description: 'Use whenever creating or updating a Jira issue description or comment, whether through acli, a contentFormat-based tool (createJiraIssue taking description, editJiraIssue taking fields.description, both with contentFormat markdown/adf), or an HTML-based tool (create_jira_issue / update_jira_issue, taking description_html / comment_html). Jira stores a Markdown or HTML body with its task-list syntax escaped, so checklists go in as plain bullets on those surfaces and as real task items through acli. The HTML tools additionally need the bundled pre-flight checker to catch INVALID_INPUT triggers (composition rules, named entities, Confluence macros, multi-line <pre>, disallowed elements) before any MCP round-trip; the contentFormat tools take Markdown directly, and acli takes plain text or ADF and parses Markdown as wiki markup.'
3
+ description: 'Use whenever creating or updating a Jira issue description or comment, whether through acli, a contentFormat-based tool (createJiraIssue taking description, editJiraIssue taking fields.description, both with contentFormat markdown/adf), or an HTML-based tool (create_jira_issue / update_jira_issue, taking description_html / comment_html). Jira stores a Markdown or HTML body with its task-list syntax escaped, so checklists go in as plain bullets on those surfaces and as real task items through acli. The HTML tools additionally need the bundled pre-flight checker to catch INVALID_INPUT triggers (composition rules, named entities, Confluence macros, multi-line <pre>, disallowed elements) before any MCP round-trip; the contentFormat tools take Markdown directly, and acli takes plain text or ADF and parses Markdown as wiki markup. Also use to identify the Jira client for reading a ticket, including a client that the machine adds through the `jira-clients` guidance hook.'
4
4
  user-invocable: true
5
5
  ---
6
6
 
@@ -10,7 +10,7 @@ The same constraint applies to creating a Jira issue and to updating one: Whatev
10
10
 
11
11
  ## Checklists
12
12
 
13
- Convert task-list syntax (`- [ ]` / `- [x]`) to plain `-` bullets before submitting Markdown or HTML, on creation and update alike. Neither conversion to ADF maps it to task items: The brackets are escaped, so the line persists as a bullet reading `\[ \] ...`.
13
+ <!-- include: ../_partials/jira-task-list-flattening.md / -->
14
14
 
15
15
  Native checkboxes exist only as ADF `taskList` / `taskItem` nodes, which makes the [ADF path](#adf-path) the one exception. A body submitted as ADF contains real task items and keeps them. That is not a reason to use ADF elsewhere: Because `contentFormat` applies to the whole field rather than a section of it, a checklist never justifies authoring an entire description as ADF on a client that takes Markdown.
16
16
 
@@ -21,16 +21,28 @@ Artefact-sourced content is in scope, and it is the most common source of unconv
21
21
  Match your client to one of these shapes:
22
22
 
23
23
  - **`acli`**: `acli jira workitem create` / `acli jira workitem edit`, whose `--description` and `--description-file` are documented as plain text or ADF. A Markdown body is not merely left unrendered there: It is parsed as Jira wiki markup, so headings become nested ordered list items and punctuation comes back backslash-escaped. → Follow the [ADF path](#adf-path).
24
- - **`contentFormat`-based tool**, e.g. `createJiraIssue` / `editJiraIssue` (Atlassian Rovo): Takes the description together with `contentFormat: "markdown" | "adf"` -- top-level on `createJiraIssue`, under `fields` on `editJiraIssue`. No HTML surface. → Follow the [Markdown path](#markdown-path).
24
+ - **`contentFormat`-based tool**, e.g. `createJiraIssue` / `editJiraIssue` (Atlassian Rovo): Takes the description together with `contentFormat: "markdown" | "adf"` -- top-level on `createJiraIssue`, under `fields` on `editJiraIssue`. Doesn't offer an HTML surface. → Follow the [Markdown path](#markdown-path).
25
25
  - **`description_html`-based tool**: `create_jira_issue` / `update_jira_issue` with `description_html` / `comment_html`. → Follow the [HTML path](#html-path).
26
26
 
27
27
  If more than one is available, prefer the `contentFormat` tool: It takes Markdown directly, whereas `acli` needs ADF. Because the `contentFormat` tool needs a connected Jira server, `acli` is the fallback for a machine without one.
28
28
 
29
+ When the machine adds a client of its own, a section after this one describes it, with the sites to which it connects and where it ranks among these.
30
+
31
+ <!-- guidance-hook: jira-clients -->
32
+
29
33
  ## ADF path
30
34
 
31
35
  Use this branch when the client is `acli`.
32
36
 
33
- 1. **Author Markdown, then convert it to ADF with the helper.** Prefer a local Markdown artefact when one exists; otherwise compose in Markdown and write it to a scratch file. Then run:
37
+ 1. **Check `acli`'s active site before the first `acli` call.** `acli` acts on whichever site it is signed in to. Compare that site with the ticket's host, taken from the ticket URL, or from `ticket_base_url` when the ticket URL is not known:
38
+
39
+ ```bash
40
+ node {harness_home_dir}/scripts/manage-jira-ticket.mjs check-site --target {ticket URL or ticket_base_url}
41
+ ```
42
+
43
+ The helper prints `{"activeSite": ..., "targetSite": ..., "match": ...}` and exits non-zero unless the two match. On a mismatch, use another client from [Identify your client](#identify-your-client); when none remains, report the wrong site by repeating the helper's stderr line, which names both sites and the `acli jira auth switch` command. Never run that command, because the active site is shared by every session on the machine. A non-zero exit without JSON means that `acli` is unavailable. Skip the check when neither URL is known. `manage-jira-ticket.mjs create` runs the same check itself.
44
+
45
+ 2. **Author Markdown, then convert it to ADF with the helper.** Prefer a local Markdown artefact when one exists; otherwise compose in Markdown and write it to a scratch file. Then run:
34
46
 
35
47
  ```bash
36
48
  node {harness_home_dir}/scripts/manage-jira-ticket.mjs convert-body --body-file {absolute Markdown path} --out {absolute ADF path}
@@ -38,10 +50,10 @@ Use this branch when the client is `acli`.
38
50
 
39
51
  Pass both paths as literal absolute paths, unquoted; the helper refuses a missing or empty body file. It writes the ADF document to `--out` and prints `{"adfPath": "..."}`. Pass that path to `--description-file`, or to `--body-file` for a comment. Never hand-write the ADF.
40
52
 
41
- 2. **Never pass Markdown to `--description` or `--description-file`.** `acli` parses it as Jira wiki markup, in which `#` opens an ordered list, so `## Problem` becomes a nested numbered item and every backtick, tilde, underscore, and bracket comes back backslash-escaped. Because the command reports success, only reading the work item back reveals the damage.
42
- 3. **Reserve plain text for a body without any structure to lose**, such as a one-line comment. Submit anything containing headings, lists, or inline marks as ADF.
43
- 4. **Keep your checkboxes**, per [Checklists](#checklists). The helper converts task-list syntax to `taskList` / `taskItem` nodes, so leave it in the Markdown rather than flattening it to plain bullets.
44
- 5. **Do not sanitize.** The HTML allowlist, the composition rules, and the pre-flight checker under [HTML path](#html-path) **do not apply** here, and you must **not** run `update-jira-ticket.mjs`, the HTML checker. `manage-jira-ticket.mjs` is the converter.
53
+ 3. **Never pass Markdown to `--description` or `--description-file`.** `acli` parses it as Jira wiki markup, in which `#` opens an ordered list, so `## Problem` becomes a nested numbered item and every backtick, tilde, underscore, and bracket comes back backslash-escaped. Because the command reports success, only reading the work item back reveals the damage.
54
+ 4. **Reserve plain text for a body without any structure to lose**, such as a one-line comment. Submit anything containing headings, lists, or inline marks as ADF.
55
+ 5. **Keep your checkboxes**, per [Checklists](#checklists). The helper converts task-list syntax to `taskList` / `taskItem` nodes, so leave it in the Markdown rather than flattening it to plain bullets.
56
+ 6. **Do not sanitize.** The HTML allowlist, the composition rules, and the pre-flight checker under [HTML path](#html-path) **do not apply** here, and you must **not** run `update-jira-ticket.mjs`, the HTML checker. `manage-jira-ticket.mjs` is the converter.
45
57
 
46
58
  ## Markdown path
47
59
 
@@ -1,9 +1,9 @@
1
1
  import { createRequire as __cjsCreateRequire } from 'node:module';
2
2
  const require = __cjsCreateRequire(import.meta.url);
3
- var L=Object.defineProperty;var s=(e,r)=>L(e,"name",{value:r,configurable:!0});import{realpathSync as A}from"node:fs";import l from"node:process";import{fileURLToPath as D}from"node:url";function x(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}s(x,"isError");function g(e){try{return x(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}s(g,"describeError");async function y(e){let r=[];for await(let t of e){if(!Buffer.isBuffer(t))throw new TypeError("readAll: expected Buffer chunks (stream must be in binary mode)");r.push(t)}return Buffer.concat(r).toString("utf8")}s(y,"readAll");var F=new Set(["br","hr","img","input","meta","link","area","base","col","embed","source"]);function T(e){let r=[],t=e.length,n=0,o=0;for(;n<t;){let i=e[n],a=e[n+1]??"";if(i==="<"&&I(a)){n>o&&r.push({type:"text",value:e.slice(o,n),offset:o});let f=O(e,n);r.push(f.token),n=f.nextIndex,o=n}else n+=1}return o<t&&r.push({type:"text",value:e.slice(o,t),offset:o}),r}s(T,"tokenize");function I(e){return e==="/"||e>="a"&&e<="z"||e>="A"&&e<="Z"}s(I,"isTagStartChar");function O(e,r){let t=e[r+1]==="/",n=r+(t?2:1),o=m(e,n,_),i=e.slice(n,o),a=i.toLowerCase();if(t){let R=h(e,o,">"),b=Math.min(R+1,e.length);return{token:{type:"close-tag",name:a,rawName:i,offset:r,raw:e.slice(r,b)},nextIndex:b}}let{attrs:f,selfClosing:c,end:p}=$(e,o),d=p<e.length?p+1:e.length,N=c||F.has(a);return{token:{type:"open-tag",name:a,rawName:i,attrs:f,selfClosing:N,offset:r,raw:e.slice(r,d)},nextIndex:d}}s(O,"parseTag");function $(e,r){let t=e.length,n=[],o=!1,i=r;for(;i<t;){i=k(e,i);let a=e[i];if(a===void 0||a===">")break;if(a==="/"){o=!0,i+=1;continue}let f=i;if(i=m(e,i,W),i===f){i+=1;continue}let c=e.slice(f,i).toLowerCase(),{value:p,next:d}=M(e,i);n.push({name:c,value:p}),i=d}return{attrs:n,selfClosing:o,end:i}}s($,"parseAttributes");function M(e,r){let t=k(e,r);if(e[t]!=="=")return{value:null,next:t};t=k(e,t+1);let n=e[t];if(n==='"'||n==="'"){let a=t+1,f=h(e,a,n),c=f<e.length?f+1:e.length;return{value:e.slice(a,f),next:c}}let o=t,i=m(e,o,a=>!w(a)&&a!==">"&&a!=="/");return{value:e.slice(o,i),next:i}}s(M,"parseAttributeValue");function m(e,r,t){let n=e.length,o=r;for(;o<n;){let i=e[o];if(i===void 0||!t(i))break;o+=1}return o}s(m,"readWhile");function h(e,r,t){let n=e.length,o=r;for(;o<n&&e[o]!==t;)o+=1;return o}s(h,"readUntilChar");function k(e,r){return m(e,r,w)}s(k,"skipWhitespace");function _(e){return e>="a"&&e<="z"||e>="A"&&e<="Z"||e>="0"&&e<="9"||e===":"||e==="-"}s(_,"isNameChar");function W(e){return e>="a"&&e<="z"||e>="A"&&e<="Z"||e>="0"&&e<="9"||e==="-"||e==="_"||e===":"}s(W,"isAttrNameChar");function w(e){return[" "," ",`
4
- `,"\r","\f"].includes(e)}s(w,"isWhitespace");function u(e,r){let t=1;for(let n=0;n<r&&n<e.length;n+=1)e[n]===`
5
- `&&(t+=1);return t}s(u,"lineOf");function E(e,r){let t=[];for(let n of e)if(n.type==="open-tag")r(n,t),n.selfClosing||t.push(n);else if(n.type==="close-tag"){for(let o=t.length-1;o>=0;o-=1)if(t[o]?.name===n.name){t.length=o;break}}}s(E,"walkTokens");var z=new Set(["h1","h2","h3","h4","h5","h6","p","ul","ol","li","strong","em","code","a","blockquote","hr","br","table","thead","tbody","tr","th","td"]),v=new Set(["strong","em","a","strike","u","sub","sup"]),j=new Set(["amp","lt","gt"]);function B(e,r){let t=[];return E(e,(n,o)=>{if(n.name==="code"){let i=o.find(a=>v.has(a.name));i&&t.push({rule:"composition-code-inline-mark",snippet:`${i.raw}...${n.raw}`,line:u(r,i.offset),fix:`Move the <code> outside <${i.name}>, or drop the inline mark.`})}else if(v.has(n.name)){let i=o.find(a=>a.name==="code");i&&t.push({rule:"composition-code-inline-mark",snippet:`${i.raw}...${n.raw}`,line:u(r,i.offset),fix:`Move <${n.name}> outside the <code>, or drop the inline mark.`})}}),t}s(B,"compositionCodeInlineMarkRule");function P(e,r){let t=[],n=/&([a-zA-Z][a-zA-Z0-9]*);/g;for(let o of e)if(o.type==="text")for(let i of o.value.matchAll(n)){let a=i[1];if(a===void 0||j.has(a))continue;let f=o.offset+i.index;t.push({rule:"named-entity",snippet:i[0],line:u(r,f),fix:"Replace with literal Unicode (e.g., \u2014 for &mdash;, \u2026 for &hellip;, a regular space for &nbsp;)."})}return t}s(P,"namedEntityRule");function U(e,r){let t=[];for(let n of e)n.type==="open-tag"&&(n.name.startsWith("ac:")||n.name.startsWith("ri:"))&&t.push({rule:"confluence-construct",snippet:n.raw,line:u(r,n.offset),fix:`Remove the <${n.rawName}> construct. Confluence storage-format elements do not have a Jira analogue.`});return t}s(U,"confluenceConstructRule");function Z(e,r){let t=[];for(let[n,o]of e.entries())o.type!=="open-tag"||o.name!=="pre"||V(e,n)&&t.push({rule:"pre-multiline",snippet:o.raw,line:u(r,o.offset),fix:"Replace the multi-line <pre> with per-line <p><code>...</code></p>, or a single <p> using <br> separators."});return t}s(Z,"preMultilineRule");function V(e,r){let t=1;for(let n=r+1;n<e.length;n+=1){let o=e[n];if(o===void 0)break;if(o.type==="open-tag"&&o.name==="pre"&&!o.selfClosing)t+=1;else if(o.type==="close-tag"&&o.name==="pre"){if(t-=1,t===0)return!1}else if(o.type==="text"&&o.value.includes(`
6
- `))return!0}return!1}s(V,"hasNewlineInPre");function q(e,r){let t=[];for(let n of e)n.type==="open-tag"&&(z.has(n.name)||n.name.startsWith("ac:")||n.name.startsWith("ri:")||t.push({rule:"disallowed-element",snippet:n.raw,line:u(r,n.offset),fix:`Remove or replace <${n.rawName}>. The allowlist is documented in update-jira-ticket/SKILL.md.`}));return t}s(q,"disallowedElementRule");var S=[B,P,U,Z,q];function C(e){let r=T(e),t=S.flatMap(n=>n(r,e));return t.length===0?{ok:!0}:{ok:!1,findings:t}}s(C,"check");async function J(){try{let e=await y(l.stdin),r=C(e);l.stdout.write(`${JSON.stringify(r,null,2)}
7
- `)}catch(e){let r=g(e);l.stderr.write(`update-jira-ticket: ${r}
8
- `),l.exit(1)}}s(J,"main");K()&&await J();function K(){let e=l.argv[1];if(e===void 0)return!1;try{return A(D(import.meta.url))===A(e)}catch(r){let t=g(r);return l.stderr.write(`update-jira-ticket: warning: could not determine entry point: ${t}
9
- `),!1}}s(K,"isEntryPoint");
3
+ var I=Object.defineProperty;var s=(e,r)=>I(e,"name",{value:r,configurable:!0});import m from"node:process";function x(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}s(x,"isError");function c(e){try{return x(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}s(c,"describeError");import{realpathSync as y}from"node:fs";import T from"node:process";import{fileURLToPath as $}from"node:url";function h(e,r){let t=T.argv[1];if(t===void 0)return!1;try{return y($(e))===y(t)}catch(n){return T.stderr.write(`${r}: warning: could not determine entry point: ${c(n)}
4
+ `),!0}}s(h,"isEntryPoint");async function w(e){let r=[];for await(let t of e){if(!Buffer.isBuffer(t))throw new TypeError("readAll: expected Buffer chunks (stream must be in binary mode)");r.push(t)}return Buffer.concat(r).toString("utf8")}s(w,"readAll");var O=new Set(["br","hr","img","input","meta","link","area","base","col","embed","source"]);function E(e){let r=[],t=e.length,n=0,o=0;for(;n<t;){let i=e[n],a=e[n+1]??"";if(i==="<"&&M(a)){n>o&&r.push({type:"text",value:e.slice(o,n),offset:o});let f=_(e,n);r.push(f.token),n=f.nextIndex,o=n}else n+=1}return o<t&&r.push({type:"text",value:e.slice(o,t),offset:o}),r}s(E,"tokenize");function M(e){return e==="/"||e>="a"&&e<="z"||e>="A"&&e<="Z"}s(M,"isTagStartChar");function _(e,r){let t=e[r+1]==="/",n=r+(t?2:1),o=g(e,n,j),i=e.slice(n,o),a=i.toLowerCase();if(t){let F=v(e,o,">"),b=Math.min(F+1,e.length);return{token:{type:"close-tag",name:a,rawName:i,offset:r,raw:e.slice(r,b)},nextIndex:b}}let{attrs:f,selfClosing:l,end:p}=W(e,o),d=p<e.length?p+1:e.length,L=l||O.has(a);return{token:{type:"open-tag",name:a,rawName:i,attrs:f,selfClosing:L,offset:r,raw:e.slice(r,d)},nextIndex:d}}s(_,"parseTag");function W(e,r){let t=e.length,n=[],o=!1,i=r;for(;i<t;){i=k(e,i);let a=e[i];if(a===void 0||a===">")break;if(a==="/"){o=!0,i+=1;continue}let f=i;if(i=g(e,i,P),i===f){i+=1;continue}let l=e.slice(f,i).toLowerCase(),{value:p,next:d}=z(e,i);n.push({name:l,value:p}),i=d}return{attrs:n,selfClosing:o,end:i}}s(W,"parseAttributes");function z(e,r){let t=k(e,r);if(e[t]!=="=")return{value:null,next:t};t=k(e,t+1);let n=e[t];if(n==='"'||n==="'"){let a=t+1,f=v(e,a,n),l=f<e.length?f+1:e.length;return{value:e.slice(a,f),next:l}}let o=t,i=g(e,o,a=>!S(a)&&a!==">"&&a!=="/");return{value:e.slice(o,i),next:i}}s(z,"parseAttributeValue");function g(e,r,t){let n=e.length,o=r;for(;o<n;){let i=e[o];if(i===void 0||!t(i))break;o+=1}return o}s(g,"readWhile");function v(e,r,t){let n=e.length,o=r;for(;o<n&&e[o]!==t;)o+=1;return o}s(v,"readUntilChar");function k(e,r){return g(e,r,S)}s(k,"skipWhitespace");function j(e){return e>="a"&&e<="z"||e>="A"&&e<="Z"||e>="0"&&e<="9"||e===":"||e==="-"}s(j,"isNameChar");function P(e){return e>="a"&&e<="z"||e>="A"&&e<="Z"||e>="0"&&e<="9"||e==="-"||e==="_"||e===":"}s(P,"isAttrNameChar");function S(e){return[" "," ",`
5
+ `,"\r","\f"].includes(e)}s(S,"isWhitespace");function u(e,r){let t=1;for(let n=0;n<r&&n<e.length;n+=1)e[n]===`
6
+ `&&(t+=1);return t}s(u,"lineOf");function C(e,r){let t=[];for(let n of e)if(n.type==="open-tag")r(n,t),n.selfClosing||t.push(n);else if(n.type==="close-tag"){for(let o=t.length-1;o>=0;o-=1)if(t[o]?.name===n.name){t.length=o;break}}}s(C,"walkTokens");var B=new Set(["h1","h2","h3","h4","h5","h6","p","ul","ol","li","strong","em","code","a","blockquote","hr","br","table","thead","tbody","tr","th","td"]),A=new Set(["strong","em","a","strike","u","sub","sup"]),U=new Set(["amp","lt","gt"]);function Z(e,r){let t=[];return C(e,(n,o)=>{if(n.name==="code"){let i=o.find(a=>A.has(a.name));i&&t.push({rule:"composition-code-inline-mark",snippet:`${i.raw}...${n.raw}`,line:u(r,i.offset),fix:`Move the <code> outside <${i.name}>, or drop the inline mark.`})}else if(A.has(n.name)){let i=o.find(a=>a.name==="code");i&&t.push({rule:"composition-code-inline-mark",snippet:`${i.raw}...${n.raw}`,line:u(r,i.offset),fix:`Move <${n.name}> outside the <code>, or drop the inline mark.`})}}),t}s(Z,"compositionCodeInlineMarkRule");function V(e,r){let t=[],n=/&([a-zA-Z][a-zA-Z0-9]*);/g;for(let o of e)if(o.type==="text")for(let i of o.value.matchAll(n)){let a=i[1];if(a===void 0||U.has(a))continue;let f=o.offset+i.index;t.push({rule:"named-entity",snippet:i[0],line:u(r,f),fix:"Replace with literal Unicode (e.g., \u2014 for &mdash;, \u2026 for &hellip;, a regular space for &nbsp;)."})}return t}s(V,"namedEntityRule");function q(e,r){let t=[];for(let n of e)n.type==="open-tag"&&(n.name.startsWith("ac:")||n.name.startsWith("ri:"))&&t.push({rule:"confluence-construct",snippet:n.raw,line:u(r,n.offset),fix:`Remove the <${n.rawName}> construct. Confluence storage-format elements do not have a Jira analogue.`});return t}s(q,"confluenceConstructRule");function D(e,r){let t=[];for(let[n,o]of e.entries())o.type!=="open-tag"||o.name!=="pre"||J(e,n)&&t.push({rule:"pre-multiline",snippet:o.raw,line:u(r,o.offset),fix:"Replace the multi-line <pre> with per-line <p><code>...</code></p>, or a single <p> using <br> separators."});return t}s(D,"preMultilineRule");function J(e,r){let t=1;for(let n=r+1;n<e.length;n+=1){let o=e[n];if(o===void 0)break;if(o.type==="open-tag"&&o.name==="pre"&&!o.selfClosing)t+=1;else if(o.type==="close-tag"&&o.name==="pre"){if(t-=1,t===0)return!1}else if(o.type==="text"&&o.value.includes(`
7
+ `))return!0}return!1}s(J,"hasNewlineInPre");function K(e,r){let t=[];for(let n of e)n.type==="open-tag"&&(B.has(n.name)||n.name.startsWith("ac:")||n.name.startsWith("ri:")||t.push({rule:"disallowed-element",snippet:n.raw,line:u(r,n.offset),fix:`Remove or replace <${n.rawName}>. The allowlist is documented in update-jira-ticket/SKILL.md.`}));return t}s(K,"disallowedElementRule");var N=[Z,V,q,D,K];function R(e){let r=E(e),t=N.flatMap(n=>n(r,e));return t.length===0?{ok:!0}:{ok:!1,findings:t}}s(R,"check");async function X(){try{let e=await w(m.stdin),r=R(e);m.stdout.write(`${JSON.stringify(r,null,2)}
8
+ `)}catch(e){let r=c(e);m.stderr.write(`update-jira-ticket: ${r}
9
+ `),m.exit(1)}}s(X,"main");h(import.meta.url,"update-jira-ticket")&&await X();
@@ -76,21 +76,21 @@ State which path was selected, and why, before proceeding.
76
76
 
77
77
  For each finding, assign one of these classes:
78
78
 
79
- | Class | Destination | Test |
80
- | ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------ |
81
- | **Ambient** | `AGENTS.md` | Applies only to this repo, and the obvious action goes wrong without it |
82
- | **Reference** | The owning package's README, or `docs/` | Applies only to this repo, but an agent needs it occasionally |
83
- | **Already covered** | Omit | Already stated in `{harness_home_dir}/{harness_guidance_file}`, or printed by the tool itself |
84
- | **General** | Recommend for the global guidance | Applies across repos but not yet in general guidance |
85
- | **Ambiguous** | Ask the user | Could go either way; collect every such finding into one review at the draft or change-list gate |
79
+ | Class | Destination | Test |
80
+ | ------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
81
+ | **Ambient** | `AGENTS.md` | Applies only to this repo, and the obvious action goes wrong without it |
82
+ | **Reference** | The owning package's README, or `docs/` | Applies only to this repo, but an agent needs it occasionally |
83
+ | **Already covered** | Omit; for a fact defined in a repository file, a pointer to that file | Already stated in `{harness_home_dir}/{harness_guidance_file}` or by a rulebook loaded into the session, defined in a repository file, or printed by the tool itself |
84
+ | **General** | Recommend for the global guidance | Applies across repos but not yet in general guidance |
85
+ | **Ambiguous** | Ask the user | Could go either way; collect every such finding into one review at the draft or change-list gate |
86
86
 
87
87
  **Rules:**
88
88
 
89
89
  - Two axes decide the destination. **Scope** (general vs project-specific) separates `{harness_home_dir}/{harness_guidance_file}` from this repo; **tier** (ambient vs reference) then separates what `AGENTS.md` states from what a package README does. Neither axis is nature (prescriptive vs descriptive): Conventions, commands, and architectural decisions all classify the same way whether they are rules or facts.
90
90
  - What belongs in a README, and where the rest goes, is stated by {rulebook:readme-conventions}. Consult it before assigning a finding to the reference tier: A README's shape follows from what it describes, so the same finding is placed differently in a library's README and in a monorepo root's.
91
91
  - A finding belongs in the ambient tier only when it is absent from the tool's own output _and_ the obvious action goes wrong without it. A command table restates `--help`; a directory listing restates `ls`. Both are reference at best, and reference material injected at launch goes stale silently, because nothing fails when it drifts.
92
- - Do not duplicate general guidance. If a project-specific convention _extends_ a general one, include only the delta.
93
- - When unsure about scope, place the finding on the recommended side provisionally and collect every ambiguous finding into one review at the gate below, as multiple-choice questions where possible.
92
+ - Do not duplicate general guidance or a rulebook loaded into the session; omit what they state. For a fact defined in a repository file, point to that file and add only what it does not state, per the "Documentation placement" section of the shared agent instructions. If a project-specific convention _extends_ a general one, include only the delta.
93
+ - When unsure about scope, place the finding on the recommended side provisionally and collect every ambiguous finding into one review at the gate below, as multiple-choice questions when possible.
94
94
  - When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
95
95
  - Content that is obvious from reading the code (e.g., "this project uses TypeScript") does not add any value. Include only what would save an agent from a wrong assumption or a slow discovery.
96
96
 
@@ -163,7 +163,7 @@ Scan the baseline for a harness-scoped path and for any `<!-- rulebook:` marker.
163
163
  Two tiers, because a mature file contains more claims than one exhaustive pass can cover. A 35-line file decomposes into dozens of independently checkable assertions, and one at the line budget into several hundred.
164
164
 
165
165
  - **Tier 1: Every checkable token, exhaustively.** Paths, filenames, command strings, counts, package and symbol names. Drift appears in these tokens: a directory listing that has gained an entry, a count off by two, a tool named one hop from what runs.
166
- - **Tier 2: Narrative claims, in the sections touched by the gap-scan window.** Unquantified prose is audited where the repo has moved under it, not everywhere.
166
+ - **Tier 2: Narrative claims, in the sections touched by the gap-scan window.** Audit unquantified prose only in the sections whose subject the repo has changed, not everywhere.
167
167
 
168
168
  Check the claim, not the section. A stale listing looks entirely plausible and is wrong only once the directory is listed, so recognizing a section's shape is the signal to slow down rather than to move on.
169
169
 
@@ -177,7 +177,7 @@ A `holds` row without an evidence token is not a permitted state. The audit is o
177
177
 
178
178
  Close the ledger by naming what was not audited, so that a bounded run reads as bounded.
179
179
 
180
- Re-run the Phase 2 classification only on the sections touched by the window, plus one pass against `{harness_home_dir}/{harness_guidance_file}` for content that the global file now states. What was ambient last month is still ambient unless something moved.
180
+ Re-run the Phase 2 classification only on the sections touched by the window, plus one pass against `{harness_home_dir}/{harness_guidance_file}` and the rulebooks loaded into the session for content that they now state. What was ambient last month is still ambient unless something moved.
181
181
 
182
182
  ##### Scan for gaps
183
183
 
@@ -282,7 +282,7 @@ Before presenting the draft or the change list, verify:
282
282
  - [ ] The file does not contain a path into a harness-owned directory, home-anchored or repository-local
283
283
  - [ ] The file does not contain a `<!-- rulebook:` marker anywhere
284
284
  - [ ] The file is at most 200 lines, matching the ambient budget against which the published guidance checklist reports; anything that pushed it over was moved to the package level behind a pointer
285
- - [ ] The file does not duplicate any content from `{harness_home_dir}/{harness_guidance_file}`
285
+ - [ ] The file does not duplicate any content from `{harness_home_dir}/{harness_guidance_file}`, from a rulebook loaded into the session, or from a repository file that defines it; it points to a defining repository file instead
286
286
  - [ ] The file does not contain a section that merely restates what's obvious from the code
287
287
  - [ ] Commands listed are ones that an agent would actually need (not exhaustive npm script listings)
288
288
  - [ ] Each command group states where to run it (repo root, package directory, etc.); don't assume the agent knows
@@ -6,6 +6,9 @@
6
6
  _defaults:
7
7
  permissionMode: bypassPermissions
8
8
 
9
+ disposition-challenger:
10
+ model: inherit
11
+
9
12
  handoff-reviewer:
10
13
  model: sonnet
11
14
 
@@ -17,3 +20,6 @@ plan-reviser:
17
20
 
18
21
  prose-reviser:
19
22
  model: inherit
23
+
24
+ usability-assessor:
25
+ model: inherit
@@ -6,6 +6,11 @@
6
6
  _defaults:
7
7
  tools: [bash, create_file, expand_code_chunks, expand_folder, grep, open_files]
8
8
 
9
+ # Rovo does not read a denylist, so the read-only grant is named here.
10
+ # `create_file` is dropped: The challenger returns text.
11
+ disposition-challenger:
12
+ tools: [bash, expand_code_chunks, expand_folder, grep, open_files]
13
+
9
14
  # Rovo does not read a denylist, so the read-only grant is named here.
10
15
  # `create_file` is dropped: The drafter returns text.
11
16
  entry-drafter:
@@ -20,8 +25,8 @@ plan-reviewer: {} # inherits _defaults
20
25
 
21
26
  plan-reviser: {} # inherits _defaults
22
27
 
23
- # Edits prose in place and creates nothing: `create_file` is dropped, and `bash` with it, the reviser
24
- # not having any command to run.
28
+ # Edits prose in place and creates nothing: `create_file` is dropped, and `bash` is dropped too, because the
29
+ # reviser does not run any command.
25
30
  prose-reviser:
26
31
  tools: [expand_code_chunks, expand_folder, find_and_replace_code, grep, open_files]
27
32
 
@@ -29,3 +34,8 @@ prose-reviser:
29
34
  # `create_file` is dropped: The assessor returns text.
30
35
  ticket-assessor:
31
36
  tools: [bash, expand_code_chunks, expand_folder, grep, open_files]
37
+
38
+ # Rovo does not read a denylist, so the read-only grant is named here. The subagent is dispatched only by the
39
+ # Claude-only `assess-usability`, so a lens never runs under this grant.
40
+ usability-assessor:
41
+ tools: [bash, expand_code_chunks, expand_folder, grep, open_files]
@@ -1,11 +1,12 @@
1
1
  ---
2
2
  name: canary
3
3
  description: Deployment canary for the declared-subagent mechanism; not meant to be invoked.
4
+ standalone: exercises the declared-subagent mechanism rather than doing work of its own
4
5
  tools: [Read]
5
6
  ---
6
7
 
7
8
  # Canary
8
9
 
9
- This subagent exists to prove that declared subagents deploy end-to-end. It doesn't have any consumers in this library and is never dispatched. Its body deliberately exercises the harness transform so that the deployed file is a real specimen: A `{tool:Read}` placeholder rewrites to the harness-native tool name, and a `{harness_home_dir}` reference rewrites to the harness home path.
10
+ This subagent exists to prove that declared subagents deploy end-to-end. It doesn't have any consumers in this library and is never dispatched. Its body deliberately exercises the harness transform so that the deployed file is a real specimen: The transform rewrites a `{tool:Read}` placeholder to the harness-native tool name and a `{harness_home_dir}` reference to the harness home path.
10
11
 
11
12
  Read configuration from `{harness_home_dir}/skills/_data/` if you ever need it, using the {tool:Read} tool.
@@ -0,0 +1,98 @@
1
+ ---
2
+ name: code-health-assessor
3
+ description: Assess one unit of a codebase through one lens of a code-health brief, asking of its code and tests whether they would be written the same way today. Returns refactoring proposals, each with an evidence key, checkable evidence, one proposed change, and its strength, size, and reach, and writes only its report and proposals, into its evidence directory.
4
+ disallowedTools: Edit, NotebookEdit, Task, Write
5
+ ---
6
+
7
+ # Code-health assessor
8
+
9
+ You assess one unit of a codebase through one lens of a brief. You have not seen the session that dispatched you or any other lens's report, and you cannot ask the author of the brief. You read the code, the tests, and the sensor output, and you return one report as text.
10
+
11
+ ## Your assignment
12
+
13
+ Your dispatch contains four scalars:
14
+
15
+ - **`brief`**: The path of the code-health brief. Read it in full before your first step.
16
+ - **`lens`**: The name of your lens, as the brief's lens table writes it.
17
+ - **`sense`**: The path of the sense document: the unit's hotspots, co-change pairs, coverage, test timings, and the results of the repository's own checks, each with its status. The `outputPath` of a check names its log.
18
+ - **`output`**: Your evidence directory. It exists.
19
+
20
+ From the brief, take your lens's row: its ID prefix, its subject, the rulebooks that it reads by path, and its proposal cap. Take the unit, the exclusions, the reuse-candidate directory, and the library inventory. Everything that the brief marks settled is settled: Do not re-decide the unit, the lenses, or the caps.
21
+
22
+ ## The question
23
+
24
+ Ask one question of every file that you read, code and tests alike: **Would we write this the same way if we wrote it afresh today?** The reference points are the rulebooks that the brief names, the libraries in the inventory and the repository's own helpers, the current test tiers, and the shape of the surrounding modules as they are now. A file that an older convention shaped, a helper that duplicates one that exists, and a test written below the current bar all answer "no".
25
+
26
+ Ask it of the tests as you ask it of the code: Your lens's subject applies to the test files of the unit as much as to its source.
27
+
28
+ ## What you may do
29
+
30
+ - Read any file in the repository and in the paths that the brief names.
31
+ - Run read-only commands, such as `git log`, `git blame`, `rg`, and `fd`. When a command must write, such as a scratch output, write it under `output` and nowhere else.
32
+ - Never edit, create, stage, or delete a file outside `output`, never commit, and never reach a remote. The dispatching session checks the working tree after you return and stops the run if you changed it.
33
+
34
+ Start from the hotspot ranking: Read the highest-ranked files of the unit first, so that the sample that you read is where change concentrates. Record the files that you read as your sample under **Limits**.
35
+
36
+ ## What counts as a proposal
37
+
38
+ A proposal is one change that makes the code or a test the way it would be written today. It is not a grade: Never record confidence, value, priority, or severity. A later triage grades each proposal, and a grade here would anchor it.
39
+
40
+ Each proposal has:
41
+
42
+ - **`key`**: `{path}:{rule-or-smell}`, a stable name for the subject, such as `src/run.ts:long-function` or `src/a.test.ts:duplicated-setup`. Use the smell or tidying names of Fowler's catalogue and Beck's tidyings, or the rulebook's own term, in kebab case. Two runs that find the same problem write the same key.
43
+ - **`paths`**: The files that the change touches.
44
+ - **`evidence`**: One or more entries that a helper checks against the tree:
45
+ - `span`: a `path`, a `startLine` and `endLine`, and a `quote` copied from those lines.
46
+ - `rule`: a `rulebook` path, a `section` (the heading text without `#`), and a `quote` copied from that section.
47
+ - `sensor`: the `sensor` name from the sense document and a `detail`, such as the hotspot rank or the coverage percentage.
48
+ - **`change`**: One change, stated so that an implementer could make it without your report. Two changes are two proposals.
49
+ - **`strength`**: `sensor` when a sensor shows the problem, `rule` when a rulebook sentence states it, `reading` when only your reading does.
50
+ - **`size`**: `small` (one function or one test), `medium` (one module), or `large` (several modules).
51
+ - **`reach`**: The number of files or call sites that the problem affects.
52
+
53
+ A quote that is not copied exactly from its lines or its section fails the check, and the proposal is dropped. Stay within your lens's proposal cap; when you find more, keep the ones with the greatest reach.
54
+
55
+ ## Report format
56
+
57
+ Return this report and nothing else:
58
+
59
+ ````markdown
60
+ ## Proposals
61
+
62
+ ### {ID}: {one-line title}
63
+
64
+ - Key: {key}
65
+ - Paths: {paths}
66
+ - Change: {the one change}
67
+ - Strength: {sensor | rule | reading}; size: {small | medium | large}; reach: {n}
68
+ - Evidence: {each entry, in one line}
69
+
70
+ ## Limits
71
+
72
+ - Sample: {the files that you read}
73
+ - {anything else that the lens could not establish, and why}
74
+
75
+ ```json
76
+ [{ "id": "...", "title": "...", "key": "...", "paths": ["..."], "evidence": [{ "kind": "span", "path": "...", "startLine": 1, "endLine": 2, "quote": "..." }], "change": "...", "strength": "sensor", "size": "small", "reach": 1 }]
77
+ ```
78
+
79
+ Phase: code-health-assessment
80
+ ````
81
+
82
+ `{ID}` is the lens's prefix from the brief followed by a number, starting at 1. The JSON block contains the same proposals as the **Proposals** section, as one array with exactly the fields shown, and `[]` when you have none. Write `- none` under **Proposals** when it is empty rather than omitting it. End with the `Phase: code-health-assessment` line, which tells the dispatching session that the report is complete.
83
+
84
+ Before you return, save the report as `{output}/report.md` and the JSON block's array as `{output}/proposals.json`, each with a quoted shell heredoc (`<<'EOF'`), so that the dispatching session reads them from disk rather than copying them from your reply.
85
+
86
+ ## How you write
87
+
88
+ <!-- include: ../_partials/plain-speech.md / -->
89
+
90
+ <!-- include: ../_partials/concision.md / -->
91
+
92
+ <!-- include: ../_partials/file-access.md / -->
93
+
94
+ <!-- include: ../_partials/shell-commands.md / -->
95
+
96
+ <!-- guidance-hook: implementation-preferences -->
97
+
98
+ <!-- guidance-hook: writing-preferences -->
@@ -0,0 +1,78 @@
1
+ ---
2
+ name: disposition-challenger
3
+ description: Argue against every disposition and grade that a triage of findings recommends, from the findings, the recommendations, and the repository alone. Returns one challenge per item and does not write any file.
4
+ disallowedTools: Edit, NotebookEdit, Task, Write
5
+ maxTurns: 80
6
+ ---
7
+
8
+ # Disposition challenger
9
+
10
+ You read a findings artifact and the recommendations that a triage made on it, and you argue against each one. You have not seen the session that made them, and you cannot ask its author: Your value is that you have only the findings, the recommendations, and the repository. You return text, and you do not write any file.
11
+
12
+ ## Your assignment
13
+
14
+ Your dispatch contains three scalars:
15
+
16
+ - **`findings`**: The path of the findings artifact. Read it in full.
17
+ - **`recommendations`**: The path of the recommendations file: one line per item, with its id, title, disposition, confidence, value, and reason.
18
+ - **`root`**: The repository root, against which every path in the findings is resolved, and in which `gh` reads the tracker.
19
+
20
+ For each item, find the strongest argument against its disposition and against each grade, check the claim on which the recommendation rests, and propose the change that you would make. The grades are defined as follows:
21
+
22
+ - **Confidence** states advisability: `high` is clearly worth doing, `medium` is worth doing but arguable, `low` is not worth a ticket now. A borderline item takes the lower grade. Only an item graded `high` or `medium` gets a ticket.
23
+ - **Value** states how much the item matters: `must-have`, `should-have`, `nice-to-have`, `questionable`.
24
+
25
+ The dispositions are `ticket` (a new ticket under the triage's umbrella), `comment` (a note on an existing issue), `merge` (folded into another item's ticket), and `drop`.
26
+
27
+ <HARD-GATE>
28
+ Never write to the tracker: Do not comment, edit, label, close, or create anything, through `gh` or any other means. Run only `gh` commands that read.
29
+
30
+ Never write to the working tree or to git: Do not create, edit, or delete a file, and do not run a git command that changes a ref, the index, or the working tree.
31
+ </HARD-GATE>
32
+
33
+ ## Method
34
+
35
+ Work in rounds, where a round is one turn of tool calls. Batch every read and check that does not depend on another into the same round: Read `AGENTS.md`, the findings, and the recommendations together in the first round, then verify many items per round. Your verification budget is 4 rounds plus 1 per item, capped at 30. Count the items as soon as you have read the recommendations, count the rounds against that budget as you go, and when it is spent, stop and write your report. The report is your only output, and a challenge that stops before writing it delivers nothing. Mark each item that you did not reach `Unverified` in its `Evidence` line.
36
+
37
+ For each item:
38
+
39
+ 1. **Check the claim.** Read the code that the finding names and confirm that the problem exists as described, or that it does not. Search the open issues with `gh issue list --search` and read the candidates with `gh issue view`: An item that an open issue already covers is a `comment` or a `drop`, not a `ticket`, and a `comment` whose issue is closed or does not cover it is wrong.
40
+ 2. **Argue against the disposition.** Ask whether the item is worth a ticket at all, whether it belongs inside another item's ticket, whether the issue that it would comment on owns the file or the behavior, and whether the finding is a design decision that the repository records rather than a defect.
41
+ 3. **Argue against each grade.** Ask what makes the item less advisable than its confidence says, and less important than its value says: the reach of the problem, the cost of the fix, a decision that already settled it, a user that it never affects. Argue the grade up when the evidence supports that instead.
42
+ 4. **Propose.** State `keep` when every argument fails on the evidence, and otherwise the disposition and grades that you would set.
43
+
44
+ Do not propose a new item: The inventory is the triage's, and you judge what it recommends. Do not redesign the fix behind an item.
45
+
46
+ ## What you return
47
+
48
+ One section per item, in the order of the recommendations file, then the return block. Return nothing else, and do not write any file.
49
+
50
+ ```markdown
51
+ ### {id}: {title}
52
+
53
+ - Argument: {the strongest case against the disposition and the grades, in one or two sentences}
54
+ - Evidence: {what the code and the tracker show, with paths and issue numbers; `Unverified` when the budget ran out before this item}
55
+ - Proposes: {keep | {disposition}, confidence {grade}, value {grade}}
56
+ ```
57
+
58
+ ```text
59
+ Phase: disposition-challenge
60
+ Status: completed|failed
61
+ Items: {n}
62
+ Challenged: {the number of items whose Proposes line is not keep}
63
+ Unverified: {the number of items marked Unverified}
64
+ ```
65
+
66
+ `Status: failed` means that you could not read the findings or the recommendations; name the path in the first section.
67
+
68
+ ## How you write
69
+
70
+ <!-- include: ../_partials/plain-speech.md / -->
71
+
72
+ <!-- include: ../_partials/concision.md / -->
73
+
74
+ <!-- include: ../_partials/file-access.md / -->
75
+
76
+ <!-- include: ../_partials/shell-commands.md / -->
77
+
78
+ <!-- guidance-hook: writing-preferences -->
@@ -11,7 +11,7 @@ You write the lede and the entry list for one change: a short paragraph stating
11
11
 
12
12
  ## Your assignment
13
13
 
14
- Answer one question: **What changed?**
14
+ Answer one question: **What changed?** What changed is the difference between the default branch and this branch's head, as `git diff {default_branch}...HEAD` shows it: what the code now does and contains that the code on the default branch did not.
15
15
 
16
16
  Who is asking is selected by the `tier` that the taxonomy assigns to the entry's own type. A change that touches several tiers has several readers, and each entry is written for the reader that its own type names.
17
17
 
@@ -46,7 +46,7 @@ Read the change and settle the entries: what each outcome is, which type it take
46
46
 
47
47
  1. **Session context.** `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits a manifest JSON on stdout. Take `default_branch`, `ticket_url`, and `ticket_id` from it.
48
48
 
49
- 2. **Commit titles and bodies.** `git log {default_branch}..HEAD --format=%s%n%b`.
49
+ 2. **Commit titles and bodies.** `git log {default_branch}..HEAD --format=%s%n%b`. The log records the branch's steps, which tell you which edits form one outcome and what each is for. The change itself is in the diff.
50
50
 
51
51
  3. **The change itself.** `git diff {default_branch}...HEAD`.
52
52
 
@@ -56,7 +56,7 @@ Read the change and settle the entries: what each outcome is, which type it take
56
56
 
57
57
  5. **The ticket.** Resolve it in this order: the `ticket-source` scalar from your dispatch, when present; otherwise `ticket_url`; otherwise `ticket_id`. Fetch a GitHub issue with `gh issue view {number} --json title,body`. Fetch a Jira issue with whichever connected read tool takes an issue URL, or the one taking an issue key and a cloud id when that is what the machine has.
58
58
 
59
- **Read the ticket's `## Problem` section and nothing else.** The proposed solution and the acceptance criteria are deliberation about what to build, and an entry reports what the change did on its own merits, not what the ticket asked for.
59
+ **Read the ticket's `## Problem` section and nothing else.** It says what need in the repository the change meets, and the diff says what the change did. When it explains why the work is split across pull requests or what a later one will do, that is how the work was staged, not what the change is for. The proposed solution and the acceptance criteria are deliberation about what to build, and an entry reports what the change did, not what the ticket asked for.
60
60
 
61
61
  A ticket that you cannot fetch, and a branch that names none, are both normal. Draft from the commit log and the diff alone, and name the omission in your report. Never fill the gap by asking the caller for a summary.
62
62
 
@@ -66,13 +66,13 @@ Read the change and settle the entries: what each outcome is, which type it take
66
66
 
67
67
  A supporting edit in another workspace does not contribute any scope. A catalog move that leaves that workspace's resolved versions unchanged is one, together with the lockfile and workspace-manifest edits beside it: It serves the outcome that needed the catalog entry and changes nothing in the other workspace.
68
68
 
69
- 7. **Exemplars.** Run `node {harness_home_dir}/scripts/select-lede-exemplars.mjs --type {type} --min-quality strong` once per distinct type among your entries. It returns text rated `strong` or `exemplary` by the author, newest first. Read it for the level of detail and the register that it uses, not for phrases to reuse. An empty list is a normal result; draft without it.
69
+ 7. **Exemplars.** Run `node {harness_home_dir}/scripts/select-lede-exemplars.mjs --type {type} --min-quality strong` once per distinct pair of `type` and `breaking` among your entries, adding `--breaking` for a pair whose `breaking` is `true`. `breaking` is the value that "The form that your answer takes" sets from the commit log. It returns text rated `strong` or `exemplary` by the author, newest first. Read it for the level of detail and the register that it uses, not for phrases to reuse. An empty list is a normal result; draft without it.
70
70
 
71
- Calibrate each entry against the exemplars drawn for its own type. One type's exemplars miscalibrate every other type, because each was written for the reader that its own tier names.
71
+ Calibrate each entry against the exemplars drawn for its own pair. One type's exemplars miscalibrate every other type, because each was written for the reader that its own tier names.
72
72
 
73
73
  Each record's text is a whole approved lede, so the sets you drew also calibrate the lede that you write. Read them together for it, since the lede describes the change as a whole rather than one of its types.
74
74
 
75
- When you cannot resolve an outcome's type against the taxonomy, put `--tier {tier}` in place of `--type {type}` for that outcome, keep `--min-quality strong`, and name the omission in your report. `{tier}` is the `tier` scalar in your dispatch, which names the branch's reader: The outcome did not resolve to any type, so the taxonomy does not name a tier for it either. Never supply a `type` that the taxonomy does not declare: A guessed type selects exemplars written for the wrong reader.
75
+ When you cannot resolve an outcome's type against the taxonomy, put `--tier {tier}` in place of `--type {type}` for that outcome, keep `--min-quality strong` and any `--breaking`, and name the omission in your report. `{tier}` is the `tier` scalar in your dispatch, which names the branch's reader: The outcome did not resolve to any type, so the taxonomy does not name a tier for it either. Never supply a `type` that the taxonomy does not declare: A guessed type selects exemplars written for the wrong reader.
76
76
 
77
77
  Writing follows.
78
78
 
@@ -80,7 +80,7 @@ Writing follows.
80
80
 
81
81
  An entry list drops true facts. Almost everything the change contains is accurate, defensible, and not worth the reader's seconds, so the question is never whether a fact is real but whether this reader acts on it. Leave out the rest, however much effort it took to establish.
82
82
 
83
- Some facts describe how the change was produced rather than what it did: review mechanics, ticket and finding numbers, and test and CI runs. A commit body often contains them, and an entry that you write never includes them. An update to a bookkeeping record, such as a sweep ledger under `.agents/`, is of the same kind: It is not an outcome, and it does not get an entry.
83
+ Some facts describe how the change was produced rather than what it did: how the need for it arose, the branch's own steps, where its code or values were copied from, why the work is split across pull requests or what a later one will do, review mechanics, ticket and finding numbers, and test and CI runs. A commit body or a ticket often contains them, and neither the lede nor an entry that you write includes them. An update to a bookkeeping record, such as a sweep ledger under `.agents/`, is of the same kind: It is not an outcome, and it does not get an entry.
84
84
 
85
85
  The general concision rule does not apply here. It tells a writer to keep every decision, constraint, and actionable fact and to compose tight instead of trimming, which is right for a plan or a report and wrong for this genre: The facts that you leave out are actionable ones, and the reader has the diff one click away.
86
86
 
@@ -104,7 +104,7 @@ The lede summarizes the change, and the entries enumerate it. The same reader re
104
104
 
105
105
  - Prose, never a list, and never the entries retold one by one. A lede that gives each entry its own sentence is an inventory of the change rather than an account of it, whatever its form.
106
106
  - The first sentence states what the change does. Add a sentence only for what the reader still needs in order to answer that question, such as a consequence that they act on. A one-sentence lede is often complete, and none runs past three.
107
- - The lede reports the change as a whole. Where the entries serve one outcome, the lede names that outcome. Where the change has several outcomes, the lede leads with the one that the change is about and covers the rest in a clause at most.
107
+ - The lede reports the change as a whole. When the entries serve one outcome, the lede names that outcome. When the change has several outcomes, the lede leads with the one that the change is about and covers the rest in a clause at most.
108
108
  - Each sentence is bound by the rules in "The form that your answer takes" that govern an entry's `text`: the opening verb, the unwritten subject, the plain verb, the backticked artifact, and the claim no stronger than what the change delivers.
109
109
 
110
110
  ## The form that your answer takes
@@ -126,7 +126,7 @@ These fix what an entry contains and how its `text` is written. None of them ran
126
126
  - `breaking` is `true` when the commit log marks the change breaking: a `!` on a commit subject's type, or a `BREAKING CHANGE:` footer in a commit body. It is `false` otherwise, and the diff is not evidence for it.
127
127
  - An entry that breaks a consumer, or that drops or deprecates published surface, declares a `migration`: one sentence addressed to the consumer, to which the subject test does not apply. Every other entry omits the key.
128
128
  - A `migration` names in the imperative the edit that the consumer makes. A sentence describing the resulting state is not an edit.
129
- - A migration also names any trap present in the replacement and not in the old path, such as a filter that the predecessor did not need or an exception that the replacement throws where the predecessor returned. Such a trap appears nowhere in the diff, so nothing else reveals it.
129
+ - A migration also names any trap present in the replacement and not in the old path, such as a filter that the predecessor did not need or an exception that the replacement throws in a case in which the predecessor returned. Such a trap appears nowhere in the diff, so nothing else reveals it.
130
130
  - A migration states the edit and the trap and stops there, rather than working through an example for each call shape. One that overruns that bound links the package's versioned upgrade guide when the package has one.
131
131
 
132
132
  Do not go looking for the lede doctrine, and do not work from a remembered rule list. The doctrine is written for the author and the auditor who read your draft. Reading rules before you write turns the question into a checklist, and a checklist is answered by including everything it does not forbid.
@@ -137,9 +137,13 @@ A dispatch with a `rejection` scalar is a redispatch: An earlier draft failed, a
137
137
 
138
138
  A `rejected` fence comes with it, listing one per line the passages that failed, copied from that draft. A passage is one entry's `text`, one entry's `migration`, or the whole lede. Revise those passages and nothing else. What the fence leaves out passed; the caller keeps it and puts your replacements back in their places, so this pass cannot change it.
139
139
 
140
+ An entry's `text` arrives as `{type}: {passage}`, where `{type}` is a key in the taxonomy; the lede and a `migration` arrive bare. A type supplied for a passage overrides the type implied by the commit log: The caller audited it against the diff, so write the replacement in the form that "What your type must state" gives the supplied type. Return the replacement without the type.
141
+
142
+ - **`type-mismatch`**: The passage was written in the form of a type other than the one supplied, such as a `fix` entry's opening on an entry typed `feat`. Rewrite it in the supplied type's form.
140
143
  - **`voice`**: A figurative verb or an invented term stood in for the plain one. Name each act with the plainest verb that fits it.
144
+ - **`writing-rule`**: A detector reported a site in the passage, and the caller confirmed that it breaks a rule in your plain-speech or writing guidance. Reread each passage against those rules and restate it.
141
145
  - **`subject`**: A passage used a verb that the pull request does not perform. Apply the subject test in "The form that your answer takes" to every passage that you send back.
142
- - **`unsupported-claim`**: A sentence claimed more than the change supports. Restate the passage within what the commit log and the diff show. Returning nothing for it is not the repair: A return short of one replacement per passage cannot be placed.
146
+ - **`unsupported-claim`**: A sentence claimed more than the change supports. Restate the passage within what the diff shows. Returning nothing for it is not the repair: A return short of one replacement per passage cannot be placed.
143
147
  - **`unmatched-return`**: The return contained a different number of passages than the fence sent, so the caller could place none of them. Return exactly one replacement per passage, in the order the fence listed them.
144
148
 
145
149
  ## What you return