codeassembly-guidance 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/.meta/changelog.json +757 -0
  2. package/CHANGELOG.md +181 -0
  3. package/README.md +125 -95
  4. package/bin/codeassembly-validate-preferences.js +18 -0
  5. package/content/_partials/README.md +2 -2
  6. package/content/_partials/code-style.md +1 -1
  7. package/content/_partials/comment-discipline.md +1 -1
  8. package/content/_partials/plain-speech-calibration.md +4 -0
  9. package/content/_partials/technical-recommendations.md +1 -0
  10. package/content/codeassembly-content.yaml +11 -1
  11. package/content/collections/all.md +2 -2
  12. package/content/collections/atlassian.md +2 -1
  13. package/content/collections/recommended.md +9 -2
  14. package/content/collections/triage.md +3 -67
  15. package/content/collections/williamthorsen.md +2 -1
  16. package/content/guidance/README.md +1 -1
  17. package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
  18. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  19. package/content/guidance/rulebooks/codeassembly-content-specification.md +32 -9
  20. package/content/guidance/rulebooks/commit-conventions.md +2 -2
  21. package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
  22. package/content/guidance/rulebooks/readme-conventions.md +3 -3
  23. package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
  24. package/content/guidance/rulebooks/shell-conventions.md +17 -23
  25. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  26. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +14 -12
  27. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
  28. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
  29. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
  30. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
  31. package/content/guidance/shared/AGENTS.md +8 -0
  32. package/content/scripts/README.md +5 -2
  33. package/content/scripts/check-branch-currency.mjs +11 -0
  34. package/content/scripts/check-prose.mjs +171 -0
  35. package/content/scripts/describe-change.mjs +97 -97
  36. package/content/scripts/manage-jira-ticket.mjs +99 -94
  37. package/content/scripts/resolve-frontmatter.sh +1 -1
  38. package/content/scripts/resolve-review-run.mjs +9 -9
  39. package/content/scripts/select-lede-exemplars.mjs +87 -87
  40. package/content/scripts/validate-preferences.mjs +146 -0
  41. package/content/skills/_data/artifact-conventions.md +46 -14
  42. package/content/skills/_data/branch-currency.md +36 -0
  43. package/content/skills/_data/change-record.md +2 -2
  44. package/content/skills/_data/design-priorities.md +3 -3
  45. package/content/skills/_data/project-stage.md +32 -0
  46. package/content/skills/_data/recommendation-gradient.md +9 -7
  47. package/content/skills/_data/scope-and-deferral.md +1 -1
  48. package/content/skills/_data/spike-conventions.md +1 -1
  49. package/content/skills/_data/ticket-evaluation.md +2 -2
  50. package/content/skills/_data/ticket-source-resolution.md +36 -3
  51. package/content/skills/_data/title-templates.md +19 -11
  52. package/content/skills/_partials/action-items.md +2 -2
  53. package/content/skills/_partials/commit-title-rendering.md +1 -1
  54. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  55. package/content/skills/_partials/next-steps-after-plan.md +10 -10
  56. package/content/skills/_partials/next-steps-after-review.md +9 -9
  57. package/content/skills/_partials/option-format.md +18 -17
  58. package/content/skills/_partials/plan-template.md +5 -5
  59. package/content/skills/_partials/split-ticket-compose.md +1 -1
  60. package/content/skills/_partials/split-ticket-create.md +1 -1
  61. package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
  62. package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
  63. package/content/skills/add-change-record/SKILL.md +2 -2
  64. package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
  65. package/content/skills/anti-patterns/SKILL.md +1 -1
  66. package/content/skills/assess-usability/SKILL.md +96 -0
  67. package/content/skills/capture-event/SKILL.md +2 -2
  68. package/content/skills/capture-event/capture-event.mjs +89 -89
  69. package/content/skills/capture-lede-decision/SKILL.md +4 -4
  70. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
  71. package/content/skills/collaborate/SKILL.md +1 -1
  72. package/content/skills/create-gh-pr/SKILL.md +24 -9
  73. package/content/skills/create-pr/SKILL.md +5 -5
  74. package/content/skills/create-ticket/SKILL.md +61 -16
  75. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  76. package/content/skills/derive-session-context/derive-session-context.mjs +95 -94
  77. package/content/skills/design-and-plan/SKILL.md +13 -10
  78. package/content/skills/groom-backlog/SKILL.md +8 -6
  79. package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
  80. package/content/skills/implement-plan/SKILL.md +25 -21
  81. package/content/skills/index-prototypes/SKILL.md +85 -30
  82. package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
  83. package/content/skills/kb-add/SKILL.md +2 -1
  84. package/content/skills/kb-add/kb-add.mjs +128 -128
  85. package/content/skills/kb-curate/SKILL.md +9 -7
  86. package/content/skills/kb-curate/kb-curate.mjs +103 -103
  87. package/content/skills/kb-edit/SKILL.md +3 -3
  88. package/content/skills/kb-edit/kb-edit.mjs +94 -94
  89. package/content/skills/kb-retrieve/kb-retrieve.mjs +78 -77
  90. package/content/skills/kb-retrieve-events/SKILL.md +1 -1
  91. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +78 -77
  92. package/content/skills/kb-update-events/SKILL.md +2 -2
  93. package/content/skills/kb-update-events/kb-update-events.mjs +108 -108
  94. package/content/skills/merge-bb-pr/SKILL.md +1 -1
  95. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
  96. package/content/skills/merge-pr/SKILL.md +11 -11
  97. package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
  98. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
  99. package/content/skills/plan/SKILL.md +1 -1
  100. package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
  101. package/content/skills/pull-from-backlog/SKILL.md +3 -3
  102. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
  103. package/content/skills/refine-plan/SKILL.md +7 -3
  104. package/content/skills/refine-prototype/SKILL.md +113 -0
  105. package/content/skills/respond-to-review/SKILL.md +1 -1
  106. package/content/skills/review-bb-pr/SKILL.md +1 -1
  107. package/content/skills/review-branch/SKILL.md +4 -2
  108. package/content/skills/review-criteria/SKILL.md +36 -3
  109. package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
  110. package/content/skills/revise-comments/SKILL.md +38 -5
  111. package/content/skills/revise-prose/SKILL.md +1 -1
  112. package/content/skills/revise-prose/revise-prose.mjs +119 -119
  113. package/content/skills/save-artifact/SKILL.md +2 -0
  114. package/content/skills/streamline-guidance/SKILL.md +1 -1
  115. package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
  116. package/content/skills/summarize-change/SKILL.md +22 -13
  117. package/content/skills/testing-conventions/SKILL.md +74 -7
  118. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  119. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  120. package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
  121. package/content/skills/update-jira-ticket/SKILL.md +20 -8
  122. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
  123. package/content/skills/update-project-guidance/SKILL.md +2 -2
  124. package/content/subagents/_data/claude.yaml +6 -0
  125. package/content/subagents/_data/rovo.yaml +12 -2
  126. package/content/subagents/canary.md +2 -1
  127. package/content/subagents/disposition-challenger.md +78 -0
  128. package/content/subagents/entry-drafter.md +14 -10
  129. package/content/subagents/handoff-reviewer.md +2 -2
  130. package/content/subagents/plan-reviewer.md +1 -1
  131. package/content/subagents/prose-reviser.md +4 -2
  132. package/content/subagents/ticket-assessor.md +9 -6
  133. package/content/subagents/usability-assessor.md +157 -0
  134. package/package.json +15 -11
  135. package/schemas/preferences.v1.json +29 -2
  136. package/schemas/work-types.v1.json +1 -1
  137. package/content/skills/testing-conventions/mistakes.md +0 -1
@@ -2,6 +2,14 @@
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
+ - **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.
12
+
5
13
  ## Directory structure
6
14
 
7
15
  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 +25,21 @@ All artifacts are stored under a configurable base directory (`base_dir`, defaul
17
25
  │ │ ├── manifest.json
18
26
  │ │ ├── shots/{slug}-v{n}.png
19
27
  │ │ └── {slug}-v{n}.html
28
+ │ ├── usability/ ← a usability assessment's lens reports and evidence, kept by `assess-usability`
29
+ │ │ ├── {lens}-report.md
30
+ │ │ └── {lens}/{finding-id}-{slug}.png
31
+ │ ├── triage/ ← a findings triage's working files, kept by `triage-spike-findings`
32
+ │ │ ├── findings.md
33
+ │ │ ├── inventory.md
34
+ │ │ ├── recommendations.md
35
+ │ │ ├── challenge.md
36
+ │ │ ├── dispositions.json
37
+ │ │ ├── preview/ ← the rendered comments shown at the confirmation
38
+ │ │ │ ├── dispositions-comment.md
39
+ │ │ │ └── comment-{issue}.md
40
+ │ │ └── rendered/ ← the rendered comments that are posted
41
+ │ │ ├── dispositions-comment.md
42
+ │ │ └── comment-{issue}.md
20
43
  │ └── {run-id}/ ← review run directory
21
44
  │ ├── {NN}_{role}_{artifact}.md
22
45
  │ └── ...
@@ -32,7 +55,7 @@ All artifacts are stored under a configurable base directory (`base_dir`, defaul
32
55
 
33
56
  ### Project slug
34
57
 
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`.
58
+ 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
59
 
37
60
  ### Ticket ID
38
61
 
@@ -42,7 +65,15 @@ A `project.ticket_ref_prefix` other than `#` is part of the ticket ID, so it nam
42
65
 
43
66
  ### Prototype sets
44
67
 
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.
68
+ `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.
69
+
70
+ ### Usability evidence
71
+
72
+ `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.
73
+
74
+ ### Triage working files
75
+
76
+ `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
77
 
47
78
  ### Run directories
48
79
 
@@ -60,11 +91,7 @@ projects/{project-slug}/tickets/{ticket-id}/{run-id}/
60
91
 
61
92
  Example: `20260221-034100Z-interactive`
62
93
 
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).
94
+ 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
95
 
69
96
  ## Path resolution
70
97
 
@@ -125,7 +152,7 @@ Devlogs and deferred-findings artifacts are dual-homed: When a ticket is in sess
125
152
  - **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
153
  - **artifact-type**: One of the registered types (see below)
127
154
 
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.
155
+ 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
156
 
130
157
  ### Run artifacts (review workflow)
131
158
 
@@ -236,7 +263,7 @@ Invocation surface:
236
263
  node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs
237
264
  ```
238
265
 
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).
266
+ 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
267
 
241
268
  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
269
 
@@ -301,7 +328,7 @@ This artifact uses the [universal artifact frontmatter](#universal-artifact-fron
301
328
 
302
329
  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
330
 
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.
331
+ **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
332
 
306
333
  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
334
 
@@ -323,7 +350,7 @@ This artifact uses the [universal artifact frontmatter](#universal-artifact-fron
323
350
 
324
351
  ## run-index.json
325
352
 
326
- Machine-readable metadata for a run directory. The retired orchestration engine wrote it, and no current skill does. `run-core` parses it.
353
+ Machine-readable metadata for a run directory. The retired orchestration engine wrote it; the current skills do not. `run-core` parses it.
327
354
 
328
355
  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
356
 
@@ -707,16 +734,21 @@ The first `coder_change-summary` in a run does not have dispositions (nothing to
707
734
 
708
735
  - `brief`: The shared brief that a round of prototype builders receives; `prepare-prototype-brief` saves it at its checkpoint
709
736
  - `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
737
+ - `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
738
  - `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)
739
+ - `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
740
  - `devlog`: Development log entry (falls back to non-ticket path when a ticket is not in session)
741
+ - `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
742
  - `merge`: Record of a merged pull request; `capture-lede-decision` reads its `## Body` as the merged side of a lede episode
714
743
  - `plan`: Implementation plan document
715
744
  - `plan-review`: Plan review findings (completeness and correctness analysis)
716
745
  - `plan-v2`: Refined implementation plan after review and revision
717
746
  - `pull-request`: PR description file; `capture-lede-decision` reads its `## What` as the agent's side of a lede episode
747
+ - `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
748
  - `review`: Code review (ticket-level, commit scope)
719
749
  - `ticket`: Issue ticket
750
+ - `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
751
+ - `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
752
 
721
753
  ### Non-ticket artifacts
722
754
 
@@ -897,9 +929,9 @@ Insights never have criticality, never block a merge, and never count toward a r
897
929
 
898
930
  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
931
 
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.
932
+ 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
933
 
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.
934
+ 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
935
 
904
936
  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
937
 
@@ -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
 
@@ -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
 
@@ -69,7 +69,7 @@ Three patterns signal a design that hasn't reached it:
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
71
 
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.
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 scope: renaming, restructuring, generalizing. That cost is real but bounded; the cost of keeping a poorly integrated change compounds.
73
73
 
74
74
  ## Reconciliation
75
75
 
@@ -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
 
@@ -59,7 +59,7 @@ Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is
59
59
 
60
60
  ## Decisions taken
61
61
 
62
- - {A decision that the agent took without asking, with its one-line reason; append `(provisional)` when it awaits the checkpoint.}
62
+ - {⏳ while it awaits the checkpoint} {A decision that the agent took without asking, with its one-line reason.}
63
63
 
64
64
  ## Timebox
65
65
 
@@ -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 / -->
@@ -50,7 +50,7 @@ The bundle does not have a shebang, so the `node` prefix is required. Each subco
50
50
  ### What stops a run and what only warns
51
51
 
52
52
  - A configured template that the engine cannot invert stops every subcommand that reads the templates, naming the surface, the template, and the defect. `resolve-ticket-type`, `resolve-effective-record`, `render-block`, `render-details`, `consolidate-entries`, `check-merge-body`, `amend-entry`, `resolve-scopes`, and `resolve-labels` read none, so a defective template does not stop them. See [What the grammar refuses](#what-the-grammar-refuses).
53
- - A configured template that renders a subject it cannot read back, for some record shape that carries a type, causes a warning on stderr from every subcommand that reads the templates, naming the surface, the template, and the record shape. The run continues and its output is unchanged. See [Optional groups](#optional-groups).
53
+ - A configured template that renders a subject it cannot read back, for some record shape that has a type, causes a warning on stderr from every subcommand that reads the templates, naming the surface, the template, and the record shape. The run continues and its output is unchanged. See [Optional groups](#optional-groups).
54
54
  - Malformed YAML in a preferences file stops every subcommand that reads the templates, naming the file.
55
55
  - Malformed YAML in `pnpm-workspace.yaml` or in the project preferences file stops `resolve-scopes`, naming the file.
56
56
  - A `project.scopes` entry that `resolve-scopes` cannot honor causes a warning naming the entry's index and fault, and the run skips that entry and resolves the rest. See [`resolve-scopes`](#resolve-scopes).
@@ -58,6 +58,14 @@ The bundle does not have a shebang, so the `node` prefix is required. Each subco
58
58
  - An unreadable taxonomy causes a warning from `render-titles`, which then renders from templates that nothing verified or checked for a lost token, and stops `parse-title`, `consolidate-branch`, `consolidate-entries`, `render-details`, `resolve-effective-record`, `resolve-merge`, and `amend-entry`.
59
59
  - Outside a repository, a subcommand that anchors at the repository root warns on stderr and anchors at the working directory instead: the `.agents/` and `.meta/label-map.json` lookups, so the global templates still render, and `resolve-scopes`'s discovery of workspace and declared scope directories.
60
60
  - A `title_format` resolving to anything but a string causes a warning on stderr, and the next source supplies the template.
61
+ - A type or scope that a configured label map does not define causes a warning from `resolve-labels`, naming the key and the map. A repository that does not configure a map does not cause any.
62
+ - A `--project-root` that does not name a readable directory stops `render-titles` and `resolve-labels`, naming the path.
63
+
64
+ ## Reading another repository's configuration
65
+
66
+ `render-titles` and `resolve-labels` take `--project-root <dir>`, which names the directory to read in place of the invoking repository's root: its `.agents/preferences.yaml` and its `.meta/label-map.json`. A relative path resolves against the invoking directory. The global preferences file still supplies a template that the directory's file omits. The run skips git's root resolution, so it does not warn outside a repository. Every other subcommand refuses the flag.
67
+
68
+ `create-ticket` uses it to resolve the title and the labels of a ticket filed in another repository, from a directory into which that repository's configuration has been fetched.
61
69
 
62
70
  ## `render-titles`
63
71
 
@@ -72,7 +80,7 @@ node {harness_home_dir}/scripts/describe-change.mjs render-titles \
72
80
  --pr-number "{pr_number}"
73
81
  ```
74
82
 
75
- Its flags are `--title`, `--scope`, `--type`, `--breaking`, `--ticket-ref`, and `--pr-number`, and all are optional. Each missing flag means the corresponding token resolves to the empty string. Always quote `--title` so that titles with spaces or shell-special characters are passed intact. Add `--breaking` for a breaking change; `--type feat!` is also accepted and splits into the bare type and the marker. A `--scope` of `*` normalizes to an empty scope, so the sentinel never appears in a rendered title.
83
+ Its flags are `--title`, `--scope`, `--type`, `--breaking`, `--ticket-ref`, `--pr-number`, and [`--project-root`](#reading-another-repositorys-configuration), and all are optional. Each missing flag means the corresponding token resolves to the empty string. Always quote `--title` so that titles with spaces or shell-special characters are passed intact. Add `--breaking` for a breaking change; `--type feat!` is also accepted and splits into the bare type and the marker. A `--scope` of `*` normalizes to an empty scope, so the sentinel never appears in a rendered title.
76
84
 
77
85
  Output is JSON:
78
86
 
@@ -163,7 +171,7 @@ node {harness_home_dir}/scripts/describe-change.mjs consolidate-branch --base or
163
171
 
164
172
  **A commit with `Change:` trailers contributes those entries and not its subject.** Because a condensed commit's subject renders the record to which its trailers already consolidate, reading both would count the branch's entries twice. See [The `Change:` trailer](./change-record.md#the-change-trailer).
165
173
 
166
- **The consolidated record ranks; it does not count.** One `feat` outranks three `fix` commits on the same branch, breaking outranks non-breaking, and the tier and listing order in [`work-types.json`](./work-types.json) settle the rest. Every field of `consolidated_record` is `null` when the run did not find any entry, which is how a caller distinguishes a branch without entries from one whose consolidated record does not name a scope. The consolidated record does not name a title: A caller takes that from the change summary.
174
+ **Consolidation ranks the entries; it does not count them.** One `feat` outranks three `fix` commits on the same branch, breaking outranks non-breaking, and the tier and listing order in [`work-types.json`](./work-types.json) settle the rest. Every field of `consolidated_record` is `null` when the run did not find any entry, which is how a caller distinguishes a branch without entries from one whose consolidated record does not name a scope. The consolidated record does not name a title: A caller takes that from the change summary.
167
175
 
168
176
  **A subject that does not match any template is listed in `unmatched` rather than dropped**, so a mistyped prefix stays visible instead of silently shrinking the set that the consolidated record is derived from.
169
177
 
@@ -173,7 +181,7 @@ The run refuses outright if the taxonomy cannot be read, since the entries have
173
181
 
174
182
  ## `consolidate-entries`
175
183
 
176
- `consolidate-entries` reports the record to which a change's [change entries](./change-record.md#terms) consolidate. Its one flag, `--entries-file`, is required and names a YAML file holding a top-level list of entry mappings, in the shape that `entry-drafter` returns.
184
+ `consolidate-entries` reports the record to which a change's [change entries](./change-record.md#terms) consolidate. Its one flag, `--entries-file`, is required and names a YAML file containing a top-level list of entry mappings, in the shape that `entry-drafter` returns.
177
185
 
178
186
  ```bash
179
187
  node {harness_home_dir}/scripts/describe-change.mjs consolidate-entries --entries-file entries-20260920-223418Z.yaml
@@ -194,11 +202,11 @@ node {harness_home_dir}/scripts/describe-change.mjs consolidate-entries --entrie
194
202
  { "consolidated_record": { "breaking": false, "scope": "agents", "type": "feat" } }
195
203
  ```
196
204
 
197
- **Each entry expands to one record per scope**, and an entry that does not name a scope expands to one record without a scope, which keeps a change touching nothing scoped rankable on its type. The expanded list is then ranked exactly as `consolidate-branch` ranks the commit entries, so one rule serves both sources: breaking outranks non-breaking, then the tier and listing order in [`work-types.json`](./work-types.json), and exactly one distinct scope survives.
205
+ **Each entry expands to one record per scope**, and an entry that does not name a scope expands to one record without a scope, so that a change that does not touch any scope can still be ranked by its type. The expanded list is then ranked exactly as `consolidate-branch` ranks the commit entries, so one rule serves both sources: breaking outranks non-breaking, then the tier and listing order in [`work-types.json`](./work-types.json), and exactly one distinct scope survives.
198
206
 
199
207
  **An entry whose `type` the taxonomy does not declare is left as written and is unrankable**, so it does not contribute a type, as an unrankable commit entry does. Every field of `consolidated_record` is `null` for an empty list, which is how a caller distinguishes a change without entries from one whose consolidated record does not name a scope.
200
208
 
201
- **The entries arrive in a file rather than through flags** because `text` is arbitrary prose containing backticks and quotes, which a shell argument would expand or truncate.
209
+ **The run reads the entries from a file rather than from flags** because `text` is arbitrary prose containing backticks and quotes, which a shell argument would expand or truncate.
202
210
 
203
211
  The run refuses an entries file that cannot be read, that is not valid YAML, or that is malformed, naming the defect: a value that is not a list, an item that is not a mapping, a missing or blank `type` or `text`, a `breaking` that is not a boolean, a `scopes` that is not a list of strings, and a `migration` that is not a string or spans more than one line, and a `text` or `migration` cut short by a YAML comment, which a space followed by `#` opens in an unquoted value; the error names the entry, the field, and the dropped text. A blank or null `migration` reads as absent, and a key that the grammar does not declare is ignored. It also refuses outright if the taxonomy cannot be read, since the entries have nothing to rank against.
204
212
 
@@ -315,7 +323,7 @@ The output is JSON whose `details` contains the body, without the `## Details` h
315
323
  - **Scope tags.** When the entries do not all name the same set of scopes, each bullet ends with one space and its scopes as bare `#scope` tags, comma-separated and each named once. An entry without scopes does not end with a tag. When every entry names the same set, whatever its order, the bullets do not end with tags, since the consolidated record already names that scope.
316
324
  - **Empty list.** An empty list yields an empty `details`, and the caller omits the section.
317
325
 
318
- The run refuses an entry whose `type` the taxonomy does not declare as a key or an alias, `feat!` included, since `breaking` carries the marker; and an entry whose `text` spans more than one line, which would break its bullet. It refuses an entries file exactly as `consolidate-entries` does, and refuses outright if the taxonomy cannot be read or does not declare an `emoji` and a `label` for `markers.breaking` and every type.
326
+ The run refuses an entry whose `type` the taxonomy does not declare as a key or an alias, `feat!` included, since `breaking` records the marker; and an entry whose `text` spans more than one line, which would break its bullet. It refuses an entries file exactly as `consolidate-entries` does, and refuses outright if the taxonomy cannot be read or does not declare an `emoji` and a `label` for `markers.breaking` and every type.
319
327
 
320
328
  ## `resolve-merge`
321
329
 
@@ -505,11 +513,11 @@ project:
505
513
 
506
514
  **A path is read relative to the repository root**, which git resolves from the invoking directory, so an absolute path and a root-relative one resolve alike whatever subdirectory the caller ran from. A path outside the root resolves to `root`. When git does not resolve a repository root, the run warns and anchors at the invoking directory.
507
515
 
508
- **The subcommand does not define a workspace rule of its own.** It delegates workspace discovery to `@williamthorsen/nmr/workspace`, whose resolver reads the same `pnpm-workspace.yaml` patterns that release-kit reads to name the workspaces it builds changelogs under. The resolver is bundled into the deployed script, which therefore needs nothing installed in the repository that it runs in. `scope-labels.unit.test.ts` in `packages/guidance` holds the derived vocabulary to the `scope:` labels that `.config/release-kit.config.ts` declares. A change to the workspace discovery rule belongs upstream, in nmr.
516
+ **The subcommand does not define a workspace rule of its own.** It delegates workspace discovery to `@williamthorsen/nmr/workspace`, whose resolver reads the same `pnpm-workspace.yaml` patterns that release-kit reads to name the workspaces it builds changelogs under. The resolver is bundled into the deployed script, which therefore needs nothing installed in the repository that it runs in. `scope-labels.unit.test.ts` in `packages/guidance` checks the derived vocabulary against the `scope:` labels that `.config/release-kit.config.ts` declares. A change to the workspace discovery rule belongs upstream, in nmr.
509
517
 
510
518
  ## `resolve-labels`
511
519
 
512
- `resolve-labels` reports the labels for a change, from the effective record that the flags pass and, when `--body-file` names a body, from the entries in its last `change-record` block. Every flag is optional. Without `--body-file`, as for a ticket that does not have a body yet, the run labels the record alone.
520
+ `resolve-labels` reports the labels for a change, from the effective record that the flags pass and, when `--body-file` names a body, from the entries in its last `change-record` block. Every flag is optional, [`--project-root`](#reading-another-repositorys-configuration) included. Without `--body-file`, as for a ticket that does not have a body yet, the run labels the record alone.
513
521
 
514
522
  ```bash
515
523
  node {harness_home_dir}/scripts/describe-change.mjs resolve-labels \
@@ -523,7 +531,7 @@ node {harness_home_dir}/scripts/describe-change.mjs resolve-labels \
523
531
 
524
532
  **`labels` is the union of what the record and the entries name**, each mapped through the repository's `.meta/label-map.json`: the type label of every type, `breaking` when the record or any entry is breaking, and the scope label of every scope. Type labels come first, then `breaking`, then scope labels. Within each group the record's label leads, followed by the entries' labels in the order in which the entries name them, and each label appears once.
525
533
 
526
- **A key that the map does not name, and a scope of `*`, do not add a label.** The run does not read the taxonomy, so an undeclared type is labeled only when the map names it. A label map that is absent, unparseable, or empty does not yield any labels at all, `breaking` included.
534
+ **A key that the map does not name, and a scope of `*`, do not add a label.** The run warns on stderr for each such key except `*`, naming it and the map. The run does not read the taxonomy, so an undeclared type is labeled only when the map names it. A label map that is absent, unparseable, or empty does not yield any labels at all, `breaking` included, and does not cause any warning.
527
535
 
528
536
  **The body file may be the change summary itself**, since only its last `change-record` block is read and the frontmatter is ignored. A body that does not contain a block, or a block without entries, is labeled from the flags alone. The run warns and does the same for a malformed block or entry list, and it refuses a body file that cannot be read. `--type feat!` is accepted and splits into the bare type and the marker.
529
537
 
@@ -544,7 +552,7 @@ A template that omits `{title}` produces a title without the bare title text: Th
544
552
 
545
553
  A `[...]` group renders verbatim when every token directly inside it resolves non-empty. When one is empty, the whole group drops, literals included.
546
554
 
547
- A group containing both `{scope}` and `{type}` therefore drops the type along with an absent scope, and a `*` scope is absent by the time the group decides. When preferences load, the bundle warns of such a template, naming the record shape that loses the type; it warns in the same way of a group that drops `{breaking}`. When the type should stay in the title of a change without a scope, nest the scope in a group of its own, as the piped-scope convention does.
555
+ A group containing both `{scope}` and `{type}` therefore drops the type along with an absent scope, and a `*` scope is absent by the time the renderer decides whether to keep the group. When preferences load, the bundle warns of such a template, naming the record shape that loses the type; it warns in the same way of a group that drops `{breaking}`. When the type should stay in the title of a change without a scope, nest the scope in a group of its own, as the piped-scope convention does.
548
556
 
549
557
  `{breaking}` never decides a group. A non-breaking change would otherwise drop the very prefix that contains the marker.
550
558
 
@@ -1,6 +1,6 @@
1
- **Close the turn with an action-items block.** Before sending, sweep the draft for anything that invites a response: A soft offer ("let me know if", "say the word and I will", "worth knowing", "I can also") is an ask, and leaving it in the narrative is how asks get missed. A check that a command, a test, or a browser could settle is run, not asked, and a command for the developer to run is a handoff. Prose may discuss; only the block may ask. Move every ask into one labelled block at the end of the response, stated as the concrete action and punctuated as the question that it is. A turn without an ask does not have a block. When this skill defines its own canonical block for asks (a next-steps menu, an action menu, a finding-keyed question list), that block takes precedence: Add the ad-hoc ask to it, keeping the block's own identifiers, and never close a turn with two competing blocks.
1
+ **Close the turn with an action-items block.** Before sending, sweep the draft for anything that invites a response: A soft offer ("let me know if", "say the word and I will", "worth knowing", "I can also") is an ask, and leaving it in the narrative is how asks get missed. Run a check that a command, a test, or a browser could settle rather than ask for it; a command for the developer to run is a handoff. Prose may discuss; only the block may ask. Move every ask into one labelled block at the end of the response, stated as the concrete action and punctuated as the question that it is. Do not add a block to a turn without an ask. When this skill defines its own canonical block for asks (a next-steps menu, an action menu, a finding-keyed question list), use that block: Add the ad-hoc ask to it, keeping the block's own identifiers, and never close a turn with two competing blocks.
2
2
 
3
- Prefix with `A` an action that you propose to take (a "yes" makes you act) and with `Q` information or a judgment that you need (a "yes" only informs you). Number each so that the user can answer the whole block in one line. A non-ask, such as a status note, is neither and stays in the prose; prefix and marker always agree. A single-item block does not prefix its item.
3
+ Prefix with `A` an action that you propose to take (a "yes" makes you act) and with `Q` information or a judgment that you need (a "yes" only informs you). Number each so that the user can answer the whole block in one line. Leave a non-ask, such as a status note, in the prose without a prefix, and keep each prefix in agreement with its marker. Do not prefix the item of a single-item block.
4
4
 
5
5
  ```
6
6
  ---
@@ -11,4 +11,4 @@ Pass `--ticket-ref` from the bundled session-context deriver so that a project w
11
11
 
12
12
  Parse the output with a JSON parser (`python3` above; `jq -r '.commit_title'` if `jq` is available) rather than `grep` or `cut`: A rendered title may contain backslash-escaped double quotes, which a regex extractor silently truncates.
13
13
 
14
- The pipeline prints the rendered title. Read it from the command's output and use it verbatim as the commit title, which already contains the rendered prefix, per the configured `commit.title_format`, and the bare title text. Assigning the parse instead prints nothing, and a shell variable does not survive to the commit call, so the title must be carried forward as literal text into the message file. If the script is not found, fall back to the bare `{title}`.
14
+ The pipeline prints the rendered title. Read it from the command's output and use it verbatim as the commit title, which already contains the rendered prefix, per the configured `commit.title_format`, and the bare title text. Assigning the parse instead prints nothing, and a shell variable does not survive to the commit call, so copy the title as literal text into the message file. If the script is not found, fall back to the bare `{title}`.
@@ -0,0 +1 @@
1
+ **Flatten task lists for Markdown and HTML clients.** Before submitting a Jira description or comment through a `contentFormat` tool or an HTML tool, on creation and update alike, convert task-list syntax (`- [ ]` / `- [x]`) to plain `-` bullets. Neither Jira conversion maps it to task items: The brackets are escaped, so each line persists as a bullet reading `\[ \] ...`. The `acli` path is the exception and keeps its checkboxes, because `manage-jira-ticket.mjs` converts task-list syntax to native `taskList` / `taskItem` nodes.