contextos-agents 2.3.1 → 2.3.2

package/.agents/core/skills/gemini-precision/SKILL.md

@@ -1,174 +1,38 @@
 ---
 name: gemini-precision
-description: >
-  High-precision engineering and execution guardrails optimized for Google Gemini models.
-  Enforces zero-assumption file inspection, complete non-lazy implementations, surgical
-  blast-radius containment, and mandatory proof-of-work execution.
+description: "Execution guidance for Gemini: inspect code, preserve scope, and report relevant verification evidence."
 ---
 
 # gemini-precision
 
 ## Overview
 
-High-precision operational standard designed specifically to harness the high speed and expansive context window of Google Gemini models while eliminating common LLM failure modes: hasty assumptions, partial code placeholders (`// ...`), unverified assertions, and scope creep.
+Apply inspection and execution discipline when working with Gemini. Model-specific quality or performance gains require separate measured comparisons.
 
 ## When to Use
 
-Activate whenever:
-
-- Executing non-trivial code modifications, refactoring, bug fixes, or architecture design.
-- The user requires maximum rigor, reliability, and precision from Gemini.
-- Handling complex multi-file changes where accidental side-effects must be zero.
+Gemini implementation and debugging tasks, or an explicit request for this guidance.
 
 ## Rules & Patterns
 
-### 1. The Read-Before-Write Invariant (Zero Assumptions)
-
-**Never write code based on assumptions about the codebase.**
-
-- Before modifying a function or creating an integration, **always inspect the actual files** using `view_file` or `grep_search`.
-- Check the exact runtime, framework version, and installed dependencies (e.g. React 19 vs 18, Next.js 15 vs 14, Tailwind v4 vs v3, Zod vs Joi) in `package.json` or config files before generating code.
-- Verify imported symbol names and parameter signatures directly from source files.
-
-### 2. The Zero-Placeholder Invariant (Complete Code Only)
-
-**Never produce lazy, incomplete, or stubbed output.**
-
-- ❌ **Forbidden**:
-  - `// TODO: implement logic here`
-  - `// ... rest of existing code ...`
-  - `// ... existing imports ...`
-  - Mock stub returns when real integration is required
-- ✅ **Mandatory**:
-  - Provide **100% complete, fully-implemented, compilable, and drop-in ready** code.
-  - When replacing a block of code, include all necessary imports, type definitions, and edge-case handling.
-
-### 3. The Proof-of-Work Invariant (Verification Before Completion)
-
-**Never claim a task is complete without tool-verified evidence.**
-
-- When modifying code or configuration:
-  1. Run the project validator or compiler (`node .agents/ctx.js validate`, `tsc --noEmit`, etc.).
-  2. Run unit and integration tests (`npm test`, `pytest`, etc.).
-  3. Run linter and formatting checks (`npm run lint:md`, `eslint`, etc.).
-  4. Run staged security and quality scanner (`contextos scan --staged --enforce`).
-- If a test or validation fails, do not guess: read the exact error trace, fix the root cause, and re-run until green.
-
-### 4. Surgical Blast Radius Containment
-
-**Modify ONLY what is strictly necessary.**
-
-- Keep edits isolated to the exact lines, functions, and files specified in the plan.
-- Do not reformat, reorder, or alter indentation of unrelated code blocks.
-- Preserve existing comments, docstrings, and project conventions unless explicitly asked to change them.
-
-### 5. Ponytail Minimalism (YAGNI)
-
-- Prioritize native platform APIs (standard library, browser built-ins) over new npm/pip packages.
-- Follow the "Rule of Three": inline on first use, duplicate cleanly on second, abstract only on third.
-- Keep solutions obvious to a mid-level developer without requiring multi-layered wrapper classes.
-
-### 6. Targeted Tool-Specific Modifications
+Inspect affected source, callers, symbols, runtime versions, and project checks. Implement the authorized behavior completely; never substitute stubs for a required integration. Preserve unrelated code. Choose checks by risk using engineering-workflow. Keep a persistent plan for substantial multi-file work when useful, not for every three tool calls. Explain meaningful decisions; role banners are optional.
 
-**Prevent accidental code loss during file updates.**
-
-- For existing files requiring localized updates (< 50% change), always prefer surgical targeted replacement chunks over destructive full-file rewrites.
-- Never discard unrelated file sections, existing comments, or helper utilities.
-
-### 7. Persistent Context & Plan Tracking
-
-**Prevent context drift during multi-step tasks.**
-
-- When an operation requires more than 3 sequential steps, write and maintain a persistent plan or checklist on disk.
-- Never rely exclusively on volatile conversational memory for tracking complex multi-file refactorings.
-
-### 8. Progressive Step Narration (Transparent Pair Programming)
-
-**Eliminate the "black box" by narrating technical decisions.**
-
-- Avoid executing long, silent chains of tool calls without user visibility.
-- Provide a concise 1-2 sentence transparent status update before key operations:
-  - State what was inspected or verified from the code.
-  - State the architectural decision made and the immediate next action.
-- Keep narration crisp and actionable without excessive verbosity.
-- **Zero-Spam Constraint**:
-  - ❌ **Forbidden**: Starting every intermediate step, tool call, or status update with domain/phase/role tags (e.g. `[DOMAIN: ...] [PHASE: ...] [ROLE: ...]`).
-  - ✅ **Mandatory**: Declare role and phase strictly once at the start of a phase. Intermediate step updates must be clean, natural language sentences describing technical actions directly.
-  - Do not narrate routine micro-inspections (single line reads or basic greps). Announce only meaningful task phases and decisions.
-
----
+Read EXAMPLES.md for a runnable validation example and its limits.
 
 ## Code Examples
 
-### Bad (Lazy Model Output) vs Good (Precision Model Output)
-
-**❌ Bad (Lazy AI Output)**:
-
-```javascript
-// user.service.js
-export async function updateUser(id, data) {
-  // ... existing auth check ...
-  // TODO: validate data with zod
-  return await db.user.update({ where: { id }, data });
-}
-```
-
-**✅ Good (Gemini Precision Output)**:
-
-```javascript
-// user.service.js
-import { z } from 'zod';
-import { db } from '../lib/db.js';
-import { ValidationError, UnauthorizedError } from '../errors/index.js';
-
-const UpdateUserSchema = z.object({
-  name: z.string().min(1).max(100).optional(),
-  email: z.string().email().optional(),
-}).strict();
-
-export async function updateUser(id, data, session) {
-  if (!session?.userId || session.userId !== id) {
-    throw new UnauthorizedError('Access denied: cannot update another user');
-  }
-
-  const parsed = UpdateUserSchema.safeParse(data);
-  if (!parsed.success) {
-    throw new ValidationError('Invalid update payload', parsed.error.format());
-  }
-
-  return await db.user.update({
-    where: { id },
-    data: parsed.data,
-    select: { id: true, name: true, email: true, updatedAt: true }
-  });
-}
-```
-
----
+A validated calculation can be verified in isolation. It does not prove a payment was persisted or executed.
 
 ## Validation Checklist
 
-- [ ] Inspected active codebase files before writing code.
-- [ ] Delivered 100% complete code with zero `// TODO` or `// ...` placeholders.
-- [ ] Ran automated tests and validation with green status.
-- [ ] Confined changes to the minimal required blast radius.
-- [ ] Preserved existing code via targeted edits rather than full-file overwrites.
-- [ ] Persisted multi-step task state and milestones to disk.
-- [ ] Narrated progress with concise, transparent step-by-step updates.
-- [ ] Reported final status with verifiable evidence.
-
----
+- [ ] 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
 
-- **Assuming API contracts**: Guessing function parameters without opening the file.
-- **Premature completion**: Declaring "fixed" without running the test suite.
-- **Uncontrolled refactoring**: Rewriting adjacent components while fixing a 1-line bug.
-
----
+Guessing imports; declaring success without relevant evidence; repeated role banners; running every project gate for a typo; presenting model-specific gains without measurement.
 
 ## Integration Notes
 
-- Pairs with `engineering-workflow` to enforce the 6-phase pipeline.
-- Enforces the 7-rung ladder of `ponytail-mindset`.
-- Acts as the baseline behavioral guardrail across all Gemini and Antigravity operations.
+engineering-workflow owns the lifecycle, ponytail-mindset owns complexity choices, and security owns protected boundaries. This guidance supplements those skills for Gemini.

package/.agents/core/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/core/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/core/skills/gemini-precision/skill.yaml

@@ -1,7 +1,7 @@
 schemaVersion: 2
 name: gemini-precision
 type: instruction-only
-description: High-precision engineering and execution guardrails optimized for Google Gemini models. Enforces zero-assumption file inspection, complete non-lazy implementations, surgical blast-radius containment, and mandatory proof-of-work execution.
+description: "Execution guidance for Gemini: inspect code, preserve scope, and report relevant verification evidence."
 version: 1.0.0
 resources:
   - EXAMPLES.md

package/.agents/core/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/core/skills/gstack-roles/SKILL.md

@@ -1,38 +1,36 @@
 ---
 name: gstack-roles
-description: Compatibility alias for engineering-workflow with optional specialist review perspectives.
+description: "Compatibility alias for engineering-workflow with optional specialist review perspectives."
 ---
 
 # gstack-roles
 
 ## 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/core/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/core/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"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
   ]
 }