codeassembly-guidance 0.6.0 → 0.7.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 (66) hide show
  1. package/.meta/changelog.json +185 -0
  2. package/CHANGELOG.md +45 -0
  3. package/README.md +29 -51
  4. package/content/_partials/kb-unsearched-private-stores.md +6 -0
  5. package/content/codeassembly-content.yaml +2 -0
  6. package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
  7. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -1
  8. package/content/guidance/shared/AGENTS.md +1 -1
  9. package/content/scripts/check-prose.mjs +1 -1
  10. package/content/scripts/describe-change.mjs +89 -89
  11. package/content/scripts/manage-jira-ticket.mjs +113 -113
  12. package/content/scripts/select-lede-exemplars.mjs +85 -85
  13. package/content/scripts/validate-preferences.mjs +38 -38
  14. package/content/skills/_data/project-stage.md +9 -5
  15. package/content/skills/_data/spike-conventions.md +9 -6
  16. package/content/skills/_partials/implementation-order-list.md +27 -0
  17. package/content/skills/_partials/next-steps-after-plan.md +2 -2
  18. package/content/skills/_partials/plan-template.md +2 -0
  19. package/content/skills/_partials/split-launch-prompts.md +1 -1
  20. package/content/skills/align-ticket-with-implementation/SKILL.md +1 -1
  21. package/content/skills/assess-code-health/SKILL.md +2 -2
  22. package/content/skills/assess-usability/SKILL.md +2 -2
  23. package/content/skills/capture-event/SKILL.md +20 -11
  24. package/content/skills/capture-event/capture-event.mjs +122 -122
  25. package/content/skills/capture-feedback/SKILL.md +2 -1
  26. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
  27. package/content/skills/create-pr/SKILL.md +11 -11
  28. package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
  29. package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
  30. package/content/skills/derive-session-context/derive-session-context.mjs +107 -107
  31. package/content/skills/design-and-plan/SKILL.md +4 -2
  32. package/content/skills/implement-plan/SKILL.md +3 -1
  33. package/content/skills/implementation-order/implementation-order.mjs +67 -0
  34. package/content/skills/investigate-spike/SKILL.md +1 -1
  35. package/content/skills/kb-add/SKILL.md +12 -3
  36. package/content/skills/kb-add/kb-add.mjs +88 -88
  37. package/content/skills/kb-curate/kb-curate.mjs +88 -88
  38. package/content/skills/kb-edit/kb-edit.mjs +90 -90
  39. package/content/skills/kb-retrieve/SKILL.md +8 -3
  40. package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
  41. package/content/skills/kb-retrieve-events/SKILL.md +8 -3
  42. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
  43. package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
  44. package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
  45. package/content/skills/list-implementation-order/SKILL.md +23 -0
  46. package/content/skills/merge-bb-pr/SKILL.md +31 -8
  47. package/content/skills/merge-gh-pr/SKILL.md +25 -12
  48. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
  49. package/content/skills/merge-pr/SKILL.md +55 -20
  50. package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
  51. package/content/skills/plan/SKILL.md +3 -1
  52. package/content/skills/prepare-prototype-brief/SKILL.md +3 -1
  53. package/content/skills/refine-plan/SKILL.md +2 -0
  54. package/content/skills/review-branch/SKILL.md +1 -1
  55. package/content/skills/review-criteria/SKILL.md +1 -1
  56. package/content/skills/revise-prose/revise-prose.mjs +111 -111
  57. package/content/skills/save-plan/SKILL.md +2 -0
  58. package/content/skills/streamline-guidance/streamline-guidance.mjs +76 -76
  59. package/content/skills/summarize-change/SKILL.md +17 -7
  60. package/content/skills/testing-conventions/SKILL.md +2 -2
  61. package/content/skills/triage-feedback/SKILL.md +4 -0
  62. package/content/skills/triage-spike-findings/SKILL.md +10 -5
  63. package/content/skills/wrap-up/SKILL.md +4 -0
  64. package/package.json +9 -9
  65. package/schemas/preferences.v1.json +74 -8
  66. package/schemas/work-types.v1.json +1 -1
@@ -64,11 +64,11 @@ Invoke the `{skill:assess-ticket}` skill with the resolved ticket source and mod
64
64
 
65
65
  ### Phase 2: Understand the task
66
66
 
67
- 1. **Explore project context:** Check relevant files, docs, recent commits to understand the affected area of the codebase. Read the project's declared stage from the manifest's `project_maturity`, `project_sensitivity`, and `project_audience` fields, which `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits.
67
+ 1. **Explore project context:** Check relevant files, docs, recent commits to understand the affected area of the codebase. Read the project's declared stage from the manifest's `project_maturity`, `project_sensitivity`, and `project_audience` fields, and the stages that its subdirectories declare from the `project_stages` field, which `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits.
68
68
 
69
69
  2. **Evaluate the ticket on its merits**: Apply the criteria in [ticket evaluation](../_data/ticket-evaluation.md). When evaluation reveals a divergence from the ticket as written, recommend a disposition, build the design on it, and present the divergence at the ticket checkpoint; raise it earlier only when the design cannot proceed without the answer. Divergence includes scope that should grow: By default, fold work that the problem requires into this change rather than into a follow-up (see [scope-and-deferral](../_data/scope-and-deferral.md)).
70
70
 
71
- 3. **Form the questions that the design turns on, and decide what the gate lets you decide.** The questions cover purpose and motivation, constraints and scope boundaries, and success criteria and edge cases. Answer each from the codebase, the ticket, and the [option format](#option-format) gate when you can, and record the answer as a decision taken, with its reason. Defer the asks that survive the gate to the ticket checkpoint in Phase 3; ask earlier only when the design cannot proceed without the answer, and prefer multiple choice when you do. Treat the declared stage as the premise of every security, availability, and infrastructure question, per [project stage](../_data/project-stage.md). Treat a step that a person must run on each machine as a defect of the design, per [who applies the change](../_data/design-priorities.md#who-applies-the-change): Prefer a design that the agent applies and verifies itself, and when the step stays, the ticket's `## Proposed solution` names the rung of that ladder that shapes it. Ask for each undeclared stage value: in this step when the design has such a question, since the answer decides it, and otherwise at the ticket checkpoint. The ticket's `## Context` states each premise that decided such a question, and the plan includes a task that declares each answered value.
71
+ 3. **Form the questions that the design turns on, and decide what the gate lets you decide.** The questions cover purpose and motivation, constraints and scope boundaries, and success criteria and edge cases. Answer each from the codebase, the ticket, and the [option format](#option-format) gate when you can, and record the answer as a decision taken, with its reason. Defer the asks that survive the gate to the ticket checkpoint in Phase 3; ask earlier only when the design cannot proceed without the answer, and prefer multiple choice when you do. Treat the stage that governs the work's paths as the premise of every security, availability, infrastructure, and verification question, per [project stage](../_data/project-stage.md). Treat a step that a person must run on each machine as a defect of the design, per [who applies the change](../_data/design-priorities.md#who-applies-the-change): Prefer a design that the agent applies and verifies itself, and when the step stays, the ticket's `## Proposed solution` names the rung of that ladder that shapes it. Ask for each undeclared stage value: in this step when the design has such a question, since the answer decides it, and otherwise at the ticket checkpoint. The ticket's `## Context` states each premise that decided such a question, and the plan includes a task that declares each answered value.
72
72
  - When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
73
73
 
74
74
  **Important:** Do not use `{tool:AskUserQuestion}` or any interactive selector (pop-up, arrow-key, structured-choice) for multiple-choice questions. Ask the question as plain text in the message body, with options as a numbered list.
@@ -191,3 +191,5 @@ Follow the options, output format, and recommendation rules in [next-steps optio
191
191
  <!-- include: ../_partials/next-steps-after-plan.md / -->
192
192
 
193
193
  <!-- include: ../_partials/option-format.md / -->
194
+
195
+ <!-- include: ../_partials/implementation-order-list.md / -->
@@ -49,7 +49,7 @@ The plan artifact is read-only. It is a record of what was decided at plan time,
49
49
 
50
50
  ## Fact routing
51
51
 
52
- The audience decides where a fact goes. A fact that the user acts on, such as a decision that is theirs or a divergence that they must weigh, belongs in the response. A fact that a reviewer acts on belongs in the commit body, the pull-request description, or a comment in the source. A fact needed by both goes in the artifact and may be summarized in the response; the artifact is never skipped.
52
+ The audience decides where a fact goes. A fact that the user acts on, such as a decision that is theirs or a divergence that they must weigh, belongs in the response. A fact that a reviewer acts on belongs in the commit body or a comment in the source; `summarize-change` adds a commit-body fact to the pull-request description's `## Notes for reviewers` when the fact passes that skill's reader test. A fact needed by both goes in the artifact and may be summarized in the response; the artifact is never skipped.
53
53
 
54
54
  The failure that this prevents is visible in the phrasing: Any wording that treats the reader as an intermediary, such as "worth a reviewer's attention", "flag this in review", or "mention that...", marks a fact that belongs in an artifact. When one is found after the artifact is written, amend the artifact rather than narrate the gap.
55
55
 
@@ -139,3 +139,5 @@ Never push, force-push, or delete a remote branch, never create a worktree, and
139
139
  <!-- include: ../_partials/split-launch-prompts.md / -->
140
140
 
141
141
  <!-- include: ../_partials/option-format.md / -->
142
+
143
+ <!-- include: ../_partials/implementation-order-list.md / -->