contextos-agents 2.3.0 → 2.3.2

package/.agents/generated/claude/skills/ponytail-mindset/TROUBLESHOOTING.md

@@ -1,19 +1,10 @@
-# ponytail-mindset Troubleshooting & Common Mistakes
-
-## 1. Conflating Minimalism with Cutting Safety Guards
-
-- **Symptom**: Agent removes input validation, error handling, or security checks in the name of "less code".
-- **Root Cause**: Misunderstanding the Ponytail principle. Ponytail cuts unnecessary abstractions, never safety invariants.
-- **Fix**: Invariant: Always retain 100% of input sanitization, error boundaries, and type safety checks.
-
-## 2. "Just In Case" Speculative Coding (YAGNI Violation)
-
-- **Symptom**: Adding config options, generics, and plugin interfaces for features not requested.
-- **Root Cause**: Premature future-proofing.
-- **Fix**: Apply Rung 1 of the ladder: If it doesn't solve the immediate requirement, do not write it.
-
-## 3. Reinventing Installed Dependencies
-
-- **Symptom**: Writing a deep-clone helper when Lodash or native structuredClone is available.
-- **Root Cause**: Skipping inspection of package.json and runtime environment.
-- **Fix**: Inspect installed dependencies before writing utility functions.
+# Minimalism troubleshooting
+
+- A shorter patch removes validation: restore the boundary checks before comparing
+  implementation sizes.
+- A helper is used once: evaluate its meaning, isolation, and readability rather
+  than automatically inlining it.
+- A new dependency appears: inspect the existing stack and actual requirement.
+- Retry behavior is assumed: check the SDK contract and test failure handling.
+- A code example is illustrative: do not report a running integration until the
+  real imports, persistence, authentication, and checks have been supplied.

package/.agents/generated/claude/skills/ponytail-mindset/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/claude/skills/ponytail-mindset/references/minimalism.md

@@ -1,186 +1,70 @@
+# Minimal maintainable implementation
 
-# ponytail-mindset
+## Decision ladder
 
-## Overview
+1. Does this solve the requested outcome? Avoid speculative features.
+2. Does project code or the installed component system already handle it?
+3. Does the standard library provide the operation?
+4. Does the native platform meet the actual requirements?
+5. Can an installed dependency handle it without extra integration cost?
+6. Can it be a readable one-liner without hiding boundary checks?
+7. Otherwise write the smallest clear implementation.
 
-Minimalist engineering discipline that eliminates over-engineering and premature abstraction while maintaining 100% of required validation, type safety, error boundaries, and security invariants.
+The rule of three is a duplication heuristic, not a ban on named functions.
+Extract a single-use helper when it clarifies an invariant or isolates an I/O
+boundary. Prefer the project's established UI system; do not install shadcn or
+another library merely because a generic guide names it. dayjs is a dependency,
+not a standard-library API. Verify retry/circuit-breaker support in the actual
+SDK; do not assume native fetch supplies an application retry policy.
 
-## When to Use
+## Preserve boundary validation
 
-Activate on all BUILD phases to prevent bloated implementations and enforce concise, focused solutions.
-
-## Rules & Patterns
-
-Based on [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail).
-
-> _He says nothing. He writes one line. It works._
-
-**Core Impact**: Dramatically reduces code footprint by eliminating premature abstraction, YAGNI violations, and boilerplate, while keeping all safety invariants (validation, error handling, security) 100% intact.
-
----
-
-### Core Principle
-
-> **The best code is code you don't write.**\
-> Write only what the task strictly needs. Lazy about the solution, never about reading and understanding.
-
----
-
-### The 7-Rung Decision Ladder
-
-**Before writing ANY code**, stop and check each rung in order. Stop at the first rung that holds:
-
-```text
-1. Does this need to exist?
-   → No: YAGNI — skip it entirely. Don't build for "future use."
-
-2. Already in this codebase or component library?
-   → Yes: Reuse it. Don't rewrite. Call the existing function/component/module.
-   → For UI: Check shadcn/ui FIRST. Before building a complex UI element from scratch, check if it exists in the component library. If yes, generate the install command: npx shadcn@latest add dialog — never manually rewrite what shadcn already provides.
-
-3. Standard library does it?
-   → Yes: Use it. Don't write formatDate() — use Intl.DateTimeFormat or dayjs.
-
-4. Native platform feature?
-   → Yes: Use it. Don't install flatpickr when <input type="date"> exists.
-   → Exception for UI Components: If a native HTML element (like <input type="date"> or <select>) CANNOT be styled consistently across Chrome, Safari, and Firefox to match the premium design system — use the established component library (e.g., shadcn/ui <DatePicker>, <Select>) instead. Cross-browser inconsistency is a legitimate reason to NOT use native.
-
-5. Already-installed dependency?
-   → Yes: Use it. Don't install a new library to do what an existing one can.
-
-6. Can it be done in one line?
-   → Yes: One line. No abstraction layer needed.
-
-7. Only then: write the MINIMUM that works.
-   → No classes when a function works. No module when an inline does.
-```
-
----
-
-### The Rule of Three (Do Not Abstract Early)
-
-- **First occurrence**: Write it inline directly where it is needed.
-- **Second occurrence**: Duplicate it cleanly. Duplication is cheaper than the wrong abstraction.
-- **Third occurrence**: Only now extract a shared helper or utility.
-
----
-
-### 10 Concrete Over-Engineering Red Flags
-
-1. Creating a `GenericRepository<T>` when you only have 2 database tables.
-2. Creating a custom state machine or complex reducer for 2 boolean flags.
-3. Adding a configuration file or environment variables for values that never change.
-4. Writing custom retry/circuit-breaker logic when native `fetch` or SDK already handles it.
-5. Building a generic `BaseService` with 15 hook methods implemented by only one class.
-6. Wrapping every standard library call in a custom helper class (`StringUtils`, `DateUtils`, `ObjectUtils`).
-7. Creating a multi-level folder structure (`domains/auth/adapters/driving/rest/controllers/dto/`) for a 30-line microservice.
-8. Writing custom mock frameworks when Vitest/Jest/Node test runner provide standard mocks.
-9. Installing a 50KB npm package for a 3-line utility (e.g. `left-pad`, `is-number`, `deep-clone`).
-10. Pre-optimizing caching and indexing for endpoints serving 10 requests a day.
-
----
-
-### The Sacred Exceptions (NEVER Cut These)
-
-The ladder applies to features and abstractions. These 4 areas are **non-negotiable** and **never simplified away**:
-
-#### 1. Input Validation
+This runnable example defines a protected update operation around a supplied
+persistence function. The caller must obtain the session through trusted
+server-side authentication. The sample schema covers only name/email; adapt it
+to the real product schema, error contracts, and tenant model.
 
+<!-- example: ponytail-update -->
 ```javascript
-// [GOOD] Always validate — even if "internal" API
-function createUser(data) {
-  if (!data.email || !isValidEmail(data.email)) {
-    throw new ValidationError('Invalid email');
-  }
-  return db.insert('users', data);
-}
-
-// [BAD] Never skip validation for "speed"
-function createUser(data) {
-  return db.insert('users', data); // NEVER
+export function createUserUpdater(update) {
+  if (typeof update !== 'function') throw new TypeError('Persistence function required');
+  return async function updateUser(id, data, session) {
+    if (typeof id !== 'string' || !id || session?.userId !== id) {
+      throw new Error('Forbidden');
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      throw new TypeError('Invalid update payload');
+    }
+    const keys = Object.keys(data);
+    if (!keys.length || keys.some(key => !['name', 'email'].includes(key))) {
+      throw new TypeError('Unknown or empty update fields');
+    }
+    const parsed = {};
+    if (Object.hasOwn(data, 'name')) {
+      if (typeof data.name !== 'string' || !data.name.trim() || data.name.length > 100) {
+        throw new TypeError('Invalid name');
+      }
+      parsed.name = data.name;
+    }
+    if (Object.hasOwn(data, 'email')) {
+      if (typeof data.email !== 'string' || data.email.length > 254 ||
+          !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email)) {
+        throw new TypeError('Invalid email');
+      }
+      parsed.email = data.email;
+    }
+    return update({ where: { id }, data: parsed });
+  };
 }
 ```
 
-#### 2. Error Handling
-
-```javascript
-// [GOOD] Always handle errors explicitly
-async function fetchUser(id) {
-  try {
-    const user = await db.findById(id);
-    if (!user) throw new NotFoundError(`User ${id} not found`);
-    return user;
-  } catch (err) {
-    logger.error('fetchUser failed', { id, err });
-    throw err;
-  }
-}
-```
-
-#### 3. Security Checks
-
-- Authorization check BEFORE every query or mutation.
-- Parameterized queries everywhere — zero string concatenation in SQL.
-- Strict sanitization of all rendered HTML and markdown.
-
-#### 4. Type Safety & Behavioral Tests
-
-- Strict TypeScript types — no `any` evasion.
-- Tests covering happy path, 4xx, and 5xx edge cases.
-
----
-
-## Code Examples
-
-### Native Platform vs Over-Built Package
-
-**Over-build**:
-
-```bash
-npm install flatpickr
-# Creates DatePickerWrapper.jsx (45 lines) + useDatePicker.js (30 lines) + styles (60 lines)
-```
-
-**Ponytail approach (rung 4)**:
-
-```html
-<input type="date" name="date" aria-label="Appointment date" />
-```
-
-### Next.js App Router Server Action vs REST Endpoint
-
-```typescript
-// Instead of /api/users/[id]/route.ts + custom fetch wrapper:
-"use server";
-
-export async function updateUser(id: string, data: UpdateUserInput) {
-  const session = await getSession(); // auth check — never skip
-  if (session?.userId !== id) throw new Error("Forbidden");
-  return db.users.update(id, data);
-}
-```
-
----
-
-## Validation Checklist
-
-- [ ] Every new dependency has been verified: cannot be solved with native platform or existing dependencies.
-- [ ] No single-use abstractions, wrappers, or interfaces created.
-- [ ] Sacred exceptions preserved: 100% input validation, explicit error handling, security checks intact.
-- [ ] All code written passes all existing unit and integration tests.
-
----
-
-## Common Mistakes
-
-- **Cutting validation to write less code**: The goal is less architecture/boilerplate, never less safety.
-- **Creating utilities "for future use"**: Only write utilities when used 3+ times.
-- **Rewriting component libraries**: Building custom modals, tabs, or tooltips from scratch when shadcn/ui or Radix is already in the project.
-
----
+The verifier runs this block with an injected persistence function and asserts
+that denied users, invalid emails, and unknown privilege fields never reach it.
+This is boundary evidence, not proof of a live database or authentication setup.
 
-## Integration Notes
+## Verification checklist
 
-- Applies during substantive Build work and reviews of implementation complexity.
-- Enforces minimalism alongside `system-design` (think at scale, implement minimally).
-- Pairs with `impeccable-design` for UI tasks.
+- Each dependency or abstraction solves an inspected requirement.
+- Protected inputs and operations retain their checks.
+- Errors have a meaningful contract; avoid redundant catch/log/rethrow layers.
+- Behavior checks cover relevant success and failure cases.

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

@@ -1,64 +1,28 @@
-# Application Security Examples — Anti-patterns vs ContextOS Standard
+# Security boundary examples
 
-## Example 1: Timing-Safe Secret Verification
+## Protected document mutation
 
-### Anti-pattern: Anti-pattern (Vulnerable to side-channel timing attack)
+Illustrative integration sketch: authenticate through trusted middleware, check
+the tenant role permits the action, and scope the query by document ID and trusted
+tenant ID. Return the established denied/missing response when no accessible
+document matches. Tenant membership alone may not permit deletion.
 
-```typescript
-// BAD: string comparison returns early on the first mismatched byte
-export function verifyApiKey(providedKey: string, storedKey: string): boolean {
-  return providedKey === storedKey; // Vulnerable to timing analysis!
-}
-```
-
-### Best practice: ContextOS Standard (Constant-time buffer comparison)
+Do not report a working endpoint from a sketch with assumed ORM/middleware.
+Verify another user's or tenant's document is inaccessible before persistence.
 
-```typescript
-// GOOD: crypto.timingSafeEqual executes in constant time
-import crypto from 'crypto';
+## Executable controls
 
-export function verifyApiKey(providedKey: string, storedKey: string): boolean {
-  const providedBuffer = Buffer.from(providedKey, 'utf8');
-  const storedBuffer = Buffer.from(storedKey, 'utf8');
+The original runnable HMAC and partner-fetch blocks are in [SKILL.md](SKILL.md).
+The verifier extracts these blocks rather than manually maintained copies.
+Checks cover signatures and URL scheme, credentials, host, port, transport, and
+redirect policy. Egress, DNS, and replay defenses need separate integration tests.
 
-  if (providedBuffer.length !== storedBuffer.length) {
-    return false;
-  }
+## Source-checkout scanner
 
-  return crypto.timingSafeEqual(providedBuffer, storedBuffer);
-}
+```powershell
+node bin/index.js scan --staged --enforce --placeholders
 ```
 
----
-
-## Example 2: Preventing IDOR (Insecure Direct Object Reference)
-
-### Anti-pattern: Anti-pattern (Trusting client ID without ownership check)
-
-```typescript
-// BAD: any authenticated user can delete any other user's document!
-app.delete('/api/documents/:id', requireAuth, async (req, res) => {
-  await prisma.document.delete({ where: { id: req.params.id } });
-  res.status(204).end();
-});
-```
-
-### Best practice: ContextOS Standard (Multi-tenant scoped authorization check)
-
-```typescript
-// GOOD: document deletion is strictly scoped to authenticated user or org
-app.delete('/api/documents/:id', requireAuth, async (req, res) => {
-  const deleted = await prisma.document.deleteMany({
-    where: {
-      id: req.params.id,
-      organizationId: req.user.organizationId, // Tenant isolation
-    },
-  });
-
-  if (deleted.count === 0) {
-    return res.status(404).json({ error: 'Document not found or access denied' });
-  }
-
-  return res.status(204).end();
-});
-```
+This checks staged secrets and placeholders. Supply --scope <file> with the
+actual scope JSON for write boundaries. Inspect unstaged changes separately.
+An empty index does not prove a candidate contains no unsafe code.