codeassembly-guidance 0.5.0 → 0.6.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 (71) hide show
  1. package/.meta/changelog.json +306 -0
  2. package/CHANGELOG.md +73 -0
  3. package/README.md +55 -4
  4. package/content/_partials/finding-grades.md +4 -0
  5. package/content/codeassembly-content.yaml +2 -0
  6. package/content/collections/recommended.md +5 -2
  7. package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
  8. package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
  9. package/content/guidance/rulebooks/cli-conventions.md +17 -2
  10. package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
  11. package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
  12. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  13. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
  14. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
  15. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
  16. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
  17. package/content/scripts/check-prose.mjs +1 -1
  18. package/content/scripts/describe-change.mjs +68 -68
  19. package/content/skills/_data/action-items.md +2 -2
  20. package/content/skills/_data/artifact-conventions.md +20 -10
  21. package/content/skills/_data/concision.md +1 -1
  22. package/content/skills/_data/entry-points.md +37 -0
  23. package/content/skills/_data/recommendation-gradient.md +6 -6
  24. package/content/skills/_data/spike-conventions.md +13 -3
  25. package/content/skills/_data/ticket-source-resolution.md +21 -4
  26. package/content/skills/_data/title-templates.md +4 -4
  27. package/content/skills/_partials/commit-title-rendering.md +2 -1
  28. package/content/skills/_partials/next-steps-after-plan.md +4 -3
  29. package/content/skills/_partials/option-format.md +8 -8
  30. package/content/skills/_partials/plan-template.md +3 -1
  31. package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
  32. package/content/skills/_partials/split-launch-prompts.md +1 -1
  33. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  34. package/content/skills/analyze-performance/SKILL.md +102 -0
  35. package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
  36. package/content/skills/assess-code-health/SKILL.md +16 -14
  37. package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
  38. package/content/skills/assess-usability/SKILL.md +5 -3
  39. package/content/skills/convert-agent-prompt/SKILL.md +60 -0
  40. package/content/skills/create-commit/SKILL.md +10 -5
  41. package/content/skills/create-pr/SKILL.md +11 -11
  42. package/content/skills/create-ticket/SKILL.md +1 -0
  43. package/content/skills/design-and-plan/SKILL.md +2 -2
  44. package/content/skills/implement-plan/SKILL.md +1 -28
  45. package/content/skills/index-prototypes/SKILL.md +36 -17
  46. package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
  47. package/content/skills/investigate-spike/SKILL.md +48 -0
  48. package/content/skills/prepare-prototype-brief/SKILL.md +17 -13
  49. package/content/skills/refine-plan/SKILL.md +7 -4
  50. package/content/skills/refine-prototype/SKILL.md +5 -5
  51. package/content/skills/review-branch/SKILL.md +7 -7
  52. package/content/skills/review-criteria/SKILL.md +3 -3
  53. package/content/skills/review-gh-pr/SKILL.md +1 -1
  54. package/content/skills/revise-prose/SKILL.md +9 -8
  55. package/content/skills/revise-prose/revise-prose.mjs +2 -2
  56. package/content/skills/start-ticket/SKILL.md +27 -0
  57. package/content/skills/summarize-change/SKILL.md +17 -9
  58. package/content/skills/testing-conventions/SKILL.md +12 -1
  59. package/content/skills/triage-spike-findings/SKILL.md +31 -12
  60. package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
  61. package/content/subagents/_data/claude.yaml +3 -0
  62. package/content/subagents/code-health-assessor.md +4 -4
  63. package/content/subagents/disposition-challenger.md +3 -4
  64. package/content/subagents/entry-drafter.md +2 -2
  65. package/content/subagents/handoff-reviewer.md +1 -1
  66. package/content/subagents/prototype-builder.md +69 -0
  67. package/content/subagents/usability-assessor.md +1 -1
  68. package/package.json +5 -4
  69. package/schemas/preferences.v1.json +1 -1
  70. package/schemas/work-types.v1.json +1 -1
  71. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
@@ -1,13 +1,13 @@
1
1
  ---
2
2
  slug: accessibility-conventions
3
- description: 'Accessibility of interfaces: usability before style, contrast and size floors for text, the states that show an element is interactive, and the browser check of a visible change. Consult before writing an artifact page, a prototype, or a mockup, before defining or changing colour tokens, before writing CSS or a UI component, and before finishing or reviewing a change to a visible component.'
3
+ description: 'Accessibility of interfaces: usability before style, contrast and size floors for text, the placement, model, and states of interactive controls, the states for which a reader scans a list, and the browser check of a visible change. Consult before writing an artifact page, a prototype, or a mockup, before designing or placing a control that opens a region or toggles a setting, before designing or reviewing a list, a table, or another surface of repeated items, before defining or changing colour tokens, before writing CSS or a UI component, and before finishing or reviewing a change to a visible component.'
4
4
  delivery: [skill]
5
- version: '2'
5
+ version: '5'
6
6
  ---
7
7
 
8
8
  # Accessibility conventions
9
9
 
10
- Accessibility and usability are requirements, not a finishing touch. Make an interface usable before making it look refined, and when a style choice conflicts with readability or usability, choose usability whatever the aesthetic: "Subtle" and "refined" never justify small or faint text. These conventions apply to a prototype or a mockup exactly as they apply to a released interface.
10
+ Make an interface usable before making it look refined, and when a style choice conflicts with readability or usability, choose usability whatever the aesthetic: "Subtle" and "refined" never justify small or faint text. These conventions apply to a prototype or a mockup exactly as they apply to a released interface.
11
11
 
12
12
  The standard is WCAG 2.2 AA. This rulebook restates only the values that an agent checks while authoring and the rules that WCAG does not set; for everything else, follow WCAG.
13
13
 
@@ -15,10 +15,26 @@ The standard is WCAG 2.2 AA. This rulebook restates only the values that an agen
15
15
 
16
16
  - **Contrast.** Every text colour meets SC 1.4.3 against each surface on which it is set, in each theme that the page defines: 4.5:1, or 3:1 for large text (at least 24px, or at least 18.7px bold).
17
17
  - **Size.** Body text is at least 14px, and secondary text (captions, counts, states, hints) at least 12px. WCAG does not set either floor.
18
- - **Tiers.** Use two text colours, primary and secondary. Add a third only if it meets the same contrast floor; a third tier that passes is within a few shades of the second and adds little.
18
+ - **Tiers.** Use two text colours, primary and secondary. Add a third only if it meets the same contrast floor.
19
19
 
20
20
  Check contrast whenever colour tokens are defined or changed. Compute the WCAG contrast ratio of each text token against each surface token on which it is used, in each theme, compositing any translucent colour or `opacity` over its surface first. Report every failing pair with its ratio, and fix it before presenting the page.
21
21
 
22
+ ## Designing controls
23
+
24
+ - **Named model.** Before designing an affordance, name the established model that the feature most resembles, such as a browser's developer tools, an editor's side panel, or a panel that the product already has, and follow it. Depart from the model only for a reason, and record the reason wherever the design is recorded. Example: An activity drawer follows the editor side-panel model.
25
+ - **Placement.** A control that opens or closes a region sits at that region's edge or in a persistent toolbar, never in an unrelated group of actions. Example: ❌ An "Activity" button among the page header's actions opens a drawer on the right. ✅ The toggle sits at the right end of the toolbar, on the drawer's side.
26
+
27
+ ## Glanceable state
28
+
29
+ A state for which a reader scans a list, a table, or another surface of repeated items, such as expired, failing, selected, in progress, or due soon, is visible without reading each item. Mark it by one or more of these means:
30
+
31
+ - **Colour with a second cue.** A colour paired with a cue that does not rely on colour, such as an icon, a badge, or a weight, per SC 1.4.1.
32
+ - **Symbol.** An icon or a badge beside each item in the state.
33
+ - **Grouping.** A section or a divider that sets the items in the state apart from the rest.
34
+ - **Order.** A sort that brings the items in the state to the top.
35
+
36
+ Text alone does not meet the rule, even in a column of its own: The reader still reads each cell to find the items in the state. A restraint on colour, such as a decision to keep a page calm, governs decoration and never such a state, and a design decision or a prototype verdict that hides one is a defect. Example: ❌ An expiry column that reads "Expired 1 day ago" and "In 200 days" in one style. ✅ Each expired token shows a red badge with a warning icon, and the expired tokens sort first.
37
+
22
38
  ## Interaction states
23
39
 
24
40
  Every element that responds to a click or a key shows that it does:
@@ -27,12 +43,16 @@ Every element that responds to a click or a key shows that it does:
27
43
  - **Hover.** Its appearance changes while the pointer is over it.
28
44
  - **Focus.** A visible indicator marks it while it has keyboard focus, per SC 2.4.7, and the indicator meets the 3:1 non-text contrast of SC 1.4.11 against its surface.
29
45
 
46
+ A button outside a toolbar also looks like a button at rest: It has a border or a fill that meets the 3:1 contrast of SC 1.4.11 against its surface. Only a button inside a toolbar may be borderless text.
47
+
30
48
  A disabled element, whether disabled by the native attribute or by `aria-disabled`, shows neither the hover state nor the pointer.
31
49
 
32
- Put the states in a base style or a shared component rather than setting them at each call site, so that a new element has them without anyone remembering to add them. Do not rely on a framework's or a reset's defaults: Some remove the pointer from a button.
50
+ A control that toggles also shows its on state at rest, by a cue that does not rely on colour alone (SC 1.4.1) and that meets the 3:1 contrast of SC 1.4.11. It exposes the state as `aria-expanded` when it shows or hides a region, and as `aria-pressed` when it switches a setting. Its label names what it governs and stays the same in both states. Example: ❌ "Show activity", which becomes "Hide activity". ✅ "Activity", with `aria-expanded` and a pressed style while the drawer is open.
51
+
52
+ Put the states in a base style or a shared component rather than setting them at each call site. Do not rely on a framework's or a reset's defaults: Some remove the pointer from a button.
33
53
 
34
54
  ## Checking in a browser
35
55
 
36
- Check every change to a visible component in a browser before reporting it finished or reviewed. Open the page, then hover over and tab through each new or changed interactive element, and confirm the three states above, or their absence on a disabled element. A test that renders HTML, or a reading of the diff, does not replace this check: Neither shows what the element looks like under the pointer or with focus.
56
+ Check every change to a visible component in a browser before reporting it finished or reviewed. Open the page, then hover over and tab through each new or changed interactive element, and confirm the three states above, or their absence on a disabled element. Toggle each control that toggles, and confirm its on state and its off state. Confirm that each button outside a toolbar has its border or fill at rest, and scan each new or changed list to confirm that its scanned states are visible without reading each item. A test that renders HTML, or a reading of the diff, does not replace this check: Neither shows what the element looks like under the pointer or with focus.
37
57
 
38
58
  When a browser is not available, report that the check did not run and name the elements that it would have covered. Never report it as passed.
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  slug: cli-conventions
3
- description: 'How a command-line tool talks to its user: subcommands and options, standard option names, configuration, writing modes, help on every command, exit codes, error messages, JSON output, progress and outcome reports, check results, color, the split of logic from presentation, and help topics. Consult before writing or changing any command-line tool, in any language.'
3
+ description: 'How a command-line tool talks to its user: subcommands and options, standard option names, configuration, writing modes, help on every command, exit codes, error messages, unexpected crashes, JSON output, progress and outcome reports, check results, color, the split of logic from presentation, and help topics. Consult before writing or changing any command-line tool, in any language.'
4
4
  delivery: skill
5
- version: '5'
5
+ version: '6'
6
6
  ---
7
7
 
8
8
  # CLI conventions
@@ -124,6 +124,21 @@ Example, for a command that needs an access token:
124
124
  - ❌ `<bin> publish --token <value>`
125
125
  - ✅ `<bin> publish --token-file <path>`, or the token piped to `<bin> publish --token-stdin`
126
126
 
127
+ ## Unexpected crashes
128
+
129
+ An unexpected crash is a bug in the tool, as opposed to a failure that the tool anticipated and reports as an error message.
130
+
131
+ - **A last-resort handler reports a crash as `<bin>: internal error: <message>` on stderr, followed by the stack frames.** The prefix follows "Error messages", and `internal error` tells the reader that the fault is the tool's.
132
+ - **The stack frames are always printed, not only under a debug flag.** A crash may not reproduce, and the stack frames are where a bug report starts.
133
+ - **A thrown value that is not an error is reported by its string form**, without stack frames, because it does not have any.
134
+ - **A crash exits 1**, as "Any other failure while running" in the exit-code table states.
135
+ - **A handled error never takes the crash shape, and a crash never takes the shape of a handled error**, so that a reader can tell a bug in the tool from a mistake in their own input.
136
+
137
+ Example, for a crash caused by reading a property of an undefined value:
138
+
139
+ - ❌ `Error: Cannot read properties of undefined (reading 'name')`, which reads as a handled error
140
+ - ✅ `<bin>: internal error: Cannot read properties of undefined (reading 'name')`, followed by the stack frames
141
+
127
142
  ## JSON output
128
143
 
129
144
  - **A command whose output a script or an agent may read supports `--json`.** Parsing text written for a person breaks when its wording changes.
@@ -3,7 +3,7 @@ slug: codeassembly-content-specification
3
3
  description: The declaration contract and authoring doctrine for CodeAssembly skills, subagents, rulebooks, and collections -- frontmatter, dependencies, invocation tokens, how broad a guidance change goes, which kind of artifact it goes in, and when a procedure belongs in a helper.
4
4
  standalone: wanted by repositories that author CodeAssembly content, which declare it directly
5
5
  delivery: skill
6
- version: '32'
6
+ version: '33'
7
7
  ---
8
8
 
9
9
  # CodeAssembly content specification
@@ -105,25 +105,25 @@ members:
105
105
 
106
106
  ### Dispositions
107
107
 
108
- A `disposition:` states what membership in a collection that enumerates its members claims about them, and `codeassembly validate` holds the root to that claim. A collection without one is a plain bundle: Its membership does not claim anything, so it neither covers an artifact nor conflicts with a disposition.
108
+ A `disposition:` states what membership in a collection that enumerates its members claims about them, and `codeassembly validate` checks the root against that claim. A collection without one is a plain bundle: Its membership does not claim anything, so it neither covers an artifact nor conflicts with a disposition.
109
109
 
110
- - `public`: Its members are generally fit. Its closure may reach only the members of public collections.
111
- - `personal`: Its members are fitted to one author. Its closure may reach the members of personal and public collections.
112
- - `opt-in`: Its members are fitted to one vendor ecosystem. Its closure may reach its own members and the members of public collections, and the closure of every other collection, other than an `'@library'` one, must not reach its members, so that only a consumer declaring it deploys them.
110
+ - `public`: Its members are generally fit. Its closure may include only the members of public collections.
111
+ - `personal`: Its members are fitted to one author. Its closure may include the members of personal and public collections.
112
+ - `opt-in`: Its members are fitted to one vendor ecosystem. Its closure may include its own members and the members of public collections, and the closure of every other collection, other than an `'@library'` one, must not include its members, so that only a consumer declaring it deploys them.
113
113
 
114
- An artifact that is deliberately outside every collection declares `standalone:` in its own frontmatter, with the reason as the value. A collection must not enumerate it, and the closure of a collection, other than an `'@library'` one, must not reach it. An artifact that several collections claim is within a closure's reach when any one of its claims is. `disposition:` on a collection whose members are computed, `standalone:` on a collection, and `disposition:` on any other type are errors.
114
+ An artifact that is deliberately outside every collection declares `standalone:` in its own frontmatter, with the reason as the value. A collection must not enumerate it, and the closure of a collection, other than an `'@library'` one, must not include it. A closure may include an artifact that several collections claim when it may include the members of any one of those collections. `disposition:` on a collection whose members are computed, `standalone:` on a collection, and `disposition:` on any other type are errors.
115
115
 
116
116
  `validate` checks a root that declares a disposition, a standalone artifact, or an `'@unclaimed'` collection, and reports each of these as a `disposition` defect:
117
117
 
118
- - a standalone artifact that a collection enumerates, or that the closure of a collection other than an `'@library'` one reaches
119
- - a collection with a disposition whose closure reaches an artifact outside its reach
120
- - a collection, other than an `'@library'` one, whose closure reaches a member of an opt-in collection other than itself
118
+ - a standalone artifact that a collection enumerates, or that the closure of a collection other than an `'@library'` one includes
119
+ - a collection with a disposition whose closure includes an artifact that its disposition does not permit
120
+ - a collection, other than an `'@library'` one, whose closure includes a member of an opt-in collection other than itself
121
121
  - in a root without an `'@unclaimed'` collection, an artifact that is not covered by any disposition
122
122
  - a `disposition:` or `standalone:` value that cannot be read
123
123
 
124
124
  ## Frontmatter fields
125
125
 
126
- - **Rulebooks:** `slug`, optional `description`, required `delivery` (`ambient`, `hook`, `skill`, or a non-empty list of them; `ambient` only when nearly every session needs the content, since an ambient rulebook is loaded by every session that declares it, and `skill` or `hook` otherwise), optional `skill-name`, optional `supported-harnesses` (a harness id or list restricting every delivery mode to those harnesses; absent deploys to all), optional `version`. A declared `version` is an opaque string, never parsed as semver, and every route that delivers the rulebook names it on a `<!-- rulebook-version: <version> -->` line directly below the marker that names the slug, so that an agent can read which version of a rulebook it has. A route omits the line for a rulebook that does not declare a version. Quote the value: YAML reads an unquoted `1.10` as the number `1.1`, and the schema rejects a non-string rather than deploying the digits that it lost. It rejects a value that the version line cannot contain on its own, which is a blank one, a multi-line one, and one containing `-->`.
126
+ - **Rulebooks:** `slug`, optional `description`, required `delivery` (`ambient`, `hook`, `skill`, or a non-empty list of them; `ambient` only when nearly every session needs the content, since an ambient rulebook is loaded by every session that declares it, and `skill` or `hook` otherwise), optional `skill-name`, optional `supported-harnesses` (a harness id or list restricting every delivery mode to those harnesses; absent deploys to all), optional `version`. A declared `version` is an opaque string, never parsed as semver, and every delivery mode of the rulebook names it on a `<!-- rulebook-version: <version> -->` line directly below the marker that names the slug, so that an agent can read which version of a rulebook it has. A rulebook that does not declare a version does not have the line in any delivery mode. Quote the value: YAML reads an unquoted `1.10` as the number `1.1`, and the schema rejects a non-string rather than deploying the digits that it lost. It rejects a value that the version line cannot contain on its own, which is a blank one, a multi-line one, and one containing `-->`.
127
127
  - **Skills:** `name`, `description`, optional `user-invocable` (defaults to `true`), optional `supported-harnesses` (a harness id or list restricting deployment to those harnesses; absent deploys to all). The deploy writes every other key to every harness unchanged, so a key that only one harness reads, such as Claude's `context` or `model`, is also written to the others, which ignore it.
128
128
  - **Subagents:** `name`, `description`, optional `tools`, optional `disallowedTools`, optional `maxTurns`, optional `skills` (skills injected into the subagent's context), optional `rulebooks` (rulebooks injected the same way, named by slug rather than by deploy name, so that a `skill-name` override on the target stays correct). `sync` pulls both lists into the deploy closure, merges each injected rulebook's deploy name into the deployed `skills:`, and drops the `rulebooks:` key from what it writes.
129
129
  - **Collections:** `name`, `description`, a `members:` block, and an optional `disposition`; see [Dispositions](#dispositions).
@@ -192,7 +192,7 @@ A sweep version is a positive integer, and a new rule starts at `1`. Raise it wh
192
192
 
193
193
  ## Guidance hooks
194
194
 
195
- When a step's guidance is a matter of local taste rather than library doctrine -- such as a user's code-style preferences, or a project's own glossary -- neither a pointer to a stated rule nor an inlined partial fits: A pointer sends the agent away to fetch the rule, and an inlined partial fixes one answer for every consumer at authoring time. Declare a guidance hook instead, `<!-- guidance-hook: <name> -->`, and leave the slot for a `codeassembly.yaml` to bind per project or per machine. An unbound hook contributes nothing to deployed output, so declaring one is safe wherever nothing fills it. A rulebook written for that slot declares `delivery: hook`, which records the route and lets `sync` report a binding and a delivery that disagree. The directive grammar is specified in `content/_partials/README.md` and the binding syntax in `packages/agents/docs/project-declaration.md`. _(Convention; not enforced.)_
195
+ When a step's guidance is a matter of local taste rather than library doctrine -- such as a user's code-style preferences, or a project's own glossary -- neither a pointer to a stated rule nor an inlined partial fits: A pointer sends the agent away to fetch the rule, and an inlined partial fixes one answer for every consumer at authoring time. Declare a guidance hook instead, `<!-- guidance-hook: <name> -->`, and leave the slot for a `codeassembly.yaml` to bind per project or per machine. An unbound hook contributes nothing to deployed output, so declaring one is safe wherever nothing fills it. A rulebook written for that slot declares `delivery: hook`, which records the delivery mode and lets `sync` report a binding and a delivery that disagree. The directive grammar is specified in `content/_partials/README.md` and the binding syntax in `packages/agents/docs/project-declaration.md`. _(Convention; not enforced.)_
196
196
 
197
197
  ## Injection-point placement
198
198
 
@@ -0,0 +1,85 @@
1
+ ---
2
+ slug: machine-readable-output-conventions
3
+ description: 'Results that a program shows to a person and that an agent or a script also reads: one result object under every renderer, the scope test, canonical values, the command-line case, structured data beside a result on a page, formats, sensitive fields, a journal of domain events, and the TypeScript packages that implement them. Consult before writing a command, a page, a dialog, or a component that shows a person a result, a report, or a confirmation, and before building an app whose state an agent or an end-to-end test verifies.'
4
+ delivery: [skill]
5
+ version: '2'
6
+ ---
7
+
8
+ # Machine-readable output conventions
9
+
10
+ A result that a program shows to a person has a second reader: an agent or a script that drives the program and needs the same facts as data. When the facts exist only in their presentational form, that reader parses prose or an accessibility tree, and the parse breaks when the wording or the formatting changes. These rules make every such result available in both forms without letting the two disagree.
11
+
12
+ These rules apply whatever language, framework, or library implements them.
13
+
14
+ ## Principle
15
+
16
+ - **A result is one object.** The program's logic produces it, and every form of it, for a person or for a machine, is a renderer over that object.
17
+ - **Every renderer reads the same object.** Two renderers cannot disagree about a fact, because neither one computes it, and each renderer can be tested without running the program.
18
+
19
+ ## Scope
20
+
21
+ - **The rules cover a result that a person would otherwise transcribe:** a created thing, a report, a check outcome, or a confirmation.
22
+ - **They cover a view of state that an agent needs in order to verify its own action**, such as the record that a form submission changed.
23
+ - **They do not cover a screen's ordinary content**, such as a table, a list, or a tooltip.
24
+
25
+ ## Canonical values
26
+
27
+ Each value in the object is in canonical form, and a renderer for a person formats it.
28
+
29
+ - **Timestamps** are ISO 8601 with an offset.
30
+ - **Numbers** are unformatted, and the field name states the unit: `ttlSeconds: 604800`, not `ttl: "7 days"`.
31
+ - **References** are ids, not display names.
32
+ - **Enumerated values** are codes, not labels.
33
+
34
+ Example, for the expiry of a created token:
35
+
36
+ - ❌ `{"expires": "Nov 12, 2026 (in 7 days)"}`
37
+ - ✅ `{"expiresAt": "2026-11-12T00:00:00Z"}`, which the dialog renders as "Nov 12, 2026 (in 7 days)"
38
+
39
+ ## Command-line output
40
+
41
+ A command-line tool exposes its result through `--json`, as the "JSON output" section of {rulebook:cli-conventions} states, and splits its logic from its presentation as that rulebook's "Logic and presentation" section states.
42
+
43
+ ## Results on a page
44
+
45
+ A result that a page shows to a person is also available as structured data, in two forms that serialize the same object:
46
+
47
+ - **A revealable element.** A tab, a pane, or a drawer beside the result shows the data and copies it with one click.
48
+ - **Embedded data.** The page embeds the data in the DOM, in a `<script type="application/json">` element or a `data-` attribute on the result's container, so that a driven browser reads it without revealing or clicking anything.
49
+
50
+ The embedded data is part of the page's interface: A published field follows the same rule that {rulebook:cli-conventions} states for a field of `--json` output.
51
+
52
+ ## Formats
53
+
54
+ - **JSON is required.** It is the canonical, lossless form, and it is the form that the page embeds.
55
+ - **YAML and Markdown are optional renderers** over the same object. Because a YAML renderer adds a dependency, an app includes one only when a person asks for it.
56
+
57
+ ## Sensitive fields
58
+
59
+ - **The result type marks a sensitive field**, such as a secret.
60
+ - **The copy and the embedded data redact a sensitive field by default.** Embedded data reaches page snapshots, test traces, and logs, which outlive the page and reach readers other than the person viewing it.
61
+ - **Including a sensitive field is an explicit act**, such as turning on an "Include secret" control beside the copy.
62
+ - **Redacted data names what it leaves out**, so that a reader can tell a redacted field from an absent one.
63
+
64
+ Example, for the copy of a created token:
65
+
66
+ - ❌ "Copy JSON" copies the token with its secret.
67
+ - ✅ "Copy JSON" copies the token without `secret` and with `"redacted": ["secret"]`, until the person turns on "Include secret".
68
+
69
+ ## Journal
70
+
71
+ An app that an agent or an end-to-end test must verify after a person's actions keeps a journal of what those actions did.
72
+
73
+ - **An entry records a domain event, not a raw action:** "token created", not "button clicked".
74
+ - **A pure function derives each entry** from the state before the action, the action, and the state after it.
75
+ - **An entry has an id, a timestamp, a type, the ids of its subjects, and canonical data.** The sentence that a person reads and the JSON are two renderers over the entry.
76
+ - **The app never reads its journal to compute state.** The state stays the one source of truth, and the journal records what changed in it.
77
+ - **The journal is a test oracle.** An end-to-end test or an agent reads it to confirm what happened, and the app exposes it as it exposes any other result.
78
+
79
+ ## TypeScript packages
80
+
81
+ Three packages implement these rules, and an implementation in TypeScript can start from them. The rules above remain the contract, whether or not an implementation uses them. Each package's README states its API.
82
+
83
+ - **[`@williamthorsen/readout`](https://github.com/williamthorsen/showroom/tree/main/packages/readout#readme)** supplies the result type, with its sensitive fields marked; a JSON serializer that redacts them and names what it leaves out; the escaping that embedded data needs; and typed renderers over the result. It implements "Formats", "Sensitive fields", and the embedded data of "Results on a page".
84
+ - **[`@williamthorsen/readout-journal`](https://github.com/williamthorsen/showroom/tree/main/packages/readout-journal#readme)** supplies a journal that a wrapped reducer derives from each state transition, its JSON form, and a renderer for each entry type. It implements "Journal".
85
+ - **[`@williamthorsen/readout-react`](https://github.com/williamthorsen/showroom/tree/main/packages/readout-react#readme)** supplies React components for a copy button, a JSON view, a view that reveals a result's data beside the result, and a drawer that lists the journal. It implements the revealable element of "Results on a page" in a React app.
@@ -2,7 +2,7 @@
2
2
  slug: ui-copy-conventions
3
3
  description: 'Text in a product surface: written for the person who returns to the page, with rules for labels, helper text, errors, and empty states, and a copy budget. Consult before writing labels, helper text, messages, or empty states for a page, a prototype, or a UI component.'
4
4
  delivery: [skill]
5
- version: '1'
5
+ version: '2'
6
6
  ---
7
7
 
8
8
  # UI copy conventions
@@ -13,7 +13,7 @@ When a project names its own content guidelines, such as a design system's, thos
13
13
 
14
14
  ## Rules
15
15
 
16
- - **Labels** are nouns. **Buttons** are verbs that name the action that they perform.
16
+ - **Labels** are nouns. **Buttons** are verbs that name the action that they perform, except a toggle, whose label names what it governs and stays the same in both states, as {rulebook:accessibility-conventions} states.
17
17
  - **Helper text** states a constraint or a consequence: the format that a field accepts, or what an action changes.
18
18
  - **An error** names the problem and the fix.
19
19
  - **Register.** A sentence never explains the page, reassures, congratulates, or narrates the reader ("you are done", "you can…").
@@ -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
 
@@ -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
 
@@ -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.6.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:","@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(`