S-tier hardening: releases, coverage, security, docs, spec versioning

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,51 @@
+name: Bug report
+description: Something in skillgate behaves incorrectly
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. skillgate is deterministic, so a minimal repro almost always pins it down.
+  - type: input
+    id: version
+    attributes:
+      label: skillgate version
+      description: Output of `skillgate --version`
+      placeholder: "0.3.0"
+    validations:
+      required: true
+  - type: dropdown
+    id: how
+    attributes:
+      label: How are you running it?
+      options:
+        - npx
+        - npm (installed dependency)
+        - CI (GitHub Actions)
+        - pre-commit
+        - Claude Code / opencode hook
+        - other
+    validations:
+      required: true
+  - type: textarea
+    id: spec
+    attributes:
+      label: Your .skillgate/done.yaml
+      description: The smallest spec that reproduces the issue.
+      render: yaml
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected vs what happened
+      description: Include the command you ran, the verdict/exit code, and the output.
+    validations:
+      required: true
+  - type: input
+    id: env
+    attributes:
+      label: Node version and OS
+      placeholder: "node 20.x, Ubuntu 24.04"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/renezander030/skillgate/security/advisories/new
+    about: Please report security issues privately, not as a public issue.
+  - name: Question / usage help
+    url: https://github.com/renezander030/skillgate/discussions
+    about: Ask how to wire skillgate into your workflow.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,26 @@
+name: Feature request
+description: Suggest a new gate type or capability
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What corner can your agent still cut?
+      description: Describe the definition-of-done step skillgate cannot enforce today.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed gate / behaviour
+      description: How would you express it in done.yaml? Sketch the YAML if you can.
+      render: yaml
+    validations:
+      required: true
+  - type: checkboxes
+    id: deterministic
+    attributes:
+      label: Determinism check
+      options:
+        - label: This can be decided as a pure function over the filesystem (no model, no network)
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+<!-- Thanks for contributing to skillgate. Keep PRs focused and deterministic. -->
+
+## What changed
+
+<!-- One or two sentences on the behaviour change. -->
+
+## Why
+
+<!-- The problem this solves. Link an issue if there is one: Closes #123 -->
+
+## How I verified it
+
+<!-- Commands you ran and what you observed. -->
+
+```
+npm run build && npm run test:coverage
+```
+
+## Checklist
+
+- [ ] Tests added/updated (unit in `test/*.test.ts`, CLI behaviour in `test/e2e.test.ts`)
+- [ ] `npm run test:coverage` passes locally (coverage thresholds are enforced in CI)
+- [ ] New/changed gate behaviour is documented in the README gate table
+- [ ] Added a bullet under `## Unreleased` in `CHANGELOG.md`
+- [ ] Change stays deterministic (pure function over the filesystem, no network, no model)

.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      dev-dependencies:
+        dependency-type: development
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

.github/scripts/changelog-section.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Print the CHANGELOG.md section for a given version, used as GitHub Release notes.
+// Usage: node changelog-section.mjs 0.4.0
+import fs from "node:fs";
+
+const version = process.argv[2];
+if (!version) {
+  console.error("usage: changelog-section.mjs <version>");
+  process.exit(1);
+}
+
+const md = fs.readFileSync(new URL("../../CHANGELOG.md", import.meta.url), "utf8");
+const lines = md.split("\n");
+
+// Match "## 0.4.0" (optionally followed by a date/anything).
+const startIdx = lines.findIndex((l) => new RegExp(`^##\\s+v?${version.replace(/\./g, "\\.")}\\b`).test(l));
+if (startIdx === -1) {
+  console.error(`no CHANGELOG section for ${version}`);
+  process.exit(1);
+}
+
+const body = [];
+for (let i = startIdx + 1; i < lines.length; i++) {
+  if (/^##\s+/.test(lines[i])) break; // next version heading
+  body.push(lines[i]);
+}
+
+console.log(body.join("\n").trim() || `Release ${version}`);

.github/workflows/ci.yml

@@ -9,11 +9,13 @@ permissions:
   contents: read
 
 jobs:
+  # Primary job — its check context is exactly "test" (kept stable for branch
+  # protection). Runs on the active LTS.
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
         with:
           node-version: '20'
           cache: npm
@@ -22,3 +24,35 @@ jobs:
       - run: npm test
       # dogfood: skillgate gates its own repo
       - run: node dist/src/cli.js check
+
+  # Compatibility coverage across the rest of the supported range.
+  compat:
+    name: compat (node ${{ matrix.node }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: ['18', '22']
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+
+  coverage:
+    name: coverage gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: '22'
+          cache: npm
+      - run: npm ci
+      # Thresholds (lines/branches/functions) live in package.json's test:coverage
+      # script; the --test-coverage-* flags fail the run when coverage drops below them.
+      - run: npm run test:coverage

.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+
+# Tag-driven release: push a SemVer tag (e.g. v0.4.0) to publish.
+#   npm version patch|minor|major   # bumps package.json + creates the tag
+#   git push --follow-tags
+# Requires repo secret NPM_TOKEN (an npm automation token).
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # create the GitHub Release
+      id-token: write    # npm provenance (--provenance)
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: npm
+
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+
+      # Fail early if the tag doesn't match the version in package.json.
+      - name: Verify tag matches package.json version
+        run: |
+          PKG="v$(node -p "require('./package.json').version")"
+          if [ "$PKG" != "${GITHUB_REF_NAME}" ]; then
+            echo "tag ${GITHUB_REF_NAME} != package.json ${PKG}" >&2
+            exit 1
+          fi
+
+      - name: Extract this version's changelog section
+        run: node .github/scripts/changelog-section.mjs "${GITHUB_REF_NAME#v}" > RELEASE_NOTES.md
+
+      - name: Publish to npm with provenance
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@c95fe1489396fe8a9eb87c0abf8aa5b2ef267fda # v2.2.1
+        with:
+          body_path: RELEASE_NOTES.md
+          fail_on_unmatched_files: true

.skillgate/done.yaml

@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/renezander030/skillgate/master/schema/done.schema.json
 # skillgate gates its own repo (dogfood). Run: npx skillgate check
 name: skillgate-self
 finishLine:

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+### Added
+- Optional `version:` field in `done.yaml` for spec-format compatibility: an older skillgate meeting a newer spec now warns instead of silently misreading gates (`SPEC_VERSION` exported from `spec.ts`).
+- JSON Schema at `schema/done.schema.json`; generated and example specs carry a `# yaml-language-server:` modeline for editor autocomplete and validation. Schema ships in the npm package.
+- `docs/`: quickstart, spec reference, recipes, architecture, and a compatibility/deprecation policy (including the documented exit-code contract).
+- Community health files: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, issue templates, and a pull-request template.
+- Tag-driven release workflow (`npm publish --provenance` + GitHub Release from the CHANGELOG section).
+- `test/e2e.test.ts`: the CLI is now covered end-to-end as a real process; `test/spec.test.ts` covers spec loading and versioning.
+
+### Changed
+- CI runs a Node 18/20/22 matrix, pins all actions to commit SHAs, and enforces coverage thresholds via `npm run test:coverage`.
+- Added Dependabot for npm and GitHub Actions.
+
 ## 0.3.0
 
 ### Added

CODE_OF_CONDUCT.md

@@ -0,0 +1,57 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards and
+will take appropriate and fair corrective action in response to any behavior
+that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer at renezander030@gmail.com. All complaints
+will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+[homepage]: https://www.contributor-covenant.org