codeassembly-guidance 0.0.0 → 0.1.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 (204) hide show
  1. package/.meta/changelog.json +563 -0
  2. package/CHANGELOG.md +134 -0
  3. package/LICENSE +7 -0
  4. package/README.md +165 -1
  5. package/content/_partials/README.md +192 -0
  6. package/content/_partials/code-descriptions.md +4 -0
  7. package/content/_partials/code-style.md +7 -0
  8. package/content/_partials/comment-discipline.md +89 -0
  9. package/content/_partials/concision.md +3 -0
  10. package/content/_partials/diff-audit-checklist.md +9 -0
  11. package/content/_partials/file-access.md +4 -0
  12. package/content/_partials/live-repo-writes.md +13 -0
  13. package/content/_partials/plain-speech-calibration.md +66 -0
  14. package/content/_partials/plain-speech.md +13 -0
  15. package/content/_partials/prose-line-breaks.md +3 -0
  16. package/content/_partials/record-marker.md +1 -0
  17. package/content/_partials/reduced-object-relative.md +28 -0
  18. package/content/_partials/shell-commands.md +3 -0
  19. package/content/_partials/target-file-set-resolution.md +22 -0
  20. package/content/_partials/technical-recommendations.md +5 -0
  21. package/content/_partials/test-structure-audit-checklist.md +7 -0
  22. package/content/_partials/ticket-assessment-baseline.md +12 -0
  23. package/content/_partials/ticket-assessment.md +202 -0
  24. package/content/_partials/work-type-choice.md +13 -0
  25. package/content/codeassembly-content.yaml +49 -0
  26. package/content/collections/all.md +11 -0
  27. package/content/collections/atlassian.md +16 -0
  28. package/content/collections/recommended.md +34 -0
  29. package/content/collections/triage.md +77 -0
  30. package/content/collections/williamthorsen.md +25 -0
  31. package/content/guidance/README.md +22 -0
  32. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  33. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  34. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  35. package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
  36. package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
  37. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  38. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  39. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  40. package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
  41. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  42. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  43. package/content/guidance/rulebooks/shell-conventions.md +279 -0
  44. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  45. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
  46. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  47. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  48. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  49. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  50. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  51. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  52. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  53. package/content/guidance/shared/AGENTS.md +43 -0
  54. package/content/scripts/README.md +41 -0
  55. package/content/scripts/describe-change.mjs +165 -0
  56. package/content/scripts/get-ticket-id.sh +131 -0
  57. package/content/scripts/manage-jira-ticket.mjs +209 -0
  58. package/content/scripts/resolve-frontmatter.sh +540 -0
  59. package/content/scripts/resolve-review-run.mjs +12 -0
  60. package/content/scripts/select-lede-exemplars.mjs +208 -0
  61. package/content/skills/_data/action-items.md +83 -0
  62. package/content/skills/_data/artifact-conventions.md +969 -0
  63. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  64. package/content/skills/_data/branch-format.md +34 -0
  65. package/content/skills/_data/change-record.md +163 -0
  66. package/content/skills/_data/complexity-classification.md +58 -0
  67. package/content/skills/_data/concision.md +23 -0
  68. package/content/skills/_data/deployed-file-provenance.md +46 -0
  69. package/content/skills/_data/design-priorities.md +76 -0
  70. package/content/skills/_data/gh-body-file.md +30 -0
  71. package/content/skills/_data/git-commands.md +39 -0
  72. package/content/skills/_data/naming-conventions.md +50 -0
  73. package/content/skills/_data/pr-resolution.md +25 -0
  74. package/content/skills/_data/pr-source-resolution.md +36 -0
  75. package/content/skills/_data/recommendation-gradient.md +90 -0
  76. package/content/skills/_data/scope-and-deferral.md +83 -0
  77. package/content/skills/_data/spike-conventions.md +89 -0
  78. package/content/skills/_data/ticket-evaluation.md +13 -0
  79. package/content/skills/_data/ticket-id-extraction.md +43 -0
  80. package/content/skills/_data/ticket-source-resolution.md +147 -0
  81. package/content/skills/_data/title-templates.md +624 -0
  82. package/content/skills/_data/title-voice.md +17 -0
  83. package/content/skills/_data/work-types.json +168 -0
  84. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  85. package/content/skills/_partials/action-items.md +22 -0
  86. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  87. package/content/skills/_partials/commit-title-rendering.md +14 -0
  88. package/content/skills/_partials/gh-body-file.md +22 -0
  89. package/content/skills/_partials/nested-list-indent.md +9 -0
  90. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  91. package/content/skills/_partials/next-steps-after-review.md +350 -0
  92. package/content/skills/_partials/option-format.md +84 -0
  93. package/content/skills/_partials/plan-template.md +97 -0
  94. package/content/skills/_partials/split-launch-prompts.md +5 -0
  95. package/content/skills/_partials/split-ticket-compose.md +5 -0
  96. package/content/skills/_partials/split-ticket-create.md +3 -0
  97. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  98. package/content/skills/_partials/ticket-concision.md +18 -0
  99. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  100. package/content/skills/_partials/ticket-placement.md +14 -0
  101. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  102. package/content/skills/_partials/ticket-skeleton.md +13 -0
  103. package/content/skills/add-change-record/SKILL.md +136 -0
  104. package/content/skills/add-test-ids/SKILL.md +51 -0
  105. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  106. package/content/skills/anti-patterns/SKILL.md +57 -0
  107. package/content/skills/assess-ticket/SKILL.md +46 -0
  108. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  109. package/content/skills/brainstorming/SKILL.md +107 -0
  110. package/content/skills/capture-event/SKILL.md +108 -0
  111. package/content/skills/capture-event/capture-event.mjs +216 -0
  112. package/content/skills/capture-feedback/SKILL.md +71 -0
  113. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  114. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  115. package/content/skills/classify-complexity/SKILL.md +92 -0
  116. package/content/skills/collaborate/SKILL.md +86 -0
  117. package/content/skills/condense-branch/SKILL.md +83 -0
  118. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  119. package/content/skills/create-commit/SKILL.md +65 -0
  120. package/content/skills/create-devlog/SKILL.md +108 -0
  121. package/content/skills/create-gh-pr/SKILL.md +106 -0
  122. package/content/skills/create-pr/SKILL.md +150 -0
  123. package/content/skills/create-ticket/SKILL.md +350 -0
  124. package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
  125. package/content/skills/design-and-plan/SKILL.md +194 -0
  126. package/content/skills/development-workflows/SKILL.md +41 -0
  127. package/content/skills/get-ticket-id/SKILL.md +67 -0
  128. package/content/skills/groom-backlog/SKILL.md +245 -0
  129. package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
  130. package/content/skills/implement-plan/SKILL.md +164 -0
  131. package/content/skills/index-prototypes/SKILL.md +145 -0
  132. package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
  133. package/content/skills/kb-add/SKILL.md +156 -0
  134. package/content/skills/kb-add/kb-add.mjs +216 -0
  135. package/content/skills/kb-curate/SKILL.md +117 -0
  136. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  137. package/content/skills/kb-edit/SKILL.md +128 -0
  138. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  139. package/content/skills/kb-retrieve/SKILL.md +100 -0
  140. package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
  141. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  142. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
  143. package/content/skills/kb-update-events/SKILL.md +77 -0
  144. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  145. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  146. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  147. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  148. package/content/skills/merge-pr/SKILL.md +368 -0
  149. package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
  150. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  151. package/content/skills/people-report/SKILL.md +208 -0
  152. package/content/skills/plan/SKILL.md +87 -0
  153. package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
  154. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  155. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
  156. package/content/skills/refine-plan/SKILL.md +259 -0
  157. package/content/skills/respond-to-review/SKILL.md +292 -0
  158. package/content/skills/review-bb-pr/SKILL.md +161 -0
  159. package/content/skills/review-branch/SKILL.md +301 -0
  160. package/content/skills/review-criteria/SKILL.md +108 -0
  161. package/content/skills/review-gh-pr/SKILL.md +155 -0
  162. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  163. package/content/skills/review-permissions/SKILL.md +39 -0
  164. package/content/skills/review-pr/SKILL.md +123 -0
  165. package/content/skills/revise-comments/SKILL.md +115 -0
  166. package/content/skills/revise-prose/SKILL.md +197 -0
  167. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  168. package/content/skills/save-artifact/SKILL.md +69 -0
  169. package/content/skills/save-plan/SKILL.md +55 -0
  170. package/content/skills/software-engineering/SKILL.md +74 -0
  171. package/content/skills/streamline-guidance/SKILL.md +174 -0
  172. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  173. package/content/skills/summarize-change/SKILL.md +308 -0
  174. package/content/skills/summarize-chat/SKILL.md +100 -0
  175. package/content/skills/systematic-debugging/SKILL.md +308 -0
  176. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  177. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  178. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  179. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  180. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  181. package/content/skills/systematic-debugging/test-academic.md +16 -0
  182. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  183. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  184. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  185. package/content/skills/testing-conventions/SKILL.md +168 -0
  186. package/content/skills/testing-conventions/mistakes.md +1 -0
  187. package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
  188. package/content/skills/update-jira-ticket/SKILL.md +245 -0
  189. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  190. package/content/skills/update-project-guidance/SKILL.md +300 -0
  191. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  192. package/content/skills/wrap-up/SKILL.md +431 -0
  193. package/content/subagents/_data/claude.yaml +19 -0
  194. package/content/subagents/_data/rovo.yaml +31 -0
  195. package/content/subagents/canary.md +11 -0
  196. package/content/subagents/entry-drafter.md +187 -0
  197. package/content/subagents/handoff-reviewer.md +75 -0
  198. package/content/subagents/plan-reviewer.md +184 -0
  199. package/content/subagents/plan-reviser.md +88 -0
  200. package/content/subagents/prose-reviser.md +130 -0
  201. package/content/subagents/ticket-assessor.md +139 -0
  202. package/package.json +70 -2
  203. package/schemas/preferences.v1.json +294 -0
  204. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,540 @@
1
+ #!/usr/bin/env bash
2
+ # Emits canonical artifact-frontmatter fields as YAML (default) or JSON.
3
+ #
4
+ # Takes session-level fields from the branch manifest emitted by the deployed `derive-session-context` helper, which
5
+ # composes it from the current preferences on every call, and runs git for the rest. `resolve_bundle_path` locates the
6
+ # helper.
7
+ #
8
+ # Flags:
9
+ # --skill NAME provenance.skill value (required in yaml mode).
10
+ # --interactive true|false provenance.isInteractive value (required in yaml mode).
11
+ # --model ID provenance.model value (optional).
12
+ # --extra KEY=VALUE Append a scalar extension key (repeatable).
13
+ # Values may contain `=`; split on the first `=`.
14
+ # --extra-list KEY=v1,v2,… Append a flow-list extension key (repeatable).
15
+ # Values are split on `,`, so an item containing a
16
+ # comma splits; use --extra-list-item for those.
17
+ # --extra-list-item KEY=V Append one item to a flow-list extension key
18
+ # (repeatable). Because items accumulate in the
19
+ # order given and are never split, an item may
20
+ # contain `,`.
21
+ # --override KEY=VALUE Force a canonical/provenance field to VALUE.
22
+ # Empty VALUE force-omits the key.
23
+ # --format yaml|json Output format (default `yaml`).
24
+ # --help, -h Show usage and exit 0.
25
+ #
26
+ # Output (yaml mode, stdout): A complete YAML frontmatter block including
27
+ # `---` delimiters. Field order:
28
+ #
29
+ # provenance:
30
+ # skill, timestamp, baseSha, isInteractive, model (camelCase)
31
+ # ticket_id, ticket_ref, branch, commit, pr, run_id (snake_case)
32
+ # {--extra / --extra-list / --extra-list-item extensions in insertion order}
33
+ #
34
+ # Output (json mode, stdout): A single JSON object. Keys: branch, commit,
35
+ # baseSha, pr, ticket_id, ticket_ref, scm, timestamp, run_id.
36
+ #
37
+ # Omission rules (both formats): Any key whose resolved value is empty is
38
+ # omitted entirely. `--override KEY=` with empty value force-omits even
39
+ # when the script resolved a value.
40
+ #
41
+ # The script resolves neither `pr` nor `run_id`. Each is populated only when a
42
+ # caller passes `--override pr=<url>` or `--override run_id=<id>`.
43
+ #
44
+ # Exit codes:
45
+ # 0 Success.
46
+ # 1 Git could not read the repository or resolve the branch, missing required commands (`jq`, `git`),
47
+ # required-arg violation in yaml mode, or the `derive-session-context` helper could not be found or itself failed.
48
+
49
+ set -euo pipefail
50
+
51
+ readonly PROG="$(basename "$0")"
52
+
53
+ show_usage() {
54
+ local exit_code="${1:-1}"
55
+ cat <<EOF
56
+ Usage:
57
+ $PROG --skill NAME --interactive true|false [--model ID]
58
+ [--extra KEY=VALUE ...] [--extra-list KEY=v1,v2,... ...]
59
+ [--extra-list-item KEY=VALUE ...]
60
+ [--override KEY=VALUE ...] [--format yaml|json]
61
+ $PROG --format json
62
+ $PROG --help
63
+
64
+ Emits canonical artifact-frontmatter fields as YAML (default) or JSON.
65
+ See script header for field list, ordering, and omission semantics.
66
+ EOF
67
+ exit "$exit_code"
68
+ }
69
+
70
+ main() {
71
+ # -- Parse arguments --
72
+ local format="yaml"
73
+ local skill="" model=""
74
+ local interactive=""
75
+ local interactive_set=false
76
+ declare -a extra_keys=()
77
+ declare -A extra_values=()
78
+ declare -A extra_kinds=()
79
+ declare -A overrides=()
80
+
81
+ while [[ "$#" -gt 0 ]]; do
82
+ case "$1" in
83
+ --help | -h)
84
+ show_usage 0
85
+ ;;
86
+ --format)
87
+ [[ "$#" -ge 2 ]] || fail "missing value for --format"
88
+ format="$2"
89
+ shift 2
90
+ ;;
91
+ --skill)
92
+ [[ "$#" -ge 2 ]] || fail "missing value for --skill"
93
+ skill="$2"
94
+ shift 2
95
+ ;;
96
+ --interactive)
97
+ [[ "$#" -ge 2 ]] || fail "missing value for --interactive"
98
+ interactive="$2"
99
+ interactive_set=true
100
+ shift 2
101
+ ;;
102
+ --model)
103
+ [[ "$#" -ge 2 ]] || fail "missing value for --model"
104
+ model="$2"
105
+ shift 2
106
+ ;;
107
+ --extra)
108
+ [[ "$#" -ge 2 ]] || fail "missing value for --extra"
109
+ add_extra "scalar" "$2" extra_keys extra_values extra_kinds
110
+ shift 2
111
+ ;;
112
+ --extra-list)
113
+ [[ "$#" -ge 2 ]] || fail "missing value for --extra-list"
114
+ add_extra "list" "$2" extra_keys extra_values extra_kinds
115
+ shift 2
116
+ ;;
117
+ --extra-list-item)
118
+ [[ "$#" -ge 2 ]] || fail "missing value for --extra-list-item"
119
+ add_extra_item "$2" extra_keys extra_values extra_kinds
120
+ shift 2
121
+ ;;
122
+ --override)
123
+ [[ "$#" -ge 2 ]] || fail "missing value for --override"
124
+ add_override "$2" overrides
125
+ shift 2
126
+ ;;
127
+ *)
128
+ echo "$PROG: Unexpected argument: $1" >&2
129
+ show_usage 1
130
+ ;;
131
+ esac
132
+ done
133
+
134
+ case "$format" in
135
+ yaml | json) ;;
136
+ *) fail "unknown --format: $format (expected yaml|json)" ;;
137
+ esac
138
+
139
+ if [[ "$format" == "yaml" ]]; then
140
+ [[ -n "$skill" ]] || fail "--skill is required in yaml mode"
141
+ [[ "$interactive_set" == "true" ]] || fail "--interactive is required in yaml mode"
142
+ case "$interactive" in
143
+ true | false) ;;
144
+ *) fail "--interactive must be true or false (got: $interactive)" ;;
145
+ esac
146
+ fi
147
+
148
+ # -- Resolve session-level values --
149
+ require_commands jq git
150
+
151
+ # Probe readability before resolving the branch, so that an unreadable repository is named as such.
152
+ local branch git_err
153
+ if ! git_err="$(git rev-parse --git-dir 2>&1 >/dev/null)"; then
154
+ fail "cannot read the git repository: $git_err"
155
+ fi
156
+ if ! branch=$(current_branch); then
157
+ git_err="$(git rev-parse --abbrev-ref HEAD 2>&1 >/dev/null || true)"
158
+ fail "git could not resolve the current branch: $git_err"
159
+ fi
160
+
161
+ local manifest
162
+ manifest=$(derive_manifest) || fail "could not derive branch manifest"
163
+
164
+ local commit
165
+ commit=$(git rev-parse --short HEAD 2>/dev/null) || fail "could not resolve HEAD commit"
166
+
167
+ local scm ticket_id ticket_ref default_branch
168
+ scm=$(jq -r '.scm // "github"' <<<"$manifest")
169
+ ticket_id=$(jq -r '.ticket_id // ""' <<<"$manifest")
170
+ ticket_ref=$(jq -r '.ticket_ref // ""' <<<"$manifest")
171
+ default_branch=$(jq -r '.default_branch // "origin/main"' <<<"$manifest")
172
+
173
+ local base_sha pr_url run_id timestamp
174
+ base_sha=$(resolve_base_sha "$default_branch")
175
+ pr_url=""
176
+ run_id=""
177
+ timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
178
+
179
+ # -- Apply overrides --
180
+ branch=$(apply_override "branch" "$branch" overrides)
181
+ commit=$(apply_override "commit" "$commit" overrides)
182
+ base_sha=$(apply_override "baseSha" "$base_sha" overrides)
183
+ pr_url=$(apply_override "pr" "$pr_url" overrides)
184
+ ticket_id=$(apply_override "ticket_id" "$ticket_id" overrides)
185
+ ticket_ref=$(apply_override "ticket_ref" "$ticket_ref" overrides)
186
+ scm=$(apply_override "scm" "$scm" overrides)
187
+ timestamp=$(apply_override "timestamp" "$timestamp" overrides)
188
+ run_id=$(apply_override "run_id" "$run_id" overrides)
189
+
190
+ if [[ "$format" == "json" ]]; then
191
+ emit_json "$branch" "$commit" "$base_sha" "$pr_url" \
192
+ "$ticket_id" "$ticket_ref" "$scm" "$timestamp" "$run_id"
193
+ else
194
+ emit_yaml \
195
+ "$skill" "$timestamp" "$base_sha" "$interactive" "$model" \
196
+ "$ticket_id" "$ticket_ref" "$branch" "$commit" "$pr_url" "$run_id" \
197
+ extra_keys extra_values extra_kinds
198
+ fi
199
+ }
200
+
201
+ # Parses a `KEY=VALUE` argument into the caller's `key` and `value` variables.
202
+ # The `flag` argument is used only for error messages. Fails when `=` is missing or the key portion is empty.
203
+ parse_key_value() {
204
+ local arg="$1" flag="$2"
205
+ local -n key_out="$3"
206
+ local -n value_out="$4"
207
+ if [[ "$arg" != *"="* ]]; then
208
+ fail "$flag argument missing '=': $arg"
209
+ fi
210
+ key_out="${arg%%=*}"
211
+ value_out="${arg#*=}"
212
+ [[ -n "$key_out" ]] || fail "$flag argument has empty key"
213
+ }
214
+
215
+ # Appends an extension key/value to the caller's ordered list. Splits the
216
+ # argument once on the first `=`. `kind` is either `scalar` or `list`.
217
+ add_extra() {
218
+ local kind="$1" arg="$2"
219
+ local -n keys_ref="$3"
220
+ local -n values_ref="$4"
221
+ local -n kinds_ref="$5"
222
+ local key value
223
+ parse_key_value "$arg" "--extra/--extra-list" key value
224
+ if [[ -z "${kinds_ref[$key]:-}" ]]; then
225
+ keys_ref+=("$key")
226
+ else
227
+ warn "duplicate --extra/--extra-list key '$key': replacing previous value"
228
+ fi
229
+ values_ref["$key"]="$value"
230
+ kinds_ref["$key"]="$kind"
231
+ }
232
+
233
+ # Appends one item to a flow-list extension key, registering the key on its
234
+ # first item. Items accumulate joined by ASCII US, the one character that an
235
+ # item may not contain; `--extra-list` splits on `,` instead, which would break
236
+ # apart a title containing one.
237
+ add_extra_item() {
238
+ local arg="$1"
239
+ local -n keys_ref="$2"
240
+ local -n values_ref="$3"
241
+ local -n kinds_ref="$4"
242
+ local key value
243
+ parse_key_value "$arg" "--extra-list-item" key value
244
+ if [[ -z "${kinds_ref[$key]:-}" ]]; then
245
+ keys_ref+=("$key")
246
+ values_ref["$key"]="$value"
247
+ elif [[ "${kinds_ref[$key]}" != "items" ]]; then
248
+ warn "--extra-list-item key '$key' was already set by --extra/--extra-list: replacing previous value"
249
+ values_ref["$key"]="$value"
250
+ else
251
+ values_ref["$key"]+=$'\x1f'"$value"
252
+ fi
253
+ kinds_ref["$key"]="items"
254
+ }
255
+
256
+ # Records an override key=value. Empty value force-omits the key on emit.
257
+ add_override() {
258
+ local arg="$1"
259
+ local -n overrides_ref="$2"
260
+ local key value
261
+ parse_key_value "$arg" "--override" key value
262
+ overrides_ref["$key"]="$value"
263
+ }
264
+
265
+ # Returns the overridden value when the key has been overridden, otherwise the resolved value.
266
+ # The empty-string override force-omits.
267
+ apply_override() {
268
+ local key="$1" resolved="$2"
269
+ local -n overrides_ref="$3"
270
+ if [[ -n "${overrides_ref[$key]+set}" ]]; then
271
+ printf '%s' "${overrides_ref[$key]}"
272
+ else
273
+ printf '%s' "$resolved"
274
+ fi
275
+ }
276
+
277
+ # Prints short SHA of `default_branch` (e.g., `origin/main`) or empty if unresolvable.
278
+ # Under a shallow clone or a missing remote, the output is silently empty.
279
+ resolve_base_sha() {
280
+ local ref="$1"
281
+ git rev-parse --short "$ref" 2>/dev/null || true
282
+ }
283
+
284
+ # Gets the current branch name. Returns non-zero outside a git repository.
285
+ current_branch() {
286
+ git rev-parse --abbrev-ref HEAD 2>/dev/null
287
+ }
288
+
289
+ # Invokes the `derive-session-context` helper to compose the branch manifest.
290
+ # Echoes the JSON manifest emitted on the helper's stdout. On failure, the helper's stderr is
291
+ # passed through verbatim to the caller's stderr and the function returns non-zero.
292
+ derive_manifest() {
293
+ local bundle_path
294
+ bundle_path="$(resolve_bundle_path)" || return 1
295
+ if [[ ! -r "$bundle_path" ]]; then
296
+ echo "$PROG: RESOLVE_FRONTMATTER_BUNDLE_PATH names $bundle_path, which is not readable" >&2
297
+ return 1
298
+ fi
299
+ if ! command -v node >/dev/null 2>&1; then
300
+ echo "$PROG: 'node' command not found on PATH; cannot run bundled deriver at $bundle_path" >&2
301
+ return 1
302
+ fi
303
+ # Anchor the deriver's cwd at the repo root. A call from a subdirectory would otherwise write a second manifest to
304
+ # `{subdir}/.agents/`.
305
+ local repo_root
306
+ repo_root=$(git rev-parse --show-toplevel 2>/dev/null) || {
307
+ echo "$PROG: could not resolve repo root for deriver invocation" >&2
308
+ return 1
309
+ }
310
+ # `RESOLVE_FRONTMATTER_BUNDLE_ARGS` passes extra args to the deriver, such as `--home /tmp/xyz` to
311
+ # isolate the global preferences lookup from the real home directory.
312
+ if [[ -n "${RESOLVE_FRONTMATTER_BUNDLE_ARGS:-}" ]]; then
313
+ # shellcheck disable=SC2086 # the args string is word-split on purpose
314
+ node "$bundle_path" --cwd "$repo_root" $RESOLVE_FRONTMATTER_BUNDLE_ARGS
315
+ else
316
+ node "$bundle_path" --cwd "$repo_root"
317
+ fi
318
+ }
319
+
320
+ # Resolves the absolute path to the `derive-session-context.mjs` helper.
321
+ # Honors `RESOLVE_FRONTMATTER_BUNDLE_PATH` when set. Otherwise searches the layout into which this script is installed:
322
+ # `install` places the script in `<harness home>/scripts/`, and `sync` deploys the helper, a support entry of its source,
323
+ # to `<harness home>/skills/_sources/<source-name>/derive-session-context/`. The source name is whatever the declaration
324
+ # gives it, so every namespace is searched, and exactly one must contain the helper.
325
+ resolve_bundle_path() {
326
+ if [[ -n "${RESOLVE_FRONTMATTER_BUNDLE_PATH:-}" ]]; then
327
+ printf '%s' "$RESOLVE_FRONTMATTER_BUNDLE_PATH"
328
+ return 0
329
+ fi
330
+ local source_path harness_home pattern
331
+ source_path="${BASH_SOURCE[0]:-$0}"
332
+ # Use the path as invoked: Its directory is the installed `scripts/`, whether `install` copied or linked the script.
333
+ harness_home="$(cd "$(dirname "$source_path")/.." && pwd)"
334
+ pattern="$harness_home/skills/_sources/*/derive-session-context/derive-session-context.mjs"
335
+ local -a matches=()
336
+ mapfile -t matches < <(compgen -G "$pattern" || true)
337
+ if [[ "${#matches[@]}" -eq 1 ]]; then
338
+ printf '%s' "${matches[0]}"
339
+ return 0
340
+ fi
341
+ if [[ "${#matches[@]}" -eq 0 ]]; then
342
+ echo "$PROG: deployed deriver not found at $pattern; set RESOLVE_FRONTMATTER_BUNDLE_PATH to its path" >&2
343
+ else
344
+ echo "$PROG: several deployed derivers match $pattern; set RESOLVE_FRONTMATTER_BUNDLE_PATH to the one to run:" >&2
345
+ printf ' %s\n' "${matches[@]}" >&2
346
+ fi
347
+ return 1
348
+ }
349
+
350
+ # Constructs the JSON output from resolved values.
351
+ # Optional fields are omitted (rather than emitted as null or empty) so that consumers can rely on `has(field)`
352
+ # semantics.
353
+ emit_json() {
354
+ local branch="$1" commit="$2" base_sha="$3" pr_url="$4"
355
+ local ticket_id="$5" ticket_ref="$6" scm="$7" timestamp="$8" run_id="$9"
356
+
357
+ jq -n \
358
+ --arg branch "$branch" \
359
+ --arg commit "$commit" \
360
+ --arg base_sha "$base_sha" \
361
+ --arg pr "$pr_url" \
362
+ --arg ticket_id "$ticket_id" \
363
+ --arg ticket_ref "$ticket_ref" \
364
+ --arg scm "$scm" \
365
+ --arg timestamp "$timestamp" \
366
+ --arg run_id "$run_id" \
367
+ '
368
+ {
369
+ branch: $branch,
370
+ commit: $commit,
371
+ scm: $scm,
372
+ timestamp: $timestamp
373
+ }
374
+ + (if $base_sha == "" then {} else { baseSha: $base_sha } end)
375
+ + (if $pr == "" then {} else { pr: $pr } end)
376
+ + (if $ticket_id == "" then {} else { ticket_id: $ticket_id } end)
377
+ + (if $ticket_ref == "" then {} else { ticket_ref: $ticket_ref } end)
378
+ + (if $run_id == "" then {} else { run_id: $run_id } end)
379
+ '
380
+ }
381
+
382
+ # Emits the canonical YAML frontmatter block, including `---` delimiters. Empty values are omitted.
383
+ # Field order is fixed: provenance block, canonical top-level fields, caller-supplied extensions in insertion order.
384
+ emit_yaml() {
385
+ local skill="$1" timestamp="$2" base_sha="$3" interactive="$4" model="$5"
386
+ local ticket_id="$6" ticket_ref="$7" branch="$8" commit="$9" pr_url="${10}" run_id="${11}"
387
+ local -n yaml_extra_keys="${12}"
388
+ local -n yaml_extra_values="${13}"
389
+ local -n yaml_extra_kinds="${14}"
390
+
391
+ printf '%s\n' "---"
392
+
393
+ printf '%s\n' "provenance:"
394
+ emit_yaml_indented_scalar "skill" "$skill"
395
+ emit_yaml_indented_scalar "timestamp" "$timestamp"
396
+ [[ -n "$base_sha" ]] && emit_yaml_indented_scalar "baseSha" "$base_sha"
397
+ # isInteractive is a boolean; emit unquoted true|false.
398
+ printf ' %s: %s\n' "isInteractive" "$interactive"
399
+ [[ -n "$model" ]] && emit_yaml_indented_scalar "model" "$model"
400
+
401
+ [[ -n "$ticket_id" ]] && emit_yaml_scalar "ticket_id" "$ticket_id"
402
+ [[ -n "$ticket_ref" ]] && emit_yaml_scalar "ticket_ref" "$ticket_ref"
403
+ emit_yaml_scalar "branch" "$branch"
404
+ emit_yaml_scalar "commit" "$commit"
405
+ [[ -n "$pr_url" ]] && emit_yaml_scalar "pr" "$pr_url"
406
+ [[ -n "$run_id" ]] && emit_yaml_scalar "run_id" "$run_id"
407
+
408
+ local key kind value
409
+ for key in "${yaml_extra_keys[@]+"${yaml_extra_keys[@]}"}"; do
410
+ value="${yaml_extra_values[$key]}"
411
+ kind="${yaml_extra_kinds[$key]}"
412
+ if [[ "$kind" == "items" ]]; then
413
+ emit_yaml_flow_list_items "$key" "$value"
414
+ elif [[ "$kind" == "list" ]]; then
415
+ # An empty flow-list extension emits `key: []`; the omission rule covers scalars alone.
416
+ emit_yaml_flow_list "$key" "$value"
417
+ else
418
+ [[ -n "$value" ]] || continue
419
+ emit_yaml_scalar "$key" "$value"
420
+ fi
421
+ done
422
+
423
+ printf '%s\n' "---"
424
+ }
425
+
426
+ # Emits a top-level YAML `key: value` line, auto-quoting the value as needed.
427
+ emit_yaml_scalar() {
428
+ local key="$1" value="$2"
429
+ printf '%s: %s\n' "$key" "$(yaml_quote "$value")"
430
+ }
431
+
432
+ # Emits an indented YAML `key: value` line inside the provenance block.
433
+ emit_yaml_indented_scalar() {
434
+ local key="$1" value="$2"
435
+ printf ' %s: %s\n' "$key" "$(yaml_quote "$value")"
436
+ }
437
+
438
+ # Emits a top-level YAML flow list: `key: [v1, v2, v3]`.
439
+ # Empty value emits an empty flow list `key: []`. Elements are split on `,` and each is passed through `yaml_quote`.
440
+ emit_yaml_flow_list() {
441
+ local key="$1" raw="$2"
442
+ if [[ -z "$raw" ]]; then
443
+ printf '%s: []\n' "$key"
444
+ return
445
+ fi
446
+ local IFS=','
447
+ # Disable globbing around the word-split so that list elements containing glob metacharacters (`*`, `?`, `[...]`)
448
+ # are not expanded against the filesystem before `yaml_quote` sees them.
449
+ set -f
450
+ # shellcheck disable=SC2206
451
+ local -a parts=($raw)
452
+ set +f
453
+ local out="" i
454
+ for ((i = 0; i < ${#parts[@]}; i++)); do
455
+ if [[ "$i" -gt 0 ]]; then
456
+ out+=", "
457
+ fi
458
+ out+="$(yaml_quote "${parts[$i]}")"
459
+ done
460
+ printf '%s: [%s]\n' "$key" "$out"
461
+ }
462
+
463
+ # Emits a top-level YAML flow list from items accumulated by `--extra-list-item`,
464
+ # splitting on ASCII US rather than on `,` so that an item containing a comma
465
+ # survives whole. Each item is quoted as `emit_yaml_flow_list` quotes its own.
466
+ emit_yaml_flow_list_items() {
467
+ local key="$1" raw="$2"
468
+ local out="" first=1 item
469
+ while IFS= read -r -d $'\x1f' item || [[ -n "$item" ]]; do
470
+ [[ "$first" == 1 ]] || out+=", "
471
+ first=0
472
+ out+="$(yaml_quote "$item")"
473
+ done < <(printf '%s' "$raw")
474
+ printf '%s: [%s]\n' "$key" "$out"
475
+ }
476
+
477
+ # Returns the value either bare or single-quoted, as `needs_yaml_quoting` decides.
478
+ # Embedded single quotes are doubled inside the quoted form.
479
+ yaml_quote() {
480
+ local v="$1"
481
+ if needs_yaml_quoting "$v"; then
482
+ local escaped="${v//\'/\'\'}"
483
+ printf "'%s'" "$escaped"
484
+ else
485
+ printf '%s' "$v"
486
+ fi
487
+ }
488
+
489
+ # Decides whether `v` needs single-quote wrapping. Returns 0 (true) when quoting is required, 1 otherwise.
490
+ #
491
+ # YAML parses `:` as a key indicator only when followed by whitespace or end-of-value,
492
+ # so URLs like `https://...` are safe bare. Because `#` is always treated as a comment introducer in YAML 1.1/1.2
493
+ # (the spec is permissive about the preceding context), any value containing `#` is quoted.
494
+ needs_yaml_quoting() {
495
+ local v="$1"
496
+ [[ -z "$v" ]] && return 0
497
+ [[ "$v" =~ ^[[:space:]] ]] && return 0
498
+ [[ "$v" =~ [[:space:]]$ ]] && return 0
499
+ # A leading `?` is covered by the glyphs-anywhere case below.
500
+ case "$v" in
501
+ -* | :*) return 0 ;;
502
+ esac
503
+ # Colon followed by whitespace anywhere is a key indicator.
504
+ [[ "$v" =~ :[[:space:]] ]] && return 0
505
+ # Trailing colon is the value-end form of a key indicator.
506
+ [[ "$v" == *: ]] && return 0
507
+ case "$v" in
508
+ *'#'* | *'['* | *']'* | *'{'* | *'}'* | \
509
+ *','* | *'&'* | *'*'* | *'!'* | *'|'* | *'>'* | *'<'* | \
510
+ *'?'* | *'%'* | *'@'* | *'`'* | *"'"* | *'"'*)
511
+ return 0
512
+ ;;
513
+ esac
514
+ # A value that looks like a YAML boolean, null, or number stays bare: The predicate's value space is
515
+ # the schema's canonical fields and known extensions, in which none of those is ambiguous.
516
+ return 1
517
+ }
518
+
519
+ # Requires each named command to be on PATH. Exits 1 with a clear message when one is missing.
520
+ require_commands() {
521
+ local cmd
522
+ for cmd in "$@"; do
523
+ command -v "$cmd" >/dev/null 2>&1 || fail "required command not found: $cmd"
524
+ done
525
+ }
526
+
527
+ # Prints an error message to stderr and exits 1.
528
+ fail() {
529
+ echo "$PROG: $1" >&2
530
+ exit 1
531
+ }
532
+
533
+ # Prints a non-fatal warning to stderr.
534
+ warn() {
535
+ echo "$PROG: warning: $1" >&2
536
+ }
537
+
538
+ if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
539
+ main "$@"
540
+ fi
@@ -0,0 +1,12 @@
1
+ import { createRequire as __cjsCreateRequire } from 'node:module';
2
+ const require = __cjsCreateRequire(import.meta.url);
3
+ var M=Object.defineProperty;var i=(e,n)=>M(e,"name",{value:n,configurable:!0});import{realpathSync as F}from"node:fs";import c from"node:process";import{fileURLToPath as I}from"node:url";function E(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}i(E,"isError");function f(e){try{return E(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}i(f,"describeError");function h(e,n){let r=[],t=[];for(let o=0;o<e.length;o+=1){let s=e[o];if(s===void 0)continue;if(!s.startsWith("--")){r.push(s);continue}let u=T(s,n);if(u===null)throw new Error(`unknown flag: ${s}`);let{spec:a,inlineValue:g}=u;if(!a.takesValue){if(g!==null)throw new Error(`--${a.name} does not take a value`);t.push({name:a.name,value:null});continue}if(g!==null){t.push({name:a.name,value:g});continue}let p=e[o+1]??null;if(p===null||p.startsWith("--"))throw new Error(`--${a.name} requires a value`);t.push({name:a.name,value:p}),o+=1}return{positionals:r,flags:t}}i(h,"scanFlags");function y(e){let n={};for(let{name:r,value:t}of e)t!==null&&(n[r]=t);return n}i(y,"valueFlagMap");function T(e,n){for(let r of n)for(let t of[r.name,...r.aliases??[]]){let o=`--${t}`;if(e===o)return{spec:r,inlineValue:null};if(e.startsWith(`${o}=`))return{spec:r,inlineValue:e.slice(o.length+1)}}return null}i(T,"matchFlag");import{mkdir as b,readdir as A}from"node:fs/promises";import w from"node:path";function P(e,n){return D(e)&&e.code===n}i(P,"isErrorCode");function x(e){return P(e,"ENOENT")}i(x,"isEnoent");function D(e){return typeof e=="object"&&e!==null}i(D,"isObject");var v="interactive",V=new RegExp(String.raw`^(\d{8}-\d{6}Z)-${v}$`),j=/^(\d{8}-\d{6}Z)_(?:overseer|reviewer)_review\.md$/,_=/^\d{8}-\d{6}Z$/;async function d(e){let n=k(await $(e,"directory"),V);return n===void 0?void 0:w.join(e,n)}i(d,"findActiveRun");async function R(e){let n=await d(e);if(n===void 0)throw new Error(`no ${v} run directory found in ${e}`);let r=k(await $(n,"file"),j);if(r===void 0)throw new Error(`no reviewer or overseer review found in ${n}`);return{reviewPath:w.join(n,r),runDir:n}}i(R,"findLatestReview");async function N(e,n){if(!_.test(n))throw new Error(`timestamp must be UTC YYYYMMDD-HHMMSSZ, got '${n}'`);let r=await d(e);if(r!==void 0)return r;let t=w.join(e,`${n}-${v}`);return await b(t,{recursive:!0}),t}i(N,"openRun");async function $(e,n){try{return(await A(e,{withFileTypes:!0})).filter(t=>n==="directory"?t.isDirectory():t.isFile()).map(t=>t.name)}catch(r){if(x(r))return[];throw r}}i($,"listEntryNames");function k(e,n){let r;for(let t of e){let o=n.exec(t)?.[1];o!==void 0&&(r===void 0||o>r.timestamp||o===r.timestamp&&t>r.name)&&(r={name:t,timestamp:o})}return r?.name}i(k,"selectNewest");var Y=[{name:"ticket-dir",takesValue:!0},{name:"timestamp",takesValue:!0}],l=`usage: resolve-review-run active --ticket-dir <dir>
4
+ resolve-review-run latest --ticket-dir <dir>
5
+ resolve-review-run open --ticket-dir <dir> --timestamp <YYYYMMDD-HHMMSSZ>`;async function L(){try{let e=await C(c.argv.slice(2));c.stdout.write(`${JSON.stringify(e,null,2)}
6
+ `)}catch(e){c.stderr.write(`resolve-review-run: ${f(e)}
7
+ `),c.exit(1)}}i(L,"main");O()&&await L();function O(){let e=c.argv[1];if(e===void 0)return!1;try{return F(I(import.meta.url))===F(e)}catch(n){return c.stderr.write(`resolve-review-run: warning: could not determine entry point: ${f(n)}
8
+ `),!1}}i(O,"isEntryPoint");function S(e,n){if(e.timestamp!==void 0)throw new Error(`${n} does not take --timestamp
9
+ ${l}`)}i(S,"rejectTimestamp");function m(e,n){let r=e[n];if(r===void 0)throw new Error(`--${n} is required
10
+ ${l}`);return r}i(m,"requireValue");async function C(e){let{flags:n,positionals:r}=h(e,Y),[t,...o]=r;if(o.length>0)throw new Error(`unexpected argument: ${o.join(" ")}
11
+ ${l}`);let s=y(n);if(t==="active")return S(s,t),{runDir:await d(m(s,"ticket-dir"))??null};if(t==="latest"){S(s,t);let{reviewPath:u,runDir:a}=await R(m(s,"ticket-dir"));return{reviewPath:u,runDir:a}}if(t==="open")return{runDir:await N(m(s,"ticket-dir"),m(s,"timestamp"))};throw new Error(t===void 0?l:`unknown command: ${t}
12
+ ${l}`)}i(C,"runCommand");