{"_id":"@davesienkowski/gsd-contribution-toolkit","name":"@davesienkowski/gsd-contribution-toolkit","dist-tags":{"latest":"2.1.3"},"versions":{"2.1.3":{"name":"@davesienkowski/gsd-contribution-toolkit","version":"2.1.3","description":"GSD Contribution Toolkit — an installable, opt-in gsd-core capability bundling the contribution + maintainer-review knowledge (two skills, five commands, one advisory plan:pre step). Advisory-only; carries no enforcement gates.","keywords":["gsd","gsd-core","capability","contribution-toolkit"],"homepage":"https://github.com/davesienkowski/gsd-contribution-toolkit#readme","repository":{"type":"git","url":"git+https://github.com/davesienkowski/gsd-contribution-toolkit.git"},"bugs":{"url":"https://github.com/davesienkowski/gsd-contribution-toolkit/issues"},"author":{"name":"davesienkowski"},"license":"MIT","publishConfig":{"access":"public"},"_id":"@davesienkowski/gsd-contribution-toolkit@2.1.3","gitHead":"c364f5702b099957189644cf9590e02539bfd01f","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-5H+u7QH2bSrrc4tmFiUy1JTnMXq0SqLabFX6lOrNFhDCXHIeJ4648Ix2PTk/Y6zpuRh2NRN/TdJFAyIrn2CQ0Q==","shasum":"2d7e82a87ad395740c24ae3f173fc4a14a87e69c","tarball":"https://registry.npmjs.org/@davesienkowski/gsd-contribution-toolkit/-/gsd-contribution-toolkit-2.1.3.tgz","fileCount":58,"unpackedSize":513181,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDOc9b7mSqJHb1h9ZC3fyP3mwUjtPpiwSGncuEaKiV73wIhAL88MlYv6AYlYetiYrhLPpO+7DCSW6YKaaiTJ95/2Y3O"}]},"_npmUser":{"name":"davesienk","email":"dave@sienkowski.com"},"directories":{},"maintainers":[{"name":"davesienk","email":"dave@sienkowski.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gsd-contribution-toolkit_2.1.3_1782282770685_0.3865420460972253"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-24T06:32:50.593Z","2.1.3":"2026-06-24T06:32:50.893Z","modified":"2026-06-24T06:32:51.063Z"},"maintainers":[{"name":"davesienk","email":"dave@sienkowski.com"}],"description":"GSD Contribution Toolkit — an installable, opt-in gsd-core capability bundling the contribution + maintainer-review knowledge (two skills, five commands, one advisory plan:pre step). Advisory-only; carries no enforcement gates.","homepage":"https://github.com/davesienkowski/gsd-contribution-toolkit#readme","keywords":["gsd","gsd-core","capability","contribution-toolkit"],"repository":{"type":"git","url":"git+https://github.com/davesienkowski/gsd-contribution-toolkit.git"},"author":{"name":"davesienkowski"},"bugs":{"url":"https://github.com/davesienkowski/gsd-contribution-toolkit/issues"},"license":"MIT","readme":"# GSD Contribution Toolkit\n\n> A self-contained, installable **GSD capability** that makes a *broken* `open-gsd/gsd-core`\n> contribution physically hard to submit — by enforcing the **outcomes** that matter\n> (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 & scope](#honesty--scope)\n- [Documentation](#documentation)\n- [For reviewers](#for-reviewers)\n- [Provenance & 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> Enforcement is a **Claude Code** property (see [Per-runtime behavior](#per-runtime-behavior)). On\n> 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 <gsd-core>/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:<40-hex>` (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 <gsd-core>/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 <gsd-core>/bin/gsd-tools.cjs capability status   --scope project\nnode <gsd-core>/bin/gsd-tools.cjs capability disable  contribution-toolkit --scope project\nnode <gsd-core>/bin/gsd-tools.cjs capability enable   contribution-toolkit --scope project\nnode <gsd-core>/bin/gsd-tools.cjs capability update   contribution-toolkit --scope project --yes\nnode <gsd-core>/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> The owner can also drive the same lifecycle from a local clone via the toolkit's own wrapper\n> (`bin/contrib-capability.cjs install|on|off|status|remove`), which auto-applies the shared-edits\n> 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 & 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 & 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","readmeFilename":"README.md","_rev":"1-482877382f892ff19fff34a7dcd1a109"}