start-vibing-stacks 2.6.0 → 2.7.3

package/stacks/_shared/skills/final-check/SKILL.md

@@ -1,56 +1,93 @@
-# Final Check — Task Completion Validator
+---
+name: final-check
+version: 2.0.0
+description: Final validator with VETO power. Now executable — runs `npx tsx .claude/hooks/final-check.ts` to scan for debug statements, secrets, .skip, any, RCE risks, SQL concat. Blocks completion on CRITICAL/HIGH findings.
+---
 
-**ALWAYS invoke BEFORE completing ANY task. HAS VETO POWER.**
+# Final Check — Executable Validator
 
-> ⚠️ **VETO POWER:** If any rule is violated → STOP, list violations, require fix, re-validate.
+**ALWAYS run BEFORE completing ANY task. HAS VETO POWER.**
 
-## Purpose
+> v2.0+ promotes this from a manual checklist to an executable script. The script never trusts memory.
 
-Last check before task completion. Ensures nothing was forgotten.
+## How to Run
 
-## Checklist
+```bash
+npx tsx .claude/hooks/final-check.ts
+```
 
-### 1. Code Quality
-- [ ] Quality gates passed (PHPStan/TypeCheck, Tests, Lint)
-- [ ] No `console.log` / `var_dump` left in code
-- [ ] No TODO/FIXME left unresolved
-- [ ] No hardcoded secrets or credentials
+Exit codes:
+- `0` — clean (or only LOW/MEDIUM warnings)
+- `1` — at least one CRITICAL or HIGH finding → **task blocked**
 
-### 2. Documentation
-- [ ] CLAUDE.md "Last Change" updated
-- [ ] Affected domain files updated
-- [ ] New patterns documented
+## What It Scans
 
-### 3. Testing
-- [ ] New code has tests
-- [ ] Existing tests still pass
-- [ ] Edge cases covered
+For every file in the diff (staged + unstaged + untracked) matching the active stack's source extensions, every line is checked against:
 
-### 4. Git
-- [ ] On correct branch
-- [ ] All files committed
-- [ ] Conventional commit message
-- [ ] Merged to main (if complete)
+| Severity | Rule | Why blocking |
+|---|---|---|
+| CRITICAL | Hardcoded secret pattern (api key / token / password) | Leak risk |
+| CRITICAL | Public env var with `*SECRET\|*TOKEN\|*PRIVATE\|*PASSWORD\|*CREDENTIAL` | Bundles into client |
+| HIGH | Arbitrary code-execution function (`eval`, Python `exec`) | RCE |
+| HIGH | `subprocess` with `shell=True` (Python) | Command injection |
+| HIGH | SQL string concatenation / f-string SQL | SQL injection |
+| HIGH | `it.only` / `test.only` / `describe.only` / `it.skip` in committed test | False green CI |
+| MEDIUM | `console.log/debug/trace` outside tests | Debug leftover, log noise |
+| MEDIUM | PHP `var_dump/dd/dump/print_r` | Debug leftover |
+| MEDIUM | TypeScript `any` (without `/* ok */` escape) | Erodes strict mode |
+| MEDIUM | `@ts-ignore` (use `@ts-expect-error` with comment) | Silently outdated |
+| MEDIUM | `@pytest.mark.skip` | Hidden test gaps |
+| LOW | `print()` outside tests (Python) | Use logger |
+| LOW | TODO / FIXME / XXX / HACK | Track or remove |
 
-### 5. Skills Consulted
-- [ ] Codebase knowledge checked before implementing
-- [ ] Research cache checked before web search
-- [ ] Security patterns applied
+Lines containing recognised placeholders (`<your...>`, `YOUR_X`, `placeholder`, `example.com`, `sk_test_`) are skipped to avoid false positives in `.env.example` and docs.
 
-## Violation Response
+## Workflow
 
 ```
-BLOCKED: [Violation description]
+1. Implementation done
+2. Run npx tsx .claude/hooks/final-check.ts
+3. If exit 1 → fix, re-run
+4. If exit 0 → proceed to quality-gate → commit
+```
+
+## Suppressing False Positives
 
-Required fixes:
-1. [Fix needed]
-2. [Fix needed]
+When a finding is intentional (e.g. an `any` in well-justified glue code):
 
-Re-run final-check after fixing.
+```ts
+const result = (json as any) /* ok: external lib without types */;
 ```
 
+Only `/* ok */` immediately after `: any` is recognised. For other rules, refactor — there is no general-purpose suppression by design.
+
+## Hook Wiring (Optional)
+
+To run automatically on Stop, add to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "npx tsx ${CLAUDE_PROJECT_DIR}/.claude/hooks/final-check.ts" }]
+    }]
+  }
+}
+```
+
+The default Stop is `stop-validator.ts` (git/branch/CLAUDE.md/secret scan). `final-check.ts` is complementary — runs before it as a code-quality gate.
+
 ## Rules
 
-1. **VETO POWER** — can block task completion
-2. **ALL CHECKS MUST PASS** — no partial approvals
-3. **RE-VALIDATE AFTER FIXES** — don't trust "I fixed it"
+1. **VETO POWER** — exit 1 blocks task completion
+2. **NEVER skip** — `--no-verify` style bypasses are forbidden
+3. **RE-RUN after fixes** — don't trust memory
+4. **One finding at a time** — fix CRITICAL first, then HIGH
+5. **Refactor over suppress** — `/* ok */` is for extraordinary cases
+
+## See Also
+
+- `quality-gate` — typecheck/lint/test/build (different scope)
+- `security-baseline` — what the secret/RCE rules enforce
+- `stop-validator.ts` — git/branch/docs gate (sibling, complementary)

package/stacks/_shared/skills/git-workflow/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: git-workflow
+version: 1.0.0
+---
+
 # Git Workflow
 
 ## Branch Naming

package/stacks/_shared/skills/hook-development/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: hook-development
+version: 1.0.0
+---
+
 # Hook Development — Claude Code Hooks
 
 **ALWAYS invoke when creating or modifying Claude Code hooks.**

package/stacks/_shared/skills/observability/SKILL.md

@@ -0,0 +1,351 @@
+---
+name: observability
+version: 1.0.0
+description: Structured logging, correlation IDs, OpenTelemetry tracing, error tracking (Sentry), metrics, and PII redaction. Invoke when adding logging, instrumentation, or debugging production issues.
+---
+
+# Observability — Logs, Traces, Metrics
+
+**ALWAYS invoke when adding logging, instrumentation, error tracking, or analyzing production issues.**
+
+> Three pillars: **Logs** (what happened) + **Traces** (where time was spent) + **Metrics** (how much / how often).
+> One signal: **correlation/trace IDs** that thread through all three.
+
+---
+
+## 1. Structured Logging — Mandatory
+
+Logs are JSON, not text. Free-form strings can't be queried, aggregated, or alerted on.
+
+### Required fields per log line
+
+| Field | Source |
+|---|---|
+| `timestamp` | ISO-8601, UTC |
+| `level` | `trace` / `debug` / `info` / `warn` / `error` / `fatal` |
+| `msg` | Short human description |
+| `service` | Service name |
+| `env` | `production` / `staging` / `development` |
+| `trace_id` | OpenTelemetry trace id (W3C `traceparent`) |
+| `span_id` | Current span |
+| `request_id` | Inbound HTTP request id (mirror to `x-request-id` header) |
+| `user_id` | Authenticated user (hash if PII concerns) — **never** email/full name |
+
+### Node.js — pino
+```ts
+// lib/logger.ts
+import pino from 'pino';
+import { randomUUID } from 'crypto';
+
+export const logger = pino({
+  level: process.env['LOG_LEVEL'] ?? 'info',
+  base: {
+    service: 'api',
+    env: process.env['NODE_ENV'],
+    pid: process.pid,
+  },
+  timestamp: pino.stdTimeFunctions.isoTime,
+  redact: {
+    paths: [
+      'req.headers.authorization',
+      'req.headers.cookie',
+      'req.body.password',
+      'req.body.token',
+      '*.password',
+      '*.creditCard',
+      '*.ssn',
+    ],
+    censor: '[REDACTED]',
+  },
+});
+
+// HTTP middleware: attach request_id + child logger to req
+export function requestLogger(req, res, next) {
+  const requestId = req.headers['x-request-id'] ?? randomUUID();
+  res.setHeader('x-request-id', requestId);
+  req.log = logger.child({ request_id: requestId, method: req.method, path: req.path });
+  req.log.info({ event: 'request.start' });
+  res.on('finish', () => {
+    req.log.info({ event: 'request.end', status: res.statusCode, duration_ms: Date.now() - req.startTime });
+  });
+  next();
+}
+```
+
+### Python — structlog
+```python
+import structlog, logging, sys, uuid
+
+structlog.configure(
+    processors=[
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso", utc=True),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.format_exc_info,
+        structlog.processors.JSONRenderer(),
+    ],
+    wrapper_class=structlog.make_filtering_bound_logger(logging.INFO),
+    logger_factory=structlog.PrintLoggerFactory(file=sys.stdout),
+)
+
+log = structlog.get_logger()
+
+# FastAPI middleware
+@app.middleware("http")
+async def request_logger(request, call_next):
+    request_id = request.headers.get("x-request-id", str(uuid.uuid4()))
+    structlog.contextvars.bind_contextvars(
+        request_id=request_id, method=request.method, path=request.url.path
+    )
+    log.info("request.start")
+    response = await call_next(request)
+    response.headers["x-request-id"] = request_id
+    log.info("request.end", status=response.status_code)
+    structlog.contextvars.clear_contextvars()
+    return response
+```
+
+### PHP — Monolog
+```php
+// config/logging.php
+'channels' => [
+    'json' => [
+        'driver' => 'monolog',
+        'handler' => Monolog\Handler\StreamHandler::class,
+        'with' => ['stream' => 'php://stdout'],
+        'formatter' => Monolog\Formatter\JsonFormatter::class,
+        'processors' => [
+            Monolog\Processor\WebProcessor::class,
+            Monolog\Processor\UidProcessor::class,
+        ],
+    ],
+],
+```
+
+---
+
+## 2. Log Levels — Use Them Right
+
+| Level | When |
+|---|---|
+| `trace` | Verbose diagnostics, off in prod |
+| `debug` | Development helper, off in prod by default |
+| `info` | Business events: signup, payment, login, job completed |
+| `warn` | Recoverable anomaly: retry, deprecated path, fallback used |
+| `error` | Operation failed for one user/request, system continues |
+| `fatal` | Cannot continue, process exits |
+
+Default prod level: `info`. Errors should always page or alert. `debug` flooding logs is a cost issue.
+
+---
+
+## 3. PII Redaction — Mandatory
+
+Never log:
+- Passwords, hashes, tokens, cookies, `Authorization` headers
+- Full credit card / IBAN / SSN / passport
+- Plaintext email if your jurisdiction (GDPR/LGPD) treats it as PII without legitimate basis
+- Full request body or full response body without filtering
+
+Redact at the logger level (so it can't be bypassed by a forgetful caller):
+
+```ts
+// pino redact paths (above)
+// or wrap manually:
+function safeBody(body: any) {
+  const out = { ...body };
+  for (const k of ['password', 'token', 'cookie', 'authorization']) {
+    if (k in out) out[k] = '[REDACTED]';
+  }
+  return out;
+}
+```
+
+For email: log a hash of the email or the first 2 chars + domain (`jo***@example.com`). Document the policy.
+
+---
+
+## 4. Distributed Tracing — OpenTelemetry
+
+Tracing answers "where did the request spend time" across services.
+
+### Node.js (auto-instrumentation)
+```ts
+// instrumentation.ts — load BEFORE any other import
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { Resource } from '@opentelemetry/resources';
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+
+new NodeSDK({
+  resource: new Resource({ [ATTR_SERVICE_NAME]: 'api' }),
+  traceExporter: new OTLPTraceExporter({ url: process.env['OTEL_EXPORTER_OTLP_ENDPOINT'] }),
+  instrumentations: [getNodeAutoInstrumentations()],
+}).start();
+```
+
+Run: `node --import ./instrumentation.js dist/index.js`
+
+### Python (FastAPI)
+```python
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+
+FastAPIInstrumentor.instrument_app(app)
+SQLAlchemyInstrumentor().instrument(engine=engine)
+HTTPXClientInstrumentor().instrument()
+```
+
+### Manual span — when you want to time business logic
+```ts
+import { trace } from '@opentelemetry/api';
+const tracer = trace.getTracer('billing');
+
+await tracer.startActiveSpan('charge_customer', async (span) => {
+  try {
+    span.setAttribute('customer.id', customerId);
+    const charge = await stripe.charges.create({ amount, customer: customerId });
+    span.setAttribute('charge.id', charge.id);
+    return charge;
+  } catch (err) {
+    span.recordException(err);
+    span.setStatus({ code: 2 /* ERROR */ });
+    throw err;
+  } finally {
+    span.end();
+  }
+});
+```
+
+---
+
+## 5. Error Tracking — Sentry
+
+Pair with structured logging. Sentry is for **alertable** errors with full stack + breadcrumbs; logs are for **everything**.
+
+### Node.js
+```ts
+import * as Sentry from '@sentry/node';
+
+Sentry.init({
+  dsn: process.env['SENTRY_DSN'],
+  environment: process.env['NODE_ENV'],
+  tracesSampleRate: 0.1,
+  profilesSampleRate: 0.1,
+  beforeSend(event) {
+    // Defense in depth — strip if logger redaction missed it
+    if (event.request?.cookies) delete event.request.cookies;
+    if (event.request?.headers?.['authorization']) {
+      event.request.headers['authorization'] = '[REDACTED]';
+    }
+    return event;
+  },
+});
+```
+
+### Python
+```python
+import sentry_sdk
+from sentry_sdk.integrations.fastapi import FastApiIntegration
+from sentry_sdk.scrubber import EventScrubber, DEFAULT_DENYLIST
+
+sentry_sdk.init(
+    dsn=os.environ["SENTRY_DSN"],
+    environment=os.environ["APP_ENV"],
+    traces_sample_rate=0.1,
+    integrations=[FastApiIntegration()],
+    event_scrubber=EventScrubber(denylist=DEFAULT_DENYLIST + ["jwt", "session"]),
+    send_default_pii=False,
+)
+```
+
+---
+
+## 6. Metrics
+
+Track **RED** (Rate / Errors / Duration) on every endpoint and **USE** (Utilization / Saturation / Errors) on every resource.
+
+OpenTelemetry metrics + Prometheus exporter, or vendor SDK (Datadog, New Relic).
+
+```ts
+import { metrics } from '@opentelemetry/api';
+const meter = metrics.getMeter('api');
+
+const httpDuration = meter.createHistogram('http.server.duration', { unit: 'ms' });
+const ordersCreated = meter.createCounter('orders.created');
+
+httpDuration.record(durationMs, { method, route, status: String(statusCode) });
+ordersCreated.add(1, { plan: order.plan });
+```
+
+Cardinality rule: never tag with user_id, email, or unbounded values — explodes time-series storage. Use `route`, `status`, `plan`, etc.
+
+---
+
+## 7. Health Checks
+
+Two endpoints, distinct semantics:
+
+```ts
+app.get('/healthz', (_, res) => res.json({ ok: true }));   // liveness — am I running?
+
+app.get('/readyz', async (_, res) => {                      // readiness — can I serve?
+  const checks = await Promise.allSettled([
+    db.raw('SELECT 1'),
+    redis.ping(),
+  ]);
+  const allOk = checks.every(c => c.status === 'fulfilled');
+  res.status(allOk ? 200 : 503).json({ ok: allOk, checks });
+});
+```
+
+Kubernetes uses `livenessProbe` → `/healthz` (restart on fail) and `readinessProbe` → `/readyz` (remove from LB on fail).
+
+---
+
+## 8. Audit Log — Separate Stream
+
+Security-relevant events go to a dedicated, append-only stream:
+
+- Logins (success + failure)
+- Authorization denials
+- Permission/role changes
+- Admin actions (impersonation, data exports, deletes)
+- Payment events
+- Data access (when required by compliance: HIPAA, SOC 2)
+
+Different retention (often longer), different access (security team), different integrity guarantees (immutable, hash-chained).
+
+---
+
+## Pre-Commit Checklist
+
+- [ ] Logger configured with redact paths for password/token/cookie/authorization
+- [ ] All endpoints emit `request.start` / `request.end` with `request_id`
+- [ ] Errors include stack trace and `trace_id`
+- [ ] No `console.log` / `print` / `dd()` left in code (use the logger)
+- [ ] No PII in info-level logs
+- [ ] Sentry initialized with `beforeSend` scrubber
+- [ ] Tracing initialized at process start (before app code)
+- [ ] `/healthz` + `/readyz` endpoints exist
+
+## FORBIDDEN
+
+| Pattern | Reason |
+|---|---|
+| `console.log(req.body)` | Leaks passwords, tokens |
+| Logger without redaction | Future caller will leak |
+| Unbounded label cardinality (user_id as metric tag) | Cost explosion |
+| Same severity for everything (all `info`) | No alerting signal |
+| Tracing in dev only | Prod is where you need it |
+| Sentry without scrubber | PII in error reports |
+| Audit log in same stream as app log | Tamper risk, retention conflict |
+
+## See Also
+
+- `secrets-management` — what NEVER to log
+- `error-handling` — Result types and error taxonomy
+- `security-baseline` — A09: Security Logging Failures

package/stacks/_shared/skills/performance-patterns/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: performance-patterns
+version: 1.0.0
+---
+
 # Performance Patterns
 
 **Invoke when app is slow or needs optimization.**

package/stacks/_shared/skills/playwright-automation/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: playwright-automation
+version: 1.0.0
+---
+
 # Playwright Automation — E2E Testing
 
 **ALWAYS invoke when writing E2E tests or browser automation.**

package/stacks/_shared/skills/quality-gate/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: quality-gate
+version: 1.0.0
+---
+
 # Quality Gate — Verification System
 
 **ALWAYS invoke BEFORE any commit.**

package/stacks/_shared/skills/research-cache/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: research-cache
+version: 1.0.0
+---
+
 # Research Cache — Best Practices Storage
 
 **ALWAYS invoke BEFORE any web research.**