contextos-agents 2.3.0 → 2.3.2

package/.agents/rules/rule-catalog.js

@@ -139,7 +139,7 @@ const BUILTIN_RULES = [
     level: 'must',
     enforcement: 'runtime',
     checker: 'secret-scanner',
-    summary: 'Zero plaintext credentials, private keys, or API tokens committed to repository',
+    summary: 'Scan configured inputs for supported credential patterns; report input scope, exclusions, and scanner results',
     applicability: ['all'],
     priority: 100,
     tokenCost: 35,
@@ -276,9 +276,8 @@ const BUILTIN_RULES = [
     id: 'TEST-001',
     sourceSkill: 'testing',
     level: 'must',
-    enforcement: 'runtime',
-    checker: 'skill-frontmatter-validator',
-    summary: 'Zero unverified claims: mandatory proof-of-work with automated test suite and validator execution',
+    enforcement: 'prompt-guidance',
+    summary: 'Report completion only with relevant behavioral evidence; document failed and unrun checks and their scope',
     applicability: ['all'],
     priority: 100,
     tokenCost: 45,
@@ -290,7 +289,7 @@ const BUILTIN_RULES = [
     sourceSkill: 'ponytail-mindset',
     level: 'must',
     enforcement: 'prompt-guidance',
-    summary: 'Surgical blast radius: modify only files planned for the task; zero unnecessary boilerplate',
+    summary: 'Keep changes within the authorized outcome, update the plan for necessary callers, and preserve unrelated edits',
     applicability: ['all'],
     priority: 90,
     tokenCost: 35,
@@ -420,6 +419,7 @@ class RuleCatalog {
         lines.push(`  Checker Module   : ${checker.module}`);
         lines.push(`  Checker Purpose  : ${checker.description}`);
       }
+      lines.push('  Coverage Note    : Registered checker; applies only when invoked on its configured inputs, not proof of the whole workflow.');
     } else {
       lines.push(`  Enforcement Note : Governed via agent prompt guidelines (No runtime checker)`);
     }

package/.agents/validate.js

@@ -413,14 +413,21 @@ function checkValidationJson(sourceSkills) {
     }
 
     try {
-      JSON.parse(fs.readFileSync(valPath, 'utf8'));
+      const metadata = JSON.parse(fs.readFileSync(valPath, 'utf8'));
+      if (metadata['x-contextos-evidence-contract'] !== undefined) {
+        const issues = require('./validation-evidence.js').validateEvidenceSchema(metadata);
+        if (issues.length) {
+          error(`[validation] ${name}/VALIDATION.json: ${issues.join('; ')}`);
+          continue;
+        }
+      }
       pass++;
     } catch (e) {
       error(`[validation] ${name}/VALIDATION.json is invalid JSON: ${e.message}`);
     }
   }
 
-  info(`[validation] ${pass} VALIDATION.json files are valid`);
+  info(`[validation] ${pass} metadata files structurally valid (not proof of command execution or agent behavior)`);
 }
 
 // ═════════════════════════════════════════════════════════════════════════════

package/.agents/validation-evidence.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const fs = require('node:fs');
+const { isDeepStrictEqual } = require('node:util');
+
+// A report contract, not an attestation that a command was actually executed.
+const EVIDENCE_REPORT_SCHEMA = {
+  $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: {
+    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 } },
+  },
+  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' } } } } } },
+    },
+  ],
+};
+
+function validateEvidenceSchema(schema) {
+  return isDeepStrictEqual(schema, EVIDENCE_REPORT_SCHEMA) ? [] : ['Evidence schema must match the version 1 report contract'];
+}
+
+function validateEvidenceReport(report) {
+  const errors = [];
+  const object = v => v && typeof v === 'object' && !Array.isArray(v);
+  const nonempty = v => typeof v === 'string' && v.trim().length > 0;
+  if (!object(report)) return ['Report must be an object'];
+  if (Object.keys(report).some(k => !['status', 'checks', 'limitations'].includes(k))) errors.push('Unknown report property');
+  if (!['verified', 'partial', 'not_run'].includes(report.status)) errors.push('Invalid status');
+  if (!Array.isArray(report.checks)) errors.push('checks must be an array');
+  else {
+    for (const [i, check] of report.checks.entries()) {
+      if (!object(check) || Object.keys(check).some(k => !['command', 'exitCode', 'scope'].includes(k)) ||
+          !nonempty(check.command) || !nonempty(check.scope) ||
+          !(check.exitCode === null || Number.isInteger(check.exitCode))) {
+        errors.push(`Invalid check at index ${i}`);
+      }
+    }
+    if (report.status === 'verified' && (!report.checks.length || report.checks.some(c => c?.exitCode !== 0))) {
+      errors.push('verified requires at least one successful check and no failed or unrun checks');
+    }
+    if (report.status === 'not_run' && report.checks.some(c => c?.exitCode !== null)) errors.push('not_run cannot contain executed checks');
+  }
+  if (!Array.isArray(report.limitations) || report.limitations.some(v => !nonempty(v))) errors.push('limitations must contain nonempty strings');
+  else if (report.status !== 'verified' && !report.limitations.length) errors.push('Partial or unrun work needs limitations');
+  return errors;
+}
+
+module.exports = { EVIDENCE_REPORT_SCHEMA, validateEvidenceSchema, validateEvidenceReport };
+
+if (require.main === module) {
+  try {
+    const report = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+    const errors = validateEvidenceReport(report);
+    process.stdout.write(JSON.stringify({ ok: errors.length === 0, scope: 'report contract only', errors }) + '\n');
+    process.exitCode = errors.length ? 1 : 0;
+  } catch (err) {
+    process.stderr.write(err.message + '\n');
+    process.exitCode = 1;
+  }
+}

package/README.md

@@ -7,7 +7,8 @@
 <h1 align="center">contextos-agents</h1>
 
 <p align="center">
-  <strong>One version-controlled source of engineering rules for supported coding agents.</strong>
+  <strong>Maintain your coding-agent rules in one place.</strong><br />
+  Export them to supported tools and catch outdated configs in CI.
 </p>
 
 <p align="center">
@@ -19,247 +20,181 @@
 </p>
 
 <p align="center">
-  <a href="#installation">Installation</a> •
-  <a href="./GUIDE.md">Guide</a> •
-  <a href="./docs/product/onboarding.md">Onboarding</a> •
-  <a href="./docs/ADAPTER_COMPATIBILITY.md">Adapters</a> •
-  <a href="#supported-agents--compilation">Supported Agents</a> •
-  <a href="./CONTRIBUTING.md">Contributing</a> •
-  <a href="https://www.npmjs.com/package/contextos-agents">npm</a>
+  <a href="#quickstart">Quickstart</a> ·
+  <a href="#supported-agents">Supported agents</a> ·
+  <a href="./GUIDE.md">Guide</a> ·
+  <a href="./CONTRIBUTING.md">Contributing</a>
 </p>
 
 ---
 
-ContextOS is a deterministic context and policy compiler for AI coding agents. It exports version-controlled engineering rules and detects configuration drift in CI. See the [adapter compatibility matrix](docs/ADAPTER_COMPATIBILITY.md) for native paths, instruction indexes and manual templates; client loader verification is separate from export tests.
+Using several coding agents in the same project? A rule updated for one tool can
+leave another tool's configuration behind. ContextOS keeps your rules in
+version-controlled Markdown, exports them to supported agent formats, and checks
+whether those exports still match their sources.
 
-## Installation
+It is useful when you or your team maintain instructions across multiple tools
+or need a configuration check before merging changes. If a small, stable
+instruction file already covers your workflow, you may not need an extra tool.
 
-You do not need to clone anything manually. Just open your terminal in the root of your project and run:
-
-```bash
-npx contextos-agents init
-```
-
-By default, ContextOS installs seven core skills: `engineering-workflow`, `ponytail-mindset`, `gemini-precision`, `security`, `context-os`, `context-manager`, and `gstack-roles`, then exports Gemini workspace skills. Supporting examples and references remain separate files. The actual context loaded and session cost depend on your client and task; ContextOS does not control an external client's chat history.
-
-Codex also discovers the shared `.agents/skills` directory. The default Cursor
-export always applies only the compact project bootstrap; skill bodies load by
-file patterns or agent request. Resolver token budgets are soft: mandatory safety
-guidance survives with an overflow warning. The experimental MCP prompt assembler
-keeps selected bodies whole and can reject an explicit hard character limit.
-
-Want more skills right away? Install pre-packaged presets or the entire catalog:
-
-```bash
-npx contextos-agents init --preset frontend   # React, Next.js, TypeScript, UI/UX, a11y
-npx contextos-agents init --preset backend    # System design, API design, Node.js, databases
-npx contextos-agents init --preset devops     # Docker, CI/CD, Terraform
-npx contextos-agents init --all               # Install all 36 catalog skills at once
-```
-
-### Options
-
-Try the [small local demo](examples/quickstart/README.md) to install the current
-candidate in a new folder, select a TypeScript skill, and add a team rule without
-calling a model API. The [five-minute guide](docs/product/onboarding.md) explains
-the same workflow for an existing project.
-
-For the current R2 candidates, see the [release preparation status](docs/R2_RELEASE_PREPARATION.md)
-and [upgrade/checkpoint rollback](docs/COMPACT_CONTEXT_MIGRATION.md). The
-[release manifest](docs/evidence/release-2.3.json) records the verified source,
-cross-platform CI and candidate archive identities. The client pilot and
-publication decision remain pending. Internal plans, local API probes
-and raw logs are excluded from the public release surface.
-
-```bash
-npx contextos-agents --help             # Show all options
-npx contextos-agents --version          # Show version
-npx contextos-agents --minimal          # Install only the core bootstrap skills
-npx contextos-agents --all              # Install all 36 catalog domain skills during init
-npx contextos-agents --preset <name>    # Install stack preset: frontend, backend, devops, full
-npx contextos-agents --profile init     # Install with specific profile
-npx contextos-agents --auto             # Auto-detect tech stack and apply recommended profile
-npx contextos-agents --dry-run          # Preview what will be installed
-npx contextos-agents --force            # Overwrite an existing .agents/ folder
-npx contextos-agents --skip-compile     # Skip auto-compilation step
-```
-
-## Why ContextOS?
-
-Modern development teams face fragmented AI tooling: engineers use Cursor, Claude Code, GitHub Copilot, Gemini, Zed, and Aider. Each tool requires its own proprietary rules format, leading to configuration drift, contradictory standards, and unvetted AI slop (`// TODO`, leaked secrets).
-
-Artificially truncating skills to save tokens degrades model reasoning and induces hallucinations. Instead, ContextOS ensures that agents receive complete, high-fidelity engineering context from a single version-controlled source.
-
-**ContextOS is not another coding agent.** It is the deterministic context compiler and policy engine for the agents your team already uses.
-
-### The Three Pillars
-
-1. **Portable (Multi-Agent):** Define your engineering skills once in standard Markdown. ContextOS compiles native configurations for all supported agents (Gemini, Claude Code, Cursor, Copilot, Aider, and Zed).
-2. **High-Fidelity & Focused:** The resolver maps domain skills to relevant tasks without lossy truncation, delivering rich, complete context to the model.
-3. **Verifiable in CI:** Lockfile v2 provenance, dual-hash verification, and CI quality gates detect configuration drift and enforce quality guardrails before merge.
-
-## How it works
-
-1. Define version-controlled engineering policies once.
-2. Resolve the complete, relevant skill policies for the current task.
-3. Compile native configuration for each coding agent.
-4. Detect configuration drift and policy violations in CI.
-
-```bash
-contextos resolve "review authentication changes" \
-  --files src/auth/session.ts \
-  --explain
-```
-
-Selected:
-  security              explicit task match
-  engineering-workflow  required dependency
-
-Excluded:
-  context-manager       domain relevance filter
-
-Risk: high
-Context status: complete and verified
-
-## Dynamic Skill Resolution & Unified CLI (`contextos` / `ctx.js`)
-
-ContextOS provides a unified CLI (`contextos` or `npx contextos-agents`) and local engine (`.agents/ctx.js`) to resolve minimal skills on the fly, run health diagnostics, and compile exports for AI assistants.
-
-### Dynamic Skill Resolution (`resolve`)
-
-```bash
-# Resolve skills for a task description:
-contextos resolve "Build an accessible modal component with React and Tailwind"
-
-# Output:
-# [DOMAIN: Frontend] [PHASE: Build] [ROLE: Senior Developer]
-# Skills loaded: ponytail-mindset, engineering-workflow, gemini-precision
-
-# Resolve with full evidence scoring explanation:
-contextos resolve "security review" --files apps/web/app/login/page.tsx --explain
-```
-
-### Skill & Catalog Management (`contextos skill`)
-
-Discover, install, and customize skills:
+<p align="center">
+  <img src="./assets/contextos-story.gif" alt="One rule changed. Three agent configs fell behind. ContextOS detects stale exports, then refreshes and verifies them." width="960" />
+</p>
 
-```bash
-# Explore all available catalog skills (36 domain skills):
-contextos skill list --available
+<p align="center"><sub>Change a rule. Catch stale exports. Bring them back in sync.</sub></p>
 
-# Install a specific skill from the catalog (with typo suggestions):
-contextos skill add fastapi
+<a id="installation"></a>
 
-# Install all 36 catalog skills at once:
-contextos skill add --all
+## Quickstart
 
-# Fork a built-in skill into your project for team customizations:
-contextos skill override gemini-precision
+Requires **Node.js 22+** and npm. Run these commands in your project's root.
+This workflow does not call a model API.
 
-# Diff your local customizations against upstream updates:
-contextos skill diff gemini-precision
+**1. Initialize the rule sources.**
 
-# Eject a skill to decouple it from upstream updates:
-contextos skill eject gemini-precision
+```sh
+npx contextos-agents init --skip-compile
 ```
 
-### Diagnostic Health Check (`contextos doctor`)
+This installs the seven core skills. We generate the agent files after adding
+your own rule below. See the [guide](GUIDE.md#initialization-options) for presets,
+installation previews, and using a pinned project dependency.
 
-Run a comprehensive pre-flight verification across your repository to ensure valid skills, profile alignment, and compiler synchronization:
+**2. Add a rule your team wants to maintain.**
 
-```bash
-contextos doctor
-```
-
-### Supported Agents & Compilation
+Create the folders and save this as
+`.agents/project/skills/team-auth/SKILL.md`:
 
-| Agent | Command | Output Format |
-|-------|---------|---------------|
-| **Gemini / Antigravity** | `contextos export gemini` | `.agents/generated/gemini/skills/` |
-| **Claude Code** | `contextos export claude` | `.agents/generated/claude/skills/` |
-| **Cursor IDE** | `contextos export cursor` | `.cursor/rules/*.mdc` (modular globs) + `.cursorrules` |
-| **GitHub Copilot** | `contextos export copilot` | `.github/copilot-instructions.md` |
-| **Aider** | `contextos export aider` | `.aider.conf.yml` + `CONVENTIONS.md` |
-| **Zed IDE** | `contextos export zed` | `.zed/rules.md` + `.zed/prompts/*.md` |
+```markdown
+---
+name: team-auth
+description: Team rules for authentication code.
+---
+# Team security
 
-```bash
-contextos export all       # Compile for all agents
+- Never log authorization headers.
 ```
 
-### Staged Index Security Scanner (`contextos scan`)
-
-Scan staged changes directly from the Git index for secret leaks, blocked credential files, unfinished lazy stubs, and write-scope containment:
+**3. Compile, export, and check.**
 
-```bash
-contextos scan --staged --enforce
-contextos scan --staged --placeholders --scope .agents/task-scope.json --json
+```sh
+npx contextos-agents compile
+npx contextos-agents export all
+npx contextos-agents export all --check --json
 ```
 
-### Safe Git Pre-Commit Hooks (`contextos hook`)
+The check should report `"status": "pass"`, `"hasDrift": false`, and exit code
+`0`. The rule is now present in generated files such as
+`.cursor/rules/team-auth.mdc` and `.agents/skills/team-auth/SKILL.md`.
 
-Install or remove isolated pre-commit hooks that run fast security checks without clobbering existing developer hooks:
+**See drift detection:** add `- Never log session tokens.` to the same source
+file, then run:
 
-```bash
-contextos hook install
-contextos hook uninstall
+```sh
+npx contextos-agents compile
+npx contextos-agents export all --check --json
 ```
 
-### CI Quality Gate (`contextos gate`)
+The check now reports `"status": "drift"` and exits with code `1`: the exports
+are out of date. Run `npx contextos-agents export all` and check again to return
+to `pass`. Commit the source rules, generated files, and lockfile together.
 
-Check that generated adapter files match source skills and the active profile:
+Edit your rules under `.agents/project/skills/`; generated files are managed
+outputs. To use a single adapter, replace `all` with its name, for example
+`cursor`. See the [step-by-step onboarding guide](docs/product/onboarding.md)
+for task selection, client activation, updates, and removal.
 
-```bash
-contextos gate
-```
+## Check rule changes in CI
 
-This is a configuration drift gate. Run your application's tests, typecheck and security checks separately. `resolve` recommends skills for a task; ordinary exports use all installed skills allowed by the profile. Resolver budgets are soft estimates of selected skill bodies and exclude client instructions, chat history and tool output.
+After committing a fresh export, run the same consistency check on pull requests.
+It checks agent configuration; your application's tests and security checks
+remain separate.
 
-### CI Quality Gate Action (contextos-gate)
+<details>
+<summary>GitHub Actions example</summary>
 
-Guard your repository against skill drift, missing outputs, and rule regressions using the official GitHub Composite Action:
+Save as `.github/workflows/contextos.yml`:
 
 ```yaml
-# .github/workflows/pr-gate.yml
-name: ContextOS Quality Gate
+name: Agent rule consistency
 on: [pull_request, push]
 jobs:
-  gate:
+  check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: kok-o/contextos-agents/.github/actions/contextos-gate@v2.2.0
+      - uses: kok-o/contextos-agents/.github/actions/contextos-gate@v2.3.2
         with:
-          version: '2.2.0'       # Pinned version of contextos-agents runner
-          adapters: 'all'        # Adapters to verify (or specific: 'cursor', 'claude')
-          working-directory: '.' # Project root directory
-```
-
-The action executes the verified ContextOS quality gate in-process from the pinned package version, verifying generated AI adapter configs against source skills without executing untrusted scripts from pull requests, and without requiring a Node.js project or running `npm test`.
-
-## Optional MCP integration (Beta)
-
-The MCP server is a separate beta package. It is not part of the stable `contextos-agents` core.
-
-Install it separately if you want to try the beta integration:
-
-```bash
-npm install --save-dev @contextos/mcp
-npx contextos-mcp --dir .
+          version: '2.3.2'
+          adapters: 'all'
+          working-directory: '.'
 ```
 
-The MCP server is read-only by default. Runtime execution remains experimental and is outside the stable core scope.
-
-## Security - Third-Party Skills
-
-ContextOS skills are **executable context** - they become part of the system prompt that controls your AI agent's behavior. A malicious skill could instruct the AI agent to exfiltrate environment variables, modify files, or ignore your project's security policies.
-
-> [!CAUTION]
-> **Install skills only from repositories you trust as you would trust executable code.** Skills installed via `ctx.js skill add` from npm or GitHub are not sandboxed.
+Set `adapters` to the adapter or adapters you actually exported.
+See [CI configuration](GUIDE.md#ci-configuration-check) for version pinning.
+
+</details>
+
+<a id="supported-agents--compilation"></a>
+
+## Supported agents
+
+| Agent | How ContextOS provides the rules |
+| --- | --- |
+| Codex | Shared native skills in `.agents/skills/*/SKILL.md`. |
+| Gemini CLI | Shared workspace skills plus Gemini exports. |
+| Claude Code | `CLAUDE.md` index linking to generated instructions. |
+| Cursor | Modular `.cursor/rules/*.mdc` files. |
+| GitHub Copilot | Repository instructions and a skill source index. |
+| Aider | `CONVENTIONS.md` referenced by `.aider.conf.yml`. |
+| Zed | Templates for manual import. |
+
+Export tests and live client loading are separate checks. See the
+[compatibility matrix](docs/ADAPTER_COMPATIBILITY.md) for exact paths, tested
+client versions, and limitations, including unverified Antigravity loading.
+
+## Beyond the first rule
+
+- **Reuse skills:** install catalog skills and stack presets, or keep team
+  overrides. See [skill management](GUIDE.md#skill--catalog-management-skill).
+- **Inspect task relevance:** `resolve` recommends skills for a task and explains
+  the selection. It does not install or activate them. Ordinary exports use the
+  installed skills allowed by the profile, independently of a task's selection.
+  See [resolution](GUIDE.md#dynamic-skill-resolution-resolve).
+- **Inspect staged changes:** the separate `scan` command and optional hooks
+  check supported secret, placeholder, and write-scope patterns. See
+  [scanning and hooks](GUIDE.md#security-scanning--governance-hooks).
+
+## Scope and evidence
+
+The core CLI manages rule sources, selection, exports, and configuration checks.
+The optional [MCP package](contextos-mcp/README.md) is separate and in beta
+(`npm install --save-dev contextos-mcp`); agent execution and runtime orchestration
+remain experimental.
+
+Consistent configuration does not guarantee that a model follows every rule.
+The [recorded calibration](docs/BENCHMARK_RESULTS.md) found no quality advantage
+over vanilla on its test corpus. Install third-party skills only from sources
+you trust: their instructions are not sandboxed.
+
+## Documentation
+
+| I want to… | Read |
+| --- | --- |
+| Look up commands, presets, profiles, and diagnostics | [Guide and cheat sheet](GUIDE.md) |
+| Try a task with a custom team rule | [Onboarding](docs/product/onboarding.md) |
+| Check agent-specific behavior | [Compatibility matrix](docs/ADAPTER_COMPATIBILITY.md) |
+| Understand the compiler and support boundaries | [Architecture](docs/ARCHITECTURE.md) · [Product boundaries](docs/PRODUCT_BOUNDARIES.md) |
+| Upgrade or recover a previous configuration | [Migration and rollback](docs/COMPACT_CONTEXT_MIGRATION.md) |
+| Review release evidence | [2.3.2 maintenance release](docs/PATCH_RELEASE_2.3.2.md) · [Changelog](CHANGELOG.md) |
+| Reproduce the animated example | [Demo commands and renderer](scripts/readme-gif/STORY.md) |
 
 ## Contributing
 
-We are open to pull requests! See [CONTRIBUTING.md](./CONTRIBUTING.md) for a step-by-step guide.
+Bug reports, documentation fixes, and examples from real projects are welcome.
+See [CONTRIBUTING.md](CONTRIBUTING.md) or
+[open an issue](https://github.com/kok-o/contextos-agents/issues).
 
 ## License
 
-Distributed under the Apache License, Version 2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for details.
+[Apache-2.0](LICENSE). See [NOTICE](NOTICE) for attribution.

package/bin/index.js

@@ -100,7 +100,7 @@ Options:
   --project <path>    Specify target project root directory (default: current directory)
   --target <adapters> Target adapter(s) to verify or export (default: all)
   --github-annotations Emit GitHub Actions workflow commands and step summary
-  --with-mcp, --mcp   [DEPRECATED] Use the separate @contextos/mcp package instead
+  --with-mcp, --mcp   [DEPRECATED] Use the separate contextos-mcp package instead
   --skip-compile      Skip running ctx.js export after installation
   --add-skill <ref>   Install a community plugin skill after setup
 

package/catalog/skills/typescript/SKILL.md

@@ -68,9 +68,23 @@ type Result<T> = { ok: true; data: T } | { ok: false; error: string };
 
 ## Type Guards
 
+A type guard must validate every required property before narrowing. This checks
+the data shape; a supplied `role` does not establish authorization.
+
+<!-- example: typescript-user-guard -->
+
 ```typescript
-function isUser(value: unknown): value is User {
-  return typeof value === 'object' && value !== null && 'id' in value;
+export interface User {
+  id: string;
+  name: string;
+  role: 'admin' | 'user';
+}
+
+export function isUser(value: unknown): value is User {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && 'id' in value && typeof value.id === 'string'
+    && 'name' in value && typeof value.name === 'string'
+    && 'role' in value && (value.role === 'admin' || value.role === 'user');
 }
 ```