codeassembly-guidance 0.2.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 (88) hide show
  1. package/.meta/changelog.json +227 -0
  2. package/CHANGELOG.md +59 -0
  3. package/README.md +37 -121
  4. package/content/_partials/README.md +19 -3
  5. package/content/_partials/diff-audit-checklist.md +1 -0
  6. package/content/_partials/kb-standard-tags.md +7 -0
  7. package/content/codeassembly-content.yaml +6 -0
  8. package/content/collections/recommended.md +1 -1
  9. package/content/guidance/README.md +1 -1
  10. package/content/guidance/rulebooks/cli-conventions.md +16 -2
  11. package/content/guidance/rulebooks/codeassembly-content-specification.md +19 -2
  12. package/content/guidance/rulebooks/commit-conventions.md +3 -2
  13. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +6 -2
  14. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
  15. package/content/guidance/shared/AGENTS.md +31 -4
  16. package/content/scripts/check-prose.mjs +38 -38
  17. package/content/scripts/describe-change.mjs +69 -69
  18. package/content/scripts/manage-jira-ticket.mjs +73 -73
  19. package/content/scripts/validate-preferences.mjs +1 -1
  20. package/content/skills/_data/action-items.md +2 -0
  21. package/content/skills/_data/artifact-conventions.md +18 -2
  22. package/content/skills/_data/complexity-classification.md +1 -1
  23. package/content/skills/_data/design-priorities.md +12 -1
  24. package/content/skills/_data/spike-conventions.md +21 -6
  25. package/content/skills/_data/title-templates.md +3 -1
  26. package/content/skills/_partials/apply-guidance-edits.md +5 -0
  27. package/content/skills/_partials/commit-title-rendering.md +1 -1
  28. package/content/skills/_partials/next-steps-after-plan.md +1 -1
  29. package/content/skills/_partials/option-format.md +2 -2
  30. package/content/skills/_partials/plan-template.md +4 -2
  31. package/content/skills/_partials/ticket-and-plan-completeness.md +1 -1
  32. package/content/skills/_partials/ticket-composition.md +40 -0
  33. package/content/skills/_partials/ticket-skeleton.md +15 -1
  34. package/content/skills/align-ticket-with-implementation/SKILL.md +1 -5
  35. package/content/skills/assess-code-health/SKILL.md +127 -0
  36. package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
  37. package/content/skills/assess-usability/SKILL.md +3 -1
  38. package/content/skills/capture-event/SKILL.md +2 -0
  39. package/content/skills/capture-feedback/SKILL.md +1 -1
  40. package/content/skills/collaborate/SKILL.md +2 -2
  41. package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
  42. package/content/skills/create-commit/SKILL.md +1 -1
  43. package/content/skills/create-gh-pr/SKILL.md +4 -1
  44. package/content/skills/create-pr/SKILL.md +2 -1
  45. package/content/skills/create-ticket/SKILL.md +3 -7
  46. package/content/skills/derive-session-context/derive-session-context.mjs +94 -94
  47. package/content/skills/design-and-plan/SKILL.md +5 -9
  48. package/content/skills/implement-plan/SKILL.md +2 -2
  49. package/content/skills/index-prototypes/SKILL.md +1 -1
  50. package/content/skills/kb-add/SKILL.md +2 -0
  51. package/content/skills/kb-edit/SKILL.md +2 -0
  52. package/content/skills/kb-edit/kb-edit.mjs +24 -24
  53. package/content/skills/kb-retrieve/kb-retrieve.mjs +75 -75
  54. package/content/skills/kb-retrieve-events/SKILL.md +19 -10
  55. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +75 -75
  56. package/content/skills/kb-update-events/SKILL.md +9 -6
  57. package/content/skills/kb-update-events/kb-update-events.mjs +86 -85
  58. package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
  59. package/content/skills/plan/SKILL.md +1 -1
  60. package/content/skills/refine-guidance/SKILL.md +97 -0
  61. package/content/skills/review-branch/SKILL.md +350 -1
  62. package/content/skills/revise-prose/revise-prose.mjs +85 -85
  63. package/content/skills/save-artifact/SKILL.md +1 -1
  64. package/content/skills/streamline-guidance/SKILL.md +10 -15
  65. package/content/skills/streamline-guidance/streamline-guidance.mjs +73 -73
  66. package/content/skills/summarize-change/SKILL.md +1 -1
  67. package/content/skills/testing-conventions/SKILL.md +7 -1
  68. package/content/skills/triage-feedback/SKILL.md +150 -0
  69. package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
  70. package/content/skills/triage-spike-findings/SKILL.md +5 -5
  71. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +30 -28
  72. package/content/skills/update-project-guidance/SKILL.md +10 -10
  73. package/content/subagents/code-health-assessor.md +98 -0
  74. package/content/subagents/feedback-triage-challenger.md +81 -0
  75. package/content/subagents/lesson-clusterer.md +68 -0
  76. package/package.json +13 -13
  77. package/schemas/preferences.v1.json +22 -6
  78. package/schemas/work-types.v1.json +1 -1
  79. package/content/_partials/code-descriptions.md +0 -4
  80. package/content/_partials/code-style.md +0 -7
  81. package/content/_partials/live-repo-writes.md +0 -13
  82. package/content/_partials/reduced-object-relative.md +0 -28
  83. package/content/_partials/test-structure-audit-checklist.md +0 -7
  84. package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
  85. package/content/skills/_partials/next-steps-after-review.md +0 -350
  86. package/content/skills/_partials/ticket-concision.md +0 -18
  87. package/content/skills/_partials/ticket-placement.md +0 -14
  88. package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
@@ -50,7 +50,7 @@ Create the directory if needed.
50
50
 
51
51
  Read `artifact_paths` from the session-context manifest for category paths (chats, devlogs, plans). These are relative to the project directory: `{artifact_base_dir}/projects/{project_slug}/{category}/`.
52
52
 
53
- Devlogs and deferred-findings artifacts use their non-ticket category paths only as a fallback: When a ticket is in session context they are written as ticket-level artifacts under `tickets/{ticket_id}/` instead. See [artifact conventions](../_data/artifact-conventions.md#non-ticket-paths) for the dual-homing rule. For frontmatter shapes, see `create-devlog/SKILL.md` (devlogs) and the deferred-findings step in `wrap-up/SKILL.md` (deferred-findings).
53
+ Devlogs, deferred-findings, and feedback-triage artifacts use their non-ticket category paths only as a fallback: When a ticket is in session context they are written as ticket-level artifacts under `tickets/{ticket_id}/` instead. See [artifact conventions](../_data/artifact-conventions.md#non-ticket-paths) for the dual-homing rule. For frontmatter shapes, see `create-devlog/SKILL.md` (devlogs), the deferred-findings step in `wrap-up/SKILL.md` (deferred-findings), and step 8 of `triage-feedback/SKILL.md` (feedback-triage).
54
54
 
55
55
  Follow [artifact conventions](../_data/artifact-conventions.md).
56
56
 
@@ -46,7 +46,7 @@ At any level, in any file:
46
46
  - The part of a frontmatter `description` that says when to invoke the skill. The rest of a description is worth cutting, since the harness loads every description into the skill index of every session.
47
47
  - Text inside a generated region, which the next deployment rewrites.
48
48
 
49
- Do not edit any file outside the targets and their transitive files, except a rulebook `version`, a version pin, or a content hash that step 7 updates.
49
+ Do not edit any file outside the targets and their transitive files, except a rulebook `version`, a version pin, or a content hash that step 6 updates.
50
50
 
51
51
  ## Process
52
52
 
@@ -103,26 +103,21 @@ Drop every candidate that touches an output shape or its skill-local reinforceme
103
103
  - At any level, propose at most two cuts in transitive files, ranked the same way.
104
104
  - Otherwise, propose every remaining candidate.
105
105
 
106
- If nothing remains, report that the files do not have any cut to propose at this level, then continue at step 8.
106
+ If nothing remains, report that the files do not have any cut to propose at this level, then continue at step 7.
107
107
 
108
108
  ### 5. Present the cuts
109
109
 
110
110
  Present one numbered table per [Cut table](#cut-table), then ask which rows to apply and which to decline, in the form `apply 1, 3; decline 2`. A row named in neither list is deferred: You do nothing with it, and a later run may propose it again.
111
111
 
112
- ### 6. Apply
112
+ ### 6. Apply, bump versions, and run the quality gate
113
113
 
114
- Apply each row named to apply with {tool:Edit}, phrase to phrase. Stop at the first edit that does not match, and report which row diverged.
114
+ Skip this step if the user did not name any row to apply. The approved edits are the rows named to apply, and each is one cut.
115
115
 
116
- ### 7. Bump versions and run the quality gate
116
+ <!-- include: ../_partials/apply-guidance-edits.md / -->
117
117
 
118
- Skip this step if the run did not apply any row.
118
+ A `conservative` cut directs nothing, so it changes nothing that a rulebook asks.
119
119
 
120
- 1. Bump the `version` of each rulebook for which a cut changed what the rulebook asks: a rulebook that a cut edited, and a rulebook that includes an edited file. Find the second kind by searching the rulebooks for an include directive that names the edited file. A `conservative` cut directs nothing, so it changes nothing that a rulebook asks.
121
- 2. Run the project's quality gate as {skill:development-workflows} resolves it.
122
- - If it fails only on a version pin or content hash that records a file edited by this run, apply the remedy that its failure message names: Update the pin to the version bumped above, or update the pin alone if the cuts did not change what the rulebook asks.
123
- - If it fails on anything else that a cut caused, restore that cut's text, report the cut, and run the gate again. If the restored cut was the only cut to change what its rulebook asks, also restore that rulebook's `version`, and its pin if this step updated it.
124
-
125
- ### 8. Record the run
120
+ ### 7. Record the run
126
121
 
127
122
  Record what the run read and what the user declined, whether or not the run proposed or applied a cut: A run that proposes nothing has still reviewed the files. Pipe the fold to `record`, the only write path of `.agents/streamline-guidance.yaml`:
128
123
 
@@ -134,11 +129,11 @@ EOF
134
129
 
135
130
  `date` is today's ISO calendar date. `declined` lists each row that the user declined, its `phrase` as the text reads in the file, and is empty when the user declined none. `reviewed` names every target and every transitive file from step 1: A transitive file is read whole, so it was reviewed. `record` measures each reviewed file as it now stands, so the record states the size at which this run left it, the baseline for the growth that a later run reports.
136
131
 
137
- ### 9. Commit
132
+ ### 8. Commit
138
133
 
139
- Commit per {skill:create-commit}, staging only the edited guidance files, any pin or version that step 7 updated, and the record. The body names each applied cut by file, class, and the text removed or reworded; when the run applied none, the commit contains the record alone.
134
+ Commit per {skill:create-commit}, staging only the edited guidance files, any pin or version that step 6 updated, and the record. The body names each applied cut by file, class, and the text removed or reworded; when the run applied none, the commit contains the record alone.
140
135
 
141
- ### 10. Emit the summary
136
+ ### 9. Emit the summary
142
137
 
143
138
  Emit the summary per [Summary format](#summary-format). For the sizes after the run, run `resolve` again with the same paths; its `lastReview` now states this run, so take `Reviewed` and `Growth` from step 1.
144
139