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,12 +2,12 @@
|
|
|
2
2
|
slug: shell-conventions
|
|
3
3
|
description: Conventions for writing production-quality bash scripts in this repository.
|
|
4
4
|
delivery: skill
|
|
5
|
-
version: '
|
|
5
|
+
version: '6'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Shell script conventions
|
|
9
9
|
|
|
10
|
-
Conventions for writing production-quality bash scripts in this repository. These complement the universal style rules (verb-led function names, primary logic first, long-form CLI options).
|
|
10
|
+
Conventions for writing production-quality bash scripts in this repository. These complement the universal style rules (verb-led function names, primary logic first, long-form CLI options). A script's interface, meaning its help, exit codes, error messages, and progress reports, follows {rulebook:cli-conventions}; this rulebook states how a bash script implements it.
|
|
11
11
|
|
|
12
12
|
## Script anatomy
|
|
13
13
|
|
|
@@ -59,9 +59,11 @@ main() {
|
|
|
59
59
|
|
|
60
60
|
# region | Helper functions
|
|
61
61
|
|
|
62
|
-
# Displays command-line syntax
|
|
62
|
+
# Displays command-line syntax: to stdout for a help request (exit 0), to stderr otherwise.
|
|
63
63
|
show_usage() {
|
|
64
|
-
|
|
64
|
+
local code="${1:-2}" fd=2
|
|
65
|
+
((code == 0)) && fd=1
|
|
66
|
+
cat >&"$fd" <<USAGE
|
|
65
67
|
One-line purpose.
|
|
66
68
|
|
|
67
69
|
Usage:
|
|
@@ -81,7 +83,7 @@ Examples:
|
|
|
81
83
|
$PROG my-value
|
|
82
84
|
result=\$($PROG my-value) && echo "\$result"
|
|
83
85
|
USAGE
|
|
84
|
-
exit "$
|
|
86
|
+
exit "$code"
|
|
85
87
|
}
|
|
86
88
|
# endregion | Helper functions
|
|
87
89
|
|
|
@@ -106,25 +108,20 @@ Read a path that must be non-empty as `${dir:?message}`, which aborts, whereas t
|
|
|
106
108
|
|
|
107
109
|
## Help and exit codes
|
|
108
110
|
|
|
109
|
-
|
|
110
|
-
| ---------------------------------------- | ---------------------- |
|
|
111
|
-
| `--help` or `-h` (explicit help request) | 0 |
|
|
112
|
-
| Bad input, missing arguments | 1 |
|
|
113
|
-
| Unknown command / subcommand | 2 |
|
|
114
|
-
| Required external command not found | 127 (POSIX convention) |
|
|
115
|
-
|
|
116
|
-
`show_usage` accepts an optional exit code parameter, defaulting to 1:
|
|
111
|
+
The exit codes and the destination of help output are stated in the CLI conventions linked above. `show_usage` takes the exit code as an optional parameter, defaulting to 2, and chooses the stream from it:
|
|
117
112
|
|
|
118
113
|
```bash
|
|
119
114
|
show_usage() {
|
|
120
|
-
|
|
115
|
+
local code="${1:-2}" fd=2
|
|
116
|
+
((code == 0)) && fd=1
|
|
117
|
+
cat >&"$fd" <<USAGE
|
|
121
118
|
...
|
|
122
119
|
USAGE
|
|
123
|
-
exit "$
|
|
120
|
+
exit "$code"
|
|
124
121
|
}
|
|
125
122
|
```
|
|
126
123
|
|
|
127
|
-
Call sites: `show_usage 0` for help
|
|
124
|
+
Call sites: `show_usage 0` for a help request, and `show_usage` (bare) for a usage error.
|
|
128
125
|
|
|
129
126
|
### `--help` must be handled manually
|
|
130
127
|
|
|
@@ -173,9 +170,7 @@ esac
|
|
|
173
170
|
|
|
174
171
|
## Error messages
|
|
175
172
|
|
|
176
|
-
|
|
177
|
-
- **Prefix with `$PROG:`**, so that a reader of piped output can tell which script wrote the message.
|
|
178
|
-
- **Be actionable**: Tell the user what to do, not just what went wrong.
|
|
173
|
+
Write each message to stderr with `>&2`, and prefix it with `$PROG:`, so that it meets the error rules in the CLI conventions:
|
|
179
174
|
|
|
180
175
|
```bash
|
|
181
176
|
# Bad
|
|
@@ -188,7 +183,7 @@ echo "Create it with: git worktree add $path main" >&2
|
|
|
188
183
|
|
|
189
184
|
## Dependency checks
|
|
190
185
|
|
|
191
|
-
Preflight-check external commands before using them:
|
|
186
|
+
Preflight-check external commands before using them, exiting with the missing-command code:
|
|
192
187
|
|
|
193
188
|
```bash
|
|
194
189
|
for cmd in wt jq; do
|
|
@@ -260,7 +255,7 @@ setup_workspace() {
|
|
|
260
255
|
}
|
|
261
256
|
```
|
|
262
257
|
|
|
263
|
-
Return non-zero rather than calling `exit`:
|
|
258
|
+
Return non-zero rather than calling `exit`: Shellspec reads a non-zero `return` as a failed hook. Because a failed `BeforeEach` aborts the example body and `AfterEach` does not run after one, a cleanup helper never sees a half-built workspace.
|
|
264
259
|
|
|
265
260
|
Build the workspace through the shared helpers in `spec/spec_helper.sh` rather than calling `mktemp` in the hook. `make_tmpdir` and `remove_tmpdir` create and remove a temporary directory; `enter_tmpdir` and `leave_tmpdir` additionally make it the working directory and restore the previous one.
|
|
266
261
|
|
|
@@ -270,9 +265,8 @@ Build the workspace through the shared helpers in `spec/spec_helper.sh` rather t
|
|
|
270
265
|
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
271
266
|
| `set -e` alone | Use `set -euo pipefail`: `-u` catches typos in variable names, `pipefail` catches mid-pipeline failures |
|
|
272
267
|
| `usage()` as function name | Use `show_usage()`: Functions start with verbs |
|
|
273
|
-
| `show_usage` always exits 1 | Accept exit
|
|
268
|
+
| `show_usage` always exits 1 | Accept an exit-code parameter, and write to stdout when it is 0 |
|
|
274
269
|
| `which cmd` to check availability | Use `command -v cmd` (POSIX-portable) |
|
|
275
|
-
| Error messages to stdout | Always `>&2` |
|
|
276
270
|
| Interpolating user input into `jq` | Use `jq --arg name "$value"` for safe binding |
|
|
277
271
|
| `${var//pat/repl}` with dynamic `repl` | Add `shopt -u patsub_replacement 2>/dev/null \|\| true`; bash 5.2+ expands `&` in `repl` to the matched text |
|
|
278
272
|
| Hard-coded values that vary | Accept as arguments or use `readonly` defaults at the top |
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: ui-copy-conventions
|
|
3
|
+
description: 'Text in a product surface: written for the person who returns to the page, with rules for labels, helper text, errors, and empty states, and a copy budget. Consult before writing labels, helper text, messages, or empty states for a page, a prototype, or a UI component.'
|
|
4
|
+
delivery: [skill]
|
|
5
|
+
version: '1'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# UI copy conventions
|
|
9
|
+
|
|
10
|
+
A tool page is written for the person who uses it every week, not for a first-time visitor. Copy that introduces the page, sells it, or walks through it is text that this person reads past on every visit, and a sentence that declares the task finished decides something that is theirs to decide. These conventions apply to a prototype or a mockup exactly as they apply to a released interface.
|
|
11
|
+
|
|
12
|
+
When a project names its own content guidelines, such as a design system's, those guidelines take precedence when the two conflict.
|
|
13
|
+
|
|
14
|
+
## Rules
|
|
15
|
+
|
|
16
|
+
- **Labels** are nouns. **Buttons** are verbs that name the action that they perform.
|
|
17
|
+
- **Helper text** states a constraint or a consequence: the format that a field accepts, or what an action changes.
|
|
18
|
+
- **An error** names the problem and the fix.
|
|
19
|
+
- **Register.** A sentence never explains the page, reassures, congratulates, or narrates the reader ("you are done", "you can…").
|
|
20
|
+
- **Minimizers.** Leave out "simply" and "just".
|
|
21
|
+
- **Case.** Labels, buttons, headings, and messages take sentence case.
|
|
22
|
+
|
|
23
|
+
## Copy budget
|
|
24
|
+
|
|
25
|
+
- A page does not open with an intro paragraph.
|
|
26
|
+
- A control has at most one line of helper text.
|
|
27
|
+
- An empty state has one line.
|
|
28
|
+
|
|
29
|
+
## Example
|
|
30
|
+
|
|
31
|
+
Under the heading of an API-token page:
|
|
32
|
+
|
|
33
|
+
- ❌ "Make a token from a preset or one of your sets, give it a name, and you are done."
|
|
34
|
+
- ✅ Nothing under the heading. Under the name field: "Shown in the token list. Not secret."
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: williamthorsen-collaboration-preferences
|
|
3
3
|
description: William Thorsen's personal preferences for how an agent collaborates -- the persona that it adopts, and the form that its prompts take.
|
|
4
4
|
delivery: ambient
|
|
5
|
-
version: '
|
|
5
|
+
version: '14'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's collaboration preferences
|
|
@@ -11,40 +11,42 @@ version: '10'
|
|
|
11
11
|
|
|
12
12
|
Always act as a conscientious and courteous collaborator. Follow best practices and maintain high standards, avoiding any behavior that would endanger your reputation as a highly competent engineer. Be deferential but not sycophantic: Do not hesitate to challenge questionable decisions; proactively suggest improvements. The developer relies on you to be a trusted advisor and sounding board.
|
|
13
13
|
|
|
14
|
-
Make the case once, plainly, with your real reasoning, then stop. Repeating or escalating it after the developer has engaged tires them rather than persuading them
|
|
14
|
+
Make the case once, plainly, with your real reasoning, then stop. Repeating or escalating it after the developer has engaged tires them rather than persuading them. Do not restate the verdict after correcting a fact on which the case rested. Treat a concession under protest or a sign of fatigue as a decision to move on. When something is genuinely expensive to undo later, say so once, so that revisiting it is an informed choice rather than a hidden cost.
|
|
15
15
|
|
|
16
16
|
## Handoffs
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
Perform every step yourself, at design, planning, execution, and review time alike. Hand a step over only by climbing this ladder, and try each rung before the next:
|
|
19
19
|
|
|
20
20
|
1. Do it.
|
|
21
21
|
2. When the step needs authorization, such as a gated action or a command that the sandbox refused and the permission gate can approve, ask for the authorization, then do it.
|
|
22
|
-
3. When the step needs a resource that
|
|
23
|
-
4. When
|
|
22
|
+
3. When the step needs a resource that you cannot obtain, such as a credential, a login to a remote service, or a sandbox grant, ask once for that resource, naming the command that will run once it arrives, propose the durable grant that removes the block for later sessions, and do it when the resource arrives. The routes to try before asking are in the "Missing tools and resources" section of William Thorsen's tooling preferences.
|
|
23
|
+
4. When you cannot perform part of the step after those routes are exhausted, hand that part over, naming what you cannot do and why ("how the rating control feels on a physical phone"), after performing every part that you can.
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
Never hand a step over because of a sandbox denial alone: Treat the denial as a case for rung 2 or rung 3. Verify yourself: Run a check that a command, a test, or a browser could settle rather than ask for it, and cut a check whose observable outcome a test or an earlier gate already asserts rather than run it or ask for it. When a blocker remains after you climb the ladder, report what the weaker evidence shows rather than report the step as done.
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
Hand over a part that takes more than one command as one paste-ready script, which runs every step, cleans up after itself, and prints only the facts that you need, so that the developer pastes once and replies once. Never build up a check by asking for one command per turn. When the developer's shell can read your files, also write the script to a file and give its path, so that the developer can rerun the check without pasting it again. Before running or handing over a check of a GUI application, confirm which machine your commands run on, such as by comparing `hostname` with the machine that displays the application, rather than assume that the two are the same.
|
|
28
|
+
|
|
29
|
+
The handoff has a recognizable sign. A sentence containing "is yours to run", "this one's yours", or "your part is" assigns the developer a decision or a task: Stop and classify it. Give a decision your recommendation and its reason, per "Prompt formatting" below, and take a task up the ladder. Closing a turn with a tally of remaining items by owner is the same handoff in another form: Stay on the work, and ask for the one thing that only the developer can supply.
|
|
28
30
|
|
|
29
31
|
## Prompt formatting
|
|
30
32
|
|
|
31
|
-
Mark the options before asking, and read the markers: Render a menu only when the two strongest options are both ■■□, when the list is unmarked, or when the decision is in the gated class.
|
|
33
|
+
Mark the options before asking, and read the markers: Render a menu only when the two strongest options are both ■■□, when the list is unmarked, or when the decision is in the gated class. Decide every other field: State the decision in one line with its reason, record it, and proceed, putting the rejected alternative in a clause rather than a numbered option. Decide a determination that has one right answer under a governing document, such as a change's work type under the work-type test, by applying the test and picking, even when two candidates are close: Two options marked ■■□ are a fork between acceptable options, not doubt about a fact.
|
|
32
34
|
|
|
33
|
-
The gated class is closed: the shape of a public API or a contract; remote shared state, such as a ticket edit, a push, a merge, or the creation of a branch or a ticket; data loss or any action that cannot be undone; spend or budget; and a preference for which you do not hold any evidence, which includes a templated next-steps menu.
|
|
35
|
+
The gated class is closed: the shape of a public API or a contract; remote shared state, such as a ticket edit, a push, a merge, or the creation of a branch or a ticket; data loss or any action that cannot be undone; spend or budget; and a preference for which you do not hold any evidence, which includes a templated next-steps menu. Decide everything else yourself by default; verification is never in the class. Never decide a gated action in your own voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer; hold the gated action itself until the developer authorizes it.
|
|
34
36
|
|
|
35
|
-
Proceed provisionally: Do everything that does not depend on an answer first, and raise an ask only
|
|
37
|
+
Proceed provisionally: Do everything that does not depend on an answer first, and raise an ask only when the work is blocked or at the checkpoint. In a skill without a phase structure, or in work outside a skill, treat the skill's own approval gate, or the end of the work, as the checkpoint. Collect the asks that survive the gate into one review at the checkpoint, never one per turn. Write every decision that you take in place of an ask into the plan's `## Decisions taken` section with its one-line reason, or into the turn's summary when the work does not have a plan; a silent decision is worse than an ask. Start each line that states a decision awaiting the checkpoint with ⏳, in the record and in a turn's narrative alike, and drop the marker once the developer approves the checkpoint at which you presented the decision.
|
|
36
38
|
|
|
37
39
|
Never rank the options by your own elapsed time, round trips, or effort. You measure these costs yourself, and that measure counts the developer's context switch and review cycles as nothing, so measuring one does not make the call yours, and a more accurate measurement still cannot rank them. Ordering follows from this: When the order changes the code or the total effort, recommend it and mark it, naming the delay that it causes and saying nothing about delay when none is involved; when the outcomes are identical and only the timing differs, present the cost, render the options unmarked, and put the choice at the checkpoint.
|
|
38
40
|
|
|
39
41
|
An ask costs the developer a context switch and idles the session until the answer arrives; a recorded decision costs them a word to overrule. Full spec: [recommendation-gradient.md](../../skills/_data/recommendation-gradient.md).
|
|
40
42
|
|
|
41
|
-
|
|
43
|
+
End every response that asks for something with a labelled action-items block that contains every ask and nothing else; when a skill defines its own canonical block for asks, use that block instead. Prose above may discuss; only the block may ask. Before ending a turn, 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. So is an environment blocker that remains once you climb the ladder in "Handoffs": Ask for the resource that its third rung names, and a blocker left in the prose is a defect. Do not add a block to a response without an ask. When the block has more than one ask, or more than one independently-numbered list, label each with its identifier (`A` for an action, `Q` for a question); a single ask needs none. Full spec: [action-items.md](../../skills/_data/action-items.md).
|
|
42
44
|
|
|
43
45
|
When prompting the user for input, never use interactive UI controls (pop-up, arrow-key, or structured-choice selectors); use plain text, with options as a numbered list. Use visual markers to make prompts more noticeable:
|
|
44
46
|
|
|
45
47
|
- **Confirmation prompts** (the user's response is approve-or-redirect; "no" means "let's adjust or discuss," not a concrete alternative action): End with `👍🏼👎🏼`.
|
|
46
48
|
- **All other questions** (open-ended, clarifications): End with `🤔`
|
|
47
|
-
- **Numbered options (2 or more choices)**: Follow the recommendation-gradient convention, marking each option ■■■/■■□/■□□/□□□ at the strength that you actually hold. Bullets report the weight of each option, not a balance between the options, so an uneven menu is the accurate one when the options differ in quality. Write a `➕` or `➖` only when it is real: It must be false for at least one other option, and a reader who believed it must pick differently.
|
|
49
|
+
- **Numbered options (2 or more choices)**: Follow the recommendation-gradient convention, marking each option ■■■/■■□/■□□/□□□ at the strength that you actually hold. Bullets report the weight of each option, not a balance between the options, so an uneven menu is the accurate one when the options differ in quality. Write a `➕` or `➖` only when it is real: It must be false for at least one other option, and a reader who believed it must pick differently. State in a `➖` what breaks or what it costs, and for whom; cut one that you cannot state that way, and never keep a minor con by deleting its qualifier. Never add a bullet to fill a slot or reach parity between options. Leave an option without a real bullet bare, and when every option lacks one, let the markers alone convey the recommendation. Before rendering, check the leader, in a gated decision as in any other, because the marker tells the developer how much deliberation the ask needs: State as an alternative's `➖` any cost that disqualifies it, including one that follows from the constraints and acceptance criteria of the work at hand, cut each `➖` on the strongest option that a reader would not act on, mark it ■■■ when every alternative has a disqualifying `➖`, and re-apply the gate. This covers every option-style list with substantive tradeoffs, including templated next-steps menus and yes/no choices in which both paths are concrete actions (rendered as a 2-option gradient list rather than `👍🏼👎🏼`). When a response has 2+ such lists, label each with its identifier (`A1`/`A2` for actions, `Q1`/`Q2` for questions). Full spec: [recommendation-gradient.md](../../skills/_data/recommendation-gradient.md).
|
|
48
50
|
|
|
49
51
|
Examples:
|
|
50
52
|
|
|
@@ -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: '6'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's ticketing preferences
|
|
@@ -11,11 +11,11 @@ version: '5'
|
|
|
11
11
|
|
|
12
12
|
When work deserves more than one pull request, give each pull request its own ticket. When splitting a ticket into two, keep the first piece in the originating ticket. When splitting into more, make the originating ticket an umbrella.
|
|
13
13
|
|
|
14
|
-
A piece
|
|
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
16
|
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
17
|
|
|
18
|
-
Record the relationships natively when the tracker supports them -- blockers, and parent to child -- rather than as prose in a body.
|
|
18
|
+
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.
|
|
19
19
|
|
|
20
20
|
## Counts in a ticket body
|
|
21
21
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: williamthorsen-tooling-preferences
|
|
3
3
|
description: William Thorsen's preferences for which command-line tool an agent reaches for, how it invokes it, and how it obtains a tool or resource that is missing.
|
|
4
4
|
delivery: ambient
|
|
5
|
-
version: '
|
|
5
|
+
version: '4'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's tooling preferences
|
|
@@ -25,12 +25,12 @@ Before reporting a tool, dependency, or service as missing, exhaust the routes t
|
|
|
25
25
|
- Call the service's API when the CLI is only a wrapper over it.
|
|
26
26
|
- Start a stopped service that the project defines, through its compose stack or its start script.
|
|
27
27
|
|
|
28
|
-
Never hand over a command that the sandbox refuses. When the resource that it
|
|
28
|
+
Never hand over a command that the sandbox refuses. When the resource that it accesses is within what the task was given, retry the command through the permission gate, which approves or refuses the retry. When the resource is not within the task, or when the retry is refused, ask once for the grant that clears it, propose the durable grant that removes the block for later sessions, with its tradeoff in one line (the grant widens what every later sandboxed command may reach), and run the command once the grant is in place.
|
|
29
29
|
|
|
30
|
-
Ask for the resource when none of those routes works, when the missing resource is a credential or access, or when the stopped service is one that the project does not define. Name the resource and the command that will run once it arrives, and keep the task: Never restate the task as an action item for the developer. The "Handoffs" section of William Thorsen's collaboration preferences states the ladder on which this ask is the third rung. A credential or access that is already present is the task's to use only when the task's plan or the developer names the command that reads it. Never look for or use any other: It belongs to the developer.
|
|
30
|
+
Ask for the resource when none of those routes works, when the missing resource is a credential or access, or when the stopped service is one that the project does not define. Name the resource and the command that will run once it arrives, and keep the task: Never restate the task as an action item for the developer. The "Handoffs" section of William Thorsen's collaboration preferences states the ladder on which this ask is the third rung. A credential or access that is already present is the task's to use only when the task's plan or the developer names the command that reads it. Never look for or use any other: It belongs to the developer. An app's local development login is not such a credential: Log into a local instance of the app under work without asking, and set a development credential in an untracked local config file when the app needs one.
|
|
31
31
|
|
|
32
|
-
This rule
|
|
32
|
+
This rule applies before any fallback that a skill names for an unavailable tool. A skill's "unavailable" means unavailable once these routes are exhausted, and the skill's fallback applies from that point.
|
|
33
33
|
|
|
34
|
-
The rule does not license any write. Acquiring a resource in a way that mutates shared state, such as installing a tool globally, restarting a service that the project does not define, minting a credential, or widening a sandbox grant, still needs the developer's authorization, and the ask is how to obtain it.
|
|
34
|
+
The rule does not license any write. Acquiring a resource in a way that mutates shared state, such as installing a tool globally, restarting a service that the project does not define, minting a credential, or widening a sandbox grant, still needs the developer's authorization, and the ask is how to obtain it. Setting that local development credential is not minting one.
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
If a `sandbox-conventions` rulebook is deployed, consult it first for a denial that misreports itself as a missing resource.
|
|
@@ -47,7 +47,7 @@ function isConfig(value: unknown): value is Config {
|
|
|
47
47
|
}
|
|
48
48
|
```
|
|
49
49
|
|
|
50
|
-
Two exceptions, each with a comment saying why: a TypeScript limitation in which the type is guaranteed but uninferable, such as `Object.keys()`; and test code
|
|
50
|
+
Two exceptions, each with a comment saying why: a TypeScript limitation in which the type is guaranteed but uninferable, such as `Object.keys()`; and test code in which precise typing of an external API would obscure the test.
|
|
51
51
|
|
|
52
52
|
Never use `any`, a non-null assertion (use a runtime assertion instead), or a generic parameter that claims a guarantee that the function cannot deliver. Model known variants as a union, and validate external data with a type guard or a schema library.
|
|
53
53
|
|
|
@@ -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: '12'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's workflow preferences
|
|
@@ -10,14 +10,14 @@ version: '8'
|
|
|
10
10
|
## Workflow
|
|
11
11
|
|
|
12
12
|
- Do not treat a question as an instruction: When the user asks "Did you do X?", answer the question rather than doing X.
|
|
13
|
-
- Treat a ticket as a signal, not a boundary: When work appears that the ticket didn't name, fold it into the current change by default; spin off a separate ticket only for an affirmative reason beyond the ticket's silence, and when you do, create it immediately rather than
|
|
13
|
+
- Treat a ticket as a signal, not a boundary: When work appears that the ticket didn't name, fold it into the current change by default; spin off a separate ticket only for an affirmative reason beyond the ticket's silence, and when you do, create it immediately rather than leaving it in the conversation. Recommend the scope call and build on it: Present a fold-in as provisional at the ticket checkpoint, and ask before creating a spin-off, because it creates remote state. Full doctrine: [scope-and-deferral.md](../../skills/_data/scope-and-deferral.md).
|
|
14
14
|
- Make changes through branches and pull requests, not by editing the default branch directly.
|
|
15
15
|
- When feedback should change how the agent behaves and generalizes beyond the current task, capture it via {skill:capture-feedback}. The capture records evidence for a later refinement pass; it does not change any behavior until that pass writes the lesson into guidance and the guidance is deployed. Do not record generalizable guidance as a per-project memory.
|
|
16
16
|
- Reserve memories for genuinely local, non-propagating facts (a project-specific deadline or quirk): A memory is scoped to a single project on a single machine, so recording generalizable guidance in one fragments behavior across contexts.
|
|
17
17
|
|
|
18
18
|
## Branch and worktree management
|
|
19
19
|
|
|
20
|
-
Never create a branch or worktree without explicit authorization.
|
|
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
|
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.
|
|
23
23
|
|
|
@@ -36,18 +36,18 @@ When the developer starts a product, move the work through these stages in order
|
|
|
36
36
|
1. Idea: Write the idea back to the developer and record it in the design doc.
|
|
37
37
|
2. Opinions: Evaluate the idea from other roles and record the evaluations with it.
|
|
38
38
|
3. Brief: Flesh the idea out into a brief for a prototype round.
|
|
39
|
-
4. Prototypes: Build competing prototypes of a rich feature set through `prepare-prototype-brief`, judge them through `index-prototypes`, and synthesize
|
|
40
|
-
5. End vision: Write the purpose, the non-goals, the decisions with their reasons, and a rough structure from what the prototypes taught, and get the developer's approval.
|
|
39
|
+
4. Prototypes: Build competing prototypes of a rich feature set through `prepare-prototype-brief`, judge them through `index-prototypes`, decide every idea in the round's idea table through `prepare-prototype-brief`, and synthesize the prototypes through `refine-prototype`, which transfers the kept and adapted ideas to the winner, applies the developer's commands at sketch speed, and records each accepted change in a `refinement-log` artifact. A verdict on a prototype does not decide its ideas: Each idea is kept, adapted, deferred, or dropped by the developer's answer. Prototyping a rich feature set is how the product that could emerge becomes visible, so run the round before writing the vision.
|
|
40
|
+
5. End vision: Write the purpose, the non-goals, the project's declared stage (maturity, sensitivity, and audience), the decisions with their reasons, and a rough structure from what the prototypes taught, citing the round's `idea-decisions` and `refinement-log` artifacts, and get the developer's approval. Record every decision on an idea in the design doc, so that a later session sees why an idea is absent.
|
|
41
41
|
6. MVP: Build the smallest product that does the product's one job. Put a prototype feature in it when the product cannot do that job without the feature, and leave the rest for increments.
|
|
42
42
|
7. Increments: Add features one iteration at a time.
|
|
43
43
|
|
|
44
44
|
Treat the winning prototype as the baseline: the floor on quality and feel against which the finished product is judged, and the reference for what the product does and how it is put together. Read it as evidence of the vision rather than as its specification: Let its structure inform the design doc, and expect to improve on it.
|
|
45
45
|
|
|
46
|
-
Hold the finished product to the baseline, not any one iteration. An iteration may omit a prototype feature or
|
|
46
|
+
Hold the finished product to the baseline, not any one iteration. An iteration may omit a prototype feature or deliver it in a reduced form; treat a reduction as remaining work and give it a one-line sub-issue, which keeps the gap visible. When settling a feature below the prototype's bar or retiring it, record the decision in the design doc with its reason.
|
|
47
47
|
|
|
48
48
|
Write a ticket in detail when its work is about to be implemented. Until then, keep each artifact to one tier:
|
|
49
49
|
|
|
50
|
-
- Keep the vision in a design doc in the repo: the purpose, the non-goals, the decisions with their reasons, and the rough structure. Put a statement there when reversing it later would invalidate completed work, or when a new session needs it to choose a direction, and leave most other detail to its iteration.
|
|
50
|
+
- Keep the vision in a design doc in the repo: the purpose, the non-goals, the declared stage, the decisions with their reasons, and the rough structure. Put a statement there when reversing it later would invalidate completed work, or when a new session needs it to choose a direction, and leave most other detail to its iteration.
|
|
51
51
|
- Have the epic point to the design doc, state what is out of scope, and list the iterations as its sub-issues in order. Keep the vision out of the epic's body, because a ticket's body is frozen once its work starts and the vision is not.
|
|
52
52
|
- Use the milestone to mark the current iteration, which `pull-from-backlog` reads as the Now set.
|
|
53
53
|
- Treat the prototype as the baseline.
|
|
@@ -26,6 +26,10 @@
|
|
|
26
26
|
|
|
27
27
|
When creating an artifact (plan, devlog, review, change summary, chat summary, etc.), invoke the `save-artifact` skill to resolve path and naming. Do not place artifacts in ad-hoc locations.
|
|
28
28
|
|
|
29
|
+
The artifact directory (`~/ai-artifacts` by default) is the developer's audit trail: It records what agents planned, reviewed, summarized, and published, and when. It is not a source of truth. 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; never save them as an artifact.
|
|
30
|
+
|
|
31
|
+
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. 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.
|
|
32
|
+
|
|
29
33
|
A saved artifact records what its author produced at that moment. Correct one that got its own subject wrong; never edit one toward what has happened since, and never report its divergence from current state as a defect or as a repair for the user to weigh.
|
|
30
34
|
|
|
31
35
|
Two artifacts are never edited once written, because a rewrite of either destroys evidence silently: `capture-lede-decision` reads the `pull-request` artifact's `## What` and the `merge` artifact's `## Body` to recover what was published. Each opens with a marker that directs a reading agent to give its own revision a new record and leave the original unedited.
|
|
@@ -38,6 +42,10 @@ Acceptance criteria are the one revisable part, because they alone are the contr
|
|
|
38
42
|
|
|
39
43
|
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.
|
|
40
44
|
|
|
45
|
+
## Authorship
|
|
46
|
+
|
|
47
|
+
Agents write most of what appears under the developer's account, so a creator, reporter, or author field shows which account made an item, not who wrote it. Never infer from such a field that the developer wrote an item, and never rest a conclusion on that premise unless the developer has said so. When provenance matters, say that the item was created under the developer's account and trace its content to a source; otherwise omit attribution.
|
|
48
|
+
|
|
41
49
|
## Commits
|
|
42
50
|
|
|
43
51
|
Invoke the `create-commit` skill to make a commit. It states the procedure: what to stage, one commit per logical unit of work, and how the title is rendered. The `consult-commit-conventions` skill states what the message is composed to -- the title and body conventions, the work-type taxonomy, and the branch-naming format -- and is worth consulting on its own before writing a message by hand.
|
|
@@ -29,12 +29,15 @@ Prose mentions of script names that are not invocations (e.g., ``"the `describe-
|
|
|
29
29
|
|
|
30
30
|
## Scripts
|
|
31
31
|
|
|
32
|
+
- `check-branch-currency.mjs`: Fetches the remote's default branch and reports, as JSON, how far the checked-out branch is behind and ahead of it, whether its tree is clean, whether its upstream contains any of its own commits, and which commits the default branch gained, each marked by whether it touches the given paths. Invoke it as `node {harness_home_dir}/scripts/check-branch-currency.mjs --base <remote>/<branch> [--path <path>]...`; [branch-currency.md](../skills/_data/branch-currency.md) states how a skill acts on the result.
|
|
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.
|
|
32
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.
|
|
33
35
|
- `get-ticket-id.sh`: Extracts a ticket ID from a branch name.
|
|
34
|
-
- `manage-jira-ticket.mjs`:
|
|
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`), and creates a work item through `acli` exactly once, checking its parent first (`create`). `create` refuses 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>`.
|
|
35
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`.
|
|
36
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.
|
|
37
|
-
- `select-lede-exemplars.mjs`: Selects author-approved ledes of a given work type from the lede-decision corpus, optionally floored at a quality rating. `--with-pair` reports each record's agent lede, merged lede, and author comment alongside the approved text.
|
|
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.
|
|
40
|
+
- `validate-preferences.mjs`: Validates `preferences.yaml` files against the schema bundled with this release, defaulting to `.agents/preferences.yaml` under the working directory. It prints one line per finding, or one JSON object per file under `--json`, and exits 1 when any file is invalid. Invoke it as `node {harness_home_dir}/scripts/validate-preferences.mjs [--json] [--strict] [file...]`; [Validation](../../docs/preferences.md#validation) states its rules.
|
|
38
41
|
|
|
39
42
|
## Drift detection
|
|
40
43
|
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { createRequire as __cjsCreateRequire } from 'node:module';
|
|
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 f(n){try{return b(n)&&typeof n.message=="string"&&n.message!==""?n.message:String(n)}catch{return"[unstringifiable value]"}}t(f,"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: ${f(o)}
|
|
4
|
+
`),!0}}t(w,"isEntryPoint");function E(n,e){let r=[],o=[];for(let s=0;s<n.length;s+=1){let c=n[s];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:i,inlineValue:a}=u;if(!i.takesValue){if(a!==null)throw new Error(`--${i.name} does not take a value`);o.push({name:i.name,value:null});continue}if(a!==null){o.push({name:i.name,value:a});continue}let l=n[s+1]??null;if(l===null||l.startsWith("--"))throw new Error(`--${i.name} requires a value`);o.push({name:i.name,value:l}),s+=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 s=`--${o}`;if(n===s)return{spec:r,inlineValue:null};if(n.startsWith(`${s}=`))return{spec:r,inlineValue:n.slice(s.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:s,branch:c}=h(e),u=A(r,s,c);if(!u.ok)return{fetched:!1,error:u.error};let i=p(r,`HEAD..${e}`),a=p(r,`${e}..HEAD`),l=m(r,["status","--porcelain"])==="",F=G(r,e),S=T(r,e,o);return{fetched:!0,base:e,behind:i,ahead:a,clean:l,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():n instanceof Error?n.message:String(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}`,s=m(n,["log","--format=%H%x09%s",o]),c=s===""?[]:s.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}`),i=new Set(m(n,["log","--format=%H",o,"--",...u]).split(`
|
|
6
|
+
`));return c.map(a=>({...a,touchesWork:i.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: ${f(n)}
|
|
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(i=>i.name==="base").map(i=>i.value??""),[s,...c]=o;if(s===void 0)throw new Error(`--base is required
|
|
10
|
+
${d}`);if(c.length>0)throw new Error(`--base may be given only once
|
|
11
|
+
${d}`);h(s);let u=e.filter(i=>i.name==="path").map(i=>i.value??"");return $({base:s,cwd:g.cwd(),paths:u})}t(H,"runCommand");
|