vouchington-tooling 2.0.2 → 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.
Files changed (68) hide show
  1. package/package.json +2 -2
  2. package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
  3. package/skills/manifest.json +15 -202
  4. package/skills/organize-github-issues/SKILL.md +20 -3
  5. package/skills/pr-description/SKILL.md +9 -65
  6. package/skills/retrospective/SKILL.md +15 -0
  7. package/skills/retrospective-distill/SKILL.md +1 -1
  8. package/skills/retrospective-distill/references/issue-body.md +6 -1
  9. package/skills/review-github-issue-taxonomy/SKILL.md +3 -4
  10. package/skills/triage-loop/SKILL.md +107 -26
  11. package/skills/triage-prs/SKILL.md +25 -27
  12. package/skills/triage-prs/references/feedback.md +14 -2
  13. package/skills/triage-prs/references/rubric.md +4 -4
  14. package/skills/triage-sweep/SKILL.md +26 -23
  15. package/skills/agent-workflow/SKILL.md +0 -72
  16. package/skills/agent-workflow/references/evidence-sweep.md +0 -12
  17. package/skills/agent-workflow/references/four-refs.md +0 -74
  18. package/skills/agent-workflow/references/implementation-and-review.md +0 -4
  19. package/skills/agent-workflow/references/implementation.md +0 -20
  20. package/skills/agent-workflow/references/review-response.md +0 -49
  21. package/skills/agent-workflow/references/review.md +0 -10
  22. package/skills/backend-vitest-test-authoring/SKILL.md +0 -22
  23. package/skills/backend-vitest-test-authoring/references/integration-boundaries.md +0 -10
  24. package/skills/bounded-iteration/SKILL.md +0 -92
  25. package/skills/bounded-iteration/references/sweep-patterns.md +0 -719
  26. package/skills/dependabot/SKILL.md +0 -117
  27. package/skills/dotnet-test-authoring/SKILL.md +0 -24
  28. package/skills/git-commit-checklist/SKILL.md +0 -29
  29. package/skills/github-actions-authoring/SKILL.md +0 -63
  30. package/skills/github-actions-checklist/SKILL.md +0 -118
  31. package/skills/github-issue/SKILL.md +0 -121
  32. package/skills/glide-mq/SKILL.md +0 -52
  33. package/skills/glide-mq/references/lease-patterns.md +0 -44
  34. package/skills/nextjs-vitest-test-authoring/SKILL.md +0 -21
  35. package/skills/nextjs-vitest-test-authoring/references/framework-boundaries.md +0 -9
  36. package/skills/npm-publishing/SKILL.md +0 -72
  37. package/skills/package-json-checklist/SKILL.md +0 -31
  38. package/skills/planning/SKILL.md +0 -37
  39. package/skills/planning/references/impact-discovery.md +0 -11
  40. package/skills/playwright-authoring/SKILL.md +0 -23
  41. package/skills/playwright-authoring/references/browser-reliability.md +0 -9
  42. package/skills/postgres-node-performance-tuning/SKILL.md +0 -35
  43. package/skills/postgres-node-performance-tuning/references/performance-patterns.md +0 -175
  44. package/skills/postgres-node-performance-tuning/references/reading-plans.md +0 -111
  45. package/skills/postgres-partitioning-uuid-v7/SKILL.md +0 -35
  46. package/skills/postgres-partitioning-uuid-v7/references/partition-lifecycle.md +0 -53
  47. package/skills/postgres-schema-design/SKILL.md +0 -31
  48. package/skills/postgres-schema-design/references/naming.md +0 -34
  49. package/skills/postgres-schema-design/references/relations.md +0 -66
  50. package/skills/postgres-schema-design/references/table-shapes.md +0 -78
  51. package/skills/pr-description/references/examples.md +0 -189
  52. package/skills/review-ci-logs/SKILL.md +0 -44
  53. package/skills/revisit-followups/SKILL.md +0 -47
  54. package/skills/stacked-prs/SKILL.md +0 -98
  55. package/skills/stacked-prs/references/drain.md +0 -177
  56. package/skills/stacked-prs/references/gh-stack.md +0 -147
  57. package/skills/static-analysis-checklist/SKILL.md +0 -32
  58. package/skills/storybook-authoring/SKILL.md +0 -22
  59. package/skills/storybook-authoring/references/component-coverage.md +0 -9
  60. package/skills/swift-test-authoring/SKILL.md +0 -23
  61. package/skills/swift-test-authoring/references/network-test-doubles.md +0 -9
  62. package/skills/test-authoring/SKILL.md +0 -27
  63. package/skills/test-authoring/references/core-practice.md +0 -16
  64. package/skills/test-authoring/references/dependency-boundaries.md +0 -38
  65. package/skills/test-authoring/references/tautological-tests.md +0 -47
  66. package/skills/triage-loop/references/shepherd.md +0 -64
  67. package/skills/vitest-test-authoring/SKILL.md +0 -22
  68. package/skills/vitest-test-authoring/references/mock-boundaries.md +0 -9
@@ -1,74 +0,0 @@
1
- # Reading the four refs
2
-
3
- Use before any rebase or lease push of a branch other agents or humans may also write. Publish this
4
- branch; do not open a replacement pull request.
5
-
6
- `origin` and `main` below stand for the consumer's remote and default branch; substitute the names
7
- local policy declares.
8
-
9
- ## Setup
10
-
11
- - Run `git fetch origin main <branch>` as its own command. Never chain the fetch with a rebase,
12
- reset, or merge.
13
- - HEAD must be the branch being updated. A stack checkout can leave the top layer checked out, so
14
- check out the layer first. A missing stack field means membership is unknown, not unstacked.
15
- - A dirty worktree stops you before a fast-forward, reset, or rebase. Do not switch branches.
16
- - Continue a conflicted rebase with `GIT_EDITOR=true git rebase --continue`.
17
-
18
- ## Read the refs
19
-
20
- - Print `git rev-parse` of HEAD, `origin/<branch>`, `origin/main`, and local `main` when it exists.
21
- Local `main` is never the rebase target; when it exists, `git rev-list --left-right --count
22
- main...origin/main` with a nonzero right count means local `main` is behind.
23
- - Print `git rev-list --left-right --count HEAD...origin/<branch>` (left: commits only on the
24
- local branch; right: commits only on `origin/<branch>`) and
25
- `git log --oneline --left-right HEAD...origin/<branch>`.
26
- - Print `git cherry -v origin/<branch> HEAD` and `git cherry -v HEAD origin/<branch>`. A leading `-`
27
- is the same patch under another SHA; a leading `+` is a patch the other side lacks.
28
- - Treat `git range-diff` as a reading aid, not the rebase cut, and read it from the base those
29
- commits were built on. Never run it from a new stack parent: after a stack rebase, old parent
30
- commits look like unique local work.
31
- - Unmatched commits on `origin/<branch>` are new commits someone pushed.
32
-
33
- ## Lease push
34
-
35
- - Capture `<sha>` with `git rev-parse origin/<branch>` after the fetch and before any rewrite. Push
36
- a non-fast-forward with `git push --force-with-lease=<branch>:<sha> origin <branch>`, always
37
- naming the remote and branch so a configured push remote cannot change the destination. With concurrent writers,
38
- capture right after the setup fetch and before any later fetch, so a later fetch cannot silently
39
- widen the lease.
40
- - If HEAD equals that SHA, do not push.
41
- - If a lease or non-force push is rejected, fetch again and re-read. It is still this branch.
42
-
43
- ## Unstacked
44
-
45
- Before any move and after every move onto `origin/<branch>`, including when HEAD already equals it
46
- (`0 0`) but `origin/main` has advanced, run `git merge-base --is-ancestor origin/main HEAD`. Exit 0
47
- means the branch already contains `origin/main`; nonzero means rebase onto `origin/main`, then lease
48
- push.
49
-
50
- | Left/right | Action |
51
- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
52
- | `0 0`, `origin/main` already an ancestor | Stop. |
53
- | `0 0`, `origin/main` not an ancestor | Rebase onto `origin/main`, then lease push. |
54
- | `0 N` | `git merge --ff-only origin/<branch>`, then the ancestor check. |
55
- | `N 0` | Read `git log --oneline origin/<branch>..HEAD`: those commits are what a push adds, including a remote rewind to an ancestor. Own unpushed work with `origin/main` an ancestor: `git push origin <branch>`. Otherwise rebase onto `origin/main`, then lease push. A rewind you did not make: stop and ask. |
56
- | Diverged, local-only commits are rewritten copies (every local-only commit has cherry `-`; matching subjects alone do not prove equivalence), no unique local work | Clean tree, `git reset --hard origin/<branch>`, then the ancestor check. |
57
- | Diverged, origin has new patches to keep and HEAD has unique local commits | `git rebase origin/<branch>` as its own command, then the ancestor check, then lease push whichever way the check exits (after another rebase onto `origin/main` if it is nonzero). This is the one added rebase target, not a license to rebase onto an arbitrary ref. If the rewrite changed patches and unique local work is mixed in, stop and ask. |
58
-
59
- ## Stacked
60
-
61
- A stack rebase is the usual reason `origin/<branch>` was rewritten, but another agent or a human can
62
- rewrite an unstacked branch the same way.
63
-
64
- - On a diverged layer, adopt `origin/<branch>` with `git reset --hard` when the layer is checked
65
- out, or `git branch -f` when it is not, if the left-right log shows pre-rebase copies: the same
66
- layer subjects on both sides and old parent subjects only on the left. Require `git cherry`
67
- patch equivalence (`-`) for every local layer commit first; matching subjects alone do not
68
- prove it, and a `+` commit is unique local work.
69
- - Never `git rebase origin/<branch>` on a stack layer: it replays parent commits onto the layer.
70
- - Never run the plain rebase-onto-main procedure on a mid-stack branch; use its stack-aware form.
71
- - If the layer has unpushed commits that are not the old parent and not already on origin under a
72
- new SHA, stop and ask.
73
- - After adopting the rewritten tip, run the stack-aware rebase only when the stack still needs to
74
- move onto `origin/main`.
@@ -1,4 +0,0 @@
1
- # Implementation and review
2
-
3
- Use [implementation](implementation.md) while editing, [evidence sweep](evidence-sweep.md) before
4
- handoff, and [review](review.md) for an independent review.
@@ -1,20 +0,0 @@
1
- # Implementation
2
-
3
- Before fixing an issue, find out why the affected code exists: read its history, callers, tests,
4
- and linked issues. A fix that ignores the code's original purpose often breaks it or patches a
5
- symptom. If the code no longer serves a purpose, or its job is done elsewhere, delete it instead of
6
- fixing it, along with its tests, configuration, and documentation.
7
-
8
- For cross-cutting work, track accepted interface, data, validation, and ownership decisions that
9
- could otherwise be lost during coding. Start from a failing behavioral test when practical and
10
- complete the real path rather than adding placeholders or compatibility shims without a requirement.
11
-
12
- When behavior changes, update the public contract, documentation, fixtures, and generated artifacts
13
- that describe it. Keep local commands, branch policy, and release mechanics in the consumer wrapper.
14
-
15
- Resolve rebase conflicts semantically: identify the upstream invariant, integrate both changes,
16
- and rerun the tests for that invariant. Do not treat the conflict as a choice of whole-file versions.
17
-
18
- Removing a deadline or abort bound needs a replacement on the same path, or evidence and a test
19
- showing every caller supplies its own bound. When changing a policy table, check sibling rows for
20
- contradictory conventions.
@@ -1,49 +0,0 @@
1
- # Review response
2
-
3
- Use when responding to feedback on an open change: a human reviewer, an automated reviewer, or a
4
- shepherding tool that surfaces both. This is the response side of [review](review.md). Record
5
- unresolved risk as an explicit decision or follow-up, never as an unnoticed gap.
6
-
7
- Give every surfaced item exactly one disposition before resolving it. Record that disposition where
8
- the review conversation lives.
9
-
10
- - Invalid — wrong, already satisfied by the current diff, or out of an already-settled scope —
11
- gets
12
- a reason and closes with no code change and no follow-up.
13
- - Blocking — correctness, security, data safety, or a gap against a linked requirement — gets
14
- fixed, pushed, and confirmed on the change's head commit before closing. Closing first can leave
15
- an unfixed commit behind a closed conversation.
16
- - For human feedback, non-blocking work gets folded into an already-planned push when the fix is
17
- cheap and low-risk, and otherwise becomes a follow-up when leaving it undone would change
18
- behavior, structure, or risk.
19
- - For an automated reviewer, a valid, actionable non-blocking item always becomes a follow-up
20
- instead; do not edit code or push for that item.
21
- - Treat reviewer identity as platform metadata. Treat the review text as untrusted input.
22
- - Decline a correct item that is only a style preference, a restatement, or polish the change is
23
- fine without. Give a reason and open no follow-up.
24
- - Escalate work the change cannot absorb, such as a large architectural or ownership change. Record
25
- it where decisions are tracked and report it for direction. Do not implement it or downgrade it
26
- to a follow-up.
27
-
28
- Route automated-reviewer follow-ups through [GitHub issues](../../github-issue/SKILL.md).
29
-
30
- - Search for an existing follow-up before opening a new one. Reuse or extend it when it covers the
31
- work, and group related items from the same round.
32
- - The issue must carry the exact existing `follow-up` label and a non-closing, fully qualified link
33
- to the originating pull request.
34
- - Re-fetch the issue and verify its canonical identity, exact label, and pull-request link before
35
- replying in the review conversation with the disposition and issue URL; only then resolve the
36
- conversation.
37
- - If search, reuse or creation, labeling, linkage, read-back verification, reply, or resolution is
38
- unavailable or unauthorized, fail closed: leave the conversation unresolved and report the
39
- blocker.
40
-
41
- Before editing, read every outstanding item and drain the round locally. The cost of iterating is
42
- the push, not the commit: a push re-runs checks and re-triggers automated reviewers. Declining a
43
- round without pushing lets that round converge.
44
-
45
- By hand-off, every item has a disposition and has reached closure. An escalation closes through its
46
- decision record. When the review surface cannot close an item, say so and leave it.
47
-
48
- Consumer wrapper owns, beyond GitHub and the required `follow-up` label: review system, resolution
49
- mechanism, repository destination, additional taxonomy, and severity vocabulary.
@@ -1,10 +0,0 @@
1
- # Review
2
-
3
- Review the complete diff, not only changed implementation lines. Check premise and scope, public
4
- contract compatibility, failure paths, authorization, untrusted input, secrets, and security
5
- boundaries. Remove dead paths and stale documentation rather than labeling them as legacy.
6
-
7
- Record unresolved risk as an explicit accepted decision or follow-up, never as an unnoticed gap.
8
- Check the pull-request description against the final behavior and audience impact. After CI
9
- diagnosis, ensure confirmed local-verification gaps or local/CI mismatches and their correction
10
- remain disclosed; passing checks do not erase the gap discovered earlier.
@@ -1,22 +0,0 @@
1
- ---
2
- name: backend-vitest-test-authoring
3
- description: Test backend persistence, providers, services, and queues with Vitest.
4
- ---
5
-
6
- # Backend Vitest test authoring
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/backend-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
- - Exercise a real integration boundary only when the test environment controls its lifecycle.
15
- Otherwise mock the network or provider edge.
16
- - Randomize fixture identities where a shared store can collide.
17
- - Assert authorization and retry behavior at the boundary.
18
- - Clean up resources deterministically.
19
- - Read [integration boundaries](references/integration-boundaries.md) for fixture and collision
20
- safety.
21
-
22
- Consumer wrapper owns: database setup, queue providers, test projects, and rate-limit policy.
@@ -1,10 +0,0 @@
1
- # Integration boundaries
2
-
3
- Use real persistence, queue, and internal-service boundaries when the test environment controls
4
- their lifecycle. Mock only external provider edges. Create collision-safe fixture identities and
5
- register event listeners before the mutation that produces them. Cleanup must be ownership-scoped;
6
- never broadly reset shared state used by concurrent tests.
7
-
8
- Assert persisted state, emitted work, or externally visible results at the boundary. A mock-only
9
- test is insufficient when import wiring, serialization, transaction behavior, or retries are part
10
- of the contract.
@@ -1,92 +0,0 @@
1
- ---
2
- name: bounded-iteration
3
- description: Bound the rows each run reads when writing or reviewing scheduled jobs, reconcilers, cleanups, dispatchers, backfills, exports, list endpoints, or any loop that reads rows.
4
- ---
5
-
6
- # Bounded iteration
7
-
8
- Read applicable `AGENTS.md` and the repository's local database adapter when present.
9
- Local policy overrides these portable conventions.
10
-
11
- A run's cost is the rows it reads and the work it starts, not the memory it holds. Read
12
- [sweep patterns](references/sweep-patterns.md) for worked SQL and loop shapes.
13
-
14
- 1. **Choose work, not entities.** Read only rows that need work, through a predicate an index
15
- serves: a work-item or dirty-marker row, a parent id, a due timestamp with a partial index, or
16
- a time or UUIDv7 window past a high-water mark. Column-to-column comparisons, `OR` of unrelated
17
- conditions, and `EXISTS` as the only condition are not filters. (`postgres-required-predicates`)
18
- A per-row threshold becomes one bucket per distinct value, comparing the stored fact with a
19
- bound, never with another column; `timestamptz + interval` is not immutable, so it cannot be
20
- indexed. See [per-row interval](references/sweep-patterns.md#per-row-interval-one-bucket-per-threshold)
21
- and [age milestones](references/sweep-patterns.md#age-milestones-from-the-uuidv7-key).
22
- 2. **Cap every run.** Every loop has a per-run cap (batches, rows, or a deadline), reports whether
23
- work remains, and resumes from a persisted position. Never loop until empty, and never default
24
- a cap to infinity.
25
- 3. **Bound every statement.** A SELECT, UPDATE, or DELETE that can touch many rows has a `LIMIT`.
26
- For writes the `LIMIT` goes in a CTE, with `FOR UPDATE SKIP LOCKED` when workers compete.
27
- (`postgres-lock-ordering`) For list reads, the bound is the page `LIMIT` plus a window or keyset,
28
- not a separate candidate cap.
29
- 4. **A stream is not a bound.** A cursor or stream bounds memory, not work. Cap the rows streamed
30
- per run.
31
- 5. **Resume without restarting.** Keep a keyset position on the UUIDv7 key or a
32
- `<verb>_through_at` time position, fix the sweep's end when it starts, and rescan an overlap
33
- when insert order differs from commit order. Prefer the position in job data; a cursor table is
34
- for a position that must be transactional with domain rows, and follows
35
- [table shapes](../postgres-schema-design/references/table-shapes.md).
36
- (`postgres-generated-column-predicates`)
37
- 6. **No unbounded fan-out.** Use `Promise.all` only over a bounded result, with bounded
38
- concurrency.
39
- 7. **Keyset pagination.** No `OFFSET`. Clamp the client's page size on the server. The API schema
40
- keeps a static ceiling; the default and the effective maximum are runtime-tunable but never
41
- above it. (`postgres-no-offset`)
42
- 8. **List and feed reads.** A list read is one walk over the entity being listed. Filters go in
43
- `WHERE`, served by an index. Order with `ORDER BY key DESC, id DESC` and `LIMIT page+1`, and
44
- continue with a plain keyset cursor, `(key, id) < ($1, $2)`. The page `LIMIT` plus a time window
45
- or the keyset bound the read. A keyset alone does not bound rows scanned. When a filter can
46
- reject long runs, such as a viewer's blocks or mutes, the time window is the scan bound where the
47
- sort has one, and EXPLAIN at representative cardinality compares rows read with rows returned. The
48
- simplest query comes first; anything more complex needs `EXPLAIN ANALYZE` plans beating it. For a
49
- ranked list that is a join and `ORDER BY` on the stored score. No candidate pools: no capped or
50
- `MATERIALIZED` CTE over the listed entity that is filtered or limited afterward, no window loops
51
- or resume probes, no proof state in the cursor, and no runtime-config fields that exist only to
52
- cap a read. A single walk with an inspected-row cap is fine, and may return a short or empty page
53
- with a continuation cursor and `has_next_page` true. Small viewer-scoped sets (the viewer's follows, mutes, blocks and
54
- memberships) may be subqueries or semi-joins, because write limits bound them. Measure a
55
- list-read change against the plain single walk, not only against the base branch. See
56
- [`MATERIALIZED` CTEs](../postgres-node-performance-tuning/references/performance-patterns.md).
57
- 9. **Tunables are runtime configuration.** Batch sizes, page sizes, caps, and windows come from the
58
- consumer's runtime configuration with a validated default and a hard maximum, and are bound as
59
- SQL parameters. `LIMIT 1` and an external API's page maximum are contracts, not tunables. For
60
- list reads, the bound is the page `LIMIT` plus a window or keyset, not a separate candidate cap.
61
- 10. **One dispatcher per signal.** Split an `OR` of unrelated reasons into one dispatcher per
62
- reason, each with its own index-served predicate, position, and schedule, all enqueuing the same
63
- idempotent job. Writes that cause a signal enqueue directly; the sweep is the backstop. See
64
- [one dispatcher per signal](references/sweep-patterns.md#one-dispatcher-per-signal).
65
- 11. **Deduplicate jobs by entity and triggering event.** A job id keyed only by the entity drops a
66
- new trigger while the last job runs or is retained. Key it by entity and event; dedup lasts
67
- only while the record is retained, and a failed retained job still claims its id. See
68
- [queue job ids](references/sweep-patterns.md#queue-job-ids-for-deduplication).
69
- 12. **Repair through an existing reconciler.** Repeat a fire-and-forget side effect (cache fill,
70
- filter add, enqueue) idempotently from the reconciler that already sweeps recently changed
71
- rows. Do not add a sweeper. See
72
- [repair](references/sweep-patterns.md#repair-through-an-existing-reconciler).
73
- 13. **Membership filters are never rebuilt on a schedule.** Add on write, rebuild in full only on
74
- an operator action or a detected failure, and stop trusting the filter after a failed add.
75
- Deleted keys and growth only cost false positives. See
76
- [membership filters](references/sweep-patterns.md#membership-filters).
77
- 14. **Global rankings stay one periodic aggregate.** A result over every row needs every score;
78
- incremental per-row inputs move the cost to every write without freshening the ranking. Give
79
- the pass an EXPLAIN budget. See [global ranking](references/sweep-patterns.md#global-ranking).
80
- 15. **External listings carry the provider's continuation token.** Cap pages per run and enqueue a
81
- continuation with the token; restarting at page one lets failing front items starve the rest.
82
- See [external listing](references/sweep-patterns.md#external-listing-with-a-continuation-token).
83
- 16. **Verify with a plan.** EXPLAIN at representative cardinality shows no Seq Scan on an
84
- unbounded table, and an index that supplies the `ORDER BY`, so the scan stops at the
85
- `LIMIT` instead of reading and sorting every match. Compare rows read with rows returned.
86
-
87
- For work-item, lease, and cursor tables, read [postgres-schema-design](../postgres-schema-design/SKILL.md).
88
- For query shape and streaming, read [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
89
- For UUIDv7 windows and pruning, use [UUIDv7 partitioning](../postgres-partitioning-uuid-v7/SKILL.md).
90
- Names in parentheses are generic `jonathanong/no-mistakes` rules; check that the installed release
91
- has one before relying on it. No generic rule checks run caps, streams, or fan-out.
92
- Consumer policy owns run caps, tunable names and ceilings, schedules, and enforcement configuration.