@karajan-family/code 4.21.0

package/templates/skills/kj-rag-query.md

@@ -0,0 +1,50 @@
+# kj-rag-query — Query Project RAG index
+
+Query the Project RAG (vector store + embedder) and return the top-K most relevant chunks of the indexed project: plans, onboarding briefs, and (optionally) source code.
+
+Use this when you need prior context about the project before deciding, refactoring, planning, or coding — without scanning the filesystem manually.
+
+## Your task
+
+$ARGUMENTS
+
+## How it works
+
+This skill is a thin wrapper over the Karajan CLI:
+
+```
+kj rag query "<text>" [--scope <all|plans|onboarding|code>] [--top-k <n>] [--json]
+```
+
+Parse `$ARGUMENTS` as the natural-language query plus optional flags:
+
+- `--scope <s>`: restrict retrieval to one source bucket. Default: `all`.
+  - `plans` → indexed plan JSON files (HU titles, scope, blocked_by).
+  - `onboarding` → onboarding briefs from `~/.karajan/onboarding/`.
+  - `code` → indexed source files (only present if user ran `kj rag index --with-sources`).
+- `--top-k <n>`: number of chunks to return. Default: 3. Max recommended: 10.
+- `--json`: emit raw JSON (use when piping into another tool).
+
+If `$ARGUMENTS` is empty, print a one-line usage hint and stop.
+
+## Behavior contract
+
+1. **Empty store**: if the CLI replies with `empty: true`, do NOT block the conversation. Tell the user once: "RAG index is empty — run `kj rag index` to seed it" and continue without prior context.
+2. **Zero hits**: if the store has chunks but no match scored above threshold, say "no relevant prior context" and continue.
+3. **Hits returned**: render each as a short block — `[score] source — snippet` — and use them as background context for the user's actual question. Do NOT dump raw JSON unless `--json` was passed.
+4. **Never re-validate flags**. Pass `--scope`/`--top-k` straight to the CLI; the CLI is the source of truth.
+
+## Examples
+
+User: `/kj-rag-query how does the retriever rank chunks`
+→ `kj rag query "how does the retriever rank chunks"`
+
+User: `/kj-rag-query auth flow --scope plans --top-k 5`
+→ `kj rag query "auth flow" --scope plans --top-k 5`
+
+User: `/kj-rag-query --scope onboarding architecture`
+→ `kj rag query "architecture" --scope onboarding`
+
+## Why this exists (Camino B)
+
+Hosts that load Karajan as Skills (Claude Code without MCP, Cursor without MCP) cannot reach the `kj_rag_query` MCP tool. This skill bridges that gap with the same retrieval contract.

package/templates/skills/kj-review.md

@@ -0,0 +1,47 @@
+# kj-review — Code Review with Quality Gates
+
+Review the current changes against task requirements and quality standards.
+
+## Your task
+
+Review the changes in the current branch: $ARGUMENTS
+
+## Steps
+
+1. Run `git diff main...HEAD` (or appropriate base branch) to see all changes
+2. Review each changed file against the priorities below
+3. Report findings clearly
+
+## Review priorities (in order)
+
+1. **Security** — vulnerabilities, exposed secrets, injection vectors
+2. **Correctness** — logic errors, edge cases, broken tests
+3. **Tests** — adequate coverage, meaningful assertions
+4. **Architecture** — patterns, maintainability, SOLID principles
+5. **Style** — naming, formatting (only flag if egregious)
+
+## Scope constraint
+
+- **ONLY review files present in the diff** — do not flag issues in untouched files
+- Out-of-scope issues go as suggestions, never as blocking
+
+## Guardrails (auto-check)
+
+Flag as BLOCKING if any of these are detected in the diff:
+- [ ] Hardcoded credentials, API keys, or secrets
+- [ ] Entire file replaced (massive deletions + additions instead of targeted edits)
+- [ ] `eval()`, `innerHTML` with user input, SQL string concatenation
+- [ ] Missing test changes when source files changed (TDD violation)
+- [ ] `rm -rf`, `DROP TABLE`, `git push --force` or similar destructive operations
+
+## Output
+
+For each issue found:
+- **File and line** where the issue is
+- **Severity**: critical / major / minor
+- **Description**: what's wrong
+- **Suggested fix**: how to fix it
+
+End with a clear verdict:
+- **APPROVED** — no blocking issues found
+- **REQUEST_CHANGES** — blocking issues listed above must be fixed

package/templates/skills/kj-run.md

@@ -0,0 +1,73 @@
+# kj-run — Full Pipeline (Skills Mode)
+
+Execute the complete Karajan pipeline as sequential skills.
+
+## Your task
+
+$ARGUMENTS
+
+## Pipeline steps (execute in order)
+
+### Step 1 — Discover (optional but recommended)
+Analyze the task for gaps before coding:
+- Identify missing requirements, ambiguities, contradictions
+- If critical gaps found, STOP and ask the user before proceeding
+- If ready, continue
+
+### Step 2 — Code (with guardrails)
+Implement the task:
+1. **Tests first** (TDD): write/update tests before implementation
+2. **Implement**: minimal, focused code to fulfill the task
+3. **Verify**: run the test suite
+4. **Security check**: no hardcoded secrets, no injection vectors, no destructive ops in the diff
+5. **Diff check**: run `git diff` and verify only intended lines changed
+6. If any guardrail fails, fix before proceeding
+
+### Step 3 — Review (self-review)
+Review your own changes against quality standards:
+1. Run `git diff main...HEAD` (or base branch)
+2. Check: security, correctness, tests, architecture, style (in that order)
+3. Flag blocking issues:
+   - Hardcoded credentials or secrets
+   - Entire files overwritten instead of targeted edits
+   - Missing tests for new code
+   - SQL injection, XSS, command injection
+   - Destructive operations
+4. If blocking issues found, fix them and re-review
+5. If clean, proceed
+
+### Step 4 — Test audit
+Verify test quality:
+1. Every changed source file has corresponding tests
+2. Run `npm test` (or equivalent) — all must pass
+3. No skipped tests for changed code
+4. If tests fail, fix before proceeding
+
+### Step 5 — Security scan
+Quick security audit on the diff:
+1. Scan for OWASP top 10 in changed files
+2. Check for leaked secrets, injection vectors, missing auth
+3. If critical/high findings, fix before proceeding
+
+### Step 6 — Sonar (if available)
+If SonarQube is running (`docker ps | grep sonarqube`):
+1. Run `npx @sonar/scan`
+2. Check quality gate
+3. Fix blockers and critical issues
+
+### Step 7 — Commit
+If all steps pass:
+1. Stage changed files: `git add <specific files>`
+2. Commit with conventional commit message: `feat:`, `fix:`, `refactor:`, etc.
+3. Do NOT push unless the user explicitly asks
+
+## HU Board Integration
+If HU Board is enabled (`hu_board.enabled: true` in config), stories and sessions
+are automatically tracked and visible at the board URL. Run `kj board` to start it.
+
+## Important rules
+
+- **Never skip steps** — execute all applicable steps in order
+- **Fix before proceeding** — if a step finds issues, fix them before moving to the next
+- **Report progress** — after each step, briefly state what was done and the result
+- **Stop on critical** — if a critical security or correctness issue can't be fixed, stop and report

package/templates/skills/kj-security.md

@@ -0,0 +1,49 @@
+# kj-security — Security Audit
+
+Perform a security audit on the current changes.
+
+## Your task
+
+$ARGUMENTS
+
+## Steps
+
+1. Run `git diff main...HEAD` to see all changes
+2. Scan for each vulnerability category below
+3. Report findings with severity and remediation
+
+## Vulnerability categories
+
+### Critical
+- [ ] Hardcoded secrets (API keys, passwords, tokens, connection strings)
+- [ ] SQL injection (string concatenation in queries)
+- [ ] Command injection (`exec`, `spawn` with unsanitized input)
+- [ ] Path traversal (file operations with user-controlled paths)
+
+### High
+- [ ] XSS (Cross-Site Scripting) — `innerHTML`, `dangerouslySetInnerHTML` with user input
+- [ ] Missing authentication/authorization checks on new endpoints
+- [ ] Insecure deserialization
+- [ ] SSRF (Server-Side Request Forgery) — fetch/request with user-controlled URLs
+
+### Medium
+- [ ] Missing input validation at system boundaries
+- [ ] Verbose error messages that leak internal details
+- [ ] Missing CSRF protection on state-changing endpoints
+- [ ] Insecure random number generation for security purposes
+
+### Low
+- [ ] Missing security headers
+- [ ] Dependencies with known vulnerabilities (check `npm audit`)
+- [ ] Console.log with sensitive data
+
+## Output
+
+For each finding:
+- **Severity**: critical / high / medium / low
+- **File and line**: where the issue is
+- **Category**: which vulnerability type
+- **Description**: what's wrong
+- **Remediation**: specific fix
+
+End with a summary: total findings by severity, and whether the code is safe to ship.

package/templates/skills/kj-sonar.md

@@ -0,0 +1,41 @@
+# kj-sonar — Static Analysis
+
+Run SonarQube/SonarCloud analysis and fix any issues found.
+
+## Your task
+
+$ARGUMENTS
+
+## Steps
+
+1. Check if SonarQube is running: `docker ps | grep sonarqube`
+2. If running, execute scan:
+   ```bash
+   npx @sonar/scan -Dsonar.host.url=http://localhost:9000 -Dsonar.projectKey=<project-key>
+   ```
+3. Check quality gate status:
+   ```bash
+   curl -s -u admin:admin "http://localhost:9000/api/qualitygates/project_status?projectKey=<project-key>"
+   ```
+4. List issues:
+   ```bash
+   curl -s -u admin:admin "http://localhost:9000/api/issues/search?projectKeys=<project-key>&statuses=OPEN&ps=50"
+   ```
+
+## If SonarQube is not available
+
+Perform manual static analysis checks:
+- [ ] Cognitive complexity — functions over 15 should be refactored
+- [ ] Duplicated code blocks (3+ lines repeated)
+- [ ] Unused imports and variables
+- [ ] Empty catch blocks without comments
+- [ ] Nested ternary operations
+- [ ] `console.log` left in production code
+
+## Output
+
+Report:
+- Quality gate status (passed/failed)
+- Issues found by severity (blocker, critical, major, minor)
+- For each issue: file, line, rule, and suggested fix
+- Fix critical and blocker issues before proceeding

package/templates/skills/kj-sql-analysis.md

@@ -0,0 +1,40 @@
+# kj-sql-analysis — SQL Analysis & Generation
+
+Generate and review SQL queries with a focus on correctness, performance, and security.
+
+## Your task
+
+$ARGUMENTS
+
+## Coder instructions
+
+When writing or modifying SQL queries:
+
+1. **Parameterized queries only** — never concatenate user input into SQL strings. Use prepared statements or parameterized queries (`$1`, `?`, `:param`) to prevent injection.
+2. **Comment complex logic** — add inline comments explaining non-obvious JOINs, subqueries, CTEs, and window functions.
+3. **Validate against schema** — if a schema or migration files are available, verify that table names, column names, and types match the actual schema.
+4. **Prefer explicit column lists** — avoid `SELECT *`; list the columns you need.
+5. **Use aliases consistently** — when joining multiple tables, alias every table and prefix all column references.
+6. **Index-aware queries** — structure WHERE clauses and JOINs to leverage existing indexes. Avoid wrapping indexed columns in functions.
+7. **Limit result sets** — add `LIMIT` / `TOP` for queries that could return unbounded rows unless the full result is explicitly needed.
+8. **Handle NULLs explicitly** — use `COALESCE`, `IS NULL`, or `IS NOT NULL` where NULL values could affect logic.
+
+## Reviewer checklist
+
+When reviewing SQL-related code, check for:
+
+- [ ] **Injection risk** — any string concatenation or template literals building SQL?
+- [ ] **N+1 queries** — loops executing individual queries instead of a single batch/join?
+- [ ] **Missing indexes** — queries filtering or joining on columns without indexes?
+- [ ] **Correct JOINs** — LEFT vs INNER vs CROSS used intentionally? Accidental cartesian products?
+- [ ] **Transaction safety** — multi-statement operations wrapped in transactions where needed?
+- [ ] **Schema alignment** — column names, types, and constraints match the current schema?
+- [ ] **Performance** — unnecessary subqueries that could be CTEs or JOINs? Missing LIMIT on large tables?
+- [ ] **NULL handling** — aggregations, comparisons, and JOINs account for NULL values?
+
+## Output
+
+Provide the SQL queries with:
+- Inline comments for complex sections
+- Explanation of the query plan and expected performance characteristics
+- Any schema changes needed (new indexes, columns, tables)

package/templates/skills/kj-test.md

@@ -0,0 +1,40 @@
+# kj-test — Test Quality Audit
+
+Evaluate test coverage and quality for the current changes.
+
+## Your task
+
+$ARGUMENTS
+
+## Steps
+
+1. Run `git diff main...HEAD` to identify changed source files
+2. For each changed source file, find the corresponding test file
+3. Run the test suite and check results
+4. Evaluate test quality
+
+## Checks
+
+### Coverage
+- [ ] Every changed source file has a corresponding test file
+- [ ] New functions/methods have at least one test
+- [ ] Edge cases are covered (null, empty, boundary values)
+
+### Quality
+- [ ] Tests have meaningful assertions (not just "no error thrown")
+- [ ] Test descriptions clearly state what is being tested
+- [ ] No tests that always pass (e.g., empty test body, `expect(true).toBe(true)`)
+- [ ] Mocks are minimal — prefer real implementations where feasible
+
+### Execution
+- [ ] Run `npm test` (or project equivalent) and report results
+- [ ] All tests pass
+- [ ] No skipped tests (`.skip`) for the changed code
+
+## Output
+
+Report:
+- Test files found/missing for each changed source file
+- Test execution results (pass/fail count)
+- Quality issues found
+- Suggestions for improving coverage

package/templates/workflows/automerge.yml

@@ -0,0 +1,30 @@
+# Auto-merge PRs approved by Karajan CI reviewer.
+# Merges when kj-reviewer[bot] approves and all checks pass.
+
+name: Auto-merge (Karajan CI)
+
+on:
+  pull_request_review:
+    types: [submitted]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  automerge:
+    if: >
+      github.event.review.state == 'approved' &&
+      contains(github.event.review.user.login, 'kj-reviewer')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enable auto-merge
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.pulls.merge({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.payload.pull_request.number,
+              merge_method: 'squash'
+            });

package/templates/workflows/houston-override.yml

@@ -0,0 +1,46 @@
+# Houston Override — allows a human to force-approve a PR by commenting "/houston approve".
+# Bypasses Karajan CI's REQUEST_CHANGES review.
+
+name: Houston Override
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  override:
+    if: >
+      github.event.issue.pull_request &&
+      contains(github.event.comment.body, '/houston approve')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dismiss Karajan CI review and approve
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const pr_number = context.payload.issue.number;
+
+            // Find and dismiss kj-reviewer reviews
+            const reviews = await github.rest.pulls.listReviews({
+              owner, repo, pull_number: pr_number
+            });
+
+            for (const review of reviews.data) {
+              if (review.user.login.includes('kj-reviewer') && review.state === 'CHANGES_REQUESTED') {
+                await github.rest.pulls.dismissReview({
+                  owner, repo, pull_number: pr_number, review_id: review.id,
+                  message: `Dismissed by Houston Override (${context.payload.comment.user.login})`
+                });
+              }
+            }
+
+            // Approve the PR
+            await github.rest.pulls.createReview({
+              owner, repo, pull_number: pr_number,
+              event: 'APPROVE',
+              body: `Houston Override by @${context.payload.comment.user.login}`
+            });

package/templates/workflows/kj-ci-gateway.yml

@@ -0,0 +1,58 @@
+# Karajan CI Gateway — publishes PR comments and reviews from repository_dispatch events.
+# Triggered by Karajan Code pipeline via `gh api repos/{owner}/{repo}/dispatches`.
+#
+# Required secrets:
+#   KJ_CI_APP_ID      — GitHub App ID for kj-reviewer
+#   KJ_CI_PRIVATE_KEY — PEM private key for the GitHub App
+
+name: Karajan CI Gateway
+
+on:
+  repository_dispatch:
+    types:
+      - kj-comment
+      - kj-review
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  gateway:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate App Token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.KJ_CI_APP_ID }}
+          private-key: ${{ secrets.KJ_CI_PRIVATE_KEY }}
+
+      - name: Post Comment
+        if: github.event.action == 'kj-comment'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ steps.app-token.outputs.token }}
+          script: |
+            const { pr_number, agent, body } = context.payload.client_payload;
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pr_number,
+              body: `**${agent}** (via Karajan CI)\n\n${body}`
+            });
+
+      - name: Submit Review
+        if: github.event.action == 'kj-review'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ steps.app-token.outputs.token }}
+          script: |
+            const { pr_number, event, body, agent } = context.payload.client_payload;
+            await github.rest.pulls.createReview({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: pr_number,
+              event: event,
+              body: `**${agent}** (via Karajan CI)\n\n${body}`
+            });

package/vendor/tree-sitter-grammars/README.md

@@ -0,0 +1,21 @@
+# Vendored tree-sitter grammars
+
+WASM binaries used by `src/lang/tree-sitter-loader.js`. Vendored (rather
+than pulled as runtime deps) so the npm package and the SEA binary ship
+exactly the grammars we support — adding all of `@vscode/tree-sitter-wasm`
+would balloon the install by ~22 MB for languages we never chunk.
+
+Source: extracted from `@vscode/tree-sitter-wasm@0.3.1`. That package
+re-builds upstream `tree-sitter-*` grammars against the tree-sitter
+0.25.x ABI, which matches the runtime `web-tree-sitter@0.26.x` we depend
+on. Older prebuilds (e.g. `tree-sitter-wasms@0.1.13`) target an older ABI
+and fail to load.
+
+Re-extract with:
+
+    npm pack @vscode/tree-sitter-wasm
+    tar -xzf vscode-tree-sitter-wasm-*.tgz
+    cp package/wasm/tree-sitter-python.wasm vendor/tree-sitter-grammars/python.wasm
+    cp package/wasm/tree-sitter-rust.wasm   vendor/tree-sitter-grammars/rust.wasm
+    cp package/wasm/tree-sitter-go.wasm     vendor/tree-sitter-grammars/go.wasm
+    cp package/wasm/tree-sitter-java.wasm   vendor/tree-sitter-grammars/java.wasm