{"id":51221305,"url":"https://github.com/davesienkowski/gsd-contribution-toolkit","last_synced_at":"2026-06-28T07:31:03.904Z","repository":{"id":366913310,"uuid":"1277584375","full_name":"davesienkowski/gsd-contribution-toolkit","owner":"davesienkowski","description":"A self-contained, toggleable GSD capability that enforces clean open-gsd/gsd-core contributions at the Claude Code harness boundary — 12 fail-closed PreToolUse gates + 2 skills + 5 commands, installed via gsd-core's capability system. Advisory-only on non-Claude runtimes.","archived":false,"fork":false,"pushed_at":"2026-06-23T20:12:50.000Z","size":205,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T22:13:27.633Z","etag":null,"topics":["capability","claude-code","code-quality","contribution-toolkit","developer-tools","git-hooks","gsd","gsd-core","pretooluse-hooks"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davesienkowski.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-23T02:45:49.000Z","updated_at":"2026-06-23T20:12:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/davesienkowski/gsd-contribution-toolkit","commit_stats":null,"previous_names":["davesienkowski/gsd-contribution-toolkit"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/davesienkowski/gsd-contribution-toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davesienkowski%2Fgsd-contribution-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davesienkowski%2Fgsd-contribution-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davesienkowski%2Fgsd-contribution-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davesienkowski%2Fgsd-contribution-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davesienkowski","download_url":"https://codeload.github.com/davesienkowski/gsd-contribution-toolkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davesienkowski%2Fgsd-contribution-toolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34881384,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["capability","claude-code","code-quality","contribution-toolkit","developer-tools","git-hooks","gsd","gsd-core","pretooluse-hooks"],"created_at":"2026-06-28T07:31:02.233Z","updated_at":"2026-06-28T07:31:03.896Z","avatar_url":"https://github.com/davesienkowski.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GSD Contribution Toolkit\n\n\u003e A self-contained, installable **GSD capability** that makes a *broken* `open-gsd/gsd-core`\n\u003e contribution physically hard to submit — by enforcing the **outcomes** that matter\n\u003e (no broken issue/PR/push, no edits to generated files) at the Claude Code harness boundary.\n\nA `role:feature` capability for **GSD 1.6.0+** (ADR-1244 capability ecosystem). It bundles the\n*knowledge* (two skills), the *triggers* (five `gsd-*` commands), and the *load-bearing layer* —\ntwelve `PreToolUse` enforcement hooks that the **harness** runs (not the model) and that call\ngsd-core's own LIVE gate scripts at runtime. It installs, toggles, and removes through gsd-core's\nnative capability system, tracked by gsd-core's ledger + consent.\n\n- **Repo:** `github.com/davesienkowski/gsd-contribution-toolkit`\n- **Latest release:** `#v2.1.3`\n- **Install:** [§ Install](#install) · **Architecture:** [docs/cross-runtime-delivery-model.md](docs/cross-runtime-delivery-model.md)\n- **Reviewers (gsd-core maintainers):** start at [§ For reviewers](#for-reviewers).\n\n---\n\n## Table of contents\n\n- [Why it exists](#why-it-exists)\n- [What's included](#whats-included)\n- [What it's capable of — by role](#what-its-capable-of--by-role)\n- [Install](#install)\n- [Manage (on / off / status / remove)](#manage-on--off--status--remove)\n- [How it works](#how-it-works)\n- [Per-runtime behavior](#per-runtime-behavior)\n- [What the gates cover](#what-the-gates-cover)\n- [Recovery offramp](#recovery-offramp)\n- [Honesty \u0026 scope](#honesty--scope)\n- [Documentation](#documentation)\n- [For reviewers](#for-reviewers)\n- [Provenance \u0026 versioning](#provenance--versioning)\n\n---\n\n## Why it exists\n\nSkills and slash-commands are model-driven: under deadline pressure a model can rationalize past a\n\"please run the full suite first\" instruction. Pressure-testing the contribution skill confirmed that\nvariance. **Hooks are the only layer the harness always runs** — they fire *before* the permission\ncheck, so they hold even under `--dangerously-skip-permissions`. This toolkit puts the\nnon-negotiable contribution outcomes behind that layer, so even a sloppy, deadline-pressured run is\nblocked and corrected rather than merged red. (Verifier-reach = spec-reach, applied to one's own\ncontribution pipeline.)\n\n## What's included\n\nThe bundle is **self-contained** — a remote install delivers the full working surface, not a\nhooks-only artifact:\n\n| Surface | Count | Items |\n|---|---|---|\n| `PreToolUse` gates | 12 | `gh-issue-create`, `gh-pr-create`, `gh-edit`, `issue-dedupe`, `policy-invariants`, `lint-ci-marker`, `git-commit-convention`, `containment`, `freshness`, `githooks-seal`, `scan-gate`, `binlib-edit` |\n| `UserPromptSubmit` advisory | 1 | `protocol-reminder` |\n| Skills | 2 | `gsd-core-contribution`, `maintainer-review-sweep` |\n| Commands | 5 | `gsd-submit`, `gsd-review-sweep`, `gsd-triage-assist`, `gsd-release-preflight`, `gsd-ruleset-drift` |\n| Loop contribution | 1 | an advisory `plan:pre` fragment, gated by the default-off `workflow.gsd_contrib_enforcement` flag |\n\nThe bundled hook scripts **resolve and call the LIVE gsd-core gate scripts at runtime** — they never\nreimplement gsd-core policy. When gsd-core's scripts evolve, the gates follow.\n\n## What it's capable of — by role\n\n| Role | What the toolkit gives you |\n|---|---|\n| **CODEOWNER** (repo owner) | The full enforcement pipeline applied to your *own* contributions: no broken issue/PR/push and no generated-file edits can leave your machine. Plus every maintainer + contributor capability below. |\n| **Maintainer** | `gsd-triage-assist` (LIVE dedupe + version-gate + canonical role suggestion), `gsd-release-preflight` (runs the four LIVE release scripts before a release is cut), `gsd-ruleset-drift` (declared `.github/rulesets/` vs live branch protection), and the `maintainer-review-sweep` skill (cost-to-advance triage + re-review of change-requested PRs). |\n| **Contributor** | `gsd-submit` files a verified finding as a proper issue + fix PR through the repo's intake gates; gates enforce well-formed issues/PRs, version/template policy, conventional commits, a green `lint:ci` stamp before push, CI-check-run-green before PR, secret/scan cleanliness, and no edits to generated `bin/lib/*.cjs`. |\n| **Collaborator** | The same gates as a contributor, plus advisory guidance from the `gsd-core-contribution` skill and a GSD-native [recovery offramp](#recovery-offramp) when a gate denies — so a block becomes a tracked, resumable fix, not a dead stop. |\n\n\u003e Enforcement is a **Claude Code** property (see [Per-runtime behavior](#per-runtime-behavior)). On\n\u003e other runtimes the skills + commands still deliver, but the toolkit runs **advisory-only**.\n\n## Install\n\nInstall through gsd-core's git capability adapter (ADR-1244 D3):\n\n```bash\nnode \u003cgsd-core\u003e/bin/gsd-tools.cjs capability install \\\n  https://github.com/davesienkowski/gsd-contribution-toolkit.git#v2.1.3 \\\n  --scope project --yes --shared-file .claude/settings.json\n```\n\n- `--scope project` installs into the gsd-core checkout (`.gsd/capabilities/contribution-toolkit/` +\n  a `.gsd-capabilities.json` ledger), keeping enforcement project-scoped — never `~/.claude`.\n  Use `--scope global` for `~/.gsd/...`.\n- `--yes` grants consent — the capability ships executable surfaces (the 13 hooks), so the install\n  discloses them and aborts without consent.\n- `--shared-file .claude/settings.json` is **required to actually wire the hooks** into\n  `settings.json`; without it the install records the ledger + overlay but applies no gates.\n- Pin a release with `#v2.1.3` (a tag) or `#sha:\u003c40-hex\u003e` (an exact commit). The earlier `…-gate`\n  repo name GitHub-redirects, so an existing `#v1.0.0` install does not hard-break.\n\n### Integrity-pinned install (npm, ADR-1244 D1)\n\nThe bundle is also published to npm as **`@davesienkowski/gsd-contribution-toolkit`**. Unlike the git\nadapter (which records a null integrity digest), the `npm:` source kind verifies the downloaded tarball\nagainst a `sha512-` digest **before** staging — so a tampered artifact is refused, fail-closed:\n\n```bash\n# Fetch the authoritative digest for the version you're pinning:\nDIGEST=$(npm view @davesienkowski/gsd-contribution-toolkit@2.1.3 dist.integrity)\n\nnode \u003cgsd-core\u003e/bin/gsd-tools.cjs capability install \\\n  npm:@davesienkowski/gsd-contribution-toolkit@2.1.3 \\\n  --integrity \"$DIGEST\" \\\n  --scope project --yes --shared-file .claude/settings.json\n```\n\n- `--integrity sha512-…` is honored only for the `tarball`/`npm`/`registry` source kinds; `git`/`local`\n  installs always record a null digest. Pinning is what turns the trust model's integrity guarantee on.\n- The published `capability.json` carries a `provenance: { sourceRepo, commit }` block (advisory; it\n  surfaces in the install ledger and does not gate the install).\n\n## Manage (on / off / status / remove)\n\n```bash\nnode \u003cgsd-core\u003e/bin/gsd-tools.cjs capability status   --scope project\nnode \u003cgsd-core\u003e/bin/gsd-tools.cjs capability disable  contribution-toolkit --scope project\nnode \u003cgsd-core\u003e/bin/gsd-tools.cjs capability enable   contribution-toolkit --scope project\nnode \u003cgsd-core\u003e/bin/gsd-tools.cjs capability update   contribution-toolkit --scope project --yes\nnode \u003cgsd-core\u003e/bin/gsd-tools.cjs capability remove   contribution-toolkit --scope project\n```\n\n`enable`/`disable` toggle the **entire** surface (hooks + commands + skills); `remove` strips exactly\nthe ledger-recorded files + shared-file fragments and revokes consent — it never deletes shared files\nwholesale. `disable`/`remove` genuinely take the enforcement away (the hooks leave `settings.json` —\nthe hooks *are* the enforcement).\n\n\u003e The owner can also drive the same lifecycle from a local clone via the toolkit's own wrapper\n\u003e (`bin/contrib-capability.cjs install|on|off|status|remove`), which auto-applies the shared-edits\n\u003e and reconciles legacy untagged entries. Remote installers use the native adapter above.\n\n## How it works\n\n1. **Harness-boundary enforcement.** The 12 `PreToolUse` gates are written into `settings.json` on\n   install. The harness runs them before each matching tool call; a broken contribution outcome\n   returns `permissionDecision: \"deny\"`. They fail **closed** — an unparseable command, an\n   unreadable body, or a missing LIVE script denies rather than allows.\n2. **Reuse, never reimplement.** Each gate resolves and calls the LIVE gsd-core gate script (issue\n   version-gate, PR template policy, `lint:ci`, the scan scripts, etc.). See\n   [docs/reuse-and-methodology.md](docs/reuse-and-methodology.md).\n3. **Accountable override.** A deliberate bypass rides on the existing per-worktree, append-only\n   `GSD_CONTRIB_OVERRIDE` receipt (a logged reason-string, never silent) — no new mechanism.\n\n## Per-runtime behavior\n\nDelivery is **per-runtime**, and what it enforces depends on the runtime:\n\n| Layer | Claude Code | Other runtimes (Codex, OpenCode, …) |\n|---|---|---|\n| Skills | delivered | delivered via the native `skills[]` contribution (copy-convert) |\n| Commands | delivered | Claude-only today (no third-party slash-command surface — see [upstream](docs/upstream-feature-requests.md)) |\n| `PreToolUse` enforcement | **full** | **none** → toolkit runs **advisory-only** |\n\nEnforcement is a Claude-harness property; everywhere else the toolkit is advice, not a hard block.\nEach skill carries an explicit advisory-only note. Full model:\n[docs/cross-runtime-delivery-model.md](docs/cross-runtime-delivery-model.md).\n\n## What the gates cover\n\n| Gate | Guards |\n|---|---|\n| `gh-issue-create` / `gh-pr-create` / `gh-edit` | well-formed, intake-passing issues/PRs (incl. `gh api`/`curl` REST synonyms) |\n| `issue-dedupe` | duplicate-issue detection before filing |\n| `policy-invariants` | the LIVE gsd-core mechanizable POLICY-02 checks on commit / pr-create |\n| `lint-ci-marker` | a fresh, tree-keyed `lint:ci`-green stamp before push |\n| `git-commit-convention` | conventional-commit message shape |\n| `containment` | edits/pushes confined to the intended worktree |\n| `freshness` | acting against a current base |\n| `githooks-seal` | git hooks not tampered |\n| `scan-gate` | secret / prompt-injection / base64 scans before push |\n| `binlib-edit` | no hand-edits to generated `bin/lib/*.cjs` (ADR-457) |\n\n## Recovery offramp\n\nWhen a gate **denies** — or the `gsd-core-contribution` skill surfaces a real blocking issue\nmid-run — you are offered a GSD-native recovery rather than a dead stop: **fix inline with\n`/gsd-quick`** for a trivial correction, or **route the issue through the GSD pipeline**\n(`/gsd-debug`, or `/gsd-discuss-phase`→`/gsd-plan-phase`→`/gsd-execute-phase`) as a tracked,\nresumable work item — then return to the submission once it is green. The offramp is **advisory\nonly**: the deny stays fail-closed, and it never suggests bypassing a gate or abusing the override.\n\n## Honesty \u0026 scope\n\nPlease read this as written — don't over-read it:\n\n- The capability's **GSD-loop surfaces are advisory**: `gates[]` is **empty**, and the one\n  `plan:pre` contribution fires only inside a GSD command. The capability does **not** reach the\n  harness tool-call boundary — a direct issue/PR/push typed outside a GSD command never crosses a\n  loop point, so the capability never sees it.\n- The **harness-boundary enforcement** is a property of the 12 `PreToolUse` hooks **once installed\n  into `settings.json`**, not an inherent property of this (toggleable) capability. **Do not read\n  this capability as \"unbypassable.\"**\n- It is **fully removable**: `disable`/`remove` genuinely takes the enforcement away.\n- Deliberate-bypass accountability rides on the existing per-worktree, append-only\n  `GSD_CONTRIB_OVERRIDE` receipt — this capability adds no new receipt mechanism.\n\n## Documentation\n\n- [docs/adr/](docs/adr/) — **Architecture Decision Records** (`CTK-ADR-*`, Nygard format): the\n  load-bearing decisions (harness-boundary enforcement; capability-native distribution via `hooks[]`;\n  the v2.3 full-surface/cross-runtime model), each independently challengeable. Accepted but open to\n  maintainer revision.\n- [docs/foundations.md](docs/foundations.md) — **what the toolkit is built on** and how it was\n  designed: trek-e's methodology, the skills-artificer law-lenses, the LIVE gsd-core machinery it\n  reuses, the lineage of every command/skill, and how the design serves gsd-core's contribution goals.\n- [docs/skills-reference.md](docs/skills-reference.md) — the **2 skills**: what each is capable of, when\n  it triggers, the pipeline it runs, and how to invoke it.\n- [docs/commands-reference.md](docs/commands-reference.md) — the **5 commands**: what each does, the\n  **accepted arguments/parameters**, examples, and the mutation-safety model.\n- [docs/cross-runtime-delivery-model.md](docs/cross-runtime-delivery-model.md) — the per-runtime\n  delivery model, symlink-vs-copy-convert, enforcement-is-Claude-only, the `off`-vs-`remove`\n  lifecycle, and why slash-commands are Claude-only (ADR-959).\n- [docs/reuse-and-methodology.md](docs/reuse-and-methodology.md) — the reuse map (delegate / wrap /\n  leave-alone) and methodology alignment with trek-e's published practices.\n- [docs/upstream-feature-requests.md](docs/upstream-feature-requests.md) — two capability-framework\n  asks for gsd-core maintainers (an opt-in symlink/`link` delivery mode; a third-party\n  slash-command overlay surface), each citing this toolkit as the reference implementation.\n\n## For reviewers\n\nIf you maintain gsd-core and are reviewing this toolkit:\n\n- Start with [docs/foundations.md](docs/foundations.md) — it lays out what the toolkit is assembled\n  from (your methodology, the artificer lenses, the LIVE gsd-core machinery), the lineage of every\n  command/skill, how it was designed, and how its design maps to what gsd-core is driving for.\n- Then [docs/adr/](docs/adr/) — the three decisions are stated as challengeable ADRs (Accepted, but\n  open to revision via a superseding ADR). Their gsd-core factual claims were re-verified against the\n  live `capability-validator.cjs` / `capability-lifecycle.cjs` / `capability-registry.cjs`.\n- The bundle conforms to the LIVE capability validators (tri-surface `declared == shipped` parity\n  across hooks + skills + commands) — see the manifest `capability.json`.\n- The two things that would let this capability go *fully native* and *cross-runtime* are written up\n  in [docs/upstream-feature-requests.md](docs/upstream-feature-requests.md) — they are framework\n  additions, not changes this toolkit can make on its own.\n- The honesty contract above is deliberate and enforced by the publish-time conformance check; the\n  capability is never presented as carrying harness-wide enforcement on its own.\n\n## Provenance \u0026 versioning\n\n- **Version:** 2.1.3 (semver; the bundle is generated from canonical `hooks/`/`skills/`/`commands/`\n  with a `--check` drift gate and validated against the LIVE gsd-core capability validators before\n  publish). The v2.1.x line is **docs releases** (v2.1.1 README; v2.1.2 foundations + ADRs; v2.1.3 skills/commands reference) —\n  the bundle logic is byte-identical to v2.1.0.\n- **Source toolkit:** `gsd-contrib-toolkit` (private), through the v2.3 milestone.\n- See [CHANGELOG.md](CHANGELOG.md) for the release history.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavesienkowski%2Fgsd-contribution-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavesienkowski%2Fgsd-contribution-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavesienkowski%2Fgsd-contribution-toolkit/lists"}