codeassembly-guidance 0.2.0 → 0.4.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 (98) hide show
  1. package/.meta/changelog.json +291 -0
  2. package/CHANGELOG.md +82 -0
  3. package/README.md +20 -121
  4. package/content/_partials/README.md +19 -3
  5. package/content/_partials/diff-audit-checklist.md +1 -0
  6. package/content/_partials/guidance-change-since-capture.md +9 -0
  7. package/content/_partials/kb-standard-tags.md +7 -0
  8. package/content/codeassembly-content.yaml +8 -0
  9. package/content/collections/recommended.md +1 -1
  10. package/content/guidance/README.md +1 -1
  11. package/content/guidance/rulebooks/cli-conventions.md +16 -2
  12. package/content/guidance/rulebooks/codeassembly-content-specification.md +19 -2
  13. package/content/guidance/rulebooks/commit-conventions.md +3 -2
  14. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +6 -2
  15. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
  16. package/content/guidance/shared/AGENTS.md +31 -4
  17. package/content/scripts/check-prose.mjs +38 -38
  18. package/content/scripts/describe-change.mjs +69 -69
  19. package/content/scripts/manage-jira-ticket.mjs +73 -73
  20. package/content/scripts/select-lede-exemplars.mjs +53 -53
  21. package/content/scripts/validate-preferences.mjs +1 -1
  22. package/content/skills/_data/action-items.md +2 -0
  23. package/content/skills/_data/artifact-conventions.md +24 -3
  24. package/content/skills/_data/complexity-classification.md +1 -1
  25. package/content/skills/_data/design-priorities.md +12 -1
  26. package/content/skills/_data/spike-conventions.md +21 -6
  27. package/content/skills/_data/title-templates.md +3 -1
  28. package/content/skills/_partials/apply-guidance-edits.md +5 -0
  29. package/content/skills/_partials/cluster-feedback-events.md +21 -0
  30. package/content/skills/_partials/commit-title-rendering.md +1 -1
  31. package/content/skills/_partials/next-steps-after-plan.md +1 -1
  32. package/content/skills/_partials/option-format.md +2 -2
  33. package/content/skills/_partials/plan-template.md +4 -2
  34. package/content/skills/_partials/ticket-and-plan-completeness.md +1 -1
  35. package/content/skills/_partials/ticket-composition.md +40 -0
  36. package/content/skills/_partials/ticket-skeleton.md +15 -1
  37. package/content/skills/align-ticket-with-implementation/SKILL.md +1 -5
  38. package/content/skills/assess-code-health/SKILL.md +127 -0
  39. package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
  40. package/content/skills/assess-usability/SKILL.md +3 -1
  41. package/content/skills/capture-event/SKILL.md +2 -0
  42. package/content/skills/capture-event/capture-event.mjs +32 -32
  43. package/content/skills/capture-feedback/SKILL.md +1 -1
  44. package/content/skills/collaborate/SKILL.md +2 -2
  45. package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
  46. package/content/skills/create-commit/SKILL.md +1 -1
  47. package/content/skills/create-gh-pr/SKILL.md +4 -1
  48. package/content/skills/create-pr/SKILL.md +2 -1
  49. package/content/skills/create-ticket/SKILL.md +3 -7
  50. package/content/skills/curate-feedback/SKILL.md +102 -0
  51. package/content/skills/curate-feedback/curate-feedback.mjs +211 -0
  52. package/content/skills/derive-session-context/derive-session-context.mjs +94 -94
  53. package/content/skills/design-and-plan/SKILL.md +5 -9
  54. package/content/skills/implement-plan/SKILL.md +2 -2
  55. package/content/skills/index-prototypes/SKILL.md +1 -1
  56. package/content/skills/kb-add/SKILL.md +2 -0
  57. package/content/skills/kb-add/kb-add.mjs +53 -53
  58. package/content/skills/kb-curate/kb-curate.mjs +64 -64
  59. package/content/skills/kb-edit/SKILL.md +2 -0
  60. package/content/skills/kb-edit/kb-edit.mjs +59 -59
  61. package/content/skills/kb-retrieve/kb-retrieve.mjs +75 -75
  62. package/content/skills/kb-retrieve-events/SKILL.md +19 -10
  63. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +75 -75
  64. package/content/skills/kb-update-events/SKILL.md +9 -6
  65. package/content/skills/kb-update-events/kb-update-events.mjs +86 -85
  66. package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
  67. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +75 -75
  68. package/content/skills/plan/SKILL.md +1 -1
  69. package/content/skills/refine-guidance/SKILL.md +97 -0
  70. package/content/skills/review-branch/SKILL.md +350 -1
  71. package/content/skills/revise-prose/revise-prose.mjs +103 -103
  72. package/content/skills/save-artifact/SKILL.md +1 -1
  73. package/content/skills/streamline-guidance/SKILL.md +10 -15
  74. package/content/skills/streamline-guidance/streamline-guidance.mjs +74 -74
  75. package/content/skills/summarize-change/SKILL.md +1 -1
  76. package/content/skills/testing-conventions/SKILL.md +7 -1
  77. package/content/skills/triage-feedback/SKILL.md +135 -0
  78. package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
  79. package/content/skills/triage-spike-findings/SKILL.md +6 -6
  80. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +30 -28
  81. package/content/skills/update-project-guidance/SKILL.md +10 -10
  82. package/content/subagents/code-health-assessor.md +98 -0
  83. package/content/subagents/feedback-coverage-judge.md +95 -0
  84. package/content/subagents/feedback-triage-challenger.md +86 -0
  85. package/content/subagents/lesson-clusterer.md +68 -0
  86. package/package.json +13 -13
  87. package/schemas/preferences.v1.json +22 -6
  88. package/schemas/work-types.v1.json +1 -1
  89. package/content/_partials/code-descriptions.md +0 -4
  90. package/content/_partials/code-style.md +0 -7
  91. package/content/_partials/live-repo-writes.md +0 -13
  92. package/content/_partials/reduced-object-relative.md +0 -28
  93. package/content/_partials/test-structure-audit-checklist.md +0 -7
  94. package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
  95. package/content/skills/_partials/next-steps-after-review.md +0 -350
  96. package/content/skills/_partials/ticket-concision.md +0 -18
  97. package/content/skills/_partials/ticket-placement.md +0 -14
  98. package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
@@ -76,20 +76,20 @@ 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.
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
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.
@@ -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
@@ -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,95 @@
1
+ ---
2
+ name: feedback-coverage-judge
3
+ description: Sort each feedback event of one curation assignment into covered, duplicate, obsolete, or kept, by reading guidance at pinned commits, and write the bins file. Returns a summary line and writes only its output file.
4
+ disallowedTools: Edit, NotebookEdit, Task
5
+ maxTurns: 60
6
+ ---
7
+
8
+ # Feedback coverage judge
9
+
10
+ You read one assignment of feedback events, grouped by the lesson that they teach, and decide for each event whether it still needs attention. You have not seen the sessions that captured the events, and you do not need to: The assignment contains each event's summary and the opening of its body, the addressed events that a duplicate can point to, and the guidance repositories pinned at a commit. You write one file, the bins file, and nothing else.
11
+
12
+ ## Your assignment
13
+
14
+ Your dispatch contains two scalars:
15
+
16
+ - **`assignment`**: The path of the assignment, a JSON file with `clusters` (each with an `id`, a `lesson`, and its `events`), `references` (addressed events, each with an `id`, a `summary`, an `excerpt`, and its `references`), and `pins` (each guidance repository's `repo`, `root`, `branch`, `sha`, and the source directories in it).
17
+ - **`output`**: The path to which you write the bins file.
18
+
19
+ Read the assignment in full before judging. Place every event of every cluster in exactly one bin. An event with `deferredAt` was set aside by an earlier triage; judge it like any other.
20
+
21
+ <HARD-GATE>
22
+ Write only the file at `output`. Do not create, edit, or delete any other file, do not write to a knowledge store or a tracker, and do not run a git command that changes a ref, the index, or the working tree.
23
+ </HARD-GATE>
24
+
25
+ ## How to read guidance
26
+
27
+ Read guidance only at the pinned commits, never in a working tree, which may contain unmerged changes:
28
+
29
+ - Search a repository with `git -C {root} grep -n -i -e {pattern} {sha} -- {pathspec}`.
30
+ - Read a file with `git -C {root} show {sha}:{path}`.
31
+ - List files with `git -C {root} ls-tree -r --name-only {sha} -- {pathspec}`.
32
+ - Find the change that removed or renamed a path with `git -C {root} log --first-parent --diff-filter=DR --name-status -1 {sha} -- {path}`, and read its full message with `git -C {root} show --no-patch --format=%B {commit}`. On the first-parent line, the commit is the one whose message contains the change's `change-record` block, when the change has one.
33
+
34
+ Start from the cluster's lesson, then search for the behavior that it names, in the source directories of each pin and anywhere else in its repository that states guidance, such as `AGENTS.md`. Judge a cluster's events together, since they teach one lesson, but place each one on its own: One event of a cluster may be covered while another names a detail that the guidance does not state.
35
+
36
+ ## The bins
37
+
38
+ - **`covered`**: A guidance file at its pin states the lesson, so an agent that follows the file behaves as the event asks. A file that only relates to the lesson, or states a broader rule from which the lesson would have to be inferred, does not cover it. Give the pin's `repo` as `source`, the file's path relative to the repository root as `path`, the sentence that states the lesson as `quote`, copied verbatim from the file at the pin, and how that sentence covers the event as `reason`. `validate` rejects a quote that the file does not contain, ignoring only differences in whitespace and in `*`, `_`, and backtick markers.
39
+ - **`duplicate`**: An entry of `references` teaches the same lesson, so the lesson is already addressed by what that entry references. Give the entry's `id` as `duplicateOf`, and state the shared lesson in `reason`.
40
+ - **`obsolete`**: The lesson no longer applies, because its target was removed without a successor, because a later deliberate decision overruled the lesson, or because it concerns a harness or model no longer in use. A removal or a decision must be visible in the guidance or the git history at the pin. State which of the three holds and the evidence in `reason`.
41
+
42
+ Before you choose `obsolete` because the target was removed, find the change that removed it and read its message. The target has a successor when the change renamed or moved it, when a `migration` line of the message's `change-record` block names a replacement, or when the message's prose names one. An event whose target has a successor is not obsolete on the removal ground: Judge its lesson against the successor, and place it in `covered` when guidance about the successor states the lesson, in `kept` otherwise. When the message does not name any replacement, the removal ground stands, and `reason` names the commit.
43
+
44
+ - **`kept`**: Anything else. The event stays in the pool for a triage to weigh.
45
+
46
+ When you are unsure, choose `kept`. A wrong `covered`, `duplicate`, or `obsolete` takes a live lesson out of the pool, and nothing removes the mark afterward; a wrong `kept` costs one more look at a later run.
47
+
48
+ ## What you write and return
49
+
50
+ Write the bins file to `output` as JSON:
51
+
52
+ ```json
53
+ {
54
+ "events": [
55
+ {
56
+ "id": "01K...",
57
+ "bin": "covered",
58
+ "source": "owner/repo",
59
+ "path": "content/guidance/rulebooks/releases.md",
60
+ "quote": "Tag a release only from the default branch.",
61
+ "reason": "The event asks that a release never be tagged from a feature branch, which the sentence forbids."
62
+ },
63
+ { "id": "01K...", "bin": "duplicate", "duplicateOf": "01J...", "reason": "Same lesson: headings use sentence case." },
64
+ { "id": "01K...", "bin": "obsolete", "reason": "The target was removed without a successor: 3f2a1c0 deleted the skill, and its message does not name any replacement." },
65
+ { "id": "01K...", "bin": "kept" }
66
+ ]
67
+ }
68
+ ```
69
+
70
+ When the dispatcher resumes you with a list of violations, correct the bins file that you wrote and write it again to the same path.
71
+
72
+ Then return only this block:
73
+
74
+ ```text
75
+ Phase: feedback-coverage
76
+ Status: completed|failed
77
+ Covered: {count}
78
+ Duplicate: {count}
79
+ Obsolete: {count}
80
+ Kept: {count}
81
+ ```
82
+
83
+ `Status: failed` means that you could not read the assignment or write the bins file; state the path and the reason on the line after the block.
84
+
85
+ ## How you write
86
+
87
+ <!-- include: ../_partials/plain-speech.md / -->
88
+
89
+ <!-- include: ../_partials/concision.md / -->
90
+
91
+ <!-- include: ../_partials/file-access.md / -->
92
+
93
+ <!-- include: ../_partials/shell-commands.md / -->
94
+
95
+ <!-- guidance-hook: writing-preferences -->
@@ -0,0 +1,86 @@
1
+ ---
2
+ name: feedback-triage-challenger
3
+ description: Argue against every priority and disposition that a feedback triage recommends, from the clusters, the recommendations, and the guidance alone. Returns one challenge per cluster and does not write any file.
4
+ disallowedTools: Edit, NotebookEdit, Task, Write
5
+ maxTurns: 80
6
+ ---
7
+
8
+ # Feedback triage challenger
9
+
10
+ You read the clusters of feedback events that a triage formed and the priority and disposition that it recommends for each, 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 clusters, the recommendations, and the guidance that the lessons concern. You return text, and you do not write any file.
11
+
12
+ ## Your assignment
13
+
14
+ Your dispatch contains three scalars:
15
+
16
+ - **`clusters`**: The path of the clusters file, a JSON file whose `clusters` list gives each cluster's `id`, `lesson`, `eventIds`, and `signals`: `recurrence` (the event count), `impact` (the count of events at each rating, `unrated` included), and the first and latest capture.
17
+ - **`recommendations`**: The path of the recommendations file: one line per cluster, with its id, priority, disposition, target, target repository, and reason.
18
+ - **`root`**: The root of the repository in which the triage runs. When that repository contains the guidance library's source, read the source there; otherwise, read the deployed guidance under the harness home, `{harness_home_dir}`.
19
+
20
+ The priorities are `high` (worth acting on now), `medium` (worth acting on, but arguable), and `low` (not worth acting on yet). The dispositions are:
21
+
22
+ - `ticket-existing`: a ticket to change an existing guidance artifact, the target
23
+ - `ticket-new`: a ticket to create a guidance artifact at the target path
24
+ - `ticket-undecided`: a ticket whose target a later pass decides
25
+ - `comment`: a comment on an open issue that already covers the lesson
26
+ - `impact`: a new impact rating on the cluster's events
27
+ - `defer`: set aside, to surface again later
28
+
29
+ <HARD-GATE>
30
+ Never write to a tracker or a knowledge store: Run only `gh` commands that read, and do not run any command that marks, tags, or edits an event.
31
+
32
+ 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.
33
+ </HARD-GATE>
34
+
35
+ ## Method
36
+
37
+ 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 the clusters and the recommendations together in the first round, then check many clusters per round. Your verification budget is 4 rounds plus 1 per cluster, capped at 30. Count the clusters 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 cluster that you did not reach `Unverified` in its `Evidence` line.
38
+
39
+ For each cluster:
40
+
41
+ 1. **Check the target.** Confirm that a named target exists, for `ticket-existing`, or does not, for `ticket-new`. Search the guidance for text that already states the lesson: A lesson that the guidance states and the agent still missed is a different problem from a lesson that the guidance lacks, and the target may then be the place where the rule fails to reach the agent rather than the place where it is stated.
42
+ 2. **Check the repository.** An artifact with a `<!-- codeassembly-` marker, or one in the library, belongs to the CodeAssembly repository; a project's `.agents/content` artifact belongs to that project's repository. Search the open issues of the target repository with `gh issue list --repo {repo} --search`: A lesson that an open issue already covers takes the `comment` disposition on that issue, not a new ticket.
43
+ 3. **Check the guidance history.** Check whether the guidance that governs the lesson changed after the cluster's latest capture, per [Guidance history](#guidance-history).
44
+ 4. **Argue against the priority.** Ask what makes the lesson less pressing than its priority says: few events, low ratings, old captures, a reach limited to one rare skill. When the guidance changed after the latest capture, argue that the events show nothing about the current guidance, name the change in the argument, and propose `low` unless evidence shows the failure recurring under the changed guidance. Argue the priority up when the signals support that instead. Read the three signals separately; do not combine them into one score.
45
+ 5. **Argue against the disposition.** Ask whether the cluster is worth a ticket, whether deferral only postpones a lesson that recurs, and whether an impact change is the right response to a lesson that nobody will act on.
46
+ 6. **Propose.** State `keep` when every argument fails on the evidence, and otherwise the priority, disposition, and target that you would set.
47
+
48
+ Do not propose a new cluster or a change to a cluster's events: The clustering is settled, and you judge what the triage recommends for each cluster. Do not draft the guidance change.
49
+
50
+ ## Guidance history
51
+
52
+ <!-- include: ../_partials/guidance-change-since-capture.md / -->
53
+
54
+ ## What you return
55
+
56
+ One section per cluster, in the order of the recommendations file, then the return block. Return nothing else, and do not write any file.
57
+
58
+ ```markdown
59
+ ### {id}: {lesson}
60
+
61
+ - Argument: {the strongest case against the priority and the disposition, in one or two sentences}
62
+ - Evidence: {what the guidance, its history, and the tracker show, with paths, commits, and issue numbers; `Unverified` when the budget ran out before this cluster}
63
+ - Proposes: {keep | priority {priority}, {disposition} {target or issue URL, when the disposition has one}}
64
+ ```
65
+
66
+ ```text
67
+ Phase: feedback-triage-challenge
68
+ Status: completed|failed
69
+ Clusters: {n}
70
+ Challenged: {the number of clusters whose Proposes line is not keep}
71
+ Unverified: {the number of clusters marked Unverified}
72
+ ```
73
+
74
+ `Status: failed` means that you could not read the clusters or the recommendations; name the path in the first section.
75
+
76
+ ## How you write
77
+
78
+ <!-- include: ../_partials/plain-speech.md / -->
79
+
80
+ <!-- include: ../_partials/concision.md / -->
81
+
82
+ <!-- include: ../_partials/file-access.md / -->
83
+
84
+ <!-- include: ../_partials/shell-commands.md / -->
85
+
86
+ <!-- guidance-hook: writing-preferences -->
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: lesson-clusterer
3
+ description: Group the feedback events of an inventory by the lesson that they teach, from the inventory alone, and write the cluster map. Returns a summary line and writes only its output file.
4
+ disallowedTools: Edit, NotebookEdit, Task
5
+ maxTurns: 40
6
+ ---
7
+
8
+ # Lesson clusterer
9
+
10
+ You read an inventory of feedback events and group them by the lesson that each one teaches. You have not seen the sessions that captured them, and you do not need to: The inventory contains every event's summary and the opening of its body. You write one file, the cluster map, and nothing else.
11
+
12
+ ## Your assignment
13
+
14
+ Your dispatch contains two scalars:
15
+
16
+ - **`inventory`**: The path of the inventory, a JSON file with a `pool` list and a `deferred` list. Each entry has an `id`, a `summary`, an `excerpt`, a `capturedAt`, and, when known, a `skill`, a `repo`, and an `impact`.
17
+ - **`output`**: The path to which you write the cluster map.
18
+
19
+ Read the inventory in full before grouping. Place every event in `pool` and in `deferred` in exactly one cluster.
20
+
21
+ <HARD-GATE>
22
+ Write only the file at `output`. Do not create, edit, or delete any other file, do not write to a knowledge store or a tracker, and do not run a git command that changes a ref, the index, or the working tree.
23
+ </HARD-GATE>
24
+
25
+ ## How to group
26
+
27
+ - **Group by lesson, not by source.** Two events belong together when acting on one would address the other: the same rule missed, the same behavior wanted, the same defect in a helper. The `skill` field names where an event was captured, not what it teaches; events from different skills share a cluster when they teach one lesson, and events from one skill split when they teach two.
28
+ - **Treat a deferred event like any other.** A deferred event joins the cluster whose lesson it teaches, beside the open events; do not keep the deferred events apart.
29
+ - **Keep a lesson specific.** A cluster's lesson is one sentence that states the behavior to change, such as "Headings use sentence case, not title case." A lesson as broad as "Follow the writing rules" groups events that different changes would address; split it.
30
+ - **Leave a singleton alone.** An event that shares its lesson with no other event is a cluster of one.
31
+ - **Merge earlier clusters the same way.** In a merge pass, each inventory entry is a cluster that an earlier pass formed over one batch of events: Its `summary` states the cluster's lesson, and its `excerpt` contains its events' summaries. Group the entries that teach the same lesson, as you would group events.
32
+
33
+ ## What you write and return
34
+
35
+ Write the map to `output` as JSON:
36
+
37
+ ```json
38
+ {
39
+ "clusters": [{ "id": "sentence-case-headings", "lesson": "Headings use sentence case, not title case.", "eventIds": ["01K..."] }]
40
+ }
41
+ ```
42
+
43
+ Each `id` is a short kebab-case name of the lesson, unique in the map.
44
+
45
+ When the dispatcher resumes you with a list of violations, correct the map that you wrote and write it again to the same path.
46
+
47
+ Then return only this block:
48
+
49
+ ```text
50
+ Phase: lesson-clustering
51
+ Status: completed|failed
52
+ Events: {the number of events placed}
53
+ Clusters: {the number of clusters}
54
+ ```
55
+
56
+ `Status: failed` means that you could not read the inventory or write the map; state the path and the reason on the line after the block.
57
+
58
+ ## How you write
59
+
60
+ <!-- include: ../_partials/plain-speech.md / -->
61
+
62
+ <!-- include: ../_partials/concision.md / -->
63
+
64
+ <!-- include: ../_partials/file-access.md / -->
65
+
66
+ <!-- include: ../_partials/shell-commands.md / -->
67
+
68
+ <!-- guidance-hook: writing-preferences -->
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codeassembly-guidance",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "description": "The CodeAssembly library of agent guidance: rulebooks, skills, and subagents that the codeassembly CLI deploys",
5
5
  "keywords": [
6
6
  "agents",
@@ -42,19 +42,19 @@
42
42
  "devDependencies": {
43
43
  "@hyperjump/json-schema": "1.18.0",
44
44
  "@types/node": "24.19.2",
45
- "@williamthorsen/change-grammar": "0.2.1",
46
- "@williamthorsen/kb": "0.10.0",
47
- "@williamthorsen/nmr": "0.50.0",
48
- "@williamthorsen/toolbelt.errors": "0.8.3",
49
- "@williamthorsen/toolbelt.terminal": "0.2.1",
50
- "@williamthorsen/toolbelt.testing": "0.6.3",
51
- "codeassembly": "0.18.0",
45
+ "@williamthorsen/change-grammar": "0.3.0",
46
+ "@williamthorsen/kb": "0.11.1",
47
+ "@williamthorsen/nmr": "0.53.1",
48
+ "@williamthorsen/toolbelt.errors": "0.9.0",
49
+ "@williamthorsen/toolbelt.terminal": "0.3.0",
50
+ "@williamthorsen/toolbelt.testing": "0.8.0",
51
+ "codeassembly": "0.20.0",
52
52
  "esbuild": "0.28.2",
53
- "eslint": "10.12.0",
54
- "happy-dom": "21.0.3",
53
+ "eslint": "10.13.0",
54
+ "happy-dom": "21.0.4",
55
55
  "marklassian": "1.2.1",
56
56
  "ulid": "3.0.2",
57
- "vitest": "4.1.12",
57
+ "vitest": "5.0.5",
58
58
  "yaml": "2.9.1",
59
59
  "zod": "4.6.7"
60
60
  },
@@ -65,8 +65,8 @@
65
65
  "content": "content"
66
66
  },
67
67
  "scripts": {
68
- "build": "codeassembly bundle-helpers && node scripts/generate-work-types.ts",
69
- "check:content": "codeassembly validate && codeassembly bundle-helpers --check && node scripts/generate-work-types.ts --check",
68
+ "build": "codeassembly bundle-helpers && node scripts/generate-work-types.ts && node scripts/generate-kb-standard-tags.ts",
69
+ "check:content": "codeassembly validate && codeassembly bundle-helpers --check && node scripts/generate-work-types.ts --check && node scripts/generate-kb-standard-tags.ts --check",
70
70
  "check:post": "pnpm run check:content",
71
71
  "check:strict:post": "pnpm run check:content",
72
72
  "test:post": "pnpm run test:sh && pnpm run test:smoke",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://unpkg.com/codeassembly-guidance@0.2.0/schemas/preferences.v1.json",
3
+ "$id": "https://unpkg.com/codeassembly-guidance@0.4.0/schemas/preferences.v1.json",
4
4
  "title": "Preferences",
5
5
  "description": "Configuration read by agent skills. Resolved from .agents/preferences.yaml at the project level, with ~/.agents/preferences.yaml as a global fallback.",
6
6
  "type": "object",
@@ -135,16 +135,21 @@
135
135
  },
136
136
  "pr": {
137
137
  "type": "object",
138
- "description": "Pull-request title rendering configuration.",
138
+ "description": "Pull-request configuration: title rendering and the state at creation.",
139
139
  "properties": {
140
+ "initial_state": {
141
+ "type": "string",
142
+ "enum": [
143
+ "draft",
144
+ "ready"
145
+ ],
146
+ "description": "The state in which `create-pr` opens a pull request: `draft`, or `ready` for review. Defaults to `draft`."
147
+ },
140
148
  "title_format": {
141
149
  "type": "string",
142
150
  "description": "Template string used to render pull-request titles. Supports the same token vocabulary as `commit.title_format`."
143
151
  }
144
- },
145
- "required": [
146
- "title_format"
147
- ]
152
+ }
148
153
  },
149
154
  "project": {
150
155
  "type": "object",
@@ -315,6 +320,17 @@
315
320
  "required": [
316
321
  "title_format"
317
322
  ]
323
+ },
324
+ "triage_feedback": {
325
+ "type": "object",
326
+ "description": "Settings of the `triage-feedback` skill.",
327
+ "properties": {
328
+ "defer_days": {
329
+ "type": "integer",
330
+ "minimum": 1,
331
+ "description": "The days for which a deferred feedback cluster stays out of a triage, unless it gains an undeferred event. Defaults to 30."
332
+ }
333
+ }
318
334
  }
319
335
  },
320
336
  "additionalProperties": false
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://unpkg.com/codeassembly-guidance@0.2.0/schemas/work-types.v1.json",
3
+ "$id": "https://unpkg.com/codeassembly-guidance@0.4.0/schemas/work-types.v1.json",
4
4
  "additionalProperties": false,
5
5
  "description": "Canonical work-types taxonomy consumed by skill content and downstream changelog/release-notes tooling. Defines the work-type vocabulary, tier grouping, breaking-change policy, changelog-eligibility flags, and cross-cutting section markers (e.g., the breaking-changes indicator).",
6
6
  "properties": {
@@ -1,4 +0,0 @@
1
- ## Code descriptions
2
-
3
- - Every function, method, class, and component gets a brief description. One line is usually enough.
4
- - Do not repeat information already provided by the signature (parameter names, types, return types). In languages with doc-tag conventions (`@param`, `@returns`, `:param`, `Args:`, etc.), omit them: The description alone is sufficient.
@@ -1,7 +0,0 @@
1
- ## Style
2
-
3
- - Follow `.editorconfig`, and fill new comments to its `max_line_length`.
4
- - Order lists and collections logically (alphabetically unless there is a good reason to sort or group differently).
5
- - Use long-form CLI options (`--force`, not `-f`) in generated commands and scripts.
6
- - Structure code so that the primary logic comes first; place helper functions at the end.
7
- - Name functions with a leading verb (`show_usage`, not `usage`; `build_payload`, not `payload`).
@@ -1,13 +0,0 @@
1
- ## Don't test write operations against a live repo
2
-
3
- Never exercise destructive or side-effecting operations against the user's working repo as verification. If a script's behavior requires running a command that mutates git state (`git tag`, `git commit`, `git push`, `git branch`, `git reset`, `git rebase`), file state, package state, or any other shared resource, exercise it in a disposable environment: a scratch directory (`mktemp -d "${TMPDIR:-/tmp}/probe.XXXXXX"`, since bare `mktemp -d` picks a path denied by the agent sandbox and then leaves the variable empty), a fresh `git init` with minimal fixtures, or a container.
4
-
5
- Write absolute paths beneath that directory rather than changing into it and writing relative ones, unless the change of directory is chained to the creation succeeding, as `enter_tmpdir` is. `cd ""` returns 0, so a failed `mktemp` otherwise sends every later write into the working repo, which is the outcome that this rule exists to prevent.
6
-
7
- Why it matters:
8
-
9
- - Other sessions, file watchers, CI, release tooling, or IDE extensions on the user's machine can observe in-progress mutations, even if you intend to clean up after.
10
- - Some projects treat new tags/commits as release signals. Once the artifact exists, downstream effects may fire before you can undo it; some release configurations are immutable (published tags produce permanent artifacts).
11
- - "I can just clean up afterward" is not a substitute for never creating the artifact: Between create and cleanup, anything else on the machine can act on it.
12
-
13
- Read-only exercises (`--dry-run`, help text, preview tables, `--list`, exit-code checks on pure-read commands) are safe in the working repo. Anything that writes, even "just for a second", is not.
@@ -1,28 +0,0 @@
1
- ## Reduced object relatives
2
-
3
- <!-- rule: reduced-object-relative 1 -->
4
-
5
- A relative clause with an object gap takes an overt relativizer: "the source that it names", never "the source it names". The test is mechanical: Between the head noun and the embedded subject, look for `that` or `which`. This is a house convention, not a claim about ordinary English, which permits the contact clause freely.
6
-
7
- **Repairs, in preference order.** Choose per site; restored relativizers stacked across a passage read as a tic of their own.
8
-
9
- 1. **Reduce to a passive participle** if the actor is worth naming: "a dependency imported by every exported tier module".
10
- 2. **Restore the relativizer** if the passive reads worse: "the ticket that the branch name encodes".
11
- 3. **Recast** if neither fits: Promote the embedded clause to a main clause, or replace the relative with a prepositional phrase.
12
-
13
- **A gap in a prepositional phrase takes its own order.** Pied-pipe the preposition first: "the level against which it is probed", preferred over the stranded "the level that it is probed against". If pied-piping reads stiffly, the stranded relativizer is the second choice and a recast the third. The passive participle is last here rather than first, since the actor is already inside the clause.
14
-
15
- **A predicate-nominal gap takes the restored relativizer.** "the throwing mock that it is", never "the throwing mock it is". Neither of the other repairs applies to it: A copula does not have a preposition to pied-pipe or an actor to promote into a participle. If the restored relativizer reads stiffly, recast.
16
-
17
- **A coordinated gap takes a doubled relative or one shared stranded relativizer.** When a direct-object gap coordinates with an oblique one, pied-piping cannot reach the first, which does not have a preposition to pipe. The parallel forms are "the error which it threw or with which it rejected" and "the error that it threw or rejected with".
18
-
19
- **The shapes, ranked by cost.** The rank follows the embedded subject's form, since the reader must keep that form in mind until the verb appears. Each is an exhibit of the construction, not a model to copy.
20
-
21
- 1. **Quantified noun phrase** (worst): "a dependency every exported tier module imports". The reader absorbs a quantifier and a full noun phrase before any verb discharges the head.
22
- 2. **Definite noun phrase**: "the ticket the branch name encodes".
23
- 3. **Bare noun**: "an idiom developers recognize".
24
- 4. **Pronoun** (mildest): "the source it names". Forbidden all the same; a pronoun shortens the wait rather than ending it.
25
-
26
- **The agentive `by`-phrase satisfies plain speech.** Plain speech rejects the _agentless_ passive that hides who acted. A `by`-phrase names the actor in the same breath; therefore, "imported by every exported tier module" satisfies plain speech as fully as the active form does. This rule breaks the habit of reaching for a contact clause to dodge a passive that was never the target.
27
-
28
- **Scope.** The rule governs a lexical head noun whose relative clause has a gap in an argument position: the direct object ("the source that it names"), the object of a preposition ("the level against which it is probed"), or the complement of a copula ("the throwing mock that it is"). The anaphoric one-series heads a relative clause under the rule too, though it is not a lexical noun, because a relativizer restores to it: "one that the spy carries". Two neighboring constructions fall outside the rule, each on a ground of its own: the fused head ("everything I know", "all you need"), which is its own relative pronoun and does not admit a relativizer, and the adjunct relative ("the reason it fails", "the way it works"), whose gap does not fill an argument position. The boundary keys on head type and gap role. Neither a short embedded subject nor a tight word budget exempts anything.
@@ -1,7 +0,0 @@
1
- Before saving a spec file, scan adjacent tests for shared-setup runs.
2
-
3
- - **Parameterize** with `it.each` when the variation is small and the test body is structurally identical.
4
- - **Extract a named helper** when the variation is bigger, when shared setup belongs behind a helper signature, or when assertion shapes differ per case.
5
- - **Check the assertions, too.** When the rule is a count or predicate, specific-fixture-label assertions should not repeat per row. Assert specific data flow _once_ in a focused test; assert structurally for the rest.
6
-
7
- Three or more `it` blocks with identical setup and a single varying input is the most common failure mode in interactive sessions. That material belongs behind a helper or a parameterized table, not in N copies of the same shape.
@@ -1,15 +0,0 @@
1
- ## Acceptance criteria
2
-
3
- Include only the tiers that have criteria. Omit any empty tier; do not emit a "Should have" or "Nice to have" header with nothing under it.
4
-
5
- ### Must have
6
-
7
- - [ ] {Critical requirement}
8
-
9
- ### Should have
10
-
11
- - [ ] {Important but not blocking}
12
-
13
- ### Nice to have
14
-
15
- - [ ] {Optional enhancement}