skillpack-one 0.1.0-alpha.10

package/docs/npm-release.md

@@ -0,0 +1,88 @@
+# Publishing SkillPack One to npm
+
+SkillPack One publishes from a reviewed GitHub Release through npm Trusted Publishing. The permanent workflow uses short-lived OIDC credentials, not a repository `NPM_TOKEN`, and npm automatically attaches provenance for a public package built from this public repository.
+
+## What the workflow enforces
+
+`.github/workflows/publish-npm.yml`:
+
+- runs only when a GitHub Release is published;
+- requires the tagged commit to be reachable from `origin/main`;
+- requires the tag to equal `v<package.json version>` exactly;
+- requires GitHub's prerelease flag to agree with SemVer;
+- maps prereleases to npm tag `next` and stable versions to `latest`;
+- runs `npm run ci` and `npm pack --dry-run` before publishing;
+- uses a GitHub-hosted runner, an `npm` deployment environment, and only `contents: read` plus `id-token: write`;
+- installs dependencies with lifecycle scripts disabled and disables package-manager caching in the privileged publish job.
+
+## One-time bootstrap for a new npm package
+
+npm requires a package to exist before a Trusted Publisher can be configured. At the time this guide was written, `skillpack-one` was not registered. The first version must therefore be created once by a maintainer with npm account-level 2FA.
+
+1. Merge the release commit containing version `0.1.0-alpha.10` into `main`, then create and push the exact tag without publishing a GitHub Release for this bootstrap version:
+
+   ```sh
+   git tag -a v0.1.0-alpha.10 -m "SkillPack One v0.1.0-alpha.10"
+   git push origin v0.1.0-alpha.10
+   ```
+
+2. From a clean checkout of that tag, authenticate interactively and verify the exact payload:
+
+   ```sh
+   npm install --global npm@11.19.1
+   npm login
+   npm ci --ignore-scripts
+   npm run ci
+   npm pack --dry-run
+   npm publish --access public --tag next
+   ```
+
+3. Confirm `https://www.npmjs.com/package/skillpack-one` shows `0.1.0-alpha.10` under `next`. Do not create a GitHub Release for this already-published bootstrap version because the automated workflow correctly rejects immutable duplicate versions.
+
+## Configure tokenless publishing
+
+1. In GitHub repository settings, create an Environment named exactly `npm`. Add required reviewers and restrict deployment to protected release tags as appropriate for the repository.
+2. With npm 11.19.1 or newer and account-level 2FA enabled, configure the package trust relationship:
+
+   ```sh
+   npm login
+   npm trust github skillpack-one \
+     --repo WnagoiYy/skillpack-one \
+     --file publish-npm.yml \
+     --env npm \
+     --allow-publish
+   ```
+
+   The filename and Environment name are case-sensitive. The workflow file must already exist on the default branch.
+3. Verify the relationship with `npm trust list skillpack-one` or in npm package settings under **Trusted publishing**.
+4. After one successful automated release, set npm **Publishing access** to **Require two-factor authentication and disallow tokens**, then revoke obsolete write tokens.
+5. Protect `v*` tags in GitHub so unreviewed commits cannot create release candidates.
+
+## Normal release
+
+1. Update `package.json`, `package-lock.json`, and `CHANGELOG.md` in a reviewed pull request. Never reuse a published version.
+2. Merge the pull request into `main` and wait for CI.
+3. Create an exact `v<version>` tag from that `main` commit.
+4. Publish a GitHub Release for the tag. Mark it as a prerelease if and only if the package version contains a SemVer prerelease suffix.
+5. Approve the `npm` Environment deployment. The workflow publishes prereleases under `next` and stable versions under `latest`.
+6. Verify the package and its provenance:
+
+   ```sh
+   npm view skillpack-one version dist-tags repository --json
+   npm install --global skillpack-one@next
+   skillpack --version
+   npm audit signatures
+   ```
+
+## Failure and rollback
+
+- If validation fails before `npm publish`, fix the source, assign a new version, and publish another GitHub Release. Do not rerun after changing the contents behind an existing tag.
+- npm package versions are immutable. A bad release is replaced by a corrective version, not overwritten.
+- With interactive 2FA, mark a known-bad version using `npm deprecate skillpack-one@<version> "<reason>"`.
+- Restore a dist-tag with `npm dist-tag add skillpack-one@<known-good-version> next` or `latest`, then publish a corrected version.
+- Avoid `npm unpublish` except for a narrowly justified security emergency; even unpublished name/version pairs cannot be reused.
+
+For a stricter future posture, change the trusted publisher to stage-only permission and replace `npm publish` with `npm stage publish`. npm then requires a separate 2FA approval before public availability. This cannot bootstrap a brand-new package.
+
+Official references: [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/), [`npm trust`](https://docs.npmjs.com/cli/v11/commands/npm-trust/), [npm provenance](https://docs.npmjs.com/generating-provenance-statements/), and [GitHub package publishing](https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages).
+

package/docs/plans/2026-09-02-evidence-driven-control-plane-design.md

@@ -0,0 +1,52 @@
+# Evidence-driven Skill control plane design
+
+## Status
+
+Candidate design for `research/skill-lifecycle-evidence`. It does not authorize promotion to `main`.
+
+## Problem
+
+SkillPack One already separates Category Skills, Atomic Skills, Capability Packs, runtime state, and Meta governance. The current implementation still has three evidence gaps:
+
+1. routing metrics reward finding any expected Atom but do not measure recovery of the complete set required by a compositional request;
+2. security metadata does not express the distinct trust boundaries crossed from contribution through evolution;
+3. evolution proposals are bounded by files and datasets, but individual optimization attempts do not yet record a text-edit budget, strict validation decision, or rejected-edit evidence.
+
+These gaps correspond to findings in SkillRet, SkillRouter, realistic in-the-wild Skill evaluation, Agent Skill Security, SkillNet, and SkillOpt. The papers are evidence inputs, not instructions and not automatic authorization to change active Skills.
+
+## Chosen architecture
+
+Keep the deterministic, inspectable Category-to-Atom router as the portable baseline. Add an evaluation profile that reports per-query Atom recall and strict full coverage alongside Hit@K and MRR. Allow a benchmark item to name functionally acceptable alternatives so a correct substitute is not counted as a false negative. Add a development suite of same-domain, functionally wrong distractors. Learned retrieval remains an optional backend and must beat this baseline on downstream effect, protected safety metrics, latency, and cost.
+
+Represent lifecycle security as a separate review artifact with six stages: authoring, storage, retrieval, selection, execution, and evolution. Every stage records its trust assumption, reviewed threats, evidence, status, and residual risk. A release decision requires all applicable stages to pass; `not-applicable` requires a reason. This does not claim that static or LLM review replaces sandboxing, permission enforcement, or runtime information-flow controls.
+
+Represent every optimizer step as an append-only evolution attempt. An attempt contains bounded `add`, `delete`, or `replace` edits, a selection score before and after, an acceptance rule, and rejection evidence. Acceptance is strict improvement only; ties and safety regressions are rejected. Training-only memory may summarize repeated accepted and rejected patterns, but it is not shipped in an Atomic Skill or exposed during ordinary task execution.
+
+Materialize only relations already supported by reviewed repository evidence: `confusable-with` from contracts, `packaged-in` and `compose-with` from Capability Packs, and `depends-on` from pack ordering. The relation graph supplements the taxonomy and does not become a second classification standard.
+
+## Data flow
+
+```text
+request -> deterministic router -> ranked categories/atoms
+        -> routing evaluator -> hit, recall, full coverage, MRR, safety
+
+contribution/update -> lifecycle review -> bounded evolution attempt
+                    -> dev/selection evaluation -> accept or reject
+                    -> untouched held-out/adversarial evaluation
+                    -> independent promotion or rollback
+
+contracts + packs -> reviewed typed relation graph -> diagnostics/composition
+```
+
+## Error handling and safety
+
+- Missing expected alternatives are treated as schema errors, not silently ignored.
+- Multi-Atom full coverage is zero unless every required capability group is represented inside K.
+- A lifecycle review cannot pass with a failed or unreviewed applicable stage.
+- Evolution attempts reject ties, permission expansion without approval, protected regression, unbounded rewrites, and edits outside the proposal.
+- Candidate changes remain on a branch until an independent reviewer approves promotion.
+
+## Evaluation
+
+Unit tests cover equivalence-aware recall/full coverage, hard distractors, relation graph validity, security-stage gating, and strict evolution acceptance. Existing multilingual and adversarial suites remain protected and unchanged. The paper reports deterministic repository validation separately from future model-backed retrieval and task-effect experiments.
+

package/docs/plans/2026-09-02-evidence-driven-control-plane.md

@@ -0,0 +1,136 @@
+# Evidence-driven Skill Control Plane Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add evidence-backed multi-Skill retrieval metrics, lifecycle security review, bounded evolution attempts, a minimal typed relation graph, and a publication-style system paper without weakening existing gates.
+
+**Architecture:** Preserve the deterministic Category-to-Atom router as the portable baseline and add orthogonal, machine-readable control-plane artifacts. New mechanisms remain optional until independently promoted, while existing protected datasets and release gates stay unchanged.
+
+**Tech Stack:** TypeScript 7, Node.js 24, Vitest, JSON Schema 2020-12, YAML, Markdown, BibTeX
+
+---
+
+### Task 1: Record research evidence and design boundaries
+
+**Files:**
+- Create: `docs/research/2026-09-02-retrieval-security-optimization.md`
+- Create: `docs/zh-CN/research/2026-09-02-retrieval-security-optimization.md`
+- Modify: `docs/research/2026-09-02-agent-skill-literature.md`
+- Modify: `docs/zh-CN/research/2026-09-02-agent-skill-literature.md`
+
+**Step 1:** Add an evidence-to-decision matrix for SkillRet, realistic in-the-wild Skill evaluation, Agent Skill Security, SkillNet, SkillRouter, and SkillOpt.
+
+**Step 2:** Record adopted, deferred, and rejected interpretations, including each paper's stated limitations.
+
+**Step 3:** Verify every claim against the official paper and keep direct source URLs.
+
+### Task 2: Add equivalence-aware compositional routing metrics
+
+**Files:**
+- Modify: `src/types.ts`
+- Modify: `src/eval/evaluate.ts`
+- Modify: `schemas/eval-dataset.schema.json`
+- Modify: `tests/eval.test.ts`
+- Create: `evals/datasets/routing-hard-distractors.yaml`
+
+**Step 1:** Write failing tests for Atom Recall@3, Full Coverage@3, and acceptable functional alternatives.
+
+**Step 2:** Run `npm test -- tests/eval.test.ts` and confirm the new expectations fail.
+
+**Step 3:** Add `acceptableAtomGroups` to routing examples and implement group-aware ranking, recall, and full coverage.
+
+**Step 4:** Add a same-domain hard-distractor development suite without modifying protected datasets.
+
+**Step 5:** Run `npm test -- tests/eval.test.ts` and confirm it passes.
+
+### Task 3: Add lifecycle security review artifacts
+
+**Files:**
+- Create: `schemas/lifecycle-security-review.schema.json`
+- Create: `src/security/lifecycle.ts`
+- Create: `tests/security-lifecycle.test.ts`
+- Create: `docs/security-lifecycle.md`
+- Create: `docs/zh-CN/security-lifecycle.md`
+
+**Step 1:** Write failing tests for missing stages, failed stages, unjustified `not-applicable`, and a fully passing review.
+
+**Step 2:** Run `npm test -- tests/security-lifecycle.test.ts` and confirm failure.
+
+**Step 3:** Implement six-stage review types and deterministic gate evaluation.
+
+**Step 4:** Add the public JSON Schema and document that semantic review is not a runtime security boundary.
+
+**Step 5:** Run the focused tests and schema tests.
+
+### Task 4: Add bounded evolution attempts
+
+**Files:**
+- Create: `schemas/evolution-attempt.schema.json`
+- Create: `src/train/attempts.ts`
+- Modify: `src/train/types.ts`
+- Modify: `skill-src/meta-skill-governor/SKILL.md`
+- Create: `tests/evolution-attempts.test.ts`
+
+**Step 1:** Write failing tests for strict improvement, tied scores, exceeded edit budgets, invalid operations, and protected regressions.
+
+**Step 2:** Run `npm test -- tests/evolution-attempts.test.ts` and confirm failure.
+
+**Step 3:** Implement bounded add/delete/replace attempt validation and acceptance decisions.
+
+**Step 4:** Update the canonical Meta Skill to require rejected-attempt evidence and keep optimizer memory out of deployed Skills.
+
+**Step 5:** Regenerate Skill projections with `npm run skills:generate` and run focused tests.
+
+### Task 5: Materialize reviewed Skill relations
+
+**Files:**
+- Create: `schemas/skill-relation-graph.schema.json`
+- Create: `src/relations.ts`
+- Create: `tests/relations.test.ts`
+
+**Step 1:** Write failing tests for `confusable-with`, `packaged-in`, `compose-with`, and ordered `depends-on` edges.
+
+**Step 2:** Implement deterministic graph construction from contracts and Capability Packs.
+
+**Step 3:** Reject unknown endpoints, self-relations where invalid, and contradictory dependency edges.
+
+**Step 4:** Run focused tests.
+
+### Task 6: Write the system paper
+
+**Files:**
+- Create: `paper/skillpack-one.md`
+- Create: `paper/skillpack-one.zh-CN.md`
+- Create: `paper/references.bib`
+- Modify: `README.md`
+- Modify: `README.zh-CN.md`
+
+**Step 1:** Write the methodology and architecture before the abstract.
+
+**Step 2:** Position the contribution against retrieval, composition, evolution, state, and security work.
+
+**Step 3:** Separate implemented deterministic evidence from proposed model-backed experiments.
+
+**Step 4:** Add limitations, threats to validity, and a reproducible evaluation protocol.
+
+**Step 5:** Link the paper artifacts from both READMEs.
+
+### Task 7: Validate the candidate
+
+**Files:**
+- Modify only files required by failures found above.
+
+**Step 1:** Run `npm run skills:check`.
+
+**Step 2:** Run `npm run typecheck`.
+
+**Step 3:** Run `npm test`.
+
+**Step 4:** Run `npm run build`.
+
+**Step 5:** Run `npm run skillpack -- gate` and verify existing protected metrics do not regress.
+
+**Step 6:** Review `git diff --check`, the candidate diff, provenance links, and rollback base.
+
+**Step 7:** Commit the candidate on `research/skill-lifecycle-evidence`; do not promote it to `main` without independent review.
+

package/docs/plans/2026-09-02-research-informed-skillpack-evolution.md

@@ -0,0 +1,46 @@
+# Research-informed SkillPack evolution design
+
+## Goal
+
+Apply convergent findings from Agent Skill research without changing SkillPack One's defining architecture: one install and governance entry point, progressive Category discovery, bounded Atomic Skills, declarative Capability Packs, and Meta Skill lifecycle control.
+
+## Preserved invariants
+
+- `SKILL.md` remains the portable executable discovery unit.
+- Category, Atom, and Meta remain the only Skill kinds.
+- Capability Packs compose stable IDs; they never absorb Atomic instructions.
+- Upstream catalog content stays non-executable until separately reviewed.
+- A candidate cannot change the protected evidence that certifies it.
+- Generated projections remain reproducible outputs of `skill-src/`.
+
+## Selected changes
+
+### 1. Constrained composition
+
+`compose <request>` reuses the existing two-stage router. It collects Atom and Meta scores, requires at least two members of a reviewed pack to cross a minimum relevance threshold, ranks matching packs, and compiles each declared partial order with a stable topological sort. The output contains selected IDs, count, missing members, execution stages, and acceptance tests. No arbitrary graph or new Skill is generated.
+
+### 2. Paired Skill effect
+
+`harness effect` consumes two task-result artifacts produced with the same dataset, example count, harness name, and harness version. It computes completion lift, rubric lift, blocked-rate change, and optional cost/latency change. A synthetic result can exercise the protocol but always fails certification. The initial admission gate requires non-regression plus a positive completion or rubric lift.
+
+### 3. Independent authorship review
+
+New proposals record authorship mode, responsible author, and—when applicable—the generating model. A human-only proposal requires a reviewer other than its author. A model-assisted or model-generated proposal rejects the generating model as reviewer. Historical append-only records are grandfathered and remain byte-stable.
+
+## Failure handling
+
+- Invalid or cyclic packs fail before a plan is returned.
+- Requests with fewer than two relevant members return no pack recommendation and leave the normal Atom route visible.
+- Mismatched task datasets, harnesses, or example counts fail effect certification.
+- Missing generator identity rejects new model-assisted/generated proposals.
+- Live evidence that is blocked remains blocked; Mock output is never promoted to a quality claim.
+
+## Verification
+
+- Unit tests cover DAG staging, request-to-pack recommendation, positive/uncertified effect comparison, schema validation, and reviewer separation.
+- Existing routing, projection, schema, catalog, plugin, harness, and governance tests must remain green.
+- The change follows the repository's own proposal → evaluate → independent promote workflow and retains a rollback revision.
+
+## Deferred work
+
+Learned retrieval, skill-aware iterative decomposition, automatic trace distillation, trust-tier enforcement, and model-weight training require larger protected datasets and live harness evidence. They are research lanes, not implicit promises in this change.

package/docs/plans/2026-09-02-self-organizing-skills-design.md

@@ -0,0 +1,307 @@
+# Self-Organizing Skill System: Architecture Design
+
+**Status:** Accepted design baseline  
+**Date:** 2026-09-02  
+**Primary language:** English, with a maintained Chinese companion document
+
+## 1. Vision
+
+Build an open, Codex-compatible system that turns a large and overlapping ecosystem of Agent Skills and MCP servers into a small set of composable atomic capabilities. The collection must organize itself, explain its classifications, evaluate routing and task completion separately, evolve through evidence, and roll back safely.
+
+The project is not another indiscriminate skill bundle. It is a skill operating system with five layers:
+
+1. **Category skills** narrow a request to a capability domain.
+2. **Atomic skills** perform one bounded capability under a declared contract.
+3. **Recipes/capability packs** compose atoms and MCP dependencies into useful workflows.
+4. **Meta skills** govern discovery, classification, change, evaluation, promotion, deprecation, and rollback.
+5. **The trainer** measures routing, compliance, completion, regression, safety, cost, and latency before any change is promoted.
+
+## 2. Requirements and non-goals
+
+### Required
+
+- Preserve native Codex Skill discovery through `.agents/skills/<skill-name>/SKILL.md`.
+- Package the same source as a Codex plugin through `.codex-plugin/plugin.json`.
+- Route in two conceptual stages: category, then atom.
+- Define category boundaries from real user outcomes rather than repository authors or tool brands.
+- Maintain an attributed catalog of at least 300 current Skills and MCP servers without blindly installing them.
+- Detect duplicates and extract reusable atomic capability candidates.
+- Support English-first ecosystem compatibility and Chinese localized references such as `index.zh-CN.md`; accept `*.zh.md` as a fallback alias.
+- Test with question sets and at least one real agent harness. Pi is the initial default; DSH and Codex use adapters.
+- Permit self-improvement only through bounded, reviewable proposals and held-out evaluation gates.
+
+### Non-goals for the first release
+
+- Training model weights.
+- Automatically executing or installing untrusted third-party code.
+- Claiming perfect taxonomy coverage.
+- Forcing Codex itself to implement a hard-coded two-pass router. Category skills provide progressive disclosure, while the trainer and registry enforce and evaluate the logical two-stage model.
+- Deleting historical versions. Deprecation and reversible archival are preferred.
+
+## 3. Alternatives considered
+
+### A. Physically nested category directories
+
+Place atoms inside category directories and depend on the agent to discover them recursively.
+
+**Benefit:** visually matches the category-then-atom idea.  
+**Problem:** Agent Skills discovery is convention-based and nested discovery is not reliably portable across Codex and other harnesses. Moving an atom between categories also changes its identity and import path.
+
+### B. Hybrid native projection plus registry — selected
+
+Keep every callable Skill as a direct child of `.agents/skills`. Category Skills are ordinary Skills whose localized indexes point to atomic capabilities. Machine-readable contracts and a registry implement two-stage routing, deduplication, evaluation, and composition.
+
+**Why selected:** native Codex compatibility, stable atom identities, plugin packaging, deterministic testing, and room for richer future routing without rewriting every Skill.
+
+### C. Database-only dynamic router
+
+Store all capabilities in a database and expose one universal router Skill.
+
+**Benefit:** flexible and easy to update.  
+**Problem:** weak progressive disclosure, a single routing bottleneck, reduced portability, and poor visibility in current Codex Skill UIs.
+
+## 4. Repository layout
+
+```text
+.codex-plugin/plugin.json           Codex plugin manifest
+skill-src/                           Canonical Skill templates and contracts
+skills/                              Generated plugin Skill projection
+.agents/skills/                      Generated native Codex project projection
+catalog/
+  sources.yaml                      Upstream source definitions
+  entries/                          Normalized Skill/MCP metadata
+  snapshots/                        Reproducible source snapshots
+taxonomy/
+  taxonomy.yaml                     Classification nodes and boundaries
+  classification-standard.md        Human-readable decision standard
+packs/                              Plugin-like recipes/capability packs
+evals/
+  datasets/                         Train/dev/test and adversarial question sets
+  baselines/                        Versioned expected scores
+src/                                Registry, router, trainer, adapters, CLI
+schemas/                            JSON Schemas for contracts and catalogs
+tests/                              Unit, integration, and golden tests
+docs/                               English documentation
+docs/zh-CN/                         Chinese documentation
+```
+
+The repository root is itself a plugin. Current plugin validation requires the plugin projection at `skills/`, while Codex project discovery uses `.agents/skills/`. A deterministic generator renders both from `skill-src/`; CI rejects projection drift. Contracts and templates are the single source of truth, while generated copies are compatibility artifacts. This is more portable than symlinks on Windows and honest about both discovery contracts.
+
+## 5. Capability model
+
+### 5.1 Stable identity
+
+Every capability receives a stable, lowercase, hyphenated ID. Moving between categories does not change the ID. Category membership is metadata, not ownership.
+
+### 5.2 Atomicity test
+
+A Skill is atomic when all answers below are singular and independently testable:
+
+- **Outcome:** one primary user-visible result.
+- **Artifact:** one dominant artifact or state transition.
+- **Authority:** one bounded permission/side-effect envelope.
+- **Evaluation:** one focused completion rubric.
+- **Failure boundary:** failure can be reported or retried without rerunning unrelated work.
+
+If a Skill contains several independently useful outcomes, it becomes a recipe or is split. If splitting creates meaningless fragments that always change together, it stays atomic.
+
+### 5.3 Contract fingerprint
+
+Each atom has a machine-readable `skill.contract.yaml` containing:
+
+- intent verbs and user outcomes;
+- inputs, outputs, preconditions, and failure modes;
+- artifacts and side effects;
+- tools/MCP dependencies and permissions;
+- domain, lifecycle stage, modality, risk, and locale metadata;
+- positive triggers, negative boundaries, and confusable capabilities;
+- provenance, license, version, and evaluation references.
+
+Deduplication compares contract fingerprints before comparing prose. Two Skills are duplicates only when outcome, artifact, authority, and evaluation boundaries substantially coincide. Shared keywords alone are not enough.
+
+## 6. Classification standard
+
+Classification is multi-axial, but routing has a single primary decision rule:
+
+1. **Primary axis: user outcome and artifact.** What durable result is requested?
+2. **Domain:** software, research, knowledge, data, media, business, operations, personal productivity, or system governance.
+3. **Lifecycle stage:** discover, plan, create, transform, analyze, verify, publish, operate, or govern.
+4. **Modality:** code, text, document, table, slide, image, audio, video, browser state, structured data, or physical-world proxy.
+5. **Dependency:** tool-agnostic, product-specific, MCP-backed, CLI-backed, or API-backed.
+6. **Risk:** read-only, reversible write, external communication, financial/legal/security-sensitive, destructive, or privileged.
+
+Category Skills describe inclusion rules, exclusions, border cases, and their atoms. An atom may appear in multiple category indexes but has one canonical contract.
+
+The initial top-level categories are deliberately broad and outcome-oriented:
+
+- software engineering;
+- research and knowledge;
+- data and analytics;
+- documents and communication;
+- design and media;
+- business and growth;
+- automation and operations;
+- personal productivity;
+- security and trust;
+- skill and agent governance.
+
+The taxonomy is versioned and may split or merge only when evaluation evidence shows persistent confusion or an overloaded category.
+
+## 7. Routing and progressive disclosure
+
+The logical flow is:
+
+```text
+request -> category candidates -> atom candidates -> recipe/dependencies -> execution
+               |                      |
+          category hit@k          atom hit@k/MRR
+                                      |
+                               completion/compliance
+```
+
+Native Codex may directly select an atom based on its description. That is valid execution but is still replayed through the logical classifier during evaluation. Category Skills exist to make broad requests discoverable and to disclose only the relevant atom index.
+
+The deterministic baseline router uses declared triggers, negative boundaries, taxonomy terms, and contract fields. Harness adapters can add model-based routing. Both produce the same trace schema so results are comparable.
+
+## 8. Category Skills
+
+A Category Skill is a first-class Skill, not a folder label. It contains:
+
+- a discriminating `SKILL.md` description;
+- `references/index.en.md` and `references/index.zh-CN.md`;
+- explicit inclusion/exclusion and boundary examples;
+- a generated atom table with stable IDs and concise capabilities;
+- instructions to read only the selected atom or recipe;
+- version and taxonomy-node metadata.
+
+Indexes are generated from contracts and checked for staleness in CI.
+
+## 9. Meta Skill governance
+
+`meta-skill-governor` may scan, learn, propose, evaluate, promote, deprecate, migrate, or roll back Skills—including itself—but it is not allowed to silently rewrite production Skills.
+
+Every evolution follows:
+
+```text
+observation -> bounded proposal -> sandbox build -> train/dev evaluation
+    -> held-out + adversarial gate -> human/policy approval -> canary -> promote
+    -> monitor -> retain or rollback
+```
+
+Rules:
+
+- Changes are patches with rationale and affected contracts.
+- Training examples may inform a change but never count as held-out proof.
+- Promotion requires no protected-metric regression and passes safety checks.
+- Self-modification uses the same gate and cannot weaken its own gate in the same proposal.
+- Deletion is represented as deprecation plus retention; physical removal is a separate explicit maintenance action.
+- All operations produce an append-only decision record.
+
+## 10. Plugin-oriented composition
+
+The project borrows four plugin ideas:
+
+- **Manifest:** explicit identity, version, entry points, dependencies, and compatibility.
+- **Isolation:** atom contracts declare tools, permissions, and side effects.
+- **Composition:** capability packs reference stable atom IDs rather than copying instructions.
+- **Lifecycle:** install, validate, enable, update, deprecate, roll back.
+
+A capability pack is a declarative recipe, not a new monolithic Skill. It specifies atoms, optional MCP dependencies, ordering constraints, handoff artifacts, locale, and acceptance tests. Frequently used packs may expose a thin orchestration Skill while retaining atoms as the source of truth.
+
+## 11. Catalog of 300+ upstream capabilities
+
+The catalog stores metadata and provenance by default, not third-party executable code. Collectors normalize:
+
+- repository and immutable revision;
+- item type (`skill`, `mcp-server`, `plugin`, `harness`);
+- upstream path and author;
+- summary, triggers, tools, permissions, and artifacts;
+- license and security review status;
+- freshness and last verification;
+- extracted contract fingerprint and duplicate cluster.
+
+The first milestone requires at least 300 unique normalized entries from current official, community, and research sources. CI rejects unattributed entries, mutable-only references, duplicate IDs, or missing licenses. Unknown licenses remain catalog-only and cannot be vendored.
+
+## 12. Evaluation and training
+
+Question sets are versioned and split by purpose:
+
+- `train`: visible cases used to improve descriptions and rules;
+- `dev`: frequent regression checks;
+- `test`: held-out release gate;
+- `adversarial`: ambiguous, multilingual, malicious, and negative-boundary cases;
+- `tasks`: executable task-completion scenarios.
+
+Metrics are intentionally separate:
+
+- category hit@1/hit@3;
+- atom hit@1/hit@3 and mean reciprocal rank;
+- correct non-invocation and ambiguity calibration;
+- procedural compliance;
+- task completion and artifact quality;
+- safety-policy adherence;
+- regression delta;
+- cost and latency.
+
+Default release gates are configurable. The bootstrap target is category hit@1 >= 0.90, atom hit@1 >= 0.80, completion >= 0.80, protected safety cases = 1.00, and no protected-suite regression. A release is not certified until it passes multiple independent datasets.
+
+The trainer optimizes declarative routing metadata and Skill wording through small candidate patches. It never treats a single aggregate score as sufficient and keeps every run reproducible.
+
+## 13. Harness architecture
+
+All harnesses implement one adapter contract:
+
+```ts
+interface HarnessAdapter {
+  discover(): Promise<HarnessCapabilities>;
+  route(example: RoutingExample): Promise<RouteTrace>;
+  execute(task: TaskExample): Promise<TaskTrace>;
+  healthcheck(): Promise<HealthReport>;
+}
+```
+
+- **Pi adapter:** first executable integration because the maintained Node package supports programmatic and structured modes on the current host.
+- **DSH adapter:** optional plugin-oriented backend; initial support targets its CLI/plugin interfaces once a stable release or pinned RC is selected.
+- **Codex adapter:** validates native discovery and can replay exported traces; automated use must not depend on private UI behavior.
+- **Mock adapter:** deterministic CI baseline with no API key.
+
+Harness identity and version are part of every evaluation record because harness behavior affects routing and compliance.
+
+## 14. Localization
+
+English remains the canonical `SKILL.md` routing surface for maximum ecosystem compatibility. Localized detail uses adjacent files:
+
+- `references/index.en.md`
+- `references/index.zh-CN.md`
+- optionally `references/index.zh.md` as a generic Chinese fallback
+
+The locale resolver follows exact locale, base language, English, then canonical default. Localizations may adapt phrasing and examples but may not change capability boundaries, safety rules, or permissions. CI compares contract references and required headings across locales.
+
+## 15. Security and trust
+
+- Cataloging is not installation.
+- Third-party instructions are untrusted data during ingestion.
+- Collectors do not execute repository scripts.
+- Network, filesystem, shell, secrets, and external messaging permissions are explicit contract fields.
+- Security checks look for prompt injection, hidden downloads, credential access, destructive commands, and authority escalation.
+- Provenance, license, checksum, and review status are visible before composition.
+- Meta evolution cannot expand permissions without an explicit review event.
+
+## 16. Error handling and recovery
+
+- Ambiguous routing returns ranked candidates and an explanation rather than inventing certainty.
+- Missing dependencies produce a typed blocked result with installation guidance.
+- Catalog fetch failures retain the last verified snapshot and report staleness.
+- Failed evolution candidates remain isolated and do not alter the active registry.
+- Every promoted registry and Skill revision has a rollback pointer.
+- Evaluation records distinguish infrastructure failure from capability failure.
+
+## 17. Delivery phases
+
+1. **Foundation:** schemas, taxonomy, registry, CLI, plugin manifest, initial category/meta/atom Skills.
+2. **Evidence:** 300+ attributed catalog entries, duplicate clusters, generated category indexes.
+3. **Evaluation:** bilingual routing sets, executable task suites, deterministic and Pi adapters.
+4. **Evolution:** bounded proposal/training loop, gates, decision log, rollback.
+5. **Ecosystem:** capability packs, DSH adapter, contribution workflow, public GitHub releases.
+
+This design deliberately separates a grand long-term vision from verifiable increments. Each phase must leave a usable, testable system.