@evo-dev/evodev 0.0.1-alpha.1 → 0.0.1-alpha.3

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

@@ -8,9 +8,9 @@ license: MIT
 
 ## Purpose
 
-Knowledge Distillation is an evidence curation pipeline. It turns reviewed execution evidence into atomic, reusable, role-tagged proposals that a user can inspect before anything becomes accepted knowledge or a project asset.
+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, or team launcher.
+It is not a trace summarizer, automatic memory writer, OKF file writer, or team launcher.
 
 ## Use This Skill When
 
@@ -25,6 +25,7 @@ It is not a trace summarizer, automatic memory writer, or team launcher.
 - 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
@@ -35,6 +36,8 @@ Work from one bounded evidence window. Prefer reviewed, minimized inputs:
 - 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.
@@ -58,161 +61,158 @@ Classify every input before extraction:
 
 ## Distillation Pipeline
 
-1. **Scope**: identify repo, task, role audience, evidence ids, and explicit project opt-in status.
+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 `roleTags`, `repoScope`, `domainTags`, `stability`, `sensitivity`, `reviewState`, and `targetStore`.
+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 proposal explains why eval coverage is not applicable.
+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**: propose a user-local knowledge/evos write, a repo-local asset suggestion, or no write.
-11. **Review plan**: list exact proposed paths, summaries, rollback notes, and why human review is required.
+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 a proposal. Use structured Markdown or JSON, but preserve these fields:
+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.",
-  "scope": {
-    "level": "user | project | workflow | skill",
-    "repo": "optional repository identifier",
-    "projectOptIn": false
-  },
-  "roleTags": ["reviewer"],
-  "executionAnalysis": {
-    "taskSlices": [
-      {
-        "id": "slice-1",
-        "goal": "Review skill output gap",
-        "ownerRole": "reviewer",
-        "dependencies": [],
-        "expectedEvidence": ["reviewed-finding"],
-        "stopCondition": "Skill gap and regression eval target are identified"
-      }
-    ],
-    "keyEvents": [
-      {
-        "id": "event-1",
-        "type": "tool-call | skill-invocation | subagent-lifecycle | verification | review-finding | route-decision",
-        "summary": "Knowledge skill proposed a behavior change without eval coverage.",
-        "evidenceRefs": ["review:skill-output-gap"],
-        "rawContentStored": false
-      }
-    ],
-    "qualityFindings": [
-      {
-        "category": "task-split-gap | tool-use-gap | skill-output-gap | subagent-routing-gap | verification-gap | privacy-gap",
-        "severity": "low | medium | high | critical",
-        "claim": "Skill proposal lacked regression eval cases for a skill change.",
-        "expectedBehavior": "Skill changes should include evoEvalSets.",
-        "roleTags": ["reviewer", "tester"]
-      }
-    ]
-  },
   "evidenceRefs": [
     {
-      "id": "verification:typecheck",
-      "class": "verified-run",
-      "storedRawContent": false
+      "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 | inferred",
+      "basis": "direct",
+      "metadataOnlyEvidence": true,
       "howToApply": "Add bun run check to the verification plan.",
       "antiCriteria": ["Do not mark completion from lint alone."],
       "roleTags": ["implementer", "reviewer"],
-      "repoScope": { "level": "project", "pathPrefixes": ["packages/cli/"] },
-      "stability": "stable | evolving | volatile",
-      "sensitivity": "public | local-private | restricted",
+      "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": 4,
+        "evidenceStrength": 5,
         "reuseValue": 4,
-        "actionability": 5,
+        "actionability": 4,
         "stability": 4,
-        "novelty": 2,
         "privacyRisk": 1,
         "duplicationRisk": 1
       },
-      "targetStore": "knowledge | evos | repo-asset-proposal | none",
-      "reviewState": "proposed"
+      "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
+      }
     }
   ],
-  "evoCases": [],
-  "skillImprovementSuggestions": [
+  "droppedSignals": [
     {
-      "skillId": "coding/knowledge-distillation",
-      "gapClass": "missing-eval-set | output-omission | inaccurate-claim | schema-drift | trigger-mismatch | privacy-defect",
-      "evidenceRefs": ["review:skill-output-gap"],
-      "observedBehavior": "A proposed skill change lacked regression eval coverage.",
-      "expectedBehavior": "Every skill behavior change includes at least one eval case or an explicit not-applicable reason.",
-      "changeSummary": "Extend the skill output contract with evoEvalSets.",
-      "targetPaths": ["packages/core/assets/skills/coding/knowledge-distillation/SKILL.md"],
-      "acceptanceCriteria": ["Output includes an eval set for each skill behavior change."],
-      "reviewState": "proposed"
-    }
-  ],
-  "evoEvalSets": [
-    {
-      "id": "eval-knowledge-distillation-skill-change-needs-evals",
-      "target": { "kind": "skill", "id": "coding/knowledge-distillation" },
-      "purpose": "Prevent skill-change proposals without regression evals.",
-      "roleTags": ["reviewer", "tester"],
-      "cases": [
-        {
-          "id": "case-skill-output-gap",
-          "inputRefs": ["fixture:reviewed-skill-gap"],
-          "assertions": [
-            "skillImprovementSuggestions[0].skillId is present",
-            "evoEvalSets contains at least one case for the skill change",
-            "privacyCheck.rawPromptsStored == false",
-            "privacyCheck.sourceDumpsStored == false",
-            "privacyCheck.rawCommandOutputStored == false"
-          ],
-          "expectedReviewState": "proposed"
-        }
-      ],
-      "privacy": {
-        "usesRawPrompt": false,
-        "usesSourceDump": false,
-        "usesRawCommandOutput": false
-      },
-      "reviewState": "proposed"
+      "evidenceRef": "event-17",
+      "reason": "Routine tool-call metadata with no reusable lesson."
     }
   ],
-  "repoAssetSuggestions": [],
-  "teamSuggestions": [],
+  "conflicts": [],
   "privacyCheck": {
     "rawPromptsStored": false,
     "rawLogsStored": false,
     "sourceDumpsStored": false,
     "rawCommandOutputStored": false,
     "secretsStored": false,
-    "internalLinksStored": false,
-    "deferredCandidates": []
+    "internalLinksStored": false
   }
 }
 ```
 
-Scoring uses 1-5 integers. A candidate should not be proposed for accepted knowledge unless evidence strength, reuse value, and actionability are high enough to justify future retrieval and privacy risk is low.
+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 review-only.
+Default output is a transient plan only.
 
-- `knowledge`: stable accepted facts, decisions, constraints, concepts, and reusable rules after review.
-- `evos`: reviewed process improvement cases with trigger, intervention, evidence, and expected future behavior.
-- `evo-eval-set`: proposed or accepted regression cases for skill, role-agent, team, workflow, routing, tool-use, or subagent behavior.
-- `repo-asset-proposal`: suggested repo rules, skills, role agents, subagents, or teams. Requires explicit project opt-in before any write.
+- `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 require an explicit opt-in step that lists exact paths, content summaries, rollback notes, and privacy checks before any file write.
+Project-local writes remain out of scope for this skill.
 
 ## Role Tags
 
@@ -228,21 +228,22 @@ Every durable candidate must include at least one role tag. Prefer stable role s
 
 Use user-defined role slugs only when a reviewed role-agent definition exists. Treat role tags as retrieval/routing filters, not decorative labels.
 
-## Review Triggers
+## Human Intervention Triggers
 
-Require explicit review before persistence when a candidate:
+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 future runtime retrieval.
+- 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
 
-Accepted role-tagged knowledge may later help a selected role focus on relevant rules, decisions, cases, or warnings. Runtime loading remains gated by role selection, repo scope, privacy policy, and consent. Pending, rejected, or deferred candidates must not influence routing or runtime behavior.
+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 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.

package/dist/plugins/evodev/skills/knowledge-distillation/references/knowledge-distillation-methods.md

@@ -8,7 +8,7 @@ This reference explains why the skill uses an evidence curation pipeline instead
 |---|---|---|
 | Postmortem / SRE review | Blameless failure analysis, root cause, impact, action items | Use for failure-derived `warning`, `anti-pattern`, `checklist`, and `workflow-improvement` candidates |
 | After Action Review | Expected vs actual, what went well, what failed, what changes next time | Use for evos cases and team/process improvement candidates |
-| Lessons learned systems | Reviewed lessons from projects/programs, not raw incident notes | Keep accepted knowledge separate from raw evidence and candidates |
+| Lessons learned systems | Reviewed lessons from projects/programs, not raw incident notes | Keep active OKF knowledge separate from raw evidence and transient plans |
 | ADR / decision logs | One durable decision with context, alternatives, rationale, consequences | Use `decision` candidates for architecture/workflow choices |
 | SKOS-style knowledge organization | Concepts, labels, narrower/broader/related terms, scope notes | Keep role tags and domain tags controlled enough for retrieval |
 | Agent memory research | Semantic facts, episodic cases, procedural improvements | Split knowledge, evos cases, and repo asset suggestions instead of one memory bucket |
@@ -23,7 +23,7 @@ Prefer evidence in this order:
 2. Reviewed findings: code review, security review, user correction, or postmortem conclusion.
 3. Official or upstream references: standards, vendor docs, framework docs, release notes, or source repositories.
 4. Existing repository contracts: `AGENTS.md`, design docs, task contracts, tests, schemas, and explicit policy files.
-5. Model reflection: useful for candidate generation only; never enough for accepted knowledge.
+5. Model reflection: useful for candidate generation only; never enough for active OKF knowledge.
 
 ## Candidate Types
 
@@ -54,17 +54,22 @@ Use 1-5 integers. Keep the score approximate; it is a review aid, not a scientif
 | `reuseValue` | Likely useful across future similar tasks | One-off or too narrow |
 | `actionability` | Clear trigger and next action | Vague or only descriptive |
 | `stability` | Likely to remain true for the repo/workflow | Depends on volatile context |
-| `novelty` | Adds knowledge not already captured | Duplicates existing guidance |
 | `privacyRisk` | Higher is worse: needs sensitive context | Redacted summary is enough |
 | `duplicationRisk` | Higher is worse: likely duplicate | Distinct from existing entries |
 
 Suggested write queue rule:
 
-- Propose accepted knowledge only when `evidenceStrength >= 4`, `reuseValue >= 3`, `actionability >= 3`, `privacyRisk <= 2`, and `duplicationRisk <= 3`.
+- Propose active OKF knowledge only when `evidenceStrength >= 4`, `reuseValue >= 3`, `actionability >= 3`, `privacyRisk <= 2`, and `duplicationRisk <= 3`.
 - Propose evos cases when the item is mainly about a trigger/intervention/outcome history.
 - Propose repo assets only when repeated future execution would benefit from a rule, skill, role, or team and explicit project opt-in can be obtained.
 - Propose evo eval sets whenever a skill, role-agent, team, workflow, routing, tool-use, or subagent behavior change is proposed. If no eval is useful, state why in the proposal.
 
+## Executable Contract Notes
+
+The runtime accepts only JSON outputs with `kind: "knowledge-distillation-output"` and `schemaVersion: 1`. Candidate decisions are `auto-accept`, `create`, `update`, `needs-human`, `skip`, and canonical `no_write`. Active writes must be metadata-only, evidence-backed, review-state gated, verified, and targeted at safe relative `.md` OKF paths. Behavior-changing active writes must include `evalSetRefs` that point to provided `evoEvalSets`.
+
+Contract validation runs before OKF writes. Validation failures are saved as redacted, non-resumable failed-plan artifacts; organizer failures preserve a resumable plan. Failed artifacts are organizer inputs only and must not influence runtime retrieval.
+
 ## Evolution Event Analysis
 
 Use reviewed event evidence to explain why the future behavior should change.
@@ -102,13 +107,12 @@ Common skill defects:
 
 | Candidate target | Canonical layer | Notes |
 |---|---|---|
-| `knowledge` | Accepted knowledge | Human-reviewable Markdown/JSON with provenance |
-| `evos` | Evolution cases | Case history with trigger, intervention, evidence, result |
+| `okf` | Active knowledge | OKF Markdown concepts with frontmatter, provenance, links, directory indexes, and logs |
 | `evo-eval-set` | Evolution eval sets | Regression cases tied to proposed or accepted behavior changes |
 | `repo-asset-proposal` | Proposal queue first | Never write project files by default |
 | `none` | Report only | Useful but not durable |
 
-Indexes, vector search, graph exports, and runtime caches are derived views. They must be rebuildable from accepted canonical records and must not store raw private content.
+Indexes, vector search, graph exports, and runtime caches are derived views. They must be rebuildable from active OKF concepts and must not store raw private content. Transient knowledge plans are organizer inputs, not accepted knowledge.
 
 ## Source Notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evo-dev/evodev",
-  "version": "0.0.1-alpha.1",
+  "version": "0.0.1-alpha.3",
   "description": "AI Coding infrastructure CLI for real R&D workflows.",
   "type": "module",
   "repository": {