contextos-agents 2.3.1 → 2.3.2

package/.agents/core/skills/context-manager/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/context-manager/references/context-rules.md

@@ -1,59 +1,5 @@
-# Context Loading Rules
+# context-manager compatibility reference
 
-Guidelines and deterministic decision tables for selecting, prioritizing, and budgeting context during AI agent execution.
+Canonical guidance: [context-os](../../context-os/SKILL.md).
 
-## Task Type to Document Mapping
-
-| Task Type | Level 1 (Always) | Level 2 (If exists) | Level 3 (Per task) |
-| --- | --- | --- | --- |
-| **New project** | PRD, ROADMAP | ARCHITECTURE, DATABASE, API | UI, TASKS, all relevant skills |
-| **New feature** | PRD | ARCHITECTURE, API | PROJECT_GRAPH, relevant skills |
-| **Frontend** | — | ARCHITECTURE, API | UI, frontend skills |
-| **Backend** | — | ARCHITECTURE, DATABASE, API | backend skills |
-| **Database** | — | ARCHITECTURE, DATABASE | — |
-| **Bugfix** | — | — | PROJECT_GRAPH (affected module only) |
-| **Refactor** | — | ARCHITECTURE | PROJECT_GRAPH, affected skills |
-| **Review** | PRD | ARCHITECTURE | TASKS, all loaded skills |
-| **Deploy** | — | ARCHITECTURE | DEPLOYMENT, infrastructure skills |
-
-## Skill Category to Document Mapping
-
-| Skill Category | Required Documents | Optional Documents |
-| --- | --- | --- |
-| `frontend` | UI.md, API.md | ARCHITECTURE.md |
-| `backend` | API.md, DATABASE.md | ARCHITECTURE.md |
-| `design` | UI.md | PRD.md |
-| `architecture` | ARCHITECTURE.md, DATABASE.md | PRD.md, API.md |
-| `infrastructure` | ARCHITECTURE.md | — |
-| `security` | ARCHITECTURE.md, API.md | DATABASE.md |
-| `testing` | API.md | ARCHITECTURE.md |
-
-## Context Budgeting
-
-To prevent context window saturation and retain maximum LLM reasoning capacity, adhere strictly to the following 4-tier token budget:
-
-| Priority Level | Max Tokens | Contents |
-| --- | --- | --- |
-| 1 (Critical) | 2,000 | Current task description, active brief, and primary skill rules |
-| 2 (Important) | 3,000 | System architecture and API contracts for affected modules |
-| 3 (Context) | 2,000 | Architectural Decision Records (ADRs) and relevant graph nodes |
-| 4 (Background) | 1,000 | PRD summary and global project conventions |
-
-**Total target context budget: ~8,000 tokens per subtask.**
-
-### Degradation Strategy When Over Budget
-
-If accumulated context exceeds the 8,000 token limit:
-
-1. **Trim Level 1 documents** to high-level executive summaries.
-2. **Slice Level 2 documents** to extract only sections matching touched module signatures.
-3. **Preserve Level 3 skills** at full fidelity, as they contain non-negotiable operational instructions and validation guardrails.
-
-## Module-Based Filtering via Dependency Graph
-
-When `PROJECT_GRAPH.md` or `.graphify/graph.json` is present, traverse dependency edges to filter candidate documents:
-
-1. Identify the primary module for the task from the symbol/path mapping.
-2. Resolve immediate inbound and outbound dependencies (`dependencies` and `dependents`).
-3. Include documents solely for the identified module and its immediate dependencies.
-4. Exclude orthogonal domain documents (for example, omit database schemas during purely presentation-layer CSS/layout tasks).
+Use the canonical resolver budget contract and workspace evidence boundaries. Load only relevant documents and source, including callers/tests when necessary. Read lockfiles or generated outputs when dependency, installation, provenance, or build investigations require them. Do not create a separate cache or promise a fixed token saving.

package/.agents/core/skills/context-manager/skill.yaml

@@ -1,9 +1,7 @@
 schemaVersion: 2
 name: context-manager
 type: instruction-only
-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."
 version: 1.0.0
 deprecated: true
 canonical: context-os

package/.agents/core/skills/context-os/EXAMPLES.md

@@ -1,21 +1,31 @@
-# context-os Examples — Anti-patterns vs ContextOS Standard
+# ContextOS command examples
 
-## Example 1: Project Lifecycle Management
+## Source checkout
 
-### Anti-pattern: Ad-hoc Unstructured Development
+These commands run in the ContextOS source repository:
 
-```text
-Coding -> Modifying DB -> Debugging -> Redesigning UI -> Changing Architecture
-All in one unstructured stream of consciousness.
+```powershell
+node .agents/ctx.js resolve "Fix IDOR in document deletion" --files src/auth.ts --json
+node .agents/ctx.js compile --check
+node .agents/ctx.js validate
+node .agents/ctx.js export all --check --json
 ```
 
-### Best practice: ContextOS Standard (Phase-Gated Development)
+After authorized edits to canonical sources, compile then export before checking
+sync. export --check is read-only; export without --check writes managed outputs.
+The resolver returns skills and package evidence, not an automatic code-file
+context package.
 
-```text
-Phase 1: DEFINE (PRD & Requirements)
-Phase 2: PLAN (Atomic Tasks & ADRs)
-Phase 3: BUILD (TDD & Minimalist Implementation)
-Phase 4: VERIFY (Automated Test Proof)
-Phase 5: REVIEW (Design QA & Code Review)
-Phase 6: SHIP (Production Release)
-```
+## Consumer project
+
+Use the installed local ContextOS executable, for example through npx when the
+package is already installed. Do not assume a consumer has this repository's bin
+or scripts directories. Inspect its installation and project-specific checks.
+Create overrides through skill override, inspect skill diff, then compile/export.
+Preserve unmanaged user files and existing overrides.
+
+## Evidence interpretation
+
+A validator pass means source/configuration checks passed. A scanner pass means
+its specified staged checks passed. Neither result proves a live client loaded
+instructions or a model followed them.

package/.agents/core/skills/context-os/SKILL.md

@@ -1,163 +1,40 @@
 ---
 name: context-os
-description: >-
-  Deterministic context compiler and policy engine for AI coding agents.
+description: "Deterministic context compiler and policy engine for AI coding agents."
 ---
 
 # context-os
 
 ## Overview
 
-Deterministic context compiler and policy engine for AI coding agents. Governs repository policy configuration, skill dependency graphs, profile management, and multi-agent configuration export.
+Guide configuration of the ContextOS compiler, resolver, profiles, and agent exports. Executable behavior lives in the CLI and modules; this Markdown entrypoint is guidance.
 
 ## When to Use
 
-Activate when managing project configuration, resolving skill dependencies, compiling rules for editors, or defining repository-level agent standards. (For task-specific file and context budgeting, use `context-manager`).
+Skill selection, context budgets, manifests, project overrides, profiles, exports, and configuration drift.
 
 ## Rules & Patterns
 
-You are the **Context Compiler**. Your job is NOT to know everything. Your job is to **assemble the minimum context** needed for the current task.
+Inspect the active project and installed skills. Canonical sources live in .agents/core/skills; project overrides in .agents/project/skills; plugins provide additional sources. Native .agents/skills contains generated projections. Entrypoint precedence is skill.v2.yaml, skill.yaml, then manifestless SKILL.md. Respect the declared entrypoint and resolve contained resource paths relative to its skill directory.
 
-## Pipeline
-
-When a user gives you a task, follow this pipeline:
-
-### Stage 1: Intent Analysis
-
-Analyze the user's prompt and determine:
-
-```yaml
-intent:
-  project_type: [webapp, api, mobile, cli, library, saas, crm, ecommerce]
-  industry: [healthcare, fintech, education, social, general]
-  layers:
-    frontend: true/false
-    backend: true/false
-    database: true/false
-    auth: true/false
-    ai: true/false
-    payments: true/false
-    realtime: true/false
-  scope: [new_project, feature, bugfix, refactor, architecture]
-```
-
-### Stage 2: Dependency Resolution
-
-For each required layer, load the skill graph:
-
-1. Read `skill.yaml` from each relevant skill directory
-2. Resolve `requires` - load mandatory dependencies
-3. Check `conflicts` - ensure no incompatible skills are loaded
-4. Apply `optional` - suggest but don't force
-5. Respect project profile (if set) - apply rules from `profiles/`
-
-**Dependency resolution example:**
-
-```
-Need: nextjs
-  → requires: react, typescript
-    → react requires: typescript (already loaded)
-  → optional: tailwind, prisma, next-auth
-  
-Loaded: [nextjs, react, typescript]
-Suggested: [tailwind, prisma, next-auth]
-```
-
-### Stage 3: Context Compilation
-
-Assemble context from three levels:
-
-**Level 1 - Vision (always available):**
-
-- `docs/PRD.md` - what are we building
-- `docs/ROADMAP.md` - where are we going
-- `docs/PROJECT_GRAPH.md` - project structure
-- `docs/API.md` - API specification (optional, when backend API layer is present)
-- `docs/UI.md` - UI/UX specification (optional, when UI layer is present)
-
-**Level 2 - Architecture (load when needed):**
-
-- `docs/ARCHITECTURE.md` - system design and boundaries
-- `docs/decisions/` - architecture decision records (ADRs)
-- `docs/PRODUCT_BOUNDARIES.md` - maturity boundaries and non-promises
-- `references/context-rules.md` - dynamic context selection and compilation rules
-
-**Level 3 - Task-Specific Context (load per task):**
-
-- Relevant skill documents from `.agents/skills/`
-- Target code and test files within planned blast radius
-
-### Stage 4: Focused Context Selection
-
-Before sending context to the AI coding assistant:
-
-1. Select only skills relevant to the task domain and touched files
-2. Prioritize: task goal > architectural constraints > project conventions
-3. Include active Decision Records that affect the target component
-4. Enforce quality guardrails and verification criteria
-
-## Core CLI Commands
-
-| Command | Action |
-| --- | --- |
-| `contextos init` | Initialize `.agents/` folder and bootstrap profiles |
-| `contextos export <agent>` | Compile skills for target agent (`gemini`, `claude`, `cursor`, `copilot`, `aider`, `zed`, `all`) |
-| `contextos resolve "<task>"` | Dynamically resolve relevant skills, rules, and risk level for task |
-| `contextos validate` | Validate skill schemas, dependencies, and detect configuration drift |
-| `contextos doctor` | Pre-flight diagnostics for skills, profiles, and compiler synchronization |
-| `contextos watch` | Background file watcher for continuous auto-compilation |
-
-## Project Initialization Flow
-
-When user says something like "Сделай CRM для стоматологии" or "Build a Trello clone":
-
-1. **Analyze intent** (Stage 1)
-2. **Ask clarifying questions:**
-   - Users and roles?
-   - Tech stack preference?
-   - Mobile app needed?
-   - AI features?
-   - Authentication type?
-   - Expected load?
-   - MVP or Production?
-3. **Select profile** (startup/enterprise/mvp/hackathon)
-4. **Resolve skills** (Stage 2)
-5. **Generate all documents** using `generators/` skill
-6. **Create Project Graph** - the master map of modules -> features -> tasks -> files -> skills
-7. **Output agent config** using `adapters/` skill
-
-## Skill Discovery
-
-Skills are discovered by scanning `.agents/skills/*/skill.yaml`. Each `skill.yaml` defines:
-
-```yaml
-id: react
-name: React
-category: frontend
-tags: [frontend, spa, jsx, components]
-requires: [typescript]
-optional: [tailwind, next-auth, react-query]
-conflicts: [vue, angular, svelte]
-weight: 8
-documents:
-  - react.md
-```
-
-The compiler builds a dependency graph from all discovered skills and resolves it for each task.
+Use the resolver with the task and affected files; inspect reasons, risk, warnings, missing skills, and soft-budget overflow. Load references only when needed. Existing authorization and proportional engineering-workflow apply.
 
+Read [references/context-rules.md](references/context-rules.md) for budgeting and [references/project-graph.md](references/project-graph.md) for graph limits.
 
 ## Code Examples
 
-See `EXAMPLES.md` for detailed code examples.
+In this source checkout: node .agents/ctx.js resolve "Fix IDOR" --files src/auth.ts --json. See EXAMPLES.md for source and consumer command boundaries.
 
 ## Validation Checklist
 
-What to verify during the review phase before completing the task.
+- [ ] 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
 
-Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+Editing generated projections; assuming catalog skills are installed; treating an estimated budget as total prompt size; expecting AST or document selection from the package graph; claiming schema validation proves agent behavior.
 
 ## Integration Notes
 
-How this skill interacts with other skills.
+context-manager is a deprecated compatibility alias. engineering-workflow owns the lifecycle; security owns protected boundaries. packs.yaml and rules.yaml are reference data, not executable policy.

package/.agents/core/skills/context-os/TROUBLESHOOTING.md

@@ -1,7 +1,12 @@
-# context-os Troubleshooting & Common Mistakes
+# ContextOS troubleshooting
 
-## 1. Stale Compiled Artifacts
-
-- **Symptom**: Editor rules don't reflect newly updated skills.
-- **Root Cause**: Modifying .agents/core/skills/ without recompiling exports.
-- **Fix**: Run node .agents/ctx.js export all whenever source skills are updated.
+- Stale projection: inspect edits in core/project sources, compile, export, and
+  verify export --check. Do not hand-edit generated artifacts.
+- Missing skill: inspect installed manifests and resolver warnings; install only
+  the required catalog skill through supported tooling.
+- Budget overflow: preserve mandatory safety guidance and reduce irrelevant
+  context; the budget is soft and entrypoint-only.
+- Wrong risk or selection: supply relevant paths, inspect the actual operation,
+  and report a reproducible routing case. A resolver label is not an authority.
+- Missing graph command: use resolve --json for workspace package evidence;
+  inspect source callers separately for symbol-level impact.

package/.agents/core/skills/context-os/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/context-os/packs.yaml

@@ -1,59 +1,10 @@
-# Skill Packs — pre-configured skill bundles
-# Users select a pack instead of individual skills
-
-packs:
-  fullstack-next:
-    name: "Next.js Full-Stack"
-    description: "Full-stack web app with Next.js, React, TypeScript, Tailwind, Prisma"
-    skills: [nextjs, react, typescript, tailwind, prisma, testing, security]
-    profile: startup
-    generates: [PRD, ARCHITECTURE, DATABASE, API, UI, TASKS, PROJECT_GRAPH]
-
-  fastapi-backend:
-    name: "FastAPI Backend"
-    description: "Python backend with FastAPI, PostgreSQL, Docker"
-    skills: [fastapi, python, pydantic, postgres, docker, testing, security, rest]
-    profile: startup
-    generates: [PRD, ARCHITECTURE, DATABASE, API, TASKS, PROJECT_GRAPH]
-
-  react-spa:
-    name: "React SPA"
-    description: "Single Page Application with React, TypeScript, Tailwind"
-    skills: [react, typescript, tailwind, performance, web-accessibility, testing]
-    profile: startup
-    generates: [PRD, ARCHITECTURE, API, UI, TASKS, PROJECT_GRAPH]
-
-  nestjs-enterprise:
-    name: "NestJS Enterprise"
-    description: "Enterprise-grade Node.js backend with NestJS, DDD, full testing"
-    skills: [nestjs, typescript, node, postgres, ddd, security, testing, cicd, docker]
-    profile: enterprise
-    generates: [PRD, ARCHITECTURE, DATABASE, API, TASKS, ROADMAP, PROJECT_GRAPH]
-
-  design-system:
-    name: "Design System"
-    description: "UI/UX design system with accessibility and performance"
-    skills: [ui-design, ux-design, web-accessibility, performance]
-    profile: startup
-    generates: [PRD, UI, TASKS]
-
-  mobile-react-native:
-    name: "React Native Mobile"
-    description: "Cross-platform mobile app with React Native"
-    skills: [react, typescript, react-native, performance, web-accessibility]
-    profile: startup
-    generates: [PRD, ARCHITECTURE, API, UI, TASKS, PROJECT_GRAPH]
-
-  hackathon-fast:
-    name: "Hackathon Quick Start"
-    description: "Fastest possible setup — SQLite, minimal architecture"
-    skills: [react, typescript, node, sqlite]
-    profile: hackathon
-    generates: [TASKS, PROJECT_GRAPH]
-
-  ai-saas:
-    name: "AI SaaS Platform"
-    description: "SaaS with AI features, auth, payments, analytics"
-    skills: [nextjs, react, typescript, tailwind, prisma, security, stripe, openai]
-    profile: startup
-    generates: [PRD, ARCHITECTURE, DATABASE, API, UI, ROADMAP, TASKS, PROJECT_GRAPH]
+# Reference-only illustration. This file does not install skills or generate docs.
+status: reference-only
+purpose: Illustrate task-focused grouping; inspect available catalog skills first.
+examples:
+  protected-api:
+    primary: [engineering-workflow, security]
+  compiler-maintenance:
+    primary: [engineering-workflow, context-os]
+  substantive-build:
+    primary: [engineering-workflow, ponytail-mindset]