contextos-agents 2.3.0 → 2.3.2

package/.agents/generated/claude/skills/security/SKILL.md

@@ -2,178 +2,104 @@
 
 ## Overview
 
-Enforces zero-trust defense-in-depth, OWASP API Top 10 mitigation, cryptographic hardening, sensitive data leakage protection, and AI/LLM safety across all services, endpoints, and agent integrations.
+Protect application and agent trust boundaries. These instructions guide work;
+automated checkers enforce only their explicitly tested scope.
 
 ## When to Use
 
-Activate whenever writing authentication, authorization, session management, database queries, cryptography, external API integrations, user input handling, or agent tool calling.
+Authentication, authorization, protected data, inputs, cryptography, external
+requests, payments, destructive actions, and tool execution.
 
 ## Rules & Patterns
 
-### Negative Constraints (What NOT to Do)
-
-1. **NEVER use standard string comparison (`===`) for secrets/hashes**: Always use `crypto.timingSafeEqual` to prevent timing attacks.
-2. **NEVER store sensitive JWT access/refresh tokens in `localStorage`**: Store tokens in `httpOnly`, `Secure`, `SameSite=Strict` cookies.
-3. **NEVER return raw database/internal error messages or stack traces to the client**: Return standardized generic error codes (`INTERNAL_SERVER_ERROR`) and log details internally.
-4. **NEVER trust client-provided IDs for authorization without tenant/ownership checks**: Always verify `where: { id, userId: session.userId }` to prevent Broken Object Level Authorization (BOLA/IDOR).
-5. **NEVER disable CSRF protection, CORS allow-all (`*`), or TLS verification (`NODE_TLS_REJECT_UNAUTHORIZED=0`) in production**: Always enforce strict origin whitelists and HTTPS.
-6. **NEVER pass un-sanitized third-party content directly into system prompts or shell execution**: Treat all external data as potentially adversarial.
-
----
-
-### OWASP Top 10 for Modern APIs & Full-Stack
-
-#### 1. Injection (SQL, NoSQL, Command)
-
-- Always use parameterized queries - never concatenate user input into SQL or shell commands.
-- Use ORMs (Prisma, Drizzle, SQLAlchemy) with strict schema validation.
-- Validate and sanitize all user input before processing.
-
-#### 2. Broken Object Level Authorization (BOLA / IDOR)
-
-- Validate user ownership on EVERY database read, update, or delete:
-
-  ```typescript
-  // [GOOD] Scoped to authenticated user
-  const doc = await db.document.findFirst({
-    where: { id: documentId, tenantId: session.tenantId }
-  });
-  ```
-
-#### 3. Broken Authentication & Session Management
-
-- Use Argon2id or bcrypt (cost factor ≥ 12) for password hashing.
-- Short-lived access tokens (15 min) + secure HTTP-only refresh tokens.
-- Enforce rate limiting and brute-force lockouts on auth endpoints.
-
-#### 4. SSRF (Server-Side Request Forgery)
-
-- Restrict server-side URL fetching: validate URL scheme (`https:` only), resolve IP, and block private CIDR blocks (`10.0.0.0/8`, `127.0.0.0/8`, `169.254.0.0/16`, `192.168.0.0/16`).
-
-#### 5. Security Misconfiguration & Headers
-
-Enforce modern production security headers:
-
-```http
-Content-Security-Policy: default-src 'self'
-X-Content-Type-Options: nosniff
-X-Frame-Options: DENY
-Strict-Transport-Security: max-age=31536000; includeSubDomains
-Referrer-Policy: strict-origin-when-cross-origin
-Permissions-Policy: camera=(), microphone=(), geolocation=()
-```
-
----
-
-### AI Agent & LLM Security Invariants
-
-When building AI workflows, tools, or MCP servers:
-
-1. **Prompt Injection Defense**:
-   - Clearly delineate untrusted user/web content using boundary markers (e.g. `<untrusted_content>` tags).
-   - Never allow untrusted content to override system instructions or tool execution permissions.
-2. **Tool Execution Boundaries**:
-   - Destructive operations (database drops, file deletions, payment triggers) MUST require explicit user confirmation.
-   - Restrict file system tools to the workspace root - block directory traversal (`../`).
-3. **Secret Masking & Output Sanitization**:
-   - Scrub API keys (`sk-...`, `Bearer ...`), tokens, and credentials before writing to agent logs or step summaries.
-4. **Sandbox Execution & Write Isolation (Supply-Chain Defense)**:
-   - Target code is inspected strictly read-only; never execute target-controlled builds or tests with write access to the repository root.
-   - Restrict process write boundaries strictly to an isolated temporary `scratch/` directory.
-   - Enforce zero outbound external network access during security audits to prevent secret exfiltration via malicious scripts or dependencies.
-   - Promote verified non-secret results to retained `artifacts/` only via trusted parent-side inspection code.
-
----
+- Obtain identity from trusted authentication. Enforce ownership/tenant policy
+  before protected reads or mutations; client IDs are not authorization.
+- Validate boundary inputs and reject unknown privilege fields. Parameterize
+  queries and encode output for its context; avoid shell interpolation. An ORM
+  does not secure interpolated raw SQL.
+- Keep credentials out of source, logs, arguments, and client bundles. Use
+  established password/session libraries and cookie, CSRF, origin, and TLS
+  policies appropriate to the threat model.
+- Use constant-time primitives for secret comparisons. Surrounding code and
+  length handling matter; the whole flow is not necessarily constant-time.
+- External content remains untrusted data. Delimit it and preserve instruction
+  and tool authority; markers alone do not prevent prompt injection.
+- Existing authorization carries forward. For destructive actions verify it
+  covers the actual target and effect; ask only for missing authority.
+- For untrusted repositories/dependency scripts, inspect before execution,
+  isolate writes, withhold credentials, and restrict network access. Ordinary
+  authorized development uses relevant project checks. State actual sandbox
+  capabilities instead of claiming isolation the tools do not provide.
 
 ## Code Examples
 
+### Timing-safe webhook signature comparison
 
-### Timing-Safe Secret Verification
+This runnable block verifies SHA-256 hexadecimal HMAC signatures. Timestamp,
+replay protection, raw-body capture, and provider formats are separate requirements.
 
+<!-- example: security-hmac -->
 ```javascript
 import crypto from 'node:crypto';
 
 export function verifyWebhookSignature(payload, signature, secret) {
-  const hmac = crypto.createHmac('sha256', secret);
-  const digest = Buffer.from(hmac.update(payload).digest('hex'), 'utf8');
-  const sigBuffer = Buffer.from(signature, 'utf8');
-
-  if (digest.length !== sigBuffer.length) return false;
-  return crypto.timingSafeEqual(digest, sigBuffer);
+  if (typeof signature !== 'string' || !/^[a-f0-9]{64}$/i.test(signature)) return false;
+  const digest = crypto.createHmac('sha256', secret).update(payload).digest();
+  const received = Buffer.from(signature, 'hex');
+  return digest.length === received.length && crypto.timingSafeEqual(digest, received);
 }
 ```
 
-### SSRF Prevention Requirements (OWASP Compliant)
+### Restricted partner URL fetch
 
-Per [OWASP SSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html), naive application-level DNS pre-checks followed by standard `fetch(url)` are fundamentally flawed due to DNS rebinding (TOCTOU) and unvalidated HTTP 3xx redirects.
+Follow the [OWASP SSRF guidance](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html).
+A hostname check followed by ordinary DNS resolution is not a complete SSRF
+boundary. Use a trusted egress transport/proxy that validates IPv4/IPv6 addresses
+at connection time and blocks private, loopback, link-local, and metadata targets,
+including DNS changes. Arbitrary URL fetchers need a separate network policy;
+this sample covers known partner hostnames.
 
-#### Mandatory Architectural Controls
+Supply that trusted transport explicitly. This block checks URL syntax, HTTPS,
+credentials, port 443, a trusted hostname allowlist, and redirect policy. There
+is no ambient fetch fallback. Local tests inject a controlled transport; they
+do not verify production egress or DNS behavior.
 
-1. **Network-Layer Defense (Primary)**: For user-supplied arbitrary webhooks or URLs, route all outbound traffic through an isolated egress forward proxy (e.g., Smokescreen, Envoy, Squid) configured with firewall-level IP filters blocking RFC 1918, RFC 6598, link-local (`169.254.169.254`), loopback, and IPv6 local addresses at the socket handshake level.
-2. **Positive Destination Allowlist**: If fetching from known external partners, validate destination hostname against a strict positive allowlist.
-3. **Disable Automatic Redirects**: Always set `redirect: 'error'` or `'manual'`. Never follow HTTP redirects automatically without re-validating the target URL against allowlist rules.
-4. **Protocol & Credential Restrictions**: Enforce `https:` exclusively; reject embedded credentials (`user:pass@host`) and non-standard ports.
-
-```typescript
-/**
- * Verified Allowlist-based HTTP Client (OWASP SSRF Prevention)
- * Enforces HTTPS, strict destination allowlist, and rejects HTTP redirects.
- */
-export async function fetchFromAllowlist(
-  urlString: string,
-  allowedHostnames: ReadonlySet<string>,
-  options: RequestInit = {}
-): Promise<Response> {
+<!-- example: security-ssrf -->
+```javascript
+export async function fetchFromAllowlist(urlString, allowedHostnames, options, transport) {
   const parsed = new URL(urlString);
-
-  // 1. Enforce HTTPS only
   if (parsed.protocol !== 'https:') {
-    throw new Error(`SSRF blocked: protocol "${parsed.protocol}" is not permitted; HTTPS required`);
+    throw new Error('SSRF blocked: protocol "' + parsed.protocol + '" is not permitted; HTTPS required');
   }
-
-  // 2. Reject credentials in URL
   if (parsed.username || parsed.password) {
     throw new Error('SSRF blocked: URL credentials (user:password@host) are prohibited');
   }
-
-  // 3. Strict positive destination allowlist (prevents internal network probing)
+  if (parsed.port && parsed.port !== '443') throw new Error('SSRF blocked: non-standard port');
   const normalizedHost = parsed.hostname.toLowerCase();
   if (!allowedHostnames.has(normalizedHost)) {
-    throw new Error(`SSRF blocked: destination host "${normalizedHost}" is not in the approved allowlist`);
+    throw new Error('SSRF blocked: destination host "' + normalizedHost + '" is not in the approved allowlist');
   }
-
-  // 4. Disable automatic redirects to prevent redirection to private IPs or metadata endpoints
-  return fetch(urlString, {
-    ...options,
-    redirect: 'error'
-  });
+  if (typeof transport !== 'function') throw new TypeError('Trusted egress transport required');
+  return transport(parsed.href, { ...options, redirect: 'error' });
 }
 ```
 
----
-
 ## Validation Checklist
 
-- [ ] All database queries parameterized or managed by type-safe ORM.
-- [ ] BOLA/IDOR prevented: all entity queries scoped by tenant/user id.
-- [ ] Cookies set with `HttpOnly`, `Secure`, and `SameSite=Strict` or `Lax`.
-- [ ] Passwords hashed with Argon2id / bcrypt.
-- [ ] Security headers active in middleware/reverse proxy.
-- [ ] No secrets or tokens checked into source control or exposed in logs.
-
----
+- [ ] Allowed and denied identity/tenant cases are checked before data access.
+- [ ] Invalid and unknown inputs never reach protected persistence.
+- [ ] Secrets and production errors preserve their boundaries.
+- [ ] External requests and tool policies are checked at the stated scope.
+- [ ] Commands, results, unrun checks, and limitations are reported.
 
 ## Common Mistakes
 
-- **Trusting client-side claims**: Checking role or permissions only on the frontend without server-side validation.
-- **Timing attacks on tokens**: Comparing tokens with `token === expectedToken` instead of `timingSafeEqual`.
-- **Exposing internal stack traces**: Returning full error objects to client in production.
-- **Unvalidated redirects / URLs**: Allowing arbitrary URLs in redirect or fetch parameters.
-
----
+Treating an allowlist as network isolation; comparing role labels instead of
+permissions; passing client payloads into persistence; interpreting a secret scan
+or document validator as a complete application security audit.
 
 ## Integration Notes
 
-- Runs in the REVIEW phase for every backend route, auth flow, and database mutation.
-- Integrates with `engineering-workflow` during Phase 5 (5-axis quality gate).
-- Pairs with `system-design` to mandate secure network boundaries and authorization layers.
+Use engineering-workflow's proportional verification and existing authority.
+The staged scanner needs --placeholders for stubs and --scope with a real scope
+JSON file for write boundaries. Validate does not replace either check.

package/.agents/generated/claude/skills/security/TROUBLESHOOTING.md

@@ -1,19 +1,13 @@
-# security Troubleshooting & Common Mistakes
-
-## 1. Insecure Direct Object References (IDOR)
-
-- **Symptom**: User A can access User B's invoices by simply modifying the ID in the URL.
-- **Root Cause**: Querying by record ID without scoping to the authenticated `user.id` or tenant ID.
-- **Fix**: Always query with ownership predicate: `db.invoice.findFirst({ where: { id, userId: auth.user.id } })`.
-
-## 2. SQL Injection via Raw String Concatenation
-
-- **Symptom**: Database compromised through input fields.
-- **Root Cause**: String templating in raw queries (`db.query("SELECT * FROM users WHERE id = " + id)`).
-- **Fix**: Always use parameterized queries (`$1, $2`) or ORM/query-builder methods.
-
-## 3. Storing Sensitive Secrets in Git or Client Bundles
-
-- **Symptom**: API keys or JWT signing secrets exposed publicly.
-- **Root Cause**: Hardcoding secrets in source files or prefixing server secrets with NEXT_PUBLIC_.
-- **Fix**: Store all secrets in server-only environment variables; add git-secrets to pre-commit hooks.
+# Security troubleshooting
+
+- IDOR/BOLA: verify denied users/tenants before persistence and require the action
+  permission, not merely an object ID.
+- SQL/shell interpolation: use parameters or safe argument APIs. Schema checks
+  alone do not repair command interpolation.
+- SSRF: DNS prechecks followed by ambient fetch can resolve again; verify the
+  connection-time transport policy, A/AAAA results, and redirects.
+- Untrusted scripts: inspect/isolate without credentials; state actual controls.
+- Authority: confirm targets/effects against existing permission instead of
+  asking again merely because a phase changed.
+- Green scan: inspect enabled flags, staged files, scope input, and exclusions.
+  Results do not prove all security invariants or unstaged code.

package/.agents/generated/claude/skills/security/VALIDATION.json

@@ -1,12 +1,123 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
+  "x-contextos-evidence-contract": 1,
+  "title": "Scoped verification evidence",
+  "description": "Report shape and outcome consistency only; command execution and agent behavior require separate evidence.",
   "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "checks",
+    "limitations"
+  ],
   "properties": {
-    "rules_followed": {
-      "type": "boolean"
+    "status": {
+      "enum": [
+        "verified",
+        "partial",
+        "not_run"
+      ]
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "command",
+          "exitCode",
+          "scope"
+        ],
+        "properties": {
+          "command": {
+            "type": "string",
+            "minLength": 1
+          },
+          "exitCode": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "scope": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "limitations": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
     }
   },
-  "required": [
-    "rules_followed"
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "verified"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "checks": {
+            "minItems": 1,
+            "items": {
+              "properties": {
+                "exitCode": {
+                  "const": 0
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "enum": [
+              "partial",
+              "not_run"
+            ]
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "limitations": {
+            "minItems": 1
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "not_run"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "checks": {
+            "items": {
+              "properties": {
+                "exitCode": {
+                  "type": "null"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
   ]
 }

package/.agents/generated/gemini/skills/context-manager/EXAMPLES.md

@@ -1,19 +1,7 @@
-# context-manager Examples — Anti-patterns vs ContextOS Standard
+# context-manager compatibility examples
 
-## Example 1: Context Selection
+Use the canonical [context-os](../context-os/SKILL.md). An explicit resolver
+request for context-manager redirects to context-os; the warning explains the mapping.
+A directly loaded alias should follow the same canonical instructions.
 
-### Anti-pattern: Context Window Dumping
-
-```text
-Agent reads all 180 files in src/ into context to debug a single button click handler.
-Result: Exhausts 150k tokens, reaches rate limits, and forgets user instructions.
-```
-
-### Best practice: ContextOS Standard (Targeted AST Traversal)
-
-```text
-1. Inspect package.json and AGENTS.md.
-2. Grep for target symbol: grep_search for 'SubmitButton'.
-3. Read ONLY components/SubmitButton.tsx and its direct import types/button.ts.
-Total tokens used: <1,500 tokens. Fast, accurate, zero hallucinations.
-```
+Inspect relevant files, callers, and resolver warnings. Package evidence does not guarantee a complete symbol graph or total prompt budget.

package/.agents/generated/gemini/skills/context-manager/SKILL.md

@@ -1,124 +1,35 @@
 ---
 name: context-manager
-description: >
-  Smart context selection engine. Analyzes the current task, consults the Project Graph, and returns only the documents and skills needed to prevent token overflow.
-
+description: "Compatibility alias for context-os context selection and budgeting."
 ---
 # context-manager
 
 ## Overview
 
-Deterministic context window optimizer. Analyzes user task intent and queries project dependency graphs to inject minimal relevant files and skills, preventing LLM attention loss and context pollution.
+Deprecated compatibility identifier. Use [context-os](../context-os/SKILL.md) for the canonical instructions.
 
 ## When to Use
 
-Activate during multi-file investigations, large refactorings, or complex tasks where dumping entire directory trees would blow past context budgets.
+An existing configuration or user explicitly names context-manager.
 
 ## Rules & Patterns
 
-You are the **Context Manager**. Your job is to prevent context overload.
-
-## How It Works
-
-When given a task:
-
-### Step 1: Classify the task
-
-```yaml
-task:
-  type: [frontend | backend | fullstack | architecture | bugfix | refactor | deploy | review]
-  scope: [module | feature | file | project-wide]
-  module: {{module_name from Project Graph}}
-```
-
-### Step 2: Consult the Project Graph
-
-If `docs/PROJECT_GRAPH.md` or `.graphify/graph.json` exists (or activate `graphify` skill to extract AST dependencies):
-
-1. Find the module this task belongs to
-2. Get the module's dependencies
-3. Get the module's required skills
-4. Get the files this task will likely touch
-
-### Step 3: Apply Context Rules
-
-Load `references/context-rules.md` and apply the task type → document mapping.
-
-### Step 4: Return Context Package
-
-Output a context package:
-
-```yaml
-context:
-  documents:
-    required:
-      - docs/API.md          # sections: [appointments]
-      - docs/ARCHITECTURE.md # sections: [backend, api-layer]
-    optional:
-      - docs/decisions/0003-postgres.md
-    skipped:
-      - docs/UI.md           # reason: backend task
-      - docs/DATABASE.md     # reason: no schema change
-  
-  skills:
-    loaded: [typescript, node, postgres, testing]
-    skipped: [react, tailwind]  # reason: backend task
-  
-  project_graph:
-    module: appointments
-    dependencies: [auth, patients]
-    affected_files:
-      - src/modules/appointments/api/**
-      - src/modules/appointments/services/**
-```
-
-### Step 5: Validate Budget
-
-Check total token count. If over budget (see context-rules.md):
-
-1. Trim Level 1 docs to summaries
-2. Load only affected sections of Level 2 docs
-3. Keep Level 3 (skills) at full detail
-
-## Context Caching
-
-After first compilation for a module, cache the result:
-
-```
-.cache/
-  frontend.context.yaml
-  backend.context.yaml
-  appointments.context.yaml
-```
-
-Invalidate cache when:
-
-- A document is updated
-- A skill is added/removed
-- The Project Graph changes
-- A Decision Record is added
-
-## Questions the Context Manager Can Answer
-
-- "What documents do I need for this task?"
-- "Which skills should be loaded?"
-- "What modules are affected by this change?"
-- "Is this context package within budget?"
-- "Why was this document skipped?"
-
+Apply the canonical skill without loading a duplicate process. Existing authorization, proportional verification, and optional role declarations carry forward. The resolver redirects this identifier and reports an alias warning.
 
 ## Code Examples
 
-See `EXAMPLES.md` for detailed code examples.
+Explicit context-manager selection resolves to context-os; inspect the resolver result rather than assuming both bodies were loaded.
 
 ## Validation Checklist
 
-What to verify during the review phase before completing the task.
+- [ ] Canonical guidance is used.
+- [ ] Alias resolution adds no duplicate body.
+- [ ] Evidence scope and limitations are stated.
 
 ## Common Mistakes
 
-Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+Treating this compatibility name as an independent engine or a mandatory ceremony.
 
 ## Integration Notes
 
-How this skill interacts with other skills.
+Keep legacy links available. Read [references/context-rules.md](references/context-rules.md) only for compatibility details.

package/.agents/generated/gemini/skills/context-manager/TROUBLESHOOTING.md

@@ -1,7 +1,7 @@
-# context-manager Troubleshooting & Common Mistakes
+# context-manager compatibility troubleshooting
 
-## 1. Token Budget Blowout
-
-- **Symptom**: Model performance drops significantly, losing earlier conversational context.
-- **Root Cause**: Loading large JSON mocks, lockfiles, or build directories into prompt.
-- **Fix**: Never read package-lock.json, dist/, or build artifacts unless explicitly debugging bundle outputs.
+- Duplicate process: load the canonical context-os instructions once.
+- Repeated approval or banners: preserve existing authorization and optional roles.
+- Conflicting legacy guidance: use the canonical skill and update the stale link.
+- Claimed automation: inspect actual CLI results and distinguish instructions
+  from runtime enforcement.