codeassembly-guidance 0.6.0 → 0.8.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 +446 -0
- package/CHANGELOG.md +107 -0
- package/README.md +47 -51
- package/bin/codeassembly-validate-preferences.js +2 -8
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/kb-unsearched-private-stores.md +6 -0
- package/content/_partials/plain-speech.md +2 -2
- package/content/_partials/ticket-assessment.md +3 -3
- package/content/codeassembly-content.yaml +8 -0
- package/content/collections/recommended.md +6 -0
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +6 -3
- package/content/guidance/rulebooks/cross-repo-migration-conventions.md +27 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
- package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
- package/content/guidance/rulebooks/visual-design-conventions.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +3 -18
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +7 -1
- package/content/guidance/rulebooks/williamthorsen-visual-design-preferences.md +14 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +5 -3
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -20
- package/content/guidance/shared/AGENTS.md +3 -4
- package/content/scripts/README.md +1 -1
- package/content/scripts/check-branch-currency.mjs +7 -7
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/describe-change.mjs +89 -89
- package/content/scripts/manage-jira-ticket.mjs +162 -160
- package/content/scripts/select-lede-exemplars.mjs +85 -85
- package/content/scripts/validate-preferences.mjs +41 -41
- package/content/skills/_data/artifact-conventions.md +3 -3
- package/content/skills/_data/entry-points.md +1 -1
- package/content/skills/_data/project-stage.md +9 -5
- package/content/skills/_data/reduced-object-relatives.md +15 -0
- package/content/skills/_data/spike-conventions.md +16 -6
- package/content/skills/_data/ticket-evaluation.md +3 -0
- package/content/skills/_partials/implementation-order-list.md +27 -0
- package/content/skills/_partials/merge-settled-criterion.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +2 -2
- package/content/skills/_partials/plan-template.md +3 -1
- package/content/skills/_partials/resolve-plan-and-ticket.md +2 -2
- package/content/skills/_partials/split-launch-prompts.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +3 -3
- package/content/skills/analyze-performance/SKILL.md +1 -1
- package/content/skills/assess-code-health/SKILL.md +4 -4
- package/content/skills/assess-code-health/assess-code-health.mjs +20 -20
- package/content/skills/assess-ticket/SKILL.md +3 -1
- package/content/skills/assess-ticket/next-steps-after-assessment.md +11 -14
- package/content/skills/assess-usability/SKILL.md +4 -4
- package/content/skills/capture-event/SKILL.md +20 -11
- package/content/skills/capture-event/capture-event.mjs +123 -123
- package/content/skills/capture-feedback/SKILL.md +2 -1
- package/content/skills/capture-lede-decision/SKILL.md +1 -1
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
- package/content/skills/collaborate/SKILL.md +1 -1
- package/content/skills/condense-branch/SKILL.md +18 -36
- package/content/skills/condense-branch/condense-branch.mjs +17 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +9 -11
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-devlog/SKILL.md +4 -4
- package/content/skills/create-gh-pr/SKILL.md +9 -11
- package/content/skills/create-pr/SKILL.md +10 -12
- package/content/skills/create-ticket/SKILL.md +22 -15
- package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
- package/content/skills/curate-feedback/SKILL.md +2 -2
- package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
- package/content/skills/derive-session-context/derive-session-context.mjs +120 -120
- package/content/skills/design-and-plan/SKILL.md +10 -8
- package/content/skills/groom-backlog/groom-backlog.mjs +15 -15
- package/content/skills/implement-plan/SKILL.md +4 -2
- package/content/skills/implementation-order/implementation-order.mjs +67 -0
- package/content/skills/index-prototypes/SKILL.md +2 -2
- package/content/skills/investigate-spike/SKILL.md +3 -3
- package/content/skills/kb-add/SKILL.md +12 -3
- package/content/skills/kb-add/kb-add.mjs +88 -88
- package/content/skills/kb-curate/kb-curate.mjs +88 -88
- package/content/skills/kb-edit/kb-edit.mjs +90 -90
- package/content/skills/kb-retrieve/SKILL.md +8 -3
- package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
- package/content/skills/kb-retrieve-events/SKILL.md +8 -3
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
- package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
- package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
- package/content/skills/list-gh-progress-items/SKILL.md +36 -0
- package/content/skills/list-gh-progress-items/list-gh-progress-items.mjs +68 -0
- package/content/skills/list-implementation-order/SKILL.md +23 -0
- package/content/skills/merge-bb-pr/SKILL.md +40 -19
- package/content/skills/merge-gh-pr/SKILL.md +34 -23
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
- package/content/skills/merge-pr/SKILL.md +64 -31
- package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
- package/content/skills/plan/SKILL.md +5 -3
- package/content/skills/prepare-prototype-brief/SKILL.md +5 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +22 -22
- package/content/skills/refine-plan/SKILL.md +5 -3
- package/content/skills/refine-prototype/SKILL.md +2 -1
- package/content/skills/respond-to-review/SKILL.md +4 -4
- package/content/skills/review-bb-pr/SKILL.md +1 -2
- package/content/skills/review-branch/SKILL.md +19 -14
- package/content/skills/review-criteria/SKILL.md +2 -2
- package/content/skills/review-gh-pr/SKILL.md +1 -2
- package/content/skills/review-pr/SKILL.md +2 -3
- package/content/skills/revise-prose/revise-prose.mjs +109 -109
- package/content/skills/save-artifact/SKILL.md +4 -6
- package/content/skills/save-plan/SKILL.md +4 -2
- package/content/skills/start-ticket/SKILL.md +1 -1
- package/content/skills/streamline-guidance/streamline-guidance.mjs +80 -80
- package/content/skills/summarize-change/SKILL.md +20 -9
- package/content/skills/summarize-chat/SKILL.md +2 -2
- package/content/skills/testing-conventions/SKILL.md +2 -2
- package/content/skills/triage-feedback/SKILL.md +6 -2
- package/content/skills/triage-spike-findings/SKILL.md +33 -24
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +19 -19
- package/content/skills/update-project-guidance/SKILL.md +1 -1
- package/content/skills/wrap-up/SKILL.md +8 -4
- package/content/skills/write-progress-report/SKILL.md +111 -0
- package/content/skills/write-progress-report/write-progress-report.mjs +150 -0
- package/content/subagents/disposition-challenger.md +7 -6
- package/content/subagents/entry-drafter.md +2 -0
- package/content/subagents/usability-assessor.md +3 -2
- package/package.json +13 -12
- package/schemas/preferences.v1.json +82 -8
- package/schemas/work-types.v1.json +1 -1
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: williamthorsen-ticketing-preferences
|
|
3
3
|
description: William Thorsen's preferences for how work is split across tickets, how the relationships between them are recorded, and which figures a ticket body states.
|
|
4
4
|
delivery: hook
|
|
5
|
-
version: '
|
|
5
|
+
version: '10'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's ticketing preferences
|
|
@@ -13,6 +13,12 @@ When work deserves more than one pull request, give each pull request its own ti
|
|
|
13
13
|
|
|
14
14
|
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. When the count is a judgment, cut finer: Merging two tickets that turned out to be one costs an edit and a close, while splitting one that turned out to be four costs a rewrite of the original, new children, a re-cut plan, and whatever was committed against the superseded contract.
|
|
15
15
|
|
|
16
|
+
Before deciding the ticket count of work that spans several layers or adds a new subsystem, estimate its size: the layers and subsystems that it touches, and the approximate source and test lines. State the estimate wherever the count is decided. When the pieces of such work can each be merged and verified on their own, recommend the split, and do not offer one ticket at equal strength. That only the last piece is visible to a user is not a reason to keep the work whole: An earlier piece is verified through its tests and its API.
|
|
17
|
+
|
|
18
|
+
Adding a package to a monorepo is two tickets. The first adds the empty scaffold with its documentation and its package references, such as the workspace lists, labels, lockfile, README, and identity checks, and it passes the repository's checks on its own. The second adds the package's functionality and is blocked by the first.
|
|
19
|
+
|
|
20
|
+
A ticket covers work in one repository. When a change needs work in two or more repositories, give each repository its own ticket, even when one repository's share is small, and record the merge order, upstream first, as blocked-by relations. The repository boundary does not need a judgment: A pull request lives in one repository, so a ticket that spans two cannot close on a single merge. When the change migrates many repositories to a new version or convention, consult {rulebook:cross-repo-migration-conventions} for the umbrella and its children.
|
|
21
|
+
|
|
16
22
|
This governs work already judged to need more than one pull request. Whether work discovered mid-change becomes a ticket at all is decided first by the fold-in default in [scope-and-deferral.md](../../skills/_data/scope-and-deferral.md).
|
|
17
23
|
|
|
18
24
|
Record the relationships natively when the tracker supports them -- blockers, and parent to child -- rather than as prose in a body. Record a blocker when there is some probability that one ticket affects another and should be merged first, not only when that is certain: A ticket whose design takes another ticket's outcome as an input is blocked by it.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: williamthorsen-visual-design-preferences
|
|
3
|
+
description: 'Visual taste for pages and interfaces: a quiet colour scheme over a monochrome one. Consult before choosing a colour scheme or styling a page, a prototype, or a UI component.'
|
|
4
|
+
delivery: [skill]
|
|
5
|
+
version: '1'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# William Thorsen's visual-design preferences
|
|
9
|
+
|
|
10
|
+
Taste that applies on top of {rulebook:visual-design-conventions}, which states the principles that hold whatever the taste. A preference here never relaxes one of those principles.
|
|
11
|
+
|
|
12
|
+
## Colour scheme
|
|
13
|
+
|
|
14
|
+
Prefer a quiet colour scheme to a monochrome one: muted hues on neutral surfaces, each hue encoding a kind or a state. A monochrome scheme leaves weight and style to do all the encoding, which the colour-as-encoding rule of {rulebook:visual-design-conventions} rules out, and a loud scheme spends the reader's attention on decoration.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: williamthorsen-workflow-preferences
|
|
3
3
|
description: William Thorsen's personal preferences for how work moves -- scope, branches and worktrees, guidance capture, and the arc of product development.
|
|
4
4
|
delivery: ambient
|
|
5
|
-
version: '
|
|
5
|
+
version: '14'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's workflow preferences
|
|
@@ -19,13 +19,15 @@ version: '13'
|
|
|
19
19
|
|
|
20
20
|
Never create a branch or worktree without explicit authorization. Each ticket is implemented in its own worktree, and the developer's tooling relies on that: Do all of one ticket's work in that worktree, never switch a worktree to another branch, and start a new session in another ticket's own worktree for work on that ticket. Which branch or worktree a ticket's work uses is settled, so never ask it.
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
A session works only in its own repository and in its own ticket's worktree. For any other repository or ticket, filing the ticket is the limit of the session's work: Do not create a branch or a worktree there, commit, push, or open a pull request. Reading another repository is not restricted. A request from the developer for that work in this session governs, but a request to file a ticket does not ask for the ticket's work.
|
|
23
|
+
|
|
24
|
+
When a session works in its own ticket's worktree and that worktree is not its cwd, pass that worktree to every skill that takes a working directory, such as `create-commit`, or commit inline with `git -C`: A skill with `context: fork` starts in the session's cwd, and the skill listing does not show which skills fork.
|
|
23
25
|
|
|
24
26
|
After a merge, say nothing about worktree or branch state and never offer to manage it. The worktree stays as long as its branch does, so there is nothing to clean up and nothing to ask about.
|
|
25
27
|
|
|
26
28
|
## Cross-repo sequencing
|
|
27
29
|
|
|
28
|
-
When the work would be better done upstream, in a package or repository on which this one depends, default to upstream first:
|
|
30
|
+
When the work would be better done upstream, in a package or repository on which this one depends, default to upstream first: File the upstream ticket and record it as a blocker of this one, and make the downstream change once the upstream change is merged and published and the dependency is upgraded here. The upstream change belongs to the upstream ticket's own session. Propose that order rather than merging a downstream workaround ahead of it.
|
|
29
31
|
|
|
30
32
|
Downstream first reads as faster because something is merged sooner, but it requires two downstream changes rather than one: the workaround, then its removal once the upstream change is merged. It also forces upstream to decide without the downstream requirement in hand, so upstream cannot weigh that requirement against its own constraints, and may settle on a shape that the consumer keeps working around.
|
|
31
33
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: williamthorsen-writing-preferences
|
|
3
3
|
description: William Thorsen's personal writing preferences for agent-authored prose.
|
|
4
4
|
delivery: [ambient, hook]
|
|
5
|
-
version: '
|
|
5
|
+
version: '14'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's writing preferences
|
|
@@ -34,7 +34,7 @@ Don't use em-dashes; use appropriate punctuation instead. A dash separating an i
|
|
|
34
34
|
|
|
35
35
|
<!-- rule: reduced-object-relative 1 -->
|
|
36
36
|
|
|
37
|
-
A relative clause with an object gap takes an overt relativizer: "the source that it names", never "the source it names". The test is mechanical: Between the head noun and the embedded subject, look for `that` or `which`.
|
|
37
|
+
A relative clause with an object gap takes an overt relativizer: "the source that it names", never "the source it names". The test is mechanical: Between the head noun and the embedded subject, look for `that` or `which`. For a gap after a copula, a coordinated gap, or the anaphoric one-series as head, see [rare cases](../../skills/_data/reduced-object-relatives.md).
|
|
38
38
|
|
|
39
39
|
**Repairs, in preference order.** Choose per site; restored relativizers stacked across a passage read as a tic of their own.
|
|
40
40
|
|
|
@@ -44,20 +44,9 @@ A relative clause with an object gap takes an overt relativizer: "the source tha
|
|
|
44
44
|
|
|
45
45
|
**A gap in a prepositional phrase takes its own order.** Pied-pipe the preposition first: "the level against which it is probed", preferred over the stranded "the level that it is probed against". If pied-piping reads stiffly, the stranded relativizer is the second choice and a recast the third. The passive participle is last here rather than first, since the actor is already inside the clause.
|
|
46
46
|
|
|
47
|
-
**
|
|
47
|
+
**The agentive `by`-phrase satisfies plain speech.** Plain speech rejects the _agentless_ passive that hides who acted. A `by`-phrase names the actor in the same phrase; therefore, "imported by every exported tier module" satisfies plain speech as fully as the active form does.
|
|
48
48
|
|
|
49
|
-
**
|
|
50
|
-
|
|
51
|
-
**The shapes, ranked from worst to mildest.** The rank follows the embedded subject's form, since the reader must keep that form in mind until the verb appears. Each is an exhibit of the construction, not a model to copy.
|
|
52
|
-
|
|
53
|
-
1. **Quantified noun phrase** (worst): "a dependency every exported tier module imports". The reader absorbs a quantifier and a full noun phrase before any verb discharges the head.
|
|
54
|
-
2. **Definite noun phrase**: "the ticket the branch name encodes".
|
|
55
|
-
3. **Bare noun**: "an idiom developers recognize".
|
|
56
|
-
4. **Pronoun** (mildest): "the source it names". Forbidden all the same; a pronoun shortens the wait rather than ending it.
|
|
57
|
-
|
|
58
|
-
**The agentive `by`-phrase satisfies plain speech.** Plain speech rejects the _agentless_ passive that hides who acted. A `by`-phrase names the actor in the same phrase; therefore, "imported by every exported tier module" satisfies plain speech as fully as the active form does. This rule breaks the habit of using a contact clause to avoid a passive that was never the target.
|
|
59
|
-
|
|
60
|
-
**Scope.** The rule governs a lexical head noun whose relative clause has a gap in an argument position: the direct object ("the source that it names"), the object of a preposition ("the level against which it is probed"), or the complement of a copula ("the throwing mock that it is"). The anaphoric one-series heads a relative clause under the rule too, though it is not a lexical noun, because a relativizer restores to it: "one that the spy carries". Two neighboring constructions fall outside the rule, each on a ground of its own: the fused head ("everything I know", "all you need"), which is its own relative pronoun and does not admit a relativizer, and the adjunct relative ("the reason it fails", "the way it works"), whose gap does not fill an argument position. The boundary keys on head type and gap role. Neither a short embedded subject nor a tight word budget exempts anything.
|
|
49
|
+
**Scope.** The rule governs a lexical head noun whose relative clause has a gap in an argument position: the direct object ("the source that it names"), the object of a preposition ("the level against which it is probed"), or the complement of a copula ("the throwing mock that it is"). Two neighboring constructions fall outside the rule, each on a ground of its own: the fused head ("everything I know", "all you need"), which is its own relative pronoun and does not admit a relativizer, and the adjunct relative ("the reason it fails", "the way it works"), whose gap does not fill an argument position. Neither a short embedded subject nor a tight word budget exempts anything.
|
|
61
50
|
|
|
62
51
|
## Second person
|
|
63
52
|
|
|
@@ -71,10 +60,7 @@ Imperative mood is untouched, because it does not contain a pronoun: "Run the fo
|
|
|
71
60
|
|
|
72
61
|
**The replacement names an actor.** Say who or what acts: "the config sets a cap on the rule" rather than "you cap the rule". If an actor does not belong in the sentence, recast so that the artifact is the subject of a verb that it performs or one that states a relation, as plain speech requires: "the flag takes a path" rather than "you pass it a path".
|
|
73
62
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
- **The agentless passive.** Dropping the pronoun by hiding who acted trades one defect for another: "your rules are capped" becomes "the rules are capped", which names nobody. Plain speech rejects that passive; name the actor instead.
|
|
77
|
-
- **The surviving object gap.** "the cap you set" and "the cap the config sets" are the same reduced object relative; therefore, the substitution leaves the second defect in place. Restore the relativizer, or apply the repairs in "Reduced object relatives" above.
|
|
63
|
+
Dropping the pronoun by hiding who acted trades one defect for another: "your rules are capped" becomes "the rules are capped", which names nobody. Plain speech rejects that passive; name the actor instead.
|
|
78
64
|
|
|
79
65
|
## Sentence case
|
|
80
66
|
|
|
@@ -83,7 +69,6 @@ A naive substitution fails in two ways:
|
|
|
83
69
|
Use sentence case for titles, headings, section headers, steps, labels, and interface elements. Never use title case. Preserve the case of proper nouns, named entities, and the actual titles of books and movies.
|
|
84
70
|
|
|
85
71
|
- "Backend: Express API routes and server" not "Backend: Express API Routes And Server"
|
|
86
|
-
- "Frontend: Static Excalibur scene" not "Frontend: Static Excalibur Scene"
|
|
87
72
|
- "Customizing the Status Adapter for a new backend", not "Customizing the Status Adapter for a New Backend"
|
|
88
73
|
|
|
89
74
|
## `so` and other connectives
|
|
@@ -57,10 +57,9 @@ Two artifacts are never edited once written, because a rewrite of either destroy
|
|
|
57
57
|
|
|
58
58
|
That restraint on editing a record applies to the remote ticket as well, from the point its work is handed to implementation. Design comes before that point: `design-and-plan` refines a raw ticket, and it may rewrite any section or the whole ticket.
|
|
59
59
|
|
|
60
|
-
From that point on, the ticket's `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when the work began, so they are never revised toward the outcome: A proposal does not become wrong because the implementer did something else, and revising it destroys the only record of what was foreseen. Report a divergence between one of those sections and the implementation in the pull-request description
|
|
61
|
-
|
|
62
|
-
Acceptance criteria are the one revisable part, because they alone are the contract that an implementation can falsify. Align them to the implementation only when the two conflict, or when the gap would mislead a reviewer. Small improvements are made as a matter of course, and the ticket is not rewritten to pretend they were foreseen.
|
|
60
|
+
From that point on, the ticket's `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when the work began, so they are never revised toward the outcome: A proposal does not become wrong because the implementer did something else, and revising it destroys the only record of what was foreseen. Report a divergence between one of those sections and the implementation in the pull-request description's `## Notes for reviewers` only when it changes what a reviewer checks, per the reader test that `summarize-change` states, and state it as the current fact rather than as a departure from the ticket.
|
|
63
61
|
|
|
62
|
+
Acceptance criteria are the one revisable part, because they alone are the contract that an implementation can falsify. Align them to the implementation only when the two conflict, or when the gap would mislead a reviewer.
|
|
64
63
|
A write that this section rules out is not a skipped step, because nobody asked for it, and it does not produce any user-facing text: Do not mention the doctrine or the marker, do not report the write that was not made, and do not offer to reconcile the record with current state. When the user asks for such a write, decline it in one line and name the alternative: for a revision that you publish, a new record; for a divergence from the ticket, the pull-request description; for a lede that the records do not contain, `capture-lede-decision`'s `--agent-lede-file` and `--merged-lede-file`. A human's later edit to a published body does not need a record, because the `merge` record captures what merged.
|
|
65
64
|
|
|
66
65
|
## Documentation placement
|
|
@@ -75,4 +74,4 @@ Agents write most of what appears under the developer's account, so a creator, r
|
|
|
75
74
|
|
|
76
75
|
## Commits
|
|
77
76
|
|
|
78
|
-
Invoke the `create-commit` skill to make a commit.
|
|
77
|
+
Invoke the `create-commit` skill to make a commit. A title rendered from the configured template is correct: Never propose changing it to match other commits, and do not comment on whether it contains a ticket reference.
|
|
@@ -33,7 +33,7 @@ Prose mentions of script names that are not invocations (e.g., ``"the `describe-
|
|
|
33
33
|
- `check-prose.mjs`: Runs every `revise-prose` detector over one Markdown file at any path, without reading or writing the sweep record, and prints one line per candidate, or one JSON document `{ file, rules, candidates }` under `--json`. It exits 0 without candidates, 1 with candidates, and 2 on a usage error or an unreadable file. Invoke it as `node {harness_home_dir}/scripts/check-prose.mjs --file <path> [--json]`; `summarize-change` runs it over a change summary's prose.
|
|
34
34
|
- `describe-change.mjs`: Renders titles for commits, tickets, PRs, and merges from declarative templates, the `{breaking}` marker included, reads a rendered title back into its parts, consolidates a commit range's entries into a consolidated record, applies overrides to a record, renders the fenced `change-record` block that ends a pull-request body and the `## Details` body of a change summary, and resolves what a pull request merges as from that block and the pull request's commits. Invoke it as `node {harness_home_dir}/scripts/describe-change.mjs <subcommand>`, where [title-templates.md](../skills/_data/title-templates.md#invoking-the-bundle) names the subcommand for each; the bundle does not have a shebang.
|
|
35
35
|
- `get-ticket-id.sh`: Extracts a ticket ID from a branch name.
|
|
36
|
-
- `manage-jira-ticket.mjs`: Compares `acli`'s active site with a ticket's site and names the `acli jira auth switch` command on a mismatch (`check-site`), resolves the project key and issue type for a Jira work item from the repository's `.agents/preferences.yaml` (`resolve-target`), converts a Markdown body to ADF with task lists as native task items (`convert-body`),
|
|
36
|
+
- `manage-jira-ticket.mjs`: Compares `acli`'s active site with a ticket's site and names the `acli jira auth switch` command on a mismatch (`check-site`), resolves the project key and issue type for a Jira work item from the repository's `.agents/preferences.yaml`, taking `integrations.jira.umbrella_issue_type` for an umbrella under `--umbrella` and `integrations.jira.subtask_issue_type` for a child of a level-0 parent under `--parent-level` (`resolve-target`, and `create` likewise, from its parent's level), converts a Markdown body to ADF with task lists as native task items (`convert-body`), creates a work item through `acli` exactly once, checking its parent first (`create`), and closes a work item (`close`): It posts a Markdown body as a comment unless a comment already opens with the body's first line, then transitions the item to the repository's `integrations.jira.done_status` unless its status category is done. `create` and `close` refuse before any other `acli` call when `ticket.base_url` is set, in the repository's preferences or the global file, and `acli`'s active site is another site or cannot be read. Invoke it as `node {harness_home_dir}/scripts/manage-jira-ticket.mjs <subcommand>`.
|
|
37
37
|
- `resolve-review-run.mjs`: Finds a ticket's active review run (its newest `interactive` run directory), opens it for a new review by creating one when none exists, or finds the newest reviewer or overseer review in it. Invoke it as `node {harness_home_dir}/scripts/resolve-review-run.mjs active|open|latest`.
|
|
38
38
|
- `resolve-frontmatter.sh`: Emits canonical artifact frontmatter (YAML or JSON) with provenance, ticket, branch, commit, and PR fields, plus scalar and list extension keys.
|
|
39
39
|
- `select-lede-exemplars.mjs`: Selects author-approved ledes of a given work type from the lede-decision corpus, optionally floored at a quality rating. `--breaking` marks the request as one for a breaking change, as a `!` on `--type` does: An unmarked request never selects a breaking record, and a marked one prefers breaking records within each widening step. `--with-pair` reports each record's agent lede, merged lede, and author comment alongside the approved text.
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
import { createRequire as __cjsCreateRequire } from 'node:module';
|
|
2
2
|
const require = __cjsCreateRequire(import.meta.url);
|
|
3
|
-
var R=Object.defineProperty;var t=(n,e)=>R(n,"name",{value:e,configurable:!0});import g from"node:process";function b(n){return n instanceof Error||Object.prototype.toString.call(n)==="[object Error]"}t(b,"isError");function
|
|
4
|
-
`),!0}}t(w,"isEntryPoint");function E(n,e){let r=[],o=[];for(let
|
|
5
|
-
`).map(a=>V(a));if(r.length===0)return c.map(a=>({...a,touchesWork:null}));let u=r.map(a=>`:(top,literal)${a}`),
|
|
6
|
-
`));return c.map(a=>({...a,touchesWork:
|
|
7
|
-
`)}catch(n){g.stderr.write(`check-branch-currency: ${
|
|
3
|
+
var R=Object.defineProperty;var t=(n,e)=>R(n,"name",{value:e,configurable:!0});import g from"node:process";function b(n){return n instanceof Error||Object.prototype.toString.call(n)==="[object Error]"}t(b,"isError");function l(n){try{return b(n)&&typeof n.message=="string"&&n.message!==""?n.message:String(n)}catch{return"[unstringifiable value]"}}t(l,"describeError");import{realpathSync as y}from"node:fs";import x from"node:process";import{fileURLToPath as O}from"node:url";function w(n,e){let r=x.argv[1];if(r===void 0)return!1;try{return y(O(n))===y(r)}catch(o){return x.stderr.write(`${e}: warning: could not determine entry point: ${l(o)}
|
|
4
|
+
`),!0}}t(w,"isEntryPoint");function E(n,e){let r=[],o=[];for(let i=0;i<n.length;i+=1){let c=n[i];if(c===void 0)continue;if(!c.startsWith("--")){r.push(c);continue}let u=B(c,e);if(u===null)throw new Error(`unknown flag: ${c}`);let{spec:s,inlineValue:a}=u;if(!s.takesValue){if(a!==null)throw new Error(`--${s.name} does not take a value`);o.push({name:s.name,value:null});continue}if(a!==null){o.push({name:s.name,value:a});continue}let f=n[i+1]??null;if(f===null||f.startsWith("--"))throw new Error(`--${s.name} requires a value`);o.push({name:s.name,value:f}),i+=1}return{positionals:r,flags:o}}t(E,"scanFlags");function B(n,e){for(let r of e)for(let o of[r.name,...r.aliases??[]]){let i=`--${o}`;if(n===i)return{spec:r,inlineValue:null};if(n.startsWith(`${i}=`))return{spec:r,inlineValue:n.slice(i.length+1)}}return null}t(B,"matchFlag");import{execFileSync as N}from"node:child_process";import j from"node:process";function k(n){return M(n)&&!Array.isArray(n)}t(k,"isRecord");function M(n){return typeof n=="object"&&n!==null}t(M,"isObject");function $(n){let{base:e,cwd:r,paths:o}=n,{remote:i,branch:c}=h(e),u=A(r,i,c);if(!u.ok)return{fetched:!1,error:u.error};let s=p(r,`HEAD..${e}`),a=p(r,`${e}..HEAD`),f=m(r,["status","--porcelain"])==="",F=G(r,e),S=T(r,e,o);return{fetched:!0,base:e,behind:s,ahead:a,clean:f,pushed:F,gained:S}}t($,"checkBranchCurrency");function h(n){let e=n.indexOf("/"),r=n.slice(0,Math.max(0,e)),o=n.slice(e+1);if(e===-1||r===""||o==="")throw new Error(`--base must name a remote and a branch, such as origin/main: ${n}`);return{remote:r,branch:o}}t(h,"splitBase");var v="@{u}";function p(n,e){return Number.parseInt(m(n,["rev-list","--count",e]),10)}t(p,"countCommits");function C(n){let e=k(n)?n.stderr:void 0;return typeof e=="string"&&e.trim()!==""?e.trim():l(n)}t(C,"describeGitFailure");function A(n,e,r){try{return N("git",["-C",n,"fetch","--quiet",e,r],{encoding:"utf8",env:{...j.env,GIT_TERMINAL_PROMPT:"0"},stdio:["ignore","pipe","pipe"]}),{ok:!0}}catch(o){return{ok:!1,error:C(o)}}}t(A,"fetchBranch");function G(n,e){return P(n)?p(n,e+".."+v)>0:!1}t(G,"hasPushedOwnCommits");function P(n){try{return m(n,["rev-parse","--abbrev-ref","--symbolic-full-name",v]),!0}catch{return!1}}t(P,"hasUpstream");function T(n,e,r){let o=`HEAD..${e}`,i=m(n,["log","--format=%H%x09%s",o]),c=i===""?[]:i.split(`
|
|
5
|
+
`).map(a=>V(a));if(r.length===0)return c.map(a=>({...a,touchesWork:null}));let u=r.map(a=>`:(top,literal)${a}`),s=new Set(m(n,["log","--format=%H",o,"--",...u]).split(`
|
|
6
|
+
`));return c.map(a=>({...a,touchesWork:s.has(a.sha)}))}t(T,"listGainedCommits");function V(n){let e=n.indexOf(" ");return{sha:n.slice(0,e),subject:n.slice(e+1)}}t(V,"parseLogLine");function m(n,e){try{return N("git",["-C",n,...e],{encoding:"utf8",stdio:["ignore","pipe","pipe"]}).trim()}catch(r){throw new Error(`git ${e.join(" ")} failed: ${C(r)}`,{cause:r})}}t(m,"readGit");var I=[{name:"base",takesValue:!0},{name:"path",takesValue:!0}],d="usage: check-branch-currency --base <remote>/<branch> [--path <path>]...";function W(){try{let n=H(g.argv.slice(2));g.stdout.write(`${JSON.stringify(n,null,2)}
|
|
7
|
+
`)}catch(n){g.stderr.write(`check-branch-currency: ${l(n)}
|
|
8
8
|
`),g.exit(1)}}t(W,"main");w(import.meta.url,"check-branch-currency")&&W();function H(n){let{flags:e,positionals:r}=E(n,I);if(r.length>0)throw new Error(`unexpected argument: ${r.join(" ")}
|
|
9
|
-
${d}`);let o=e.filter(
|
|
9
|
+
${d}`);let o=e.filter(s=>s.name==="base").map(s=>s.value??""),[i,...c]=o;if(i===void 0)throw new Error(`--base is required
|
|
10
10
|
${d}`);if(c.length>0)throw new Error(`--base may be given only once
|
|
11
|
-
${d}`);h(
|
|
11
|
+
${d}`);h(i);let u=e.filter(s=>s.name==="path").map(s=>s.value??"");return $({base:i,cwd:g.cwd(),paths:u})}t(H,"runCommand");
|