chore(release): v0.3.0

.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "adr-toolkit",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Initialize, record, and check Architecture Decision Records by inspecting the repository and existing decisions before asking questions."
 }

.githooks/pre-push

@@ -0,0 +1,17 @@
+#!/bin/bash
+# .githooks/pre-push
+# Prevents direct git push to protected branches (develop, master)
+
+protected_branches="^(develop|master)$"
+
+while read local_ref local_oid remote_ref remote_oid; do
+    target_branch="${remote_ref#refs/heads/}"
+
+    if [[ "$target_branch" =~ $protected_branches ]]; then
+        echo "❌ [Direct Push Blocked] '$target_branch' 브랜치로 직접 push하는 것은 금지되어 있습니다."
+        echo "   반드시 feature/* 또는 fix/* 브랜치에서 PR(Pull Request)을 올려 병합하세요!"
+        exit 1
+    fi
+done
+
+exit 0

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,7 +1,22 @@
+## PR Title Format
+
+Please ensure your PR title follows Conventional Commits format:
+`type(scope): description` (e.g. `feat(cli): add discover command`, `fix(check): fix unicode path matching`)
+
+Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`
+
+---
+
 ## Summary
 
 - 
 
+## Examples Impact (Mandatory for `feat:` and `fix:`)
+
+- [ ] `feat:` or `fix:` PR: I updated/added `examples/` and `examples/ko/` guides.
+- [ ] I verified examples execution via `python3 scripts/verify_examples.py --check`.
+- [ ] Non-feature change (`docs:`, `chore:`, `ci:`): No example changes needed.
+
 ## ADR Impact
 
 - [ ] I checked whether this changes an accepted architectural decision.
@@ -13,6 +28,7 @@ Related ADRs:
 ## Verification
 
 - [ ] `python3 -m pytest -q`
+- [ ] `python3 scripts/verify_examples.py --check`
 - [ ] `python3 scripts/sync_version.py --check`
 - [ ] `python3 skills/adr-toolkit/scripts/adr.py validate --dir docs/decisions --json`
 - [ ] `python3 skills/adr-toolkit/scripts/adr.py index --dir docs/decisions --json`

.github/workflows/release.yml

@@ -15,8 +15,17 @@ jobs:
     runs-on: ubuntu-latest
     # softprops/action-gh-release needs write access to create the release;
     # the default GITHUB_TOKEN is read-only for repos created since Feb 2023.
+    # attest-build-provenance needs id-token (to mint an OIDC token for
+    # Sigstore's keyless signing) and attestations: write (to publish the
+    # resulting attestation to the repo) -- no private key to manage or
+    # rotate; every install/consumption path here references the git repo
+    # or this packaged skill folder directly (docs/adr-toolkit-audit-report.md
+    # §2.2 2.2), so provenance tied to the exact commit is what actually
+    # matters, not a signed build of something nobody downloads separately.
     permissions:
       contents: write
+      id-token: write
+      attestations: write
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
@@ -32,7 +41,23 @@ jobs:
         run: |
           test "v$(cat skills/adr-toolkit/VERSION)" = "$GITHUB_REF_NAME" \
             || { echo "tag $GITHUB_REF_NAME != v$(cat skills/adr-toolkit/VERSION)"; exit 1; }
+      - name: Package the distributable skill
+        id: package
+        run: |
+          set -euo pipefail
+          VERSION="$(cat skills/adr-toolkit/VERSION)"
+          ARCHIVE="adr-toolkit-skill-v${VERSION}.tar.gz"
+          tar -czf "$ARCHIVE" -C skills adr-toolkit
+          sha256sum "$ARCHIVE" > "${ARCHIVE}.sha256"
+          echo "archive=$ARCHIVE" >> "$GITHUB_OUTPUT"
+      - name: Generate build provenance attestation
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: ${{ steps.package.outputs.archive }}
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
           generate_release_notes: true
+          files: |
+            ${{ steps.package.outputs.archive }}
+            ${{ steps.package.outputs.archive }}.sha256

.github/workflows/test.yml

@@ -29,9 +29,26 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
-        run: pip install pytest
+        run: pip install pytest pytest-cov
       - name: Run tests
-        run: python -m pytest tests/unit tests/integration -v
+        run: python -m pytest tests/unit tests/integration -v --cov=skills/adr-toolkit/scripts --cov-branch --cov-report=term-missing --cov-fail-under=85
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install mypy
+        run: pip install mypy
+      - name: Type-check the fully-typed core modules
+        run: >-
+          mypy
+          skills/adr-toolkit/scripts/core/atomic_io.py
+          skills/adr-toolkit/scripts/core/telemetry.py
+          skills/adr-toolkit/scripts/core/contracts.py
+          --strict
 
   version-drift:
     runs-on: ubuntu-latest
@@ -43,6 +60,32 @@ jobs:
       - name: Check manifest versions and descriptions are in sync
         run: python scripts/sync_version.py --check
 
+  examples-drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Verify examples workflows execution and parity
+        run: python scripts/verify_examples.py --check
+
+  pr-title-check:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate PR Title Conventional Commits Format
+        run: |
+          TITLE="${{ github.event.pull_request.title }}"
+          echo "Checking PR Title: $TITLE"
+          REGEX="^(feat|fix|docs|style|refactor|perf|test|chore|ci)(\([a-z0-9-]+\))?!?: .+"
+          if [[ ! "$TITLE" =~ $REGEX ]]; then
+            echo "❌ PR Title does not match Conventional Commits format."
+            echo "Expected format: type(scope): description (e.g. feat(cli): add discover command)"
+            exit 1
+          fi
+          echo "✓ PR Title matches Conventional Commits format."
+
   harness-parity:
     # Installs the real Codex CLI and Gemini CLI and drives their own plugin
     # commands against this repo, the same way a contributor would. Manifest

.gitignore

@@ -35,3 +35,7 @@ adapters/antigravity/skills/adr-toolkit
 # docs/superpowers/specs/ (the design docs) stay tracked; only plans/ is
 # excluded. History from before this commit still has them if ever needed.
 docs/superpowers/plans/
+
+# Cross-process mutex file created by core/atomic_io.py's directory lock
+# during create/exception/supersede -- a runtime artifact, not source.
+.adr-toolkit.lock

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: local
+    hooks:
+      - id: sync-version-check
+        name: sync-version-check
+        entry: python3 scripts/sync_version.py --check
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: pytest-unit
+        name: pytest-unit
+        entry: python3 -m pytest tests/unit -q
+        language: system
+        pass_filenames: false
+        always_run: true

CONTRIBUTING.md

@@ -14,7 +14,7 @@ Follow the repository policy in `AGENTS.md`.
 - Release branches merge to `master` and back to `develop`.
 - Tags named `v*` are created only from `master`.
 
-## Local Checks
+## Local Checks & Pre-Commit
 
 Run the relevant checks before opening a pull request:
 
@@ -25,6 +25,19 @@ python3 skills/adr-toolkit/scripts/adr.py validate --dir docs/decisions --json
 python3 skills/adr-toolkit/scripts/adr.py index --dir docs/decisions --json
 ```
 
+You can also install the local pre-commit hook to run these checks automatically before committing:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+### Plugin Adapters & Manifest Governance
+
+If you add or modify a harness adapter (e.g. under `adapters/` or `.claude-plugin/`):
+- Every `plugin.json` or `gemini-extension.json` must be registered in `MANIFEST_SPECS` and `DESCRIPTION_MANIFEST_SPECS` in `scripts/sync_version.py`.
+- `python3 scripts/sync_version.py --check` will fail in CI if an untracked or out-of-sync manifest file is added.
+
 For changes that may affect accepted architectural decisions, also run:
 
 ```bash
@@ -41,6 +54,19 @@ python3 skills/adr-toolkit/scripts/adr.py check --uncommitted --dir docs/decisio
 - Accepted ADRs are append-only in spirit: use supersession for changed
   decisions instead of rewriting history.
 
+## `constraints:` Block Review
+
+An ADR's `constraints:` block is enforced by `adr.py check` against every
+future diff, so a change to one is a change to the repository's policy
+surface, not just prose. Until CODEOWNERS-backed independent review is
+active (see "Public Repository Hygiene" below), a PR that adds or edits a
+`constraints:` block requires sign-off from someone with authority over
+the affected `affected_paths`, in addition to normal review. This is a
+process control, not a code sandbox -- see
+`docs/adr-toolkit-audit-report.md` §2.2 2.1 for why isolation isn't the
+right defense here (no third-party code executes; the block is
+structured policy text).
+
 ## Public Repository Hygiene
 
 Public repository branch/tag protection is expected to enforce PRs, required

SECURITY.md

@@ -18,6 +18,35 @@ public issue. Include:
 Do not include exploit details in a public issue until a fix or mitigation is
 available.
 
+## Verifying a Release
+
+Every `v*` release is built by `.github/workflows/release.yml` from a
+tagged commit, and the workflow publishes a [GitHub Artifact
+Attestation](https://docs.github.com/en/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds)
+for the packaged skill archive it attaches to the release
+(`adr-toolkit-skill-vX.Y.Z.tar.gz`). This is a Sigstore-backed, keyless
+signature -- no private key is held or rotated by this project -- proving
+the archive was produced by this repository's own CI, from the exact
+commit the release tag points to.
+
+To verify a downloaded archive:
+
+```bash
+# Checksum: confirms the file wasn't corrupted/tampered with in transit
+sha256sum -c adr-toolkit-skill-vX.Y.Z.tar.gz.sha256
+
+# Provenance: confirms the archive was actually built by this repo's CI,
+# not a look-alike release from a compromised account or a different repo
+gh attestation verify adr-toolkit-skill-vX.Y.Z.tar.gz -R SHcommit/ADR-toolkit
+```
+
+Anyone consuming this repository directly (`git clone`, or an adapter's
+`marketplace add`/`plugin add` pointing at the repo, which is how every
+adapter installs this skill today) is verifying via Git/GitHub's own
+commit and tag history rather than this archive -- the attestation is
+primarily for the one path where a bare checkout doesn't happen: someone
+who downloads the release archive off the GitHub Releases page directly.
+
 ## Scope
 
 In scope:

adapters/antigravity/README.md

@@ -2,7 +2,8 @@
 
 Antigravity plugins are a `plugin.json` marker file plus optional sibling
 directories (`skills/`, `agents/`, `rules/`), per
-`antigravity.google/docs/cli/plugins/`. This manifest needs only `name`.
+`antigravity.google/docs/cli/plugins/`. This manifest includes `name`,
+`version`, `description`, and `$schema`.
 **Manually verified against Antigravity's `agy` CLI 1.1.13** (`agy
 --version`): validate, install, and discovery all work — see "Verification
 status" below.

adapters/antigravity/plugin.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "adr-toolkit",
+  "version": "0.3.0",
   "description": "Initialize, record, and check Architecture Decision Records by inspecting the repository and existing decisions before asking questions."
 }

adapters/gemini-cli/gemini-extension.json

@@ -1,5 +1,5 @@
 {
   "name": "adr-toolkit",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Initialize, record, and check Architecture Decision Records by inspecting the repository and existing decisions before asking questions."
 }