contextos-agents 2.3.1 → 2.3.2

package/.agents/generated/claude/skills/gemini-precision/TROUBLESHOOTING.md

@@ -1,25 +1,12 @@
-# gemini-precision Troubleshooting & Common Failure Modes
-
-## 1. Test Failure Investigation (No Guesswork)
-
-- **Symptom**: Test fails during `npm test` after code modifications.
-- **Root Cause**: Trying to patch the code without reading the exact assertion diff.
-- **Fix**: Never guess the fix. View the test file line where assertion failed, inspect expected vs actual output, and resolve the root discrepancy.
-
-## 2. Accidental Staged Secrets or Placeholders
-
-- **Symptom**: `contextos scan --staged --enforce` fails with exit code 1.
-- **Root Cause**: Committed temporary `.env` file or left an unfinished `// TODO: implement later` stub in added lines.
-- **Fix**: Remove or redact the secret before committing. Fully implement the logic or replace the placeholder with an explicit tracked issue rather than committed code stubs.
-
-## 3. Scope Creep and Excessive Blast Radius
-
-- **Symptom**: Unrelated files reformatted or imports reordered across the repository.
-- **Root Cause**: Full-file rewrite instead of targeted surgical replacement.
-- **Fix**: Use targeted chunks that touch only the lines specified in the task plan. Avoid modifying unrelated styling or formatting.
-
-## 4. Forbidden Long Dashes
-
-- **Symptom**: Linter or compliance check flags unicode dashes in text.
-- **Root Cause**: Using typography dashes (`\u2014` or `\u2013`) instead of standard ASCII hyphens.
-- **Fix**: Replace all em-dashes and en-dashes with standard ASCII hyphens (` - `) or appropriate punctuation (parentheses, commas, colons).
+# Gemini execution troubleshooting
+
+- A test fails: inspect the assertion and actual caller behavior, fix the root
+  cause, and rerun relevant checks.
+- A scan misses a stub: placeholder checks require --placeholders; scope checks
+  require --scope <file>. Use an actual staged candidate for a staged scan.
+- Scope grows: inspect callers, explain necessary additions, preserve unrelated
+  formatting and local changes.
+- Context drifts: keep a short persistent plan for substantial work and update
+  it as evidence changes.
+- Typography preference differs: follow the user's or repository's style; this
+  skill does not define a universal ban on Unicode punctuation.

package/.agents/generated/claude/skills/gemini-precision/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/gstack-roles/EXAMPLES.md

@@ -1,23 +1,7 @@
-# gstack-roles Examples — Anti-patterns vs ContextOS Standard
+# gstack-roles compatibility examples
 
-## Example 1: Specialist Persona Activation
+Use the canonical [engineering-workflow](../engineering-workflow/SKILL.md). An explicit resolver
+request for gstack-roles redirects to engineering-workflow; the warning explains the mapping.
+A directly loaded alias should follow the same canonical instructions.
 
-### Anti-pattern: Undifferentiated Generalist Response
-
-```text
-User: "Should we migrate our monolithic PostgreSQL database to MongoDB?"
-Agent: Gives a vague 5-paragraph summary listing pros and cons of both without making a recommendation.
-```
-
-### Best practice: ContextOS Standard (Architect Role Declaration)
-
-```markdown
-[DOMAIN: Architecture] [PHASE: Plan] [ROLE: Database Architect]
-Skills loaded: database, system-design, decisions
-
-### Recommendation: Stay with PostgreSQL. Do NOT migrate to MongoDB.
-1. Data Integrity: Your domain model has high relational complexity (orders -> items -> shipments -> payments).
-2. Transactional Consistency: MongoDB multi-document ACID transactions introduce significant latency overhead compared to Postgres native WAL.
-3. JSON Support: PostgreSQL JSONB handles document storage and indexing natively if semi-structured flexibility is needed.
-Decision: Draft ADR 0004-retain-postgresql-with-jsonb.md.
-```
+An authorization review can use correctness and security perspectives without role banners. Those perspectives do not create an independent reviewer.

package/.agents/generated/claude/skills/gstack-roles/SKILL.md

@@ -2,32 +2,30 @@
 
 ## Overview
 
-Use specialist perspectives when they reveal concrete issues. The canonical lifecycle skill is engineering-workflow.
+Deprecated compatibility identifier. Use [engineering-workflow](../engineering-workflow/SKILL.md) for the canonical instructions.
 
 ## When to Use
 
-Explicit role guidance or a specialist review request.
+An existing configuration or user explicitly names gstack-roles.
 
 ## Rules & Patterns
 
-Choose the useful perspective: product scope, architecture, implementation, QA, security, or release. Role declarations are optional. Repeated headers and mandatory role switches add no evidence. Existing authorization and routine fast tracks apply.
-
-Read [references/roles.md](references/roles.md) for detailed procedures and examples only when needed.
+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
 
-For access control, use the security perspective to examine authorization boundaries and negative cases.
+Explicit gstack-roles selection resolves to engineering-workflow; inspect the resolver result rather than assuming both bodies were loaded.
 
 ## Validation Checklist
 
-- [ ] The requested outcome is handled.
-- [ ] Relevant verification and safety boundaries are preserved.
-- [ ] Limitations are stated.
+- [ ] Canonical guidance is used.
+- [ ] Alias resolution adds no duplicate body.
+- [ ] Evidence scope and limitations are stated.
 
 ## Common Mistakes
 
-Repeated approval after authorization; unnecessary ceremonies for routine edits; treating role labels or string checks as behavioral proof.
+Treating this compatibility name as an independent engine or a mandatory ceremony.
 
 ## Integration Notes
 
-Load relevant domain skills and supporting resources on demand. Compatibility identifiers remain available.
+Keep legacy links available. Read [references/roles.md](references/roles.md) only for compatibility details.

package/.agents/generated/claude/skills/gstack-roles/TROUBLESHOOTING.md

@@ -1,13 +1,7 @@
-# gstack-roles Troubleshooting & Common Mistakes
+# gstack-roles compatibility troubleshooting
 
-## 1. Persona Abandonment
-
-- **Symptom**: Agent stops declaring its role and drifts back into generic assistant voice.
-- **Root Cause**: Not declaring role headers at the start of multi-turn conversations.
-- **Fix**: Always open every major response with the ContextOS status banner: [DOMAIN: ...] [PHASE: ...] [ROLE: ...].
-
-## 2. Mismatched Role Authority
-
-- **Symptom**: Junior Developer persona trying to override Architectural Decisions without ADR review.
-- **Root Cause**: Role boundary confusion.
-- **Fix**: Respect hierarchy: Product Manager owns scope, Architect owns topology, Senior Dev owns implementation.
+- Duplicate process: load the canonical engineering-workflow 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.

package/.agents/generated/claude/skills/gstack-roles/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/gstack-roles/references/roles.md

@@ -1,149 +1,5 @@
+# gstack-roles compatibility reference
 
-# gstack-roles
+Canonical guidance: [engineering-workflow](../../engineering-workflow/SKILL.md).
 
-## Overview
-
-Specialist persona orchestrator defining 23 domain roles (Product Manager, Architect, Senior Developer, QA Lead, Chief Security Officer, etc.). Enforces mindset transitions across engineering pipeline phases.
-
-## When to Use
-
-Activate on every task to declare explicit specialist role and mindset before beginning DEFINE, PLAN, BUILD, VERIFY, REVIEW, or SHIP phases.
-
-## Rules & Patterns
-
-Inspired by [Garry Tan's gstack](https://github.com/garrytan/gstack) - structured persona transitions across engineering phases.
-
-## Core Principle
-
-> Before starting ANY task, identify your current role. You are not a generic AI. You are a specialist. Think and act accordingly.
-
-## Role Identification Protocol
-
-At the start of each task or major phase switch, declare your role using the ContextOS standard format:
-
-```text
-[DOMAIN: <Domain>] [PHASE: <Phase>] [ROLE: <Role Name>]
-Skills loaded: <skill-1>, <skill-2>
-```
-
-> **Anti-Spam Invariant**: Declare this role header **strictly once per phase**. Never prefix intermediate tool calls, file operations, or step updates with role tags.
-
-Then execute ONLY within the constraints of that role.
-
----
-
-## The 23 Specialist Roles
-
-### Strategy & Planning
-
-| Role | Mandate | When to Activate |
-| ------ | --------- | ----------------- |
-| **CEO / Founder** | Rethink the problem. Find the 10-star product hiding inside the request. Challenge scope. | Feature planning, product decisions |
-| **YC Office Hours** | Ask 6 forcing questions that reframe the product before writing code. Push back on framing. | Before any new feature starts |
-| **Product Manager** | Define requirements as user stories. Prioritize ruthlessly. Ship the narrowest wedge first. | Requirement gathering |
-| **Architect** | Lock in architecture, data flow, diagrams, edge cases. Force hidden assumptions into the open. | System design, tech stack decisions |
-
-### Engineering
-
-| Role | Mandate | When to Activate |
-| ------ | --------- | ----------------- |
-| **Engineering Manager** | Break work into atomic tasks. Review test plans. Run retrospectives. | Sprint planning, reviews |
-| **Staff Engineer** | Find bugs that pass CI but blow up in production. Auto-fix the obvious. Flag gaps. | Code review |
-| **Senior Developer** | Write production-quality code. Follow architecture decisions. Test everything. | Implementation |
-| **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. | Bug fixing |
-| **Performance Engineer** | Baseline metrics. Core Web Vitals. Resource sizes. Compare before/after. | Optimization |
-| **Developer Experience Lead** | Benchmark onboarding speed. Find friction. Design the magical moment. | DX review |
-
-### Design
-
-| Role | Mandate | When to Activate |
-| ------ | --------- | ----------------- |
-| **Senior Designer** | Rate each design dimension 0-10. Detect AI slop. Interactive: one question per design choice. | Design review, UI tasks |
-| **Design Engineer** | Turn mockups into production HTML/CSS that actually works. 30KB, zero deps where possible. | Frontend implementation |
-| **Design Explorer** | Generate 4-6 design variants. Open comparison. Iterate until user loves it. | Design ideation |
-
-### Quality & Security
-
-| Role | Mandate | When to Activate |
-| ------ | --------- | ----------------- |
-| **QA Lead** | Test the app, find bugs, fix with atomic commits, re-verify, write regression tests. | Before shipping |
-| **QA Reporter** | Pure bug report only. No code changes. | Bug reporting |
-| **Chief Security Officer** | OWASP Top 10 + STRIDE threat model. Zero-noise: 8/10+ confidence gate. Each finding needs exploit scenario. | Security audit |
-
-### Operations & Release
-
-| Role | Mandate | When to Activate |
-| ------ | --------- | ----------------- |
-| **Release Engineer** | Sync main, run tests, audit coverage, push, open PR. Bootstrap test frameworks if missing. | Before shipping |
-| **SRE** | Post-deploy monitoring loop. Watch for console errors, performance regressions, failures. | After deploy |
-| **Technical Writer** | Update all docs to match what shipped. Catch stale READMEs. Build Diataxis coverage map. | After feature ships |
-
-### Research & Memory
-
-| Role | Mandate | When to Activate |
-| ------ | --------- | ----------------- |
-| **Researcher** | Investigate root causes systematically. No fixes without understanding. Max 3 hypothesis cycles. | Unknown problems |
-| **Memory Manager** | Manage learnings across sessions. Review, search, prune, export project patterns. | Session start/end |
-| **Spec Author** | Turn vague intent into precise executable specs in 5 phases: why, scope, technical, draft, file. | Before planning |
-| **Retro Facilitator** | Per-person breakdowns, shipping streaks, test health trends, growth opportunities. | End of sprint |
-
----
-
-## Sprint Lifecycle
-
-Every change follows this lifecycle, with a specific role per phase:
-
-```
-THINK          PLAN           BUILD          REVIEW         TEST           SHIP
-[YC Hours]   [Architect]   [Sr Developer]  [Staff Eng]   [QA Lead]    [Release Eng]
-[CEO]        [Eng Mgr]                     [Designer]    [Sec Officer]
-```
-
-## Role-Switching Rules
-
-1. **Use proportional phases.** Scope substantial work; routine edits can proceed directly.
-2. **One role at a time.** Don't mix QA and implementation in the same response.
-3. **Declare when helpful.** Role labels are optional communication aids.
-4. **Escalate correctly.** If a QA finds an architectural problem → escalate to Architect role.
-5. **The CEO always goes last on planning** - challenges scope reduction before committing.
-
-## Example Usage
-
-```
-User: "Add a notifications feature"
-
-[ROLE: YC Office Hours]
-Before I plan this, 6 forcing questions:
-1. What pain does the ABSENCE of notifications cause today?
-2. Who specifically gets notified? What's the trigger?
-...
-
-[ROLE: CEO / Founder]
-I'm going to push back on "notifications feature."
-What you actually described is a user re-engagement system.
-The narrowest wedge: one email on task completion.
-Ship that tomorrow. The full vision is a 3-month project.
-
-[ROLE: Architect]
-For the narrow wedge:
-- Event: task.completed → webhook → email queue (Redis)
-- No real-time needed for MVP
-- Schema: notifications(id, user_id, type, payload, sent_at)
-```
-
-
-## Code Examples
-
-See `EXAMPLES.md` for detailed code examples.
-
-## Validation Checklist
-
-What to verify during the review phase before completing the task.
-
-## Common Mistakes
-
-Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
-
-## Integration Notes
-
-How this skill interacts with other skills.
+Useful review perspectives are product scope, architecture, implementation, QA, security, and release. Choose only those relevant to the inspected change. Role declarations are optional, and switching roles within one model is self-review. Ask for missing material decisions instead of a fixed six-question interview.

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

@@ -1,45 +1,12 @@
-# ponytail-mindset Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Data Formatting and Manipulation
-
-### Anti-pattern: Over-engineered Custom Utility Class
-
-```typescript
-// BAD: 40 lines of boilerplate for relative date formatting
-export class DateFormatterService {
-  private static instance: DateFormatterService;
-  public static getInstance() { /* singleton boilerplate */ }
-  public formatRelative(date: Date): string {
-    const diff = Date.now() - date.getTime();
-    // 30 lines of manual math, plurals, and string building
-  }
-}
-```
-
-### Best practice: ContextOS Standard (Standard Library Native API)
-
-```typescript
-// GOOD: Native Intl API, zero bundle cost, handles all locales
-export const formatRelativeTime = (date: Date, locale = 'en'): string => {
-  const diffDays = Math.round((date.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
-  return new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(diffDays, 'day');
-};
-```
-
----
-
-## Example 2: Component Library Reuse
-
-### Anti-pattern: Hand-rolled Modal from Scratch
-
-```text
-BAD: Writing custom overlay DOM, manual scroll locking, manual focus trapping,
-and custom keydown listeners. Burns 300+ lines of fragile code.
-```
-
-### Best practice: ContextOS Standard (Leverage Established Primitives)
-
-```bash
-# GOOD: Install battle-tested primitive that handles ARIA, portals, and keyboard navigation
-npx shadcn@latest add dialog
-```
+# Minimalism examples
+
+- Formatting: use Intl.DateTimeFormat, Intl.RelativeTimeFormat, or the existing
+  formatter after verifying locale, timezone, invalid-date, and rounding needs.
+  A snippet's length is not a measured bundle or accuracy guarantee.
+- UI: reuse the installed component library when it meets accessibility and
+  interaction requirements. Use a native control when it meets those requirements.
+- Protected writes: see the executable updater in
+  [references/minimalism.md](references/minimalism.md). Copying arbitrary payload
+  fields into persistence does not satisfy minimalism or security.
+- Refactoring: a small named function can be clearer than repeated inline logic,
+  even before its third use.

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

@@ -6,31 +6,28 @@ Reduce unnecessary code and dependencies without weakening correctness or securi
 
 ## When to Use
 
-Substantive implementation and refactoring during Build.
+Substantive implementation, refactoring, and reviews of complexity.
 
 ## Rules & Patterns
 
-Before adding code, check whether the feature is needed and whether existing code, the standard library, the platform, or an installed dependency handles it. Then implement the smallest readable solution. Avoid premature abstractions. Preserve validation, authorization, parameterized queries, meaningful error handling, and required tests.
+Before adding code, consider YAGNI, project reuse, the standard library, native platform features, installed dependencies, a readable one-liner, then the minimum maintainable code. Preserve validation, authorization, parameterized queries, meaningful errors, and required checks. Single-use helpers are allowed when they clarify a concept or boundary.
 
-The 7-rung ladder: YAGNI; reuse project code; standard library; native platform;
-installed dependencies; a readable one-liner; the minimum maintainable code.
-
-Read [references/minimalism.md](references/minimalism.md) for detailed procedures and examples only when needed.
+Read [references/minimalism.md](references/minimalism.md) when a tradeoff needs detail.
 
 ## Code Examples
 
-Reuse the existing date formatter. A shorter database query still needs authorization and validated input.
+Reuse the installed date formatter. An update endpoint still validates its payload and checks ownership before writing.
 
 ## Validation Checklist
 
-- [ ] The requested outcome is handled.
-- [ ] Relevant verification and safety boundaries are preserved.
-- [ ] Limitations are stated.
+- [ ] The requested outcome and applicable failure cases are checked.
+- [ ] Evidence names commands, results, scope, and limitations.
+- [ ] Unrelated changes and existing authorization are preserved.
 
 ## Common Mistakes
 
-Repeated approval after authorization; unnecessary ceremonies for routine edits; treating role labels or string checks as behavioral proof.
+Code-golf; deleting safety checks; choosing a new component library by default; duplicating access-control logic solely to obey a reuse count.
 
 ## Integration Notes
 
-Load relevant domain skills and supporting resources on demand. Compatibility identifiers remain available.
+engineering-workflow chooses verification by risk; security defines protected boundaries. This skill chooses implementation size and readability.