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
@@ -14,15 +14,16 @@ For assertion recall (the canonical knowledge-base notes), use `kb-retrieve` ins
14
14
 
15
15
  ## Arguments
16
16
 
17
- | Argument | Description | Required |
18
- | -------------- | --------------------------------------------------------------------------------- | -------- |
19
- | `<query>` | The free-text search query. All non-flag tokens are joined into the query string. | Yes |
20
- | `--all-kbs` | Widen the search to every registered knowledge base, not just the default scope. | No |
21
- | `--min-impact` | Keep only events rated at or above the given level; unrated events are dropped. | No |
22
- | `--store` | Scope the search to a single registered knowledge base by name (alias: `--kb`). | No |
23
- | `--tag` | Keep only events with this tag (canonical or alias form), case-insensitively. | No |
17
+ | Argument | Description | Required |
18
+ | --------------- | ------------------------------------------------------------------------------------------------- | -------- |
19
+ | `<query>` | The free-text search query. All non-flag tokens are joined into the query string. | Yes |
20
+ | `--all-kbs` | Widen the search to every registered knowledge base, not just the default scope. | No |
21
+ | `--exclude-tag` | Drop events with any of these comma-separated tags (canonical or alias form), case-insensitively. | No |
22
+ | `--min-impact` | Keep only events rated at or above the given level; unrated events are dropped. | No |
23
+ | `--store` | Scope the search to a single registered knowledge base by name (alias: `--kb`). | No |
24
+ | `--tag` | Keep only events with this tag (canonical or alias form), case-insensitively. | No |
24
25
 
25
- A value-bearing flag accepts both `--tag fix` and `--tag=fix`. `--min-impact` takes one of the impact levels, ordered `low` < `medium` < `high` < `critical`; an absent or out-of-range value is rejected with a usage message.
26
+ A value-bearing flag accepts both `--tag fix` and `--tag=fix`. A repeated `--exclude-tag` adds to the list, and an empty value or an empty list entry is rejected with a usage message. `--min-impact` takes one of the impact levels, ordered `low` < `medium` < `high` < `critical`; an absent or out-of-range value is rejected with a usage message.
26
27
 
27
28
  ### Scope
28
29
 
@@ -32,6 +33,8 @@ By default the helper searches up to two knowledge bases: the one discovered by
32
33
 
33
34
  Within each knowledge base, recall is limited to the notes declared by the store, the files matching its configured `targets`/`exclude` (the same note set that `kb check` enforces). Events are stored under `content/events/`.
34
35
 
36
+ <!-- include: ../../_partials/kb-standard-tags.md / -->
37
+
35
38
  ## Runtime dependencies
36
39
 
37
40
  - **`node` ≥ 24**: The bundled helper inherits the Node version floor of `@williamthorsen/kb`.
@@ -44,7 +47,13 @@ Within each knowledge base, recall is limited to the notes declared by the store
44
47
  Invoke the co-located bundled helper with `node`, passing the query and any flags through verbatim:
45
48
 
46
49
  ```bash
47
- node {harness_home_dir}/skills/kb-retrieve-events/kb-retrieve-events.mjs <query> [--all-kbs] [--store <name>] [--tag <tag>] [--min-impact <level>]
50
+ node {harness_home_dir}/skills/kb-retrieve-events/kb-retrieve-events.mjs <query> [--all-kbs] [--store <name>] [--tag <tag>] [--exclude-tag <tag[,tag...]>] [--min-impact <level>]
51
+ ```
52
+
53
+ Read a curated pool, leaving out the events culled with a disposition tag:
54
+
55
+ ```bash
56
+ node {harness_home_dir}/skills/kb-retrieve-events/kb-retrieve-events.mjs "flaky timer" --store <name> --exclude-tag obsolete,deferred
48
57
  ```
49
58
 
50
59
  Triage the most consequential events with an impact floor:
@@ -82,7 +91,7 @@ When the helper returns a `diagnostic` without any candidates, report the empty
82
91
  - `store "<name>" is not registered in kb.yaml`: The named `--store` did not match any registry entry.
83
92
  - `registry invalid: …`: The only configured `kb.yaml` registry failed to load; this is a setup problem to fix, not a missing-events outcome.
84
93
  - `the query did not match any notes`: The knowledge bases were searched but nothing matched; suggest broadening the query or adding `--all-kbs`.
85
- - `all matches were filtered out`: Matches were found but every one was excluded by `--tag`; suggest dropping or loosening the filter.
94
+ - `all matches were filtered out`: Matches were found but every one was excluded by `--tag` or `--exclude-tag`; suggest dropping or loosening the filter.
86
95
  - `all matches were below the --min-impact threshold of <level>`: Events matched, but every one was rated below the `--min-impact` floor or was unrated; suggest lowering or dropping the filter.
87
96
  - `matches were found but none are events; use kb-retrieve for assertion recall`: The query matched only non-event records; the reader likely wants `kb-retrieve`.
88
97