codeassembly-guidance 0.0.0 → 0.2.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 (219) hide show
  1. package/.meta/changelog.json +1320 -0
  2. package/CHANGELOG.md +315 -0
  3. package/LICENSE +7 -0
  4. package/README.md +195 -1
  5. package/bin/codeassembly-validate-preferences.js +18 -0
  6. package/content/_partials/README.md +192 -0
  7. package/content/_partials/code-descriptions.md +4 -0
  8. package/content/_partials/code-style.md +7 -0
  9. package/content/_partials/comment-discipline.md +89 -0
  10. package/content/_partials/concision.md +3 -0
  11. package/content/_partials/diff-audit-checklist.md +9 -0
  12. package/content/_partials/file-access.md +4 -0
  13. package/content/_partials/live-repo-writes.md +13 -0
  14. package/content/_partials/plain-speech-calibration.md +70 -0
  15. package/content/_partials/plain-speech.md +13 -0
  16. package/content/_partials/prose-line-breaks.md +3 -0
  17. package/content/_partials/record-marker.md +1 -0
  18. package/content/_partials/reduced-object-relative.md +28 -0
  19. package/content/_partials/shell-commands.md +3 -0
  20. package/content/_partials/target-file-set-resolution.md +22 -0
  21. package/content/_partials/technical-recommendations.md +6 -0
  22. package/content/_partials/test-structure-audit-checklist.md +7 -0
  23. package/content/_partials/ticket-assessment-baseline.md +12 -0
  24. package/content/_partials/ticket-assessment.md +202 -0
  25. package/content/_partials/work-type-choice.md +13 -0
  26. package/content/codeassembly-content.yaml +59 -0
  27. package/content/collections/all.md +11 -0
  28. package/content/collections/atlassian.md +17 -0
  29. package/content/collections/recommended.md +41 -0
  30. package/content/collections/triage.md +13 -0
  31. package/content/collections/williamthorsen.md +26 -0
  32. package/content/guidance/README.md +22 -0
  33. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  34. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  35. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  36. package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
  37. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  38. package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
  39. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  40. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  41. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  42. package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
  43. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  44. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  45. package/content/guidance/rulebooks/shell-conventions.md +273 -0
  46. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  47. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  48. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
  49. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  50. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  51. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  52. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  53. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  54. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  55. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  56. package/content/guidance/shared/AGENTS.md +51 -0
  57. package/content/scripts/README.md +44 -0
  58. package/content/scripts/check-branch-currency.mjs +11 -0
  59. package/content/scripts/check-prose.mjs +171 -0
  60. package/content/scripts/describe-change.mjs +165 -0
  61. package/content/scripts/get-ticket-id.sh +131 -0
  62. package/content/scripts/manage-jira-ticket.mjs +214 -0
  63. package/content/scripts/resolve-frontmatter.sh +540 -0
  64. package/content/scripts/resolve-review-run.mjs +12 -0
  65. package/content/scripts/select-lede-exemplars.mjs +208 -0
  66. package/content/scripts/validate-preferences.mjs +146 -0
  67. package/content/skills/_data/action-items.md +83 -0
  68. package/content/skills/_data/artifact-conventions.md +1001 -0
  69. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  70. package/content/skills/_data/branch-currency.md +36 -0
  71. package/content/skills/_data/branch-format.md +34 -0
  72. package/content/skills/_data/change-record.md +163 -0
  73. package/content/skills/_data/complexity-classification.md +58 -0
  74. package/content/skills/_data/concision.md +23 -0
  75. package/content/skills/_data/deployed-file-provenance.md +46 -0
  76. package/content/skills/_data/design-priorities.md +76 -0
  77. package/content/skills/_data/gh-body-file.md +30 -0
  78. package/content/skills/_data/git-commands.md +39 -0
  79. package/content/skills/_data/naming-conventions.md +50 -0
  80. package/content/skills/_data/pr-resolution.md +25 -0
  81. package/content/skills/_data/pr-source-resolution.md +36 -0
  82. package/content/skills/_data/project-stage.md +32 -0
  83. package/content/skills/_data/recommendation-gradient.md +92 -0
  84. package/content/skills/_data/scope-and-deferral.md +83 -0
  85. package/content/skills/_data/spike-conventions.md +89 -0
  86. package/content/skills/_data/ticket-evaluation.md +13 -0
  87. package/content/skills/_data/ticket-id-extraction.md +43 -0
  88. package/content/skills/_data/ticket-source-resolution.md +180 -0
  89. package/content/skills/_data/title-templates.md +632 -0
  90. package/content/skills/_data/title-voice.md +17 -0
  91. package/content/skills/_data/work-types.json +168 -0
  92. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  93. package/content/skills/_partials/action-items.md +22 -0
  94. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  95. package/content/skills/_partials/commit-title-rendering.md +14 -0
  96. package/content/skills/_partials/gh-body-file.md +22 -0
  97. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  98. package/content/skills/_partials/nested-list-indent.md +9 -0
  99. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  100. package/content/skills/_partials/next-steps-after-review.md +350 -0
  101. package/content/skills/_partials/option-format.md +85 -0
  102. package/content/skills/_partials/plan-template.md +97 -0
  103. package/content/skills/_partials/split-launch-prompts.md +5 -0
  104. package/content/skills/_partials/split-ticket-compose.md +5 -0
  105. package/content/skills/_partials/split-ticket-create.md +3 -0
  106. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  107. package/content/skills/_partials/ticket-concision.md +18 -0
  108. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  109. package/content/skills/_partials/ticket-placement.md +14 -0
  110. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  111. package/content/skills/_partials/ticket-skeleton.md +13 -0
  112. package/content/skills/add-change-record/SKILL.md +136 -0
  113. package/content/skills/add-test-ids/SKILL.md +51 -0
  114. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  115. package/content/skills/anti-patterns/SKILL.md +57 -0
  116. package/content/skills/assess-ticket/SKILL.md +46 -0
  117. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  118. package/content/skills/assess-usability/SKILL.md +96 -0
  119. package/content/skills/brainstorming/SKILL.md +107 -0
  120. package/content/skills/capture-event/SKILL.md +108 -0
  121. package/content/skills/capture-event/capture-event.mjs +216 -0
  122. package/content/skills/capture-feedback/SKILL.md +71 -0
  123. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  124. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  125. package/content/skills/classify-complexity/SKILL.md +92 -0
  126. package/content/skills/collaborate/SKILL.md +86 -0
  127. package/content/skills/condense-branch/SKILL.md +83 -0
  128. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  129. package/content/skills/create-commit/SKILL.md +65 -0
  130. package/content/skills/create-devlog/SKILL.md +108 -0
  131. package/content/skills/create-gh-pr/SKILL.md +121 -0
  132. package/content/skills/create-pr/SKILL.md +150 -0
  133. package/content/skills/create-ticket/SKILL.md +395 -0
  134. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  135. package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
  136. package/content/skills/design-and-plan/SKILL.md +197 -0
  137. package/content/skills/development-workflows/SKILL.md +41 -0
  138. package/content/skills/get-ticket-id/SKILL.md +67 -0
  139. package/content/skills/groom-backlog/SKILL.md +247 -0
  140. package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
  141. package/content/skills/implement-plan/SKILL.md +168 -0
  142. package/content/skills/index-prototypes/SKILL.md +200 -0
  143. package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
  144. package/content/skills/kb-add/SKILL.md +157 -0
  145. package/content/skills/kb-add/kb-add.mjs +216 -0
  146. package/content/skills/kb-curate/SKILL.md +119 -0
  147. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  148. package/content/skills/kb-edit/SKILL.md +128 -0
  149. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  150. package/content/skills/kb-retrieve/SKILL.md +100 -0
  151. package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
  152. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  153. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
  154. package/content/skills/kb-update-events/SKILL.md +77 -0
  155. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  156. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  157. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  158. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  159. package/content/skills/merge-pr/SKILL.md +368 -0
  160. package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
  161. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  162. package/content/skills/people-report/SKILL.md +208 -0
  163. package/content/skills/plan/SKILL.md +87 -0
  164. package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
  165. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  166. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
  167. package/content/skills/refine-plan/SKILL.md +263 -0
  168. package/content/skills/refine-prototype/SKILL.md +113 -0
  169. package/content/skills/respond-to-review/SKILL.md +292 -0
  170. package/content/skills/review-bb-pr/SKILL.md +161 -0
  171. package/content/skills/review-branch/SKILL.md +303 -0
  172. package/content/skills/review-criteria/SKILL.md +141 -0
  173. package/content/skills/review-gh-pr/SKILL.md +155 -0
  174. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  175. package/content/skills/review-permissions/SKILL.md +39 -0
  176. package/content/skills/review-pr/SKILL.md +123 -0
  177. package/content/skills/revise-comments/SKILL.md +148 -0
  178. package/content/skills/revise-prose/SKILL.md +197 -0
  179. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  180. package/content/skills/save-artifact/SKILL.md +71 -0
  181. package/content/skills/save-plan/SKILL.md +55 -0
  182. package/content/skills/software-engineering/SKILL.md +74 -0
  183. package/content/skills/streamline-guidance/SKILL.md +174 -0
  184. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  185. package/content/skills/summarize-change/SKILL.md +317 -0
  186. package/content/skills/summarize-chat/SKILL.md +100 -0
  187. package/content/skills/systematic-debugging/SKILL.md +308 -0
  188. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  189. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  190. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  191. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  192. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  193. package/content/skills/systematic-debugging/test-academic.md +16 -0
  194. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  195. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  196. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  197. package/content/skills/testing-conventions/SKILL.md +235 -0
  198. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  199. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  200. package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
  201. package/content/skills/update-jira-ticket/SKILL.md +257 -0
  202. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  203. package/content/skills/update-project-guidance/SKILL.md +300 -0
  204. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  205. package/content/skills/wrap-up/SKILL.md +431 -0
  206. package/content/subagents/_data/claude.yaml +25 -0
  207. package/content/subagents/_data/rovo.yaml +41 -0
  208. package/content/subagents/canary.md +12 -0
  209. package/content/subagents/disposition-challenger.md +78 -0
  210. package/content/subagents/entry-drafter.md +191 -0
  211. package/content/subagents/handoff-reviewer.md +75 -0
  212. package/content/subagents/plan-reviewer.md +184 -0
  213. package/content/subagents/plan-reviser.md +88 -0
  214. package/content/subagents/prose-reviser.md +132 -0
  215. package/content/subagents/ticket-assessor.md +142 -0
  216. package/content/subagents/usability-assessor.md +157 -0
  217. package/package.json +74 -2
  218. package/schemas/preferences.v1.json +321 -0
  219. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,128 @@
1
+ ---
2
+ name: kb-edit
3
+ description: 'Mutate an existing knowledge-base note via a single mechanical operation: bump updated, mark verified, replace tags, append a section, or supersede with another note'
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Edit an existing knowledge-base note
8
+
9
+ Apply a single mutation to a note that already exists in a knowledge base. A bundled helper does the mechanical work: It resolves the writable KB to which the note belongs, loads the note as a typed assertion record, runs alias canonicalization when relevant, applies the change, and writes atomically. You do the judgment work: Pick which operation fits the change, supply the new tags or body content, and decide when supersession is the right move.
10
+
11
+ The split is deliberate: The helper is narrow and mechanical; the operation choice is wide and judgment-driven. Treat the helper as a guardrail. It refuses to write into a KB marked `readonly: true`, refuses a note that does not parse as an assertion, and refuses to leave a half-finished supersede chain.
12
+
13
+ For new notes, use `kb-add`. For finding notes, use `kb-retrieve`. For periodic vault hygiene (broken wikilinks, stale verifications, tag drift), use `kb-curate`.
14
+
15
+ **Announce at start:** "Using kb-edit to {short description of the change}."
16
+
17
+ ## Arguments
18
+
19
+ | Argument | Description | Required |
20
+ | --------------------------- | ----------------------------------------------------------------------------------------------- | -------- |
21
+ | `<path>` | Path to the existing note. Absolute or relative to the cwd. `--add-addressed-by` takes several. | Yes |
22
+ | `--bump-updated` | Set `updated:` to today (UTC). Body unchanged. | One op |
23
+ | `--verify` | Set `last-verified:` to today (UTC). Does **not** bump `updated:`. | One op |
24
+ | `--append` | Append the body read from stdin after a separating blank line, and bump `updated:`. | One op |
25
+ | `--retag <list>` | Replace `tags:` with the comma-separated list. Canonicalizes; does **not** bump `updated:`. | One op |
26
+ | `--add-addressed-by <refs>` | Append comma-separated reference(s) to each target's `addressed-by` list; bumps `updated:`. | One op |
27
+ | `--supersede-with <p>` | Mark `<path>` superseded by `<p>`. Two-file atomic write; both notes bump `updated:`. | One op |
28
+
29
+ A value-bearing flag accepts both `--retag node,react` and `--retag=node,react`. Exactly one operation flag is required per invocation; combining two is rejected with `invalid-args`. The note body for `--append` is read from stdin to EOF; empty or whitespace-only stdin is rejected.
30
+
31
+ `--add-addressed-by` is the one multi-target operation: It accepts one or more `<path>` arguments and appends the same reference(s) to each note's `addressed-by` list. References are free-form (a KB wikilink or relative path, a commit SHA, a PR/issue ref, or a URL); they are stored verbatim and de-duplicated after any existing entries. A reference value that is empty or contains only separators is rejected with `invalid-args`. (Because the value is comma-separated, a reference that itself contains a comma, such as a rare URL, would be split; use one invocation per such reference. A reference that begins with `--` is otherwise read as the next flag, so pass it with the inline `--add-addressed-by=<ref>` form.)
32
+
33
+ ### KB selection
34
+
35
+ The destination knowledge base is inferred by walking up from the note's directory for a `.kb/` folder. The helper does not accept a `--kb` override: The note's location is the selector, and a note outside any discoverable `.kb/` is refused with `missing-destination`. The helper refuses to write into a KB whose `kb.yaml` entry sets `readonly: true`, reporting `readonly-kb`.
36
+
37
+ ## Runtime dependencies
38
+
39
+ - **`node` ≥ 24**: The bundled helper inherits the Node version floor of `@williamthorsen/kb`.
40
+
41
+ ## Modes
42
+
43
+ - **Default mode**: Pick the operation, decide tags/body, present the proposed change to the user, run the helper after confirmation.
44
+ - **Auto mode (`--auto`)**: Pick the operation and supply inputs without asking. The agent never prompts in this mode.
45
+
46
+ The `--auto` flag is for you, not for the bundled helper; it controls whether you present the proposal for confirmation before invoking the helper.
47
+
48
+ ## Operations: When to use each
49
+
50
+ - **`--bump-updated`**: A non-empirical edit to the note (rewording, restructuring, fact correction) in which the body change is made out of band and you want only to refresh `updated:`. Rare on its own; mostly an audit-trail tool.
51
+ - **`--verify`**: You reran the note's instructions or re-confirmed its claims and they still hold. Use this for the "I just checked; still good" path. Does not bump `updated:` because nothing about the content changed.
52
+ - **`--append`**: Add a section to an existing note. The helper writes the new content after the existing body with a separating blank line. Use for accumulating findings or extending a list.
53
+ - **`--retag`**: Replace the tag list wholesale (canonicalized through the KB's `.kb/tag-aliases.yaml`). Use when tags drift, when restructuring categories, or when remediating findings from `kb-curate`. Curatorial: It changes how a record is found, not what it asserts, so it leaves `updated:` unchanged.
54
+ - **`--add-addressed-by`**: Record what addressed a problem by appending references to a record's recall-facing `addressed-by` list so that the response appears when the record is later recalled. Pass several target notes to link one response (a fix note, a PR, a commit) to all the incidents that it resolved in a single run.
55
+ - **`--supersede-with`**: Mark an old note deprecated and point it at its replacement. Both notes' frontmatter is updated atomically (best-effort): The old note gets `superseded-by` and the `deprecated` tag; the new note gets `supersedes`. Use when a note is no longer canonical but should remain discoverable.
56
+
57
+ ## Update semantics: Which operations bump `updated:`
58
+
59
+ `updated:` records the last _substantive_ change to a record (what it asserts, its body, or its lifecycle state). Operations that do not make such a change leave `updated:` untouched. Classify each new operation against this rule deliberately rather than in isolation:
60
+
61
+ - **Bump `updated:`** (substantive change): `--append` (body change), `--add-addressed-by` (records a response relation), and `--supersede-with` (lifecycle-state change). `--bump-updated` is the explicit escape hatch for an out-of-band edit made elsewhere.
62
+ - **Leave `updated:` unchanged** (no substantive change): `--retag` (curatorial: Reorganizes findability only) and `--verify` (re-confirmation: Content is unchanged).
63
+
64
+ ## Process
65
+
66
+ ### 1. Pick the operation
67
+
68
+ Identify which single operation fits the change. If you have several distinct changes in mind (retag and append, say), make them in two separate invocations: The helper rejects combined flags.
69
+
70
+ ### 2. Survey context with kb-retrieve when warranted
71
+
72
+ For `--retag` and `--supersede-with`, run `{skill:kb-retrieve}` for related notes first: A retag is often a vault-wide pattern change worth applying consistently, and a supersession needs the right successor identified.
73
+
74
+ ### 3. Present the proposal (default mode)
75
+
76
+ In default mode, present the note path, the operation, and the operation-specific inputs (new tags, addition body, supersede target). Wait for confirmation or a redirect. In auto mode, skip this step.
77
+
78
+ ### 4. Invoke the helper
79
+
80
+ `--bump-updated`, `--verify`, `--retag`, and `--supersede-with` do not read stdin:
81
+
82
+ ```bash
83
+ node {harness_home_dir}/skills/kb-edit/kb-edit.mjs <path> --bump-updated
84
+ node {harness_home_dir}/skills/kb-edit/kb-edit.mjs <path> --verify
85
+ node {harness_home_dir}/skills/kb-edit/kb-edit.mjs <path> --retag "tag1,tag2"
86
+ node {harness_home_dir}/skills/kb-edit/kb-edit.mjs <old-path> --supersede-with <new-path>
87
+ ```
88
+
89
+ `--add-addressed-by` appends to one or more notes; comma-separate multiple references, space-separate multiple target notes:
90
+
91
+ ```bash
92
+ node {harness_home_dir}/skills/kb-edit/kb-edit.mjs <path> --add-addressed-by "[[how-to-avoid-x]]"
93
+ node {harness_home_dir}/skills/kb-edit/kb-edit.mjs <event-1> <event-2> --add-addressed-by "[[how-to-avoid-x]],#789"
94
+ ```
95
+
96
+ `--append` reads the new body from stdin. A heredoc keeps the addition legible without shell quoting and escaping:
97
+
98
+ ```bash
99
+ cat <<'EOF' | node {harness_home_dir}/skills/kb-edit/kb-edit.mjs <path> --append
100
+ A new section appended to the existing body. The helper adds a separating
101
+ blank line and bumps `updated:` to today (UTC).
102
+ EOF
103
+ ```
104
+
105
+ ### 5. Handle the result
106
+
107
+ The helper prints a JSON object to stdout. On success the payload contains `ok: true`, the resolved `kb`, the written `record`, and (for `--retag`) the `originalTags` / `canonicalTags` audit trail. `--supersede-with` returns `oldRecord` and `newRecord` for both files.
108
+
109
+ `--add-addressed-by` returns a `results` array (one entry per target note, in the order supplied) instead of a single-note payload. Each entry has its own `ok`: A success entry has the written `record`, a failure entry has an `error` code and `message`. Its top-level `ok: true` means the batch ran (without a usage or system error), not that every record succeeded; inspect each `results[]` entry to see which notes were written and which failed, then re-run for the failures (the append de-duplicates, so re-running is safe).
110
+
111
+ On failure, `ok: false` plus a categorical `error` code:
112
+
113
+ | Code | What it means | What to do |
114
+ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
115
+ | `invalid-args` | Missing/extra flags, unknown flag, a second path for a single-target op, empty `--append` stdin, an empty `--add-addressed-by` reference list, or cross-KB supersede. | Correct the invocation. The message names the specific defect. |
116
+ | `missing-destination` | The note's path is not inside any discoverable `.kb/`. | Confirm the path; the note may be outside a KB or the wrong path was supplied. |
117
+ | `note-not-found` | The path does not exist. | Confirm the path. For `--supersede-with`, the _new_ path gets `supersede-target-missing` instead. |
118
+ | `note-parse` | The note's frontmatter is malformed or does not satisfy the assertion contract (YAML error, missing block, or a missing/ill-typed field). | Repair the frontmatter manually; the helper rewrites a note only if it parses as an assertion. |
119
+ | `validation` | The edited record's rendered frontmatter did not re-parse as an assertion (a defensive guard; should not occur for a well-formed note). | Inspect `details.errors`; report the note, which was left unmodified. |
120
+ | `readonly-kb` | The note resolves into a KB marked `readonly: true` in `kb.yaml`. | Switch to a writable KB or update the registry entry intentionally. |
121
+ | `supersede-target-missing` | The `--supersede-with` target path does not exist. | Create the new note (use `kb-add`) before issuing the supersession. |
122
+ | `partial-supersede` | A `--supersede-with` write committed one side, the rollback also failed. | Inspect both paths in `details`; resolve the inconsistency manually before retrying. |
123
+
124
+ System failures (out-of-disk, permission denied) print to stderr and exit non-zero. They are out of band and never appear as a structured `error` code.
125
+
126
+ ## Completion
127
+
128
+ A mutated note at the reported path (two notes for `--supersede-with`, or every successfully-written target for `--add-addressed-by`) conforming to the assertion record contract, plus the canonicalization audit trail for `--retag` so that the user can verify which alias tags were rewritten.