chore(deps-dev): bump @commitlint/config-conventional from 19.8.1 to 21.0.0

.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,54 @@
+---
+name: Bug report
+about: Something doesn't work the way you expect
+title: '[bug] '
+labels: bug
+assignees: ''
+---
+
+## Summary
+
+What happened, in one sentence.
+
+## Reproduction
+
+Minimal steps to reproduce (or a public repo + commit SHA we can clone):
+
+```bash
+# 1.
+# 2.
+# 3.
+```
+
+## Expected vs actual
+
+- **Expected:**
+- **Actual:**
+
+## Environment
+
+- `terrain version --json` output:
+  ```
+  paste here
+  ```
+- OS / arch (e.g. macOS 14.5 arm64):
+- Install method (npm / homebrew / go install / pre-built / source):
+- Terrain config in `.terrain/` (if any):
+
+## Logs
+
+If the bug surfaces an error, paste the full stderr + the output of
+re-running with `--log-level=debug`:
+
+<details>
+<summary>Debug output</summary>
+
+```
+paste here
+```
+
+</details>
+
+## Anything else
+
+Screenshots, profiler output, hypotheses, related issues, etc.

.github/ISSUE_TEMPLATE/false-positive.md

@@ -0,0 +1,53 @@
+---
+name: False positive
+about: A detector fired but the underlying code is fine
+title: '[fp] '
+labels: false-positive, calibration
+assignees: ''
+---
+
+Detector false positives directly affect calibration (precision). The
+more concrete the reproduction, the easier it is to add a labeled
+fixture under `tests/calibration/` so the regression doesn't come back.
+
+## Detector
+
+Type the exact signal type as it appears in `terrain analyze --json`
+(e.g. `aiToolWithoutSandbox`, `weakAssertion`).
+
+## Code that triggered the finding
+
+The minimal source / config snippet that caused the detector to fire,
+with surrounding context preserved:
+
+```yaml
+# or .py / .ts / .go etc.
+paste here
+```
+
+## Why this isn't actually a problem
+
+In one or two sentences, why this code is fine despite matching the
+detector's pattern. Example: "`delete_cache` is a request-scoped LRU
+clear, not a destructive data operation."
+
+## Detector output
+
+The full signal as it appears in `--json` output:
+
+```json
+paste here
+```
+
+## Suggested fix shape
+
+If you have a sense for what would close this — a noun whitelist
+expansion, a confidence downgrade, a path-shape exclusion — name it.
+The maintainers will translate the suggestion into a concrete
+detector change.
+
+## Calibration corpus opt-in
+
+If you can share the snippet under an open-source license, would you
+be willing to have it added to `tests/calibration/<detector>/` with
+`expectedAbsent: <signal>` so this regression is locked out? Yes/no.

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,33 @@
+---
+name: Feature request
+about: A capability you'd like Terrain to have
+title: '[feat] '
+labels: enhancement
+assignees: ''
+---
+
+## What you want to do
+
+The user-facing problem, framed as a job-to-be-done. Avoid jumping to
+implementation; lead with the outcome.
+
+## Why today's Terrain doesn't get you there
+
+Which specific commands / signals / outputs you've tried, and where
+they fall short. If a workaround exists, describe it briefly.
+
+## What "done" looks like
+
+Concrete success criteria. Could be a CLI shape, a JSON field, a
+report section, a CI gate. The more specific, the easier to scope.
+
+## Connections to existing work
+
+Related issues / PRs / feature-status entries / known-gaps items.
+Linking saves the maintainers a search.
+
+## Optional: implementation hint
+
+If you know the codebase, where you think the change goes (e.g. "new
+detector under `internal/aidetect/`", "new flag on `terrain analyze`,
+parsed in `cmd/terrain/cmd_analyze.go`"). Skip if you don't.

.github/pull_request_template.md

@@ -14,12 +14,12 @@ but specific.
 
 <!-- Check all that apply. -->
 
-- [ ] Bug fix (no behaviour change beyond the fix)
-- [ ] New feature (additive only — no changes to existing behaviour)
-- [ ] Breaking change (alters existing behaviour, schema, CLI, or output shape)
+- [ ] Bug fix (no behavior change beyond the fix)
+- [ ] New feature (additive only — no changes to existing behavior)
+- [ ] Breaking change (alters existing behavior, schema, CLI, or output shape)
 - [ ] Documentation only
 - [ ] Test or tooling only
-- [ ] Refactor (behaviour-preserving)
+- [ ] Refactor (behavior-preserving)
 
 ## Reviewer checklist
 
@@ -61,5 +61,5 @@ note. If unsure, see docs/schema/COMPAT.md for the contract.
 <!--
 - [ ] Smoke-tested locally with: ...
 - [ ] Added unit / integration tests for: ...
-- [ ] Regression-tested existing behaviour for: ...
+- [ ] Regression-tested existing behavior for: ...
 -->

.github/workflows/ci.yml

@@ -6,12 +6,24 @@ on:
   pull_request:
     branches: [main]
 
+# Cancel in-progress CI runs when a new commit is pushed to the same
+# PR / branch. Pre-0.2.x final-polish, force-pushes piled up
+# overlapping runs that all consumed runner minutes pointlessly.
+# `cancel-in-progress: true` on PR-triggered runs keeps the queue
+# clean; we leave main-branch runs uncancelled so post-merge runs
+# always complete (they're rare and the result is load-bearing for
+# release dashboards).
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 permissions:
   contents: read
 
 jobs:
   npm-package:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
 
     steps:
       - name: Checkout repository
@@ -66,6 +78,7 @@ jobs:
           - os: windows-latest
             extended: false
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
 
     steps:
       - name: Checkout repository
@@ -84,6 +97,13 @@ jobs:
           go mod tidy
           git diff --exit-code go.mod go.sum
 
+      - name: Verify generated docs are up to date
+        if: matrix.extended
+        # Hard-fail gate (carries the 0.1.2 manifest scaffold to enforcement
+        # in 0.2). If you edit internal/signals/manifest.go, run
+        # `make docs-gen` and commit docs/signals/manifest.json.
+        run: make docs-verify
+
       - name: Run core Go verification
         if: matrix.extended
         run: make go-release-verify
@@ -150,6 +170,7 @@ jobs:
 
   extension:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
 
     steps:
       - name: Checkout repository
@@ -169,6 +190,7 @@ jobs:
   go-bench-compare:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
+    timeout-minutes: 30
 
     steps:
       - name: Checkout repository
@@ -204,12 +226,30 @@ jobs:
           git checkout "${{ github.sha }}"
           "$(go env GOPATH)/bin/benchstat" /tmp/bench_base.txt /tmp/bench_head.txt | tee /tmp/benchstat.txt
 
-      - name: Append benchstat summary
+      - name: Regression gate (>10% fails the job)
+        # Carries the round-4 review's "perf regression suite establishes
+        # baseline" finding into a hard-fail gate. The gate parses the same
+        # benchmark output benchstat consumed, computes per-bench delta,
+        # and fails if any benchmark regressed beyond the threshold.
+        run: |
+          go run ./cmd/terrain-bench-gate \
+            --base /tmp/bench_base.txt \
+            --head /tmp/bench_head.txt \
+            --threshold 10 | tee /tmp/bench-gate.txt
+
+      - name: Append summary
+        if: always()
         run: |
           {
             echo '### Go Benchmark Comparison (base vs head)'
             echo ''
             echo '```'
             cat /tmp/benchstat.txt
             echo '```'
+            echo ''
+            echo '### Regression gate (>10% threshold)'
+            echo ''
+            echo '```'
+            cat /tmp/bench-gate.txt 2>/dev/null || echo "(gate did not run)"
+            echo '```'
           } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/codeql.yml

@@ -8,18 +8,28 @@ on:
   schedule:
     - cron: '0 6 * * 1' # weekly Monday 6am UTC
 
+concurrency:
+  group: codeql-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 permissions:
   security-events: write
   contents: read
 
 jobs:
   analyze:
     runs-on: ubuntu-latest
+    timeout-minutes: 30
 
     strategy:
       fail-fast: false
+      # 0.2.0 final-polish: dropped `python` from the language matrix.
+      # The repo has only a handful of Python helper scripts (no
+      # production Python under analysis); CodeQL Python autobuild was
+      # spending ~5 min/week with effectively no coverage. Re-add when
+      # the engine itself analyses Python source.
       matrix:
-        language: [go, javascript-typescript, python]
+        language: [go, javascript-typescript]
 
     steps:
       - name: Checkout repository

.github/workflows/homebrew-update.yml

@@ -0,0 +1,90 @@
+name: homebrew-update
+
+# Updates the source-build formula in pmclSF/homebrew-terrain to point at
+# the source tarball for a given tag. The existing formula is source-build
+# (downloads refs/tags/<tag>.tar.gz and runs `go build`), so we just need
+# the version and the tarball SHA256 — goreleaser is not involved.
+#
+# Triggers automatically when a v* tag is pushed AND when a release is
+# published (so it runs after the main release workflow finishes), and
+# also on manual workflow_dispatch as a recovery path.
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag (e.g. v0.1.2)'
+        required: true
+        type: string
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  update-formula:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve tag
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            TAG="${{ inputs.tag }}"
+          else
+            TAG="${{ github.event.release.tag_name }}"
+          fi
+          VERSION="${TAG#v}"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Updating brew formula for $TAG (version $VERSION)"
+
+      - name: Compute source tarball SHA256
+        id: sha
+        run: |
+          TAG="${{ steps.tag.outputs.tag }}"
+          URL="https://github.com/pmclSF/terrain/archive/refs/tags/${TAG}.tar.gz"
+          curl --fail --location --silent --show-error -o /tmp/source.tar.gz "$URL"
+          SHA=$(sha256sum /tmp/source.tar.gz | awk '{print $1}')
+          echo "sha=$SHA" >> "$GITHUB_OUTPUT"
+          echo "SHA256: $SHA"
+
+      - name: Check out homebrew tap
+        uses: actions/checkout@v6
+        with:
+          repository: pmclSF/homebrew-terrain
+          token: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}
+          path: tap
+
+      - name: Update Formula/mapterrain.rb
+        run: |
+          set -euo pipefail
+          TAG="${{ steps.tag.outputs.tag }}"
+          SHA="${{ steps.sha.outputs.sha }}"
+          FORMULA=tap/Formula/mapterrain.rb
+
+          # Replace the url line (matches refs/tags/<tag>.tar.gz suffix).
+          sed -i -E "s|refs/tags/v[0-9.]+\.tar\.gz|refs/tags/${TAG}.tar.gz|" "$FORMULA"
+          # Replace the sha256 line (the first one, since the formula has only
+          # one url/sha256 pair).
+          sed -i -E "0,/sha256 \"[a-f0-9]+\"/{s|sha256 \"[a-f0-9]+\"|sha256 \"${SHA}\"|}" "$FORMULA"
+
+          echo "=== Updated formula ==="
+          cat "$FORMULA"
+
+      - name: Commit + push formula update
+        working-directory: tap
+        run: |
+          set -euo pipefail
+          TAG="${{ steps.tag.outputs.tag }}"
+
+          if git diff --quiet; then
+            echo "Formula already up-to-date for $TAG; nothing to commit."
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add Formula/mapterrain.rb
+          git commit -m "mapterrain ${TAG}"
+          git push origin main