vouchington-tooling 2.0.1 → 3.0.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/dist/host-lock/with-host-lock.test-helpers.d.mts +10 -0
- package/dist/host-lock/with-host-lock.test-helpers.mjs +27 -1
- package/dist/sql-ast/no-mistakes-peer.d.mts +29 -0
- package/package.json +3 -3
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
- package/skills/manifest.json +15 -202
- package/skills/organize-github-issues/SKILL.md +20 -3
- package/skills/pr-description/SKILL.md +9 -65
- package/skills/retrospective/SKILL.md +15 -0
- package/skills/retrospective-distill/SKILL.md +1 -1
- package/skills/retrospective-distill/references/issue-body.md +6 -1
- package/skills/review-github-issue-taxonomy/SKILL.md +3 -4
- package/skills/triage-loop/SKILL.md +115 -30
- package/skills/triage-prs/SKILL.md +26 -27
- package/skills/triage-prs/references/feedback.md +14 -2
- package/skills/triage-prs/references/rubric.md +4 -4
- package/skills/triage-sweep/SKILL.md +41 -27
- package/skills/agent-workflow/SKILL.md +0 -72
- package/skills/agent-workflow/references/evidence-sweep.md +0 -12
- package/skills/agent-workflow/references/four-refs.md +0 -74
- package/skills/agent-workflow/references/implementation-and-review.md +0 -4
- package/skills/agent-workflow/references/implementation.md +0 -20
- package/skills/agent-workflow/references/review-response.md +0 -49
- package/skills/agent-workflow/references/review.md +0 -10
- package/skills/backend-vitest-test-authoring/SKILL.md +0 -22
- package/skills/backend-vitest-test-authoring/references/integration-boundaries.md +0 -10
- package/skills/bounded-iteration/SKILL.md +0 -92
- package/skills/bounded-iteration/references/sweep-patterns.md +0 -719
- package/skills/dependabot/SKILL.md +0 -117
- package/skills/dotnet-test-authoring/SKILL.md +0 -24
- package/skills/git-commit-checklist/SKILL.md +0 -29
- package/skills/github-actions-authoring/SKILL.md +0 -63
- package/skills/github-actions-checklist/SKILL.md +0 -118
- package/skills/github-issue/SKILL.md +0 -121
- package/skills/glide-mq/SKILL.md +0 -52
- package/skills/glide-mq/references/lease-patterns.md +0 -44
- package/skills/nextjs-vitest-test-authoring/SKILL.md +0 -21
- package/skills/nextjs-vitest-test-authoring/references/framework-boundaries.md +0 -9
- package/skills/npm-publishing/SKILL.md +0 -72
- package/skills/package-json-checklist/SKILL.md +0 -31
- package/skills/planning/SKILL.md +0 -37
- package/skills/planning/references/impact-discovery.md +0 -11
- package/skills/playwright-authoring/SKILL.md +0 -23
- package/skills/playwright-authoring/references/browser-reliability.md +0 -9
- package/skills/postgres-node-performance-tuning/SKILL.md +0 -35
- package/skills/postgres-node-performance-tuning/references/performance-patterns.md +0 -175
- package/skills/postgres-node-performance-tuning/references/reading-plans.md +0 -111
- package/skills/postgres-partitioning-uuid-v7/SKILL.md +0 -35
- package/skills/postgres-partitioning-uuid-v7/references/partition-lifecycle.md +0 -53
- package/skills/postgres-schema-design/SKILL.md +0 -31
- package/skills/postgres-schema-design/references/naming.md +0 -34
- package/skills/postgres-schema-design/references/relations.md +0 -66
- package/skills/postgres-schema-design/references/table-shapes.md +0 -78
- package/skills/pr-description/references/examples.md +0 -189
- package/skills/review-ci-logs/SKILL.md +0 -44
- package/skills/revisit-followups/SKILL.md +0 -47
- package/skills/stacked-prs/SKILL.md +0 -98
- package/skills/stacked-prs/references/drain.md +0 -177
- package/skills/stacked-prs/references/gh-stack.md +0 -147
- package/skills/static-analysis-checklist/SKILL.md +0 -32
- package/skills/storybook-authoring/SKILL.md +0 -22
- package/skills/storybook-authoring/references/component-coverage.md +0 -9
- package/skills/swift-test-authoring/SKILL.md +0 -23
- package/skills/swift-test-authoring/references/network-test-doubles.md +0 -9
- package/skills/test-authoring/SKILL.md +0 -27
- package/skills/test-authoring/references/core-practice.md +0 -16
- package/skills/test-authoring/references/dependency-boundaries.md +0 -38
- package/skills/test-authoring/references/tautological-tests.md +0 -47
- package/skills/triage-loop/references/shepherd.md +0 -62
- package/skills/vitest-test-authoring/SKILL.md +0 -22
- package/skills/vitest-test-authoring/references/mock-boundaries.md +0 -9
|
@@ -1,117 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: dependabot
|
|
3
|
-
description: Configure Dependabot coverage, grouping, cooldowns, and trusted automation.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Dependabot policy
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/dependabot/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Read every applicable `AGENTS.md`, then the repository's dependency, CI, release,
|
|
13
|
-
and branch-protection docs. The consumer wrapper owns the accepted cooldown, package roots,
|
|
14
|
-
first-party publishers, manual-update exceptions, runner policy, required checks, and secret source.
|
|
15
|
-
|
|
16
|
-
## Cover the dependency graph
|
|
17
|
-
|
|
18
|
-
- Inventory tracked manifests, lockfiles, Dockerfiles, workflow actions, infrastructure roots, and
|
|
19
|
-
any companion dependency bot. Add one Dependabot update entry per supported ecosystem and
|
|
20
|
-
manifest root. Do not create a second owner for a dependency already assigned elsewhere.
|
|
21
|
-
- Schedule version checks daily. Set `cooldown.default-days` to the consumer's release delay, or
|
|
22
|
-
seven days when local policy does not choose another value. Cooldown applies to version updates,
|
|
23
|
-
not security updates.
|
|
24
|
-
- Set `open-pull-requests-limit: 5` on every update entry. The limit is per entry and covers
|
|
25
|
-
version updates only. Use a lower value only when a serialized repair or manual validation path
|
|
26
|
-
requires it.
|
|
27
|
-
- Keep security updates enabled and immediate. Do not add an age gate that delays vulnerability
|
|
28
|
-
fixes.
|
|
29
|
-
|
|
30
|
-
## Group package families
|
|
31
|
-
|
|
32
|
-
Group packages that share one compatibility family or release train. Do not group by version type.
|
|
33
|
-
Use manifests, peer dependencies, lockfiles, and upstream release practice to decide what moves
|
|
34
|
-
together.
|
|
35
|
-
|
|
36
|
-
```yaml
|
|
37
|
-
cooldown:
|
|
38
|
-
default-days: 2
|
|
39
|
-
exclude: ['@acme/*', 'acme-cli']
|
|
40
|
-
groups:
|
|
41
|
-
first-party:
|
|
42
|
-
patterns: ['@acme/*', 'acme-cli']
|
|
43
|
-
oxc:
|
|
44
|
-
patterns: ['oxlint', 'oxfmt', 'oxlint-tsgolint']
|
|
45
|
-
vitest:
|
|
46
|
-
patterns: ['vitest', '@vitest/*', '@vitejs/*']
|
|
47
|
-
react:
|
|
48
|
-
patterns: ['react', 'react-dom']
|
|
49
|
-
react-security:
|
|
50
|
-
applies-to: 'security-updates'
|
|
51
|
-
patterns: ['react', 'react-dom']
|
|
52
|
-
react-email:
|
|
53
|
-
patterns: ['react-email', '@react-email/*']
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
- Name each group for the package, toolchain, framework, or verified release family. Prefer a narrow
|
|
57
|
-
namespace or prefix wildcard such as `@vitest/*` when that wildcard is one family. Put more
|
|
58
|
-
specific families before broader ones.
|
|
59
|
-
- Do not add generic groups such as `other-minor-and-patch`, `minor-and-patch`,
|
|
60
|
-
`security-minor-and-patch`, or `security-updates`. Do not use `patterns: ['*']` to force every
|
|
61
|
-
update into a group. Narrow family wildcards are expected. Leave unrelated packages ungrouped.
|
|
62
|
-
- Omit `update-types` so a family receives major, minor, and patch updates. Major updates are never
|
|
63
|
-
auto-merged by the workflow. Leaving majors out of the group splits the release train.
|
|
64
|
-
- Groups default to `applies-to: version-updates`. When the same family is also safe to upgrade
|
|
65
|
-
together for security fixes, add a separate group such as `react-security` with the same patterns
|
|
66
|
-
and `applies-to: security-updates`. Do not combine unrelated vulnerability fixes into one group.
|
|
67
|
-
- Keep verified first-party packages in a `first-party` group. For a namespace the owner wholly
|
|
68
|
-
controls, use its scoped wildcard, such as `@acme/*`. List unscoped packages by exact name.
|
|
69
|
-
- Keep first-party patterns in `cooldown.exclude` so those updates have zero-day eligibility, while
|
|
70
|
-
third-party packages keep the release delay. A grouped pull request is auto-mergeable only when
|
|
71
|
-
every included update is eligible.
|
|
72
|
-
|
|
73
|
-
## Exempt verified first-party releases
|
|
74
|
-
|
|
75
|
-
- Use `cooldown.exclude` only for first-party packages whose owning repository and default-branch
|
|
76
|
-
release workflow have been verified.
|
|
77
|
-
- That workflow must publish the package with OIDC, `id-token: write`, and no long-lived registry
|
|
78
|
-
token.
|
|
79
|
-
- Use a namespace wildcard only when the owner controls the whole namespace and intends future
|
|
80
|
-
packages to inherit the exemption. Otherwise use exact package names.
|
|
81
|
-
- Keep the consumer-owned registry, documentation, cooldown exclusions, and `first-party` group in
|
|
82
|
-
sync.
|
|
83
|
-
|
|
84
|
-
## Preserve the trust boundary
|
|
85
|
-
|
|
86
|
-
- Use a trusted default-branch `pull_request_target` workflow only for metadata inspection and the
|
|
87
|
-
minimal auto-merge mutation.
|
|
88
|
-
- Revalidate the live pull request, Dependabot identity, default base, same-repository
|
|
89
|
-
`dependabot/` head, and immutable base and head SHAs.
|
|
90
|
-
- Do not check out or execute pull-request code in that privileged workflow. Pin external actions
|
|
91
|
-
per local policy.
|
|
92
|
-
- Auto-merge only a verified semver patch, or a stable minor whose old and new majors are both at
|
|
93
|
-
least 1. Majors, pre-1.0 minors, prereleases, downgrades, malformed or inconsistent metadata, and
|
|
94
|
-
consumer-declared manual ecosystems need a human. The workflow never merges majors; the triage
|
|
95
|
-
loop may merge them under its grant, as triage-sweep Phase A describes.
|
|
96
|
-
- Enable platform auto-merge. Do not auto-approve. Required checks and branch rules remain the gate.
|
|
97
|
-
- Store `DEPENDABOT_AUTOMERGE_TOKEN` as a Dependabot secret, not only as an Actions secret. Grant
|
|
98
|
-
only the Contents and Pull requests access needed to enable or disable auto-merge. Fail an
|
|
99
|
-
eligible mutation visibly when the token is missing or underprivileged.
|
|
100
|
-
- A Dependabot-triggered workflow cannot assume ordinary Actions secrets or trusted OIDC access.
|
|
101
|
-
Copy only the narrow credentials mandatory tests need into Dependabot secret scope.
|
|
102
|
-
- For cloud, deployment, production, or other privileged checks, keep credential-free validation
|
|
103
|
-
running and mark the trusted portion skipped or not applicable for Dependabot. A required fan-in
|
|
104
|
-
job must distinguish that intentional state from an unexpected missing credential.
|
|
105
|
-
|
|
106
|
-
## Validate and roll out
|
|
107
|
-
|
|
108
|
-
- Parse the YAML. Run the repository's workflow checker and policy tests.
|
|
109
|
-
- Inspect the diff for uncovered manifests, overlapping groups, broad exemptions, secret exposure,
|
|
110
|
-
and pull-request code crossing a privileged boundary.
|
|
111
|
-
- Verify repository settings for dependency security updates and auto-merge.
|
|
112
|
-
- After the configuration reaches the default branch, read Dependabot logs for every configured
|
|
113
|
-
root. Check a representative patch, minor, major, security update, manual update, and
|
|
114
|
-
missing-secret path.
|
|
115
|
-
|
|
116
|
-
Consumer wrapper owns: cooldown, package roots, first-party publishers, manual-update exceptions,
|
|
117
|
-
runner policy, required checks, and secret source.
|
|
@@ -1,24 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: dotnet-test-authoring
|
|
3
|
-
description: Author .NET unit, application, and integration tests.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# .NET test authoring
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/dotnet-test-authoring/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Apply [test-authoring](../test-authoring/SKILL.md).
|
|
13
|
-
|
|
14
|
-
- Place a test at the narrowest layer that proves the behavior.
|
|
15
|
-
- Batch native or external selection where the project requires it.
|
|
16
|
-
- Isolate process and filesystem state.
|
|
17
|
-
- Assert a serialized contract. Do not assert a private implementation detail.
|
|
18
|
-
- Keep a helper typed and reusable only when it removes repeated setup without hiding an
|
|
19
|
-
expectation.
|
|
20
|
-
- Keep portable library tests separate from rendered application tests.
|
|
21
|
-
- Batch compatible native targets in one selection pass so one shared build validates that source
|
|
22
|
-
set.
|
|
23
|
-
|
|
24
|
-
Consumer wrapper owns: solution layout, test frameworks, native dependencies, and coverage policy.
|
|
@@ -1,29 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: git-commit-checklist
|
|
3
|
-
description: Verify scope, checks, and local policy before committing.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Git commit checklist
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/git-commit-checklist/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Use before every commit. Read local `AGENTS.md`, contribution guidance, and hook
|
|
13
|
-
output first; they own commit format, required trailers, file-size limits, and validation commands.
|
|
14
|
-
|
|
15
|
-
1. Inspect `git status` and the complete diff. Stage only files that implement the accepted task.
|
|
16
|
-
2. Confirm new or changed source and test files meet local size, formatting, and generated-file
|
|
17
|
-
policy. Do not commit credentials, build outputs, editor state, or unrelated changes.
|
|
18
|
-
3. Run focused tests and required local checks. Record any permitted skipped check and why.
|
|
19
|
-
4. Use the repository's conventional subject and required body/trailers. If code was extracted,
|
|
20
|
-
record the required provenance in the commit body.
|
|
21
|
-
5. Re-read the staged diff and commit message before committing. Do not amend another author's
|
|
22
|
-
work or rewrite history unless local policy and explicit authorization allow it.
|
|
23
|
-
|
|
24
|
-
Local instructions or the consumer wrapper own: branch names, file-size budgets, commit
|
|
25
|
-
conventions, pull-request templates, and push commands.
|
|
26
|
-
|
|
27
|
-
When an authorized rebase push may race another writer, capture the remote tip before fetching and
|
|
28
|
-
push with an exact expected-tip lease. A lease against a freshly fetched tracking ref can overwrite
|
|
29
|
-
the concurrent change it was meant to protect.
|
|
@@ -1,63 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: github-actions-authoring
|
|
3
|
-
description: Design event-driven GitHub Actions without remote-state polling.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# GitHub Actions authoring
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/github-actions-authoring/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Never poll in CI. A workflow reacts to a state transition. Read
|
|
13
|
-
[github-actions-checklist](../github-actions-checklist/SKILL.md) first, then every applicable
|
|
14
|
-
`AGENTS.md`. Repository-local policy and the consumer wrapper own runner labels,
|
|
15
|
-
permissions, action pins, concurrency, secrets, and required-check names.
|
|
16
|
-
|
|
17
|
-
## Design the event graph
|
|
18
|
-
|
|
19
|
-
- Name the producer, the durable transition it emits, and the consumer that owns the next action.
|
|
20
|
-
- Use `needs` for jobs in one workflow. Use `workflow_call` when the caller must await a reusable
|
|
21
|
-
workflow. When a consumer must run after failure or skip, give it an explicit status condition and
|
|
22
|
-
read `needs.<job>.result`. The implicit success condition skips it otherwise.
|
|
23
|
-
- Use `workflow_run` when a completed workflow is the trusted event boundary. Validate the source
|
|
24
|
-
workflow, repository, branch or pull-request head, conclusion, and artifacts before acting.
|
|
25
|
-
- The `workflow_run` receiver must already exist on the default branch. GitHub chains at most three
|
|
26
|
-
`workflow_run` levels. Plan that rollout, and collapse a deeper chain into one DAG.
|
|
27
|
-
- Use `repository_dispatch` for a cross-repository transition or an authenticated external callback.
|
|
28
|
-
Authenticate the sender, pass immutable correlation data, validate it against the source, and make
|
|
29
|
-
duplicate delivery safe. The receiver must already exist on the default branch before senders are
|
|
30
|
-
enabled.
|
|
31
|
-
- Prefer a provider-native completion event, callback, queue, or state-machine transition for a
|
|
32
|
-
deployment or service.
|
|
33
|
-
- A scheduled reconciliation workflow may repair a missed event. It inspects one snapshot and exits.
|
|
34
|
-
It does not wait for convergence.
|
|
35
|
-
|
|
36
|
-
## Persistent workspaces
|
|
37
|
-
|
|
38
|
-
Apply the persistent-workspace rules in
|
|
39
|
-
[github-actions-checklist](../github-actions-checklist/SKILL.md).
|
|
40
|
-
|
|
41
|
-
## Reject polling designs
|
|
42
|
-
|
|
43
|
-
- Do not add a sleep-and-read loop, a repeated query of a run, check, deployment, lease, or
|
|
44
|
-
service, a CLI waiter, or a recursive redispatch whose purpose is to watch remote state change.
|
|
45
|
-
- A timeout caps cost. It does not make polling event-driven.
|
|
46
|
-
- If the producer cannot emit a usable event, add the bridge at the producer or provider boundary
|
|
47
|
-
and let that bridge dispatch the correlated completion event.
|
|
48
|
-
- Bounded retries are allowed only for the same failed operation, and only when the failure is
|
|
49
|
-
transient and the operation is idempotent.
|
|
50
|
-
- A local process readiness check is allowed when that process runs inside the job and cannot emit
|
|
51
|
-
a workflow event.
|
|
52
|
-
- Neither exception allows repeated observation of remote state.
|
|
53
|
-
|
|
54
|
-
## Validate the result
|
|
55
|
-
|
|
56
|
-
- Test accepted, rejected, duplicate, stale, and out-of-order events.
|
|
57
|
-
- Preserve required-check names. Prove that every terminal producer outcome causes one terminal
|
|
58
|
-
consumer outcome.
|
|
59
|
-
- Run the local workflow checker and affected tests. Inspect the event graph for credentials
|
|
60
|
-
crossing an untrusted boundary, a missing correlation field, and any remaining polling path.
|
|
61
|
-
|
|
62
|
-
Consumer wrapper owns: runner labels, permissions, action pins, concurrency, secrets, and
|
|
63
|
-
required-check names.
|
|
@@ -1,118 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: github-actions-checklist
|
|
3
|
-
description: Check Actions triggers, permissions, runners, pins, and deadlines.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# GitHub Actions checklist
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/github-actions-checklist/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Use before editing a workflow or composite action. Repository-local instructions own runners,
|
|
13
|
-
approved action pins, concurrency names, secrets, permissions, and workflow-only pull-request rules.
|
|
14
|
-
Apply this baseline unless a stricter local rule overrides it.
|
|
15
|
-
|
|
16
|
-
## Triggers and required checks
|
|
17
|
-
|
|
18
|
-
- Use `pull_request` for pull-request workflows in private repositories.
|
|
19
|
-
- Reserve `pull_request_target` for base-owned orchestration in a public repository, or for a
|
|
20
|
-
narrowly scoped Dependabot or Renovate workflow.
|
|
21
|
-
- A pull-request CI workflow must not subscribe to `ready_for_review` or `converted_to_draft`
|
|
22
|
-
unless a job changes what it does on that transition. Those activity types start another run for
|
|
23
|
-
the same head, and `cancel-in-progress: true` replaces checks that already passed. Dependabot
|
|
24
|
-
auto-merge may keep `ready_for_review`: it enables merge and does not rerun tests.
|
|
25
|
-
- A privileged workflow must not check out or execute untrusted pull-request content.
|
|
26
|
-
- When changing orchestration, load
|
|
27
|
-
[github-actions-authoring](../github-actions-authoring/SKILL.md). Do not poll remote workflow,
|
|
28
|
-
deployment, lease, service, or health state.
|
|
29
|
-
- Required checks must be actual workflow jobs that run or aggregate the work they report.
|
|
30
|
-
- Workflow code must not create or publish check runs or commit statuses to synthesize a required
|
|
31
|
-
context, copy another workflow's conclusion, or bypass the event graph.
|
|
32
|
-
- An external CI or analysis integration may report its own result. Do not relay GitHub Actions
|
|
33
|
-
work through its API.
|
|
34
|
-
|
|
35
|
-
## Tests, concurrency, and timeouts
|
|
36
|
-
|
|
37
|
-
- On `main`, or the consumer's configured default branch, split test jobs by domain, such as web
|
|
38
|
-
and backend. Keep required-check job names stable. Add a bounded fan-in job only when the merge
|
|
39
|
-
contract needs one combined result.
|
|
40
|
-
- Serialize test runs for the same pull request or default branch with one stable concurrency group.
|
|
41
|
-
- For pull requests, set `cancel-in-progress: true`. On `main`, or the consumer's configured default
|
|
42
|
-
branch, set `cancel-in-progress: false` so the active run finishes before the newest pending
|
|
43
|
-
revision starts. GitHub may replace an older pending main run with the newest pending revision;
|
|
44
|
-
preserving every intermediate queued revision is not required.
|
|
45
|
-
- When one workflow handles both events, make `cancel-in-progress` conditional on the pull-request
|
|
46
|
-
event. Keep the pull-request number or branch ref in the group.
|
|
47
|
-
- Give every concrete job `timeout-minutes` of at most 30 minutes. A top-level `jobs.<job_id>.uses`
|
|
48
|
-
caller cannot accept `timeout-minutes`; set it on every concrete job in the called workflow.
|
|
49
|
-
- If the operation cannot finish inside that bound, split it into event-driven phases. Lowering or
|
|
50
|
-
moving the timeout does not fix the design. Preserve a required job or check name with a bounded
|
|
51
|
-
fan-in job when the split would otherwise change the merge contract.
|
|
52
|
-
- Each underlying phase also has a deadline of no more than 30 minutes and supports cancellation,
|
|
53
|
-
rollback, or an explicit terminal retained or recovery state. A callback may report completion. It
|
|
54
|
-
must not hide a longer-running operation in another service.
|
|
55
|
-
- Keep each job's `timeout-minutes` below any hard platform limit of its runner so the job's own
|
|
56
|
-
cancellation fires first and `always()`/`cancelled()` cleanup steps still run. Example: no more
|
|
57
|
-
than 14 minutes on a runner with a 15-minute hard cap that `timeout-minutes` cannot raise.
|
|
58
|
-
- Give every long-running, network-bound, or waiting step its own `timeout-minutes` inside the job
|
|
59
|
-
budget. Bound every network call, such as `curl --connect-timeout … --max-time …`.
|
|
60
|
-
|
|
61
|
-
## Runners and persistent workspaces
|
|
62
|
-
|
|
63
|
-
- Prefer GitHub-hosted runners for public and private repositories. Choose the smallest hosted
|
|
64
|
-
runner the job fits, such as `ubuntu-slim` for a short job that needs no Docker daemon. Use a full
|
|
65
|
-
VM or native-architecture runner only for work the smaller runner cannot do. A consumer that still
|
|
66
|
-
requires self-hosted or disposable runners names its approved labels in repository-local policy.
|
|
67
|
-
- Ephemeral hosted runners start from a clean workspace. Do not add workspace-cleanup steps for
|
|
68
|
-
them, and check out with `persist-credentials: false` unless a later step must push with that
|
|
69
|
-
token.
|
|
70
|
-
- Moving a job from a self-hosted or other persistent runner to a GitHub-hosted one drops every
|
|
71
|
-
piece of runner-local state the job assumed was already there. Audit browser installs (a
|
|
72
|
-
Playwright, Cypress, or Puppeteer cache), package-manager stores (pnpm/npm, Go modules, a Rust
|
|
73
|
-
`target/` directory, Gradle), `apt-get install` steps that used to be a no-op because the package
|
|
74
|
-
was already present, and Docker image pulls that used to hit a warm local image store. A comment
|
|
75
|
-
that a tool "persists between runs so caching is not needed" describes the old runner and becomes
|
|
76
|
-
false the moment `runs-on` changes; replace that assumption with a keyed `actions/cache` step
|
|
77
|
-
instead. Re-derive `timeout-minutes` from a real passing run on the new runner rather than
|
|
78
|
-
carrying over a budget calibrated on a warm host.
|
|
79
|
-
- A persistent workspace checks out the full tree. Do not configure sparse checkout. Enforce that
|
|
80
|
-
with a YAML-aware check over intended tracked workflow and action files, with accepted and
|
|
81
|
-
rejected fixtures.
|
|
82
|
-
- Fix workspace ownership at the producer. A writable workspace bind mount uses a non-root identity
|
|
83
|
-
whose ownership and write access match the runner workspace.
|
|
84
|
-
- Do not add an unconditional pre-checkout workspace-wide permission or ownership traversal.
|
|
85
|
-
- Migrate a contaminated workspace once, while the runner is drained.
|
|
86
|
-
- Routine repair may cover bounded known generated paths. A workspace-wide fallback must be
|
|
87
|
-
failure-gated, same-filesystem, directory-only, and batched,
|
|
88
|
-
and must record path count and timing.
|
|
89
|
-
|
|
90
|
-
## Pinning
|
|
91
|
-
|
|
92
|
-
- Pin every repository-backed external `uses:` reference — anything other than a local `./...`
|
|
93
|
-
action or a `$/` self-repository reference — to a full lowercase 40-character Git SHA and its
|
|
94
|
-
immediate machine-maintainable version comment, such as `# v4.2.0`, so Dependabot can update both.
|
|
95
|
-
- A `$/` reference is the same repository at the running commit. It must not include an `@ref`.
|
|
96
|
-
- Pin `docker://...` actions to an immutable `@sha256:` image digest. Keep GitHub Actions dependency
|
|
97
|
-
updates enabled.
|
|
98
|
-
- Workflow tests and fixtures must not assert an action dependency's exact SHA or version. Assert
|
|
99
|
-
the action identity and Git SHA shape, or read the ref from the workflow under test.
|
|
100
|
-
- This does not prohibit asserting an exact source revision in `with.ref` when exact-head checkout
|
|
101
|
-
is a workflow security invariant.
|
|
102
|
-
|
|
103
|
-
## Edit
|
|
104
|
-
|
|
105
|
-
1. Read every applicable `AGENTS.md` from the repository root through the workflow,
|
|
106
|
-
plus CI docs and callers. On conflict, apply the closest instruction. Name trusted inputs,
|
|
107
|
-
untrusted inputs, and every credential boundary.
|
|
108
|
-
2. Give each job the least permissions it needs. Keep untrusted pull-request content out of shell
|
|
109
|
-
interpolation, privileged tokens, and write-capable steps.
|
|
110
|
-
3. Apply this baseline and any stricter consumer policy. Keep checkout refs, artifact boundaries,
|
|
111
|
-
caches, and concurrency explicit.
|
|
112
|
-
4. Validate changed YAML with the local workflow checker and run the affected tests or scripts.
|
|
113
|
-
Update local CI docs when behavior or operator expectations change.
|
|
114
|
-
5. Review the diff for privilege escalation, secret exposure, unsafe quoting, unsupported runner
|
|
115
|
-
assumptions, and unreachable paths.
|
|
116
|
-
|
|
117
|
-
Consumer wrapper owns: runner labels, action SHAs, workflow directories, concurrency scheme, and
|
|
118
|
-
release policy.
|
|
@@ -1,121 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: github-issue
|
|
3
|
-
description: Search, write, and classify GitHub issues within live authorization.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# GitHub issues
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/github-issue/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Use for durable follow-ups and pull-request linkage. Read local `AGENTS.md`, issue
|
|
13
|
-
templates, and repository-routing policy before any remote mutation.
|
|
14
|
-
|
|
15
|
-
## Mutation authority
|
|
16
|
-
|
|
17
|
-
- Caller authorization is required before any issue or taxonomy mutation. A credential does not
|
|
18
|
-
grant scope.
|
|
19
|
-
- Resolve the authenticated identity, current repository, and requested target. Do not assume an
|
|
20
|
-
owner prefix or visibility.
|
|
21
|
-
- Immediately before every write, refetch the exact target. Its canonical identity must still
|
|
22
|
-
match, and the repository must not be archived.
|
|
23
|
-
- Issue operations require issues to be enabled and `viewerPermission` of `TRIAGE`, `WRITE`,
|
|
24
|
-
`MAINTAIN`, or `ADMIN`. Issue creation additionally requires `viewerCanCreateIssues`.
|
|
25
|
-
- Applying existing metadata to a pull request uses that same permission set and does not require
|
|
26
|
-
issues to be enabled.
|
|
27
|
-
- Creating, changing, or deleting taxonomy definitions requires `WRITE`, `MAINTAIN`, or `ADMIN`
|
|
28
|
-
plus the operation-specific API capability. Creating, renaming, or closing a project requires
|
|
29
|
-
project-write.
|
|
30
|
-
- Insufficient permission or capability, missing or inaccessible data, an identity change, or a
|
|
31
|
-
mismatch is a hard deny. Approval cannot override it.
|
|
32
|
-
- Adding an item to an existing project uses the same permission set as applying existing metadata,
|
|
33
|
-
plus project-write. That add mutates project membership and needs no separate approval.
|
|
34
|
-
- Missing project scope or capability denies the project step only. Skip it, report the gap, and
|
|
35
|
-
do not work around it. The issue and its other metadata still proceed.
|
|
36
|
-
|
|
37
|
-
## Denied external target
|
|
38
|
-
|
|
39
|
-
- Do not write to a denied external creation target.
|
|
40
|
-
- Search for, then create or reuse, a tracking issue in the current repository or a
|
|
41
|
-
consumer-selected tracker. Immediately before that write, refetch the destination and apply the
|
|
42
|
-
issue-operation gate above.
|
|
43
|
-
- Include the intended upstream repository and a copy-ready report.
|
|
44
|
-
- Before naming that upstream repository, resolve it and compare the returned canonical name with
|
|
45
|
-
the name being written. A rename redirect resolves under the stale name, so existence is not
|
|
46
|
-
identity. This check is report accuracy, not the hard-deny mismatch above: write the canonical
|
|
47
|
-
name. When the name does not resolve, route the follow-up to the current repository and do not
|
|
48
|
-
name the unreachable target.
|
|
49
|
-
- Before copying details to a less-restricted destination, remove private repository identity,
|
|
50
|
-
paths, links, code, and findings. If redaction would make the report unusable, require explicit
|
|
51
|
-
destination approval or return the draft without mutation.
|
|
52
|
-
- Authorization to file the external issue includes this tracking fallback unless the caller opts
|
|
53
|
-
out. Report the reroute. If no tracker passes, return the draft without mutation.
|
|
54
|
-
- Do not fall back silently, and do not fall back to an unverified repository.
|
|
55
|
-
|
|
56
|
-
## Issue workflow
|
|
57
|
-
|
|
58
|
-
1. Search open issues and relevant closed issues in the destination. Return a likely duplicate
|
|
59
|
-
instead of filing one. Verify the paths and current behavior the issue names.
|
|
60
|
-
2. Before editing, commenting, relating, closing, or otherwise changing state, refetch the issue
|
|
61
|
-
and its discussion. Confirm the mutation is still authorized and supported. Close only when the
|
|
62
|
-
documented outcome and acceptance evidence show the work is resolved. Otherwise leave state
|
|
63
|
-
unchanged and report the gap.
|
|
64
|
-
3. Write a self-contained issue: problem, desired outcome, ownership boundaries, concrete areas,
|
|
65
|
-
validation, and external context. A discovered blocker does not widen implementation scope.
|
|
66
|
-
- Before absorbing a newly discovered blocker, require the calling workflow to reproduce it
|
|
67
|
-
against the refreshed default branch and provide the evidence, then search for an existing fix
|
|
68
|
-
or issue. If a fix resolves it, report it so the caller can use and retest it. Otherwise ask
|
|
69
|
-
whether to widen the accepted scope or only link or record a follow-up. Filing records work;
|
|
70
|
-
it does not amend the accepted plan or authorize implementation.
|
|
71
|
-
- A stop condition in an issue names a real decision for a human. Adding or changing an index,
|
|
72
|
-
or a rewrite that returns the same rows, is never one: the worker makes the change and records
|
|
73
|
-
the plan before and after.
|
|
74
|
-
- Verify every existing path in `## Files / areas` against `HEAD`. Mark a proposed path `New`
|
|
75
|
-
and verify its owning parent or module. Reject absolute and parent-traversal (`..`) paths. For
|
|
76
|
-
a target outside the current checkout, verify only redacted remote metadata through the
|
|
77
|
-
Contents API.
|
|
78
|
-
4. Fetch the complete live taxonomy, including open projects. Apply matching existing labels and a
|
|
79
|
-
selected existing milestone with no separate approval.
|
|
80
|
-
- Use an existing open project for strategic, initiative-level tracking, and a milestone for
|
|
81
|
-
repo-local release or sequencing. Choose by the initiative, not by how many repositories it
|
|
82
|
-
touches. A single-repo strategic initiative can have a project. An initiative can have both.
|
|
83
|
-
An issue belongs to at most one project, and not every issue needs one.
|
|
84
|
-
- Before adding a project item, check that item and any item the project's automation could
|
|
85
|
-
pull in with it, such as a parent issue's sub-issues. If any already belongs to a different
|
|
86
|
-
project, skip the add and report the conflict.
|
|
87
|
-
- Adding an item to an existing, described project needs no separate approval. Creating,
|
|
88
|
-
renaming, or closing a project is a separate taxonomy operation, as is creating a milestone.
|
|
89
|
-
- Missing project scope or permission skips the project step. Report the gap and do not work
|
|
90
|
-
around it.
|
|
91
|
-
- Do not set a project status that closes the issue unless closing is separately authorized.
|
|
92
|
-
GitHub's Auto-close issue workflow closes the issue when status becomes Done.
|
|
93
|
-
- When a plan issue's source already has a milestone, apply that same milestone. When the source
|
|
94
|
-
already has a project, refetch memberships and apply that project only when exactly one
|
|
95
|
-
accessible open membership exists. Otherwise skip the project and report the conflict.
|
|
96
|
-
- Omit a missing optional milestone. A missing required milestone blocks the issue. Omit a
|
|
97
|
-
declined optional label. A missing required label blocks the issue.
|
|
98
|
-
- For a missing label, use
|
|
99
|
-
[review-github-issue-taxonomy](../review-github-issue-taxonomy/SKILL.md) and get explicit
|
|
100
|
-
approval of the exact repository, name, description, and color before creating it.
|
|
101
|
-
5. Refetch the created or updated issue and verify metadata, including project membership. After a
|
|
102
|
-
project add, re-read the project: automation can pull in more items, including into a second
|
|
103
|
-
project. Report a partial failure without retrying creation. Preserve history and report the
|
|
104
|
-
action, URL, labels, milestone, and project.
|
|
105
|
-
6. Link a pull request with a closing reference only when it fully resolves the issue. Fully
|
|
106
|
-
qualify cross-repository references. Pull-request creation authority stays separate.
|
|
107
|
-
7. Use native sub-issues only for a real hierarchy, blocked-by only for a known dependency, and
|
|
108
|
-
prose links for related work. Read every created relationship back.
|
|
109
|
-
|
|
110
|
-
For a batch, preflight every entry before writing any issue. One invalid entry fails the whole
|
|
111
|
-
batch. A partial transport failure stops further creation and reports every issue already created.
|
|
112
|
-
Do not retry an entry that succeeded.
|
|
113
|
-
|
|
114
|
-
## Bounded output
|
|
115
|
-
|
|
116
|
-
- A search returns at most five `#N: title -- url` lines.
|
|
117
|
-
- A near-duplicate returns `Duplicate of #N: <url>`.
|
|
118
|
-
- A mutation returns the action, URL, labels, and verification, plus milestone and project when set.
|
|
119
|
-
|
|
120
|
-
Consumer wrapper owns: repository allowlist, taxonomy, issue template, credential, and CLI wrapper.
|
|
121
|
-
It may tighten this gate and may not weaken it.
|
package/skills/glide-mq/SKILL.md
DELETED
|
@@ -1,52 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: glide-mq
|
|
3
|
-
description: Design glide-mq queue jobs, ordering lanes, worker concurrency, and cross-job caps when writing or reviewing queue producers, workers, and dispatchers.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# glide-mq queues
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and the repository's local queue adapter when present.
|
|
9
|
-
Local policy overrides these portable conventions.
|
|
10
|
-
|
|
11
|
-
Names below are the glide-mq API: the job option `ordering: { key, concurrency }`, the worker
|
|
12
|
-
option `concurrency`, `lockDuration`, and `job.moveToDelayed(timestamp)`. Read
|
|
13
|
-
[lease patterns](references/lease-patterns.md) for the lease shape.
|
|
14
|
-
|
|
15
|
-
1. **Every shared-queue job sets `ordering`.** An ungrouped job in a shared queue competes for
|
|
16
|
-
every worker slot, so a flood of it starves other families. Give each job an
|
|
17
|
-
`ordering.key` prefixed with its domain name and an explicit `ordering.concurrency`.
|
|
18
|
-
2. **`ordering.concurrency` is a global cap; the worker `concurrency` is per process.** The key's
|
|
19
|
-
cap holds across all workers and processes. The worker option only bounds one process's
|
|
20
|
-
active jobs. Never size lane caps to sum to the worker option. Take caps from runtime
|
|
21
|
-
configuration, and give batched families a low cap.
|
|
22
|
-
3. **Group FIFO ignores `priority`.** Jobs sharing an ordering key run in enqueue order whatever
|
|
23
|
-
their priority. Work that must not wait behind a flood, and dispatchers that rely on
|
|
24
|
-
priority, get their own lane. Put work that outsiders can flood in a lane of its own.
|
|
25
|
-
Ordering keys are the orchestration layer; add none on top.
|
|
26
|
-
4. **`globalConcurrency` caps the whole queue.** The worker option `globalConcurrency` limits
|
|
27
|
-
every job on the queue together, so on a shared queue it throttles all families at once. Use
|
|
28
|
-
ordering lanes for per-family caps, and use `globalConcurrency` only when one resource bounds
|
|
29
|
-
the whole queue.
|
|
30
|
-
5. **A job moved to delayed keeps its ordering slot until it completes.** A deferred job still
|
|
31
|
-
counts against `ordering.concurrency`, so deferred jobs can fill a key and block ready work
|
|
32
|
-
on it. A cap that must survive deferral belongs in a token-owned lease, released before
|
|
33
|
-
`moveToDelayed`, not in the ordering key. Never fix starvation by raising the key's
|
|
34
|
-
concurrency: overlap grows and the same number of deferred jobs still fill the slots.
|
|
35
|
-
6. **Lease mechanics.** Acquire a token-owned lease with `SET key token NX PX ttl` before the
|
|
36
|
-
guarded work. Set the TTL at or above the job's `lockDuration`, renew it while the job runs,
|
|
37
|
-
and release it with compare-and-delete in `finally`. On contention, `moveToDelayed` only this
|
|
38
|
-
job by a short, bounded, jittered delay so it keeps its id, cursor, and dedup. Release the
|
|
39
|
-
lease before any `moveToDelayed` for quota deferral. Reuse the repository's lease helper
|
|
40
|
-
rather than adding a second. See [lease patterns](references/lease-patterns.md).
|
|
41
|
-
7. **Job count is not a KPI.** Many small jobs with a dispatcher and a sweep are fine. Do not
|
|
42
|
-
merge or remove jobs to cut the count. Judge a design by model calls or spend per item and by
|
|
43
|
-
how simply the jobs share a lifecycle.
|
|
44
|
-
|
|
45
|
-
Dispatchers, paged fan-out, and job-id deduplication follow
|
|
46
|
-
[bounded iteration](../bounded-iteration/SKILL.md). A lease for work that spans an external call
|
|
47
|
-
replaces holding a PostgreSQL transaction open across it, and PostgreSQL advisory locks are never
|
|
48
|
-
used; see
|
|
49
|
-
[performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
|
|
50
|
-
|
|
51
|
-
Consumer policy owns queue names, lane keys, caps and their configuration source, the lease helper,
|
|
52
|
-
and enforcement configuration.
|
|
@@ -1,44 +0,0 @@
|
|
|
1
|
-
# Lease patterns
|
|
2
|
-
|
|
3
|
-
A lease caps work across jobs and survives deferral, which an `ordering` slot does not: a job
|
|
4
|
-
moved to delayed keeps its slot until it completes.
|
|
5
|
-
|
|
6
|
-
## Acquire, renew, release
|
|
7
|
-
|
|
8
|
-
```ts
|
|
9
|
-
const token = randomUUID()
|
|
10
|
-
// SET leaseKey token NX PX ttlMs -> null when another job holds the lease
|
|
11
|
-
if (!(await setIfAbsent(leaseKey, token, ttlMs))) {
|
|
12
|
-
return job.moveToDelayed(Date.now() + jitteredDelayMs) // this job only; never falls through
|
|
13
|
-
}
|
|
14
|
-
try {
|
|
15
|
-
// renew while running, e.g. every ttlMs / 3, only while the stored value equals token
|
|
16
|
-
await doGuardedWork()
|
|
17
|
-
} finally {
|
|
18
|
-
await compareAndDelete(leaseKey, token) // script: delete only when the value equals token
|
|
19
|
-
}
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
- The TTL is at least the job's `lockDuration`. A shorter lease can expire while the job is
|
|
23
|
-
still active, and a second job then enters the guarded section.
|
|
24
|
-
- Renewal and release are scripts that compare the stored value with the token. A plain `DEL`
|
|
25
|
-
can remove a lease another job has since acquired.
|
|
26
|
-
- The delay on contention is short, bounded, and jittered so deferred jobs do not wake together.
|
|
27
|
-
`moveToDelayed` defers this job only and keeps its id, cursor, and dedup.
|
|
28
|
-
|
|
29
|
-
## Quota deferral
|
|
30
|
-
|
|
31
|
-
When the work defers itself for a quota or rate, release the lease first, then call
|
|
32
|
-
`moveToDelayed`. `moveToDelayed` never returns, so a release placed after it does not run, and a
|
|
33
|
-
deferred job that keeps the lease blocks the jobs the lease exists to admit.
|
|
34
|
-
|
|
35
|
-
```ts
|
|
36
|
-
await compareAndDelete(leaseKey, token)
|
|
37
|
-
await job.moveToDelayed(resumeAt)
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
## Why not the ordering key
|
|
41
|
-
|
|
42
|
-
Concurrency 1 on a key serializes ready work but lets deferred jobs hold the slot. Raising it to
|
|
43
|
-
2 lets two guarded sections overlap, and two deferred jobs still fill both slots. A lease
|
|
44
|
-
separates the cap on active work from the queue-order slot.
|
|
@@ -1,21 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: nextjs-vitest-test-authoring
|
|
3
|
-
description: Test Next.js components, routes, and server boundaries with Vitest.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Next.js Vitest test authoring
|
|
7
|
-
|
|
8
|
-
Read applicable `AGENTS.md` and their declared adapter alias, otherwise
|
|
9
|
-
`.agents/skills/nextjs-vitest-test-authoring/SKILL.md` from the repository root if present.
|
|
10
|
-
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
|
|
11
|
-
|
|
12
|
-
Apply [vitest-test-authoring](../vitest-test-authoring/SKILL.md) first.
|
|
13
|
-
|
|
14
|
-
- Mock framework navigation, headers, and server-only boundaries at the framework edge.
|
|
15
|
-
- Test component behavior through rendered output and user-visible state.
|
|
16
|
-
- Keep API-response fixtures representative. Do not test framework internals.
|
|
17
|
-
- Use a browser test for behavior the test runtime cannot represent.
|
|
18
|
-
- Read [framework boundaries](references/framework-boundaries.md) for module shape and server-only
|
|
19
|
-
cases.
|
|
20
|
-
|
|
21
|
-
Consumer wrapper owns: framework mock helpers, render libraries, and route fixture conventions.
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
# Framework boundaries
|
|
2
|
-
|
|
3
|
-
Mock framework navigation, headers, cookies, and server-only APIs at the framework edge, not inside
|
|
4
|
-
the component or route under test. Preserve typed module shape and use the consumer's shared mocks
|
|
5
|
-
when they exist. Build API responses with typed factories rather than inline partial objects.
|
|
6
|
-
|
|
7
|
-
Use direct rendering for component behavior. If request scope, hydration, browser APIs, or server
|
|
8
|
-
module resolution cannot be represented faithfully, move the assertion to an integration or browser
|
|
9
|
-
test instead of widening a unit-test mock.
|