contextos-agents 2.3.1 → 2.3.2

package/.agents/core/skills/engineering-workflow/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/engineering-workflow/references/workflow.md

@@ -1,336 +1,74 @@
+# Proportional engineering workflow
 
-# engineering-workflow
+## Choose checks by risk
 
-## Overview
+| Work | Process | Evidence |
+| --- | --- | --- |
+| Routine docs, formatting, low-risk config | Inspect, edit, targeted verification | Relevant formatter, validator, or smoke check |
+| Feature or bugfix | Short plan, implement, behavior checks, self-review | Changed behavior and callers, relevant integration tests |
+| Auth, payments, migrations, concurrency | Acceptance criteria, plan, bounded change, regression checks, review | Allowed and denied cases, failure paths, relevant project gates |
+| Destructive operation | Confirm existing authority and bounds, backup/rollback, guarded action, verify | State before/after and recovery evidence |
 
-Systematic 6-phase engineering pipeline (DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP) enforcing role declarations, atomic task execution, quality gates, regression prevention, and structured requirements elicitation.
+Risk classification is a routing aid. Inspect the actual operation; do not treat
+an inferred low-risk label as authorization or permission to remove safety checks.
 
-## When to Use
+## Define and plan
 
-Activate on all project tasks to orchestrate structured development, spec definition, architectural planning, and verification gates.
+For substantial changes record the outcome, in-scope work, acceptance cases,
+affected code/callers, dependencies, and relevant verification. Resolve only
+missing material decisions. Keep user authorization across phases; do not stop
+again merely because a spec or plan now exists.
 
-## Rules & Patterns
+Prefer independently useful vertical slices when possible. For a referral
+feature, start with one minimal service/API/UI path, verify it, then add expiry
+and abuse controls. Infrastructure-only work can have infrastructure-only steps.
+Update the plan when an inspected caller must change within the authorized scope.
 
-Inspired by [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) by Addy Osmani (Google Chrome) and [obra/superpowers](https://github.com/obra/superpowers).
+## Implement and verify
 
-### Core Principle
+Read before editing. Preserve unrelated work. Use a failing regression test first
+when it clearly captures a bug or logic change; TDD is a technique, not a required
+ceremony for every file. Docs/config may need a validator or smoke run instead.
+Do not add tests that merely repeat implementation or count strings as behavior.
+Do not claim a real integration is implemented using a stub. Commit only when
+requested or required by the repository workflow; an atomic slice does not
+itself require a commit.
 
-> **A junior writes code immediately. A senior writes a spec first.**\
-> Establish scope before substantial changes and carry existing authorization forward.
+Run relevant checks, examine failures, and repair introduced regressions. State
+pre-existing failures, unavailable environments, and unrun checks separately.
+Do not silently expand the feature or remove a check to obtain a green result.
 
----
+## Review and simplify
 
-### The 6-Phase Development Pipeline
+Compare the diff to acceptance criteria, callers, and applicable security and
+performance boundaries. Prefer readable code and existing facilities. A helper
+used once is acceptable when it names a concept, isolates a boundary, or makes
+verification clearer. Reuse counts alone do not determine good abstractions.
+Role changes within one model are self-review, not independent peer review.
 
-```
-  DEFINE          PLAN           BUILD          VERIFY         REVIEW          SHIP
- ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
- │ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │  QA  │ ───▶ │  Go  │
- │Refine│      │  PRD │      │ Impl │      │Debug │      │ Gate │      │ Live │
- └──────┘      └──────┘      └──────┘      └──────┘      └──────┘      └──────┘
-   /spec          /plan          /build        /test         /review       /ship
-
-[ROLE: Product Manager]  [ROLE: Architect]  [ROLE: Senior Dev]  [ROLE: QA Lead]  [ROLE: Staff Eng]  [ROLE: Release Eng]
-```
-
-**Workflow rule**: Scope substantial work before implementation. Existing authorization, standalone requests, and routine fast tracks permit proceeding directly.
-**Direct Build & Fast-Track Exception**: When the prompt/caller explicitly requests a standalone implementation, declares `[PHASE: Build]`, or requests routine operational/maintenance tasks (git operations, version bumps, typo fixes, small config tweaks, diagnostic checks), proceed directly to execution without conversational approval pauses.
-
----
-
-### Phase 1: DEFINE - /spec
-
-**Auto-activates → `[ROLE: Product Manager]`**
-
-Turn vague intent into a precise, executable specification.
-
-#### Step 1.1: The Interview Protocol (`interview-me`)
-
-Before writing the spec, if there is ambiguity, high blast radius, or multiple architectural paths, stop and ask the user **one question at a time** (or up to 2 tightly coupled questions):
-
-1. **Clarify Business Intent**: What user problem are we solving? What is explicitly out of scope?
-2. **Clarify Constraints**: Runtime versions, database engines, performance bounds.
-3. **Clarify Edge Cases**: What happens on offline state, empty lists, unauthorized requests?
-
-#### Step 1.2: Spec Template
-
-```markdown
-## Feature Spec: [Feature Name]
+## Prepare delivery
 
-### Why (Problem)
-[What pain does this solve? Who has it? How often?]
+Update relevant documentation and migration/rollback instructions. Publishing,
+deployment, destructive actions, and external messages require authorization for
+that action unless it is already present. Preparation does not prove deployment.
+Durable project learnings can be recorded when authorized; do not add a required
+learning statement or unrelated memory edits to every completion.
 
-### Scope (What's In / Out)
+## Report evidence
 
-**In-Scope**:
-- [Specific item 1]
-- [Specific item 2]
+Name what changed, why, commands/results, tested scope, and remaining limitations.
+VALIDATION.json describes an evidence-report format, not proof that these rules
+were followed. Structural validation, example tests, and live client behavior
+are different evidence scopes.
 
-**Out-of-Scope**:
-- [Thing we're NOT doing and why]
+For this source checkout:
 
-### Technical Approach
-[Read the relevant code. Understand what changes where.]
-Files affected:
-- `src/X.js` - [what changes]
-- `src/Y.js` - [what changes]
-
-### Acceptance Criteria
-- [ ] Given [context], when [action], then [result]
-- [ ] Given [context], when [action], then [result]
-
-### Open Questions
-- [Unresolved decision 1]
-- [Unresolved decision 2]
+```powershell
+node .agents/ctx.js validate
+node bin/index.js scan --staged --enforce --placeholders
 ```
 
----
-
-### Phase 2: PLAN - /plan
-
-**Auto-activates → `[ROLE: Architect]`**
-
-Break the spec into atomic, independently testable tasks.
-
-#### Thin Vertical Slices (`incremental-implementation`)
-
-Organize tasks as **Thin Vertical Slices** rather than horizontal layers:
-
-- **Bad (Horizontal)**: Task 1: All DB migrations. Task 2: All API routes. Task 3: All UI components. (Nothing works until step 3).
-- **Good (Vertical Slices)**: Slice 1: Minimal DB table + minimal API + minimal UI button end-to-end. Verify and commit. Slice 2: Add validation + edge cases. Slice 3: Polish UI & telemetry.
-
-#### Plan Rules
-
-- Each task must be **completable in < 2 hours** of focused work.
-- Each task must be **independently testable**.
-- Tasks must be **ordered by dependency** (blocking tasks first).
-- Each task gets a **test requirement** - no task without a test.
-
-#### Plan Template
-
-```markdown
-## Implementation Plan: [Feature Name]
-
-### Tasks
-
-**Task 1: [Slice 1 Name]** (est. 30min)
-- What: [Specific implementation detail]
-- Files: [file1.js, file2.js]\
-- Test: [How will you verify this works?]
-- Blocked by: [nothing / Task N]
-
-**Task 2: [Slice 2 Name]** (est. 45min)
-- What: [Specific implementation detail]
-- Files: [file3.js]
-- Test: [Test description]
-- Blocked by: Task 1
-
-### Risk Assessment
-- [Risk 1]: [Mitigation]
-- [Risk 2]: [Mitigation]
-
-### STOP - Awaiting Approval
-Proceed to BUILD when implementation is authorized; clarify missing scope decisions when needed.
-```
-
----
-
-### Phase 3: BUILD - /build
-
-**Auto-activates → `[ROLE: Senior Developer]`**
-
-Implement one task at a time. Commit after each task.
-
-#### Build Rules
-
-1. **One task per commit** - atomic, descriptive commit messages.
-2. **Write the test FIRST** (TDD - red-green-refactor).
-3. **No dead code** - if it's not tested, it's not shipped.
-4. **No TODOs in committed code** - resolve or create a tracked issue.
-5. **Read before writing** - understand the surrounding code before changing it.
-6. **Limit the blast radius** - modify ONLY the files explicitly listed in the current task's plan. Do NOT rewrite adjacent components, hooks, or utilities unless strictly required by the authorized outcome.
-
-#### Commit Message Format
-
-```text
-type(scope): short description (max 72 chars)
-
-- Detail 1
-- Detail 2
-
-Refs: #issue-number
-```
-
-Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
-
----
-
-### Phase 4: VERIFY - /test
-
-**Auto-activates → `[ROLE: QA Lead]`**
-
-Tests are proof, not an afterthought.
-
-#### Test Strategy by Code Type
-
-**Logic & Services (TDD)**:
-
-```text
-1. RED:      Write a failing test for the next small behavior
-2. GREEN:    Write the minimum code to make it pass
-3. REFACTOR: Clean up without breaking tests
-4. REPEAT
-```
-
-**UI Components & User Flows (BDD)**:
-
-For complex React components, prioritize testing _user behavior_ over internal state:
-
-- Use **React Testing Library** (`userEvent`, `screen.getByRole`) - test what the user sees.
-- Use **Playwright** for critical user flows (login, checkout, form submit).
-- Do NOT test implementation details (internal state, private methods, component structure).
-- Focus on: "When user clicks X, does Y appear?" not "Does `useState` hold the right value?"
-
-```tsx
-// [GOOD] BDD: Test behavior
-test("shows error when email is invalid", async () => {
-  render(<LoginForm />);
-  await userEvent.type(screen.getByLabelText("Email"), "not-an-email");
-  await userEvent.click(screen.getByRole("button", { name: /sign in/i }));
-  expect(screen.getByText(/invalid email/i)).toBeInTheDocument();
-});
-```
-
-#### Test Quality Gates
-
-Before moving to Review, verify:
-
-- [ ] All new code has tests
-- [ ] Tests are meaningful (not just coverage theater)
-- [ ] Edge cases are covered (null, empty, overflow, unauthorized)
-- [ ] Tests fail when the implementation is broken (anti-regression)
-- [ ] Test names are readable: `it("returns 404 when user not found")`
-
----
-
-### Phase 5: REVIEW - /review
-
-**Auto-activates → `[ROLE: Staff Engineer]` + `[ROLE: Senior Designer]` for UI tasks**
-
-Review before merging. Always.
-
-#### Subagent / Peer Code Review Protocol
-
-Inspired by [obra/superpowers](https://github.com/obra/superpowers):
-
-1. **Self-Review First**: The implementer runs git diff and verifies against the original acceptance criteria.
-2. **Review Checklist**:
-   - **Correctness**: Does it do what the spec says? Are all criteria met?
-   - **Architecture**: Single Responsibility, DRY without premature abstraction, no business logic in API routes.
-   - **Security**: No secrets hardcoded, inputs validated via Zod/schemas, auth checked before data access.
-   - **Performance**: No N+1 queries, expensive operations cached, sets paginated.
-   - **Design**: If UI, passes `impeccable-design` quick audit (typography, colors, spacing, animations).
-
----
-
-### Phase 5.5: SIMPLIFY - /simplify
-
-**Auto-activates → `[ROLE: Staff Engineer]` (Ponytail Mindset)**
-
-Before merging, ruthlessly simplify:
-
-1. Did we introduce abstractions that are only used once? (Inline them).
-2. Can 3 lines of standard JavaScript replace a 50-line custom utility?
-3. Is any configuration or generic handler premature? (YAGNI).
-4. Is the code obvious to a mid-level engineer without reading a documentation manual?
-
----
-
-### Phase 6: SHIP - /ship
-
-**Auto-activates → `[ROLE: Release Engineer]`**
-
-Only ship when all gates are green.
-
-#### Pre-Ship Checklist
-
-- [ ] All tests pass in CI
-- [ ] No lint errors
-- [ ] Feature works in staging environment
-- [ ] Docs updated (README, API docs, changelogs)
-- [ ] Breaking changes documented
-- [ ] Rollback plan exists
-- [ ] Preview / staging deployment verified (if applicable, e.g. Vercel Preview and Core Web Vitals for frontend deployments)
-
-#### Operational Self-Improvement
-
-Before completing a workflow, review the session for durable learnings. Write them to `.agents/learnings.md`. If no durable learning occurred, state "No durable learnings this session" in your final output.
-
----
-
-## Code Examples
-
-### Vertical Slice Example
-
-```javascript
-// Slice 1: Minimal functional endpoint
-// POST /api/v1/projects -> creates project with basic validation
-import { z } from 'zod';
-import { projectService } from '@/services/project';
-
-const CreateProjectSchema = z.object({
-  name: z.string().min(1).max(100),
-  description: z.string().optional()
-});
-
-export async function POST(req) {
-  const session = await auth();
-  if (!session?.userId) return Response.json({ error: 'Unauthorized' }, { status: 401 });
-
-  const body = await req.json();
-  const parsed = CreateProjectSchema.parse(body);
-  const project = await projectService.create({ ...parsed, userId: session.userId });
-
-  return Response.json(project, { status: 201 });
-}
-```
-
----
-
-## Validation Checklist
-
-- [ ] Specification exists with clear In-Scope and Out-of-Scope boundaries.
-- [ ] Implementation plan broken down into vertical tasks < 2 hours each.
-- [ ] Tests written before implementation (TDD/BDD).
-- [ ] Code reviewed against correctness, security, performance, and design gates.
-- [ ] Staged security and quality check passes (`contextos scan --staged --enforce`).
-- [ ] Simplification ladder executed before shipping.
-
----
-
-## Common Mistakes
-
-- **Writing code before approval**: Skipping `/spec` or `/plan` in interactive sessions.
-- **Horizontal task splitting**: Building all DB models first without verifying end-to-end integration.
-- **Premature refactoring**: Changing unrelated adjacent code during a feature task.
-- **Ignoring non-happy paths**: Testing only 200 OK responses while ignoring 400, 401, 404, 500 scenarios.
-
----
-
-## Integration Notes
-
-- Integrates with `gstack-roles` for automated role switching across all 6 phases.
-- Triggers `ponytail-mindset` during the BUILD and SIMPLIFY phases.
-- Hands off to `impeccable-design` for UI quality review.
-- Coordinates with `security` during Phase 5 for pre-merge compliance.
-
----
-
-## Completion Status Protocol
-
-When completing a task or workflow, you must explicitly report your final status as the last part of your output:
-
-- **DONE** - completed with evidence.
-- **DONE_WITH_CONCERNS** - completed, but list concerns.
-- **BLOCKED** - cannot proceed; state blocker and what was tried.
-- **NEEDS_CONTEXT** - missing info; state exactly what is needed.
+The first command checks skill sources and sync. The second checks staged secrets
+and placeholders. Add --scope <file> only with an actual scope JSON file; an empty
+index does not verify unstaged edits. For a consumer installation use its local
+ContextOS executable rather than assuming these source paths exist.

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

@@ -1,72 +1,52 @@
-# gemini-precision Examples - Anti-patterns vs ContextOS Standard
+# Gemini execution examples
 
-## Example 1: Read-Before-Write Invariant (Zero Assumptions)
+## Inspect before integration
 
-### Anti-pattern: Hallucinated Import and Signature
+Before calling a password helper, read its export and signature. Do not infer a
+package, import path, or return type from an example. Name the checked files and
+run the relevant authentication regression.
 
-```typescript
-// BAD: Assuming the module exists and export is a default function
-import hashPassword from 'src/utils/crypto';
-const hash = hashPassword(password);
-```
-
-### Best practice: ContextOS Standard (Inspected Active Codebase First)
-
-```typescript
-// GOOD: Inspected src/lib/auth.ts via view_file before writing code
-import { hashSecret, ARGON2_CONFIG } from '../lib/auth.js';
-const hash = await hashSecret(password, ARGON2_CONFIG);
-```
-
----
-
-## Example 2: Zero-Placeholder Invariant (Complete Code Only)
-
-### Anti-pattern: Lazy Stubs and Ellipsis Comments
+## Complete pure calculation with an explicit boundary
 
-```typescript
-// BAD: Emitting incomplete code with TODOs and ellipsis
-export function processTransaction(tx: Transaction) {
-  // TODO: validate transaction balance
-  // ... rest of implementation stays here ...
-  return { status: 'ok' };
-}
-```
+This block validates integer minor-unit amounts and computes a proposed balance.
+It does not execute or persist a transfer. A real payment operation also needs
+trusted authorization, concurrency control, idempotency, and a transactional
+persistence boundary. Do not report this function as a completed integration.
 
-### Best practice: ContextOS Standard (100% Drop-in Compilable)
-
-```typescript
-// GOOD: Fully implemented logic with complete error handling
-export function processTransaction(tx: Transaction): TransactionResult {
-  if (!tx.amount || tx.amount <= 0) {
-    throw new ValidationError('Transaction amount must be positive');
+<!-- example: gemini-transfer -->
+```javascript
+export function processTransaction(tx) {
+  if (!tx || typeof tx !== 'object' ||
+      typeof tx.id !== 'string' || !tx.id ||
+      typeof tx.senderId !== 'string' || !tx.senderId) {
+    throw new TypeError('Transaction identity required');
   }
-  if (tx.senderBalance < tx.amount) {
-    throw new InsufficientFundsError(tx.senderId, tx.amount);
+  if (!Number.isSafeInteger(tx.amount) || tx.amount <= 0 ||
+      !Number.isSafeInteger(tx.senderBalance) || tx.senderBalance < 0) {
+    throw new TypeError('Amounts must be safe integer minor units');
   }
+  if (tx.senderBalance < tx.amount) throw new RangeError('Insufficient funds');
   return {
-    status: 'ok',
+    status: 'validated',
     transactionId: tx.id,
     newBalance: tx.senderBalance - tx.amount,
   };
 }
 ```
 
----
+The example verifier rejects NaN, Infinity, fractional/unsafe amounts, and
+insufficient balances. These cases establish the calculation's stated contract.
 
-## Example 3: Mandatory Proof-of-Work Invariant
+## Relevant proof of work
 
-### Anti-pattern: Claiming Task Complete Without Evidence
+For an authorization fix, run an allowed-user case, a denied-user case, and the
+affected integration checks. In this source checkout, skill consistency and
+staged placeholder checks are separate commands:
 
-```text
-BAD: "I have updated the authentication handler. The code looks correct and is ready to merge."
-```
-
-### Best practice: ContextOS Standard (Verified with Automated Gates)
-
-```bash
-# GOOD: Run test suite, staged scanner, and consistency checks
-npm test
-contextos scan --staged --enforce
+```powershell
 node .agents/ctx.js validate
+node bin/index.js scan --staged --enforce --placeholders
 ```
+
+An empty staged index says nothing about unstaged changes. Supply --scope <file>
+when an actual scope JSON file is part of the task.