feat: add Kilo Gastown methodology spec and SAST tooling

.github/RULESET_BASELINE.md

@@ -0,0 +1,43 @@
+# cliproxyapi-plusplus Ruleset Baseline
+
+This repository now has a checked-in baseline that matches the repaired remote `Main` ruleset.
+
+## Enforced Branch Protection Baseline
+
+- require pull requests before merge on the default branch
+- no branch deletion
+- no force push / non-fast-forward updates
+- require at least 1 approval
+- dismiss stale approvals on new push
+- require resolved review threads before merge
+- allow merge methods: `merge`, `squash`
+- enable GitHub `code_quality`
+- enable GitHub `copilot_code_review`
+
+## Repo-Local Governance Gates
+
+The repo-local workflow set remains the main CI and policy contract:
+
+- `policy-gate`
+- `pr-path-guard`
+- `pr-test-build`
+- `required-check-names-guard`
+- `quality-gate`
+- `security-guard`
+- `codeql`
+- `sast-quick`
+- `sast-full`
+
+Current required check manifests:
+
+- `.github/required-checks.txt`
+- `.github/release-required-checks.txt`
+
+Those manifests should drive the next remote ruleset wave once the stable job names are re-verified
+against live workflow output.
+
+## Exception Policy
+
+- only documented billing or quota failures may be excluded from blocking CI evaluation
+- review threads and blocking comments must be resolved before merge
+- PRs must not rely on local `--no-verify` bypasses instead of server-side checks

.github/rulesets/main.json

@@ -0,0 +1,41 @@
+{
+  "name": "Main",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": ["~DEFAULT_BRANCH"],
+      "exclude": []
+    }
+  },
+  "bypass_actors": [],
+  "rules": [
+    { "type": "deletion" },
+    { "type": "non_fast_forward" },
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 1,
+        "dismiss_stale_reviews_on_push": true,
+        "required_reviewers": [],
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": true,
+        "allowed_merge_methods": ["merge", "squash"]
+      }
+    },
+    {
+      "type": "code_quality",
+      "parameters": {
+        "severity": "errors"
+      }
+    },
+    {
+      "type": "copilot_code_review",
+      "parameters": {
+        "review_on_push": true,
+        "review_draft_pull_requests": true
+      }
+    }
+  ]
+}

.github/workflows/ci.yml

@@ -12,7 +12,8 @@ jobs:
       - name: Refresh models catalog
         run: |
           git fetch --depth 1 https://github.com/router-for-me/models.git main
-          git show FETCH_HEAD:models.json > internal/registry/models/models.json
+          mkdir -p pkg/llmproxy/registry/models
+          git show FETCH_HEAD:models.json > pkg/llmproxy/registry/models/models.json
       - uses: actions/setup-go@v5
         with:
           go-version-file: go.mod

.github/workflows/sast-full.yml

@@ -0,0 +1,89 @@
+name: SAST Full Analysis
+
+on:
+  schedule:
+    - cron: "0 2 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  codeql:
+    name: CodeQL Analysis
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      matrix:
+        language: [go, javascript]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+
+  trivy-repo:
+    name: Trivy Repository Scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: aquasecurity/trivy-action@v0.35.0
+        with:
+          scan-type: fs
+          scan-ref: .
+          format: sarif
+          output: trivy-results.sarif
+      - name: Upload Trivy SARIF
+        uses: github/codeql-action/upload-sarif@v4
+        if: always()
+        with:
+          sarif_file: trivy-results.sarif
+          category: trivy
+
+  full-semgrep:
+    name: Full Semgrep Analysis
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install Semgrep
+        run: python -m pip install --disable-pip-version-check semgrep==1.157.0
+      - name: Run Semgrep
+        run: |
+          semgrep scan \
+            --config p/security-audit \
+            --config p/owasp-top-ten \
+            --config p/cwe-top-25 \
+            --error \
+            --sarif \
+            --output semgrep.sarif \
+            .
+
+      - name: Upload SARIF
+        uses: github/codeql-action/upload-sarif@v4
+        if: always()
+        with:
+          sarif_file: semgrep.sarif
+          category: semgrep-full
+
+  full-secrets:
+    name: Full Secret Scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: trufflesecurity/trufflehog@v3.94.2
+        with:
+          path: ./
+          extra_args: --only-verified

.github/workflows/sast-quick.yml

@@ -0,0 +1,91 @@
+name: SAST Quick Check
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  semgrep:
+    name: Semgrep Scan
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install Semgrep
+        run: python -m pip install --disable-pip-version-check semgrep==1.157.0
+      - name: Run Semgrep
+        run: |
+          semgrep scan \
+            --config p/security-audit \
+            --config p/owasp-top-ten \
+            --config p/cwe-top-25 \
+            --error \
+            --sarif \
+            --output semgrep.sarif \
+            .
+
+      - name: Upload SARIF
+        uses: github/codeql-action/upload-sarif@v4
+        if: always()
+        with:
+          sarif_file: semgrep.sarif
+          category: semgrep
+
+  secrets:
+    name: Secret Scanning
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: trufflesecurity/trufflehog@v3.94.2
+        with:
+          path: ./
+          extra_args: --only-verified
+
+  go-quality:
+    name: Go Quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+      - name: Enforce gofmt
+        run: |
+          files=$(git ls-files '*.go')
+          if [ -z "$files" ]; then
+            exit 0
+          fi
+          unformatted=$(gofmt -l $files)
+          if [ -n "$unformatted" ]; then
+            echo "$unformatted"
+            exit 1
+          fi
+      - name: Run go vet
+        run: go vet ./...
+
+  license-check:
+    name: License Compliance
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+      - name: Capture dependency inventory
+        run: |
+          go list -m -f '{{if not .Main}}{{.Path}} {{.Version}}{{end}}' all | sort > license-inventory.txt
+          test -s license-inventory.txt

.github/workflows/security-guard.yml

@@ -1,9 +1,18 @@
-name: security-guard
-on: [workflow_dispatch]
+name: Security Guard
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
 jobs:
-  audit:
+  ggshield-scan:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Run security audit
-        run: echo "Security audit placeholder - no script available yet"
+      - uses: actions/setup-python@v5
+      - name: Install ggshield
+        run: pip install ggshield
+      - name: Run ggshield secret scan
+        env:
+          GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }}
+        run: ggshield secret scan path . --recursive

.semgrep-rules/architecture-violations.yml

@@ -0,0 +1,28 @@
+rules:
+  - id: no-dot-imports
+    pattern: import . "$PKG"
+    message: Dot imports hide call sites and make ownership harder to trace. Use explicit package names.
+    languages: [go]
+    severity: MEDIUM
+
+  - id: no-blank-imports-outside-entrypoints
+    patterns:
+      - pattern: import _ "$PKG"
+    message: Blank imports belong in explicit wiring points only. Move them out of library packages.
+    languages: [go]
+    severity: MEDIUM
+    paths:
+      exclude:
+        - "cmd/**"
+        - "**/*_test.go"
+
+  - id: getenv-in-http-handler
+    patterns:
+      - pattern-inside: |
+          func $HANDLER($W http.ResponseWriter, $R *http.Request) {
+            ...
+          }
+      - pattern: os.Getenv(...)
+    message: Avoid reading process environment directly inside request handlers. Inject configuration instead.
+    languages: [go]
+    severity: LOW

.semgrep-rules/secrets-detection.yml

@@ -0,0 +1,40 @@
+rules:
+  - id: hardcoded-aws-key
+    pattern-regex: AKIA[0-9A-Z]{16}
+    message: Potential AWS Access Key detected. Use environment variables instead.
+    languages: [generic]
+    severity: CRITICAL
+
+  - id: hardcoded-api-key
+    pattern-regex: (?i)(api[_-]?key|token|secret)\s*(?:[:=])\s*["'][^"'\\n]{8,}["']
+    message: Hardcoded API key detected. Use environment variables or secrets management.
+    languages: [generic]
+    severity: HIGH
+    paths:
+      exclude:
+        - "**/*_test.go"
+        - "examples/**"
+        - "test/**"
+
+  - id: hardcoded-password
+    pattern-regex: (?i)(password|passwd|pwd)\s*(?:[:=])\s*["'][^"'\\n]{8,}["']
+    message: Hardcoded password detected. Use environment variables or secrets management.
+    languages: [generic]
+    severity: CRITICAL
+    paths:
+      exclude:
+        - "**/*_test.go"
+        - "examples/**"
+        - "test/**"
+
+  - id: hardcoded-slack-webhook
+    pattern-regex: https://hooks\.slack\.com/services/[A-Za-z0-9/_-]+
+    message: Slack webhook URL detected. This should be in environment variables.
+    languages: [generic]
+    severity: HIGH
+
+  - id: hardcoded-github-token
+    pattern-regex: gh[pousr]_[A-Za-z0-9_]{36,255}
+    message: GitHub token detected. Never commit tokens to code.
+    languages: [generic]
+    severity: CRITICAL

.semgrep-rules/unsafe-patterns.yml

@@ -0,0 +1,26 @@
+rules:
+  - id: shell-command-with-shell
+    patterns:
+      - pattern-either:
+          - pattern: exec.Command("sh", "-c", ...)
+          - pattern: exec.Command("bash", "-c", ...)
+    message: Avoid shell evaluation in exec.Command. Pass explicit argv slices instead.
+    languages: [go]
+    severity: CRITICAL
+
+  - id: sql-query-built-with-sprintf
+    patterns:
+      - pattern: fmt.Sprintf($QUERY, ...)
+      - metavariable-regex:
+          metavariable: $QUERY
+          regex: (?i).*(select|insert|update|delete|from|where).*
+    message: SQL assembled with fmt.Sprintf is injection-prone. Use parameter binding instead.
+    languages: [go]
+    severity: CRITICAL
+
+  - id: direct-http-get-without-timeout
+    patterns:
+      - pattern: http.Get(...)
+    message: http.Get uses the default client without an explicit timeout. Prefer a configured http.Client.
+    languages: [go]
+    severity: LOW