codeassembly-guidance 0.1.0 → 0.3.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 (165) hide show
  1. package/.meta/changelog.json +984 -0
  2. package/CHANGELOG.md +240 -0
  3. package/README.md +45 -99
  4. package/bin/codeassembly-validate-preferences.js +18 -0
  5. package/content/_partials/README.md +21 -5
  6. package/content/_partials/comment-discipline.md +1 -1
  7. package/content/_partials/diff-audit-checklist.md +1 -0
  8. package/content/_partials/kb-standard-tags.md +7 -0
  9. package/content/_partials/plain-speech-calibration.md +4 -0
  10. package/content/_partials/technical-recommendations.md +1 -0
  11. package/content/codeassembly-content.yaml +17 -1
  12. package/content/collections/all.md +2 -2
  13. package/content/collections/atlassian.md +2 -1
  14. package/content/collections/recommended.md +9 -2
  15. package/content/collections/triage.md +3 -67
  16. package/content/collections/williamthorsen.md +2 -1
  17. package/content/guidance/README.md +1 -1
  18. package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
  19. package/content/guidance/rulebooks/cli-conventions.md +206 -0
  20. package/content/guidance/rulebooks/codeassembly-content-specification.md +50 -10
  21. package/content/guidance/rulebooks/commit-conventions.md +5 -4
  22. package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
  23. package/content/guidance/rulebooks/readme-conventions.md +3 -3
  24. package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
  25. package/content/guidance/rulebooks/shell-conventions.md +17 -23
  26. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  27. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +18 -12
  28. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
  29. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
  30. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
  31. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
  32. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
  33. package/content/guidance/shared/AGENTS.md +39 -4
  34. package/content/scripts/README.md +5 -2
  35. package/content/scripts/check-branch-currency.mjs +11 -0
  36. package/content/scripts/check-prose.mjs +171 -0
  37. package/content/scripts/describe-change.mjs +98 -98
  38. package/content/scripts/manage-jira-ticket.mjs +99 -94
  39. package/content/scripts/resolve-frontmatter.sh +1 -1
  40. package/content/scripts/resolve-review-run.mjs +9 -9
  41. package/content/scripts/select-lede-exemplars.mjs +87 -87
  42. package/content/scripts/validate-preferences.mjs +146 -0
  43. package/content/skills/_data/action-items.md +2 -0
  44. package/content/skills/_data/artifact-conventions.md +64 -16
  45. package/content/skills/_data/branch-currency.md +36 -0
  46. package/content/skills/_data/change-record.md +2 -2
  47. package/content/skills/_data/complexity-classification.md +1 -1
  48. package/content/skills/_data/design-priorities.md +15 -4
  49. package/content/skills/_data/project-stage.md +32 -0
  50. package/content/skills/_data/recommendation-gradient.md +9 -7
  51. package/content/skills/_data/scope-and-deferral.md +1 -1
  52. package/content/skills/_data/spike-conventions.md +21 -6
  53. package/content/skills/_data/ticket-evaluation.md +2 -2
  54. package/content/skills/_data/ticket-source-resolution.md +36 -3
  55. package/content/skills/_data/title-templates.md +22 -12
  56. package/content/skills/_partials/action-items.md +2 -2
  57. package/content/skills/_partials/apply-guidance-edits.md +5 -0
  58. package/content/skills/_partials/commit-title-rendering.md +1 -1
  59. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  60. package/content/skills/_partials/next-steps-after-plan.md +11 -11
  61. package/content/skills/_partials/option-format.md +18 -17
  62. package/content/skills/_partials/plan-template.md +7 -5
  63. package/content/skills/_partials/split-ticket-compose.md +1 -1
  64. package/content/skills/_partials/split-ticket-create.md +1 -1
  65. package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
  66. package/content/skills/_partials/ticket-composition.md +40 -0
  67. package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
  68. package/content/skills/_partials/ticket-skeleton.md +15 -1
  69. package/content/skills/add-change-record/SKILL.md +2 -2
  70. package/content/skills/align-ticket-with-implementation/SKILL.md +3 -7
  71. package/content/skills/anti-patterns/SKILL.md +1 -1
  72. package/content/skills/assess-code-health/SKILL.md +127 -0
  73. package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
  74. package/content/skills/assess-usability/SKILL.md +98 -0
  75. package/content/skills/capture-event/SKILL.md +4 -2
  76. package/content/skills/capture-event/capture-event.mjs +89 -89
  77. package/content/skills/capture-feedback/SKILL.md +1 -1
  78. package/content/skills/capture-lede-decision/SKILL.md +4 -4
  79. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
  80. package/content/skills/collaborate/SKILL.md +3 -3
  81. package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
  82. package/content/skills/create-commit/SKILL.md +1 -1
  83. package/content/skills/create-gh-pr/SKILL.md +28 -10
  84. package/content/skills/create-pr/SKILL.md +7 -6
  85. package/content/skills/create-ticket/SKILL.md +64 -23
  86. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  87. package/content/skills/derive-session-context/derive-session-context.mjs +83 -82
  88. package/content/skills/design-and-plan/SKILL.md +17 -18
  89. package/content/skills/groom-backlog/SKILL.md +8 -6
  90. package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
  91. package/content/skills/implement-plan/SKILL.md +27 -23
  92. package/content/skills/index-prototypes/SKILL.md +86 -31
  93. package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
  94. package/content/skills/kb-add/SKILL.md +4 -1
  95. package/content/skills/kb-add/kb-add.mjs +128 -128
  96. package/content/skills/kb-curate/SKILL.md +9 -7
  97. package/content/skills/kb-curate/kb-curate.mjs +103 -103
  98. package/content/skills/kb-edit/SKILL.md +5 -3
  99. package/content/skills/kb-edit/kb-edit.mjs +94 -94
  100. package/content/skills/kb-retrieve/kb-retrieve.mjs +86 -85
  101. package/content/skills/kb-retrieve-events/SKILL.md +20 -11
  102. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +86 -85
  103. package/content/skills/kb-update-events/SKILL.md +10 -7
  104. package/content/skills/kb-update-events/kb-update-events.mjs +110 -109
  105. package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
  106. package/content/skills/merge-bb-pr/SKILL.md +1 -1
  107. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
  108. package/content/skills/merge-pr/SKILL.md +11 -11
  109. package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
  110. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
  111. package/content/skills/plan/SKILL.md +2 -2
  112. package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
  113. package/content/skills/pull-from-backlog/SKILL.md +3 -3
  114. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
  115. package/content/skills/refine-guidance/SKILL.md +97 -0
  116. package/content/skills/refine-plan/SKILL.md +7 -3
  117. package/content/skills/refine-prototype/SKILL.md +113 -0
  118. package/content/skills/respond-to-review/SKILL.md +1 -1
  119. package/content/skills/review-bb-pr/SKILL.md +1 -1
  120. package/content/skills/review-branch/SKILL.md +354 -3
  121. package/content/skills/review-criteria/SKILL.md +36 -3
  122. package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
  123. package/content/skills/revise-comments/SKILL.md +38 -5
  124. package/content/skills/revise-prose/SKILL.md +1 -1
  125. package/content/skills/revise-prose/revise-prose.mjs +119 -119
  126. package/content/skills/save-artifact/SKILL.md +3 -1
  127. package/content/skills/streamline-guidance/SKILL.md +11 -16
  128. package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
  129. package/content/skills/summarize-change/SKILL.md +23 -14
  130. package/content/skills/testing-conventions/SKILL.md +81 -8
  131. package/content/skills/triage-feedback/SKILL.md +150 -0
  132. package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
  133. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  134. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +73 -0
  135. package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
  136. package/content/skills/update-jira-ticket/SKILL.md +20 -8
  137. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
  138. package/content/skills/update-project-guidance/SKILL.md +12 -12
  139. package/content/subagents/_data/claude.yaml +6 -0
  140. package/content/subagents/_data/rovo.yaml +12 -2
  141. package/content/subagents/canary.md +2 -1
  142. package/content/subagents/code-health-assessor.md +98 -0
  143. package/content/subagents/disposition-challenger.md +78 -0
  144. package/content/subagents/entry-drafter.md +14 -10
  145. package/content/subagents/feedback-triage-challenger.md +81 -0
  146. package/content/subagents/handoff-reviewer.md +2 -2
  147. package/content/subagents/lesson-clusterer.md +68 -0
  148. package/content/subagents/plan-reviewer.md +1 -1
  149. package/content/subagents/prose-reviser.md +4 -2
  150. package/content/subagents/ticket-assessor.md +9 -6
  151. package/content/subagents/usability-assessor.md +157 -0
  152. package/package.json +21 -17
  153. package/schemas/preferences.v1.json +50 -7
  154. package/schemas/work-types.v1.json +1 -1
  155. package/content/_partials/code-descriptions.md +0 -4
  156. package/content/_partials/code-style.md +0 -7
  157. package/content/_partials/live-repo-writes.md +0 -13
  158. package/content/_partials/reduced-object-relative.md +0 -28
  159. package/content/_partials/test-structure-audit-checklist.md +0 -7
  160. package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
  161. package/content/skills/_partials/next-steps-after-review.md +0 -350
  162. package/content/skills/_partials/ticket-concision.md +0 -18
  163. package/content/skills/_partials/ticket-placement.md +0 -14
  164. package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
  165. package/content/skills/testing-conventions/mistakes.md +0 -1
@@ -2,6 +2,15 @@
2
2
 
3
3
  Standards for AI-generated artifact storage, naming, and lifecycle.
4
4
 
5
+ ## Purpose
6
+
7
+ The artifact directory is the developer's audit trail of development. Its plans, reviews, change summaries, pull-request and merge records, devlogs, and chat summaries record what an agent produced and when, each as it stood at the moment of writing (see [Mutability](#mutability)). The directory is not a source of truth, and it is not a home for durable content:
8
+
9
+ - **Durable content.** Put instructions, a procedure, or a reference that a later session must find in the repository (its docs, `AGENTS.md`, or a README), or in a skill or rulebook when they apply across repositories. A later session looks there, not in the artifact directory.
10
+ - **Authority.** An artifact is not authority on the current state of code, design, or decisions. Treat what a search of artifacts turns up as history, and verify it against the repository, the tickets, and the pull requests.
11
+ - **Conclusions.** A conclusion that a reader of the ticket needs is posted on the ticket, and the artifact keeps the evidence. For a spike, see [Closing post](spike-conventions.md#closing-post).
12
+ - **Inputs to the same work.** A skill that reads an artifact as an input to the same piece of work, such as the plan that `implement-plan` executes or the change summary that `create-pr` publishes, uses the artifact as the workflow intends.
13
+
5
14
  ## Directory structure
6
15
 
7
16
  All artifacts are stored under a configurable base directory (`base_dir`, default `~/ai-artifacts`). Invoke the bundled session-context deriver (`node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`) to resolve `artifact_base_dir`:
@@ -17,6 +26,25 @@ All artifacts are stored under a configurable base directory (`base_dir`, defaul
17
26
  │ │ ├── manifest.json
18
27
  │ │ ├── shots/{slug}-v{n}.png
19
28
  │ │ └── {slug}-v{n}.html
29
+ │ ├── usability/ ← a usability assessment's lens reports and evidence, kept by `assess-usability`
30
+ │ │ ├── {lens}-report.md
31
+ │ │ └── {lens}/{finding-id}-{slug}.png
32
+ │ ├── code-health/ ← a code-health assessment's sense document, reports, and proposals, kept by `assess-code-health`
33
+ │ │ ├── sense.json
34
+ │ │ ├── {lens}/report.md
35
+ │ │ └── {lens}/proposals.json
36
+ │ ├── triage/ ← a findings triage's working files, kept by `triage-spike-findings`
37
+ │ │ ├── findings.md
38
+ │ │ ├── inventory.md
39
+ │ │ ├── recommendations.md
40
+ │ │ ├── challenge.md
41
+ │ │ ├── dispositions.json
42
+ │ │ ├── preview/ ← the rendered comments shown at the confirmation
43
+ │ │ │ ├── dispositions-comment.md
44
+ │ │ │ └── comment-{issue}.md
45
+ │ │ └── rendered/ ← the rendered comments that are posted
46
+ │ │ ├── dispositions-comment.md
47
+ │ │ └── comment-{issue}.md
20
48
  │ └── {run-id}/ ← review run directory
21
49
  │ ├── {NN}_{role}_{artifact}.md
22
50
  │ └── ...
@@ -26,13 +54,16 @@ All artifacts are stored under a configurable base directory (`base_dir`, defaul
26
54
  │ └── {timestamp}_{slug}_deferred-findings.md ← project-scoped fallback when a ticket is not in session
27
55
  ├── devlogs/
28
56
  │ └── {timestamp}_{concise-title}.md ← project-scoped fallback when a ticket is not in session
57
+ ├── feedback-triage/
58
+ │ ├── {timestamp}_{slug}_feedback-triage.md ← project-scoped fallback when a ticket is not in session
59
+ │ └── {timestamp}_work/ ← the run's working files
29
60
  └── plans/
30
61
  └── {design-documents}.md
31
62
  ```
32
63
 
33
64
  ### Project slug
34
65
 
35
- Always present under `projects/`, even when `{base_dir}/` is inside the project. Constant structure enables simple directory sync for export. Invoke the bundled session-context deriver to obtain `project_slug`.
66
+ Always present under `projects/`, even when `{base_dir}/` is inside the project, so that an artifact's path has the same shape wherever `base_dir` lies. Invoke the bundled session-context deriver to obtain `project_slug`.
36
67
 
37
68
  ### Ticket ID
38
69
 
@@ -42,7 +73,19 @@ A `project.ticket_ref_prefix` other than `#` is part of the ticket ID, so it nam
42
73
 
43
74
  ### Prototype sets
44
75
 
45
- `prototypes/` holds the ticket's one prototype set: the sources, the stored screenshots, and the manifest from which `index-prototypes` renders the set's index page. The page itself is rendered into the session's scratch directory for publishing and is not kept here.
76
+ `prototypes/` contains the ticket's one prototype set: the sources, the stored screenshots, and the manifest from which `index-prototypes` renders the set's index page. The page itself is rendered into the session's scratch directory for publishing and is not kept here.
77
+
78
+ ### Usability evidence
79
+
80
+ `usability/` contains the working files of the ticket's usability assessment: each lens's report and each lens's evidence, which is screenshots in a browser assessment and transcripts in a CLI assessment. The `usability-findings` artifact cites the evidence by paths relative to the ticket directory, so the evidence stays in the ticket directory. A CLI assessment's fixtures are scratch directories outside the ticket directory, and nothing keeps them.
81
+
82
+ ### Code-health working files
83
+
84
+ `code-health/` contains the working files of the ticket's code-health assessment: the sense document with each check's log beside it, the test reports that the sensors read, each lens's report and checked proposals, and the merged proposals. The `code-health-findings` artifact cites code by paths relative to the repository root, so it does not depend on these files; they record what the run measured.
85
+
86
+ ### Triage working files
87
+
88
+ `triage/` contains the working files of a triage of the ticket's findings: a local copy of the findings when they came from an artifact URL, the inventory, the recommendations that the challenger reads, the challenger's reply, the dispositions record from which the `dispositions` artifact is rendered, and the comments rendered from that record: `preview/` with placeholders for the confirmation, `rendered/` with every number for posting. The record stays here as a working file; the artifact is the rendered text.
46
89
 
47
90
  ### Run directories
48
91
 
@@ -60,11 +103,7 @@ projects/{project-slug}/tickets/{ticket-id}/{run-id}/
60
103
 
61
104
  Example: `20260221-034100Z-interactive`
62
105
 
63
- A ticket's **active run** is its newest run directory of mode `interactive`, by the timestamp in its name. A review saves into the active run, and the author's response saves into the run that holds the review, so a review, the response, and a re-review share one run. A new run directory is created, when the review is written, only when the ticket directory does not contain an active run. A run of mode `orchestrated` is never active. `resolve-review-run` applies this definition.
64
-
65
- ### Persistent export destination
66
-
67
- Artifacts under `{base_dir}/` are ephemeral when `base_dir` is a git-ignored path (the default). In worktrees, they are lost on deletion. The `export-ai-artifacts.sh` script copies them to `~/ai-artifacts/projects/{project-slug}/` for long-term retention, preserving the same directory structure. Exported artifacts are immutable (first export wins).
106
+ A ticket's **active run** is its newest run directory of mode `interactive`, by the timestamp in its name. A review is saved into the active run, and the author's response is saved into the run that contains the review, so a review, the response, and a re-review share one run. A new run directory is created, when the review is written, only when the ticket directory does not contain an active run. A run of mode `orchestrated` is never active. `resolve-review-run` applies this definition.
68
107
 
69
108
  ## Path resolution
70
109
 
@@ -107,11 +146,12 @@ Ticket-level artifacts and run directories are both stored here. Invoke the bund
107
146
  | chats | `chats` | `{base_dir}/projects/{project-slug}/chats/` |
108
147
  | deferred-findings | `deferred-findings` | `{base_dir}/projects/{project-slug}/deferred-findings/` |
109
148
  | devlogs | `devlogs` | `{base_dir}/projects/{project-slug}/devlogs/` |
149
+ | feedback-triage | `feedback-triage` | `{base_dir}/projects/{project-slug}/feedback-triage/` |
110
150
  | plans | `plans` | `{base_dir}/projects/{project-slug}/plans/` |
111
151
 
112
- Non-ticket paths are relative to the project directory. Category names remain configurable via `artifacts.paths.{category}` in preferences.yaml, with one exception: `deferred-findings` is hardcoded and cannot be overridden.
152
+ Non-ticket paths are relative to the project directory. Category names remain configurable via `artifacts.paths.{category}` in preferences.yaml, with two exceptions: `deferred-findings` and `feedback-triage` are hardcoded and cannot be overridden.
113
153
 
114
- Devlogs and deferred-findings artifacts are dual-homed: When a ticket is in session context they are written as ticket-level artifacts under `tickets/{ticket-id}/`; otherwise they fall back to the project-scoped paths above (`devlogs/` for devlogs, `deferred-findings/` for deferred-findings). All filenames in both types use the standard `YYYYMMDD-HHMMSSZ` ticket-level timestamp shape regardless of which directory they are written to.
154
+ Devlogs, deferred-findings, and feedback-triage artifacts are dual-homed: When a ticket is in session context they are written as ticket-level artifacts under `tickets/{ticket-id}/`; otherwise they fall back to the project-scoped paths above (`devlogs/`, `deferred-findings/`, and `feedback-triage/`). All filenames in these types use the standard `YYYYMMDD-HHMMSSZ` ticket-level timestamp shape regardless of which directory they are written to.
115
155
 
116
156
  ## Naming conventions
117
157
 
@@ -125,7 +165,7 @@ Devlogs and deferred-findings artifacts are dual-homed: When a ticket is in sess
125
165
  - **slug**: Kebab-case descriptor drawn from work context, e.g., branch description (`improve-artifact-naming`) or commit subject (`fix-login-validation`). Max 60 chars, filesystem-safe.
126
166
  - **artifact-type**: One of the registered types (see below)
127
167
 
128
- When the ticket directory already contains artifacts for this change, reuse their slug; derive a fresh one only when the change's descriptor has moved. One change has one name, which keeps it legible where the enclosing path is not in view: an editor tab, a search result, an export.
168
+ When the ticket directory already contains artifacts for this change, reuse their slug; derive a fresh one only when the change's descriptor has changed. One change has one name, which keeps it legible where the enclosing path is not in view: an editor tab, a search result, an export.
129
169
 
130
170
  ### Run artifacts (review workflow)
131
171
 
@@ -236,7 +276,7 @@ Invocation surface:
236
276
  node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs
237
277
  ```
238
278
 
239
- The deriver prints the manifest JSON to stdout and writes it to `.agents/{sanitized-branch}.branch-manifest.json` as a side effect. Every invocation recomposes the derived fields from the current preferences and git state, so a preference change takes effect on the next call. The file keeps `created_at` and the URLs written by the mutation flags (recorded in `explicit_urls`), and the deriver rewrites it only when its content changes. On the default branch, the deriver drops any stored `ticket_url` or `pr_url` per [Stored ticket URL](ticket-source-resolution.md#stored-ticket-url). Diagnostics are printed to stderr; exit 0 on success, 1 on hard failure (corrupt preferences, detached HEAD, schema-validation error).
279
+ The deriver prints the manifest JSON to stdout and writes it to `.agents/{sanitized-branch}.branch-manifest.json` as a side effect. Because every invocation recomposes the derived fields from the current preferences and git state, a preference change takes effect on the next call. The file keeps `created_at` and the URLs written by the mutation flags (recorded in `explicit_urls`), and the deriver rewrites it only when its content changes. On the default branch, the deriver drops any stored `ticket_url` or `pr_url` per [Stored ticket URL](ticket-source-resolution.md#stored-ticket-url). Diagnostics are printed to stderr; exit 0 on success, 1 on hard failure (corrupt preferences, detached HEAD, schema-validation error).
240
280
 
241
281
  When authoring a new skill that needs session-context fields: Invoke the bundled deriver and read the fields from the emitted JSON. Do not rely on any other caller having populated the manifest first: The deriver is the single derivation surface and is safe to call from any context.
242
282
 
@@ -301,7 +341,7 @@ This artifact uses the [universal artifact frontmatter](#universal-artifact-fron
301
341
 
302
342
  Each override is recorded beside the field that it overrides rather than in its place. A skill that needs the effective record reads it from [`resolve-effective-record`](title-templates.md#resolve-effective-record) rather than applying the overrides itself.
303
343
 
304
- **The change summary's body ends with the rendered `change-record` block**, which carries the change entries and the consolidated record to the pull request. `create-pr` copies the body from `## What` onward, so the block reaches the pull-request body without being rendered again.
344
+ **The change summary's body ends with the rendered `change-record` block**, which contains the change entries and the consolidated record for the pull request. `create-pr` copies the body from `## What` onward, so the block is copied into the pull-request body without being rendered again.
305
345
 
306
346
  The frontmatter stays flat, whereas the `change-record` block nests the consolidated record, the overrides, and the entries, because the artifact store is an Obsidian vault and Obsidian's Properties editor does not handle nested maps. That is also why the entries are recorded in the block rather than as a nested frontmatter field.
307
347
 
@@ -323,7 +363,7 @@ This artifact uses the [universal artifact frontmatter](#universal-artifact-fron
323
363
 
324
364
  ## run-index.json
325
365
 
326
- Machine-readable metadata for a run directory. The retired orchestration engine wrote it, and no current skill does. `run-core` parses it.
366
+ Machine-readable metadata for a run directory. The retired orchestration engine wrote it; the current skills do not. `run-core` parses it.
327
367
 
328
368
  Every example and value list in this section and in [V3 format](#v3-format-event-sourced-runs) describes runs written by the retired engine, so its roles, agents, phases, and modes are historical values.
329
369
 
@@ -707,16 +747,24 @@ The first `coder_change-summary` in a run does not have dispositions (nothing to
707
747
 
708
748
  - `brief`: The shared brief that a round of prototype builders receives; `prepare-prototype-brief` saves it at its checkpoint
709
749
  - `change-summary`: Branch change summary for PRs
710
- - `comparison`: Findings across a round of prototypes: where they agree, where they diverge, which ideas to carry forward, and which decisions the round leaves open; `prepare-prototype-brief` saves it after the index
750
+ - `code-health-brief`: The brief that every lens of a code-health assessment reads: the unit and its hotspots, the reuse-candidate directory and library inventory, the lenses with their rulebooks and caps, and the exclusions; `assess-code-health` saves it at its checkpoint
751
+ - `code-health-findings`: The merged, ungraded proposals of a code-health assessment, ranked by reach and hotspot rank, with the proposed groupings, the proposals that a prior triage or an issue already tracks, the residual unknowns, and the lens reports; `assess-code-health` saves it, and `triage-spike-findings` reads it
752
+ - `comparison`: Findings across a round of prototypes: the points on which they agree and those on which they diverge, a table of every distinctive idea with an empty decision, and which decisions the round leaves open; `prepare-prototype-brief` saves it after the index
711
753
  - `deferred-findings`: Record of findings deferred during a `wrap-up` session, with cross-references to created tickets (falls back to non-ticket path when a ticket is not in session)
754
+ - `dispositions`: The rendered dispositions of a triage of findings, the text that `triage-spike-findings` posts on the triage ticket: every item with its disposition, its confidence and value, where it went, and its reason, with the challenge's summary; the JSON record from which it is rendered stays in `triage/`
712
755
  - `devlog`: Development log entry (falls back to non-ticket path when a ticket is not in session)
756
+ - `feedback-triage`: The record of a `triage-feedback` run: each surfaced cluster of feedback events with its signals, priority, challenge, disposition, and result, and the remainder left in the pool. A deferred event's `addressed-by` names the artifact, whose filename timestamp dates the deferral; the run's working files stay in `{timestamp}_work/` beside it (falls back to non-ticket path when a ticket is not in session)
757
+ - `idea-decisions`: The idea table of a round of prototypes with the decision on each idea filled; `prepare-prototype-brief` saves it after the developer decides each idea, and the end vision cites it
713
758
  - `merge`: Record of a merged pull request; `capture-lede-decision` reads its `## Body` as the merged side of a lede episode
714
759
  - `plan`: Implementation plan document
715
760
  - `plan-review`: Plan review findings (completeness and correctness analysis)
716
761
  - `plan-v2`: Refined implementation plan after review and revision
717
762
  - `pull-request`: PR description file; `capture-lede-decision` reads its `## What` as the agent's side of a lede episode
763
+ - `refinement-log`: The accepted changes of one session of `refine-prototype`, grouped under the id of the version that each one entered, with the transplants' sources and the open forks; the end vision reads it with the `idea-decisions` artifact
718
764
  - `review`: Code review (ticket-level, commit scope)
719
765
  - `ticket`: Issue ticket
766
+ - `usability-brief`: The brief that every lens of a usability assessment reads: the medium, the targets and their write rules, the lenses with their minimum use cases, and the exclusions; `assess-usability` saves it at its checkpoint
767
+ - `usability-findings`: The merged findings of a usability assessment, ranked by effect and reach, with the use-case outcomes, the ideas, the proposed groupings, the residual unknowns, and the lens reports; `assess-usability` saves it, and `triage-spike-findings` reads it
720
768
 
721
769
  ### Non-ticket artifacts
722
770
 
@@ -897,9 +945,9 @@ Insights never have criticality, never block a merge, and never count toward a r
897
945
 
898
946
  A saved artifact is a point-in-time record of what its author produced at the moment of writing. Correct one that got its own subject wrong; never edit one toward what has happened since, whether a later human edit to the remote to which it was published, a rebase that leaves `baseSha` and `commit` unresolvable, or a subsequent turn of the session that wrote it. Divergence from current state is the artifact doing its job, so it is never reported as a defect or raised as a repair for the user to weigh. A step that discloses which of two candidate sources it measured against is reporting its own input, not proposing a reconciliation.
899
947
 
900
- The `pull-request` and `merge` records carry a marker that directs a reading agent to leave the record unedited, stated in the file rather than left to standing guidance, because `capture-lede-decision` reads them and a rewrite corrupts it silently. The other artifacts do not have one.
948
+ The `pull-request` and `merge` records contain a marker that directs a reading agent to leave the record unedited, stated in the file rather than left to standing guidance, because `capture-lede-decision` reads them and a rewrite corrupts it silently. The other artifacts do not have one.
901
949
 
902
- A flow still composing its own artifact has reached nothing downstream of it, so overwriting that artifact finishes its record rather than revising a finished one.
950
+ A flow still composing its own artifact has not yet passed it to anything downstream, so overwriting that artifact finishes its record rather than revising a finished one.
903
951
 
904
952
  A later flow that revises a finished record writes a new artifact rather than editing the old one. `refine-plan` saves its output as `plan-v2` under a later timestamp, leaving the plan that it refines intact.
905
953
 
@@ -0,0 +1,36 @@
1
+ # Branch currency
2
+
3
+ A branch whose base is behind the remote's default branch gets designed, planned, or implemented without the changes that the default branch has gained since. Check the branch before such work starts, so that the check reveals the gap while it is still cheap to close.
4
+
5
+ ## When to check
6
+
7
+ Check a branch other than the default branch, before the work starts. Skip the check on the default branch, comparing `branch_name` with `default_branch` stripped of its remote (everything after its first `/`), and on a detached HEAD, which the manifest reports as an empty `branch_name`. Read both values from the session-context manifest, never from git directly, so that the remote and the default branch follow the repository's preferences.
8
+
9
+ ## Invocation
10
+
11
+ ```
12
+ node {harness_home_dir}/scripts/check-branch-currency.mjs --base {default_branch} [--path {path}]...
13
+ ```
14
+
15
+ Pass one `--path` for each file or directory that the work touches, relative to the repository root, as the calling skill names them. Pass only paths that exist in the tree; a ticket that describes its area in prose does not supply any. The helper fetches the default branch, which is read-only, and prints one JSON object. It exits non-zero on a usage error, or when git fails after the fetch; act on a non-zero exit as on `fetched: false`, with the helper's stderr as the error.
16
+
17
+ ## Acting on the result
18
+
19
+ **`fetched: false`.** Report in one line that the branch check did not run, with the `error`, and continue. Never report the branch as current. When the `consult-sandbox-conventions` skill is deployed, consult it before reading the error as a missing credential or an unreachable network.
20
+
21
+ **`behind: 0`.** Say nothing.
22
+
23
+ **`behind` above 0, `ahead: 0`, and `clean: true`.** The branch does not have any commits of its own or uncommitted changes, so a fast-forward loses nothing and can be undone. Run `git merge --ff-only {default_branch}` without asking, and report in one line that the branch was fast-forwarded by `behind` commits, followed by the [commit list](#commit-list). When the fast-forward fails, act on the result as in the next case.
24
+
25
+ **`behind` above 0 otherwise.** Report the gap and the [commit list](#commit-list), and ask how to proceed before the work starts, as a numbered gradient menu:
26
+
27
+ 1. Bring the base in: by rebase onto `{default_branch}`, or by merging `{default_branch}` into the branch when `pushed` is true, because rebasing pushed commits would then need a force-push.
28
+ 2. Proceed against the current base.
29
+
30
+ Recommend the first unless none of the gained commits touches the work. When `clean` is false, say that the tree has uncommitted changes, and do not run a git operation that would touch them before the developer answers.
31
+
32
+ ## Commit list
33
+
34
+ Name each gained commit by its short SHA and subject. When paths were passed, name only the commits whose `touchesWork` is true, and state how many others the default branch gained; when none touches the work, say so. When paths were not passed, name the first 10 commits of `gained`, which is ordered newest first, and state the count of the rest.
35
+
36
+ The calling skill states what follows the report.
@@ -76,9 +76,9 @@ entries:
76
76
 
77
77
  The payload is YAML rather than a surface template because `overrides` and `entries` nest, and a template renders one flat line. Nesting also leaves room for the block to gain structured keys, such as a grammar version or a ticket reference. Its inverse is a YAML parse rather than a compiled pattern, so this pair needs none of the round-trip verification required by the title grammar.
78
78
 
79
- **The scalars precede `entries`**, so the bulky list does not separate the title from the overrides.
79
+ **The scalars precede `entries`** so that the bulky list does not separate the title from the overrides.
80
80
 
81
- **The block records the change entries as data**, which is how a reader downstream of the merge gets them without parsing them back out of the rendered `## Details` prose. The change summary's `changes` frontmatter field is a different list: It holds the commit entries, which record what the branch's commits declared.
81
+ **The block records the change entries as data**, which is how a reader downstream of the merge gets them without parsing them back out of the rendered `## Details` prose. The change summary's `changes` frontmatter field is a different list: It contains the commit entries, which record what the branch's commits declared.
82
82
 
83
83
  **The block is the body's last element.** A reader takes the last `change-record` fence in the body, and the merge body that `resolve-merge` composes from the pull request excludes every block.
84
84
 
@@ -49,7 +49,7 @@ Each consuming skill defines which complexity levels qualify for its "simple eno
49
49
  | `design-and-plan` / `plan` handoff pass | 1–2 | Skip the handoff pass; the session reports the skip in one line that names the level, and saves the artifacts |
50
50
  | `next-steps-after-plan` | 1–2 | Recommend "Implement". When a review pass would catch nothing meaningful (e.g., a typo or unused-import removal), note on the option that the review can be skipped at `implement-plan`'s closing menu. |
51
51
  | `implement-plan` closing menu | 1–2 | Recommend "Create PR without review"; the realized diff is trivial enough that a review pass would catch nothing meaningful |
52
- | `next-steps-after-review` | n/a | Trivial findings usually name a single change, for which the skill recommends "Implement directly and commit"; the recommendation depends on the finding's shape rather than on the level. |
52
+ | `review-branch` closing menu | n/a | Trivial findings usually name a single change, for which the skill recommends "Implement directly and commit"; the recommendation depends on the finding's shape rather than on the level. |
53
53
 
54
54
  When characteristics span two levels, prefer the higher level.
55
55
 
@@ -8,7 +8,7 @@ Design options have two kinds of properties.
8
8
 
9
9
  **Correctness** (what makes the design right):
10
10
 
11
- - Behavioral correctness: Does it produce the right results across the cases that matter?
11
+ - Behavioral correctness: Does it produce the right results across the cases that matter? The project's declared stage sets which cases matter; see [project stage](project-stage.md).
12
12
  - API quality: Clear contracts, expressive interfaces, sensible boundaries
13
13
  - Architectural soundness: Modularity, separation of concerns, single responsibility, composability, SOLID
14
14
  - Testability: The design can be verified in isolation
@@ -25,7 +25,7 @@ Rank options on correctness. Convenience is secondary: a tiebreaker among correc
25
25
 
26
26
  ## Why
27
27
 
28
- Correctness determines what it costs to live with the system over its remaining life. A clean design can be evolved; a wrong one accumulates patches around its wrongness. Convenience is paid once, at the moment of change.
28
+ Correctness determines what it costs to live with the system over its remaining life. A clean design can be evolved; a wrong one accumulates patches around its wrongness. Convenience saves effort only once, at the moment of change.
29
29
 
30
30
  ## Before / after
31
31
 
@@ -63,13 +63,24 @@ The factual lists about each option are similar; the **ranking** flips because t
63
63
 
64
64
  When designing a change, ask: _How would we have written this if the new behavior had been there from the start?_ Aim the design at that target.
65
65
 
66
- Three patterns signal a design that hasn't reached it:
66
+ Four patterns signal a design that hasn't reached it:
67
67
 
68
68
  - **Workarounds**: Changing surrounding code to accommodate a fix instead of changing the code that's wrong.
69
69
  - **Carve-outs**: Special cases or conditional branches that exist because the change couldn't be integrated cleanly, not because the cases are genuinely distinct.
70
70
  - **Bolt-ons**: New modules or extension points appended alongside existing structure when the existing structure should have evolved to absorb the change.
71
+ - **Hand-offs**: Steps that a person performs on each machine or environment because the design did not give the agent a way to apply the change there. See [who applies the change](#who-applies-the-change).
71
72
 
72
- A fresh codebase wouldn't have these shapes; their presence means the change was attached to the system rather than integrated into it. Reaching the target may require touching code outside the ticket's literal frame: renaming, restructuring, generalizing. That cost is real but bounded; the cost of keeping a poorly integrated change compounds.
73
+ A fresh codebase wouldn't have these shapes; their presence means the change was attached to the system rather than integrated into it. Reaching the target may require touching code outside the ticket's literal scope: renaming, restructuring, generalizing. That cost is real but bounded; the cost of keeping a poorly integrated change compounds.
74
+
75
+ ## Who applies the change
76
+
77
+ The developer's manual steps are a cost of the design, counted across the session rather than per turn: Every command that a person runs on a machine, and every result that they paste back, is a step that the design failed to script. Rank a design that the agent applies and verifies itself above one that needs a person to act on each machine, whatever the convenience properties say. A step that a person must run on each machine is a defect of the design: Raise it at design time, and never ship it as README steps, written after the merge, for a person to follow.
78
+
79
+ When the design cannot remove the step, shape it on this ladder, and stop at the first rung that works:
80
+
81
+ 1. Reach the machine through the access that its own tooling already uses, such as `ssh`, and apply the step there. When this rung needs a credential or a grant, ask for it once, naming the command that runs once it arrives.
82
+ 2. Route the step through provisioning that the machine already runs, such as the ensure scripts of its configuration repository, so that the agent commits the change and the machine applies it on its next run.
83
+ 3. Leave one script per machine, run once, that checks its own result and prints only the facts that the agent needs. The agent writes and commits the script and keeps every other part, including the records of what was done.
73
84
 
74
85
  ## Reconciliation
75
86
 
@@ -0,0 +1,32 @@
1
+ # Project stage
2
+
3
+ A project declares its stage in its own `.agents/preferences.yaml`, under `project`, and the session-context manifest reports each value as `project_maturity`, `project_sensitivity`, and `project_audience`, `null` when the project does not declare it. The global preferences file never supplies a stage, because a stage describes one repo.
4
+
5
+ ## Values
6
+
7
+ | Key | Value | Meaning |
8
+ | ------------- | -------------- | -------------------------------------------------------------------------------- |
9
+ | `maturity` | `hobby` | Built for the owner's own use or learning; breakage costs only the owner's time. |
10
+ | | `early` | In use by others, but the shape is still changing; downtime is tolerated. |
11
+ | | `production` | Others depend on it; downtime and data loss have real costs. |
12
+ | `sensitivity` | `low` | Nothing that would harm anyone if published. |
13
+ | | `personal` | Personal data about the owner or identifiable individuals. |
14
+ | | `confidential` | Secrets, credentials, or data that a third party is obliged to protect. |
15
+ | `audience` | `owner` | Only the repo's owner uses it. |
16
+ | | `team` | A known, bounded group uses it. |
17
+ | | `public` | Anyone who can reach it uses it. |
18
+
19
+ ## What each value implies
20
+
21
+ - **Security.** `owner` with `low` sensitivity needs only what keeps the owner's own credentials out of the repository; access control beyond the host's own login is machinery without an asset to protect. `personal` data warrants access limited to the people that it concerns. Authentication with several factors, rate limits, and origin checks are needed for `public` users or `confidential` data.
22
+ - **Availability.** `hobby` tolerates a service that runs only while the owner works, such as a local process or a database on the owner's machine. `early` tolerates downtime and manual recovery. Hosted, always-available infrastructure and backups are needed for `production`.
23
+ - **Infrastructure.** Choose the least infrastructure on which the project runs at its declared stage: a file before a database, a local process before a hosted service, one environment before several.
24
+
25
+ ## Rules
26
+
27
+ - **The declared values are premises.** Design for the stage that the project declares, not for the stage that a general-purpose system would assume. A design that serves requirements beyond the declared stage is wrong for this project, however sound it would be elsewhere.
28
+ - **Default to the least machinery that works for the declared stage.** Read [design priorities](design-priorities.md) against the stage: Behavioral correctness covers the cases that matter at that stage.
29
+ - **Escalate only for a named asset or need.** Add security, availability, or infrastructure beyond what the stage implies only when the design names what it protects or serves, such as "the tokens table holds the owner's API keys". State the asset or need in the ticket.
30
+ - **Make added hardening switchable.** A safeguard added beyond the stage, such as an origin check or a rate limit, is switched by configuration, so that a preview deployment or a local run can work without it.
31
+ - **Ask for an undeclared value; never infer it.** An undeclared value is a preference for which the agent holds no evidence, so it is in the gated class: Ask the developer rather than infer enterprise requirements from silence. Once the developer answers, declare the value in the project's `.agents/preferences.yaml` and run `node {harness_home_dir}/scripts/validate-preferences.mjs` on the edited file, so that the question is asked once.
32
+ - **Record the premises.** State each value that decided a security, availability, or infrastructure question where the work records its decisions: in a ticket's `## Context`, one sentence per premise naming the value and the decision that it settled, and in a product's design doc.
@@ -8,21 +8,23 @@ The render contract comes first; the doctrine behind it follows. Skills that ask
8
8
 
9
9
  ## Why the gate comes first
10
10
 
11
- Asking is not a neutral act. It is cheap for the agent (it discharges responsibility for the call, rules out being wrong, and costs one paragraph) and expensive twice over: The developer pays a context switch to load the context, weigh the options, and answer, and the session that asked idles until the answer arrives. Across a dozen concurrent sessions those costs compound into decision fatigue and a stalled pipeline. A menu that the agent could have resolved itself transfers cost from the cheap side to the expensive one, and it looks like diligence while it happens, which is why it goes unnoticed and recurs.
11
+ Asking is not a neutral act. It is cheap for the agent (it discharges responsibility for the call, rules out being wrong, and takes one paragraph) and expensive twice over: The developer must switch context to load the context, weigh the options, and answer, and the session that asked idles until the answer arrives. Across a dozen concurrent sessions those costs compound into decision fatigue and a stalled pipeline. A menu that the agent could have resolved itself transfers cost from the cheap side to the expensive one, and it looks like diligence while it happens, which is why it goes unnoticed and recurs.
12
12
 
13
- The gate reads the markers rather than asking for judgment, because a judgment gate loses to a step that says to ask: An agent following a step list executes the step, and a rendered ■■■ makes the ask feel legitimate. The gate is only as reliable as the markers that it reads, and the observed bias is a marker set too weak: An option whose alternatives have disqualifying flaws gets ■■□, and the menu renders. The contract's leader check corrects that before the gate reads the markers. Two ■■□ at the top is a real fork, an unmarked list is a preference, and every other field is decided. The gated class is a closed list for the same reason: "consequential" is read generously, and a list is not.
13
+ The gate reads the markers rather than asking for judgment, because a step that says to ask overrides a judgment gate: An agent following a step list executes the step, and a rendered ■■■ makes the ask feel legitimate. The gate is only as reliable as the markers that it reads, and the observed bias is a marker set too weak: An option whose alternatives have disqualifying flaws gets ■■□, and the menu renders. The contract's leader check corrects that before the gate reads the markers. Two ■■□ at the top is a real fork, an unmarked list is a preference, and every other field is decided. The gated class is a closed list for the same reason: "consequential" is read generously, and a list is not.
14
14
 
15
- A real fork is a choice between acceptable options, not doubt about a fact. On one change, the agent applied the work-type test and resolved the change to `feat`, then rendered one entry's typing, `feat` against `fix`, as a menu marked ■■□ on both options. The agent held the diff, the commits, the taxonomy, and the test that decides the type; the developer held the summary bullets, and answering meant reloading all of it to give a worse-informed answer than the agent's. The type has one right answer under the test, and the closeness of the two candidates was doubt about which one the test yields. The correct handling is a decision: Apply the test, pick, state the reason in one line, and let the pull-request body show the type before anything publishes.
15
+ The leader check is not only for the gate. A gated decision renders its menu whatever the markers say, so a check read as deciding whether a menu renders looks pointless there and is skipped. The marker still does its other job: It tells the developer how much deliberation the ask needs. A leader marked ■■□ above a disqualified alternative reads as a close call, and the developer must re-derive the analysis to find out that the alternative was never viable before approving. An honest ■■■ lets them approve at a glance. A cost that disqualifies an alternative often follows from the constraints or the acceptance criteria of the work at hand rather than from the option itself, which is why the check searches each alternative for such a cost before marking.
16
16
 
17
- A wrong-but-stated recommendation is cheaper to correct than a decision handed back: Correcting one costs a word, answering one costs an evaluation and a wait. The record keeps the developer's veto at the cheaper price. They read the ledger and overrule the entries with which they disagree, and the session has kept working in the meantime. "When in doubt, ask" is therefore the expensive default, not the safe one, and "when in doubt, record" is the rule that replaces it.
17
+ A real fork is a choice between acceptable options, not doubt about a fact. On one change, the agent applied the work-type test and resolved the change to `feat`, then rendered one entry's typing, `feat` against `fix`, as a menu marked ■■□ on both options. The agent had the diff, the commits, the taxonomy, and the test that decides the type; the developer had the summary bullets, and answering meant reloading all of it to give a worse-informed answer than the agent's. The type has one right answer under the test, and the closeness of the two candidates was doubt about which one the test yields. The correct handling is a decision: Apply the test, pick, state the reason in one line, and let the pull-request body show the type before anything is published.
18
18
 
19
- The gate and the marker are one rule seen twice. A menu that passes the gate is one that the markers could not settle or one that the developer authorizes, and the agent may still hold a strong evidence-based ranking inside an authorization menu, which is exactly when ■■■ is honest. A marker set below the strength actually available tells the developer nothing, and leaves them investigating every menu to find the few that are real forks.
19
+ A wrong-but-stated recommendation is cheaper to correct than a decision handed back: Correcting one takes a word; answering one takes an evaluation and a wait. The record keeps the developer's veto and makes it cheaper to use. They read the record and overrule the entries with which they disagree, and the session has kept working in the meantime. "When in doubt, ask" is therefore the expensive default, not the safe one, and "when in doubt, record" is the rule that replaces it.
20
+
21
+ The gate and the marker are one rule seen twice. A menu that passes the gate is one that the markers could not settle or one that the developer authorizes, and the agent may still have a strong evidence-based ranking inside an authorization menu, which is exactly when ■■■ is honest. A marker set below the strength actually available tells the developer nothing, and leaves them investigating every menu to find the few that are real forks.
20
22
 
21
23
  ## Why a manufactured bullet costs more than none
22
24
 
23
- Bullets in an option list are weighted equally by construction; the format does not provide a minor bullet. Placing a line under `➖` asserts that the reader should weigh it, so they spend attention deciding how much it matters. For a manufactured con the answer is none, and the cost is paid before the worthlessness is discovered. That makes it waste rather than merely noise.
25
+ Bullets in an option list are weighted equally by construction; the format does not provide a minor bullet. Placing a line under `➖` asserts that the reader should weigh it, so they spend attention deciding how much it matters. For a manufactured con the answer is none, and the reader spends that attention before discovering that the con is worthless. That makes it waste rather than merely noise.
24
26
 
25
- The con is also load-bearing for the menu's existence: Because an option recommended without a drawback reads as a decision rather than an option, presenting a settled call as a fork requires inventing a drawback. A fabricated con is the sign that the gate above was skipped, not an independent formatting slip.
27
+ The menu's existence also depends on the con: Because an option recommended without a drawback reads as a decision rather than an option, presenting a settled call as a fork requires inventing a drawback. A fabricated con is the sign that the gate above was skipped, not an independent formatting slip.
26
28
 
27
29
  When the honest cost is hard to find, that difficulty is itself evidence the option is strong. Spend the effort on finding the real cost or on omitting the bullet, never on manufacturing a plausible-sounding one.
28
30
 
@@ -11,7 +11,7 @@ By default, fold into the current change the work that the ticket didn't name (a
11
11
 
12
12
  "The ticket didn't mention it" is never such a reason. When the discovered work addresses the same underlying problem, closing only the ticket-named part leaves the problem partially solved, so the discovered work is required, not optional.
13
13
 
14
- **Authority.** The agent recommends the disposition of discovered work and builds on the recommendation; the developer vetoes. A fold-in is provisional and surfaces at the ticket checkpoint with its reason. A spin-off creates remote state, so it is asked before the ticket is created. Never declare work "out of scope" as settled fact, and never drop discovered work without reporting it.
14
+ **Authority.** The agent recommends the disposition of discovered work and builds on the recommendation; the developer vetoes. A fold-in is provisional, and the agent reports it at the ticket checkpoint with its reason. Because a spin-off creates remote state, the agent asks before creating the ticket. Never declare work "out of scope" as settled fact, and never drop discovered work without reporting it.
15
15
 
16
16
  **Feature responsibility.** When the current change introduces a feature, an avoidable user-visible defect caused by that feature is in-scope-by-default, a likely bug to fix here, not an automatic follow-up. Meeting the ticket's written acceptance criteria does not license merging a defect that the change itself introduced.
17
17
 
@@ -1,6 +1,8 @@
1
1
  # Spike conventions
2
2
 
3
- Spike work is an investigation, not a build: Its artifacts answer questions and enable a decision rather than deliver observable software behavior. This file defines the spike-shaped ticket and plan templates that the ticket- and plan-authoring skills use in place of their feature templates when the work is a spike.
3
+ Spike work is an investigation, not a build: Its artifacts answer questions and enable a decision rather than deliver observable software behavior. This file defines the spike-shaped ticket and plan templates that the ticket- and plan-authoring skills use in place of their feature templates when the work is a spike, and the [closing post](#closing-post) that ends every spike.
4
+
5
+ The ticket is the record of a spike, and the findings artifact is its log: The artifact holds the full findings and the evidence, and the ticket holds what the spike concluded. See [Purpose](artifact-conventions.md#purpose) for the artifact directory's role.
4
6
 
5
7
  Spike mode is entered explicitly (the invocation signals it) and is not auto-detected from ticket type, label, or title. Everything outside the two templates below (source resolution, staleness, Q&A, saving) is unchanged from the feature flow.
6
8
 
@@ -37,12 +39,12 @@ The concision and content-placement doctrines for feature tickets and plans appl
37
39
 
38
40
  - [ ] {A decision that the findings must make possible.}
39
41
 
40
- Deliverable: a findings & recommendation artifact.
42
+ Deliverable: a findings & recommendation artifact, and the closing post on this ticket.
41
43
  ```
42
44
 
43
45
  `Context` and `Scope` are opt-in: Include either only when it adds signal on which the reader must act.
44
46
 
45
- Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is a first-class section; acceptance criteria are questions-to-answer and decisions-to-enable rather than observable-behavior checkboxes; the spike ticket does not have a test or documentation criterion; the deliverable is a findings artifact, saved via the standard `save-artifact` conventions (without a dedicated artifact type).
47
+ Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is a first-class section; acceptance criteria are questions-to-answer and decisions-to-enable rather than observable-behavior checkboxes; the spike ticket does not have a test or documentation criterion; the deliverable is a findings artifact, saved via the standard `save-artifact` conventions (without a dedicated artifact type), and the [closing post](#closing-post) on the ticket.
46
48
 
47
49
  ## Spike plan template
48
50
 
@@ -59,7 +61,7 @@ Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is
59
61
 
60
62
  ## Decisions taken
61
63
 
62
- - {A decision that the agent took without asking, with its one-line reason; append `(provisional)` when it awaits the checkpoint.}
64
+ - {🔲 while it awaits the checkpoint} {A decision that the agent took without asking, with its one-line reason.}
63
65
 
64
66
  ## Timebox
65
67
 
@@ -79,10 +81,23 @@ Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is
79
81
 
80
82
  ## Deliverable
81
83
 
82
- {The findings & recommendation artifact: the answers reached, a recommendation, and residual unknowns.}
84
+ {The findings & recommendation artifact (the answers reached, a recommendation, and residual unknowns), and the closing post on the ticket, offered at the closing checkpoint and made on consent, per `spike-conventions.md` § Closing post.}
83
85
  ```
84
86
 
85
- Differences from the feature plan: Investigation steps, each framed by the question that it probes, replace tasks with create/modify/test file lists; `Timebox` is first-class; `Deliverable` replaces `Verification`, since a spike produces findings rather than verifiable behavior; a step does not have a test or documentation criterion.
87
+ Differences from the feature plan: Investigation steps, each framed by the question that it probes, replace tasks with create/modify/test file lists; `Timebox` is first-class; `Deliverable` replaces `Verification`, since a spike produces findings rather than verifiable behavior, and it names the [closing post](#closing-post); a step does not have a test or documentation criterion.
88
+
89
+ ## Closing post
90
+
91
+ The agent that ends a spike posts its conclusion on the ticket as a comment. The post contains:
92
+
93
+ - The answer to each of the ticket's questions to answer.
94
+ - The recommendation on each of the ticket's decisions to enable.
95
+ - The counts and the proposed groupings, when the spike produced them.
96
+ - Links to the published page, when the spike published one, and to the findings artifact, with the artifact's path written `~/`-relative, so that the post does not publish a home-directory path.
97
+
98
+ Offer the post as an item in the closing action-items block, show its body, and post it only on consent: It is a remote write, and the developer is the one who can tell whether a finding is fit for the ticket's tracker. When the session does not have a ticket, do not offer it.
99
+
100
+ Pass the body through a file, per [gh body file](ticket-source-resolution.md#gh-body-file). Before posting, read the ticket's comments, and skip the post when a comment already opens with the post's first line, so that a rerun does not post it twice.
86
101
 
87
102
  ## Aligning a spike
88
103
 
@@ -1,11 +1,11 @@
1
1
  # Ticket evaluation
2
2
 
3
- A ticket (regardless of who created it) is a request, report, or suggestion, not a contract. We own the code; the ticket is input. Any behavioral or API change proposed by the ticket is a recommendation to evaluate, not an instruction to implement.
3
+ A ticket is a request, report, or suggestion, not a contract. Treat its content as unsourced, whichever account created the ticket, until you trace it to a source. We own the code; the ticket is input. Any behavioral or API change proposed by the ticket is a recommendation to evaluate, not an instruction to implement.
4
4
 
5
5
  The author may have framed it poorly, missed the actual problem, scoped it too narrowly, proposed an unsound fix, or filed work that turns out to be inadvisable. Before designing to a ticket, evaluate it on its merits:
6
6
 
7
7
  - **Is the problem real?** Reproduce or verify the underlying observation, not just the framing.
8
- - **Is the scope right?** Look for related instances of the same defect class, neighboring code paths, or assumptions that don't hold beyond the ticket's frame. Scope can grow, not only shrink: Work required by the problem folds into the current change by default rather than being deferred; see [scope-and-deferral](./scope-and-deferral.md). Scope can also be too large: When the ticket holds two or more pieces that each ship and can be verified on their own, raise the split before design begins, while the cut still costs an edit rather than a rewrite of the ticket, new children, a re-cut plan, and work already committed against it.
8
+ - **Is the scope right?** Look for related instances of the same defect class, neighboring code paths, or assumptions that don't hold beyond the ticket's frame. Scope can grow, not only shrink: By default, the agent folds work required by the problem into the current change rather than deferring it; see [scope-and-deferral](./scope-and-deferral.md). Scope can also be too large: When the ticket contains two or more pieces that can each be merged and verified on their own, raise the split before design begins, while the cut still requires an edit rather than a rewrite of the ticket, new children, a re-cut plan, and work already committed against it.
9
9
  - **Is the proposed solution sound?** A ticket may include a recommended fix that solves the symptom but not the cause, or that fixes the cause less well than an alternative. Apply the [design priorities](./design-priorities.md) criteria: A convenient-but-wrong fix is unsound, even if it matches surrounding code.
10
10
  - **Is the title accurate?** "Flaky test in X" may be a hygiene anti-pattern that exists in three places. Reframe titles when the underlying truth is broader or different.
11
11
  - **Is the change worth making?** Synthesize the above: Doing nothing, or doing something narrower, may be the right call. Don't treat acceptance as the default.
@@ -75,7 +75,15 @@ Skills may request a subset of these fields. The `updatedAt` field is needed by
75
75
 
76
76
  Access Jira Cloud through Atlassian's `acli`, falling back to a connected Jira read tool. Detect the CLI with `command -v acli`, and treat a non-zero exit from the fetch itself as unavailable: An `acli` that is installed but unauthenticated exits non-zero with an error on stderr and nothing on stdout, and that error does not distinguish an authentication failure from a missing issue, so fall through on the exit status rather than on the message.
77
77
 
78
- **Preferred: `acli`.** Read the ticket body with the default view, which renders the description as text.
78
+ **Preferred: `acli`.** `acli` reads from whichever site it is signed in to, and a ticket on another site fails with the same error as a missing one. Before the first `acli` call, compare its active site with the ticket's host, taken from the ticket URL, or from `ticket_base_url` when the ticket URL is not known:
79
+
80
+ ```
81
+ node {harness_home_dir}/scripts/manage-jira-ticket.mjs check-site --target {ticket URL or ticket_base_url}
82
+ ```
83
+
84
+ The helper prints `{"activeSite": ..., "targetSite": ..., "match": ...}` and exits non-zero unless the two match. On a mismatch, read the ticket through another client below; a non-zero exit without JSON means that `acli` is unavailable. When neither URL is known, skip the check and read through `acli` as below.
85
+
86
+ Read the ticket body with the default view, which renders the description as text.
79
87
 
80
88
  ```
81
89
  acli jira workitem view {key}
@@ -90,9 +98,31 @@ When a skill needs structured metadata, such as the `updated` timestamp for a st
90
98
  - **Takes an issue URL**: Pass the ticket URL. Prefer this shape when both are connected, since it does not need site resolution.
91
99
  - **Takes an issue key and a cloud ID**: Resolve the cloud ID first, from the same server's tool listing accessible Atlassian sites. It is the `id` of the site whose URL matches the ticket URL's host, or of the sole site listed when the ticket URL is not known. If neither settles it, ask the user which site hosts the ticket. Resolve it once and reuse it for the rest of the session.
92
100
 
93
- **Last resort.** When neither is available, present the Jira key and ask the user for the ticket content. When `ticket.base_url` is configured, the ticket URL is reconstructed from the base and `ticket_id` (per [auto-resolve](#auto-resolve) step 4d), so it does not have to be supplied or re-pasted. A caller with a sound default source may substitute it for that prompt, as [When auto-resolve fails](#when-auto-resolve-fails) allows.
101
+ **A client that the machine adds.** {skill?:update-jira-ticket} lists any Jira client that this machine adds to the cascade, with the sites that it can access and its rank. Read through it as its entry states.
102
+
103
+ **Last resort.** When no client can read the ticket and `check-site` reported a mismatch, report the wrong site rather than a missing ticket: Repeat the helper's stderr line, which names both sites and the `acli jira auth switch` command. Never run that command, because the active site is shared by every session on the machine. When no client is available, present the Jira key and ask the user for the ticket content. When `ticket.base_url` is configured, the ticket URL is reconstructed from the base and `ticket_id` (per [auto-resolve](#auto-resolve) step 4d), so it does not have to be supplied or re-pasted. A caller with a sound default source may substitute it for that prompt, as [When auto-resolve fails](#when-auto-resolve-fails) allows.
104
+
105
+ The stored URL applies throughout: A Jira ticket URL resolved once is reused on later sessions, and it is invalidated like any other stored URL when it does not yield the expected ticket (see [Stored ticket URL](#stored-ticket-url)). A site mismatch does not invalidate the stored URL, because it does not show that the ticket is missing.
106
+
107
+ ## Open blockers
108
+
109
+ A ticket's open blockers are the tickets recorded natively as blocking it that are not yet done. Read them each time a skill resolves the ticket, even when the ticket is already in context, because a blocker can close or appear during a session.
94
110
 
95
- The stored URL applies throughout: A Jira ticket URL resolved once is reused on later sessions, and it is invalidated like any other stored URL when it does not yield the expected ticket (see [Stored ticket URL](#stored-ticket-url)).
111
+ **GitHub.** A blocker is open while its `state` is `OPEN`, so one closed as not planned counts as resolved. A blocker can be in another repository:
112
+
113
+ ```
114
+ gh issue view {number} --json blockedBy --jq '.blockedBy.nodes[] | select(.state == "OPEN") | [.url, .title] | @tsv'
115
+ ```
116
+
117
+ Name a blocker `#N` when its URL has the same `owner/repo` as the ticket's, and `owner/repo#N` otherwise.
118
+
119
+ **Jira.** Read the links through the Jira clients that [platform-specific fetch](#platform-specific-fetch) ranks, after the same site check: `acli jira workitem view {key} --json --fields issuelinks`, or a connected read tool asked for the `issuelinks` field. A blocker is a link whose `type.name` is `Blocks`, or whose `type.inward` reads `is blocked by`, and that has an `inwardIssue`. It is open while `inwardIssue.fields.status.statusCategory.key` is not `done`. Name it by its key and `fields.summary`.
120
+
121
+ **A file.** A ticket artifact copies a remote ticket, so a ticket that resolved from a file is checked against the remote ticket that its frontmatter `ticket_ref` names, resolved per [shorthand reference resolution](#shorthand-reference-resolution). A file without a `ticket_ref` is not checked.
122
+
123
+ **Other sources.** A ticket that resolved from plain text or from another platform is not checked, and the skill says nothing about blockers. Because a project hosted on Bitbucket keeps its tickets in Jira, its tickets are checked as Jira tickets.
124
+
125
+ **Report.** When the ticket has open blockers, report them in one line, each by reference and title: `⚠️ {ticket_ref} is blocked by {blocker_ref} ({title}), …`. When it has none, report nothing. When the read fails or no client can make it, report in one line that the blocker check did not run, and why; never report the ticket as unblocked. The calling skill states what follows the report.
96
126
 
97
127
  ## Platform-specific write
98
128
 
@@ -116,6 +146,8 @@ gh issue edit {number} --body-file "$body_path"
116
146
 
117
147
  Update through {skill?:update-jira-ticket}, which states the tool-shape branch and bundles the pre-flight checker that its HTML surface needs.
118
148
 
149
+ <!-- include: ../_partials/jira-task-list-flattening.md / -->
150
+
119
151
  `acli`'s default view is text rather than Markdown and the write converts the whole description, so a partial revision re-renders the sections that it leaves alone; report it as a re-rendering of the whole description rather than an edit confined to the revised section.
120
152
 
121
153
  ### Other platforms
@@ -142,6 +174,7 @@ After resolution, store the following metadata for use by the calling skill:
142
174
  - **Issue number**: The numeric identifier, if applicable
143
175
  - **Last-updated date**: The ticket's last-modified timestamp, if available from the platform
144
176
  - **Ticket content**: The title, body, labels, and any other retrieved fields
177
+ - **Open blockers**: For a skill that checks them, each open blocker's reference and title, read per [Open blockers](#open-blockers)
145
178
  - **Ticket URL**: Persisted across sessions in the branch manifest's `ticket_url` field, written through the deriver's mutation flags; see [Stored ticket URL](#stored-ticket-url)
146
179
 
147
180
  <!-- include: ../_partials/gh-body-file.md / -->