codeassembly-guidance 0.3.0 â 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +64 -0
- package/CHANGELOG.md +23 -0
- package/README.md +17 -34
- package/content/_partials/guidance-change-since-capture.md +9 -0
- package/content/codeassembly-content.yaml +2 -0
- package/content/scripts/check-prose.mjs +1 -1
- package/content/scripts/select-lede-exemplars.mjs +53 -53
- package/content/skills/_data/artifact-conventions.md +8 -3
- package/content/skills/_partials/cluster-feedback-events.md +21 -0
- package/content/skills/capture-event/capture-event.mjs +32 -32
- package/content/skills/curate-feedback/SKILL.md +102 -0
- package/content/skills/curate-feedback/curate-feedback.mjs +211 -0
- package/content/skills/kb-add/kb-add.mjs +53 -53
- package/content/skills/kb-curate/kb-curate.mjs +64 -64
- package/content/skills/kb-edit/kb-edit.mjs +61 -61
- package/content/skills/kb-update-events/kb-update-events.mjs +19 -19
- package/content/skills/lesson-clusters/lesson-clusters.mjs +47 -47
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +75 -75
- package/content/skills/revise-prose/revise-prose.mjs +66 -66
- package/content/skills/save-artifact/SKILL.md +1 -1
- package/content/skills/streamline-guidance/streamline-guidance.mjs +30 -30
- package/content/skills/triage-feedback/SKILL.md +7 -22
- package/content/skills/triage-feedback/triage-feedback.mjs +7 -7
- package/content/skills/triage-spike-findings/SKILL.md +1 -1
- package/content/subagents/feedback-coverage-judge.md +95 -0
- package/content/subagents/feedback-triage-challenger.md +9 -4
- package/package.json +3 -3
- package/schemas/preferences.v1.json +1 -1
- package/schemas/work-types.v1.json +1 -1
package/.meta/changelog.json
CHANGED
|
@@ -1,4 +1,68 @@
|
|
|
1
1
|
[
|
|
2
|
+
{
|
|
3
|
+
"version": "0.4.0",
|
|
4
|
+
"date": "2026-11-02",
|
|
5
|
+
"sections": [
|
|
6
|
+
{
|
|
7
|
+
"title": "ð Features",
|
|
8
|
+
"audience": "all",
|
|
9
|
+
"items": [
|
|
10
|
+
{
|
|
11
|
+
"description": "Adds the `curate-feedback` skill, which has `feedback-coverage-judge` subagents sort each open feedback event into covered, duplicate, obsolete, or kept against guidance pinned at a commit, and then, after approval or under `--apply`, marks every event that is not kept through `kb-update-events` and records the run in a `feedback-curation` artifact. (#2231)",
|
|
12
|
+
"hash": "6bb5907a3426bb91a6f1a4a340b3a4180576a503",
|
|
13
|
+
"entry": 1
|
|
14
|
+
},
|
|
15
|
+
{
|
|
16
|
+
"description": "Adds each covered entry's quote to the `feedback-curation` artifact's events table and to the approval table that `curate-feedback --list` presents, so that the developer can check every covered verdict against its stating sentence before approving the marks. (#2236)",
|
|
17
|
+
"hash": "73c4bd7e28cccf9b4875a18c491993ac371869df",
|
|
18
|
+
"entry": 2
|
|
19
|
+
}
|
|
20
|
+
]
|
|
21
|
+
},
|
|
22
|
+
{
|
|
23
|
+
"title": "ðŠĶ Removed",
|
|
24
|
+
"audience": "all",
|
|
25
|
+
"items": [
|
|
26
|
+
{
|
|
27
|
+
"description": "Remove the factory and the demos (#2234)",
|
|
28
|
+
"body": "Removes the dormant factory visualization package and the catwalk demos, together with the docs, repo-local skills, dependencies, and configuration that only they used. Adds to `docs/repository-split.md` the command that finds the last commit containing the factory, which is the commit from which a revival restores it.",
|
|
29
|
+
"hash": "a2715300691038525090dd8299b4c6602fbba607"
|
|
30
|
+
}
|
|
31
|
+
]
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
"title": "ð Bug fixes",
|
|
35
|
+
"audience": "all",
|
|
36
|
+
"items": [
|
|
37
|
+
{
|
|
38
|
+
"description": "Fixes the issue that the `feedback-coverage-judge` subagent of `curate-feedback` marked a feedback event `obsolete` when the change that removed the event's target had renamed or moved it, or had named a replacement for it. (#2233)",
|
|
39
|
+
"hash": "628e9f86e2b47f4b63922468157f31e4da5c2155",
|
|
40
|
+
"entry": 1
|
|
41
|
+
},
|
|
42
|
+
{
|
|
43
|
+
"description": "Fixes the issue that `curate-feedback validate` accepted a `covered` entry after checking only that the cited guidance file existed, by requiring a verbatim `quote` of the stating sentence and rejecting the entry when the file at the pin does not contain it, ignoring differences in whitespace and in `*`, `_`, and backtick markers. (#2236)",
|
|
44
|
+
"hash": "73c4bd7e28cccf9b4875a18c491993ac371869df",
|
|
45
|
+
"entry": 1
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
"description": "Fixes the issue that `triage-feedback` ranked a feedback cluster by its events even when all of them predated a change to the guidance that governs its lesson, and directs the skill and its `feedback-triage-challenger` subagent to check that guidance's commit history and set such a cluster to `low` unless evidence shows the failure recurring under the changed guidance. (#2243)",
|
|
49
|
+
"hash": "4d16db28a5e06835ecee87bd6d07c758d9ce00b4",
|
|
50
|
+
"entry": 1
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
"description": "Fixes the issue that `triage-feedback` and `triage-spike-findings` accepted a defense against the challenger that rested on grounds other than the evidence named by the challenger's argument. (#2243)",
|
|
54
|
+
"hash": "4d16db28a5e06835ecee87bd6d07c758d9ce00b4",
|
|
55
|
+
"entry": 2
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
"description": "Remove the unshipped `source` export condition from the published packages (#2244)",
|
|
59
|
+
"body": "Removes the `source` export condition from `codeassembly`, `@williamthorsen/kb`, and `codeassembly-run-core`, because it pointed at TypeScript files that their tarballs don't contain, so that a consumer that enables the condition resolves the shipped `dist/` output instead of failing.",
|
|
60
|
+
"hash": "1e1dfc9f376b90956f1c769e0d439a142d43a84b"
|
|
61
|
+
}
|
|
62
|
+
]
|
|
63
|
+
}
|
|
64
|
+
]
|
|
65
|
+
},
|
|
2
66
|
{
|
|
3
67
|
"version": "0.3.0",
|
|
4
68
|
"date": "2026-11-01",
|
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,29 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## 0.4.0 â 2026-11-02
|
|
6
|
+
|
|
7
|
+
### ð Features
|
|
8
|
+
|
|
9
|
+
- Adds the `curate-feedback` skill, which has `feedback-coverage-judge` subagents sort each open feedback event into covered, duplicate, obsolete, or kept against guidance pinned at a commit, and then, after approval or under `--apply`, marks every event that is not kept through `kb-update-events` and records the run in a `feedback-curation` artifact. (#2231)
|
|
10
|
+
- Adds each covered entry's quote to the `feedback-curation` artifact's events table and to the approval table that `curate-feedback --list` presents, so that the developer can check every covered verdict against its stating sentence before approving the marks. (#2236)
|
|
11
|
+
|
|
12
|
+
### ðŠĶ Removed
|
|
13
|
+
|
|
14
|
+
- Remove the factory and the demos (#2234)
|
|
15
|
+
|
|
16
|
+
Removes the dormant factory visualization package and the catwalk demos, together with the docs, repo-local skills, dependencies, and configuration that only they used. Adds to `docs/repository-split.md` the command that finds the last commit containing the factory, which is the commit from which a revival restores it.
|
|
17
|
+
|
|
18
|
+
### ð Bug fixes
|
|
19
|
+
|
|
20
|
+
- Fixes the issue that the `feedback-coverage-judge` subagent of `curate-feedback` marked a feedback event `obsolete` when the change that removed the event's target had renamed or moved it, or had named a replacement for it. (#2233)
|
|
21
|
+
- Fixes the issue that `curate-feedback validate` accepted a `covered` entry after checking only that the cited guidance file existed, by requiring a verbatim `quote` of the stating sentence and rejecting the entry when the file at the pin does not contain it, ignoring differences in whitespace and in `*`, `_`, and backtick markers. (#2236)
|
|
22
|
+
- Fixes the issue that `triage-feedback` ranked a feedback cluster by its events even when all of them predated a change to the guidance that governs its lesson, and directs the skill and its `feedback-triage-challenger` subagent to check that guidance's commit history and set such a cluster to `low` unless evidence shows the failure recurring under the changed guidance. (#2243)
|
|
23
|
+
- Fixes the issue that `triage-feedback` and `triage-spike-findings` accepted a defense against the challenger that rested on grounds other than the evidence named by the challenger's argument. (#2243)
|
|
24
|
+
- Remove the unshipped `source` export condition from the published packages (#2244)
|
|
25
|
+
|
|
26
|
+
Removes the `source` export condition from `codeassembly`, `@williamthorsen/kb`, and `codeassembly-run-core`, because it pointed at TypeScript files that their tarballs don't contain, so that a consumer that enables the condition resolves the shipped `dist/` output instead of failing.
|
|
27
|
+
|
|
5
28
|
## 0.3.0 â 2026-11-01
|
|
6
29
|
|
|
7
30
|
### ð Features
|
package/README.md
CHANGED
|
@@ -5,46 +5,28 @@
|
|
|
5
5
|
The CodeAssembly library of agent guidance: rulebooks, skills, and subagents for coding harnesses, which the [`codeassembly`](../agents/README.md) CLI deploys into Claude Code and Rovo Dev.
|
|
6
6
|
|
|
7
7
|
<!-- section:release-notes -->
|
|
8
|
-
## Release notes â v0.
|
|
8
|
+
## Release notes â v0.4.0 (2026-11-02)
|
|
9
9
|
|
|
10
10
|
### ð Features
|
|
11
11
|
|
|
12
|
-
- Adds
|
|
13
|
-
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- Extends the duplication check in `update-project-guidance` from the global guidance file to rulebooks loaded into the session and to repository files, so that the skill omits what loaded guidance already states and points to a repository file that defines a fact. (#2181)
|
|
21
|
-
- Changes the marker that the `williamthorsen-collaboration-preferences` rulebook and the plan and option-format templates prescribe for a decision awaiting the developer's checkpoint from âģ to ðē, an unchecked box that reads as an item still to approve rather than as work in progress. (#2185)
|
|
22
|
-
- Adds a `defects` field to the JSON output of `consolidate-entries`, which lists each entry whose breaking marker violates its type's policy or whose type the taxonomy does not declare, naming the entry by its 0-based index with the same `policy-violation` and `undeclared-type` kinds that `resolve-merge` reports. (#2186)
|
|
23
|
-
- Directs `summarize-change` to report each entry defect that `consolidate-entries` returns, naming the entry by its `text`, and to continue without changing anything. (#2186)
|
|
24
|
-
- Adds the closing post to `spike-conventions.md`, a ticket comment that contains the answers to the ticket's questions, the recommendations on its decisions, and links to the findings artifact and, when the spike published one, to its page, and names the post in the deliverables of the spike ticket and plan templates. (#2196)
|
|
25
|
-
- Adds an offer of the closing post to the action-items block of the `assess-usability` report step, and replaces the skill's statement that it writes nothing remote with one that names this post, made on consent, as its one remote write. (#2196)
|
|
26
|
-
- Extends the ðŽ Investigate option for a spike plan, shown in the next-steps menu of `design-and-plan`, `plan`, `refine-plan`, and `save-plan`, to end the run with the plan's `## Deliverable`, which includes the offer of the closing post. (#2196)
|
|
27
|
-
- Adds a rule to `artifact-conventions.md` that a conclusion needed by a reader of the ticket is posted on the ticket, while the artifact keeps the evidence. (#2196)
|
|
28
|
-
- Adds the `pr.initial_state` preference (`draft` or `ready`, default `draft`), which `create-pr` reads from the project or global preferences file to open a pull request as a draft or ready for review, and makes `pr.title_format` optional so that a `pr` section can set only the state. (#2198)
|
|
29
|
-
- Adds the `--add-tag` operation to `kb-update-events`, which appends the given tags, canonicalized through the store's alias map, to each named event's tags and leaves an event that already has all of them untouched, unlike `--retag`, which replaces the whole set. (#2208)
|
|
30
|
-
- Adds `--help` to the `kb-update-events` helper, which prints usage describing every operation and exits without updating any event. (#2208)
|
|
31
|
-
- Adds an `--exclude-tag` flag to `kb-retrieve-events` that takes a comma-separated list of tags, matched in canonical or alias form, and drops every event that has any of them; a repeated flag adds to the list. (#2209)
|
|
32
|
-
- Adds a "Standard tags" section, generated from `STANDARD_TAGS`, to the skills that write or filter knowledge-base tags, such as `capture-event` and `kb-update-events`, which directs the agent to tag a record's disposition by a standard name rather than a variant spelling. (#2212)
|
|
33
|
-
- Adds an optional `evidence` field (a stable `key` and the `paths` that it covers) to each item of the `triage-spike-findings` record and an optional `commit` field to the record, which `validate` requires once any item has evidence, and adds to the end of the dispositions comment a hidden, versioned JSON block that the exported `parseEvidenceBlock` function reads back. (#2213)
|
|
34
|
-
- Has the `triage-spike-findings` skill copy each item's evidence key and paths from the findings into the inventory and the record, and set the record's `commit` to the HEAD at which the developer approved the dispositions. (#2213)
|
|
35
|
-
- Adds the `assess-code-health` skill, which measures git hotspots and test coverage for one package or subtree, dispatches five `code-health-assessor` subagents (conventions, structure, extraction, error handling, and tests), and ranks the proposals whose cited evidence resolves against the tree in a `code-health-findings` artifact that `triage-spike-findings` now accepts as input. (#2216)
|
|
36
|
-
- Adds the `triage-feedback` skill, which groups the open events of a feedback store by lesson, shows the top `--limit` clusters with each one's recurrence, impact, and latest capture, has a subagent without session context challenge every priority, and after one approval files a ticket, comments on an open issue that already covers the lesson, defers the cluster, or changes its impact rating. (#2217)
|
|
37
|
-
- Adds the `triage_feedback.defer_days` preference, which sets the number of days for which `triage-feedback` leaves a deferred cluster out of a triage unless the cluster gains a new event, 30 by default. (#2217)
|
|
38
|
-
- Adds the `refine-guidance` skill, which finds the rule that already states a lesson or places a new artifact, drafts the edits for approval, opens a pull request, and marks the lesson's feedback events as addressed by it. (#2227)
|
|
39
|
-
- Adds a "Choosing a kind" section to the `codeassembly-content-specification` rulebook, which states the kind of artifact and the content root in which a lesson belongs, and when to change an existing rule rather than add a parallel one. (#2227)
|
|
12
|
+
- Adds the `curate-feedback` skill, which has `feedback-coverage-judge` subagents sort each open feedback event into covered, duplicate, obsolete, or kept against guidance pinned at a commit, and then, after approval or under `--apply`, marks every event that is not kept through `kb-update-events` and records the run in a `feedback-curation` artifact. (#2231)
|
|
13
|
+
- Adds each covered entry's quote to the `feedback-curation` artifact's events table and to the approval table that `curate-feedback --list` presents, so that the developer can check every covered verdict against its stating sentence before approving the marks. (#2236)
|
|
14
|
+
|
|
15
|
+
### ðŠĶ Removed
|
|
16
|
+
|
|
17
|
+
- Remove the factory and the demos (#2234)
|
|
18
|
+
|
|
19
|
+
Removes the dormant factory visualization package and the catwalk demos, together with the docs, repo-local skills, dependencies, and configuration that only they used. Adds to `docs/repository-split.md` the command that finds the last commit containing the factory, which is the commit from which a revival restores it.
|
|
40
20
|
|
|
41
21
|
### ð Bug fixes
|
|
42
22
|
|
|
43
|
-
- Fixes the issue that the
|
|
44
|
-
- Fixes the issue that `
|
|
45
|
-
- Fixes the issue that `
|
|
46
|
-
- Fixes the issue that
|
|
47
|
-
-
|
|
23
|
+
- Fixes the issue that the `feedback-coverage-judge` subagent of `curate-feedback` marked a feedback event `obsolete` when the change that removed the event's target had renamed or moved it, or had named a replacement for it. (#2233)
|
|
24
|
+
- Fixes the issue that `curate-feedback validate` accepted a `covered` entry after checking only that the cited guidance file existed, by requiring a verbatim `quote` of the stating sentence and rejecting the entry when the file at the pin does not contain it, ignoring differences in whitespace and in `*`, `_`, and backtick markers. (#2236)
|
|
25
|
+
- Fixes the issue that `triage-feedback` ranked a feedback cluster by its events even when all of them predated a change to the guidance that governs its lesson, and directs the skill and its `feedback-triage-challenger` subagent to check that guidance's commit history and set such a cluster to `low` unless evidence shows the failure recurring under the changed guidance. (#2243)
|
|
26
|
+
- Fixes the issue that `triage-feedback` and `triage-spike-findings` accepted a defense against the challenger that rested on grounds other than the evidence named by the challenger's argument. (#2243)
|
|
27
|
+
- Remove the unshipped `source` export condition from the published packages (#2244)
|
|
28
|
+
|
|
29
|
+
Removes the `source` export condition from `codeassembly`, `@williamthorsen/kb`, and `codeassembly-run-core`, because it pointed at TypeScript files that their tarballs don't contain, so that a consumer that enables the condition resolves the shipped `dist/` output instead of failing.
|
|
48
30
|
<!-- /section:release-notes -->
|
|
49
31
|
|
|
50
32
|
## Using the library
|
|
@@ -109,3 +91,4 @@ codeassembly-validate-preferences --strict .agents/preferences.yaml
|
|
|
109
91
|
- [Findings triage helper](docs/triage-spike-findings-helper.md): the helper that the `triage-spike-findings` skill runs.
|
|
110
92
|
- [Code-health helper](docs/assess-code-health-helper.md): the helper that the `assess-code-health` skill runs.
|
|
111
93
|
- [Feedback triage helpers](docs/triage-feedback-helper.md): the helpers that the `triage-feedback` skill runs.
|
|
94
|
+
- [Feedback curation helper](docs/curate-feedback-helper.md): the helper that the `curate-feedback` skill runs.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
A cluster whose events all predate a change to the guidance that governs its lesson is evidence about guidance that no longer exists: It does not show that the failure recurs under the current guidance. Before you judge a cluster's priority, check whether that guidance changed after the cluster's latest capture, `signals.latestCapturedAt` in the clusters file.
|
|
2
|
+
|
|
3
|
+
Check each artifact that states or should state the lesson: the target, every artifact that your search found stating the lesson, and every partial that one of them includes.
|
|
4
|
+
|
|
5
|
+
1. Find the artifact's source file in the repository that owns it. A guidance-library artifact's source is under `packages/guidance/content/` in the CodeAssembly repository, at its path relative to the content root, such as `subagents/entry-drafter.md`.
|
|
6
|
+
2. List the commits on the owning repository's default branch that touched the source file after the latest capture: `gh api 'repos/{owner}/{repo}/commits?path={path}&since={latestCapturedAt}' --jq '.[] | [.sha[0:8], .commit.committer.date, (.commit.message | split("\n")[0])] | @tsv'`. Only when `gh` cannot reach the repository, read a local clone of it at its remote's default branch, never at the checked-out branch, which may predate the change: `git -C {clone} log --first-parent --since={latestCapturedAt} --format='%h %cs %s' origin/HEAD -- {path}`. The clone shows history only up to its last fetch.
|
|
7
|
+
3. Read the message of each listed commit, with `gh api repos/{owner}/{repo}/commits/{sha} --jq .commit.message`, or with `git -C {clone} show --no-patch --format=%B {sha}` on the fallback route. A commit changed the guidance when it changed what the artifact tells the agent to do about the lesson. A commit that only repairs prose, reformats, or renames does not.
|
|
8
|
+
|
|
9
|
+
The guidance changed after the latest capture when at least one commit changed it; name the latest such commit by its short SHA, date, and subject. Otherwise, it did not change.
|
|
@@ -53,6 +53,8 @@ helpers:
|
|
|
53
53
|
out: skills/create-ticket/resolve-ticket-target.mjs
|
|
54
54
|
- entry: ../src/assess-code-health/cli.ts
|
|
55
55
|
out: skills/assess-code-health/assess-code-health.mjs
|
|
56
|
+
- entry: ../src/curate-feedback/cli.ts
|
|
57
|
+
out: skills/curate-feedback/curate-feedback.mjs
|
|
56
58
|
- entry: ../src/lesson-clusters/cli.ts
|
|
57
59
|
out: skills/lesson-clusters/lesson-clusters.mjs
|
|
58
60
|
- entry: ../src/triage-feedback/cli.ts
|
|
@@ -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 Aa=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(),ka=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=ka.visit;C.visitAsync=ka.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 ki={name:"codeassembly-guidance",version:"0.
|
|
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 Aa=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(),ka=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=ka.visit;C.visitAsync=ka.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 ki={name:"codeassembly-guidance",version:"0.4.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/tree/main/packages/guidance#readme",bugs:{url:"https://github.com/williamthorsen/codeassembly/issues"},repository:{type:"git",url:"https://github.com/williamthorsen/codeassembly.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":"workspace:*","@williamthorsen/nmr":"catalog:","@williamthorsen/toolbelt.errors":"catalog:","@williamthorsen/toolbelt.terminal":"catalog:","@williamthorsen/toolbelt.testing":"catalog:",codeassembly:"workspace:*",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 Ai}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 Ai(Il(n))===Ai(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(`
|