opencode-agent-skill 11.0.0 → 12.0.0-beta.0

package/CHANGELOG.md

@@ -6,6 +6,24 @@ The project follows Semantic Versioning.
 
 ## [Unreleased]
 
+## [12.0.0-beta.0] - 2026-09-22
+
+### Beta
+- Added empirical per-task-class model performance history and capability-preserving reranking with a minimum evidence threshold before reranking.
+- Added context quality receipts for required-file recall and irrelevant-context ratio.
+- Added hash-keyed plan snapshots with active-plan execution fencing.
+- Added bounded decision policy for reversible local rulings versus human-gated destructive/external actions.
+- Added deterministic repo-scale benchmark fixture generation and V12/repo-scale validation gates.
+- Hardened release consistency checks to derive eval counts and validate aggregate workflow structure.
+- Fixed missing empirical-history handling so models without benchmark history safely fall back to static capability routing.
+
+### Verified locally on Windows
+- 255 tests total: 253 passed, 0 failed, 2 platform-specific skips.
+- Syntax, catalog validation, docs consistency, routing, V11/V12/repo-scale/live/long/polyglot validation: PASS.
+- npm pack, packed-install smoke and plain one-command install/resource auto-sync smoke: PASS.
+- Published prerelease intent: npm dist-tag `next`; V11 remains `latest` until V12 stable release gates are satisfied.
+
+
 ## [11.0.0] - 2026-09-22
 
 ### Released

package/README.md

@@ -1,7 +1,7 @@
 # OpenCode Universal Engineering System (UES)
 
-> **V11 stable: 11.0.0** — perception-aware adaptive execution engine với evidence-efficient context, capability routing và visual/browser verification.
-> UES là bộ công cụ hỗ trợ OpenCode xử lý dự án lớn, tác vụ dài và quy trình kỹ thuật cần kiểm chứng bằng bằng chứng thực tế.
+> **V12 beta: 12.0.0-beta.0** — weak-model intelligence foundation với empirical routing, context-quality metrics, plan-scoped execution và repo-scale validation.
+> **Stable latest vẫn là V11: 11.0.0.** Dùng `npm install -g opencode-agent-skill@next` để thử V12 beta.
 
 [![npm version](https://img.shields.io/npm/v/opencode-agent-skill.svg)](https://www.npmjs.com/package/opencode-agent-skill)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -431,7 +431,7 @@ ocskill work status checkout .
 
 ## Skills
 
-V11 development hiện có **48 skills**; V10 stable có 39. Router vẫn chỉ chọn tập skill phù hợp thay vì nạp toàn bộ catalog vào mỗi task. Router chỉ chọn các skill phù hợp thay vì nạp toàn bộ catalog vào mỗi task.
+V11 stable hiện có **48 skills**; V10 stable có 39. Router vẫn chỉ chọn tập skill phù hợp thay vì nạp toàn bộ catalog vào mỗi task.
 
 Một số process skill quan trọng:
 
@@ -592,10 +592,11 @@ Integration sẽ từ chối ghi đè lên file đang dirty ở root. Safe-wave
 
 ## Evaluation
 
-UES 9.0.0 hiện có:
+V11 hiện có:
 
-- **34 static skill-routing scenarios** phủ 39 skills;
-- **120 V2 router cases** với required routes và negative guards;
+- **43 static skill-routing scenarios** phủ 48 skills;
+- **129 V2 router cases** với required routes và negative guards;
+- **13 V11 contract tasks** across 6 categories;
 - **20 standard live tasks**;
 - **5 long-horizon tasks**;
 - **8 polyglot tasks** cho Python, Java, .NET, Next.js, React Native, SQL migration, monorepo và generated contract;
@@ -667,11 +668,13 @@ Pipeline hiện kiểm tra:
 ```text
 syntax
 → resource validation
+→ docs:check
 → static skill routing
 → V2 router matrix
 → standard hidden-grader integrity
 → long hidden-grader integrity
 → polyglot hidden-grader integrity
+→ V11 contract validation
 → Node tests
 → npm pack --dry-run
 → packed global-install smoke
@@ -712,6 +715,7 @@ UES chỉ quản lý resource có namespace/marker của chính nó và cố g
 - [V7 Intelligence Runtime](docs/V7-INTELLIGENCE-RUNTIME.md)
 - [V8 Intelligence & Reliability](docs/V8-INTELLIGENCE-RELIABILITY.md)
 - [V9 Speed & Intelligence](docs/V9-SPEED-INTELLIGENCE.md)
+- [V12 Weak-Model Intelligence (beta)](docs/V12-WEAK-MODEL-INTELLIGENCE.md)
 
 ---
 
@@ -732,9 +736,11 @@ npm install -g opencode-agent-skill
 Phiên bản hiện tại:
 
 ```text
-9.0.0
+12.0.0-beta.0
 ```
 
+V12 beta dùng npm dist-tag `next`; `latest` tiếp tục trỏ tới V11 stable cho đến khi các release gate V12 hoàn tất.
+
 ---
 
 ## License

package/bin/ocskill.mjs

@@ -65,9 +65,10 @@ import { classifyEngineeringTask } from "../lib/orchestrator-policy.mjs"
 import { createTaskSandbox, integrateTaskSandbox, listTaskSandboxes, removeTaskSandbox } from "../lib/worktree-sandbox.mjs"
 import { analyzeEvalTraces, saveLearningAnalysis, readLearningState, acceptLearning, promoteLearning } from "../lib/learning-engine.mjs"
 import { hermesStatus, buildHermesDelegationPrompt, buildHermesWorkflowPrompt, hermesOneShotArgs, hermesSidecarPlan } from "../lib/hermes-bridge.mjs"
-import { readModelPolicy, validateModelID, writeModelPolicy } from "../lib/model-config.mjs"
+import { readModelPolicy, recordModelPerformance, validateModelID, writeModelPolicy } from "../lib/model-config.mjs"
 import { evidenceStoreStatus, gcEvidenceStore, getEvidence, putEvidence } from "../lib/evidence-store.mjs"
 import { inferTaskCapabilities } from "../lib/capability-registry.mjs"
+import { MODEL_TASK_CLASSES } from "../lib/model-performance.mjs"
 import { browserCapability, buildBrowserVerificationPlan } from "../lib/browser-adapter.mjs"
 import { inspectBrowserPage, summarizeBrowserInspection } from "../lib/browser-runtime.mjs"
 import { comparePngFiles, cropPngFile } from "../lib/png-diff.mjs"
@@ -171,6 +172,7 @@ Usage:
     ocskill models set <light|standard|heavy> <provider/model[#variant]>
     ocskill models role <role> <light|standard|heavy>
     ocskill models capability <provider/model> [--vision on|off] [--browser on|off] [--reasoning on|off] [--long-context on|off] [--cost low|medium|high] [--latency fast|medium|slow] [--quality 0..1]
+    ocskill models observe <provider/model> --task-class <class> --passed on|off [--retries N] [--tokens N] [--latency-ms N]
 
   --force backs up and replaces/removes state owned by another package.
 `)
@@ -812,6 +814,27 @@ async function modelsControl() {
     return
   }
 
+  if (action === "observe") {
+    const model = args[2]
+    if (!validateModelID(model)) {
+      console.error("Usage: ocskill models observe <provider/model> --task-class <class> --passed on|off")
+      process.exitCode = 2
+      return
+    }
+    const taskClass = optionValue(args, "--task-class") || "general"
+    if (!MODEL_TASK_CLASSES.includes(taskClass)) throw new Error("--task-class must be one of: " + MODEL_TASK_CLASSES.join(", "))
+    const passedRaw = String(optionValue(args, "--passed") || "").toLowerCase()
+    if (!["on","off","true","false","pass","fail"].includes(passedRaw)) throw new Error("--passed must be on/off, true/false, or pass/fail")
+    policy = await recordModelPerformance(getConfigDir(), {
+      model, taskClass, passed: ["on","true","pass"].includes(passedRaw),
+      retries: optionInt(args, "--retries", 0) || 0,
+      tokens: optionInt(args, "--tokens", 0) || 0,
+      latencyMs: optionInt(args, "--latency-ms", 0) || 0,
+    })
+    printJson({ model, taskClass, recorded: true, performance: policy.performance?.[model]?.[taskClass] || null })
+    return
+  }
+
   if (action === "capability") {
     const model = args[2]
     if (!validateModelID(model)) {

package/docs/DETERMINISTIC-TOOLS.md

@@ -1,6 +1,6 @@
 # Deterministic evidence and execution tools
 
-UES 8 uses dependency-light Node helpers for work that should not rely on a model guessing or remembering it.
+V11 uses dependency-light Node helpers for work that should not rely on a model guessing or remembering it.
 
 ## Repository evidence
 

package/docs/ENGINEERING-DESIGN.md

@@ -1,6 +1,6 @@
 # UES engineering design
 
-UES 8 evolves the project from an engineering workflow harness into a **long-horizon execution engine** designed to reduce context pressure on coding models.
+V11 evolves the project from an engineering workflow harness into a **perception-aware adaptive execution engine** designed to reduce context pressure on coding models while keeping evidence needed for correctness.
 
 The selected model remains the selected model. UES improves orchestration, evidence, task boundaries, state persistence and verification; it does not claim model equivalence.
 
@@ -44,11 +44,11 @@ Models still reason about semantics and read affected code.
 
 ### Progressive disclosure
 
-The catalog remains 39 skills. UES prefers a small active skill set and loads deeper references only when needed.
+The catalog spans 48 skills. UES prefers a small active skill set and loads deeper references only when needed.
 
 ### Hard gates, not reminders
 
-V8 machine-enforces the important boundaries:
+V11 machine-enforces the important boundaries:
 
 1. long/high-risk plans are not executable until a structured plan-verification receipt matches the current plan hash;
 2. long/high-risk task completion requires a successful verification receipt for the active run and the current workspace fingerprint;
@@ -133,7 +133,7 @@ Only UES-managed resources are rewritten/removed.
 
 UES separates:
 
-1. **static skill contract** — 34 scenarios covering the 39-skill catalog;
+1. **static skill contract** — 43 scenarios covering the 48-skill catalog;
 2. **V2 router precision matrix** — 120 required-route/negative-guard cases;
 3. **standard live benchmark** — 20 executable hidden-graded tasks;
 4. **long-horizon benchmark** — 5 tasks, including one 15-source-file integration workload;

package/docs/EVALS.md

@@ -1,10 +1,10 @@
 # UES evaluations
 
-UES 8 separates catalog correctness, routing precision, benchmark integrity, final behavior, long-horizon orchestration and cross-stack coverage.
+V11 separates catalog correctness, routing precision, benchmark integrity, final behavior, long-horizon orchestration and cross-stack coverage.
 
 ## 1. Static skill-routing contract
 
-`evals/routing.json` keeps 34 representative scenarios and covers all installed skills.
+`evals/routing.json` keeps 43 representative scenarios and covers all installed skills.
 
 ```bash
 npm run evals
@@ -141,7 +141,7 @@ Compare the same model, variant, prompt, fixture, grader and environment. Report
 A benchmark result is evidence only for the measured workload. UES does not claim to turn one base model into another.
 
 
-## V8 live-run observability and evidence gate
+## V11 live-run observability and evidence gate
 
 Live runs accept:
 

package/docs/GITHUB-RULESET.md

@@ -0,0 +1,50 @@
+# GitHub Ruleset Readiness
+
+This document records the recommended GitHub repository ruleset configuration for the `main` branch, to be activated only after CI Gate and Security Gate have each achieved at least one successful run.
+
+## Recommended ruleset
+
+- **Ruleset name:** `main-protection`
+- **Target:** default branch / `main`
+- **Enforcement:** Active
+
+## Rules
+
+1. **Restrict deletions** — block deleting the default branch or force-pushing over it.
+2. **Block force pushes** — no `git push --force` or `git push -f` to `main`.
+3. **Require pull request before merge** — all changes must go through a PR.
+4. **Require conversation resolution** — PR reviewers must resolve all inline comments before merge.
+5. **Require status checks** — PRs must have passing CI Gate and Security Gate checks before merge.
+6. **Require branch up to date** — PR branches must be up to date with `main` before merge (applies when there are multiple contributors; can be relaxed for single-maintainer setups).
+7. **Required check: CI Gate** — the aggregate CI check from `.github/workflows/ci.yml`.
+8. **Required check: Security Gate** — the aggregate security check from `.github/workflows/security.yml`.
+
+## Approval policy for single-maintainer repo
+
+This repository currently has one maintainer. Setting `required approval = 1` would prevent the owner from merging their own PRs (they cannot approve their own PR). Therefore:
+
+- **Required approval = 0** for now.
+- When a collaborator or external reviewer is added, raise to `required approval = 1` to restore oversight.
+
+## Classic branch protection vs ruleset
+
+GitHub supports both classic branch protection rules and repository rulesets simultaneously. When both are configured:
+
+- They can apply independently to different aspects of branch protection.
+- Be cautious of duplicate or conflicting protections (e.g., two rules both requiring status checks but with different required lists).
+- If migrating from classic protection to ruleset, remove the classic rule after confirming the ruleset is active and working.
+
+## Activation prerequisite
+
+Do not enable the ruleset until:
+
+1. CI Gate has at least one successful run on `main`.
+2. Security Gate has at least one successful run on `main` or a PR.
+
+Without these prerequisites, the ruleset would block all merges immediately after activation, effectively locking the repository.
+
+## Current status
+
+- **CI Gate:** Added in `.github/workflows/ci.yml`. Awaiting first successful run.
+- **Security Gate:** Added in `.github/workflows/security.yml`. Awaiting first successful run.
+- **Ruleset:** NOT YET ACTIVATED. Will be configured via GitHub admin settings after both gates have successful runs.

package/docs/NPM-PUBLISH.md

@@ -17,7 +17,7 @@ opencode-agent-skill
 npm run ci
 ```
 
-V9 CI includes syntax validation, resource validation, static skill routing, the 120-case V2 router matrix, standard/long/polyglot hidden-grader integrity checks, unit/integration tests, package dry-run, packed global-install smoke, and a plain global-install compatibility smoke.
+CI includes syntax validation, resource validation, static skill routing, the 129-case V2 router matrix, 13 V11 contract tasks, standard/long/polyglot hidden-grader integrity checks, unit/integration tests, package dry-run, packed global-install smoke, and a plain one-command install/resource sync smoke.
 
 ## Manual release-like test
 
@@ -27,7 +27,7 @@ Use:
 
 ```cmd
 npm pack
-npm install -g .\opencode-agent-skill-9.0.0.tgz --allow-scripts=opencode-agent-skill
+npm install -g .\opencode-agent-skill-11.0.0.tgz --allow-scripts=opencode-agent-skill
 ocskill status
 ocskill doctor
 ```
@@ -47,14 +47,14 @@ After publication verify:
 
 ```cmd
 npm view opencode-agent-skill versions --json
-npm view opencode-agent-skill@9.0.0 version
+npm view opencode-agent-skill@11.0.0 version
 npm dist-tag ls opencode-agent-skill
 ```
 
 The expected release tag is:
 
 ```text
-latest: 9.0.0
+latest: 11.0.0
 ```
 
 ## GitHub Actions publishing

package/docs/OPENCODE-COMPAT.md

@@ -1,6 +1,6 @@
 # OpenCode compatibility
 
-UES 8 ships one npm package for OpenCode 1.x and 2.x, while only enabling V2-native runtime features when V2 is detected.
+V11 ships one npm package for OpenCode 1.x and 2.x, while only enabling V2-native runtime features when V2 is detected.
 
 ## Detection
 
@@ -23,9 +23,9 @@ The detected major is recorded in the managed state.
 
 UES installs:
 
-- 39 namespaced skills
+- 48 namespaced skills
 - 11 namespaced commands
-- 10 namespaced subagents using compatible V1 `permission` frontmatter
+- 12 namespaced subagents using compatible V1 `permission` frontmatter
 - managed global `AGENTS.md` block
 
 The V2 runtime plugin is not installed.

package/docs/TRACE-SCHEMA.md

@@ -75,7 +75,7 @@ Keep constant:
 Compare observable success, regressions, elapsed time, tool behavior and cost rather than narrative confidence.
 
 
-## V8 runtime and evidence fields
+## V11 runtime and evidence fields
 
 Each live result may additionally contain:
 

package/docs/V11-PERCEPTION-ADAPTIVE.md

@@ -1,6 +1,6 @@
 # UES V11 — Perception & Adaptive Execution
 
-Status: development (`11.0.0-dev.1`). V10 remains npm `latest` until the V11 release gates pass.
+Status: stable (`11.0.0`). V11 is npm `latest`.
 
 ## Goal
 
@@ -211,7 +211,7 @@ Do not promote V11 to stable until all are satisfied:
 7. Packed and plain npm-install smoke tests pass.
 8. Real weak-model evaluation shows no suite regression.
 9. Any configured cache/evidence target has sufficient telemetry and passes.
-10. npm `latest` remains V10 until the V11 candidate completes these gates.
+10. npm `latest` is V11 stable; no release gate prevents promotion.
 
 ## Compatibility
 

package/docs/V12-WEAK-MODEL-INTELLIGENCE.md

@@ -0,0 +1,27 @@
+# V12 Weak-Model Intelligence Foundation
+
+Status: beta prerelease (`12.0.0-beta.0`, npm dist-tag `next`). V11 (`11.0.0`) remains the stable `latest` release until V12 earns stable-release evidence.
+
+## Goal
+
+V12 focuses on making weaker coding models more reliable on large repositories by improving measured context quality, empirical model routing, plan identity, bounded autonomous decisions, and repo-scale evaluation. It does not claim that orchestration makes one base model equivalent to a stronger model.
+
+## Foundations
+
+- Empirical model performance: observed pass rate, retries, token use and latency can rerank capability-eligible models by task class.
+- Context quality receipts: adaptive context reports required-file recall and irrelevant-context ratio.
+- Plan-scoped snapshots: every imported plan gets a SHA-256 keyed snapshot and active-plan fence before execution.
+- Decision policy: reversible local engineering choices can be auto-resolvable; publish/deploy/destructive/product decisions remain human-gated.
+- Repo-scale contract suite: deterministic generation of a 300-module monorepo fixture for larger-repository validation.
+
+## Release policy
+
+V12 is not stable merely because unit tests pass. Promotion requires healthy GitHub CI/Security gates, repo-scale validation, real weak-model baseline-vs-UES trials, no regression in existing suites, measured context recall, sufficient empirical routing samples, and Windows/Linux package/install smoke evidence.
+
+## Beta install
+
+```cmd
+npm install -g opencode-agent-skill@next
+ocskill install
+ocskill doctor
+```

package/evals/repo-scale/tasks.json

@@ -0,0 +1,62 @@
+{
+  "version": 1,
+  "kind": "repo-scale-contract-suite",
+  "description": "Deterministic large-repository contract tasks used to validate V12 weak-model context/routing foundations before live model runs.",
+  "minimumGeneratedModules": 300,
+  "tasks": [
+    {
+      "id": "cross-package-regression",
+      "category": "repo-scale",
+      "objective": "Trace a regression across package boundaries without loading the entire generated monorepo into context.",
+      "requiredFiles": [
+        "packages/pkg-0/src/mod049.mjs",
+        "packages/pkg-1/src/mod049.mjs"
+      ],
+      "acceptance": [
+        "Required-file context recall is measurable",
+        "Unrelated packages stay bounded"
+      ]
+    },
+    {
+      "id": "public-contract-ripple",
+      "category": "contract",
+      "objective": "Change a public API field and identify the API producer and web consumer that must move together.",
+      "requiredFiles": [
+        "contracts/public-api.json",
+        "apps/api/src/service.mjs",
+        "apps/web/src/consumer.mjs"
+      ],
+      "acceptance": [
+        "Contract producer and consumer are both discovered",
+        "Change-impact evidence is explicit"
+      ]
+    },
+    {
+      "id": "deep-chain-debug",
+      "category": "debugging",
+      "objective": "Diagnose a defect near the end of a fifty-module import chain using bounded evidence expansion.",
+      "requiredFiles": [
+        "packages/pkg-2/src/mod048.mjs",
+        "packages/pkg-2/src/mod049.mjs"
+      ],
+      "acceptance": [
+        "Initial context remains bounded",
+        "Recovery can expand around the failing chain"
+      ]
+    },
+    {
+      "id": "multi-package-refactor",
+      "category": "refactor",
+      "objective": "Coordinate a refactor touching several package endpoints while serializing shared contract writes.",
+      "requiredFiles": [
+        "packages/pkg-3/src/index.mjs",
+        "packages/pkg-4/src/index.mjs",
+        "contracts/public-api.json"
+      ],
+      "acceptance": [
+        "Cross-package scope is explicit",
+        "Shared contract changes are treated as a write-conflict surface"
+      ]
+    }
+  ]
+}

package/lib/context-engine-v11.mjs

@@ -3,6 +3,7 @@ import { planEvidenceBudget, evidenceValueScore } from "./evidence-budget.mjs"
 import { putEvidence } from "./evidence-store.mjs"
 import { inferTaskCapabilities } from "./capability-registry.mjs"
 import { buildPromptEnvelope, comparePromptEnvelopes } from "./prompt-cache.mjs"
+import { measureContextQuality } from "./context-quality.mjs"
 
 function taskText(task = {}) {
   return [
@@ -118,6 +119,8 @@ export async function buildAdaptiveTaskContext(root, task, options = {}) {
     recentMessages: options.recentMessages || [],
   })
 
+  const contextQuality = measureContextQuality(task, externalized.manifest, { minRequiredRecall: options.minRequiredRecall })
+
   const cache = options.previousPromptEnvelope
     ? comparePromptEnvelopes(options.previousPromptEnvelope, promptEnvelope)
     : null
@@ -128,6 +131,7 @@ export async function buildAdaptiveTaskContext(root, task, options = {}) {
     capabilities,
     evidenceBudget,
     contextManifest: externalized.manifest,
+    contextQuality,
     evidenceStore: {
       refs: externalized.externalized.length,
       externalizedBytes: externalized.externalizedBytes,

package/lib/context-quality.mjs

@@ -0,0 +1,59 @@
+function normalizePath(value) {
+  return String(value || "").replaceAll("\\", "/").replace(/^\.\//, "")
+}
+
+function declaredTaskFiles(task = {}) {
+  const files = task.files
+  const values = []
+  if (Array.isArray(files)) values.push(...files)
+  else if (files && typeof files === "object") {
+    for (const [kind, list] of Object.entries(files)) {
+      if (kind === "create") continue
+      if (Array.isArray(list)) values.push(...list)
+      else if (typeof list === "string") values.push(list)
+    }
+  }
+  if (Array.isArray(task.requiredFiles)) values.push(...task.requiredFiles)
+  return [...new Set(values.map(normalizePath).filter(Boolean))]
+}
+
+function manifestPaths(manifest = {}) {
+  const values = []
+  for (const item of manifest.excerpts || []) if (item?.path) values.push(item.path)
+  for (const item of manifest.rankedReferences || []) if (item?.path) values.push(item.path)
+  for (const item of manifest.instructions || []) {
+    if (typeof item === "string") values.push(item)
+    else if (item?.path) values.push(item.path)
+  }
+  return [...new Set(values.map(normalizePath).filter(Boolean))]
+}
+
+export function measureContextQuality(task = {}, manifest = {}, options = {}) {
+  const required = declaredTaskFiles(task)
+  const included = manifestPaths(manifest)
+  const includedSet = new Set(included)
+  const hits = required.filter((file) => includedSet.has(file))
+  const requiredFileRecall = required.length ? hits.length / required.length : null
+  const relevant = new Set(required)
+  for (const item of manifest.instructions || []) {
+    if (typeof item === "string") relevant.add(normalizePath(item))
+    else if (item?.path) relevant.add(normalizePath(item.path))
+  }
+  for (const item of manifest.excerpts || []) {
+    if (["declared", "test", "instruction"].includes(item?.role) && item?.path) relevant.add(normalizePath(item.path))
+  }
+  const irrelevant = included.filter((file) => !relevant.has(file))
+  const irrelevantRatio = included.length ? irrelevant.length / included.length : 0
+  const minRequiredRecall = Number.isFinite(Number(options.minRequiredRecall))
+    ? Math.max(0, Math.min(1, Number(options.minRequiredRecall))) : 1
+  return {
+    schemaVersion: 1,
+    requiredFiles: required,
+    includedFiles: included,
+    requiredFileHits: hits,
+    requiredFileRecall,
+    irrelevantFiles: irrelevant,
+    irrelevantRatio,
+    checks: { requiredRecallAcceptable: requiredFileRecall == null ? true : requiredFileRecall >= minRequiredRecall },
+  }
+}

package/lib/decision-policy.mjs

@@ -0,0 +1,23 @@
+const HIGH_RISK = /(npm publish|publish package|deploy|production|git push|force push|reset --hard|git clean|delete branch|drop table|truncate|rotate secret|credential|api key|purchase|payment|irreversible|public api break)/i
+const MEDIUM_RISK = /(migration|schema|dependency upgrade|lockfile|generated code|shared config|auth|permission|security)/i
+const REVERSIBLE = /(local|test|rename|format|refactor|temporary|fixture|internal|reversible)/i
+
+export function classifyDecisionPolicy(text = "", facts = {}) {
+  const value = String(text || "").trim()
+  const explicitlyIrreversible = facts.irreversible === true
+  const externalSideEffect = facts.externalSideEffect === true
+  const destructive = facts.destructive === true || HIGH_RISK.test(value)
+  const medium = MEDIUM_RISK.test(value)
+  const reversible = facts.reversible === true || (!destructive && REVERSIBLE.test(value))
+  const risk = destructive || explicitlyIrreversible || externalSideEffect ? "high" : medium ? "medium" : "low"
+  const requiresUser = risk === "high" || facts.productDecision === true
+  return {
+    schemaVersion: 1, risk, reversible, destructive, externalSideEffect, requiresUser,
+    autoResolvable: !requiresUser && (reversible || risk === "low"),
+    reason: requiresUser ? "human-approval-required" : reversible ? "reversible-local-decision" : "bounded-engineering-decision",
+  }
+}
+
+export function canAutoResolveDecision(text = "", facts = {}) {
+  return classifyDecisionPolicy(text, facts).autoResolvable
+}

package/lib/model-config.mjs

@@ -3,6 +3,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises"
 import path from "node:path"
 import { defaultModelPolicy, resolveModel } from "./model-policy.mjs"
 import { normalizeCapabilityProfile } from "./capability-registry.mjs"
+import { normalizePerformanceHistory, recordPerformanceOutcome } from "./model-performance.mjs"
 
 const TIERS = new Set(["light", "standard", "heavy"])
 
@@ -29,8 +30,10 @@ function normalize(policy) {
     if (validModelID(model)) capabilities[model] = normalizeCapabilityProfile(profile)
   }
 
+  const performance = normalizePerformanceHistory(input.performance || {})
+
   return {
-    schemaVersion: 2,
+    schemaVersion: 3,
     enabled: input.enabled === true,
     maxEscalations: Number.isInteger(input.maxEscalations)
       ? Math.max(0, Math.min(input.maxEscalations, 2))
@@ -38,6 +41,8 @@ function normalize(policy) {
     tiers,
     roleTiers,
     capabilities,
+    performance,
+    performanceMinSamples: Number.isInteger(input.performanceMinSamples) ? Math.max(1, Math.min(input.performanceMinSamples, 20)) : base.performanceMinSamples,
   }
 }
 
@@ -64,6 +69,7 @@ export async function writeModelPolicy(configDir, patch = {}) {
     tiers: { ...current.tiers, ...(patch.tiers || {}) },
     roleTiers: { ...current.roleTiers, ...(patch.roleTiers || {}) },
     capabilities: { ...(current.capabilities || {}), ...(patch.capabilities || {}) },
+    performance: patch.performance || current.performance || {},
   })
   const file = modelPolicyFile(configDir)
   await mkdir(path.dirname(file), { recursive: true })
@@ -94,3 +100,9 @@ export function applyConfiguredModel(source, role, policy) {
   }
   return lines.join("\n")
 }
+
+export async function recordModelPerformance(configDir, outcome = {}) {
+  const current = await readModelPolicy(configDir)
+  const performance = recordPerformanceOutcome(current.performance || {}, outcome)
+  return writeModelPolicy(configDir, { performance })
+}

package/lib/model-performance.mjs

@@ -0,0 +1,113 @@
+export const MODEL_TASK_CLASSES = Object.freeze([
+  "general", "repo-scale", "debugging", "architecture", "security",
+  "migration", "frontend", "backend", "visual", "browser",
+])
+const KNOWN_TASK_CLASSES = new Set(MODEL_TASK_CLASSES)
+
+function boundedNumber(value, fallback = 0, min = 0, max = Number.MAX_SAFE_INTEGER) {
+  const number = Number(value)
+  if (!Number.isFinite(number)) return fallback
+  return Math.max(min, Math.min(max, number))
+}
+
+export function inferTaskClass(text = "", facts = {}) {
+  const explicit = String(facts.taskClass || "").trim().toLowerCase()
+  if (KNOWN_TASK_CLASSES.has(explicit)) return explicit
+  const value = String(text || "").toLowerCase()
+  if (/(whole repo|entire project|large monorepo|repo[- ]scale|cross[- ]module|toàn bộ dự án|nhiều module)/.test(value)) return "repo-scale"
+  if (/(prompt injection|security|auth|authorization|permission|secret|credential|bảo mật|phân quyền)/.test(value)) return "security"
+  if (/(migration|schema|database|sql|backfill|migrate)/.test(value)) return "migration"
+  if (/(screenshot|visual|figma|pixel|responsive|storybook)/.test(value)) return "visual"
+  if (/(browser|playwright|e2e|web page|click flow)/.test(value)) return "browser"
+  if (/(root cause|debug|regression|crash|failing|bug|lỗi)/.test(value)) return "debugging"
+  if (/(architecture|architect|design decision|system design|kiến trúc)/.test(value)) return "architecture"
+  if (/(react|next\.js|vue|svelte|css|frontend|ui\b)/.test(value)) return "frontend"
+  if (/(api|service|node|python|java|dotnet|backend|server)/.test(value)) return "backend"
+  return "general"
+}
+
+export function normalizePerformanceRecord(record = {}) {
+  record = record && typeof record === "object" ? record : {}
+  const samples = Math.floor(boundedNumber(record.samples, 0, 0))
+  const successes = Math.floor(boundedNumber(record.successes, Math.round(samples * boundedNumber(record.passRate, 0, 0, 1)), 0, samples))
+  return {
+    samples,
+    successes,
+    passRate: samples ? successes / samples : 0,
+    avgRetries: boundedNumber(record.avgRetries, 0, 0, 100),
+    avgTokens: boundedNumber(record.avgTokens, 0, 0),
+    avgLatencyMs: boundedNumber(record.avgLatencyMs, 0, 0),
+    updatedAt: typeof record.updatedAt === "string" ? record.updatedAt : null,
+  }
+}
+
+export function normalizePerformanceHistory(history = {}) {
+  const output = {}
+  for (const [model, classes] of Object.entries(history || {})) {
+    if (!model || !classes || typeof classes !== "object") continue
+    const normalizedClasses = {}
+    for (const [taskClass, record] of Object.entries(classes)) {
+      if (!KNOWN_TASK_CLASSES.has(taskClass) && taskClass !== "overall") continue
+      normalizedClasses[taskClass] = normalizePerformanceRecord(record)
+    }
+    if (Object.keys(normalizedClasses).length) output[model] = normalizedClasses
+  }
+  return output
+}
+
+function mergeAverage(previousAverage, previousSamples, value) {
+  return previousSamples <= 0 ? value : ((previousAverage * previousSamples) + value) / (previousSamples + 1)
+}
+
+export function recordPerformanceOutcome(history = {}, outcome = {}) {
+  const model = String(outcome.model || "").trim()
+  if (!model) throw new Error("model performance outcome requires model")
+  const taskClass = inferTaskClass(outcome.text || "", { taskClass: outcome.taskClass })
+  const normalized = normalizePerformanceHistory(history)
+  const current = normalizePerformanceRecord(normalized[model]?.[taskClass] || {})
+  const samples = current.samples
+  const passed = outcome.passed === true
+  const next = {
+    samples: samples + 1,
+    successes: current.successes + (passed ? 1 : 0),
+    passRate: 0,
+    avgRetries: mergeAverage(current.avgRetries, samples, boundedNumber(outcome.retries, 0, 0, 100)),
+    avgTokens: mergeAverage(current.avgTokens, samples, boundedNumber(outcome.tokens, 0, 0)),
+    avgLatencyMs: mergeAverage(current.avgLatencyMs, samples, boundedNumber(outcome.latencyMs, 0, 0)),
+    updatedAt: new Date().toISOString(),
+  }
+  next.passRate = next.successes / next.samples
+  return { ...normalized, [model]: { ...(normalized[model] || {}), [taskClass]: next } }
+}
+
+function performanceAdjustment(record, minSamples) {
+  const normalized = normalizePerformanceRecord(record)
+  if (normalized.samples <= 0) return { adjustment: 0, confidence: 0, record: normalized }
+  const confidence = Math.min(1, normalized.samples / Math.max(1, minSamples))
+  if (normalized.samples < minSamples) return { adjustment: 0, confidence, record: normalized }
+  const correctness = (normalized.passRate - 0.5) * 80
+  const retryPenalty = Math.min(20, normalized.avgRetries * 5)
+  const latencyPenalty = normalized.avgLatencyMs > 0 ? Math.min(10, Math.max(0, Math.log10(Math.max(1, normalized.avgLatencyMs / 1000)) * 3)) : 0
+  return { adjustment: (correctness - retryPenalty - latencyPenalty) * confidence, confidence, record: normalized }
+}
+
+export function rerankCapabilitySelection(selection = {}, history = {}, options = {}) {
+  const taskClass = inferTaskClass(options.text || "", { taskClass: options.taskClass })
+  const minSamples = Math.max(1, Number(options.minSamples || 3))
+  const normalized = normalizePerformanceHistory(history)
+  const candidates = (selection.candidates || []).map((candidate) => {
+    const record = normalized[candidate.id]?.[taskClass] || normalized[candidate.id]?.overall || null
+    const evidence = performanceAdjustment(record, minSamples)
+    return {
+      ...candidate,
+      baseScore: Number(candidate.score || 0),
+      empiricalTaskClass: taskClass,
+      empiricalEvidence: evidence.record,
+      empiricalConfidence: Number(evidence.confidence.toFixed(4)),
+      adjustedScore: Number((Number(candidate.score || 0) + evidence.adjustment).toFixed(6)),
+    }
+  })
+  const eligible = candidates.filter((candidate) => candidate.eligible)
+    .sort((a, b) => b.adjustedScore - a.adjustedScore || b.baseScore - a.baseScore)
+  return { ...selection, selected: eligible[0] || null, candidates, taskClass, empirical: true }
+}

package/lib/model-policy.mjs

@@ -1,4 +1,5 @@
 import { inferTaskCapabilities, modelCandidatesFromPolicy, selectCapabilityCandidate } from "./capability-registry.mjs"
+import { inferTaskClass, rerankCapabilitySelection } from "./model-performance.mjs"
 
 const ROLE_TIERS = {
   "codebase-mapper": "standard",
@@ -45,12 +46,14 @@ export function resolveModel(role, attempt, config = {}) {
 
 export function defaultModelPolicy() {
   return {
-    schemaVersion: 2,
+    schemaVersion: 3,
     enabled: false,
     maxEscalations: 2,
     tiers: { light: null, standard: null, heavy: null },
     roleTiers: { ...ROLE_TIERS },
     capabilities: {},
+    performance: {},
+    performanceMinSamples: 3,
   }
 }
 
@@ -90,10 +93,14 @@ export function resolveCapabilityModel(role, attempt, taskText = "", taskPolicy
   })
   const candidates = modelCandidatesFromPolicy(config)
     .filter((candidate) => tierIndex(candidate.tier) >= tierIndex(base.tier))
-  const selection = selectCapabilityCandidate(requirements, candidates, {
+  const staticSelection = selectCapabilityCandidate(requirements, candidates, {
     role,
     preferredTier: base.tier,
   })
+  const taskClass = inferTaskClass(taskText, facts)
+  const selection = rerankCapabilitySelection(staticSelection, config.performance || {}, {
+    taskClass, text: taskText, minSamples: config.performanceMinSamples || 3,
+  })
   const capabilityEnforced = config.enabled === true && candidates.length > 0
   if (capabilityEnforced && !selection.selected) {
     return {

package/lib/repo-scale-fixture.mjs

@@ -0,0 +1,45 @@
+import { mkdir, writeFile } from "node:fs/promises"
+import path from "node:path"
+
+function moduleSource(packageIndex, moduleIndex) {
+  const previous = moduleIndex > 0
+    ? 'import { value as previous } from "./mod' + String(moduleIndex - 1).padStart(3, "0") + '.mjs"\n'
+    : ""
+  return previous + "export const value = " + (moduleIndex > 0 ? "previous + 1" : packageIndex * 1000) +
+    "\nexport function compute(input) { return value + Number(input || 0) }\n"
+}
+
+export async function generateRepoScaleFixture(root, options = {}) {
+  const packageCount = Math.max(2, Number(options.packageCount || 6))
+  const modulesPerPackage = Math.max(5, Number(options.modulesPerPackage || 50))
+  await mkdir(root, { recursive: true })
+  await writeFile(path.join(root, "package.json"), JSON.stringify({
+    name: "ues-repo-scale-fixture", private: true, type: "module", workspaces: ["packages/*", "apps/*"],
+  }, null, 2) + "\n")
+
+  let generatedModules = 0
+  for (let p = 0; p < packageCount; p += 1) {
+    const pkgRoot = path.join(root, "packages", "pkg-" + p)
+    const src = path.join(pkgRoot, "src")
+    await mkdir(src, { recursive: true })
+    await writeFile(path.join(pkgRoot, "package.json"), JSON.stringify({
+      name: "@fixture/pkg-" + p, private: true, type: "module", exports: "./src/index.mjs",
+    }, null, 2) + "\n")
+    for (let m = 0; m < modulesPerPackage; m += 1) {
+      await writeFile(path.join(src, "mod" + String(m).padStart(3, "0") + ".mjs"), moduleSource(p, m))
+      generatedModules += 1
+    }
+    await writeFile(path.join(src, "index.mjs"),
+      'export { value, compute } from "./mod' + String(modulesPerPackage - 1).padStart(3, "0") + '.mjs"\n')
+  }
+
+  const apiRoot = path.join(root, "apps", "api", "src")
+  const webRoot = path.join(root, "apps", "web", "src")
+  const contracts = path.join(root, "contracts")
+  await mkdir(apiRoot, { recursive: true }); await mkdir(webRoot, { recursive: true }); await mkdir(contracts, { recursive: true })
+  await writeFile(path.join(contracts, "public-api.json"), JSON.stringify({ version: 1, fields: ["id", "name", "status"] }, null, 2) + "\n")
+  await writeFile(path.join(apiRoot, "service.mjs"), 'export function serialize(row) { return { id: row.id, name: row.name, status: row.status } }\n')
+  await writeFile(path.join(webRoot, "consumer.mjs"), 'export function render(item) { return item.name + ":" + item.status }\n')
+  await writeFile(path.join(root, "AGENTS.md"), "# Fixture instructions\n\nPreserve public contracts and update focused tests.\n")
+  return { root, packageCount, modulesPerPackage, generatedModules, totalPrimaryFiles: generatedModules + packageCount + 5 }
+}

package/lib/task-engine.mjs

@@ -15,6 +15,8 @@ import { putEvidence } from "./evidence-store.mjs"
 import { inferTaskCapabilities } from "./capability-registry.mjs"
 import { buildPromptEnvelope } from "./prompt-cache.mjs"
 import { externalizeContextExcerpts } from "./context-engine-v11.mjs"
+import { assertActivePlanScope, persistPlanScope } from "./work-plan-scope.mjs"
+import { classifyDecisionPolicy } from "./decision-policy.mjs"
 
 const WORK_DIR = ".ues-work"
 const STATE_SCHEMA = 4
@@ -49,6 +51,8 @@ export function workPaths(root, slug) {
     events: path.join(dir, "EVENTS.jsonl"),
     tasks: path.join(dir, "tasks"),
     reports: path.join(dir, "reports"),
+    plans: path.join(dir, "plans"),
+    activePlan: path.join(dir, "ACTIVE_PLAN.json"),
     lock: path.join(dir, ".state-lock"),
   }
 }
@@ -268,6 +272,7 @@ export async function initWork(root, slug, goal) {
 
   await mkdir(paths.tasks, { recursive: true })
   await mkdir(paths.reports, { recursive: true })
+  await mkdir(paths.plans, { recursive: true })
   const createdAt = now()
   const cleanGoal = String(goal || "").trim() || "Define the requested engineering outcome."
 
@@ -285,6 +290,7 @@ export async function initWork(root, slug, goal) {
     planImportedAt: null,
     planHash: null,
     planApproval: null,
+    planScope: null,
     integrationVerification: null,
     tasks: {},
     decisions: [],
@@ -383,6 +389,7 @@ export async function importPlan(root, slug, planInput) {
     }
 
     const updatedAt = now()
+    const planScope = await persistPlanScope(loaded.paths, hash, plan, { importedAt: updatedAt, previousPlanHash: loaded.state.planHash || null })
     const state = {
       ...loaded.state,
       schemaVersion: STATE_SCHEMA,
@@ -392,6 +399,7 @@ export async function importPlan(root, slug, planInput) {
       planImportedAt: updatedAt,
       planHash: hash,
       planApproval: { status: "pending", planHash: hash, at: updatedAt, evidence: null },
+      planScope,
       integrationVerification: null,
       checkpoint: null,
       evidencePolicy: evidencePolicyForPlan(plan),
@@ -414,6 +422,7 @@ export async function approvePlan(root, slug, evidence, options = {}) {
     const loaded = await loadWork(root, slug)
     if (!loaded.plan) throw new Error("PLAN.json is missing")
     const hash = planHash(loaded.plan)
+    await assertActivePlanScope(loaded.paths, loaded.state.planHash || hash)
     if (loaded.state.planHash && loaded.state.planHash !== hash) {
       throw new Error("PLAN.json changed after import; re-import it before approval")
     }
@@ -540,6 +549,7 @@ export async function workStatus(root, slug) {
     blockers: loaded.state.blockers || [],
     planApproval: loaded.state.planApproval || null,
     integrationVerification: loaded.state.integrationVerification || null,
+    planScope: loaded.state.planScope || null,
     evidence: {
       receiptBacked,
       completed,
@@ -557,6 +567,7 @@ export async function startTask(root, slug, taskID, options = {}) {
   const result = await withWorkLock(root, slug, async () => {
     const loaded = await loadWork(root, slug)
     if (!loaded.plan) throw new Error("PLAN.json is missing; import a valid plan first")
+    await assertActivePlanScope(loaded.paths, loaded.state.planHash || planHash(loaded.plan))
     if (!planIsApproved(loaded.state, loaded.plan)) {
       throw new Error("plan is not approved; run ues-plan-checker and 'ocskill work approve-plan' first")
     }
@@ -888,16 +899,19 @@ export async function failTask(root, slug, taskID, reason, options = {}) {
 }
 
 export async function addDecision(root, slug, decision) {
-  const text = String(decision || "").trim()
+  const input = decision && typeof decision === "object" ? decision : { text: decision }
+  const text = String(input.text || "").trim()
   if (!text) throw new Error("decision text is required")
-
+  const policy = classifyDecisionPolicy(text, input.facts || input)
+  if (input.auto === true && !policy.autoResolvable) throw new Error("decision requires human approval before automatic resolution")
   return withWorkLock(root, slug, async () => {
     const loaded = await loadWork(root, slug)
     loaded.state.decisions ??= []
     const timestamp = now()
-    loaded.state.decisions.push({ at: timestamp, text })
+    loaded.state.decisions.push({ at: timestamp, text, policy, source: input.source || (input.auto === true ? "auto-ruling" : "human-or-agent") })
     loaded.state.updatedAt = timestamp
     await writeJson(loaded.paths.state, loaded.state)
+    await journal(loaded.paths, "decision.recorded", { text, policy })
     return loaded.state
   })
 }

package/lib/work-plan-scope.mjs

@@ -0,0 +1,49 @@
+import { existsSync } from "node:fs"
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import path from "node:path"
+
+function validPlanHash(value) {
+  return /^[a-f0-9]{64}$/i.test(String(value || ""))
+}
+
+export function planScopePaths(paths, planHash) {
+  if (!validPlanHash(planHash)) throw new Error("plan scope requires a SHA-256 plan hash")
+  const dir = path.join(paths.plans, planHash)
+  return { dir, plan: path.join(dir, "PLAN.json"), metadata: path.join(dir, "SCOPE.json") }
+}
+
+export async function persistPlanScope(paths, planHash, plan, metadata = {}) {
+  const scoped = planScopePaths(paths, planHash)
+  await mkdir(scoped.dir, { recursive: true })
+  await writeFile(scoped.plan, JSON.stringify(plan, null, 2) + "\n", "utf8")
+  const record = {
+    schemaVersion: 1,
+    planHash,
+    importedAt: metadata.importedAt || new Date().toISOString(),
+    previousPlanHash: metadata.previousPlanHash || null,
+    relativeDir: path.relative(paths.root, scoped.dir).replaceAll("\\", "/"),
+  }
+  await writeFile(scoped.metadata, JSON.stringify(record, null, 2) + "\n", "utf8")
+  await writeFile(paths.activePlan, JSON.stringify(record, null, 2) + "\n", "utf8")
+  return record
+}
+
+export async function readActivePlanScope(paths) {
+  if (!existsSync(paths.activePlan)) return null
+  try { return JSON.parse(await readFile(paths.activePlan, "utf8")) }
+  catch { throw new Error("ACTIVE_PLAN.json is invalid; re-import the plan before execution") }
+}
+
+export async function assertActivePlanScope(paths, expectedPlanHash) {
+  const active = await readActivePlanScope(paths)
+  if (!active) return { legacy: true, planHash: expectedPlanHash || null }
+  if (!validPlanHash(active.planHash)) throw new Error("ACTIVE_PLAN.json contains an invalid plan hash")
+  if (expectedPlanHash && active.planHash !== expectedPlanHash) {
+    throw new Error("active plan scope mismatch; re-import PLAN.json before executing tasks")
+  }
+  const scoped = planScopePaths(paths, active.planHash)
+  if (!existsSync(scoped.plan) || !existsSync(scoped.metadata)) {
+    throw new Error("active plan scope snapshot is incomplete; re-import PLAN.json")
+  }
+  return { ...active, legacy: false }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-agent-skill",
-  "version": "11.0.0",
+  "version": "12.0.0-beta.0",
   "description": "Perception-aware evidence-first engineering runtime with adaptive context, capability routing, visual/browser verification, weak-model recovery and benchmark-gated execution for OpenCode",
   "type": "module",
   "bin": {
@@ -23,7 +23,7 @@
     "evals": "node scripts/eval-skills.mjs",
     "evals:live:validate": "node scripts/validate-live-suite.mjs",
     "test": "node --test test/*.test.mjs",
-    "ci": "npm run syntax && npm run validate && npm run evals && npm run evals:router && npm run evals:v11:validate && npm run evals:live:validate && npm run evals:long:validate && npm run evals:polyglot:validate && npm test && npm pack --dry-run && npm run smoke:pack && npm run smoke:plain-install",
+    "ci": "npm run syntax && npm run validate && npm run docs:check && npm run evals && npm run evals:router && npm run evals:v11:validate && npm run evals:v12:validate && npm run evals:repo-scale:validate && npm run evals:live:validate && npm run evals:long:validate && npm run evals:polyglot:validate && npm test && npm pack --dry-run && npm run smoke:pack && npm run smoke:plain-install",
     "postinstall": "node scripts/install.mjs",
     "preuninstall": "node scripts/uninstall.mjs",
     "prepublishOnly": "npm run ci",
@@ -42,13 +42,16 @@
     "dashboard": "node scripts/control-center.mjs",
     "evals:matrix": "node scripts/eval-matrix.mjs",
     "smoke:plain-install": "node scripts/smoke-plain-install.mjs",
+    "docs:check": "node scripts/check-release-consistency.mjs",
     "release:check-tag": "node scripts/check-release-tag.mjs",
     "evals:polyglot:validate": "node scripts/validate-live-suite.mjs --suite polyglot",
     "evals:polyglot": "node scripts/eval-live.mjs --suite polyglot",
     "evals:matrix:gate": "node scripts/eval-matrix.mjs --require-confidence",
     "evals:ablation": "node scripts/eval-ablation.mjs",
     "evals:v11": "node --test test/*-v11.test.mjs",
-    "evals:v11:validate": "node scripts/validate-v11-suite.mjs"
+    "evals:v11:validate": "node scripts/validate-v11-suite.mjs",
+    "evals:repo-scale:validate": "node scripts/validate-repo-scale-suite.mjs",
+    "evals:v12:validate": "node scripts/validate-v12-foundation.mjs"
   },
   "keywords": [
     "opencode",

package/scripts/check-release-consistency.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+
+function readJson(root, relative) {
+  const file = path.join(root, relative)
+  if (!existsSync(file)) {
+    return { ok: false, error: `${relative}: file not found`, value: null }
+  }
+  try {
+    return { ok: true, error: null, value: JSON.parse(readFileSync(file, "utf8")) }
+  } catch (e) {
+    return { ok: false, error: `${relative}: invalid JSON (${e.message})`, value: null }
+  }
+}
+
+function readText(root, relative) {
+  const file = path.join(root, relative)
+  if (!existsSync(file)) {
+    return { ok: false, error: `${relative}: file not found`, value: null }
+  }
+  return { ok: true, error: null, value: readFileSync(file, "utf8") }
+}
+
+function countSkillDirs(root) {
+  const fullPath = path.join(root, "global-config", "skills")
+  if (!existsSync(fullPath)) return { ok: false, error: "global-config/skills: directory not found", value: 0 }
+  const entries = readdirSync(fullPath, { withFileTypes: true })
+  const count = entries.filter((entry) => entry.isDirectory() && existsSync(path.join(fullPath, entry.name, "SKILL.md"))).length
+  return { ok: true, error: null, value: count }
+}
+
+function countDir(root, dirPath, filter) {
+  const fullPath = path.join(root, dirPath)
+  if (!existsSync(fullPath)) {
+    return { ok: false, error: `${dirPath}: directory not found`, value: 0 }
+  }
+  const entries = readdirSync(fullPath, { withFileTypes: true })
+  const count = filter ? entries.filter(filter).length : entries.length
+  return { ok: true, error: null, value: count }
+}
+
+export function checkReleaseConsistency(root) {
+  root = root || DEFAULT_ROOT
+  const errors = []
+  const warnings = []
+
+  function rJson(relative) {
+    return readJson(root, relative)
+  }
+  function rText(relative) {
+    return readText(root, relative)
+  }
+  function rCount(dirPath, filter) {
+    return countDir(root, dirPath, filter)
+  }
+
+  // 1. package.json version == package-lock.json version
+  const pkg = rJson("package.json")
+  const lock = rJson("package-lock.json")
+  if (pkg.ok && lock.ok) {
+    const pkgVersion = pkg.value.version
+    const lockVersion = lock.value.version
+    if (pkgVersion !== lockVersion) {
+      errors.push(`package.json version (${pkgVersion}) != package-lock.json version (${lockVersion})`)
+    }
+  } else {
+    if (!pkg.ok) errors.push(pkg.error)
+    if (!lock.ok) errors.push(lock.error)
+  }
+
+  // 2. Count skills, commands, subagents
+  const skillRes = countSkillDirs(root)
+  const commandRes = rCount("global-config/commands", (e) => e.isFile() && e.name.endsWith(".md"))
+  const agentRes = rCount("global-config/agents", (e) => e.isFile() && e.name.endsWith(".md"))
+  const skillCount = skillRes.ok ? skillRes.value : 0
+  const commandCount = commandRes.ok ? commandRes.value : 0
+  const agentCount = agentRes.ok ? agentRes.value : 0
+  if (!skillRes.ok) errors.push(skillRes.error)
+  if (!commandRes.ok) errors.push(commandRes.error)
+  if (!agentRes.ok) errors.push(agentRes.error)
+
+  const expectedVersion = pkg.ok ? pkg.value.version : "unknown"
+  const routing = rJson("evals/routing.json")
+  const routerTriggers = rJson("evals/router-triggers.json")
+  const staticScenarioCount = routing.ok && Array.isArray(routing.value.scenarios) ? routing.value.scenarios.length : 0
+  const routerCaseCount = routerTriggers.ok && Array.isArray(routerTriggers.value.cases) ? routerTriggers.value.cases.length : 0
+  if (!routing.ok) errors.push(routing.error)
+  if (!routerTriggers.ok) errors.push(routerTriggers.error)
+
+  // 3. Check README current version block
+  const readme = rText("README.md")
+  if (readme.ok) {
+    const versionMatch = readme.value.match(/Phiên bản hiện tại:\s*\n```text\n(\S+)/)
+    if (versionMatch && versionMatch[1] !== expectedVersion) {
+      errors.push(`README.md: current version says ${versionMatch[1]}, expected ${expectedVersion}`)
+    } else if (!versionMatch) {
+      errors.push("README.md: could not find current version block")
+    }
+    if (staticScenarioCount && !readme.value.includes("**" + staticScenarioCount + " static skill-routing scenarios**")) {
+      errors.push("README.md: static routing scenario count drift (actual: " + staticScenarioCount + ")")
+    }
+    if (routerCaseCount && !readme.value.includes("**" + routerCaseCount + " V2 router cases**")) {
+      errors.push("README.md: router case count drift (actual: " + routerCaseCount + ")")
+    }
+  } else {
+    errors.push(readme.error)
+  }
+
+  // 4. Check V11 docs for stale status markers
+  const v11Docs = ["docs/V11-PERCEPTION-ADAPTIVE.md", "docs/V11-PERCEPTION-ADAPTIVE-EXECUTION.md"]
+  for (const doc of v11Docs) {
+    const content = rText(doc)
+    if (!content.ok) {
+      errors.push(content.error)
+      continue
+    }
+    if (content.value.includes("Status: development")) {
+      errors.push(`${doc}: still marked as development`)
+    }
+    if (content.value.includes("11.0.0-dev.")) {
+      errors.push(`${doc}: still references dev version 11.0.0-dev.*`)
+    }
+    if (content.value.includes("npm `latest` remains V10")) {
+      errors.push(`${doc}: still says V10 remains npm latest`)
+    }
+  }
+
+  // 5. Verify docs reflect actual counts (skip historical sections)
+  const docsToCheck = ["README.md", "docs/ENGINEERING-DESIGN.md", "docs/OPENCODE-COMPAT.md"]
+  for (const doc of docsToCheck) {
+    const content = rText(doc)
+    if (!content.ok) {
+      errors.push(content.error)
+      continue
+    }
+    const sections = content.value.split(/\n(?=#{1,6}\s)/)
+    for (const section of sections) {
+      const isHistorical = /^\s*#{1,6}\s+.*(V\d+\.|UES\s+\d+\.|historical|Historical)/im.test(section)
+      if (isHistorical) continue
+      if (section.includes("39 skills") || section.includes("39 namespaced skills")) {
+        errors.push(`${doc}: current section still references 39 skills (actual: ${skillCount})`)
+      }
+      if (section.includes("10 namespaced subagents") || section.includes("10 subagents")) {
+        errors.push(`${doc}: current section still references 10 subagents (actual: ${agentCount})`)
+      }
+      if (section.includes("34 static") && section.includes("scenarios")) {
+        errors.push(`${doc}: current section still references 34 static scenarios (actual: ${staticScenarioCount})`)
+      }
+    }
+  }
+
+  // 6. Check CI workflow
+  const ciYaml = rText(".github/workflows/ci.yml")
+  if (ciYaml.ok) {
+    if (!ciYaml.value.includes("evals:v11:validate")) {
+      errors.push(".github/workflows/ci.yml: missing evals:v11:validate job")
+    }
+    if (!/^\s*name:\s*CI Gate\s*$/m.test(ciYaml.value)) errors.push(".github/workflows/ci.yml: missing CI Gate aggregate job name")
+    if (!/needs:\s*\[\s*static\s*,\s*unit\s*,\s*package\s*\]/m.test(ciYaml.value)) errors.push(".github/workflows/ci.yml: CI Gate must depend on static, unit and package")
+    if (!/if:\s*always\(\)/m.test(ciYaml.value)) errors.push(".github/workflows/ci.yml: aggregate gate must use if: always()")
+    if (!ciYaml.value.includes("docs:check")) errors.push(".github/workflows/ci.yml: missing docs:check job")
+    for (const check of ["evals:v12:validate","evals:repo-scale:validate"]) {
+      if (!ciYaml.value.includes(check)) errors.push(".github/workflows/ci.yml: missing " + check + " job")
+    }
+  } else {
+    errors.push(ciYaml.error)
+  }
+
+  // 7. Check Security workflow
+  const securityYaml = rText(".github/workflows/security.yml")
+  if (securityYaml.ok) {
+    if (!/^\s*name:\s*Security Gate\s*$/m.test(securityYaml.value)) errors.push(".github/workflows/security.yml: missing Security Gate aggregate job name")
+    if (!/needs:\s*\[\s*codeql\s*,\s*dependency-review\s*\]/m.test(securityYaml.value)) errors.push(".github/workflows/security.yml: Security Gate must depend on codeql and dependency-review")
+  } else {
+    errors.push(securityYaml.error)
+  }
+
+  // 8. Check publish workflow idempotency
+  const publishYaml = rText(".github/workflows/publish.yml")
+  if (publishYaml.ok) {
+    if (!publishYaml.value.includes("already published")) {
+      errors.push(".github/workflows/publish.yml: missing idempotency check for existing versions")
+    }
+  } else {
+    errors.push(publishYaml.error)
+  }
+
+  // 9. Check npm script docs:check exists
+  if (pkg.ok) {
+    const pkgScripts = pkg.value.scripts || {}
+    if (!pkgScripts["docs:check"]) {
+      warnings.push("package.json: missing docs:check npm script")
+    }
+  }
+
+  return {
+    pass: errors.length === 0,
+    errors,
+    warnings,
+    version: expectedVersion,
+    skillCount,
+    commandCount,
+    subagentCount: agentCount,
+    staticScenarioCount,
+    routerCaseCount,
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const result = checkReleaseConsistency(process.env.UES_BUNDLE_ROOT || DEFAULT_ROOT)
+  if (result.warnings.length) {
+    console.warn("Warnings:")
+    for (const w of result.warnings) console.warn(`  WARN: ${w}`)
+  }
+  if (result.errors.length) {
+    console.error("Release consistency check FAILED:")
+    for (const e of result.errors) console.error(`  - ${e}`)
+    process.exit(1)
+  }
+  console.log(
+    `Release consistency check PASS: package=${result.version}, skills=${result.skillCount}, commands=${result.commandCount}, subagents=${result.subagentCount}`,
+  )
+}

package/scripts/validate-repo-scale-suite.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { mkdtemp, readFile, rm } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { generateRepoScaleFixture } from "../lib/repo-scale-fixture.mjs"
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+const suite = JSON.parse(await readFile(path.join(root, "evals", "repo-scale", "tasks.json"), "utf8"))
+const errors = []
+if (!Array.isArray(suite.tasks) || suite.tasks.length < 4) errors.push("repo-scale suite must define at least 4 tasks")
+for (const task of suite.tasks || []) {
+  if (!task.id || !task.objective || task.objective.length < 40) errors.push((task.id || "<missing>") + ": objective too weak")
+  if (!Array.isArray(task.requiredFiles) || task.requiredFiles.length < 2) errors.push((task.id || "<missing>") + ": requiredFiles must contain at least 2 paths")
+  if (!Array.isArray(task.acceptance) || task.acceptance.length < 2) errors.push((task.id || "<missing>") + ": acceptance must contain at least 2 checks")
+}
+const tmp = await mkdtemp(path.join(os.tmpdir(), "ues-repo-scale-"))
+try {
+  const generated = await generateRepoScaleFixture(tmp)
+  if (generated.generatedModules < Number(suite.minimumGeneratedModules || 300)) errors.push("generated repo too small: " + generated.generatedModules + " modules")
+} finally { await rm(tmp, { recursive: true, force: true }) }
+if (errors.length) {
+  console.error("Repo-scale suite validation failed:")
+  for (const error of errors) console.error("- " + error)
+  process.exit(1)
+}
+console.log("Validated repo-scale suite: " + suite.tasks.length + " tasks, >=" + suite.minimumGeneratedModules + " generated modules.")

package/scripts/validate-v12-foundation.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+const errors = []
+const required = [
+  "lib/model-performance.mjs","lib/context-quality.mjs","lib/work-plan-scope.mjs",
+  "lib/decision-policy.mjs","lib/repo-scale-fixture.mjs","evals/repo-scale/tasks.json",
+  "scripts/validate-repo-scale-suite.mjs",
+]
+for (const relative of required) if (!existsSync(path.join(root, relative))) errors.push("missing V12 foundation file: " + relative)
+const pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"))
+for (const script of ["evals:v12:validate","evals:repo-scale:validate"]) if (!pkg.scripts?.[script]) errors.push("package.json missing script " + script)
+const tasks = JSON.parse(await readFile(path.join(root, "evals", "repo-scale", "tasks.json"), "utf8"))
+if ((tasks.tasks || []).length < 4) errors.push("V12 repo-scale suite needs at least 4 contract tasks")
+if (errors.length) {
+  console.error("V12 foundation validation failed:")
+  for (const error of errors) console.error("- " + error)
+  process.exit(1)
+}
+console.log("Validated V12 weak-model intelligence foundation files and repo-scale contracts.")