@evo-dev/evodev 0.0.1-alpha → 0.0.1-alpha.2

package/dist/plugins/evodev/hooks/transform-agent.ts

@@ -10,6 +10,16 @@ export interface ClaudeAgentTransformResult {
   content: string;
 }
 
+export interface CodexAgentTransformInput {
+  asset: ScannedAsset<AgentManifest>;
+  source: string;
+}
+
+export interface CodexAgentTransformResult {
+  name: string;
+  content: string;
+}
+
 export function transformClaudeAgent(input: ClaudeAgentTransformInput): ClaudeAgentTransformResult {
   const { manifest } = input.asset;
   const frontmatter = [
@@ -25,6 +35,26 @@ export function transformClaudeAgent(input: ClaudeAgentTransformInput): ClaudeAg
   };
 }
 
+export function transformCodexAgent(input: CodexAgentTransformInput): CodexAgentTransformResult {
+  const { manifest } = input.asset;
+  const lines = [
+    `# Generated by EvoDev from ${input.asset.registryKey}`,
+    `name = ${tomlString(manifest.id)}`,
+    `description = ${tomlString(manifest.description)}`,
+    `developer_instructions = ${tomlString(input.source)}`,
+    "",
+  ];
+
+  return {
+    name: manifest.id,
+    content: lines.join("\n"),
+  };
+}
+
 function escapeFrontmatterValue(value: string): string {
   return value.replaceAll("\n", " ");
 }
+
+function tomlString(value: string): string {
+  return JSON.stringify(value);
+}

package/dist/plugins/evodev/hooks/workspace-core.ts

@@ -0,0 +1,154 @@
+import type { Dirent } from "node:fs";
+import { cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export interface WorkspaceCoreHydrationResult {
+  warnings: string[];
+  errors: string[];
+}
+
+export async function hydrateWorkspaceCoreDependency(input: {
+  sourceCoreRoot: string;
+  cachePluginRoot: string;
+  runtimeLabel: string;
+}): Promise<WorkspaceCoreHydrationResult> {
+  const warnings: string[] = [];
+  const errors: string[] = [];
+
+  const installedPluginRoot = await findInstalledPluginRoot(input.cachePluginRoot);
+  if (installedPluginRoot === null) {
+    warnings.push(
+      `Skipped @evo-dev/core hydration because the ${input.runtimeLabel} plugin cache was not found: ${input.cachePluginRoot}`,
+    );
+    return { warnings, errors };
+  }
+
+  if (!(await isDirectory(input.sourceCoreRoot))) {
+    errors.push(
+      `Cannot hydrate @evo-dev/core for ${input.runtimeLabel} plugin runtime: marketplace core package not found at ${input.sourceCoreRoot}`,
+    );
+    return { warnings, errors };
+  }
+
+  try {
+    await writeRuntimeCorePackage({
+      sourceCoreRoot: input.sourceCoreRoot,
+      targetCoreRoot: `${installedPluginRoot}/node_modules/@evo-dev/core`,
+    });
+  } catch (error) {
+    errors.push(
+      `Cannot hydrate @evo-dev/core for ${input.runtimeLabel} plugin runtime: ${describeError(error)}`,
+    );
+  }
+
+  return { warnings, errors };
+}
+
+export function isSafePluginCacheSegment(segment: string): boolean {
+  return /^[A-Za-z0-9._-]+$/.test(segment) && segment !== "." && segment !== "..";
+}
+
+async function findInstalledPluginRoot(cachePluginRoot: string): Promise<string | null> {
+  let entries: Dirent[];
+  try {
+    entries = await readdir(cachePluginRoot, { withFileTypes: true });
+  } catch (error) {
+    if (isNotFoundError(error)) {
+      return null;
+    }
+    throw error;
+  }
+
+  const versionDirs = await Promise.all(
+    entries
+      .filter((entry) => entry.isDirectory())
+      .map(async (entry) => {
+        const path = `${cachePluginRoot}/${entry.name}`;
+        const pathStat = await stat(path);
+        return { path, mtimeMs: pathStat.mtimeMs };
+      }),
+  );
+  if (versionDirs.length === 0) {
+    return null;
+  }
+
+  versionDirs.sort(
+    (left, right) => right.mtimeMs - left.mtimeMs || right.path.localeCompare(left.path),
+  );
+  return versionDirs[0].path;
+}
+
+async function writeRuntimeCorePackage(input: {
+  sourceCoreRoot: string;
+  targetCoreRoot: string;
+}): Promise<void> {
+  const sourcePackagePath = `${input.sourceCoreRoot}/package.json`;
+  if (!(await isFile(sourcePackagePath))) {
+    throw new Error(`source package.json not found at ${sourcePackagePath}`);
+  }
+  if (!(await isDirectory(`${input.sourceCoreRoot}/src`))) {
+    throw new Error(`source src directory not found at ${input.sourceCoreRoot}/src`);
+  }
+
+  await rm(input.targetCoreRoot, { recursive: true, force: true });
+  await mkdir(dirname(input.targetCoreRoot), { recursive: true });
+  await mkdir(input.targetCoreRoot, { recursive: true });
+  await cp(`${input.sourceCoreRoot}/src`, `${input.targetCoreRoot}/src`, {
+    recursive: true,
+  });
+  if (await isDirectory(`${input.sourceCoreRoot}/assets`)) {
+    await cp(`${input.sourceCoreRoot}/assets`, `${input.targetCoreRoot}/assets`, {
+      recursive: true,
+    });
+  }
+
+  const sourcePackageJson = JSON.parse(await readFile(sourcePackagePath, "utf8")) as Record<
+    string,
+    unknown
+  >;
+  const runtimePackageJson = {
+    ...sourcePackageJson,
+    files: ["src", "assets", "package.json"],
+  };
+  await writeFile(
+    `${input.targetCoreRoot}/package.json`,
+    `${JSON.stringify(runtimePackageJson, null, 2)}\n`,
+    "utf8",
+  );
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch (error) {
+    if (isNotFoundError(error)) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+async function isFile(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile();
+  } catch (error) {
+    if (isNotFoundError(error)) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return (
+    error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT"
+  );
+}
+
+function describeError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}

package/dist/plugins/evodev/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@evo-dev/plugin",
-  "version": "0.0.1-alpha",
+  "version": "0.0.1-alpha.2",
   "type": "module",
   "exports": {
     ".": "./hooks/index.ts"
   },
   "dependencies": {
-    "@evo-dev/core": "0.0.1-alpha"
+    "@evo-dev/core": "workspace:*"
   },
   "engines": {
     "bun": ">=1.1.0"
   },
-  "files": ["hooks", ".claude-plugin", ".codex-plugin", "hooks", "package.json"],
+  "files": ["hooks", ".claude-plugin", ".codex-plugin", ".mcp.json", "skills", "package.json"],
   "license": "MIT"
 }

package/dist/plugins/evodev/skills/engineering-discipline/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: engineering-discipline
+description: Use when implementing, reviewing, or refactoring code to clarify assumptions, avoid overengineering, keep diffs focused, protect scope boundaries, and verify results.
+license: MIT
+---
+
+# Engineering Discipline
+
+## Purpose
+
+Engineering Discipline is a practical guardrail for AI-assisted development. It keeps each coding session anchored to the requested outcome, makes assumptions visible, and requires verification before reporting success.
+
+## Use this skill when
+
+- Implementing a feature, bug fix, refactor, or test change.
+- Reviewing code for correctness, safety, or maintainability.
+- Working under explicit MVP, privacy, release, or project-boundary constraints.
+- A task could expand into speculative architecture or unrelated cleanup.
+
+## Do not use this skill for
+
+- Pure brainstorming where no code or plan will be produced.
+- Tasks where the user explicitly asks for unconstrained exploration.
+- Replacing product, security, or legal review when those are required.
+
+## Core principles
+
+### 1. Assumption management
+
+State meaningful assumptions before acting. If an assumption changes the user-visible behavior, data boundary, or implementation scope, pause and ask instead of silently guessing.
+
+### 2. Simplicity control
+
+Prefer the smallest design that satisfies the current acceptance criteria. Avoid framework additions, broad abstractions, and future-facing features unless they are required now.
+
+### 3. Diff discipline
+
+Every modified file should have a clear reason tied to the task. Avoid drive-by formatting, unrelated refactors, and opportunistic rewrites.
+
+### 4. Verification loop
+
+Attach each important change to a verification method: test, typecheck, lint, dry-run, manual command, or explicit reason it cannot be run. Do not claim a gate passed unless it was actually executed.
+
+### 5. Scope boundary
+
+Respect project and privacy boundaries. Do not modify user project assets, user-level Code Agent configuration, secrets, logs, or learning data unless the task explicitly requires it and the relevant safeguards exist.
+
+## Operating steps
+
+1. Restate the goal and identify the current task, todo item, or acceptance criteria.
+2. Check the nearest source of truth: existing code, tests, implementation notes, or task instructions.
+3. List assumptions and ask when a choice is materially ambiguous.
+4. Make the smallest focused change that satisfies the goal.
+5. Verify with the most relevant local gate.
+6. Report what changed, what was tested, what failed or was skipped, and any remaining risk.
+
+## Output checklist
+
+- Goal remains unchanged from the request.
+- Modified files are directly related to the goal.
+- New behavior has a validation path.
+- User or project boundaries were not crossed.
+- Final report distinguishes PASS, FAIL, and not-run checks.

package/dist/plugins/evodev/skills/engineering-discipline/anti-patterns.md

@@ -0,0 +1,21 @@
+# Engineering Discipline Anti-Patterns
+
+## Scope creep
+
+Adding sync, plugin, workflow, or learning behavior while a task only asks for canonical assets.
+
+## Silent assumptions
+
+Choosing a destructive write path, external dependency, or user-data behavior without explaining the assumption or asking for confirmation.
+
+## Diff pollution
+
+Formatting unrelated files, renaming public APIs, or refactoring neighboring modules because they were nearby.
+
+## Verification theater
+
+Reporting success without running the relevant gate, or hiding a failed check behind vague wording.
+
+## Boundary violations
+
+Writing to project-level `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.codex/`, or user private data unless the user explicitly requested it and the current task permits it.

package/dist/plugins/evodev/skills/engineering-discipline/examples.md

@@ -0,0 +1,19 @@
+# Engineering Discipline Examples
+
+## Focused implementation
+
+**Situation:** The task asks for a scanner-valid built-in asset.
+
+**Disciplined response:** Add only the asset directory, manifest, entry file, and concise support files. Validate with the asset scanner or project check. Do not implement plugin sync or CLI behavior in the same task.
+
+## Assumption handling
+
+**Situation:** Two output formats are possible and both affect users.
+
+**Disciplined response:** Explain the options and ask for direction, or choose the option already specified by the current source of truth.
+
+## Verification report
+
+**Good report:** `bun run check` was run and passed. Asset manifests scan with registry keys `coding/engineering-discipline` and `review/code-reviewer`.
+
+**Bad report:** “Looks good” without saying what was run or whether any gate failed.

package/dist/plugins/evodev/skills/engineering-discipline/verification.md

@@ -0,0 +1,11 @@
+# Engineering Discipline Verification
+
+Use this quick gate before reporting completion:
+
+1. **Scope:** Does every change map to the current request, todo item, or acceptance criteria?
+2. **Safety:** Did the work avoid project assets, secrets, private logs, and user configuration unless explicitly allowed?
+3. **Simplicity:** Is there any new abstraction, dependency, or feature not needed for the current goal?
+4. **Evidence:** Was the most relevant test, typecheck, lint, scanner, or dry-run executed?
+5. **Report:** Are failures and skipped checks stated plainly?
+
+If any answer is no, fix the issue or report the remaining risk instead of claiming the gate passed.

package/dist/plugins/evodev/skills/knowledge-distillation/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: knowledge-distillation
+description: Use when turning reviewed execution evidence into atomic, privacy-filtered, role-tagged engineering knowledge candidates, evos cases, repo asset proposals, or role-agent/team suggestions.
+license: MIT
+---
+
+# Knowledge Distillation / 提炼
+
+## Purpose
+
+Knowledge Distillation is an evidence curation pipeline. It turns reviewed execution evidence into an OKF-aware transient knowledge plan. The organizer, not this skill, writes final OKF Markdown files after dedupe, conflict handling, tagging, link updates, index generation, and logging.
+
+It is not a trace summarizer, automatic memory writer, OKF file writer, or team launcher.
+
+## Use This Skill When
+
+- A completed task produced a repeatable repository-specific lesson.
+- A review, failure, postmortem, or user correction should become a rule, warning, checklist item, decision, pattern, or evos case.
+- Execution evidence suggests a repo-local skill, rule, role agent, subagent, or EvoHub team.
+- Reviewed execution evidence shows a task split, tool call, skill output, or subagent handoff was incomplete, inaccurate, inefficient, or unsafe.
+- Role-specific knowledge should later be available to a role agent, subject to explicit consent and runtime scope.
+
+## Do Not Use This Skill For
+
+- Writing `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.codex/`, `.evodev/`, source files, or project assets without explicit project opt-in.
+- Storing raw prompts, transcripts, source dumps, raw command output, secrets, tokens, internal links, or private URLs.
+- Treating unreviewed observations, model reflection, or trace logs as accepted memory.
+- Writing final OKF concept documents directly; output a transient plan for the organizer.
+- Starting subagents or teams automatically.
+
+## Inputs
+
+Work from one bounded evidence window. Prefer reviewed, minimized inputs:
+
+- Task goal, final outcome, and repository scope.
+- Verification evidence, failures, fixes, and review findings.
+- Accepted corrections or explicit user feedback.
+- Relevant external authority, when the lesson depends on a standard, official documentation, or upstream behavior.
+- Relevant OKF v0.1 constraints: concept documents need YAML frontmatter with non-empty `type`; `index.md` and `log.md` are reserved at every directory level; bundle-relative absolute Markdown links are preferred for durable relationships.
+- Existing OKF index snippets or concept summaries, when available, so duplicate and conflict risk can be scored before proposing new candidates.
+- Candidate roles that should care, such as `architect`, `implementer`, `reviewer`, `tester`, `security`, `release`, `docs`, or user-defined role slugs.
+
+Do not ingest raw traces wholesale. If trace evidence is needed, use a redacted summary and evidence references.
+
+## Evidence Policy
+
+Classify every input before extraction:
+
+| Evidence class | Use | Constraint |
+|---|---|---|
+| `verified-run` | Test/build/lint/check outcomes and accepted fixes | Store references and summaries, not raw output |
+| `reviewed-finding` | Code review, security review, or user correction | Keep finding, impact, and accepted action separate |
+| `decision-record` | Architecture or workflow decision | Preserve context, decision, alternatives, consequences |
+| `postmortem-case` | Failure, incident, or after-action review | Preserve expected vs actual, cause, action item |
+| `official-reference` | Standards, docs, upstream behavior | Include URL/version/date; do not overquote |
+| `model-reflection` | Agent-generated synthesis | Candidate only; never accepted without review |
+| `tool-call-summary` | Tool selection, risk class, status, and recovery | No raw command or raw stdout/stderr by default |
+| `skill-invocation` | Skill id/version, input class, output schema, and reviewed result | Record omissions or inaccuracies as findings; do not store raw prompts/source |
+| `subagent-lifecycle` | Role, reason, scope, status, output refs, and merge result | No raw transcript |
+| `evo-eval-result` | Eval case pass/fail and assertion summary | Store fixture refs and assertion results, not private raw data |
+
+## Distillation Pipeline
+
+1. **Scope**: identify repo, task, role audience, workflow audience, path scope, evidence ids, and user-local OKF target scope.
+2. **Minimize**: remove raw prompts, raw logs, source dumps, secrets, personal data, internal links, and one-off noise.
+3. **Analyze execution structure**: when event evidence is present, identify task slices, owner roles, dependencies, key tool calls, skill invocations, subagent lifecycle events, verification gates, and merge outcomes.
+4. **Extract atomic candidates**: one claim per candidate. Allowed `kind` values are `rule`, `decision`, `pattern`, `anti-pattern`, `warning`, `checklist`, `concept`, `workflow-improvement`, `task-split-improvement`, `tool-use-improvement`, `skill-improvement`, `repo-asset-suggestion`, `role-agent-suggestion`, `team-suggestion`, `eval-set`, and `open-question`.
+5. **Separate fact from inference**: mark whether the candidate is directly evidenced or inferred from evidence.
+6. **Classify**: add `okfType`, `targetPath`, `stableKey`, `roleTags`, `repoTags`, `workflowTags`, `pathScopes`, `domainTags`, `stability`, `sensitivity`, and `targetStore`.
+7. **Score**: estimate evidence strength, reuse value, actionability, stability, novelty, privacy risk, and duplication risk.
+8. **Pair improvements with evals**: every proposed skill, role-agent, team, workflow, routing, tool-use, or subagent behavior change should include an `evoEvalSets` entry, unless the plan explains why eval coverage is not applicable.
+9. **Privacy gate**: defer candidates that require raw private content to remain meaningful.
+10. **Route**: emit `no_write`, `create`, `update`, `skip`, or `needs-human` for each candidate.
+11. **Plan OKF organization**: provide canonical concept targets and repo/role/workflow overlay updates. Do not emit final OKF files.
+12. **Recovery notes**: explain conflicts, stale information, required repo fact checks, and why human intervention is needed when applicable.
+
+## Output Schema
+
+Return executable JSON with `schemaVersion: 1` and `kind: "knowledge-distillation-output"`. The runtime parser converts this output into an OKF plan and validates the full contract before any OKF directory or concept write occurs. Invalid outputs become validation failed-plan artifacts; those artifacts are redacted, non-resumable, and inspectable with `evo plan show`.
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "knowledge-distillation-output",
+  "projectKey": "evodev",
+  "runId": "run-123",
+  "createdAt": "2026-06-24T00:00:00.000Z",
+  "evidenceWindowId": "evidence-run-123",
+  "summary": "What reusable improvement was found.",
+  "evidenceRefs": [
+    {
+      "id": "source-1",
+      "kind": "verification",
+      "source": "state/evidence/metadata.json",
+      "rawContentStored": false,
+      "externalContentCopied": false
+    }
+  ],
+  "evoEvalSets": [
+    {
+      "id": "eval-role-routing-1",
+      "target": { "kind": "role-agent-suggestion", "id": "candidate-1" },
+      "purpose": "Guard a behavior-changing active write.",
+      "roleTags": ["reviewer"],
+      "cases": [
+        {
+          "id": "case-1",
+          "inputRefs": ["source-1"],
+          "assertions": ["Candidate remains metadata-only and review-state gated."],
+          "expectedReviewState": "auto-accepted"
+        }
+      ],
+      "privacy": {
+        "usesRawPrompt": false,
+        "usesSourceDump": false,
+        "usesRawCommandOutput": false
+      },
+      "decision": "create"
+    }
+  ],
+  "knowledgeCandidates": [
+    {
+      "id": "candidate-1",
+      "decision": "auto-accept",
+      "kind": "rule",
+      "okfType": "EvoDev Rule",
+      "targetStore": "okf",
+      "targetPath": "concepts/rules/workspace-check.md",
+      "stableKey": "rule:verification:workspace-check",
+      "confidence": "high",
+      "title": "Workspace check before completion",
+      "description": "Run the workspace check before reporting TypeScript CLI completion.",
+      "claim": "For TypeScript CLI changes, run the workspace check before reporting completion.",
+      "basis": "direct",
+      "metadataOnlyEvidence": true,
+      "howToApply": "Add bun run check to the verification plan.",
+      "antiCriteria": ["Do not mark completion from lint alone."],
+      "roleTags": ["implementer", "reviewer"],
+      "repoTags": ["evodev"],
+      "workflowTags": ["feature-implementation"],
+      "pathScopes": ["packages/cli/", "packages/core/"],
+      "relatedConceptLinks": ["/concepts/verification/workspace-quality-gate.md"],
+      "overlayUpdates": [
+        {
+          "targetPath": "roles/reviewer/verification.md",
+          "operation": "append-link",
+          "link": "/concepts/rules/workspace-check.md"
+        }
+      ],
+      "scores": {
+        "evidenceStrength": 5,
+        "reuseValue": 4,
+        "actionability": 4,
+        "stability": 4,
+        "privacyRisk": 1,
+        "duplicationRisk": 1
+      },
+      "decisionReason": "Auto-accepted from verified metadata-only evidence.",
+      "evidenceRefs": ["source-1"],
+      "reviewState": "auto-accepted",
+      "evalSetRefs": [],
+      "bodySections": {
+        "summary": "Run the workspace check before reporting completion.",
+        "appliesWhen": ["TypeScript CLI or core changes were made."],
+        "guidance": ["Run bun run check and report the result."],
+        "antiCriteria": ["Do not store raw command output."],
+        "verification": ["Workspace check passed with metadata-only evidence."],
+        "citations": []
+      },
+      "privacyCheck": {
+        "rawPromptsStored": false,
+        "rawLogsStored": false,
+        "sourceDumpsStored": false,
+        "rawCommandOutputStored": false,
+        "secretsStored": false,
+        "internalLinksStored": false
+      }
+    }
+  ],
+  "droppedSignals": [
+    {
+      "evidenceRef": "event-17",
+      "reason": "Routine tool-call metadata with no reusable lesson."
+    }
+  ],
+  "conflicts": [],
+  "privacyCheck": {
+    "rawPromptsStored": false,
+    "rawLogsStored": false,
+    "sourceDumpsStored": false,
+    "rawCommandOutputStored": false,
+    "secretsStored": false,
+    "internalLinksStored": false
+  }
+}
+```
+
+Required candidate fields are `id`, `decision`, `kind`, `okfType`, `targetStore`, `targetPath`, `stableKey`, `confidence`, `title`, `description`, `claim`, `basis`, `metadataOnlyEvidence`, `howToApply`, `antiCriteria`, `roleTags`, `repoTags`, `workflowTags`, `pathScopes`, `relatedConceptLinks`, `overlayUpdates`, `scores`, `decisionReason`, `evidenceRefs`, `reviewState`, `bodySections`, and `privacyCheck`.
+
+Valid decisions are `auto-accept`, `create`, `update`, `needs-human`, `skip`, and canonical `no_write`. `no-write` may be normalized by the runtime but new output should emit `no_write`. Active writes (`auto-accept`, `create`, `update`) must target `okf`, use reviewState `auto-accepted` or `accepted`, use metadata-only evidence, include evidence refs, have a safe relative `.md` target path outside reserved `index.md` and `log.md`, and include verification or `verificationNotApplicableReason`.
+
+Behavior-changing active writes, including skill, role-agent, team, workflow, routing, tool-use, task-split, and subagent changes, must include `evalSetRefs` that point to provided `evoEvalSets`. Eval sets must be metadata-only and use privacy flags `usesRawPrompt: false`, `usesSourceDump: false`, and `usesRawCommandOutput: false`.
+
+Scoring uses 1-5 integers for `evidenceStrength`, `reuseValue`, `actionability`, `stability`, `privacyRisk`, and `duplicationRisk`. A candidate should not target `okf` unless evidence strength, reuse value, and actionability justify future retrieval and privacy risk is low. `no_write` is a normal result and should be common.
+
+## Write Targets
+
+Default output is a transient plan only.
+
+- `okf`: stable facts, decisions, constraints, concepts, evos cases, and reusable rules that the organizer may write into user-local OKF.
+- `evo-eval-set`: regression cases tied to proposed or accepted behavior changes.
+- `repo-asset-proposal`: suggested repo rules, skills, role agents, subagents, or teams. Requires explicit project opt-in before any repository write.
+- `none`: useful observation that should stay in the report and not become durable knowledge.
+
+Project-local writes remain out of scope for this skill.
+
+## Role Tags
+
+Every durable candidate must include at least one role tag. Prefer stable role slugs:
+
+- `architect`
+- `implementer`
+- `reviewer`
+- `tester`
+- `security`
+- `release`
+- `docs`
+
+Use user-defined role slugs only when a reviewed role-agent definition exists. Treat role tags as retrieval/routing filters, not decorative labels.
+
+## Human Intervention Triggers
+
+Mark a candidate as `needs-human` when it:
+
+- Affects security, privacy, release, architecture, or cross-repo behavior.
+- Suggests a project-local file write.
+- Suggests changing a skill, role agent, team, workflow, routing rule, tool-use policy, or subagent behavior without an associated `evoEvalSets` entry or explicit not-applicable reason.
+- Has low evidence strength, high privacy risk, or ambiguous repo scope.
+- Would change role-agent behavior, EvoHub team composition, or runtime retrieval behavior.
+- Conflicts with existing OKF guidance in a way the organizer cannot resolve from current repo facts.
+- Is derived primarily from model reflection rather than verified evidence.
+
+## Runtime Attention Boundary
+
+Only active OKF concepts under `~/.evodev/knowledge/okf` may influence retrieval. Runtime loading remains gated by role selection, repo scope, workflow scope, path scope, privacy policy, and consent. Transient plans, failed plans, repo proposals, and `no_write` observations must not influence routing or runtime behavior.
+
+## References
+
+For method comparisons and design rationale, read `references/knowledge-distillation-methods.md` in this skill directory. For OKF structure, reserved filenames, concept frontmatter, links, indexes, logs, and conformance rules, follow the Open Knowledge Format v0.1 spec: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md.