codeassembly-guidance 0.5.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 (110) hide show
  1. package/.meta/changelog.json +491 -0
  2. package/CHANGELOG.md +118 -0
  3. package/README.md +33 -4
  4. package/content/_partials/finding-grades.md +4 -0
  5. package/content/_partials/kb-unsearched-private-stores.md +6 -0
  6. package/content/codeassembly-content.yaml +4 -0
  7. package/content/collections/recommended.md +5 -2
  8. package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
  9. package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
  10. package/content/guidance/rulebooks/cli-conventions.md +17 -2
  11. package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
  12. package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
  13. package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
  14. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  15. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
  16. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -1
  17. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
  18. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
  19. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
  20. package/content/guidance/shared/AGENTS.md +1 -1
  21. package/content/scripts/check-prose.mjs +1 -1
  22. package/content/scripts/describe-change.mjs +88 -88
  23. package/content/scripts/manage-jira-ticket.mjs +113 -113
  24. package/content/scripts/select-lede-exemplars.mjs +85 -85
  25. package/content/scripts/validate-preferences.mjs +38 -38
  26. package/content/skills/_data/action-items.md +2 -2
  27. package/content/skills/_data/artifact-conventions.md +20 -10
  28. package/content/skills/_data/concision.md +1 -1
  29. package/content/skills/_data/entry-points.md +37 -0
  30. package/content/skills/_data/project-stage.md +9 -5
  31. package/content/skills/_data/recommendation-gradient.md +6 -6
  32. package/content/skills/_data/spike-conventions.md +20 -7
  33. package/content/skills/_data/ticket-source-resolution.md +21 -4
  34. package/content/skills/_data/title-templates.md +4 -4
  35. package/content/skills/_partials/commit-title-rendering.md +2 -1
  36. package/content/skills/_partials/implementation-order-list.md +27 -0
  37. package/content/skills/_partials/next-steps-after-plan.md +6 -5
  38. package/content/skills/_partials/option-format.md +8 -8
  39. package/content/skills/_partials/plan-template.md +5 -1
  40. package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
  41. package/content/skills/_partials/split-launch-prompts.md +2 -2
  42. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  43. package/content/skills/align-ticket-with-implementation/SKILL.md +1 -1
  44. package/content/skills/analyze-performance/SKILL.md +102 -0
  45. package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
  46. package/content/skills/assess-code-health/SKILL.md +16 -14
  47. package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
  48. package/content/skills/assess-usability/SKILL.md +5 -3
  49. package/content/skills/capture-event/SKILL.md +20 -11
  50. package/content/skills/capture-event/capture-event.mjs +122 -122
  51. package/content/skills/capture-feedback/SKILL.md +2 -1
  52. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
  53. package/content/skills/convert-agent-prompt/SKILL.md +60 -0
  54. package/content/skills/create-commit/SKILL.md +10 -5
  55. package/content/skills/create-pr/SKILL.md +11 -11
  56. package/content/skills/create-ticket/SKILL.md +1 -0
  57. package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
  58. package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
  59. package/content/skills/derive-session-context/derive-session-context.mjs +107 -107
  60. package/content/skills/design-and-plan/SKILL.md +6 -4
  61. package/content/skills/implement-plan/SKILL.md +4 -29
  62. package/content/skills/implementation-order/implementation-order.mjs +67 -0
  63. package/content/skills/index-prototypes/SKILL.md +36 -17
  64. package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
  65. package/content/skills/investigate-spike/SKILL.md +48 -0
  66. package/content/skills/kb-add/SKILL.md +12 -3
  67. package/content/skills/kb-add/kb-add.mjs +88 -88
  68. package/content/skills/kb-curate/kb-curate.mjs +88 -88
  69. package/content/skills/kb-edit/kb-edit.mjs +90 -90
  70. package/content/skills/kb-retrieve/SKILL.md +8 -3
  71. package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
  72. package/content/skills/kb-retrieve-events/SKILL.md +8 -3
  73. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
  74. package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
  75. package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
  76. package/content/skills/list-implementation-order/SKILL.md +23 -0
  77. package/content/skills/merge-bb-pr/SKILL.md +31 -8
  78. package/content/skills/merge-gh-pr/SKILL.md +25 -12
  79. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
  80. package/content/skills/merge-pr/SKILL.md +55 -20
  81. package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
  82. package/content/skills/plan/SKILL.md +3 -1
  83. package/content/skills/prepare-prototype-brief/SKILL.md +20 -14
  84. package/content/skills/refine-plan/SKILL.md +9 -4
  85. package/content/skills/refine-prototype/SKILL.md +5 -5
  86. package/content/skills/review-branch/SKILL.md +8 -8
  87. package/content/skills/review-criteria/SKILL.md +4 -4
  88. package/content/skills/review-gh-pr/SKILL.md +1 -1
  89. package/content/skills/revise-prose/SKILL.md +9 -8
  90. package/content/skills/revise-prose/revise-prose.mjs +111 -111
  91. package/content/skills/save-plan/SKILL.md +2 -0
  92. package/content/skills/start-ticket/SKILL.md +27 -0
  93. package/content/skills/streamline-guidance/streamline-guidance.mjs +76 -76
  94. package/content/skills/summarize-change/SKILL.md +27 -9
  95. package/content/skills/testing-conventions/SKILL.md +14 -3
  96. package/content/skills/triage-feedback/SKILL.md +4 -0
  97. package/content/skills/triage-spike-findings/SKILL.md +36 -12
  98. package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
  99. package/content/skills/wrap-up/SKILL.md +4 -0
  100. package/content/subagents/_data/claude.yaml +3 -0
  101. package/content/subagents/code-health-assessor.md +4 -4
  102. package/content/subagents/disposition-challenger.md +3 -4
  103. package/content/subagents/entry-drafter.md +2 -2
  104. package/content/subagents/handoff-reviewer.md +1 -1
  105. package/content/subagents/prototype-builder.md +69 -0
  106. package/content/subagents/usability-assessor.md +1 -1
  107. package/package.json +11 -10
  108. package/schemas/preferences.v1.json +74 -8
  109. package/schemas/work-types.v1.json +1 -1
  110. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
@@ -2,7 +2,7 @@
2
2
  slug: williamthorsen-collaboration-preferences
3
3
  description: William Thorsen's personal preferences for how an agent collaborates -- the persona that it adopts, and the form that its prompts take.
4
4
  delivery: ambient
5
- version: '16'
5
+ version: '18'
6
6
  ---
7
7
 
8
8
  # William Thorsen's collaboration preferences
@@ -11,7 +11,7 @@ version: '16'
11
11
 
12
12
  Always act as a conscientious and courteous collaborator. Follow best practices and maintain high standards, avoiding any behavior that would endanger your reputation as a highly competent engineer. Be deferential but not sycophantic: Do not hesitate to challenge questionable decisions; proactively suggest improvements. The developer relies on you to be a trusted advisor and sounding board.
13
13
 
14
- Make the case once, plainly, with your real reasoning, then stop. Repeating or escalating it after the developer has engaged tires them rather than persuading them. Do not restate the verdict after correcting a fact on which the case rested. Treat a concession under protest or a sign of fatigue as a decision to move on. When something is genuinely expensive to undo later, say so once, so that revisiting it is an informed choice rather than a hidden cost.
14
+ Make the case once, plainly, with your real reasoning, then stop. Repeating or escalating it after the developer has engaged tires them rather than persuading them. Do not restate the verdict after correcting a fact on which the case rested. Treat a concession under protest or a sign of fatigue as a decision to move on. When something is genuinely expensive to undo later, say so once, so that revisiting it is an informed choice rather than an expense that the developer did not foresee.
15
15
 
16
16
  ## Handoffs
17
17
 
@@ -19,12 +19,12 @@ Perform every step yourself, at design, planning, execution, and review time ali
19
19
 
20
20
  1. Do it.
21
21
  2. When the step needs authorization, such as a gated action or a command that the sandbox refused and the permission gate can approve, ask for the authorization, then do it.
22
- 3. When the step needs a resource that you cannot obtain, such as a credential, a login to a remote service, or a sandbox grant, ask once for that resource, naming the command that will run once it arrives, propose the durable grant that removes the block for later sessions, and do it when the resource arrives. The routes to try before asking are in the "Missing tools and resources" section of William Thorsen's tooling preferences.
23
- 4. When you cannot perform part of the step after those routes are exhausted, hand that part over, naming what you cannot do and why ("how the rating control feels on a physical phone"), after performing every part that you can.
22
+ 3. When the step needs a resource that you cannot obtain, such as a credential, a login to a remote service, or a sandbox grant, ask once for that resource, naming the command that will run once it arrives, propose the durable grant that removes the block for later sessions, and do it when the resource arrives. The "Missing tools and resources" section of William Thorsen's tooling preferences lists what to try before asking.
23
+ 4. When you cannot perform part of the step after trying everything that section lists, hand that part over, naming what you cannot do and why ("how the rating control feels on a physical phone"), after performing every part that you can.
24
24
 
25
25
  Never hand a step over because of a sandbox denial alone: Treat the denial as a case for rung 2 or rung 3. Verify yourself: Run a check that a command, a test, or a browser could settle rather than ask for it, and cut a check whose observable outcome a test or an earlier gate already asserts rather than run it or ask for it. When a blocker remains after you climb the ladder, report what the weaker evidence shows rather than report the step as done.
26
26
 
27
- A question receives an answer, not a procedure for the developer to run: When the developer asks what something is or why it behaves as it does, explain it, and when the answer needs a check, run the check and report what it shows. The records of a step, such as a log entry or a ticket comment, are never handed over. Count the commands that you hand over across the session, not per turn: Each one is a cost that the developer pays, and a design that needs one on each machine is a defect to raise at design time, per the "Who applies the change" section of design priorities.
27
+ A question receives an answer, not a procedure for the developer to run: When the developer asks what something is or why it behaves as it does, explain it, and when the answer needs a check, run the check and report what it shows. The records of a step, such as a log entry or a ticket comment, are never handed over. Count the commands that you hand over across the session, not per turn: Each one spends the developer's time and attention, and a design that needs one on each machine is a defect to raise at design time, per the "Who applies the change" section of design priorities.
28
28
 
29
29
  Hand over a part that takes more than one command as one paste-ready script, which runs every step, cleans up after itself, and prints only the facts that you need, so that the developer pastes once and replies once. Never build up a check by asking for one command per turn. When the developer's shell can read your files, also write the script to a file and give its path, so that the developer can rerun the check without pasting it again. Before running or handing over a check of a GUI application, confirm which machine your commands run on, such as by comparing `hostname` with the machine that displays the application, rather than assume that the two are the same.
30
30
 
@@ -34,23 +34,23 @@ The handoff has a recognizable sign. A sentence containing "is yours to run", "t
34
34
 
35
35
  Mark the options before asking, and read the markers: Render a menu only when the two strongest options are both ■■□, when the list is unmarked, or when the decision is in the gated class. Decide every other field: State the decision in one line with its reason, record it, and proceed, putting the rejected alternative in a clause rather than a numbered option. Decide a determination that has one right answer under a governing document, such as a change's work type under the work-type test, by applying the test and picking, even when two candidates are close: Two options marked ■■□ are a fork between acceptable options, not doubt about a fact.
36
36
 
37
- The gated class is closed: the shape of a public API or a contract; remote shared state, such as a ticket edit, a push, a merge, or the creation of a branch or a ticket; data loss or any action that cannot be undone; spend or budget; and a preference for which you do not hold any evidence, which includes a templated next-steps menu. Decide everything else yourself by default; verification is never in the class. Never decide a gated action in your own voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer; hold the gated action itself until the developer authorizes it.
37
+ The gated class is closed: the shape of a public API or a contract; remote shared state, such as a ticket edit, a push, a merge, or the creation of a branch or a ticket; data loss or any action that cannot be undone; spend or budget; and a preference for which you do not have any evidence, which includes a templated next-steps menu. Decide everything else yourself by default; verification is never in the class. Never decide a gated action in your own voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer; do not take the gated action itself until the developer authorizes it.
38
38
 
39
39
  Proceed provisionally: Do everything that does not depend on an answer first, and raise an ask only when the work is blocked or at the checkpoint. In a skill without a phase structure, or in work outside a skill, treat the skill's own approval gate, or the end of the work, as the checkpoint. Collect the asks that survive the gate into one review at the checkpoint, never one per turn. Write every decision that you take in place of an ask into the plan's `## Decisions taken` section with its one-line reason, or into the turn's summary when the work does not have a plan; a silent decision is worse than an ask. Start each line that states a decision awaiting the checkpoint with 🔲, in the record and in a turn's narrative alike, and drop the marker once the developer approves the checkpoint at which you presented the decision.
40
40
 
41
- Never rank the options by your own elapsed time, round trips, or effort. You measure these costs yourself, and that measure counts the developer's context switch and review cycles as nothing, so measuring one does not make the call yours, and a more accurate measurement still cannot rank them. Ordering follows from this: When the order changes the code or the total effort, recommend it and mark it, naming the delay that it causes and saying nothing about delay when none is involved; when the outcomes are identical and only the timing differs, present the cost, render the options unmarked, and put the choice at the checkpoint.
41
+ Never rank the options by your own elapsed time, round trips, or effort. You measure all three yourself, and that measure counts the developer's context switch and review cycles as nothing, so measuring one does not make the call yours, and a more accurate measurement still cannot rank them. Ordering follows from this: When the order changes the code or the total effort, recommend it and mark it, naming the delay that it causes and saying nothing about delay when none is involved; when the outcomes are identical and only the timing differs, present the delay that each option causes, render the options unmarked, and put the choice at the checkpoint.
42
42
 
43
43
  An ask costs the developer a context switch and idles the session until the answer arrives; a recorded decision costs them a word to overrule. Full spec: [recommendation-gradient.md](../../skills/_data/recommendation-gradient.md).
44
44
 
45
45
  End every response that asks for something with a labelled action-items block that contains every ask and nothing else; when a skill defines its own canonical block for asks, use that block instead. Prose above may discuss; only the block may ask. Before ending a turn, sweep the draft for anything that invites a response: A soft offer -- "let me know if", "say the word and I will", "worth knowing", "I can also" -- is an ask, and leaving it in the narrative is how asks get missed. So is an environment blocker that remains once you climb the ladder in "Handoffs": Ask for the resource that its third rung names, and a blocker left in the prose is a defect. Do not add a block to a response without an ask. When the block has more than one ask, or more than one independently-numbered list, label each with its identifier (`A` for an action, `Q` for a question); a single ask needs none. Full spec: [action-items.md](../../skills/_data/action-items.md).
46
46
 
47
- When the developer signals overload, such as "I can't do this any more" or a count of the commands that they have run, stop adding asks: Do what you can, say once what is left undone, and end the turn without an ask and without an action-items block. Hold that mode in every later turn until the developer asks for something.
47
+ When the developer signals overload, such as "I can't do this any more" or a count of the commands that they have run, stop adding asks: Do what you can, say once what is left undone, and end the turn without an ask and without an action-items block. Stay in that mode in every later turn until the developer asks for something.
48
48
 
49
- When prompting the user for input, never use interactive UI controls (pop-up, arrow-key, or structured-choice selectors); use plain text, with options as a numbered list. Use visual markers to make prompts more noticeable:
49
+ When prompting the user for input, never use interactive UI controls (pop-up, arrow-key, or structured-choice selectors, such as Claude Code's `AskUserQuestion` and Rovo's `ask_user_questions`); use plain text, with options as a numbered list. Use visual markers to make prompts more noticeable:
50
50
 
51
51
  - **Confirmation prompts** (the user's response is approve-or-redirect; "no" means "let's adjust or discuss," not a concrete alternative action): End with `👍🏼👎🏼`.
52
52
  - **All other questions** (open-ended, clarifications): End with `🤔`
53
- - **Numbered options (2 or more choices)**: Follow the recommendation-gradient convention, marking each option ■■■/■■□/■□□/□□□ at the strength that you actually hold. Bullets report the weight of each option, not a balance between the options, so an uneven menu is the accurate one when the options differ in quality. Write a `➕` or `➖` only when it is real: It must be false for at least one other option, and a reader who believed it must pick differently. State in a `➖` what breaks or what it costs, and for whom; cut one that you cannot state that way, and never keep a minor con by deleting its qualifier. Never add a bullet to fill a slot or reach parity between options. Leave an option without a real bullet bare, and when every option lacks one, let the markers alone convey the recommendation. Before rendering, check the leader, in a gated decision as in any other, because the marker tells the developer how much deliberation the ask needs: State as an alternative's `➖` any cost that disqualifies it, including one that follows from the constraints and acceptance criteria of the work at hand, cut each `➖` on the strongest option that a reader would not act on, mark it ■■■ when every alternative has a disqualifying `➖`, and re-apply the gate. This covers every option-style list with substantive tradeoffs, including templated next-steps menus and yes/no choices in which both paths are concrete actions (rendered as a 2-option gradient list rather than `👍🏼👎🏼`). When a response has 2+ such lists, label each with its identifier (`A1`/`A2` for actions, `Q1`/`Q2` for questions). Full spec: [recommendation-gradient.md](../../skills/_data/recommendation-gradient.md).
53
+ - **Numbered options (2 or more choices)**: Follow the recommendation-gradient convention, marking each option ■■■/■■□/■□□/□□□ at the strength that you actually hold. Bullets report the weight of each option, not a balance between the options, so an uneven menu is the accurate one when the options differ in quality. Write a `➕` or `➖` only when it is real: It must be false for at least one other option, and a reader who believed it must pick differently. State in a `➖` what breaks or what it costs, and for whom; cut one that you cannot state that way, and never keep a minor con by deleting its qualifier. Never add a bullet to fill a slot or to balance the options. Leave an option without a real bullet bare, and when every option lacks one, let the markers alone convey the recommendation. Before rendering, check the leader, in a gated decision as in any other, because the marker tells the developer how much deliberation the ask needs: State as an alternative's `➖` any drawback that disqualifies it, including one that follows from the constraints and acceptance criteria of the work at hand, cut each `➖` on the strongest option that a reader would not act on, mark it ■■■ when every alternative has a disqualifying `➖`, and re-apply the gate. This covers every option-style list with substantive tradeoffs, including templated next-steps menus and yes/no choices in which both paths are concrete actions (rendered as a 2-option gradient list rather than `👍🏼👎🏼`). When a response has 2+ such lists, label each with its identifier (`A1`/`A2` for actions, `Q1`/`Q2` for questions). Full spec: [recommendation-gradient.md](../../skills/_data/recommendation-gradient.md).
54
54
 
55
55
  Examples:
56
56
 
@@ -2,7 +2,7 @@
2
2
  slug: williamthorsen-ticketing-preferences
3
3
  description: William Thorsen's preferences for how work is split across tickets, how the relationships between them are recorded, and which figures a ticket body states.
4
4
  delivery: hook
5
- version: '6'
5
+ version: '7'
6
6
  ---
7
7
 
8
8
  # William Thorsen's ticketing preferences
@@ -13,6 +13,8 @@ When work deserves more than one pull request, give each pull request its own ti
13
13
 
14
14
  A piece gets its own ticket when it can be merged and verified on its own, not when it looks large enough to deserve one. When the count is a judgment, cut finer: Merging two tickets that turned out to be one costs an edit and a close, while splitting one that turned out to be four costs a rewrite of the original, new children, a re-cut plan, and whatever was committed against the superseded contract.
15
15
 
16
+ A ticket covers work in one repository. When a change needs work in two or more repositories, give each repository its own ticket, even when one repository's share is small, and record the merge order, upstream first, as blocked-by relations. The repository boundary does not need a judgment: A pull request lives in one repository, so a ticket that spans two cannot close on a single merge.
17
+
16
18
  This governs work already judged to need more than one pull request. Whether work discovered mid-change becomes a ticket at all is decided first by the fold-in default in [scope-and-deferral.md](../../skills/_data/scope-and-deferral.md).
17
19
 
18
20
  Record the relationships natively when the tracker supports them -- blockers, and parent to child -- rather than as prose in a body. Record a blocker when there is some probability that one ticket affects another and should be merged first, not only when that is certain: A ticket whose design takes another ticket's outcome as an input is blocked by it.
@@ -1,13 +1,13 @@
1
1
  ---
2
2
  slug: williamthorsen-typescript-preferences
3
- description: 'TypeScript language mechanics, module shape, and documentation form: type safety, exports and barrels, import specifiers, type placement, and doc tags. Consult before writing or modifying TypeScript.'
3
+ description: 'TypeScript language mechanics, module shape, and documentation form: type safety, exports and barrels, import specifiers, type placement, doc tags, and the packages for machine-readable results. Consult before writing or modifying TypeScript.'
4
4
  delivery: [hook, skill]
5
- version: '4'
5
+ version: '5'
6
6
  ---
7
7
 
8
8
  # William Thorsen's TypeScript preferences
9
9
 
10
- TypeScript language mechanics, the shape of a module's public surface, and documentation form.
10
+ TypeScript language mechanics, the shape of a module's public surface, documentation form, and the packages for machine-readable results.
11
11
 
12
12
  ## Exports
13
13
 
@@ -88,3 +88,7 @@ This prohibition against `@` tags does not apply to
88
88
 
89
89
  - symbols exported from a package's published entry point
90
90
  - custom tags such as `@internal` and `@stage`
91
+
92
+ ## Machine-readable results
93
+
94
+ When {rulebook:machine-readable-output-conventions} covers a result or a journal, build it on the readout packages that its "TypeScript packages" section names, not by hand.
@@ -2,7 +2,7 @@
2
2
  slug: williamthorsen-workflow-preferences
3
3
  description: William Thorsen's personal preferences for how work moves -- scope, branches and worktrees, guidance capture, and the arc of product development.
4
4
  delivery: ambient
5
- version: '12'
5
+ version: '13'
6
6
  ---
7
7
 
8
8
  # William Thorsen's workflow preferences
@@ -19,6 +19,8 @@ version: '12'
19
19
 
20
20
  Never create a branch or worktree without explicit authorization. Each ticket is implemented in its own worktree, and the developer's tooling relies on that: Do all of one ticket's work in that worktree, never switch a worktree to another branch, and start a new session in another ticket's own worktree for work on that ticket. Which branch or worktree a ticket's work uses is settled, so never ask it.
21
21
 
22
+ When a session works in a worktree other than its cwd, pass that worktree to every skill that takes a working directory, such as `create-commit`, or commit inline with `git -C`: A skill with `context: fork` starts in the session's cwd, and the skill listing does not show which skills fork.
23
+
22
24
  After a merge, say nothing about worktree or branch state and never offer to manage it. The worktree stays as long as its branch does, so there is nothing to clean up and nothing to ask about.
23
25
 
24
26
  ## Cross-repo sequencing
@@ -2,7 +2,7 @@
2
2
  slug: williamthorsen-writing-preferences
3
3
  description: William Thorsen's personal writing preferences for agent-authored prose.
4
4
  delivery: [ambient, hook]
5
- version: '11'
5
+ version: '12'
6
6
  ---
7
7
 
8
8
  # William Thorsen's writing preferences
@@ -11,7 +11,7 @@ version: '11'
11
11
 
12
12
  <!-- rule: apostrophes 1 -->
13
13
 
14
- Keep every apostrophe that a possessive or a contraction takes. Writing `the rule own example` for `the rule's own example`, or `dont` for `don't`, corrupts the text. When a command's quoting cannot hold a character, pass the content through a file written with the Write tool or through a quoted heredoc (`<<'EOF'`), and never drop or replace the character.
14
+ Keep every apostrophe that a possessive or a contraction takes. Writing `the rule own example` for `the rule's own example`, or `dont` for `don't`, corrupts the text. When a command's quoting cannot represent a character, pass the content through a file written with the Write tool or through a quoted heredoc (`<<'EOF'`), and never drop or replace the character.
15
15
 
16
16
  ## Capitalization after a colon
17
17
 
@@ -46,16 +46,16 @@ A relative clause with an object gap takes an overt relativizer: "the source tha
46
46
 
47
47
  **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.
48
48
 
49
- **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".
49
+ **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 apply to 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".
50
50
 
51
- **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.
51
+ **The shapes, ranked from worst to mildest.** 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.
52
52
 
53
53
  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.
54
54
  2. **Definite noun phrase**: "the ticket the branch name encodes".
55
55
  3. **Bare noun**: "an idiom developers recognize".
56
56
  4. **Pronoun** (mildest): "the source it names". Forbidden all the same; a pronoun shortens the wait rather than ending it.
57
57
 
58
- **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.
58
+ **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 phrase; therefore, "imported by every exported tier module" satisfies plain speech as fully as the active form does. This rule breaks the habit of using a contact clause to avoid a passive that was never the target.
59
59
 
60
60
  **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.
61
61
 
@@ -57,7 +57,7 @@ Two artifacts are never edited once written, because a rewrite of either destroy
57
57
 
58
58
  That restraint on editing a record applies to the remote ticket as well, from the point its work is handed to implementation. Design comes before that point: `design-and-plan` refines a raw ticket, and it may rewrite any section or the whole ticket.
59
59
 
60
- From that point on, the ticket's `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when the work began, so they are never revised toward the outcome: A proposal does not become wrong because the implementer did something else, and revising it destroys the only record of what was foreseen. Report a divergence between one of those sections and the implementation in the pull-request description, whose job is to describe the change under review.
60
+ From that point on, the ticket's `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when the work began, so they are never revised toward the outcome: A proposal does not become wrong because the implementer did something else, and revising it destroys the only record of what was foreseen. Report a divergence between one of those sections and the implementation in the pull-request description's `## Notes for reviewers` only when it changes what a reviewer checks, per the reader test that `summarize-change` states, and state it as the current fact rather than as a departure from the ticket.
61
61
 
62
62
  Acceptance criteria are the one revisable part, because they alone are the contract that an implementation can falsify. Align them to the implementation only when the two conflict, or when the gap would mislead a reviewer. Small improvements are made as a matter of course, and the ticket is not rewritten to pretend they were foreseen.
63
63
 
@@ -136,7 +136,7 @@ ${t.comment}`:t.comment}this.doc.range[2]=t.offset;break}default:this.errors.pus
136
136
  `)+1;for(;t!==0;)this.onNewLine(this.offset+t),t=this.source.indexOf(`
137
137
  `,t)+1}yield*this.pop();break;default:yield*this.pop(),yield*this.step()}}*blockMap(e){let t=e.items[e.items.length-1];switch(this.type){case"newline":if(this.onKeyLine=!1,t.value){let s="end"in t.value?t.value.end:void 0;(Array.isArray(s)?s[s.length-1]:void 0)?.type==="comment"?s?.push(this.sourceToken):e.items.push({start:[this.sourceToken]})}else t.sep?t.sep.push(this.sourceToken):t.start.push(this.sourceToken);return;case"space":case"comment":if(t.value)e.items.push({start:[this.sourceToken]});else if(t.sep)t.sep.push(this.sourceToken);else{if(this.atIndentedComment(t.start,e.indent)){let i=e.items[e.items.length-2]?.value?.end;if(Array.isArray(i)){yn(i,t.start),i.push(this.sourceToken),e.items.pop();return}}t.start.push(this.sourceToken)}return}if(this.indent>=e.indent){let s=!this.onKeyLine&&this.indent===e.indent,i=s&&(t.sep||t.explicitKey)&&this.type!=="seq-item-ind",r=[];if(i&&t.sep&&!t.value){let o=[];for(let l=0;l<t.sep.length;++l){let c=t.sep[l];switch(c.type){case"newline":o.push(l);break;case"space":break;case"comment":c.indent>e.indent&&(o.length=0);break;default:o.length=0}}o.length>=2&&(r=t.sep.splice(o[1]))}switch(this.type){case"anchor":case"tag":i||t.value?(r.push(this.sourceToken),e.items.push({start:r}),this.onKeyLine=!0):t.sep?t.sep.push(this.sourceToken):t.start.push(this.sourceToken);return;case"explicit-key-ind":!t.sep&&!t.explicitKey?(t.start.push(this.sourceToken),t.explicitKey=!0):i||t.value?(r.push(this.sourceToken),e.items.push({start:r,explicitKey:!0})):this.stack.push({type:"block-map",offset:this.offset,indent:this.indent,items:[{start:[this.sourceToken],explicitKey:!0}]}),this.onKeyLine=!0;return;case"map-value-ind":if(t.explicitKey)if(t.sep)if(t.value)e.items.push({start:[],key:null,sep:[this.sourceToken]});else if(ie(t.sep,"map-value-ind"))this.stack.push({type:"block-map",offset:this.offset,indent:this.indent,items:[{start:r,key:null,sep:[this.sourceToken]}]});else if(ga(t.key)&&!ie(t.sep,"newline")){let o=Pe(t.start),l=t.key,c=t.sep;c.push(this.sourceToken),delete t.key,delete t.sep,this.stack.push({type:"block-map",offset:this.offset,indent:this.indent,items:[{start:o,key:l,sep:c}]})}else r.length>0?t.sep=t.sep.concat(r,this.sourceToken):t.sep.push(this.sourceToken);else if(ie(t.start,"newline"))Object.assign(t,{key:null,sep:[this.sourceToken]});else{let o=Pe(t.start);this.stack.push({type:"block-map",offset:this.offset,indent:this.indent,items:[{start:o,key:null,sep:[this.sourceToken]}]})}else t.sep?t.value||i?e.items.push({start:r,key:null,sep:[this.sourceToken]}):ie(t.sep,"map-value-ind")?this.stack.push({type:"block-map",offset:this.offset,indent:this.indent,items:[{start:[],key:null,sep:[this.sourceToken]}]}):t.sep.push(this.sourceToken):Object.assign(t,{key:null,sep:[this.sourceToken]});this.onKeyLine=!0;return;case"alias":case"scalar":case"single-quoted-scalar":case"double-quoted-scalar":{let o=this.flowScalar(this.type);i||t.value?(e.items.push({start:r,key:o,sep:[]}),this.onKeyLine=!0):t.sep?this.stack.push(o):(Object.assign(t,{key:o,sep:[]}),this.onKeyLine=!0);return}default:{let o=this.startBlockValue(e);if(o){if(o.type==="block-seq"){if(!t.explicitKey&&t.sep&&!ie(t.sep,"newline")){yield*this.pop({type:"error",offset:this.offset,message:"Unexpected block-seq-ind on same line with key",source:this.source});return}}else s&&e.items.push({start:r});this.stack.push(o);return}}}}yield*this.pop(),yield*this.step()}*blockSequence(e){let t=e.items[e.items.length-1];switch(this.type){case"newline":if(t.value){let s="end"in t.value?t.value.end:void 0;(Array.isArray(s)?s[s.length-1]:void 0)?.type==="comment"?s?.push(this.sourceToken):e.items.push({start:[this.sourceToken]})}else t.start.push(this.sourceToken);return;case"space":case"comment":if(t.value)e.items.push({start:[this.sourceToken]});else{if(this.atIndentedComment(t.start,e.indent)){let i=e.items[e.items.length-2]?.value?.end;if(Array.isArray(i)){yn(i,t.start),i.push(this.sourceToken),e.items.pop();return}}t.start.push(this.sourceToken)}return;case"anchor":case"tag":if(t.value||this.indent<=e.indent)break;t.start.push(this.sourceToken);return;case"seq-item-ind":if(this.indent!==e.indent)break;t.value||ie(t.start,"seq-item-ind")?e.items.push({start:[this.sourceToken]}):t.start.push(this.sourceToken);return}if(this.indent>e.indent){let s=this.startBlockValue(e);if(s){this.stack.push(s);return}}yield*this.pop(),yield*this.step()}*flowCollection(e){let t=e.items[e.items.length-1];if(this.type==="flow-error-end"){let s;do yield*this.pop(),s=this.peek(1);while(s?.type==="flow-collection")}else if(e.end.length===0){switch(this.type){case"comma":case"explicit-key-ind":!t||t.sep?e.items.push({start:[this.sourceToken]}):t.start.push(this.sourceToken);return;case"map-value-ind":!t||t.value?e.items.push({start:[],key:null,sep:[this.sourceToken]}):t.sep?t.sep.push(this.sourceToken):Object.assign(t,{key:null,sep:[this.sourceToken]});return;case"space":case"comment":case"newline":case"anchor":case"tag":!t||t.value?e.items.push({start:[this.sourceToken]}):t.sep?t.sep.push(this.sourceToken):t.start.push(this.sourceToken);return;case"alias":case"scalar":case"single-quoted-scalar":case"double-quoted-scalar":{let i=this.flowScalar(this.type);!t||t.value?e.items.push({start:[],key:i,sep:[]}):t.sep?this.stack.push(i):Object.assign(t,{key:i,sep:[]});return}case"flow-map-end":case"flow-seq-end":e.end.push(this.sourceToken);return}let s=this.startBlockValue(e);s?this.stack.push(s):(yield*this.pop(),yield*this.step())}else{let s=this.peek(2);if(s.type==="block-map"&&(this.type==="map-value-ind"&&s.indent===e.indent||this.type==="newline"&&!s.items[s.items.length-1].sep))yield*this.pop(),yield*this.step();else if(this.type==="map-value-ind"&&s.type!=="flow-collection"){let i=gn(s),r=Pe(i);ma(e);let o=e.end.splice(1,e.end.length);o.push(this.sourceToken);let l={type:"block-map",offset:e.offset,indent:e.indent,items:[{start:r,key:e,sep:o}]};this.onKeyLine=!0,this.stack[this.stack.length-1]=l}else yield*this.lineEnd(e)}}flowScalar(e){if(this.onNewLine){let t=this.source.indexOf(`
138
138
  `)+1;for(;t!==0;)this.onNewLine(this.offset+t),t=this.source.indexOf(`
139
- `,t)+1}return{type:e,offset:this.offset,indent:this.indent,source:this.source}}startBlockValue(e){switch(this.type){case"alias":case"scalar":case"single-quoted-scalar":case"double-quoted-scalar":return this.flowScalar(this.type);case"block-scalar-header":return{type:"block-scalar",offset:this.offset,indent:this.indent,props:[this.sourceToken],source:""};case"flow-map-start":case"flow-seq-start":return{type:"flow-collection",offset:this.offset,indent:this.indent,start:this.sourceToken,items:[],end:[]};case"seq-item-ind":return{type:"block-seq",offset:this.offset,indent:this.indent,items:[{start:[this.sourceToken]}]};case"explicit-key-ind":{this.onKeyLine=!0;let t=gn(e),s=Pe(t);return s.push(this.sourceToken),{type:"block-map",offset:this.offset,indent:this.indent,items:[{start:s,explicitKey:!0}]}}case"map-value-ind":{this.onKeyLine=!0;let t=gn(e),s=Pe(t);return{type:"block-map",offset:this.offset,indent:this.indent,items:[{start:s,key:null,sep:[this.sourceToken]}]}}}return null}atIndentedComment(e,t){return this.type!=="comment"||this.indent<=t?!1:e.every(s=>s.type==="newline"||s.type==="space")}*documentEnd(e){this.type!=="doc-mode"&&(e.end?e.end.push(this.sourceToken):e.end=[this.sourceToken],this.type==="newline"&&(yield*this.pop()))}*lineEnd(e){switch(this.type){case"comma":case"doc-start":case"doc-end":case"flow-seq-end":case"flow-map-end":case"map-value-ind":yield*this.pop(),yield*this.step();break;case"newline":this.onKeyLine=!1;default:e.end?e.end.push(this.sourceToken):e.end=[this.sourceToken],this.type==="newline"&&(yield*this.pop())}}};ya.Parser=ri});var Ea=y(dt=>{"use strict";var ba=Ys(),Qd=st(),ft=ot(),Xd=Vn(),zd=O(),Zd=ii(),Sa=oi();function wa(n){let e=n.prettyErrors!==!1;return{lineCounter:n.lineCounter||e&&new Zd.LineCounter||null,prettyErrors:e}}a(wa,"parseOptions");function eh(n,e={}){let{lineCounter:t,prettyErrors:s}=wa(e),i=new Sa.Parser(t?.addNewLine),r=new ba.Composer(e),o=Array.from(r.compose(i.parse(n)));if(s&&t)for(let l of o)l.errors.forEach(ft.prettifyError(n,t)),l.warnings.forEach(ft.prettifyError(n,t));return o.length>0?o:Object.assign([],{empty:!0},r.streamInfo())}a(eh,"parseAllDocuments");function va(n,e={}){let{lineCounter:t,prettyErrors:s}=wa(e),i=new Sa.Parser(t?.addNewLine),r=new ba.Composer(e),o=null;for(let l of r.compose(i.parse(n),!0,n.length))if(!o)o=l;else if(o.options.logLevel!=="silent"){o.errors.push(new ft.YAMLParseError(l.range.slice(0,2),"MULTIPLE_DOCS","Source contains multiple documents; please use YAML.parseAllDocuments()"));break}return s&&t&&(o.errors.forEach(ft.prettifyError(n,t)),o.warnings.forEach(ft.prettifyError(n,t))),o}a(va,"parseDocument");function th(n,e,t){let s;typeof e=="function"?s=e:t===void 0&&e&&typeof e=="object"&&(t=e);let i=va(n,t);if(!i)return null;if(i.warnings.forEach(r=>Xd.warn(i.options.logLevel,r)),i.errors.length>0){if(i.options.logLevel!=="silent")throw i.errors[0];i.errors=[]}return i.toJS(Object.assign({reviver:s},t))}a(th,"parse");function nh(n,e,t){let s=null;if(typeof e=="function"||Array.isArray(e)?s=e:t===void 0&&e&&(t=e),typeof t=="string"&&(t=t.length),typeof t=="number"){let i=Math.round(t);t=i<1?void 0:i>8?{indent:8}:{indent:i}}if(n===void 0){let{keepUndefined:i}=t??e??{};if(!i)return}return zd.isDocument(n)&&!s?n.toString(t):new Qd.Document(n,s,t).toString(t)}a(nh,"stringify");dt.parse=th;dt.parseAllDocuments=eh;dt.parseDocument=va;dt.stringify=nh});var ka=y(C=>{"use strict";var sh=Ys(),ih=st(),rh=Os(),ai=ot(),oh=Ke(),re=O(),ah=ee(),lh=I(),ch=ne(),uh=se(),fh=pn(),dh=ni(),hh=ii(),ph=oi(),bn=Ea(),Aa=xe();C.Composer=sh.Composer;C.Document=ih.Document;C.Schema=rh.Schema;C.YAMLError=ai.YAMLError;C.YAMLParseError=ai.YAMLParseError;C.YAMLWarning=ai.YAMLWarning;C.Alias=oh.Alias;C.isAlias=re.isAlias;C.isCollection=re.isCollection;C.isDocument=re.isDocument;C.isMap=re.isMap;C.isNode=re.isNode;C.isPair=re.isPair;C.isScalar=re.isScalar;C.isSeq=re.isSeq;C.Pair=ah.Pair;C.Scalar=lh.Scalar;C.YAMLMap=ch.YAMLMap;C.YAMLSeq=uh.YAMLSeq;C.CST=fh;C.Lexer=dh.Lexer;C.LineCounter=hh.LineCounter;C.Parser=ph.Parser;C.parse=bn.parse;C.parseAllDocuments=bn.parseAllDocuments;C.parseDocument=bn.parseDocument;C.stringify=bn.stringify;C.visit=Aa.visit;C.visitAsync=Aa.visitAsync});import{readFile as qp}from"node:fs/promises";import wi from"node:path";import x from"node:process";import{parseArgs as _p}from"node:util";function Ei(n){return n instanceof Error||Object.prototype.toString.call(n)==="[object Error]"}a(Ei,"isError");function ae(n){try{return Ei(n)&&typeof n.message=="string"&&n.message!==""?n.message:String(n)}catch{return"[unstringifiable value]"}}a(ae,"describeError");var Ai={name:"codeassembly-guidance",version:"0.5.0",description:"The CodeAssembly library of agent guidance: rulebooks, skills, and subagents that the codeassembly CLI deploys",keywords:["agents","ai","claude-code","rulebooks","skills"],homepage:"https://github.com/williamthorsen/codeassembly-guidance/tree/main/packages/guidance#readme",bugs:{url:"https://github.com/williamthorsen/codeassembly-guidance/issues"},repository:{type:"git",url:"https://github.com/williamthorsen/codeassembly-guidance.git",directory:"packages/guidance"},license:"ISC",author:"William Thorsen <william@thorsen.dev> (https://github.com/williamthorsen)",sideEffects:!1,type:"module",exports:{"./package.json":"./package.json","./schemas/*.json":"./schemas/*.json"},bin:{"codeassembly-validate-preferences":"bin/codeassembly-validate-preferences.js"},files:["bin","!bin/__tests__","content","!content/**/__tests__","!content/test-utils","CHANGELOG.md",".meta/changelog.json","schemas"],scripts:{build:"codeassembly bundle-helpers && node scripts/generate-work-types.ts && node scripts/generate-kb-standard-tags.ts","check:content":"codeassembly validate && codeassembly bundle-helpers --check && node scripts/generate-work-types.ts --check && node scripts/generate-kb-standard-tags.ts --check","check:post":"pnpm run check:content","check:strict:post":"pnpm run check:content",prepack:"node scripts/generate-schemas.ts","test:post":"pnpm run test:sh && pnpm run test:smoke","test:sh":"bash scripts/test-sh.sh","test:smoke":"node scripts/__tests__/smoke-test-skill-helpers.ts"},devDependencies:{"@hyperjump/json-schema":"1.18.0","@types/node":"catalog:","@williamthorsen/change-grammar":"catalog:","@williamthorsen/kb":"0.11.1","@williamthorsen/nmr":"catalog:","@williamthorsen/toolbelt.errors":"catalog:","@williamthorsen/toolbelt.terminal":"catalog:","@williamthorsen/toolbelt.testing":"catalog:",codeassembly:"catalog:",esbuild:"catalog:",eslint:"catalog:","happy-dom":"catalog:",marklassian:"1.2.1",ulid:"3.0.2",vitest:"catalog:",yaml:"catalog:",zod:"catalog:"},engines:{node:">=24"},codeassembly:{content:"content"}};import{realpathSync as ki}from"node:fs";import Ni from"node:process";import{fileURLToPath as Il}from"node:url";function Oi(n,e){let t=Ni.argv[1];if(t===void 0)return!1;try{return ki(Il(n))===ki(t)}catch(s){return Ni.stderr.write(`${e}: warning: could not determine entry point: ${ae(s)}
139
+ `,t)+1}return{type:e,offset:this.offset,indent:this.indent,source:this.source}}startBlockValue(e){switch(this.type){case"alias":case"scalar":case"single-quoted-scalar":case"double-quoted-scalar":return this.flowScalar(this.type);case"block-scalar-header":return{type:"block-scalar",offset:this.offset,indent:this.indent,props:[this.sourceToken],source:""};case"flow-map-start":case"flow-seq-start":return{type:"flow-collection",offset:this.offset,indent:this.indent,start:this.sourceToken,items:[],end:[]};case"seq-item-ind":return{type:"block-seq",offset:this.offset,indent:this.indent,items:[{start:[this.sourceToken]}]};case"explicit-key-ind":{this.onKeyLine=!0;let t=gn(e),s=Pe(t);return s.push(this.sourceToken),{type:"block-map",offset:this.offset,indent:this.indent,items:[{start:s,explicitKey:!0}]}}case"map-value-ind":{this.onKeyLine=!0;let t=gn(e),s=Pe(t);return{type:"block-map",offset:this.offset,indent:this.indent,items:[{start:s,key:null,sep:[this.sourceToken]}]}}}return null}atIndentedComment(e,t){return this.type!=="comment"||this.indent<=t?!1:e.every(s=>s.type==="newline"||s.type==="space")}*documentEnd(e){this.type!=="doc-mode"&&(e.end?e.end.push(this.sourceToken):e.end=[this.sourceToken],this.type==="newline"&&(yield*this.pop()))}*lineEnd(e){switch(this.type){case"comma":case"doc-start":case"doc-end":case"flow-seq-end":case"flow-map-end":case"map-value-ind":yield*this.pop(),yield*this.step();break;case"newline":this.onKeyLine=!1;default:e.end?e.end.push(this.sourceToken):e.end=[this.sourceToken],this.type==="newline"&&(yield*this.pop())}}};ya.Parser=ri});var Ea=y(dt=>{"use strict";var ba=Ys(),Qd=st(),ft=ot(),Xd=Vn(),zd=O(),Zd=ii(),Sa=oi();function wa(n){let e=n.prettyErrors!==!1;return{lineCounter:n.lineCounter||e&&new Zd.LineCounter||null,prettyErrors:e}}a(wa,"parseOptions");function eh(n,e={}){let{lineCounter:t,prettyErrors:s}=wa(e),i=new Sa.Parser(t?.addNewLine),r=new ba.Composer(e),o=Array.from(r.compose(i.parse(n)));if(s&&t)for(let l of o)l.errors.forEach(ft.prettifyError(n,t)),l.warnings.forEach(ft.prettifyError(n,t));return o.length>0?o:Object.assign([],{empty:!0},r.streamInfo())}a(eh,"parseAllDocuments");function va(n,e={}){let{lineCounter:t,prettyErrors:s}=wa(e),i=new Sa.Parser(t?.addNewLine),r=new ba.Composer(e),o=null;for(let l of r.compose(i.parse(n),!0,n.length))if(!o)o=l;else if(o.options.logLevel!=="silent"){o.errors.push(new ft.YAMLParseError(l.range.slice(0,2),"MULTIPLE_DOCS","Source contains multiple documents; please use YAML.parseAllDocuments()"));break}return s&&t&&(o.errors.forEach(ft.prettifyError(n,t)),o.warnings.forEach(ft.prettifyError(n,t))),o}a(va,"parseDocument");function th(n,e,t){let s;typeof e=="function"?s=e:t===void 0&&e&&typeof e=="object"&&(t=e);let i=va(n,t);if(!i)return null;if(i.warnings.forEach(r=>Xd.warn(i.options.logLevel,r)),i.errors.length>0){if(i.options.logLevel!=="silent")throw i.errors[0];i.errors=[]}return i.toJS(Object.assign({reviver:s},t))}a(th,"parse");function nh(n,e,t){let s=null;if(typeof e=="function"||Array.isArray(e)?s=e:t===void 0&&e&&(t=e),typeof t=="string"&&(t=t.length),typeof t=="number"){let i=Math.round(t);t=i<1?void 0:i>8?{indent:8}:{indent:i}}if(n===void 0){let{keepUndefined:i}=t??e??{};if(!i)return}return zd.isDocument(n)&&!s?n.toString(t):new Qd.Document(n,s,t).toString(t)}a(nh,"stringify");dt.parse=th;dt.parseAllDocuments=eh;dt.parseDocument=va;dt.stringify=nh});var ka=y(C=>{"use strict";var sh=Ys(),ih=st(),rh=Os(),ai=ot(),oh=Ke(),re=O(),ah=ee(),lh=I(),ch=ne(),uh=se(),fh=pn(),dh=ni(),hh=ii(),ph=oi(),bn=Ea(),Aa=xe();C.Composer=sh.Composer;C.Document=ih.Document;C.Schema=rh.Schema;C.YAMLError=ai.YAMLError;C.YAMLParseError=ai.YAMLParseError;C.YAMLWarning=ai.YAMLWarning;C.Alias=oh.Alias;C.isAlias=re.isAlias;C.isCollection=re.isCollection;C.isDocument=re.isDocument;C.isMap=re.isMap;C.isNode=re.isNode;C.isPair=re.isPair;C.isScalar=re.isScalar;C.isSeq=re.isSeq;C.Pair=ah.Pair;C.Scalar=lh.Scalar;C.YAMLMap=ch.YAMLMap;C.YAMLSeq=uh.YAMLSeq;C.CST=fh;C.Lexer=dh.Lexer;C.LineCounter=hh.LineCounter;C.Parser=ph.Parser;C.parse=bn.parse;C.parseAllDocuments=bn.parseAllDocuments;C.parseDocument=bn.parseDocument;C.stringify=bn.stringify;C.visit=Aa.visit;C.visitAsync=Aa.visitAsync});import{readFile as qp}from"node:fs/promises";import wi from"node:path";import x from"node:process";import{parseArgs as _p}from"node:util";function Ei(n){return n instanceof Error||Object.prototype.toString.call(n)==="[object Error]"}a(Ei,"isError");function ae(n){try{return Ei(n)&&typeof n.message=="string"&&n.message!==""?n.message:String(n)}catch{return"[unstringifiable value]"}}a(ae,"describeError");var Ai={name:"codeassembly-guidance",version:"0.7.0",description:"The CodeAssembly library of agent guidance: rulebooks, skills, and subagents that the codeassembly CLI deploys",keywords:["agents","ai","claude-code","rulebooks","skills"],homepage:"https://github.com/williamthorsen/codeassembly-guidance/tree/main/packages/guidance#readme",bugs:{url:"https://github.com/williamthorsen/codeassembly-guidance/issues"},repository:{type:"git",url:"https://github.com/williamthorsen/codeassembly-guidance.git",directory:"packages/guidance"},license:"ISC",author:"William Thorsen <william@thorsen.dev> (https://github.com/williamthorsen)",sideEffects:!1,type:"module",exports:{"./package.json":"./package.json","./schemas/*.json":"./schemas/*.json"},bin:{"codeassembly-validate-preferences":"bin/codeassembly-validate-preferences.js"},files:["bin","!bin/__tests__","content","!content/**/__tests__","!content/test-utils","CHANGELOG.md",".meta/changelog.json","schemas"],scripts:{build:"codeassembly bundle-helpers && node scripts/generate-work-types.ts && node scripts/generate-kb-standard-tags.ts","check:content":"codeassembly validate && codeassembly bundle-helpers --check && node scripts/generate-work-types.ts --check && node scripts/generate-kb-standard-tags.ts --check","check:post":"pnpm run check:content","check:strict:post":"pnpm run check:content",prepack:"node scripts/generate-schemas.ts","test:post":"pnpm run test:sh && pnpm run test:smoke","test:sh":"bash scripts/test-sh.sh","test:smoke":"node scripts/__tests__/smoke-test-skill-helpers.ts"},devDependencies:{"@hyperjump/json-schema":"1.18.0","@types/node":"catalog:","@williamthorsen/change-grammar":"catalog:","@williamthorsen/kb":"0.12.0","@williamthorsen/nmr":"catalog:","@williamthorsen/toolbelt.errors":"catalog:","@williamthorsen/toolbelt.terminal":"catalog:","@williamthorsen/toolbelt.testing":"catalog:","@williamthorsen/toolbelt.vitest":"catalog:",codeassembly:"catalog:",esbuild:"catalog:",eslint:"catalog:","happy-dom":"catalog:",marklassian:"1.2.1",ulid:"3.0.2",vitest:"catalog:",yaml:"catalog:",zod:"catalog:"},engines:{node:">=24"},codeassembly:{content:"content"}};import{realpathSync as ki}from"node:fs";import Ni from"node:process";import{fileURLToPath as Il}from"node:url";function Oi(n,e){let t=Ni.argv[1];if(t===void 0)return!1;try{return ki(Il(n))===ki(t)}catch(s){return Ni.stderr.write(`${e}: warning: could not determine entry point: ${ae(s)}
140
140
  `),!0}}a(Oi,"isEntryPoint");function Ci(n,e){let t=Math.max(1,Math.floor(n.length/3)),s;for(let i of e.toSorted()){let r=Pl(n.toLowerCase(),i.toLowerCase());r<=t&&(s===void 0||r<s.distance)&&(s={key:i,distance:r})}return s?.key}a(Ci,"findNearestKey");function Pl(n,e){let t=Array.from({length:e.length+1},(s,i)=>i);for(let s=1;s<=n.length;s++){let i=[s];for(let r=1;r<=e.length;r++){let o=(t[r-1]??0)+(n[s-1]===e[r-1]?0:1);i[r]=Math.min((t[r]??0)+1,(i[r-1]??0)+1,o)}t=i}return t[e.length]??0}a(Pl,"measureEditDistance");function bt(n){let e;for(let t=0;t<n.length;t+=1){let s=n[t];if(s==="\\"&&e!=="'"){t+=1;continue}if(e!==void 0){s===e&&(e=void 0);continue}if(s==='"'||s==="'"){e=s;continue}if(s==="#"&&(t===0||/\s/.test(n[t-1]??"")))return t}return-1}a(bt,"findHashCommentStart");function De(n){let e=0;for(let t of n)t===`
141
141
  `&&(e+=1);return e}a(De,"countNewlines");function V(n,e){let t=0;for(let s=0;s<e&&s<n.length;s+=1)n[s]===`
142
142
  `&&(t+=1);return t}a(V,"countNewlinesBefore");function le(n){let e=[],t=/`+/g,s=t.exec(n);for(;s!==null;){let i=ql(n,t,s[0].length);if(i===null){t.lastIndex=s.index+s[0].length,s=t.exec(n);continue}e.push({start:s.index,end:i.index+i[0].length}),s=t.exec(n)}return e}a(le,"findCodeSpans");function G(n,e){let t=le(n.text),s=[],i=-1;for(let r of n.text.matchAll(e)){let o=r.index;if(t.some(c=>o>=c.start&&o<c.end))continue;let l=Se(n.text,o,o+r[0].length);l.start!==i&&(i=l.start,s.push({line:n.line+V(n.text,l.start),sentence:j(n.text.slice(l.start,l.end))}))}return s}a(G,"findMatchingSentences");function Ti(n,e,t){let s=Se(n,e,t);return j(n.slice(s.start,s.end))}a(Ti,"findSentence");function Se(n,e,t){let s=new RegExp(Pi),i=0,r=s.exec(n);for(;r!==null;){let l=r.index+1;if(l>=t)break;l<=e&&(i=l),r=s.exec(n)}let o=r===null?n.length:Math.max(r.index+1,t);return{start:Li(n,i,o),end:o}}a(Se,"findSentenceBounds");function j(n){return n.replaceAll(/\s+/g," ").trim()}a(j,"flattenWhitespace");function St(n){return Rl(n)>=Ll}a(St,"isProseLiteral");function Ii(n){let e=n.matchAll(Pi).map(i=>i.index+1).toArray();e.at(-1)!==n.length&&e.push(n.length);let t=[],s=0;for(let i of e){let r=Li(n,s,i);r<i&&t.push({start:r,end:i}),s=i}return t}a(Ii,"listSentenceBounds");var Ll=3,Pi=/[.!?](?=\s|$)/g;function Rl(n){return n.split(/\s+/).filter(e=>/[a-z]{2}/i.test(e)).length}a(Rl,"countWords");function ql(n,e,t){let s=e.exec(n);for(;s!==null&&s[0].length!==t;)s=e.exec(n);return s}a(ql,"findClosingRun");function Li(n,e,t){let s=e;for(;s<t&&/\s/.test(n[s]??"");)s+=1;return s}a(Li,"skipWhitespace");var _l=new Set([" "," ","\r"]),Ml=new Set(['"',"'","`"]),Dl=new Set(["(",",","=",":","[","!","&","|","?","{",";","+","-","*","%","<",">"]);function Ri(n,e){let t=[],s;function i(){s!==void 0&&t.push({file:n,line:s.line,text:s.texts.join(`