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.
- package/.meta/changelog.json +757 -0
- package/CHANGELOG.md +181 -0
- package/README.md +125 -95
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +2 -2
- package/content/_partials/code-style.md +1 -1
- package/content/_partials/comment-discipline.md +1 -1
- package/content/_partials/plain-speech-calibration.md +4 -0
- package/content/_partials/technical-recommendations.md +1 -0
- package/content/codeassembly-content.yaml +11 -1
- package/content/collections/all.md +2 -2
- package/content/collections/atlassian.md +2 -1
- package/content/collections/recommended.md +9 -2
- package/content/collections/triage.md +3 -67
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
- package/content/guidance/rulebooks/cli-conventions.md +192 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +32 -9
- package/content/guidance/rulebooks/commit-conventions.md +2 -2
- package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
- package/content/guidance/rulebooks/readme-conventions.md +3 -3
- package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
- package/content/guidance/rulebooks/shell-conventions.md +17 -23
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +14 -12
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
- package/content/guidance/shared/AGENTS.md +8 -0
- package/content/scripts/README.md +5 -2
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +97 -97
- package/content/scripts/manage-jira-ticket.mjs +99 -94
- package/content/scripts/resolve-frontmatter.sh +1 -1
- package/content/scripts/resolve-review-run.mjs +9 -9
- package/content/scripts/select-lede-exemplars.mjs +87 -87
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/artifact-conventions.md +46 -14
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/change-record.md +2 -2
- package/content/skills/_data/design-priorities.md +3 -3
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +9 -7
- package/content/skills/_data/scope-and-deferral.md +1 -1
- package/content/skills/_data/spike-conventions.md +1 -1
- package/content/skills/_data/ticket-evaluation.md +2 -2
- package/content/skills/_data/ticket-source-resolution.md +36 -3
- package/content/skills/_data/title-templates.md +19 -11
- package/content/skills/_partials/action-items.md +2 -2
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +10 -10
- package/content/skills/_partials/next-steps-after-review.md +9 -9
- package/content/skills/_partials/option-format.md +18 -17
- package/content/skills/_partials/plan-template.md +5 -5
- package/content/skills/_partials/split-ticket-compose.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
- package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
- package/content/skills/add-change-record/SKILL.md +2 -2
- package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
- package/content/skills/anti-patterns/SKILL.md +1 -1
- package/content/skills/assess-usability/SKILL.md +96 -0
- package/content/skills/capture-event/SKILL.md +2 -2
- package/content/skills/capture-event/capture-event.mjs +89 -89
- package/content/skills/capture-lede-decision/SKILL.md +4 -4
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
- package/content/skills/collaborate/SKILL.md +1 -1
- package/content/skills/create-gh-pr/SKILL.md +24 -9
- package/content/skills/create-pr/SKILL.md +5 -5
- package/content/skills/create-ticket/SKILL.md +61 -16
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +95 -94
- package/content/skills/design-and-plan/SKILL.md +13 -10
- package/content/skills/groom-backlog/SKILL.md +8 -6
- package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
- package/content/skills/implement-plan/SKILL.md +25 -21
- package/content/skills/index-prototypes/SKILL.md +85 -30
- package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
- package/content/skills/kb-add/SKILL.md +2 -1
- package/content/skills/kb-add/kb-add.mjs +128 -128
- package/content/skills/kb-curate/SKILL.md +9 -7
- package/content/skills/kb-curate/kb-curate.mjs +103 -103
- package/content/skills/kb-edit/SKILL.md +3 -3
- package/content/skills/kb-edit/kb-edit.mjs +94 -94
- package/content/skills/kb-retrieve/kb-retrieve.mjs +78 -77
- package/content/skills/kb-retrieve-events/SKILL.md +1 -1
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +78 -77
- package/content/skills/kb-update-events/SKILL.md +2 -2
- package/content/skills/kb-update-events/kb-update-events.mjs +108 -108
- package/content/skills/merge-bb-pr/SKILL.md +1 -1
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
- package/content/skills/merge-pr/SKILL.md +11 -11
- package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
- package/content/skills/plan/SKILL.md +1 -1
- package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
- package/content/skills/pull-from-backlog/SKILL.md +3 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
- package/content/skills/refine-plan/SKILL.md +7 -3
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +1 -1
- package/content/skills/review-bb-pr/SKILL.md +1 -1
- package/content/skills/review-branch/SKILL.md +4 -2
- package/content/skills/review-criteria/SKILL.md +36 -3
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
- package/content/skills/revise-comments/SKILL.md +38 -5
- package/content/skills/revise-prose/SKILL.md +1 -1
- package/content/skills/revise-prose/revise-prose.mjs +119 -119
- package/content/skills/save-artifact/SKILL.md +2 -0
- package/content/skills/streamline-guidance/SKILL.md +1 -1
- package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
- package/content/skills/summarize-change/SKILL.md +22 -13
- package/content/skills/testing-conventions/SKILL.md +74 -7
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
- package/content/skills/update-jira-ticket/SKILL.md +20 -8
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
- package/content/skills/update-project-guidance/SKILL.md +2 -2
- package/content/subagents/_data/claude.yaml +6 -0
- package/content/subagents/_data/rovo.yaml +12 -2
- package/content/subagents/canary.md +2 -1
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +14 -10
- package/content/subagents/handoff-reviewer.md +2 -2
- package/content/subagents/plan-reviewer.md +1 -1
- package/content/subagents/prose-reviser.md +4 -2
- package/content/subagents/ticket-assessor.md +9 -6
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +15 -11
- package/schemas/preferences.v1.json +29 -2
- package/schemas/work-types.v1.json +1 -1
- 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
|
|
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/`
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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`.**
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
|
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`,
|
|
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
|
-
**
|
|
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
|
|
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,
|
|
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
|
|
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`
|
|
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`
|
|
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
|
|
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.
|
|
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.
|
|
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
|
|
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.
|