codeassembly-guidance 0.5.0 → 0.7.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 (110) hide show
  1. package/.meta/changelog.json +491 -0
  2. package/CHANGELOG.md +118 -0
  3. package/README.md +33 -4
  4. package/content/_partials/finding-grades.md +4 -0
  5. package/content/_partials/kb-unsearched-private-stores.md +6 -0
  6. package/content/codeassembly-content.yaml +4 -0
  7. package/content/collections/recommended.md +5 -2
  8. package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
  9. package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
  10. package/content/guidance/rulebooks/cli-conventions.md +17 -2
  11. package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
  12. package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
  13. package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
  14. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  15. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
  16. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -1
  17. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
  18. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
  19. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
  20. package/content/guidance/shared/AGENTS.md +1 -1
  21. package/content/scripts/check-prose.mjs +1 -1
  22. package/content/scripts/describe-change.mjs +88 -88
  23. package/content/scripts/manage-jira-ticket.mjs +113 -113
  24. package/content/scripts/select-lede-exemplars.mjs +85 -85
  25. package/content/scripts/validate-preferences.mjs +38 -38
  26. package/content/skills/_data/action-items.md +2 -2
  27. package/content/skills/_data/artifact-conventions.md +20 -10
  28. package/content/skills/_data/concision.md +1 -1
  29. package/content/skills/_data/entry-points.md +37 -0
  30. package/content/skills/_data/project-stage.md +9 -5
  31. package/content/skills/_data/recommendation-gradient.md +6 -6
  32. package/content/skills/_data/spike-conventions.md +20 -7
  33. package/content/skills/_data/ticket-source-resolution.md +21 -4
  34. package/content/skills/_data/title-templates.md +4 -4
  35. package/content/skills/_partials/commit-title-rendering.md +2 -1
  36. package/content/skills/_partials/implementation-order-list.md +27 -0
  37. package/content/skills/_partials/next-steps-after-plan.md +6 -5
  38. package/content/skills/_partials/option-format.md +8 -8
  39. package/content/skills/_partials/plan-template.md +5 -1
  40. package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
  41. package/content/skills/_partials/split-launch-prompts.md +2 -2
  42. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  43. package/content/skills/align-ticket-with-implementation/SKILL.md +1 -1
  44. package/content/skills/analyze-performance/SKILL.md +102 -0
  45. package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
  46. package/content/skills/assess-code-health/SKILL.md +16 -14
  47. package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
  48. package/content/skills/assess-usability/SKILL.md +5 -3
  49. package/content/skills/capture-event/SKILL.md +20 -11
  50. package/content/skills/capture-event/capture-event.mjs +122 -122
  51. package/content/skills/capture-feedback/SKILL.md +2 -1
  52. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
  53. package/content/skills/convert-agent-prompt/SKILL.md +60 -0
  54. package/content/skills/create-commit/SKILL.md +10 -5
  55. package/content/skills/create-pr/SKILL.md +11 -11
  56. package/content/skills/create-ticket/SKILL.md +1 -0
  57. package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
  58. package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
  59. package/content/skills/derive-session-context/derive-session-context.mjs +107 -107
  60. package/content/skills/design-and-plan/SKILL.md +6 -4
  61. package/content/skills/implement-plan/SKILL.md +4 -29
  62. package/content/skills/implementation-order/implementation-order.mjs +67 -0
  63. package/content/skills/index-prototypes/SKILL.md +36 -17
  64. package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
  65. package/content/skills/investigate-spike/SKILL.md +48 -0
  66. package/content/skills/kb-add/SKILL.md +12 -3
  67. package/content/skills/kb-add/kb-add.mjs +88 -88
  68. package/content/skills/kb-curate/kb-curate.mjs +88 -88
  69. package/content/skills/kb-edit/kb-edit.mjs +90 -90
  70. package/content/skills/kb-retrieve/SKILL.md +8 -3
  71. package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
  72. package/content/skills/kb-retrieve-events/SKILL.md +8 -3
  73. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
  74. package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
  75. package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
  76. package/content/skills/list-implementation-order/SKILL.md +23 -0
  77. package/content/skills/merge-bb-pr/SKILL.md +31 -8
  78. package/content/skills/merge-gh-pr/SKILL.md +25 -12
  79. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
  80. package/content/skills/merge-pr/SKILL.md +55 -20
  81. package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
  82. package/content/skills/plan/SKILL.md +3 -1
  83. package/content/skills/prepare-prototype-brief/SKILL.md +20 -14
  84. package/content/skills/refine-plan/SKILL.md +9 -4
  85. package/content/skills/refine-prototype/SKILL.md +5 -5
  86. package/content/skills/review-branch/SKILL.md +8 -8
  87. package/content/skills/review-criteria/SKILL.md +4 -4
  88. package/content/skills/review-gh-pr/SKILL.md +1 -1
  89. package/content/skills/revise-prose/SKILL.md +9 -8
  90. package/content/skills/revise-prose/revise-prose.mjs +111 -111
  91. package/content/skills/save-plan/SKILL.md +2 -0
  92. package/content/skills/start-ticket/SKILL.md +27 -0
  93. package/content/skills/streamline-guidance/streamline-guidance.mjs +76 -76
  94. package/content/skills/summarize-change/SKILL.md +27 -9
  95. package/content/skills/testing-conventions/SKILL.md +14 -3
  96. package/content/skills/triage-feedback/SKILL.md +4 -0
  97. package/content/skills/triage-spike-findings/SKILL.md +36 -12
  98. package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
  99. package/content/skills/wrap-up/SKILL.md +4 -0
  100. package/content/subagents/_data/claude.yaml +3 -0
  101. package/content/subagents/code-health-assessor.md +4 -4
  102. package/content/subagents/disposition-challenger.md +3 -4
  103. package/content/subagents/entry-drafter.md +2 -2
  104. package/content/subagents/handoff-reviewer.md +1 -1
  105. package/content/subagents/prototype-builder.md +69 -0
  106. package/content/subagents/usability-assessor.md +1 -1
  107. package/package.json +11 -10
  108. package/schemas/preferences.v1.json +74 -8
  109. package/schemas/work-types.v1.json +1 -1
  110. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
@@ -8,7 +8,7 @@ The render contract comes first; the doctrine behind it follows. Skills that clo
8
8
 
9
9
  ## Sweep before sending
10
10
 
11
- The failure prevented by this convention is not bad formatting. It is an ask that the agent never recognized as an ask. The formatting rules never applied to it. Before ending a turn, scan the draft for anything that invites a response and move every hit into the block.
11
+ This convention prevents an ask that the agent never recognized as an ask, and to which the formatting rules therefore never applied. Before ending a turn, scan the draft for anything that invites a response and move every hit into the block.
12
12
 
13
13
  Soft offers are the hardest form to spot. Each phrases a question as a statement:
14
14
 
@@ -25,7 +25,7 @@ Soft offers are the hardest form to spot. Each phrases a question as a statement
25
25
 
26
26
  Each is an action item. Restate it in the block as the concrete action that it proposes, and strike the offer from the prose. The observation that prompted it may stay; that is signal. The ask may not.
27
27
 
28
- The sweep runs in both directions. Having moved every ask into the block, read the block back and ask of each item whether it is really a question: An item whose answer follows from evidence that the agent already holds is a decision that it declined to make, and handing it back makes the user evaluate what a clause would have stated. Strike it, state the decision in the prose with its reason, and leave the block to the items that only the user can settle. An item that the agent could perform is a step that it declined to take: Run it, and leave in the block only the part that the agent cannot perform, named with its reason. A plan's "the owner exercises `/lab/book-row` by keyboard and on a touch device" is the counterexample: The agent drives the route through a debug browser, and the block holds at most how the control feels on a physical phone. A block emptied this way is a turn without an ask, which is a report rather than a failure.
28
+ The sweep runs in both directions. Having moved every ask into the block, read the block back and ask of each item whether it is really a question: An item whose answer follows from evidence that the agent already has is a decision that it declined to make, and handing it back makes the user evaluate what a clause would have stated. Strike it, state the decision in the prose with its reason, and leave the block to the items that only the user can settle. An item that the agent could perform is a step that it declined to take: Run it, and leave in the block only the part that the agent cannot perform, named with its reason. A plan's "the owner exercises `/lab/book-row` by keyboard and on a touch device" is the counterexample: The agent drives the route through a debug browser, and the block contains at most how the control feels on a physical phone. A block emptied this way is a turn without an ask, which is a report rather than a failure.
29
29
 
30
30
  An overload signal from the user, such as "I can't do this any more" or a count of the commands that they have run, empties the block in every turn until the user asks for something; the "Prompt formatting" section of the collaboration preferences states the rule.
31
31
 
@@ -4,7 +4,7 @@ Standards for AI-generated artifact storage, naming, and lifecycle.
4
4
 
5
5
  ## Purpose
6
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:
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 was 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
8
 
9
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
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.
@@ -33,6 +33,9 @@ All artifacts are stored under a configurable base directory (`base_dir`, defaul
33
33
  │ │ ├── sense.json
34
34
  │ │ ├── {lens}/report.md
35
35
  │ │ └── {lens}/proposals.json
36
+ │ ├── performance/ ← a performance analysis's measurements and summary, kept by `analyze-performance`
37
+ │ │ ├── summary.json
38
+ │ │ └── raw/ ← the helper's run directory: `manifest.json` and each page's raw responses
36
39
  │ ├── triage/ ← a findings triage's working files, kept by `triage-spike-findings`
37
40
  │ │ ├── findings.md
38
41
  │ │ ├── inventory.md
@@ -86,6 +89,10 @@ A `project.ticket_ref_prefix` other than `#` is part of the ticket ID, so it nam
86
89
 
87
90
  `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.
88
91
 
92
+ ### Performance measurements
93
+
94
+ `performance/` contains the working files of the ticket's performance analysis: `raw/`, the run directory that the `analyze-performance` helper writes, with its manifest and every PSI response, Lighthouse report, and CrUX record, and `summary.json`, the helper's summary of that directory. The `performance-findings` artifact cites raw files by paths relative to the ticket directory, so the measurements stay in the ticket directory.
95
+
89
96
  ### Triage working files
90
97
 
91
98
  `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.
@@ -230,7 +237,7 @@ Keys inside the `provenance:` block use **camelCase** (e.g., `baseSha`, `isInter
230
237
 
231
238
  ### Field definitions
232
239
 
233
- The table below lists only the universal fields. Artifact-specific extensions (`provenance.iteration`, `session_type`, `tickets_created`, `title`, `scope`, `type`, `responding_to`, etc.) are documented in the per-artifact sections below.
240
+ The table below lists only the universal fields. Artifact-specific extensions (`provenance.iteration`, `provenance.parent`, `session_type`, `tickets_created`, `title`, `scope`, `type`, `responding_to`, etc.) are documented in the per-artifact sections below.
234
241
 
235
242
  | Field | Required | Description |
236
243
  | -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -261,7 +268,7 @@ The table below lists only the universal fields. Artifact-specific extensions (`
261
268
 
262
269
  Most skills and subagents produce frontmatter by running `resolve-frontmatter.sh` in its default YAML mode and prepending the output verbatim. Two sites are deliberate exceptions and compose the YAML block themselves:
263
270
 
264
- - `refine-plan`: The `provenance:` block is case-branched on the input artifact's existing provenance (preserving `skill`, `baseSha`, `isInteractive`, and `iteration` from the original authoring skill, with fallbacks when the input does not have provenance). The shell flag surface cannot express this conditional logic cleanly.
271
+ - `refine-plan`: The `provenance:` block is case-branched on the input artifact's existing provenance (preserving `skill`, `baseSha`, `isInteractive`, and `iteration` from the original authoring skill, with fallbacks when the input does not have provenance), and `parent` is set from the input's file name. The shell flag surface cannot express this conditional logic cleanly.
265
272
  - `wrap-up` (deferred-findings artifact): `tickets_created` is a list of `{id, items}` objects, a structure that does not have a clean CLI expression and is best composed in the skill's own logic.
266
273
 
267
274
  Both read the script's JSON output and write the YAML frontmatter themselves. The pattern is intentional, not a workaround; keep new skills on the YAML mode path unless they have a similarly structural reason to deviate.
@@ -284,11 +291,12 @@ When authoring a new skill that needs session-context fields: Invoke the bundled
284
291
 
285
292
  ## Plan provenance
286
293
 
287
- This artifact uses the [universal artifact frontmatter](#universal-artifact-frontmatter) plus the following artifact-specific extension:
294
+ This artifact uses the [universal artifact frontmatter](#universal-artifact-frontmatter) plus the following artifact-specific extensions:
288
295
 
289
- | Field | Required | Description |
290
- | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
291
- | `provenance.iteration` | no | Refinement iteration counter. Absent on first authoring; set to `2` on first refinement, incremented on subsequent refinements. |
296
+ | Field | Required | Description |
297
+ | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
298
+ | `provenance.iteration` | no | Refinement iteration counter. Absent on first authoring; set to `2` on first refinement, incremented on subsequent refinements. |
299
+ | `provenance.parent` | no | File name of the plan that this plan was revised from. Absent on first authoring; set by `refine-plan` on every revision and never carried forward, so that each revision names its own predecessor. |
292
300
 
293
301
  Plan-specific `provenance.skill` values include `design-and-plan`, `plan`, `plan-mode`, and `unknown` (when the authoring skill cannot be determined). `refinedBy` is the skill that last processed the plan (typically `refine-plan`).
294
302
 
@@ -393,15 +401,17 @@ The first `coder_change-summary` in a run does not have dispositions (nothing to
393
401
  - `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/`
394
402
  - `devlog`: Development log entry (falls back to non-ticket path when a ticket is not in session)
395
403
  - `feedback-curation`: The record of a `curate-feedback` run: the count of events in each bin, the guidance commits against which the judges read, each mark with its result, and every event with its bin, reference, and reason; the run's working files stay in `{timestamp}_work/` beside it (falls back to non-ticket path when a ticket is not in session)
396
- - `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)
404
+ - `feedback-triage`: The record of a `triage-feedback` run: each reported 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)
397
405
  - `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
398
406
  - `merge`: Record of a merged pull request; `capture-lede-decision` reads its `## Body` as the merged side of a lede episode
407
+ - `performance-findings`: The measured performance of a site and the improvements ranked by expected effect, with field and lab data reported separately, each improvement's evidence, metric, and effort, what was left unmeasured, and the method; `analyze-performance` saves it, and `triage-spike-findings` reads it
399
408
  - `plan`: Implementation plan document
400
409
  - `plan-review`: Plan review findings (completeness and correctness analysis)
401
410
  - `plan-v2`: Refined implementation plan after review and revision
402
411
  - `pull-request`: PR description file; `capture-lede-decision` reads its `## What` as the agent's side of a lede episode
403
412
  - `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
404
413
  - `review`: Code review (ticket-level, commit scope)
414
+ - `spike-findings`: The findings and recommendation of a spike: the answer to each of the ticket's questions to answer, the recommendation on each decision to enable, the residual unknowns, the evidence, and any proposed work; `investigate-spike` saves it, and `triage-spike-findings` reads it
405
415
  - `ticket`: Issue ticket
406
416
  - `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
407
417
  - `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
@@ -476,9 +486,9 @@ A finding therefore has one of exactly two shapes, and consumers may rely on the
476
486
 
477
487
  A named change still has to be worth making. Decide at this gate whether it is, having established at the [Proposed-change gate](#proposed-change-gate) that a change exists.
478
488
 
479
- A finding costs more than its line length: the reader's time, the tokens spent asking you to reconsider it, the author's triage, and every later reader who reads both the finding and its rejection. Treat emitting any finding as taking on a burden of proof, weighed against that full cost, never against its line length.
489
+ A finding consumes more than its line length: the reader's time, the tokens spent asking you to reconsider it, the author's triage, and every later reader who reads both the finding and its rejection. Treat emitting any finding as taking on a burden of proof, weighed against everything that it consumes, never against its line length.
480
490
 
481
- This gate is the [concision principle](./concision.md) applied to findings: A finding, like any detail, costs every reader attention once that cost outweighs the decision that it enables.
491
+ This gate is the [concision principle](./concision.md) applied to findings: A finding, like any detail, wastes every reader's attention once the attention that it takes outweighs the decision that it enables.
482
492
 
483
493
  **Hedging language is a delete trigger, not a softening device.** If a finding's own qualifiers make it irrelevant, it does not belong. Drop it. If the condition genuinely holds now, drop the qualifier instead and state the finding plainly. Disqualifying signs include:
484
494
 
@@ -12,7 +12,7 @@ A load-bearing decision is worth elaborating; a routine one is worth a clause. A
12
12
 
13
13
  ## What to cut
14
14
 
15
- Intros, hedging, restated context, exhaustive enumeration. Process narration (how the work or decision was reached) when only the conclusion serves the reader.
15
+ Intros, hedging, restated context, exhaustive enumeration. Process narration (how the work was done or how the decision was made) when only the conclusion serves the reader.
16
16
 
17
17
  ## Self-test
18
18
 
@@ -0,0 +1,37 @@
1
+ # Entry points
2
+
3
+ The skill that opens the work in a ticket's worktree follows from the ticket's state and the artifacts in its ticket directory. This file states that rule once; {skill?:start-ticket} applies it when a session starts, and the split report of every plan skill names that skill rather than choosing an entry point of its own.
4
+
5
+ ## Inputs
6
+
7
+ - **The ticket's state**: open or closed, from the platform fetch in [ticket source resolution](ticket-source-resolution.md#platform-specific-fetch).
8
+ - **The branch's pull request**: `pr_url` from the session-context manifest, or else the pull request whose head is `branch_name` in any state (on GitHub, `gh pr list --head {branch_name} --state all --json url,state`). `pr_url` is usually null on a ticket branch, so the lookup is the common case.
9
+ - **The ticket directory**: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`, and the artifact types that [artifact conventions](artifact-conventions.md) defines. The newest plan is the one that the plan resolution of {skill?:implement-plan} selects (its [process](../implement-plan/SKILL.md#process), step 2): the greatest filename prefix across `*_plan.md` and `*_plan-v*.md`, never `*_plan-review.md`. The newest artifact of any other type is the one with the greatest filename prefix.
10
+
11
+ ## Routes
12
+
13
+ Check the routes in order and stop at the first match. Each route names the skill, the arguments that it passes, and the reason that the announcement states.
14
+
15
+ 1. **Done.** The ticket is closed, or the branch has a pull request that is open or merged: Stop, and report in one line `{ticket_ref} is {state}; PR {url} is {state}.`, with each clause only when it applies. A closed pull request that was not merged does not match, because the work may restart.
16
+
17
+ 2. **Unsettled plan.** The newest plan contains a list entry inside its `## Decisions taken` section whose text starts with 🔲: {skill?:refine-plan} with the plan path and the ticket. Reason: the plan contains a decision that no checkpoint approved. A 🔲 elsewhere in the plan, or one that a decision mentions rather than starts with, does not match.
18
+
19
+ 3. **Spike.** The ticket body, in its newest ticket artifact or on the platform, contains the `## Question` section and the `### Questions to answer` tier of the [spike ticket template](spike-conventions.md#spike-ticket-template), or the newest plan contains `## Investigation steps`:
20
+ - The ticket directory contains a `dispositions` artifact, which {skill?:triage-spike-findings} saves once its last write succeeds: Stop, and report the findings artifact and the dispositions. The spike is finished.
21
+ - The ticket directory contains `triage/dispositions.json` without a `dispositions` artifact: {skill?:triage-spike-findings} with the findings path, which resumes the interrupted triage from that record.
22
+ - A `spike-findings` artifact newer than the plan proposes work, judged by reading it with the test of {skill?:investigate-spike} step 8: {skill?:triage-spike-findings} with the findings path.
23
+ - A `spike-findings` artifact newer than the plan does not propose any work: Stop, and report it, with the closing post as the step that remains, which {skill?:investigate-spike} offers.
24
+ - The newest plan is a spike plan: {skill?:investigate-spike} with `--plan={path}` and `--ticket={ticket_ref}`.
25
+ - Otherwise: routes 5c and 5d, with `as a spike` after the ticket ref. That phrase is the explicit entry into spike mode that [spike conventions](spike-conventions.md) requires.
26
+
27
+ 4. **Prototype round.** The ticket directory contains a prototype set (`prototypes/manifest.json`, per [the set](../index-prototypes/SKILL.md#the-set)), or a `brief`, `comparison`, `idea-decisions`, or `refinement-log` artifact, or the ticket calls for two or more competing prototypes of one idea, judged by reading it:
28
+ - A `refinement-log` artifact: {skill?:design-and-plan} with the ticket ref, for the end vision and the ticket. {skill?:refine-prototype} saves the log when the refinement closes, so the log marks the refinement as done.
29
+ - An `idea-decisions` artifact that is newer than the newest `comparison` and does not contain an `open` row: {skill?:refine-prototype}.
30
+ - A `comparison` artifact, with an `idea-decisions` artifact newer than it that contains an `open` row, or none newer than it: {skill?:prepare-prototype-brief} with the ticket ref and the scope note `decide the ideas (step 7)`.
31
+ - Otherwise: {skill?:prepare-prototype-brief} with the ticket ref, adding the scope note `resume the round from the saved brief` when a `brief` artifact exists.
32
+
33
+ 5. **Feature.**
34
+ - a. Route 2 covers a plan that contains an unsettled decision.
35
+ - b. Any other plan: {skill?:implement-plan} with `--plan={path}` and `--ticket={ticket_ref}`.
36
+ - c. The ticket is ready: It states a problem, a proposed solution, and acceptance criteria, and applying [ticket evaluation](ticket-evaluation.md) does not find any divergence that needs a design conversation. This is a judgment, and the announcement states its reason. {skill?:plan} with the ticket ref.
37
+ - d. Otherwise: {skill?:design-and-plan} with the ticket ref.
@@ -1,12 +1,15 @@
1
1
  # Project stage
2
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.
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. A subdirectory, such as one experiment in a repository of experiments, declares its own stage as an entry of `project.stages`: a `path` relative to the repository root and the keys that it overrides. The manifest reports the entries as `project_stages`, each with the values that it inherits from the project filled in. The global preferences file never supplies a stage, because a stage describes one repository or a part of one.
4
+
5
+ The stage that governs a piece of work is the entry whose `path` contains the work's paths, matched at a directory boundary, with the longest containing path winning; a path under no entry takes the project's stage. When the work touches paths under more than one stage, each key takes its most demanding value among them. The table below lists each key's values from the least demanding to the most.
4
6
 
5
7
  ## Values
6
8
 
7
9
  | Key | Value | Meaning |
8
10
  | ------------- | -------------- | -------------------------------------------------------------------------------- |
9
- | `maturity` | `hobby` | Built for the owner's own use or learning; breakage costs only the owner's time. |
11
+ | `maturity` | `exploration` | The output's shape is still being found, and nothing depends on it yet. |
12
+ | | `hobby` | Built for the owner's own use or learning; breakage costs only the owner's time. |
10
13
  | | `early` | In use by others, but the shape is still changing; downtime is tolerated. |
11
14
  | | `production` | Others depend on it; downtime and data loss have real costs. |
12
15
  | `sensitivity` | `low` | Nothing that would harm anyone if published. |
@@ -19,8 +22,9 @@ A project declares its stage in its own `.agents/preferences.yaml`, under `proje
19
22
  ## What each value implies
20
23
 
21
24
  - **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`.
25
+ - **Availability.** `exploration` and `hobby` tolerate 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
26
  - **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.
27
+ - **Verification.** An output is unsettled while the governing maturity is `exploration`, or while the work is a spike, a proof of concept, a prototype, or an agent whose output the developer has not approved. While an output is unsettled, the developer judges it by reading it on real inputs, starting from the user's own example of the output when one exists. Golden references, answer keys, gated evals, and exhaustive fixtures wait until the developer approves an output as the target, and are frozen from it; any built earlier are provisional, not a contract. Unit tests of the deterministic code around the output are outside this rule.
24
28
 
25
29
  ## Rules
26
30
 
@@ -28,5 +32,5 @@ A project declares its stage in its own `.agents/preferences.yaml`, under `proje
28
32
  - **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
33
  - **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
34
  - **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.
35
+ - **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. Ask about verification only when the answer decides it: Work that is unsettled by its kind, such as a spike, does not need the maturity. Once the developer answers, declare the value in the project's `.agents/preferences.yaml`, under `project.stages` when it describes a subdirectory, and run `node {harness_home_dir}/scripts/validate-preferences.mjs` on the edited file, so that the question is asked once.
36
+ - **Record the premises.** State each value that decided a security, availability, infrastructure, or verification 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,11 +8,11 @@ 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 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.
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 context switches and idle waits add up to decision fatigue and a stalled pipeline. A menu that the agent could have resolved itself moves the work of the decision from the agent, for which it is cheap, to the developer, for whom it is expensive, and it looks like diligence while it happens, which is why it goes unnoticed and recurs.
12
12
 
13
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
- 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.
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 drawback 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 drawback before marking.
16
16
 
17
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
 
@@ -20,13 +20,13 @@ A wrong-but-stated recommendation is cheaper to correct than a decision handed b
20
20
 
21
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.
22
22
 
23
- ## Why a manufactured bullet costs more than none
23
+ ## Why a manufactured bullet is worse than none
24
24
 
25
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.
26
26
 
27
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.
28
28
 
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.
29
+ When the honest drawback is hard to find, that difficulty is itself evidence the option is strong. Spend the effort on finding the real drawback or on omitting the bullet, never on manufacturing a plausible-sounding one.
30
30
 
31
31
  A menu that looks balanced when the options are not misreports the analysis: It tells the developer that the agent found a close call. The developer relies on the menu for objective advice, and an even-handed look is the opposite of that when one option is sound and the others are flawed. A con whose size the reader cannot see does the same damage in a smaller form, since the reader has to investigate to learn that it is trivial. Both failures recur after being named, because a menu with a con on every option looks diligent while it misleads.
32
32
 
@@ -51,7 +51,7 @@ Same surface phrasing, two correct renderings:
51
51
  > 1. ■■□ Close #412 as superseded by this change:
52
52
  > - ➖ the alias request closes with it, and it is not tracked by any other ticket
53
53
  > 2. ■■□ Leave #412 open, retitled to the alias:
54
- > - ➖ its 30 comments about the shipped flag bury the one about the alias
54
+ > - ➖ its 30 comments about the flag that this change adds bury the one about the alias
55
55
 
56
56
  Both "yes" (close) and "no" (retitle) are concrete agent actions with their own tradeoffs. The decision edits a remote ticket, so it is in the gated class and is asked whatever the markers say.
57
57
 
@@ -88,5 +88,5 @@ Multiple questions in one response (Q1/Q2 identifiers):
88
88
  1. ■■□ Co-locate with its only consumer:
89
89
  - ➕ the check changes together with the form that it validates
90
90
  2. ■■□ Place in the shared utility package:
91
- - ➕ the billing package needs the same check once #588 lands
91
+ - ➕ the billing package needs the same check once #588 is merged
92
92
  ```
@@ -4,7 +4,7 @@ Spike work is an investigation, not a build: Its artifacts answer questions and
4
4
 
5
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.
6
6
 
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.
7
+ Spike mode is entered explicitly (the invocation signals it) and is not auto-detected from ticket type, label, or title. {skill?:start-ticket} signals it for a ticket or a plan written in the shape of a template below, per [entry points](entry-points.md). Everything outside the two templates below (source resolution, staleness, Q&A, saving) is unchanged from the feature flow.
8
8
 
9
9
  The concision and content-placement doctrines for feature tickets and plans apply unchanged; only what differs for a spike is stated here.
10
10
 
@@ -39,12 +39,12 @@ The concision and content-placement doctrines for feature tickets and plans appl
39
39
 
40
40
  - [ ] {A decision that the findings must make possible.}
41
41
 
42
- Deliverable: a findings & recommendation artifact, and the closing post on this ticket.
42
+ Deliverable: a findings & recommendation artifact, and the closing post on this ticket, followed by the ticket's close.
43
43
  ```
44
44
 
45
45
  `Context` and `Scope` are opt-in: Include either only when it adds signal on which the reader must act.
46
46
 
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.
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 as a `spike-findings` artifact via the standard `save-artifact` conventions, and the [closing post](#closing-post) on the ticket.
48
48
 
49
49
  ## Spike plan template
50
50
 
@@ -81,23 +81,36 @@ Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is
81
81
 
82
82
  ## Deliverable
83
83
 
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.}
84
+ {The findings & recommendation artifact (the answers reached, a recommendation, and residual unknowns), and the closing post on the ticket, followed by the ticket's close, offered at the closing checkpoint and made on consent, per `spike-conventions.md` § Closing post.}
85
85
  ```
86
86
 
87
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
88
 
89
+ The `investigate-spike` skill carries out a spike plan.
90
+
89
91
  ## Closing post
90
92
 
91
- The agent that ends a spike posts its conclusion on the ticket as a comment. The post contains:
93
+ The agent that ends a spike posts its conclusion on the ticket as a comment, then closes the ticket as completed. The post contains:
92
94
 
93
95
  - The answer to each of the ticket's questions to answer.
94
96
  - The recommendation on each of the ticket's decisions to enable.
95
97
  - The counts and the proposed groupings, when the spike produced them.
96
98
  - 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
99
 
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.
100
+ The skill that ends the spike offers the post. When the findings leave an item without a disposition, the triage round that disposes of them on the same ticket ends the spike: `triage-spike-findings` offers the post, and the skill that produced the findings names the triage as its next step without offering the post, which could not yet answer the decisions to enable. When the findings leave nothing to triage, the skill that produced them offers it. A follow-up triage ticket for a later batch does not take a closing post, because its dispositions comment is its record: `triage-spike-findings` closes it as completed, without a post, once that comment is posted, under the confirmation that covers the round's writes. The post on the original ticket names the follow-ups.
101
+
102
+ Offer the post and the close as one item in the closing action-items block of that skill, show the post's body, and name both actions in the ask: "Post this conclusion on #420 and close it as completed?". Make both writes only on consent: They are remote writes, and the developer is the one who can tell whether a finding is fit for the ticket's tracker and whether the spike is done. Consent to the offer is the developer's call on closing the ticket. When the developer declines, post nothing and leave the ticket open. When the session does not have a ticket, do not offer it.
103
+
104
+ Before writing, read the ticket's comments and its state, and decide each write on its own, so that a rerun neither posts the conclusion twice nor fails on a closed ticket:
105
+
106
+ - Post the conclusion unless a comment already opens with the post's first line. Pass the body through a file, per [gh body file](ticket-source-resolution.md#gh-body-file).
107
+ - Close the ticket with `gh issue close {number} --reason completed` only while its state is `OPEN`.
108
+
109
+ ## Findings batches
110
+
111
+ A batch is the set of items that one triage round inventories: the proposals, findings, and ideas of a findings artifact, with a grouping counted as one item. A batch holds at most 10 items, so that the developer can review it in one sitting.
99
112
 
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.
113
+ Each batch has a ticket of its own, which covers the assessment that produced the batch and the triage round that disposes of it, so the ticket's [closing post](#closing-post) follows the triage round. An assessment that spans more than one unit is an umbrella with one child per unit, each child covering that unit's assessment and triage round and blocked by the child before it, so that each round runs after the earlier rounds have posted their dispositions and can read them. A findings artifact that holds more than 10 items is triaged in several batches, each on its own ticket, as `triage-spike-findings` states.
101
114
 
102
115
  ## Aligning a spike
103
116
 
@@ -9,7 +9,7 @@ Resolve a ticket source argument into ticket content and metadata. Skills that a
9
9
  | URL to a known platform (GitHub, Jira, etc.) | Use the platform CLI or a connected read tool if available; otherwise, fetch the URL content |
10
10
  | Other URL | Fetch the URL content |
11
11
  | Shorthand reference (`#99`, `issue 99`, `GitHub issue #99`) | Resolve platform (see below), then fetch per [platform-specific fetch](#platform-specific-fetch) |
12
- | File path | Read the file |
12
+ | File path | Read the file, then read its remote comments per [Comments](#comments) |
13
13
  | Plain text | Use as-is |
14
14
  | _(no source provided)_ | Auto-resolve from environment (see [auto-resolve](#auto-resolve)) |
15
15
 
@@ -66,10 +66,10 @@ Determine which platform `#99` refers to using the [platform resolution cascade]
66
66
  ### GitHub
67
67
 
68
68
  ```
69
- gh issue view --json number,title,body,labels,updatedAt {number}
69
+ gh issue view --json number,title,body,comments,labels,updatedAt {number}
70
70
  ```
71
71
 
72
- Skills may request a subset of these fields. The `updatedAt` field is needed by skills that perform temporal analysis (e.g., staleness checks) and may be omitted by skills that only need the ticket content.
72
+ Skills may request a subset of these fields, and a subset that includes `body` also includes `comments`. The `updatedAt` field is needed by skills that perform temporal analysis (e.g., staleness checks) and may be omitted by skills that only need the ticket content.
73
73
 
74
74
  ### Jira
75
75
 
@@ -89,6 +89,12 @@ Read the ticket body with the default view, which renders the description as tex
89
89
  acli jira workitem view {key}
90
90
  ```
91
91
 
92
+ The view does not include the comments. Read them with a second call, which also renders as text, and treat its non-zero exit as the view's:
93
+
94
+ ```
95
+ acli jira workitem comment list --key {key} --paginate
96
+ ```
97
+
92
98
  When the source is a Jira URL rather than a key, the key is its `PROJECT-NUMBER` segment, which is the final segment of a `/browse/` URL.
93
99
 
94
100
  When a skill needs structured metadata, such as the `updated` timestamp for a staleness check, add `--json --fields '*navigable,-description'`. The `--json` flag returns the raw REST v3 response, in which the description is Atlassian Document Format rather than Markdown, so exclude it there and take the body from the default view. First-time setup is `acli jira auth login --web`, a browser flow that does not mint an API token.
@@ -98,12 +104,22 @@ When a skill needs structured metadata, such as the `updated` timestamp for a st
98
104
  - **Takes an issue URL**: Pass the ticket URL. Prefer this shape when both are connected, since it does not need site resolution.
99
105
  - **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.
100
106
 
107
+ A tool of either shape that takes a field list is asked for the `comment` field with the issue; one that returns every field does not need it.
108
+
101
109
  **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
110
 
103
111
  **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
112
 
105
113
  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
114
 
115
+ ## Comments
116
+
117
+ A ticket's comments are part of its content: A comment can record an assessment, a decision, a scope change, or a correction that the body does not contain. Both platform fetches above return them oldest first.
118
+
119
+ **The body stays the ticket of record.** A comment that extends or contradicts the body is a divergence. Report it through the divergence report that the reading skill already makes, and when the skill does not make one, name the comment and how it diverges in the skill's own output. Never apply such a comment silently, and never ignore it.
120
+
121
+ **A file.** A ticket artifact copies the body at one moment, so a comment posted after the copy is missing from it. When the file's frontmatter names a `ticket_ref`, read that remote ticket's comments per [platform-specific fetch](#platform-specific-fetch), as [Open blockers](#open-blockers) reads its blockers. A file without a `ticket_ref` does not have any comments to read.
122
+
107
123
  ## Open blockers
108
124
 
109
125
  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.
@@ -118,7 +134,7 @@ Name a blocker `#N` when its URL has the same `owner/repo` as the ticket's, and
118
134
 
119
135
  **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
136
 
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.
137
+ **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. [Comments](#comments) reads the same remote ticket's comments.
122
138
 
123
139
  **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
140
 
@@ -174,6 +190,7 @@ After resolution, store the following metadata for use by the calling skill:
174
190
  - **Issue number**: The numeric identifier, if applicable
175
191
  - **Last-updated date**: The ticket's last-modified timestamp, if available from the platform
176
192
  - **Ticket content**: The title, body, labels, and any other retrieved fields
193
+ - **Comments**: Each comment's author, date, and body, oldest first, read per [Comments](#comments)
177
194
  - **Open blockers**: For a skill that checks them, each open blocker's reference and title, read per [Open blockers](#open-blockers)
178
195
  - **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)
179
196
 
@@ -125,7 +125,7 @@ For a subject not matched by the template, the run reports `{"matched":false}` a
125
125
 
126
126
  **Under a template that does not name `{ticket_ref}`, the bundle strips one first.** The bundle removes three leading forms before the match: `## `, `#123 ` (with an optional `.1` or `-1` suffix), and `ABC-123 `. These are the forms that release-kit strips, which lets a commit template that does not name `{ticket_ref}` read a subject that contains one.
127
127
 
128
- **When a parse could read a group as present or absent, present wins.** This is release-kit's reading, and it makes `agents|feat: Add foo` parse as scoped and typed rather than as a bare title. See [What the grammar does not support](#what-the-grammar-does-not-support) for the cost.
128
+ **When a parse could read a group as present or absent, present wins.** This is release-kit's reading, and it makes `agents|feat: Add foo` parse as scoped and typed rather than as a bare title. See [What the grammar does not support](#what-the-grammar-does-not-support) for the misreadings that this allows.
129
129
 
130
130
  The run refuses a surface whose template is empty, since there is nothing to read the subject through, and refuses if the taxonomy cannot be read.
131
131
 
@@ -499,7 +499,7 @@ node {harness_home_dir}/scripts/describe-change.mjs resolve-scopes \
499
499
 
500
500
  **`path_scopes` maps each path as given to its scope**, under the spelling that the invocation passed, so a caller can look a result up by the path that it asked about. **`scopes` is the sorted set** of the scopes that those paths name between them.
501
501
 
502
- **The derivation**: `@williamthorsen/nmr/workspace` resolves the repository root's workspace directories, honoring the `packages` patterns that `pnpm-workspace.yaml` declares, negative patterns included; each is named by its basename. The repository adds scope directories of its own under `project.scopes` in its `.agents/preferences.yaml`, each named by its `name` or else by its basename. A path's scope is the name of the longest of those directories that contains it, so a nested directory wins over the one enclosing it, whether either is a package or a declared directory. A path outside every scope directory resolves to `root`.
502
+ **The derivation**: `@williamthorsen/nmr/workspace` resolves the repository root's workspace directories, honoring the `packages` patterns that `pnpm-workspace.yaml` declares, negative patterns included; each is named by its basename. The repository root is never one of them, even when `pnpm-workspace.yaml` declares it as a package (`'.'`), so a path in a root package resolves to `root` rather than to the checkout directory's name. The repository adds scope directories of its own under `project.scopes` in its `.agents/preferences.yaml`, each named by its `name` or else by its basename. A path's scope is the name of the longest of those directories that contains it, so a nested directory wins over the one enclosing it, whether either is a package or a declared directory. A path outside every scope directory resolves to `root`.
503
503
 
504
504
  ```yaml
505
505
  project:
@@ -509,7 +509,7 @@ project:
509
509
  name: ios
510
510
  ```
511
511
 
512
- **A declared directory owns a scope without becoming a workspace**, so a deliverable that is not a Node package, such as a SwiftPM app, can own one without a placeholder manifest that nmr and release-kit would then act on. A declared directory that is also a package directory takes its declared name. Only the project preferences file declares scopes; `project.scopes` in the global file does not have any effect. An entry that is not a mapping, that does not have a string `path`, that has a `name` that is not a non-empty string, or whose path is absolute, outside the repository, missing, or not a directory is skipped with a warning, and a `project.scopes` that is not a list is ignored with one.
512
+ **A declared directory owns a scope without becoming a workspace**, so a deliverable that is not a Node package, such as a SwiftPM app, can own one without a placeholder manifest that nmr and release-kit would then act on. A declared directory that is also a package directory takes its declared name. Only the project preferences file declares scopes; `project.scopes` in the global file does not have any effect. An entry that is not a mapping, that does not have a string `path`, that has a `name` that is not a non-empty string, that names the repository root without a `name`, or whose path is absolute, outside the repository, missing, or not a directory is skipped with a warning, and a `project.scopes` that is not a list is ignored with one.
513
513
 
514
514
  **A repository without scope directories yields `root` for every path.** A root that is not a pnpm workspace and does not declare scopes discovers none, as does one whose patterns do not match any directory, and this is how a consumer detects that the repository does not have a scope vocabulary. A repository on another package manager reads the same way unless it declares scopes.
515
515
 
@@ -614,7 +614,7 @@ A template that round-trips every well-formed record but loses a token for some
614
614
 
615
615
  **Value-dependent ambiguity passes the check.** The check runs over well-formed values, so it accepts a template whose ambiguity depends on what a value happens to contain. Under `[{ticket_ref} ]{title}`, the title `#466 Add foo` reads back as ticket reference `#466` and title `Add foo`. Because that matches how release-kit reads it, the behavior is compatibility rather than a defect, but a caller that keeps both halves separately should not rely on a round trip to recover them.
616
616
 
617
- The same cost applies to the piped-scope convention, in which a present group wins. `Rename kb|docs: the shared layer` reads back as scope `Rename kb`, type `docs`, title `the shared layer`. The type check prevents the misreading when the type is nonsense, so `Support a|b: syntax` is unmatched, but not when the type is real.
617
+ The same misreading affects the piped-scope convention, in which a present group wins. `Rename kb|docs: the shared layer` reads back as scope `Rename kb`, type `docs`, title `the shared layer`. The type check prevents the misreading when the type is nonsense, so `Support a|b: syntax` is unmatched, but not when the type is real.
618
618
 
619
619
  ## Scope values
620
620
 
@@ -4,10 +4,11 @@ node {harness_home_dir}/scripts/describe-change.mjs render-titles \
4
4
  --scope "{scope}" \
5
5
  --type "{type}" \
6
6
  --ticket-ref "{ticket_ref}" \
7
+ --project-root "{project_root}" \
7
8
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('commit_title',''))"
8
9
  ```
9
10
 
10
- Pass `--ticket-ref` from the bundled session-context deriver so that a project whose `commit.title_format` references `{ticket_ref}` renders the ref. Omit any flag whose value is empty or null, `--ticket-ref` included when session context reports it as `null`.
11
+ Pass `--ticket-ref` from the bundled session-context deriver so that a project whose `commit.title_format` references `{ticket_ref}` renders the ref. Omit any flag whose value is empty or null, `--ticket-ref` included when session context reports it as `null`. Pass `--project-root` only when the invoking skill names the directory in which it works: The renderer reads `commit.title_format` from the project that contains the directory in which it runs, unless the flag names another.
11
12
 
12
13
  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
14
 
@@ -0,0 +1,27 @@
1
+ ## Implementation-order list
2
+
3
+ Print open tickets in the order in which to implement them, as a tree for a narrow column. The step that links here names the tickets, in the order in which it reached them, an `--external` entry for each ticket outside GitHub, and an `--edge` for each dependency that the tracker does not record. A bundled helper reads the tickets, orders them, and writes the fixed part of every line. You shorten the titles and mark the publish gates.
4
+
5
+ 1. **Run the helper.**
6
+
7
+ ```bash
8
+ node {harness_home_dir}/skills/implementation-order/implementation-order.mjs \
9
+ --ticket {OWNER/REPO#N} --external "{KEY}={Title}" --edge "{BLOCKER}>{BLOCKED}"
10
+ ```
11
+
12
+ Write a GitHub ticket as `OWNER/REPO#N`, taking the repository from the ticket's URL. Repeat each flag once per ticket or edge. Each side of an edge is `OWNER/REPO#N` or a key that an `--external` declares, and the blocked side is a listed ticket. On a non-zero exit, report the helper's stderr and do not print the list: A list that lacks a ticket misstates the order.
13
+
14
+ The helper prints `{"tickets": [...], "omitted": [...], "cycle": [...]}`. `tickets` is in list order. `omitted` names the closed tickets, which the list leaves out.
15
+
16
+ 2. **Shorten each title** to at most the ticket's `titleBudget` characters. Cut words rather than end with an ellipsis, and keep the leading verb. Leave a title that already fits as it is.
17
+
18
+ 3. **Find the publish gates.** A gate follows a ticket when its change must be published, and the dependency upgraded in a consuming repository, before a ticket that it blocks can start. Look for one wherever a ticket blocks a ticket in another repository; `crossRepository` marks those among `otherBlockers`, and a child in the tree whose `repository` differs from its parent's is another. The tracker does not record whether the blocked repository consumes the blocking one as a published package, so judge that from the tickets and the conversation.
19
+
20
+ 4. **Print the list** as one fenced block. For each ticket, in order:
21
+ - Its line: `lead`, then the shortened title.
22
+ - Its `blockerLine`, when that is not null.
23
+ - Its gate, when step 3 found one: `gateLead`, then the package's name, then `, upgrade in `, then the prefix of each consuming repository in the list, separated by commas. Name the package rather than the repository when the two differ.
24
+
25
+ A ticket's place states its blocker: It is indented under the ticket that blocks it. `blockerLine` names the blockers that the indent does not state.
26
+
27
+ When `cycle` is not empty, add a last line inside the block: `⚠️`, then the labels of the tickets in `cycle`, then `block each other`.
@@ -16,12 +16,13 @@ Present all three options as a numbered list per [option format](#option-format)
16
16
 
17
17
  **One `➕` line is mandatory rather than omitted.** When Refine plan is the selected option, it must include a `➕` line naming the specific unsettled decision that the pass would raise (rule 1). The line names an open decision, never a reassurance about work already done: "a refine pass is the cheap way to find out whether I missed something" is the shape that this requirement exists to forbid. When Split the ticket is the selected option, it must include a `➕` line naming the plan's size and the pieces (rule 2). Selecting either without its line is a defect: If the line cannot be written, the rule did not match and the cascade continues.
18
18
 
19
- **Spike plans.** A spike plan has `## Investigation steps` rather than `## Tasks` (see [spike conventions](../_data/spike-conventions.md)). It is carried out to produce findings rather than implemented to produce a diff, and `implement-plan` reads only the feature shape. Render option 3 as 🔬 Investigate, without invoking a skill; the agent works the investigation steps directly and ends the run with the plan's `## Deliverable`, which includes offering the [closing post](../_data/spike-conventions.md#closing-post) on the ticket and making it on consent. Option 1 renders unchanged. Option 2 renders at □□□ with the `➖` that a spike produces findings rather than pieces that ship. In the recommendation rules below, rule 2 never matches on a spike plan, so Investigate is the fallthrough whenever rule 1 does not match.
19
+ **Spike plans.** A spike plan has `## Investigation steps` rather than `## Tasks` (see [spike conventions](../_data/spike-conventions.md)). It is carried out to produce findings rather than implemented to produce a diff. Render option 3 as 🔬 Investigate, invoking {skill?:investigate-spike} with plan: {plan_path}, ticket: {ticket_source}; that skill works the investigation steps and ends the run with the plan's `## Deliverable`: the offer of the [closing post](../_data/spike-conventions.md#closing-post) on the ticket or, when the findings propose work, the recommendation of the triage round that offers it. Option 1 renders unchanged. Option 2 renders at □□□ with the `➖` that a spike produces findings rather than pieces that ship. In the recommendation rules below, rule 2 never matches on a spike plan, so Investigate is the fallthrough whenever rule 1 does not match.
20
20
 
21
21
  Options that invoke a skill include context-clearing guidance:
22
22
 
23
23
  - **Refine plan**: Prepend "Clear context, then..." because the plan artifact is self-contained; prior conversation wastes tokens and can introduce bias.
24
24
  - **Split the ticket**: No "Clear context" prefix, and no pasted invocation line; the split runs in this session because the library doesn't have a skill for it, and it cuts the pieces from the saved plan. See [Splitting the ticket](#splitting-the-ticket).
25
+ - **Investigate**: No "Clear context" prefix, for the same reason as Implement: `investigate-spike` re-resolves the plan and ticket from the environment.
25
26
  - **Implement**: No "Clear context" prefix. The ticket and plan are self-contained, so `implement-plan` works the same in this session or in a fresh one, and clearing gains nothing: Unlike a refine or review pass, implementation is not harmed by sharing the planner's view. The user can also paste the same line into a fresh session, or into the other harness with its own skill sigil, in which the skill re-resolves the plan and ticket from the environment.
26
27
 
27
28
  Example (rendered for the default case, in which the recommendation rules below select Implement):
@@ -40,7 +41,7 @@ Skill names for each option:
40
41
 
41
42
  - 🧠 **Refine plan** -> `refine-plan`
42
43
  - ✂️ **Split the ticket** -> `{skill:create-ticket}`, once per piece, in this session
43
- - 🚀 **Implement** -> `implement-plan`; on a spike plan the option is 🔬 **Investigate** and does not invoke a skill
44
+ - 🚀 **Implement** -> `implement-plan`; on a spike plan the option is 🔬 **Investigate** -> `investigate-spike`
44
45
 
45
46
  ### Recommendation rules
46
47
 
@@ -64,9 +65,9 @@ Select the recommended option by checking these rules in order and stopping at t
64
65
 
65
66
  When rule 1 matches, the rendered option must name that decision on a `➕` line. Being unable to write the line means rule 1 did not match.
66
67
 
67
- 2. **Split the ticket**: Recommend only when the plan is too large for one implement-and-review pass, and it contains two or more pieces that can each be merged and verified on their own. Both halves are required: Too large without a seam is not a match, and a seam in a plan that one pass would cover is not one either.
68
+ 2. **Split the ticket**: Recommend only when the plan is too large for one implement-and-review pass, and it contains two or more pieces that can each be merged and verified on their own. Both halves are required: Too large without a seam is not a match, and a seam in a plan that one pass would cover is not one either. A plan that touches two or more repositories matches whatever its size: Each repository is a piece, per the ticketing preferences.
68
69
 
69
- A piece gets its own ticket when it can be merged and verified on its own, not when it looks large enough to deserve one. The `➕` line names the size and the pieces, each with the tasks that it takes: `➕ eleven tasks across three packages, and two pieces ship on their own: the schema change (tasks 1–4), then the reader that consumes it (tasks 5–11)`.
70
+ A piece gets its own ticket when it can be merged and verified on its own, not when it looks large enough to deserve one. The `➕` line names the size and the pieces, each with the tasks that it takes: `➕ eleven tasks across three packages, and two pieces ship on their own: the schema change (tasks 1–4), then the reader that consumes it (tasks 5–11)`. For a plan that spans repositories, the pieces are the repositories: `➕ three tasks across two repositories: the helper in williamthorsen/codeassembly (task 1), then the skill that calls it here (tasks 2–3)`.
70
71
 
71
72
  Structural properties (new module boundaries, changed interfaces, several packages) make a plan _more likely_ to be too large. They are evidence to weigh, and none of them matches rule 2 on its own.
72
73
 
@@ -92,7 +93,7 @@ Each skill supplies its own recommendation context (e.g., whether the plan was d
92
93
 
93
94
  **Save the first piece's plan.** With two pieces, save the first piece's plan in the originating ticket's directory per `{skill:save-artifact}`. Its timestamp is later than the approved plan's, so `implement-plan` resolves it rather than the unsplit plan.
94
95
 
95
- **Report.** Report the ticket references and the plan paths. Choose each ticket's entry point from what its artifacts settle: `{skill?:design-and-plan}` when the piece's design needs a closer look; `{skill?:plan}` when the ticket is ready but does not have a plan; `{skill?:refine-plan}` when its plan leaves a decision unsettled, by the test in rule 1 above; `{skill?:implement-plan}` otherwise, which is the default for a plan cut from an approved one.
96
+ **Report.** Report the ticket references and the plan paths. Every piece enters at `{skill?:start-ticket}`, invoked without arguments, which chooses the skill that opens the work from the piece's artifacts per [entry points](../_data/entry-points.md). A fact that the choice needs and that the artifacts do not state belongs in the piece's ticket or plan, not in its prompt.
96
97
 
97
98
  <!-- include: split-launch-prompts.md / -->
98
99