♻️ Unify project lessons into self-evolving project skills

Lessons become skills with a category (workflow / pitfall / convention):
one model, one prompt section, one permission rule. A repaired failure
records or updates a pitfall skill deduplicated by failure signature;
harvest sees every skill and may merge into an existing one; corroborated
skills auto-activate per project (skillAutoActivation, default on).
Runs given a skill are counted (skill_usage); platform-maintained skills
retire after 3 failing runs in a row or 90 days unused. Skills can be
imported from SKILL.md / zip, copied between projects and searched across
projects. Migration 004 converts existing lesson rows to skills.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
eust-w 2026-11-04 12:37:36 +08:00
parent ee340d6a8b
commit 0e4ef42771
17 changed files with 1504 additions and 303 deletions

View File

@ -0,0 +1,32 @@
-- Project lessons become project skills: one kind of project know-how, one prompt section.
-- Data changes below must see every tenant: fail instead of silently skipping rows under RLS.
SET LOCAL row_security = off;
-- A lesson recorded from a repaired failure becomes a pitfall skill, a convention one a convention
-- skill. Each keeps its id, project, status, author and source run; its name is made unique from
-- its id, its summary is both its description (shortened) and its content.
INSERT INTO entities(tenant_id, kind, id, version, data, created_at)
SELECT l.tenant_id, 'skill', l.id, 1,
jsonb_strip_nulls(jsonb_build_object(
'id', l.id,
'tenantId', l.tenant_id,
'createdAt', l.data->>'createdAt',
'updatedAt', coalesce(l.data->>'updatedAt', l.data->>'createdAt'),
'version', 1,
'projectId', l.data->>'projectId',
'name', CASE WHEN l.data->>'kind' = 'convention' THEN 'convention-' ELSE 'pitfall-' END
|| substr(regexp_replace(lower(l.id), '[^a-z0-9]', '', 'g'), 1, 12),
'description', left(regexp_replace(btrim(l.data->>'summary'), '\s+', ' ', 'g'), 300),
'content', btrim(l.data->>'summary'),
'category', CASE WHEN l.data->>'kind' = 'convention' THEN 'convention' ELSE 'pitfall' END,
'status', CASE WHEN l.data->>'status' = 'disabled' THEN 'disabled' ELSE 'active' END,
'sourceRunIds', CASE WHEN l.data ? 'sourceRunId' THEN jsonb_build_array(l.data->>'sourceRunId')
ELSE '[]'::jsonb END,
'createdBy', coalesce(l.data->>'createdBy', 'wishforge')
)),
l.created_at
FROM entities l
WHERE l.kind = 'lesson' AND coalesce(btrim(l.data->>'summary'), '') <> ''
ON CONFLICT (tenant_id, kind, id) DO NOTHING;
DELETE FROM entities WHERE kind = 'lesson';

View File

@ -52,8 +52,7 @@ import { Artifacts } from './artifacts.js';
import { providerProxyConfigured } from './provider-proxy.js';
import { assertVerificationProfile, verificationPolicyDigest } from './verification-policy.js';
import { IntegrationLeases } from './integration-lease.js';
import { captureLesson, projectLessons } from './lessons.js';
import { projectSkills } from './skills.js';
import { learnFromRun, projectSkills, recordSkillUse } from './skills.js';
import { describeProviderEvent } from './provider-events.js';
import { backendDefined, personWishScope, requirePermission, wishScopeOf } from './permissions.js';
@ -1135,6 +1134,9 @@ export class ControlPlane {
}
if (run.status === 'running') run.lastActiveAt = now();
else run.lastActiveAt = undefined;
// The executor starts an implementation round with the project's skills in its prompt.
if (actor.kind === 'worker' && run.stage === 'implement' && run.status === 'running')
await recordSkillUse(tx, run);
await tx.put('run', run);
await tx.event(id, 'run.transition', redact(data.message), {
stage: run.stage,
@ -1356,7 +1358,7 @@ export class ControlPlane {
clearWaiting(run);
if (run.lease) run.lease.expiresAt = now();
if (!run.providerProxyActiveRequest) run.reservedTokens = 0;
await captureLesson(tx, run);
await learnFromRun(tx, run);
await tx.event(
run.id,
'run.succeeded',
@ -1405,7 +1407,6 @@ export class ControlPlane {
verificationProfileRequired: isProduction(this.env),
connectionId: connection?.id ?? null,
bundleConfig: await resolveBundle(tx, run.bundleVersion),
lessons: await projectLessons(tx, run.projectId),
skills: await projectSkills(tx, run.projectId),
delivery: {
release,

View File

@ -1,90 +0,0 @@
import { z } from 'zod';
import { lessonInput, type Actor, type Lesson, type Run } from '@wishforge/contracts';
import { LESSON_LIMIT, repairLesson } from '@wishforge/agent';
import type { Store, Transaction } from '../db/store.js';
import { must, projectAccess, record, touch } from './control-plane.js';
import { redact, requireHuman, requireRole } from './policy.js';
const statusInput = z.object({ status: z.enum(['active', 'disabled']) }).strict();
const newestFirst = (a: Lesson, b: Lesson) => b.createdAt.localeCompare(a.createdAt);
/** Active lessons of a project, most recent first, as they are injected into prompts. */
export async function projectLessons(tx: Transaction, projectId: string): Promise<string[]> {
return (await tx.list<Lesson>('lesson', { projectId, status: 'active' }))
.sort(newestFirst)
.slice(0, LESSON_LIMIT)
.map(lesson => lesson.summary);
}
/** A run that needed a repair round before it succeeded leaves a lesson for later runs of its project. */
export async function captureLesson(tx: Transaction, run: Run) {
if (!run.repairCount || !run.lastFailure) return;
const lessons = await tx.list<Lesson>('lesson', { projectId: run.projectId });
if (lessons.some(lesson => lesson.sourceRunId === run.id && lesson.kind === 'repair')) return;
const lesson: Lesson = {
...record(run.tenantId),
projectId: run.projectId,
kind: 'repair',
summary: redact(repairLesson(run.lastFailure, run.implementationSummary)),
sourceRunId: run.id,
status: 'active',
createdBy: 'wishforge',
};
await tx.put('lesson', lesson);
await tx.event(run.id, 'lesson.recorded', 'Recorded a project lesson from the repaired failure.', {
lessonId: lesson.id,
});
}
/** Owners and admins review what later runs will be told. */
export class Lessons {
constructor(private readonly store: Store) {}
async list(actor: Actor, projectId: string) {
return this.store.read(actor.tenantId, async tx => {
await projectAccess(tx, actor, projectId);
return (await tx.list<Lesson>('lesson', { projectId })).sort(newestFirst);
});
}
async create(actor: Actor, projectId: string, input: unknown) {
this.authorize(actor);
const { summary } = lessonInput.parse(input);
return this.store.transaction(actor.tenantId, async tx => {
await projectAccess(tx, actor, projectId);
const lesson: Lesson = {
...record(actor.tenantId),
projectId,
kind: 'convention',
summary: redact(summary),
status: 'active',
createdBy: actor.userId,
};
await tx.put('lesson', lesson);
return lesson;
});
}
async setStatus(actor: Actor, id: string, input: unknown) {
this.authorize(actor);
const { status } = statusInput.parse(input);
return this.store.transaction(actor.tenantId, async tx => {
const lesson = await must<Lesson>(tx, 'lesson', id);
await projectAccess(tx, actor, lesson.projectId);
if (lesson.status === status) return lesson;
const next = { ...touch(lesson), status };
await tx.put('lesson', next);
return next;
});
}
async remove(actor: Actor, id: string) {
this.authorize(actor);
return this.store.transaction(actor.tenantId, async tx => {
const lesson = await must<Lesson>(tx, 'lesson', id);
await projectAccess(tx, actor, lesson.projectId);
await tx.remove('lesson', id);
return { deleted: true };
});
}
private authorize(actor: Actor) {
requireRole(actor, ['owner', 'admin']);
requireHuman(actor);
}
}

View File

@ -32,7 +32,7 @@ import {
setWaiting,
clearWaiting,
} from './control-plane.js';
import { captureLesson } from './lessons.js';
import { learnFromRun } from './skills.js';
import { digest, releaseRisk, requireRole, requireHuman } from './policy.js';
import { requirePermission } from './permissions.js';
@ -542,7 +542,7 @@ export class Releases {
run.stage = 'accept';
clearWaiting(run);
run.reservedTokens = 0;
await captureLesson(tx, run);
await learnFromRun(tx, run);
run.lastActiveAt = undefined;
if (run.lease) run.lease.expiresAt = now();
await tx.put('release', touch(release));

View File

@ -0,0 +1,282 @@
import { crc32, inflateRawSync } from 'node:zlib';
import {
DomainError,
SKILL_CONTENT_LIMIT,
skillCategories,
skillName,
type Skill,
type SkillCategory,
} from '@wishforge/contracts';
/**
* Skills as files: SKILL.md with its name and purpose up front, one directory per skill in a zip,
* as Claude Code's .claude/skills/ expects. Export writes them; import reads them back, from this
* platform's exports or from skills written elsewhere.
*/
/** What an import may hold. Larger archives and files are refused rather than read partly. */
export const SKILL_IMPORT_LIMITS = {
/** A zip as uploaded (before base64). */
archiveBytes: 512 * 1024,
/** Entries a zip's directory may list, skills or not. */
entries: 500,
/** Skills one import may add. */
skills: 50,
/** One SKILL.md, uncompressed. */
fileBytes: 64 * 1024,
/** Every SKILL.md of an archive together, uncompressed. */
totalBytes: 2 * 1024 * 1024,
} as const;
/** One skill read from a file, before it joins a project. */
export interface SkillFile {
name: string;
description: string;
content: string;
category: SkillCategory;
/** Where it came from: the file name or the path inside the archive. */
source: string;
}
/** A skill as Claude Code and other agents read it: SKILL.md with its name and purpose up front. */
export function skillMarkdown(skill: Pick<Skill, 'name' | 'description' | 'content' | 'category'>) {
const description = skill.description.replace(/\s+/g, ' ').trim();
// Other tools ignore metadata; an import here restores what kind of skill it was.
const metadata =
skill.category && skill.category !== 'workflow' ? `metadata:\n wishforge-category: ${skill.category}\n` : '';
return `---\nname: ${skill.name}\ndescription: ${JSON.stringify(description)}\n${metadata}---\n\n${skill.content.trim()}\n`;
}
const invalid = (source: string, reason: string) => new DomainError('INVALID_SKILL_FILE', `${source}: ${reason}`, 400);
/** A YAML scalar as SKILL.md front matter writes it: plain, single- or double-quoted. */
function scalar(raw: string, source: string): string {
const value = raw.trim();
if (value.startsWith('"')) {
try {
const parsed: unknown = JSON.parse(value);
if (typeof parsed === 'string') return parsed;
} catch {}
throw invalid(source, 'a quoted value in the front matter is not closed');
}
if (value.startsWith("'")) {
if (!value.endsWith("'") || value.length < 2)
throw invalid(source, 'a quoted value in the front matter is not closed');
return value.slice(1, -1).replaceAll("''", "'");
}
// A comment after a plain value is not part of it.
return value.replace(/\s+#.*$/, '');
}
/**
* The front matter keys SKILL.md uses: top-level scalars, block scalars (`|`, `>`) and one level
* of nesting (`metadata:`). Anything richer is ignored rather than misread.
*/
function frontMatter(lines: string[], source: string) {
const fields: Record<string, string> = {};
const nested: Record<string, string> = {};
for (let i = 0; i < lines.length; i++) {
const line = lines[i]!;
if (!line.trim() || line.trimStart().startsWith('#')) continue;
const match = /^([A-Za-z0-9_-]+):(.*)$/.exec(line);
if (!match) continue;
const [, key, rest] = match as unknown as [string, string, string];
const indented: string[] = [];
while (i + 1 < lines.length && (/^\s+\S/.test(lines[i + 1]!) || !lines[i + 1]!.trim())) indented.push(lines[++i]!);
const marker = rest.trim();
if (/^[|>][+-]?$/.test(marker)) {
const body = indented.map(item => item.trim());
fields[key] = (marker.startsWith('>') ? body.join(' ') : body.join('\n')).trim();
} else if (marker) {
fields[key] = [scalar(marker, source), ...indented.map(item => item.trim())].join(' ').trim();
} else
for (const item of indented) {
const child = /^\s+([A-Za-z0-9_-]+):(.*)$/.exec(item);
if (child?.[2]?.trim()) nested[`${key}.${child[1]}`] = scalar(child[2], source);
}
}
return { ...nested, ...fields };
}
/** Lowercase words joined by hyphens, from whatever a file or directory was called. */
export function skillSlug(value: string) {
return value
.normalize('NFKD')
.toLowerCase()
.replace(/[^a-z0-9]+/g, '-')
.replace(/^-+|-+$/g, '')
.slice(0, 64)
.replace(/-+$/, '');
}
/** The skill a path names when its front matter does not: `name/SKILL.md`, `name.SKILL.md` or `name.md`. */
function nameFromPath(source: string) {
const parts = source.split('/').filter(Boolean);
const file = parts.at(-1) ?? '';
if (/^skill\.md$/i.test(file)) return parts.at(-2) ?? '';
return file.replace(/(\.skill)?\.md$/i, '');
}
/** Reads one SKILL.md; `source` names it in errors and supplies the name when the file has none. */
export function parseSkillMarkdown(text: string, source: string): SkillFile {
const normalized = text.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
if (Buffer.byteLength(normalized, 'utf8') > SKILL_IMPORT_LIMITS.fileBytes)
throw invalid(source, `larger than ${SKILL_IMPORT_LIMITS.fileBytes / 1024} KiB`);
let fields: Record<string, string> = {};
let body = normalized;
if (normalized.startsWith('---\n')) {
const end = normalized.indexOf('\n---', 4);
if (end === -1) throw invalid(source, 'the front matter is not closed with ---');
fields = frontMatter(normalized.slice(4, end).split('\n'), source);
body = normalized.slice(end + 4).replace(/^[^\n]*\n?/, '');
}
const content = body.trim();
if (!content) throw invalid(source, 'the skill has no instructions after its front matter');
if (content.length > SKILL_CONTENT_LIMIT)
throw invalid(source, `the instructions are longer than ${SKILL_CONTENT_LIMIT} characters`);
const rawName = fields.name?.trim() || nameFromPath(source);
const name = skillName.safeParse(rawName).success ? rawName : skillSlug(rawName);
if (!name) throw invalid(source, 'the skill has no usable name');
// Skills written elsewhere sometimes leave the description out; their first line says what they are for.
const description = (fields.description || content.split('\n').find(line => line.trim()) || '')
.replace(/^#+\s*/, '')
.replace(/\s+/g, ' ')
.trim()
.slice(0, 500);
if (!description) throw invalid(source, 'the skill has no description');
const category = fields['metadata.wishforge-category'] ?? fields.category;
return {
name,
description,
content,
category: (skillCategories as readonly string[]).includes(category ?? '')
? (category as SkillCategory)
: 'workflow',
source,
};
}
/** A zip archive of text files, stored without compression: the format every system opens. */
export function zipFiles(files: { path: string; content: string }[], at = new Date()): Buffer {
const time = ((at.getHours() << 11) | (at.getMinutes() << 5) | (at.getSeconds() >> 1)) & 0xffff;
const date = (((at.getFullYear() - 1980) << 9) | ((at.getMonth() + 1) << 5) | at.getDate()) & 0xffff;
const locals: Buffer[] = [];
const centrals: Buffer[] = [];
let offset = 0;
for (const file of files) {
const name = Buffer.from(file.path, 'utf8');
const data = Buffer.from(file.content, 'utf8');
const checksum = crc32(data);
const local = Buffer.alloc(30);
local.writeUInt32LE(0x04034b50, 0);
local.writeUInt16LE(20, 4);
local.writeUInt16LE(0x0800, 6); // UTF-8 names
local.writeUInt16LE(0, 8);
local.writeUInt16LE(time, 10);
local.writeUInt16LE(date, 12);
local.writeUInt32LE(checksum, 14);
local.writeUInt32LE(data.length, 18);
local.writeUInt32LE(data.length, 22);
local.writeUInt16LE(name.length, 26);
local.writeUInt16LE(0, 28);
const central = Buffer.alloc(46);
central.writeUInt32LE(0x02014b50, 0);
central.writeUInt16LE(20, 4);
central.writeUInt16LE(20, 6);
central.writeUInt16LE(0x0800, 8);
central.writeUInt16LE(0, 10);
central.writeUInt16LE(time, 12);
central.writeUInt16LE(date, 14);
central.writeUInt32LE(checksum, 16);
central.writeUInt32LE(data.length, 20);
central.writeUInt32LE(data.length, 24);
central.writeUInt16LE(name.length, 28);
central.writeUInt32LE(offset, 42);
locals.push(local, name, data);
centrals.push(central, name);
offset += local.length + name.length + data.length;
}
const directory = Buffer.concat(centrals);
const end = Buffer.alloc(22);
end.writeUInt32LE(0x06054b50, 0);
end.writeUInt16LE(files.length, 8);
end.writeUInt16LE(files.length, 10);
end.writeUInt32LE(directory.length, 12);
end.writeUInt32LE(offset, 16);
return Buffer.concat([...locals, directory, end]);
}
const isSkillFile = (path: string) => /(^|\/)skill\.md$/i.test(path) || /\.skill\.md$/i.test(path);
/**
* The SKILL.md files of a zip, stored or deflated, as this platform and common tools write them.
* Other files (scripts, references) are counted, not read: a skill here is its instructions.
* Encrypted, multi-disk and ZIP64 archives, and anything beyond the limits, are refused.
*/
export function readSkillArchive(archive: Buffer): { files: { path: string; content: string }[]; ignored: number } {
const bad = (reason: string) => new DomainError('INVALID_SKILL_ARCHIVE', `The zip archive ${reason}`, 400);
if (archive.length > SKILL_IMPORT_LIMITS.archiveBytes)
throw bad(`is larger than ${SKILL_IMPORT_LIMITS.archiveBytes / 1024} KiB`);
let end = -1;
for (let i = archive.length - 22; i >= Math.max(0, archive.length - 22 - 0xffff); i--)
if (archive.readUInt32LE(i) === 0x06054b50) {
end = i;
break;
}
if (end === -1) throw bad('cannot be read: it is not a zip file');
const count = archive.readUInt16LE(end + 10);
const size = archive.readUInt32LE(end + 12);
const start = archive.readUInt32LE(end + 16);
if (archive.readUInt16LE(end + 4) !== 0 || count === 0xffff || start === 0xffffffff)
throw bad('uses multiple disks or ZIP64, which is not supported');
if (count > SKILL_IMPORT_LIMITS.entries) throw bad(`has more than ${SKILL_IMPORT_LIMITS.entries} entries`);
if (start + size > end) throw bad('is damaged');
const files: { path: string; content: string }[] = [];
let ignored = 0;
let total = 0;
let at = start;
for (let n = 0; n < count; n++) {
if (at + 46 > end || archive.readUInt32LE(at) !== 0x02014b50) throw bad('is damaged');
const flags = archive.readUInt16LE(at + 8);
const method = archive.readUInt16LE(at + 10);
const checksum = archive.readUInt32LE(at + 16);
const compressed = archive.readUInt32LE(at + 20);
const uncompressed = archive.readUInt32LE(at + 24);
const nameLength = archive.readUInt16LE(at + 28);
const extraLength = archive.readUInt16LE(at + 30);
const commentLength = archive.readUInt16LE(at + 32);
const local = archive.readUInt32LE(at + 42);
const path = archive.subarray(at + 46, at + 46 + nameLength).toString('utf8');
at += 46 + nameLength + extraLength + commentLength;
if (path.endsWith('/')) continue;
// macOS adds resource forks under __MACOSX/; they are not skills.
if (!isSkillFile(path) || path.startsWith('__MACOSX/')) {
ignored++;
continue;
}
if (flags & 1) throw bad(`is encrypted (${path})`);
if (uncompressed > SKILL_IMPORT_LIMITS.fileBytes)
throw bad(`holds ${path}, larger than ${SKILL_IMPORT_LIMITS.fileBytes / 1024} KiB`);
total += uncompressed;
if (total > SKILL_IMPORT_LIMITS.totalBytes)
throw bad(`holds more than ${SKILL_IMPORT_LIMITS.totalBytes / 1024 / 1024} MiB of skills`);
if (local + 30 > end || archive.readUInt32LE(local) !== 0x04034b50) throw bad('is damaged');
const dataStart = local + 30 + archive.readUInt16LE(local + 26) + archive.readUInt16LE(local + 28);
if (dataStart + compressed > end) throw bad('is damaged');
const raw = archive.subarray(dataStart, dataStart + compressed);
let data: Buffer;
if (method === 0) data = raw;
else if (method === 8)
try {
data = inflateRawSync(raw, { maxOutputLength: SKILL_IMPORT_LIMITS.fileBytes });
} catch {
throw bad(`holds ${path}, which cannot be decompressed`);
}
else throw bad(`compresses ${path} in a way that is not supported`);
if (data.length !== uncompressed || crc32(data) !== checksum) throw bad(`holds ${path}, which is damaged`);
files.push({ path, content: data.toString('utf8') });
if (files.length > SKILL_IMPORT_LIMITS.skills)
throw bad(`holds more than ${SKILL_IMPORT_LIMITS.skills} skills; import them in parts`);
}
return { files, ignored };
}

View File

@ -1,103 +1,273 @@
import { crc32 } from 'node:zlib';
import { z } from 'zod';
import { askClaude } from '@wishforge/runtime';
import { SKILL_LIMIT, type PromptSkill } from '@wishforge/agent';
import { repairLesson, selectSkills, type PromptSkill } from '@wishforge/agent';
import {
DomainError,
SKILL_CONTENT_LIMIT,
skillCategories,
skillInput,
skillName,
skillUpdateInput,
type Actor,
type CodeReview,
type FailureSummary,
type Project,
type Run,
type Skill,
type SkillHarvest,
type SkillUsage,
} from '@wishforge/contracts';
import type { Store, Transaction } from '../db/store.js';
import { must, projectAccess, record, touch } from './control-plane.js';
import { idempotent, must, now, projectAccess, record, terminal, touch } from './control-plane.js';
import { nativeClaudeEnabled } from './local-execution.js';
import { wishScopeOf } from './permissions.js';
import { redact, requireHuman } from './policy.js';
import {
SKILL_IMPORT_LIMITS,
parseSkillMarkdown,
readSkillArchive,
skillMarkdown,
skillSlug,
zipFiles,
type SkillFile,
} from './skill-files.js';
import { dispatchTenants } from '../tenants.js';
export { skillMarkdown, zipFiles } from './skill-files.js';
const recentlyChanged = (a: Skill, b: Skill) => b.updatedAt.localeCompare(a.updatedAt);
/** Active skills of a project, most recently changed first, as they enter prompts. */
/** A pitfall records at most this many repaired failures, most recent first. */
const PITFALL_ENTRIES = 8;
/** A skill remembers at most this many runs it was learned from. */
const SOURCE_RUNS = 20;
/** A platform-maintained skill is retired after this many settled runs in a row that used it failed. */
export const RETIRE_AFTER_FAILURES = 3;
/** A platform-maintained skill no run was given for this long, while the project kept running, is retired. */
export const RETIRE_UNUSED_DAYS = 90;
/** Whether the project lets the platform activate corroborated skills itself (absent: yes). */
export const autoActivation = (project: Pick<Project, 'skillAutoActivation'>) => project.skillAutoActivation !== false;
/** Learned by the platform and not since written by a person: the platform may rewrite or retire it. */
export const platformMaintained = (skill: Skill) => skill.createdBy === 'wishforge' && !skill.updatedBy;
/** A change to a skill's bookkeeping only: it keeps its place among the most recently changed. */
const counted = (skill: Skill, changes: Partial<Skill>): Skill => ({
...skill,
...changes,
version: skill.version + 1,
});
const lastRuns = (ids: string[], runId: string) => [...ids.filter(id => id !== runId), runId].slice(-SOURCE_RUNS);
/** Active skills of a project as they enter prompts: most recently changed first, within the limits. */
async function promptSkillsOf(tx: Transaction, projectId: string): Promise<Skill[]> {
return selectSkills((await tx.list<Skill>('skill', { projectId, status: 'active' })).sort(recentlyChanged));
}
export async function projectSkills(tx: Transaction, projectId: string): Promise<PromptSkill[]> {
return (await tx.list<Skill>('skill', { projectId, status: 'active' }))
.sort(recentlyChanged)
.slice(0, SKILL_LIMIT)
.map(({ name, description, content }) => ({ name, description, content }));
return (await promptSkillsOf(tx, projectId)).map(({ name, description, content }) => ({
name,
description,
content,
}));
}
/** A skill as Claude Code and other agents read it: SKILL.md with its name and purpose up front. */
export function skillMarkdown(skill: Pick<Skill, 'name' | 'description' | 'content'>) {
const description = skill.description.replace(/\s+/g, ' ').trim();
return `---\nname: ${skill.name}\ndescription: ${JSON.stringify(description)}\n---\n\n${skill.content.trim()}\n`;
/**
* Notes which skills a run's implementation is given, once per run and skill: called when an
* executor takes the run at its implementation stage, just before it reads them.
*/
export async function recordSkillUse(tx: Transaction, run: Run) {
const skills = await promptSkillsOf(tx, run.projectId);
const usage = await tx.get<SkillUsage>('skill_usage', run.id);
const known = new Set(usage?.skillIds ?? []);
const fresh = skills.filter(skill => !known.has(skill.id));
if (!fresh.length) return;
const time = now();
for (const skill of fresh)
await tx.put('skill', counted(skill, { useCount: (skill.useCount ?? 0) + 1, lastUsedAt: time }));
const next: SkillUsage = {
...(usage ? touch(usage) : { ...record(run.tenantId), id: run.id }),
runId: run.id,
projectId: run.projectId,
skillIds: [...known, ...fresh.map(skill => skill.id)],
};
await tx.put('skill_usage', next);
}
/** A zip archive of text files, stored without compression: the format every system opens. */
export function zipFiles(files: { path: string; content: string }[], at = new Date()): Buffer {
const time = ((at.getHours() << 11) | (at.getMinutes() << 5) | (at.getSeconds() >> 1)) & 0xffff;
const date = (((at.getFullYear() - 1980) << 9) | ((at.getMonth() + 1) << 5) | at.getDate()) & 0xffff;
const locals: Buffer[] = [];
const centrals: Buffer[] = [];
let offset = 0;
for (const file of files) {
const name = Buffer.from(file.path, 'utf8');
const data = Buffer.from(file.content, 'utf8');
const checksum = crc32(data);
const local = Buffer.alloc(30);
local.writeUInt32LE(0x04034b50, 0);
local.writeUInt16LE(20, 4);
local.writeUInt16LE(0x0800, 6); // UTF-8 names
local.writeUInt16LE(0, 8);
local.writeUInt16LE(time, 10);
local.writeUInt16LE(date, 12);
local.writeUInt32LE(checksum, 14);
local.writeUInt32LE(data.length, 18);
local.writeUInt32LE(data.length, 22);
local.writeUInt16LE(name.length, 26);
local.writeUInt16LE(0, 28);
const central = Buffer.alloc(46);
central.writeUInt32LE(0x02014b50, 0);
central.writeUInt16LE(20, 4);
central.writeUInt16LE(20, 6);
central.writeUInt16LE(0x0800, 8);
central.writeUInt16LE(0, 10);
central.writeUInt16LE(time, 12);
central.writeUInt16LE(date, 14);
central.writeUInt32LE(checksum, 16);
central.writeUInt32LE(data.length, 20);
central.writeUInt32LE(data.length, 24);
central.writeUInt16LE(name.length, 28);
central.writeUInt32LE(offset, 42);
locals.push(local, name, data);
centrals.push(central, name);
offset += local.length + name.length + data.length;
/**
* Counts how a finished run that was given skills ended. A success resets each skill's failure
* streak; a failure (or a cancel after a failed check) extends it, and a platform-maintained skill
* whose streak reaches RETIRE_AFTER_FAILURES is disabled. A cancel without a failure counts for
* neither: the person changed their mind, not the skill.
*/
export async function settleSkillUsage(tx: Transaction, run: Run) {
const usage = await tx.get<SkillUsage>('skill_usage', run.id);
if (!usage || usage.outcome || !terminal(run)) return;
const outcome: NonNullable<SkillUsage['outcome']> =
run.status === 'succeeded'
? 'succeeded'
: run.status === 'failed' || run.repairCount > 0 || run.lastFailure
? 'failed'
: 'neutral';
await tx.put('skill_usage', { ...touch(usage), outcome });
if (outcome === 'neutral') return;
const retired: Skill[] = [];
for (const id of usage.skillIds) {
const skill = await tx.get<Skill>('skill', id);
if (!skill) continue;
let next =
outcome === 'succeeded'
? counted(skill, { successCount: (skill.successCount ?? 0) + 1, failureStreak: 0 })
: counted(skill, {
failureCount: (skill.failureCount ?? 0) + 1,
failureStreak: (skill.failureStreak ?? 0) + 1,
});
if (
outcome === 'failed' &&
next.status === 'active' &&
platformMaintained(next) &&
(next.failureStreak ?? 0) >= RETIRE_AFTER_FAILURES
) {
next = { ...touch(next), status: 'disabled', retiredAt: now(), retiredReason: 'failing' };
retired.push(next);
}
await tx.put('skill', next);
}
const directory = Buffer.concat(centrals);
const end = Buffer.alloc(22);
end.writeUInt32LE(0x06054b50, 0);
end.writeUInt16LE(files.length, 8);
end.writeUInt16LE(files.length, 10);
end.writeUInt32LE(directory.length, 12);
end.writeUInt32LE(offset, 16);
return Buffer.concat([...locals, directory, end]);
if (retired.length)
await tx.event(
run.id,
'skill.retired',
`Disabled ${retired.map(skill => skill.name).join(', ')}: the last ${RETIRE_AFTER_FAILURES} runs that used ${retired.length > 1 ? 'them' : 'it'} failed.`,
{ skillIds: retired.map(skill => skill.id), reason: 'failing' },
);
}
export const HARVEST_RULES = `你是一名资深工程师,负责为一个软件项目沉淀"技能"(skill):以后在这个项目里做类似工作时,编码 Agent 可以直接照做的、可复用的做法。你会拿到一次已完成的工作记录(需求、验收标准、实现总结、改动的文件、遇到的失败和审核意见)以及项目里已有的技能。
/**
* What identifies a failure across runs: the failing command, or the conflicting or out-of-scope
* files. The same failure in a later run updates the same pitfall instead of adding another.
*/
export function failureSignature(failure: FailureSummary): string {
const words = (text: string) => text.toLowerCase().split(/\s+/).filter(Boolean);
if (failure.kind === 'integration_conflict' || failure.kind === 'scope')
return `${failure.kind}:${[...new Set(words(failure.outputTail))].sort().join(' ')}`.slice(0, 500);
return `${failure.kind}:${words((failure.argv ?? []).join(' ')).join(' ')}`.slice(0, 500);
}
const PITFALL_HEADER = 'Earlier runs of this project failed here, and a repair round fixed it. Most recent first:';
/** The name and purpose of a pitfall about a failure. */
function pitfallOf(failure: FailureSummary): { name: string; description: string } {
const command = `\`${failure.argv?.join(' ') ?? 'verification'}\``;
const files = failure.outputTail.split(/\s+/).filter(Boolean);
const subject =
failure.kind === 'integration_conflict'
? `merge-conflict ${files[0] ?? ''}`
: failure.kind === 'scope'
? 'frontend-scope'
: // Executables by name, not by where they are installed.
`${failure.kind === 'install' ? 'install ' : ''}${failure.argv?.map(word => word.split('/').pop()).join(' ') ?? 'verification'}`;
const description =
failure.kind === 'integration_conflict'
? `When changing ${files.slice(0, 5).join(', ')}: merging into the target branch conflicted there before; how it was resolved.`
: failure.kind === 'scope'
? 'For frontend-only wishes: backend files were changed by mistake before; how the change stayed in the frontend.'
: failure.kind === 'install'
? `Before changing dependency manifests: installing with ${command} failed in earlier runs; what fixed it.`
: `Before finishing a change that ${command} checks: how it failed in earlier runs and what fixed it.`;
return {
name: `pitfall-${skillSlug(subject)}`.slice(0, 64).replace(/-+$/, ''),
description: description.slice(0, 500),
};
}
/** A pitfall's content with a new entry first: rebuilt when the platform keeps it, else prepended. */
function withEntry(skill: Skill | undefined, entry: string) {
const line = `- ${entry}`;
if (!skill) return `${PITFALL_HEADER}\n\n${line}`;
if (!platformMaintained(skill)) return `${line}\n\n${skill.content}`.slice(0, SKILL_CONTENT_LIMIT);
const entries = skill.content.split('\n').filter(item => item.startsWith('- '));
return `${PITFALL_HEADER}\n\n${[line, ...entries].slice(0, PITFALL_ENTRIES).join('\n')}`.slice(
0,
SKILL_CONTENT_LIMIT,
);
}
/** A name the project does not use yet: the name itself, or with the next free number. */
function freeName(name: string, taken: Set<string>) {
if (!taken.has(name)) return name;
for (let n = 2; ; n++) {
const suffix = `-${n}`;
const candidate = `${name.slice(0, 64 - suffix.length).replace(/-+$/, '')}${suffix}`;
if (!taken.has(candidate)) return candidate;
}
}
/**
* What a run that ended well teaches the project: its skills' counts include it, and when a
* repair round fixed a failure on the way, that failure becomes (or updates) a pitfall skill.
* The pitfall is active right away where the project lets the platform activate skills, since
* it is drawn from a verified failure and a verified fix; otherwise it waits for a person.
*/
export async function learnFromRun(tx: Transaction, run: Run) {
await settleSkillUsage(tx, run);
if (!run.repairCount || !run.lastFailure) return;
const project = await must<Project>(tx, 'project', run.projectId);
const skills = await tx.list<Skill>('skill', { projectId: run.projectId });
const signature = failureSignature(run.lastFailure);
const entry = redact(repairLesson(run.lastFailure, run.implementationSummary));
const existing = skills.find(skill => skill.category === 'pitfall' && skill.signature === signature);
if (existing?.sourceRunIds.includes(run.id)) return;
const auto = autoActivation(project);
if (existing) {
const activate = existing.status === 'proposed' && auto;
const next: Skill = {
...touch(existing),
content: withEntry(existing, entry),
sourceRunIds: lastRuns(existing.sourceRunIds, run.id),
...(activate ? { status: 'active' as const } : {}),
};
await tx.put('skill', next);
await tx.event(
run.id,
activate ? 'skill.activated' : 'skill.updated',
`${activate ? 'Activated' : 'Updated'} the pitfall skill ${next.name} with the repaired failure${next.status === 'disabled' ? '; it stays disabled' : ''}.`,
{ skillId: next.id },
);
return;
}
const pitfall = pitfallOf(run.lastFailure);
const skill: Skill = {
...record(run.tenantId),
projectId: run.projectId,
name: freeName(pitfall.name, new Set(skills.map(item => item.name))),
description: redact(pitfall.description),
content: withEntry(undefined, entry),
category: 'pitfall',
signature,
status: auto ? 'active' : 'proposed',
sourceRunIds: [run.id],
createdBy: 'wishforge',
};
await tx.put('skill', skill);
await tx.event(
run.id,
auto ? 'skill.activated' : 'skill.proposed',
`Recorded the repaired failure as the pitfall skill ${skill.name}${auto ? '; later runs are told about it' : ', waiting for confirmation'}.`,
{ skillId: skill.id, skillIds: [skill.id] },
);
}
export const HARVEST_RULES = `你是一名资深工程师,负责为一个软件项目沉淀"技能"(skill):以后在这个项目里做类似工作时,编码 Agent 可以直接照做的、可复用的做法。你会拿到一次已完成的工作记录(需求、验收标准、实现总结、改动的文件、遇到的失败和审核意见)以及项目里已有的技能(category 为 workflow 是做法,pitfall 是踩过的坑和修法,convention 是项目约定;status 为 disabled 的是被停用的)。
1. 只提炼以后还会用到的、对这个项目具体有用的做法:例如这个项目里某类改动该改哪些地方、按什么步骤、要注意什么坑、怎么验证。不要把这一次的具体改动本身写成技能。
2. 通用常识(写测试、读代码、遵守代码风格之类)不算技能。已有技能已经覆盖的不要重复。没有值得沉淀的就返回空数组,这完全正常。
3. 最多返回 2 个。name 用小写英文单词和连字符,例如 lazy-load-page-css;description 用一两句话写"什么时候用它";content 用 Markdown 写做法:适用场景、步骤、注意事项、如何验证,具体到这个项目的目录、文件和命令,不超过 3000 字。
4. 只写工作记录里有依据的内容,不要编造文件、命令或结论。
5. 用和需求相同的语言写 description 和 content。`;
2. 通用常识(写测试、读代码、遵守代码风格之类)不算技能。已有技能已经覆盖的不要重复,被停用的也不要再提。没有值得沉淀的就返回空数组,这完全正常。
3. 这次的工作让某个已有技能需要补充或修正时,不要新建:把 updates 设为那个技能的 name,name 也用它,content 写合并后的完整做法(保留原有仍然成立的内容)。全新的技能不要填 updates。
4. 最多返回 2 个。name 用小写英文单词和连字符,例如 lazy-load-page-css;description 用一两句话写"什么时候用它";content 用 Markdown 写做法:适用场景、步骤、注意事项、如何验证,具体到这个项目的目录、文件和命令,不超过 3000 字。
5. 只写工作记录里有依据的内容,不要编造文件、命令或结论。
6. 用和需求相同的语言写 description 和 content。`;
const proposal = z
.object({
name: skillName,
description: z.string().trim().min(1).max(500),
content: z.string().trim().min(1).max(8000),
updates: z.string().trim().max(64).optional(),
})
.strip();
const harvestSchema = {
@ -113,6 +283,7 @@ const harvestSchema = {
name: { type: 'string', description: '小写英文单词和连字符' },
description: { type: 'string', description: '什么时候用它,一两句话' },
content: { type: 'string', description: 'Markdown 写的做法:适用场景、步骤、注意事项、如何验证' },
updates: { type: 'string', description: '补充已有技能时填它的 name;新技能不填' },
},
required: ['name', 'description', 'content'],
additionalProperties: false,
@ -134,13 +305,51 @@ function changedFiles(events: { type: string; message: string }[]) {
return [...files].slice(0, 100);
}
const listQuery = z
.object({
projectId: z.string().min(1).max(128).optional(),
status: z.enum(['proposed', 'active', 'disabled']).optional(),
category: z.enum(skillCategories).optional(),
q: z.string().trim().max(200).optional(),
})
.strict();
const copyInput = z
.object({ skillIds: z.array(z.string().min(1).max(128)).min(1).max(100), projectId: z.string().min(1).max(128) })
.strict();
const importInput = z
.object({
/** SKILL.md files as text, each with its file name. */
files: z
.array(z.object({ path: z.string().min(1).max(300), content: z.string().max(SKILL_IMPORT_LIMITS.fileBytes) }))
.min(1)
.max(SKILL_IMPORT_LIMITS.skills)
.optional(),
/** A zip, base64-encoded, as the project export writes it. */
archive: z
.string()
.max(Math.ceil((SKILL_IMPORT_LIMITS.archiveBytes * 4) / 3) + 4)
.optional(),
/** Imported skills are active unless they should wait for a confirmation first. */
status: z.enum(['active', 'proposed']).default('active'),
})
.strict()
.refine(value => Boolean(value.files) !== Boolean(value.archive), 'Provide either SKILL.md files or a zip archive');
/** What adding skills to a project did: added (perhaps under another name), or left out and why. */
export interface SkillTransfer {
created: Skill[];
skipped: { name: string; source: string; reason: 'identical' | 'invalid'; detail?: string }[];
/** Files in an archive that were not SKILL.md. */
ignored: number;
}
/** At most this many proposals are worked out at once on the deployment's Claude account. */
const CONCURRENCY = 1;
let running = 0;
/**
* A project's skills: proposed by the platform from finished runs, confirmed, edited, disabled,
* deleted and exported by the people who wish for the project.
* Project skills, the one place a project's know-how lives: workflows the platform proposes from
* finished runs, pitfalls it records from repaired failures, conventions people write. Whoever may
* wish for a project confirms, edits, disables, deletes, copies, imports and exports them.
*/
export class Skills {
constructor(
@ -154,6 +363,32 @@ export class Skills {
return (await tx.list<Skill>('skill', { projectId })).sort(recentlyChanged);
});
}
/** Skills of every project the person may see, filtered as the knowledge base page asks. */
async search(actor: Actor, query: unknown) {
const filter = listQuery.parse(query);
return this.store.read(actor.tenantId, async tx => {
if (filter.projectId) await projectAccess(tx, actor, filter.projectId);
const visible = new Set(
(await tx.list<Project>('project'))
.filter(p => ['owner', 'admin'].includes(actor.role) || p.memberIds.includes(actor.userId))
.map(p => p.id),
);
const words = filter.q?.toLowerCase();
return (
await tx.list<Skill>('skill', {
...(filter.projectId ? { projectId: filter.projectId } : {}),
...(filter.status ? { status: filter.status } : {}),
})
)
.filter(
skill =>
visible.has(skill.projectId) &&
(!filter.category || (skill.category ?? 'workflow') === filter.category) &&
(!words || [skill.name, skill.description, skill.content].some(text => text.toLowerCase().includes(words))),
)
.sort(recentlyChanged);
});
}
async create(actor: Actor, projectId: string, input: unknown) {
const data = skillInput.parse(input);
return this.store.transaction(actor.tenantId, async tx => {
@ -166,6 +401,7 @@ export class Skills {
name: data.name,
description: redact(data.description),
content: redact(data.content),
category: data.category,
status: 'active',
sourceRunIds: [],
createdBy: actor.userId,
@ -174,21 +410,32 @@ export class Skills {
return skill;
});
}
/** Edits a skill; confirming a proposal is setting it active. */
/**
* Edits a skill; confirming a proposal is setting it active. Changing what it says makes it a
* person's: the platform no longer rewrites or retires it. Enabling it again starts its failure
* streak afresh.
*/
async update(actor: Actor, id: string, input: unknown) {
const data = skillUpdateInput.parse(input);
return this.store.transaction(actor.tenantId, async tx => {
const skill = await must<Skill>(tx, 'skill', id);
this.authorize(actor, await projectAccess(tx, actor, skill.projectId));
if (data.name && data.name !== skill.name) await this.uniqueName(tx, skill.projectId, data.name, id);
const edited = Boolean(data.name || data.description || data.content || data.category);
const next: Skill = {
...touch(skill),
...(data.name ? { name: data.name } : {}),
...(data.description ? { description: redact(data.description) } : {}),
...(data.content ? { content: redact(data.content) } : {}),
...(data.category ? { category: data.category } : {}),
...(data.status ? { status: data.status } : {}),
updatedBy: actor.userId,
...(edited ? { updatedBy: actor.userId } : {}),
};
if (data.status === 'active' && skill.status !== 'active') {
delete next.retiredAt;
delete next.retiredReason;
next.failureStreak = 0;
}
await tx.put('skill', next);
return next;
});
@ -211,7 +458,7 @@ export class Skills {
}
/**
* The project's skills, proposals left out unless asked for, as a zip with a directory per skill
* holding its SKILL.md: what .claude/skills/ expects.
* holding its SKILL.md: what .claude/skills/ expects, and what import reads back.
*/
async exportAll(actor: Actor, projectId: string, includeProposed = false) {
return this.store.read(actor.tenantId, async tx => {
@ -220,17 +467,125 @@ export class Skills {
.filter(skill => skill.status === 'active' || (includeProposed && skill.status === 'proposed'))
.sort((a, b) => a.name.localeCompare(b.name));
if (!skills.length) throw new DomainError('NO_SKILLS', 'This project has no skills to export', 404);
const slug = project.name
.normalize('NFKD')
.replace(/[^A-Za-z0-9]+/g, '-')
.replace(/^-|-$/g, '')
.toLowerCase();
return {
filename: `${slug || 'project'}-skills.zip`,
filename: `${skillSlug(project.name) || 'project'}-skills.zip`,
content: zipFiles(skills.map(skill => ({ path: `${skill.name}/SKILL.md`, content: skillMarkdown(skill) }))),
};
});
}
/**
* Adds skills from SKILL.md files or a zip of them (as export writes it) to a project. A skill
* the project already has word for word (description and content) is skipped, so importing the
* same files twice adds nothing; one whose name a different skill holds is added with the next
* free number.
*/
async importFiles(actor: Actor, projectId: string, input: unknown, key?: string): Promise<SkillTransfer> {
const data = importInput.parse(input);
let sources: { path: string; content: string }[];
let ignored = 0;
if (data.archive) {
const archive = Buffer.from(data.archive, 'base64');
({ files: sources, ignored } = readSkillArchive(archive));
} else sources = data.files!;
const skipped: SkillTransfer['skipped'] = [];
const parsed: SkillFile[] = [];
for (const source of sources)
try {
parsed.push(parseSkillMarkdown(source.content, source.path));
} catch (error) {
skipped.push({
name: source.path,
source: source.path,
reason: 'invalid',
detail: error instanceof Error ? error.message : 'unreadable',
});
}
if (!parsed.length)
throw new DomainError(
'NO_SKILLS',
skipped.length ? `No skill could be read: ${skipped[0]!.detail}` : 'The archive holds no SKILL.md files',
400,
);
return this.store.transaction(actor.tenantId, async tx => {
this.authorize(actor, await projectAccess(tx, actor, projectId));
return idempotent(tx, key && `skills-import:${actor.userId}:${projectId}:${key}`, data, async () => {
const result = await this.addSkills(tx, actor, projectId, parsed, () => data.status);
return { ...result, skipped: [...skipped, ...result.skipped], ignored };
});
});
}
/**
* Copies skills to another project the person may shape, keeping what they say and whether they
* are active, but not their counts or the runs they came from. Collisions as for an import.
*/
async copy(actor: Actor, input: unknown, key?: string): Promise<SkillTransfer> {
const data = copyInput.parse(input);
return this.store.transaction(actor.tenantId, async tx => {
this.authorize(actor, await projectAccess(tx, actor, data.projectId));
return idempotent(tx, key && `skills-copy:${actor.userId}:${key}`, data, async () => {
const originals: Skill[] = [];
for (const id of new Set(data.skillIds)) {
const skill = await must<Skill>(tx, 'skill', id);
await projectAccess(tx, actor, skill.projectId);
originals.push(skill);
}
const files = originals.map(skill => ({
name: skill.name,
description: skill.description,
content: skill.content,
category: skill.category ?? 'workflow',
source: skill.id,
signature: skill.signature,
}));
const status = new Map(originals.map(skill => [skill.id, skill.status]));
return {
...(await this.addSkills(tx, actor, data.projectId, files, file => status.get(file.source)!)),
ignored: 0,
};
});
});
}
private async addSkills(
tx: Transaction,
actor: Actor,
projectId: string,
files: (SkillFile & { signature?: string })[],
status: (file: SkillFile) => Skill['status'],
): Promise<Omit<SkillTransfer, 'ignored'>> {
const existing = await tx.list<Skill>('skill', { projectId });
const taken = new Set(existing.map(skill => skill.name));
const created: Skill[] = [];
const skipped: SkillTransfer['skipped'] = [];
for (const file of files) {
const description = redact(file.description);
const content = redact(file.content);
// Saying exactly the same under whatever name: already there.
const same = [...existing, ...created].find(
skill => skill.description === description && skill.content === content,
);
if (same) {
skipped.push({ name: file.name, source: file.source, reason: 'identical' });
continue;
}
const name = freeName(file.name, taken);
taken.add(name);
const skill: Skill = {
...record(actor.tenantId),
projectId,
name,
description,
content,
category: file.category,
...(file.signature ? { signature: file.signature } : {}),
status: status(file),
sourceRunIds: [],
createdBy: actor.userId,
};
await tx.put('skill', skill);
created.push(skill);
}
return { created, skipped };
}
available(tenantId: string) {
return nativeClaudeEnabled(this.env, tenantId);
}
@ -254,8 +609,12 @@ export class Skills {
return this.harvest(actor.tenantId, runId);
}
/**
* Looks for skills in one run and stores what it finds as proposals; records that it looked, so
* the background harvest does not ask again.
* Looks for skills in one run. A proposal that names an existing skill (or is called like one)
* updates it instead of adding another: a proposal is rewritten, as is an active skill only the
* platform maintains where the project lets it activate skills; a skill a person wrote or
* disabled just records the run. A proposal seen in two succeeded runs becomes active where the
* project allows it. Records that it looked, so the background harvest does not ask again.
* Returns the skills it added or changed.
*/
async harvest(tenantId: string, runId: string): Promise<Skill[]> {
running++;
@ -285,9 +644,13 @@ export class Skills {
? { kind: run.lastFailure.kind, outputTail: run.lastFailure.outputTail.slice(-2000) }
: undefined,
reviewComments: reviews.flatMap(review => (review.comment ? [review.comment] : [])).slice(0, 5),
existingSkills: existing
.filter(skill => skill.status !== 'disabled')
.map(skill => ({ name: skill.name, description: skill.description, content: skill.content.slice(0, 1500) })),
existingSkills: existing.sort(recentlyChanged).map(skill => ({
name: skill.name,
category: skill.category ?? 'workflow',
status: skill.status,
description: skill.description,
...(skill.status === 'disabled' ? {} : { content: skill.content.slice(0, 1500) }),
})),
};
const output = await this.ask({
binary: this.env.WF_CLAUDE_BIN!,
@ -307,35 +670,76 @@ export class Skills {
})
.slice(0, 2);
return await this.store.transaction(tenantId, async tx => {
const names = new Set((await tx.list<Skill>('skill', { projectId: run.projectId })).map(skill => skill.name));
const project = await must<Project>(tx, 'project', run.projectId);
const auto = autoActivation(project);
const skills = await tx.list<Skill>('skill', { projectId: run.projectId });
const byName = new Map(skills.map(skill => [skill.name, skill]));
const succeeded = async (ids: string[]) => {
let count = 0;
for (const id of ids) if ((await tx.get<Run>('run', id))?.status === 'succeeded') count++;
return count;
};
const created: Skill[] = [];
const updated: Skill[] = [];
const activated: Skill[] = [];
for (const item of proposals) {
// A name the project uses already gets the next free number.
let name = item.name;
for (let n = 2; names.has(name); n++) name = `${item.name}-${n}`;
names.add(name);
const description = redact(item.description);
const content = redact(item.content).slice(0, SKILL_CONTENT_LIMIT);
const target = (item.updates && byName.get(item.updates)) || byName.get(item.name);
if (target) {
const rewrite =
target.status === 'proposed' || (target.status === 'active' && auto && platformMaintained(target));
// Asked about the same run again: only new words are news.
const unchanged = !rewrite || (target.content === content && target.description === description);
if (target.sourceRunIds.includes(run.id) && unchanged) continue;
const sourceRunIds = lastRuns(target.sourceRunIds, run.id);
const activate = target.status === 'proposed' && auto && (await succeeded(sourceRunIds)) >= 2;
const next: Skill = rewrite
? { ...touch(target), description, content, sourceRunIds }
: counted(target, { sourceRunIds });
if (activate) next.status = 'active';
await tx.put('skill', next);
byName.set(next.name, next);
(activate ? activated : updated).push(next);
continue;
}
const skill: Skill = {
...record(tenantId),
projectId: run.projectId,
name,
description: redact(item.description),
content: redact(item.content).slice(0, SKILL_CONTENT_LIMIT),
name: freeName(item.name, new Set(byName.keys())),
description,
content,
category: 'workflow',
status: 'proposed',
sourceRunIds: [run.id],
createdBy: 'wishforge',
};
await tx.put('skill', skill);
byName.set(skill.name, skill);
created.push(skill);
}
await this.recordHarvest(tx, run, { status: 'done', skillIds: created.map(skill => skill.id) });
const changed = [...created, ...updated, ...activated];
await this.recordHarvest(tx, run, { status: 'done', skillIds: changed.map(skill => skill.id) });
const names = (list: Skill[]) => list.map(skill => skill.name).join(', ');
if (created.length)
await tx.event(
run.id,
'skill.proposed',
`Proposed ${created.length} project skill${created.length > 1 ? 's' : ''}: ${created.map(skill => skill.name).join(', ')}`,
`Proposed ${created.length} project skill${created.length > 1 ? 's' : ''}: ${names(created)}`,
{ skillIds: created.map(skill => skill.id) },
);
return created;
if (updated.length)
await tx.event(run.id, 'skill.updated', `Updated project skills with this run: ${names(updated)}`, {
skillIds: updated.map(skill => skill.id),
});
if (activated.length)
await tx.event(
run.id,
'skill.activated',
`Activated ${names(activated)}: proposed again by a second succeeded run.`,
{ skillIds: activated.map(skill => skill.id) },
);
return changed;
});
} catch (error) {
await this.store
@ -387,6 +791,38 @@ export class Skills {
await this.harvest(tenantId, next.id);
return next.id;
}
/**
* Keeps the skills honest: counts the outcome of every finished run that was given skills (a
* success counts when it happens; failures and cancels are found here), and retires
* platform-maintained skills no run was given for RETIRE_UNUSED_DAYS while their project kept
* running, crowded out by newer ones. Returns the skills it retired.
*/
async maintain(tenantId: string, at = new Date()): Promise<Skill[]> {
return this.store.transaction(tenantId, async tx => {
const usages = await tx.list<SkillUsage>('skill_usage');
// Oldest first, so a failure streak ends on the run that completed it.
for (const usage of usages.filter(item => !item.outcome).reverse()) {
const run = await tx.get<Run>('run', usage.runId);
if (!run) await tx.put('skill_usage', { ...touch(usage), outcome: 'neutral' });
else await settleSkillUsage(tx, run);
}
const cutoff = new Date(at.getTime() - RETIRE_UNUSED_DAYS * 86_400_000).toISOString();
const live = new Set(usages.filter(usage => usage.createdAt >= cutoff).map(usage => usage.projectId));
const retired: Skill[] = [];
for (const skill of await tx.list<Skill>('skill', { status: 'active' }))
if (platformMaintained(skill) && live.has(skill.projectId) && (skill.lastUsedAt ?? skill.updatedAt) < cutoff) {
const next: Skill = {
...touch(skill),
status: 'disabled',
retiredAt: at.toISOString(),
retiredReason: 'stale',
};
await tx.put('skill', next);
retired.push(next);
}
return retired;
});
}
/**
* Every run that succeeded is looked at once, oldest first, one at a time; a failed look is tried
* again a few times. Runs only where the deployment's Claude account serves its tenant.
@ -410,6 +846,28 @@ export class Skills {
timer.unref();
return () => clearInterval(timer);
}
/** Counts finished runs and retires stale skills for every tenant this deployment serves. */
startMaintenance(intervalMs = 10 * 60_000) {
const tenants = [
...new Set([...(this.env.WF_TENANT_ID ? [this.env.WF_TENANT_ID] : []), ...dispatchTenants(this.env)]),
];
if (!tenants.length) return () => undefined;
let busy = false;
const tick = async () => {
if (busy) return;
busy = true;
try {
for (const tenantId of tenants) await this.maintain(tenantId);
} catch (error) {
console.error(`[skills] ${error instanceof Error ? error.message : 'maintenance failed'}`);
} finally {
busy = false;
}
};
const timer = setInterval(() => void tick(), intervalMs);
timer.unref();
return () => clearInterval(timer);
}
/** Whoever may wish for the project may shape the skills its later wishes follow. */
private authorize(actor: Actor, project: Project) {
requireHuman(actor);

View File

@ -35,7 +35,6 @@ import { Authenticator, localUser } from './auth.js';
import { ControlPlane, must, projectAccess, record, touch } from './domain/control-plane.js';
import { Releases } from './domain/releases.js';
import { AgentBundles } from './domain/agent-bundles.js';
import { Lessons } from './domain/lessons.js';
import { Skills } from './domain/skills.js';
import { WishReports } from './domain/wish-report.js';
import { Connections } from './domain/connections.js';
@ -58,7 +57,6 @@ export class Services {
auth: Authenticator;
releases: Releases;
bundles: AgentBundles;
lessons: Lessons;
skills: Skills;
reports: WishReports;
connections: Connections;
@ -71,7 +69,6 @@ export class Services {
this.auth = new Authenticator(control.store, control.env);
this.releases = new Releases(control.store, control.env);
this.bundles = new AgentBundles(control.store);
this.lessons = new Lessons(control.store);
this.skills = new Skills(control.store, control.env);
this.reports = new WishReports(control.store);
this.connections = new Connections(control.store, control.env);
@ -311,6 +308,7 @@ export class ApiController {
codeReview: codeReviewPolicyInput.nullable().optional(),
wishRules: wishRulesInput.optional(),
models: projectModelsInput.nullable().optional(),
skillAutoActivation: z.boolean().optional(),
deliveryConfig: z
.object({
imageRepository: z.string().min(1),
@ -350,24 +348,33 @@ export class ApiController {
}),
);
}
@Get('projects/:id/lessons') async lessons(@Req() r: AuthRequest, @Param('id') id: string) {
return ok(await this.s.lessons.list(r.actor, id));
}
@Post('projects/:id/lessons') async createLesson(@Req() r: AuthRequest, @Param('id') id: string, @Body() b: unknown) {
return ok(await this.s.lessons.create(r.actor, id, b));
}
@Patch('lessons/:id') async updateLesson(@Req() r: AuthRequest, @Param('id') id: string, @Body() b: unknown) {
return ok(await this.s.lessons.setStatus(r.actor, id, b));
}
@Delete('lessons/:id') async deleteLesson(@Req() r: AuthRequest, @Param('id') id: string) {
return ok(await this.s.lessons.remove(r.actor, id));
}
@Get('projects/:id/skills') async skills(@Req() r: AuthRequest, @Param('id') id: string) {
return ok(await this.s.skills.list(r.actor, id));
}
@Post('projects/:id/skills') async createSkill(@Req() r: AuthRequest, @Param('id') id: string, @Body() b: unknown) {
return ok(await this.s.skills.create(r.actor, id, b));
}
/** SKILL.md files, or a zip of them as the export writes it, added to the project. */
@Post('projects/:id/skills/import') async importSkills(
@Req() r: AuthRequest,
@Param('id') id: string,
@Body() b: unknown,
) {
return ok(await this.s.skills.importFiles(r.actor, id, b, key(r)));
}
/** The knowledge base: skills of every project the person may see. */
@Get('skills') async allSkills(
@Req() r: AuthRequest,
@Query('project') projectId?: string,
@Query('status') status?: string,
@Query('category') category?: string,
@Query('q') q?: string,
) {
return ok(await this.s.skills.search(r.actor, { projectId, status, category, q }));
}
@Post('skills/copy') async copySkills(@Req() r: AuthRequest, @Body() b: unknown) {
return ok(await this.s.skills.copy(r.actor, b, key(r)));
}
/** Every active skill (and with ?proposed=1 the proposals) as a zip, one directory per skill. */
@Get('projects/:id/skills/export') async exportSkills(
@Req() r: AuthRequest,

View File

@ -37,6 +37,8 @@ export async function bootstrap() {
const service = new Services(new ControlPlane(store));
// Succeeded runs are looked at for skills worth keeping, one at a time, in the background.
service.skills.startHarvesting();
// Finished runs count for the skills they were given; skills that keep failing or go unused retire.
service.skills.startMaintenance();
const telemetry = await observability();
@Module({
controllers: [ApiController, InternalController, WorkspaceLifecycleController, WorkspaceLaunchController],

View File

@ -49,8 +49,7 @@ export interface RunContext {
verificationProfileDigest?: string;
verificationProfileRequired?: boolean;
bundleConfig?: AgentBundleConfig;
lessons?: string[];
/** The project's active skills, most recently changed first. */
/** The project's active skills (workflows, pitfalls, conventions), most recently changed first. */
skills?: PromptSkill[];
delivery?: {
release?: { id: string; status: string };

View File

@ -342,7 +342,6 @@ export async function executeRun(config: WorkerConfig, input: RunInput): Promise
acceptanceCriteria: run.acceptanceCriteria,
repairCount: run.repairCount,
lastFailure,
lessons: context.lessons,
skills: context.skills,
sourceBranch: run.sourceBranch,
...(revert ? { revert } : {}),

View File

@ -6,13 +6,14 @@ export const QUESTIONS_MARKER = 'QUESTIONS:';
export const QUESTION_LIMIT = 5;
const QUESTION_MAX_LENGTH = 300;
/** At most this many lessons, and this many characters of them, enter a prompt. */
export const LESSON_LIMIT = 5;
export const LESSON_CHARS = 4096;
/** The longest account of one repaired failure a pitfall skill records. */
export const LESSON_MAX_LENGTH = 1000;
/** At most this many skills, and this many characters of them, enter a prompt. */
export const SKILL_LIMIT = 8;
export const SKILL_CHARS = 16000;
/**
* At most this many skills, and this many characters of them, enter a prompt; pitfalls and
* conventions (once lessons) share the budget with workflows.
*/
export const SKILL_LIMIT = 12;
export const SKILL_CHARS = 20000;
/** A project skill as a prompt carries it. */
export interface PromptSkill {
@ -27,8 +28,6 @@ export interface PromptInput {
repairCount: number;
/** The failure this repair round must fix. */
lastFailure?: FailureSummary;
/** Active project lessons, most recent first. */
lessons?: string[];
/** Active project skills, most recently changed first. */
skills?: PromptSkill[];
/** The branch the workspace started from instead of the target branch. */
@ -45,21 +44,9 @@ export interface PromptInput {
frontendOnly?: { backend: string[]; except: string[] };
}
/** Keeps the most recent lessons that fit the count and size limits. */
export function selectLessons(summaries: string[]): string[] {
const chosen: string[] = [];
let used = 0;
for (const summary of summaries.slice(0, LESSON_LIMIT)) {
if (used + summary.length > LESSON_CHARS) break;
chosen.push(summary);
used += summary.length;
}
return chosen;
}
/** Keeps the most recently changed skills that fit the count and size limits. */
export function selectSkills(skills: PromptSkill[]): PromptSkill[] {
const chosen: PromptSkill[] = [];
export function selectSkills<T extends PromptSkill>(skills: T[]): T[] {
const chosen: T[] = [];
let used = 0;
for (const skill of skills.slice(0, SKILL_LIMIT)) {
const size = skill.name.length + skill.description.length + skill.content.length;
@ -135,15 +122,11 @@ export function bundlePrompt(config: AgentBundleConfig, input: PromptInput) {
]
.filter(Boolean)
.join('\n\n');
const lessons = selectLessons(input.lessons ?? []);
const skills = selectSkills(input.skills ?? []);
return [
instructions,
input.goal,
`Acceptance criteria:\n${input.acceptanceCriteria.map((criterion, i) => `${i + 1}. ${criterion}`).join('\n')}`,
lessons.length
? `Lessons from earlier work on this project (apply them when relevant):\n${lessons.map(lesson => `- ${lesson}`).join('\n')}`
: '',
skills.length ? skillsSection(skills) : '',
input.sourceBranch
? `The workspace starts from branch ${input.sourceBranch}, which holds changes people made themselves (for example in the IDE). Keep those changes and build on them; this run verifies and merges them into the target branch together with your work.`
@ -196,7 +179,7 @@ function failureLine(output: string) {
return line ? singleLine(line).slice(0, 300) : 'no output';
}
/** A lesson learned when a repair round turned a recorded failure into a pass. */
/** What a repair round that turned a recorded failure into a pass teaches: one entry of a pitfall skill. */
export function repairLesson(failure: FailureSummary, summary?: string): string {
const trigger =
failure.kind === 'integration_conflict'

View File

@ -1,14 +1,5 @@
import { describe, expect, it } from 'vitest';
import {
BASELINE_BUNDLE,
LESSON_CHARS,
LESSON_LIMIT,
LESSON_MAX_LENGTH,
bundlePrompt,
questionsIn,
repairLesson,
selectLessons,
} from '../src/index.js';
import { BASELINE_BUNDLE, LESSON_MAX_LENGTH, bundlePrompt, questionsIn, repairLesson } from '../src/index.js';
const failure = {
kind: 'verification' as const,
@ -123,21 +114,6 @@ describe('agent prompt', () => {
'A frontend-only wish changed backend files go.mod server/main.go. What fixed it: Moved the style into src/',
);
});
it('injects at most the configured number and size of lessons', () => {
const lessons = Array.from({ length: 8 }, (_, i) => `lesson ${i}`);
const prompt = bundlePrompt(BASELINE_BUNDLE, {
goal: 'Goal',
acceptanceCriteria: ['Criterion'],
repairCount: 0,
lessons,
});
expect(prompt).toContain('- lesson 0');
expect(prompt).toContain(`- lesson ${LESSON_LIMIT - 1}`);
expect(prompt).not.toContain(`- lesson ${LESSON_LIMIT}`);
const large = selectLessons(['x'.repeat(LESSON_CHARS - 10), 'y'.repeat(20), 'z']);
expect(large).toHaveLength(1);
});
it('turns a repaired failure into a bounded lesson', () => {
const lesson = repairLesson(failure, 'Built the project before running the tests.\nAdded a missing fixture.');
expect(lesson).toContain('`npm test` failed (exit code 1): FAIL b.test.ts');

View File

@ -57,7 +57,6 @@ export type EntityKind =
| 'workspace'
| 'provider_connection'
| 'bundle'
| 'lesson'
| 'runner_task'
| 'runner'
| 'policy'
@ -69,7 +68,8 @@ export type EntityKind =
| 'local_account'
| 'notification'
| 'skill'
| 'skill_harvest';
| 'skill_harvest'
| 'skill_usage';
export interface Entity {
id: string;
tenantId: string;
@ -123,6 +123,11 @@ export interface Project extends Entity {
wishRules?: string;
/** Models a wish of this project may run with; flash when offered, else the first; absent: the executor's default. */
models?: string[];
/**
* Whether the platform activates the skills it learns once they are corroborated: a pitfall
* from a repaired failure, or a proposal seen in two succeeded runs. Absent: on.
*/
skillAutoActivation?: boolean;
}
/** A run that takes back what another run integrated into the target branch. */
export interface RevertSource {
@ -264,11 +269,14 @@ export interface FailureSummary {
/** For a conflict: the target-branch commit the repair round must merge. */
targetCommit?: string;
}
/** Knowledge reused by later runs of the same project (docs/requirements.md FR-I2). */
/** What a skill is: a way of working, a known pitfall and its fix, or a project convention. */
export const skillCategories = ['workflow', 'pitfall', 'convention'] as const;
export type SkillCategory = (typeof skillCategories)[number];
/**
* Know-how a project's later wishes can reuse: when it applies and how to do it. The platform
* proposes skills from finished runs; people confirm, edit and export them. Active skills enter
* the prompts of the project's later runs.
* Know-how a project's later wishes can reuse: when it applies and how to do it (docs/requirements.md
* FR-I2). The platform proposes skills from finished runs and records pitfalls from repaired
* failures; people confirm, edit, copy, import and export them. Active skills enter the prompts of
* the project's later runs.
*/
export interface Skill extends Entity {
projectId: string;
@ -278,13 +286,27 @@ export interface Skill extends Entity {
description: string;
/** How to do it, in Markdown. */
content: string;
/** Absent: `workflow` (skills stored before categories existed). */
category?: SkillCategory;
/** `proposed`: suggested by the platform, waiting for a person; only `active` skills are used. */
status: 'proposed' | 'active' | 'disabled';
/** The runs it was learned from. */
/** The runs it was learned from, oldest first. */
sourceRunIds: string[];
/** `wishforge` for proposals, else the person who wrote it. */
/** For a pitfall: the failure it is about, so the same failure in later runs updates it. */
signature?: string;
/** `wishforge` for what the platform learned, else the person who wrote it. */
createdBy: string;
updatedBy?: string;
/** How often runs were given the skill, and how the settled ones ended. */
useCount?: number;
successCount?: number;
failureCount?: number;
/** Settled runs that used it and failed since the last one that succeeded. */
failureStreak?: number;
lastUsedAt?: string;
/** Set when the platform disabled it: its runs kept failing, or it went unused too long. */
retiredAt?: string;
retiredReason?: 'failing' | 'stale';
}
/** Whether the platform has looked for skills in a finished run; its id is the run's. */
export interface SkillHarvest extends Entity {
@ -295,13 +317,13 @@ export interface SkillHarvest extends Entity {
skillIds: string[];
error?: string;
}
export interface Lesson extends Entity {
/** Which skills a run's prompts carried, and whether that run's outcome was counted; its id is the run's. */
export interface SkillUsage extends Entity {
runId: string;
projectId: string;
kind: 'repair' | 'convention';
summary: string;
sourceRunId?: string;
status: 'active' | 'disabled';
createdBy: string;
skillIds: string[];
/** Set once the run ended and the skills' counts include it; `neutral` counts for neither. */
outcome?: 'succeeded' | 'failed' | 'neutral';
}
export interface RunEvent {
id: string;
@ -497,7 +519,6 @@ export const projectInput = z
installCommands: commandList.default([]),
})
.strict();
export const lessonInput = z.object({ summary: text.max(1000) }).strict();
export const skillName = z
.string()
.trim()
@ -505,13 +526,19 @@ export const skillName = z
.max(64);
export const SKILL_CONTENT_LIMIT = 20000;
export const skillInput = z
.object({ name: skillName, description: text.max(500), content: text.max(SKILL_CONTENT_LIMIT) })
.object({
name: skillName,
description: text.max(500),
content: text.max(SKILL_CONTENT_LIMIT),
category: z.enum(skillCategories).default('workflow'),
})
.strict();
export const skillUpdateInput = z
.object({
name: skillName.optional(),
description: text.max(500).optional(),
content: text.max(SKILL_CONTENT_LIMIT).optional(),
category: z.enum(skillCategories).optional(),
status: z.enum(['active', 'disabled']).optional(),
})
.strict()

View File

@ -40,6 +40,7 @@ export const PROJECT_KINDS = [
'bundle',
'skill',
'skill_harvest',
'skill_usage',
];
/** Where the containers keep POC state; a rehearsal of this script names another directory. */
const POC_STATE = process.env.WF_CLUSTER_POC_STATE ?? '/var/lib/wishforge/poc-state';

View File

@ -1,6 +1,6 @@
/**
* The main loop end to end with real Git: wish → executor → independent verification
* → repair with failure feedback → integration → success, plus lessons and merge
* → repair with failure feedback → integration → success, plus pitfall skills and merge
* conflicts, and a change pushed from the IDE workspace. The control plane runs in process
* behind its real internal routes; only the agent is scripted.
*/
@ -21,11 +21,11 @@ import {
type CheckpointRecord,
type Environment,
type Evidence,
type Lesson,
type Project,
type Release,
type Role,
type Run,
type Skill,
} from '@wishforge/contracts';
import { executeCommand, type CommandExecutor, type HostCheckSandbox, type ProviderStart } from '@wishforge/runtime';
import { ManagedProvider } from '../packages/runtime/src/providers/base.js';
@ -471,18 +471,24 @@ describe('local main loop', () => {
expect(await drive(session)).toEqual({ status: 'complete' });
await release(runId, session.generation);
// The background harvest looks at the run once; the model proposes two skills, one named
// like a skill the project has.
// The background harvest looks at the run once; the model proposes a new skill, an update
// of one the project has, and one it cannot use.
const asked: string[] = [];
const skills = new Skills(store, { ...env, WF_TENANT_ID: TENANT }, async input => {
asked.push(input.prompt);
return {
skills: [
{
name: 'greeting-check',
name: 'greeting-check-flow',
description: 'When changing greeting.txt',
content: '1. Edit greeting.txt.\n2. Run `node check.mjs`.',
},
{
name: 'greeting-check',
updates: 'greeting-check',
description: 'An older skill',
content: 'Keep greetings lowercase, and run node check.mjs.',
},
{ name: 'Not A Name', description: 'x', content: 'y' },
],
};
@ -497,13 +503,25 @@ describe('local main loop', () => {
expect(JSON.parse(asked[0]!)).toMatchObject({
goal: 'Make the greeting say hello world',
changedFiles: ['greeting.txt'],
existingSkills: [{ name: 'greeting-check' }],
});
// The harvest sees every skill, the pitfall from the repair included.
expect(
JSON.parse(asked[0]!)
.existingSkills.map((skill: { name: string; category: string }) => `${skill.category}:${skill.name}`)
.sort(),
).toEqual(['pitfall:pitfall-node-check-mjs', 'workflow:greeting-check']);
const listed = await skills.list(owner, project.id);
const proposed = listed.find(skill => skill.status === 'proposed')!;
expect(listed).toHaveLength(2);
expect(proposed).toMatchObject({ name: 'greeting-check-2', createdBy: 'wishforge', sourceRunIds: [runId] });
expect((await services.control.events(owner, runId)).map(event => event.type)).toContain('skill.proposed');
expect(listed).toHaveLength(3);
expect(proposed).toMatchObject({ name: 'greeting-check-flow', createdBy: 'wishforge', sourceRunIds: [runId] });
// A person's skill keeps what it says; it records the run that confirmed it.
expect(listed.find(skill => skill.name === 'greeting-check')).toMatchObject({
content: 'Keep greetings lowercase.',
sourceRunIds: [runId],
});
expect((await services.control.events(owner, runId)).map(event => event.type)).toEqual(
expect.arrayContaining(['skill.activated', 'skill.proposed', 'skill.updated']),
);
// Someone who may not wish for the project may not shape its skills; anyone who may can.
const viewer = await person(project.id, 'li', { wish: 'none', manage: false, releases: false, reviewCode: false });
@ -525,20 +543,29 @@ describe('local main loop', () => {
return writeGreeting('hello world', 'Nothing to change.')(start);
});
await second.executor.executeRun(second.input);
expect(prompt).toContain('### greeting-check-2');
expect(prompt).toContain('### greeting-check-flow');
expect(prompt).toContain('Edit greeting.txt, then run node check.mjs.');
expect(prompt).toContain('### greeting-check');
// Exports: one SKILL.md, or a zip with a directory per active skill.
const one = await skills.exportOne(owner, proposed.id);
expect(one.content).toMatch(/^---\nname: greeting-check-2\ndescription: "When changing greeting.txt"\n---\n\nEdit/);
expect(one.content).toMatch(
/^---\nname: greeting-check-flow\ndescription: "When changing greeting.txt"\n---\n\nEdit/,
);
const zip = await skills.exportAll(owner, project.id);
expect(zip.content.subarray(0, 4).toString('hex')).toBe('504b0304');
const unzipped = path.join(root, 'skills.zip');
await writeFile(unzipped, zip.content);
const listing = await run('unzip', ['-Z1', unzipped]).then(result => result.stdout.trim().split('\n'));
expect(listing.sort()).toEqual(['greeting-check-2/SKILL.md', 'greeting-check/SKILL.md']);
expect((await run('unzip', ['-p', unzipped, 'greeting-check-2/SKILL.md'])).stdout).toBe(one.content);
expect(listing.sort()).toEqual([
'greeting-check-flow/SKILL.md',
'greeting-check/SKILL.md',
'pitfall-node-check-mjs/SKILL.md',
]);
expect((await run('unzip', ['-p', unzipped, 'greeting-check-flow/SKILL.md'])).stdout).toBe(one.content);
expect((await run('unzip', ['-p', unzipped, 'pitfall-node-check-mjs/SKILL.md'])).stdout).toContain(
'wishforge-category: pitfall',
);
// The wish's report carries every stage, the agent's work, the change and the checks.
const report = await new WishReports(store).markdown(owner, (await services.control.run(owner, runId)).wishId);
@ -604,27 +631,42 @@ describe('local main loop', () => {
expect(events.find(e => e.type === 'provider.output')?.message).toContain('Updated the greeting');
expect(events.find(e => e.type === 'provider.command')?.message).toBe('$ node edit.mjs (exit 0)');
// The repair became a project lesson that the next run is told about (FR-I2).
const lessons = await services.lessons.list(owner, project.id);
expect(lessons).toHaveLength(1);
expect(lessons[0]).toMatchObject({ kind: 'repair', status: 'active', sourceRunId: runId });
expect(lessons[0]!.summary).toContain('check.mjs');
expect(lessons[0]!.summary).toContain('Fixed the typo');
// The repair became an active pitfall skill that the next run is told about (FR-I2).
const skills = await services.skills.list(owner, project.id);
expect(skills).toHaveLength(1);
const pitfall = skills[0]!;
expect(pitfall).toMatchObject({
name: 'pitfall-node-check-mjs',
category: 'pitfall',
status: 'active',
sourceRunIds: [runId],
createdBy: 'wishforge',
});
expect(pitfall.content).toContain('check.mjs');
expect(pitfall.content).toContain('Fixed the typo');
expect((await services.control.events(owner, runId)).map(event => event.type)).toContain('skill.activated');
await release(runId, session.generation);
const next = await submit(project.id, 'Make the greeting say hello world again', 'wish-lesson-0002');
const second = await provision(next, writeGreeting('hello world!', 'Added an exclamation mark.'));
expect(await drive(second)).toEqual({ status: 'complete' });
expect(prompts[2]).toContain('Lessons from earlier work on this project');
expect(prompts[2]).toContain(lessons[0]!.summary);
expect(prompts[2]).toContain('### pitfall-node-check-mjs');
expect(prompts[2]).toContain('Fixed the typo');
expect(prompts[2]).not.toContain('Lessons from earlier work');
await release(next, second.generation);
// The run that was given it succeeded: the skill counts it.
expect((await services.skills.list(owner, project.id))[0]).toMatchObject({
useCount: 1,
successCount: 1,
failureStreak: 0,
});
// A disabled lesson is no longer injected.
await services.lessons.setStatus(owner, lessons[0]!.id, { status: 'disabled' });
// A disabled skill is no longer injected.
await services.skills.update(owner, pitfall.id, { status: 'disabled' });
const third = await submit(project.id, 'Keep the greeting', 'wish-lesson-0003');
const thirdSession = await provision(third, writeGreeting('hello world!!', 'More emphasis.'));
expect(await drive(thirdSession)).toEqual({ status: 'complete' });
expect(prompts[3]).not.toContain('Lessons from earlier work');
expect(prompts[3]).not.toContain('pitfall-node-check-mjs');
});
it('waits instead of repairing when the repair budget is used up, and continues on request', async () => {
@ -685,8 +727,9 @@ describe('local main loop', () => {
// The resolved change contains A's commit; nothing was overwritten (FR-F1).
const integratedA = (await services.control.run(owner, first)).integratedCommit!;
await git(remote, 'merge-base', '--is-ancestor', integratedA, 'main');
const lessons: Lesson[] = await services.lessons.list(owner, project.id);
expect(lessons[0]?.summary).toContain('Merging into the target branch conflicted in greeting.txt');
const pitfalls: Skill[] = await services.skills.list(owner, project.id);
expect(pitfalls[0]).toMatchObject({ category: 'pitfall', name: 'pitfall-merge-conflict-greeting-txt' });
expect(pitfalls[0]?.content).toContain('Merging into the target branch conflicted in greeting.txt');
});
it('merges a change onto a target that moved meanwhile, and checks the merge', async () => {
@ -1132,10 +1175,12 @@ describe('local main loop', () => {
expect((await evidenceOf(runId)).find(evidence => evidence.installFailure)?.changedManifests).toEqual([
'package.json',
]);
const lessons = await store.transaction(TENANT, tx => tx.list<Lesson>('lesson', { projectId: project.id }));
expect(lessons.map(lesson => lesson.summary)).toEqual([
expect.stringMatching(/^Installing dependencies with `.+` failed \(exit code 1\): .*left-pad-typo/),
]);
const pitfalls = await store.transaction(TENANT, tx => tx.list<Skill>('skill', { projectId: project.id }));
expect(pitfalls).toHaveLength(1);
expect(pitfalls[0]).toMatchObject({ category: 'pitfall', status: 'active' });
expect(pitfalls[0]!.content).toMatch(
/\n- Installing dependencies with `.+` failed \(exit code 1\): .*left-pad-typo/,
);
// The same manifest change failing on the network is the environment's: no repair round is spent.
const second = await submit(project.id, 'Greet again', 'wish-install-0002');

View File

@ -31,6 +31,12 @@ describe('versioned database migrations (requirements FR-K2)', () => {
expect(new Set(versions.map(v => v.slice(0, 3))).size).toBe(versions.length);
// Data migrations must not run silently restricted by row-level security.
expect(migrations[1]!.sql).toContain('SET LOCAL row_security = off');
// Lessons became skills: every lesson row is converted, keeping its id, then removed.
const lessons = migrations.find(m => m.version === '004_lessons_to_skills')!;
expect(lessons.sql).toContain('SET LOCAL row_security = off');
expect(lessons.sql).toContain("WHERE l.kind = 'lesson'");
expect(lessons.sql).toContain('ON CONFLICT (tenant_id, kind, id) DO NOTHING');
expect(lessons.sql).toContain("DELETE FROM entities WHERE kind = 'lesson'");
});
it('applies only what has not run, in order, and never repeats a migration', async () => {
const db = database();

473
tests/skills.test.ts Normal file
View File

@ -0,0 +1,473 @@
/**
* Project skills as the one home of a project's know-how (requirements FR-I2): pitfalls learned
* from repaired failures, harvested proposals merged and activated, effectiveness counted and
* retired, and skills moved between projects as SKILL.md files, zips or copies.
*/
import { describe, expect, it } from 'vitest';
import { crc32, deflateRawSync } from 'node:zlib';
import type { Actor, FailureSummary, Project, Run, Skill } from '@wishforge/contracts';
import {
RETIRE_AFTER_FAILURES,
RETIRE_UNUSED_DAYS,
Skills,
failureSignature,
learnFromRun,
projectSkills,
recordSkillUse,
settleSkillUsage,
} from '../apps/api/src/domain/skills.js';
import { parseSkillMarkdown, readSkillArchive, skillMarkdown, zipFiles } from '../apps/api/src/domain/skill-files.js';
import { MemoryStore } from './helpers/memory-store.js';
const TENANT = 'demo';
const owner: Actor = { tenantId: TENANT, userId: 'owner', role: 'owner', kind: 'human' };
const viewer: Actor = { tenantId: TENANT, userId: 'viewer', role: 'viewer', kind: 'human' };
const stamp = (id: string) => {
const time = new Date().toISOString();
return { id, tenantId: TENANT, version: 1, createdAt: time, updatedAt: time };
};
const failure = (argv = ['npm', 'test'], tail = 'Error: expected 2 to equal 3'): FailureSummary => ({
kind: 'verification',
evidenceId: 'evidence',
sourceCommit: 'a'.repeat(40),
argv,
exitCode: 1,
outputTail: tail,
});
function setup() {
const store = new MemoryStore();
store.seed(TENANT);
const answers: unknown[] = [];
const asked: string[] = [];
const skills = new Skills(store, { WF_TENANT_ID: TENANT } as NodeJS.ProcessEnv, async input => {
asked.push(input.prompt);
return answers.shift() ?? { skills: [] };
});
const project = async (id: string, extra: Partial<Project> = {}) => {
const value = {
...stamp(id),
name: `Project ${id}`,
repositoryStorage: 'platform',
repositoryStatus: 'ready',
targetBranch: 'main',
memberIds: ['viewer'],
verificationCommands: [],
autoDeploy: false,
...extra,
} as Project;
await store.transaction(TENANT, tx => tx.put('project', value));
return value;
};
const run = async (id: string, projectId: string, extra: Partial<Run> = {}) => {
const value = {
...stamp(id),
projectId,
wishId: `wish-${id}`,
goal: 'Change the greeting',
acceptanceCriteria: ['check passes'],
status: 'running',
stage: 'implement',
repairCount: 0,
...extra,
} as unknown as Run;
await store.transaction(TENANT, tx => tx.put('run', value));
return value;
};
/** The run ends: its status changes and, for a success, the control plane learns from it. */
const finish = (value: Run, status: Run['status'], extra: Partial<Run> = {}) =>
store.transaction(TENANT, async tx => {
const next = { ...value, ...extra, status };
await tx.put('run', next);
if (status === 'succeeded') await learnFromRun(tx, next);
return next;
});
const use = (value: Run) => store.transaction(TENANT, tx => recordSkillUse(tx, value));
const all = (projectId: string) => skills.list(owner, projectId);
return { store, skills, answers, asked, project, run, finish, use, all };
}
describe('pitfall skills from repaired failures', () => {
it('turns the same failure in several runs into one pitfall, active right away', async () => {
const { project, run, finish, all, store } = setup();
await project('p1');
const first = await run('r1', 'p1');
await finish(first, 'succeeded', {
repairCount: 1,
lastFailure: failure(),
implementationSummary: 'Built before testing.',
});
const second = await run('r2', 'p1');
await finish(second, 'succeeded', {
repairCount: 1,
lastFailure: failure(['npm', ' test'], 'FAIL other.test.ts'),
implementationSummary: 'Added a fixture.',
});
// Learning from the same run again changes nothing.
await finish(second, 'succeeded', { repairCount: 1, lastFailure: failure(), implementationSummary: 'x' });
const skills = await all('p1');
expect(skills).toHaveLength(1);
const pitfall = skills[0]!;
expect(pitfall).toMatchObject({
name: 'pitfall-npm-test',
category: 'pitfall',
status: 'active',
signature: 'verification:npm test',
sourceRunIds: ['r1', 'r2'],
createdBy: 'wishforge',
});
// Most recent first.
expect(pitfall.content.indexOf('Added a fixture')).toBeLessThan(pitfall.content.indexOf('Built before testing'));
const events = await store.read(TENANT, tx => tx.events('r2'));
expect(events.map(event => event.type)).toEqual(['skill.updated']);
// A different command is a different pitfall; a conflict is identified by its files.
expect(failureSignature(failure(['npm', 'run', 'lint']))).toBe('verification:npm run lint');
expect(
failureSignature({ ...failure(), kind: 'integration_conflict', argv: undefined, outputTail: 'b.ts\na.ts' }),
).toBe('integration_conflict:a.ts b.ts');
});
it('waits for a person where the project does not activate skills itself, and is not shown before', async () => {
const { project, run, finish, all, store } = setup();
await project('p1', { skillAutoActivation: false });
await finish(await run('r1', 'p1'), 'succeeded', { repairCount: 1, lastFailure: failure() });
expect((await all('p1'))[0]).toMatchObject({ status: 'proposed', category: 'pitfall' });
expect(await store.read(TENANT, tx => projectSkills(tx, 'p1'))).toEqual([]);
// A run that needed no repair teaches nothing.
await finish(await run('r2', 'p1'), 'succeeded');
expect(await all('p1')).toHaveLength(1);
});
});
describe('harvested skills', () => {
it('merges a proposal into the skill it updates, and activates one two succeeded runs proposed', async () => {
const { project, run, skills, answers, asked, all } = setup();
await project('p1');
await run('r1', 'p1', { status: 'succeeded' });
await run('r2', 'p1', { status: 'succeeded' });
const written = await skills.create(owner, 'p1', {
name: 'house-style',
description: 'Any change',
content: 'Use tabs.',
category: 'convention',
});
answers.push({
skills: [
{ name: 'add-page', description: 'When adding a page', content: 'Register it in routes.ts.' },
{ name: 'house-style', updates: 'house-style', description: 'Any change', content: 'Use spaces.' },
],
});
expect((await skills.harvest(TENANT, 'r1')).map(skill => skill.name).sort()).toEqual(['add-page', 'house-style']);
expect(JSON.parse(asked[0]!).existingSkills).toEqual([
expect.objectContaining({ name: 'house-style', category: 'convention', status: 'active' }),
]);
let listed = await all('p1');
expect(listed.find(skill => skill.name === 'add-page')).toMatchObject({ status: 'proposed', sourceRunIds: ['r1'] });
// A person's skill keeps its words.
expect(listed.find(skill => skill.id === written.id)).toMatchObject({ content: 'Use tabs.', sourceRunIds: ['r1'] });
// A second succeeded run proposes the same skill again (by name): it is rewritten and activated.
answers.push({
skills: [
{ name: 'add-page', description: 'When adding a page', content: 'Register it in routes.ts; add a test.' },
],
});
await skills.harvest(TENANT, 'r2');
listed = await all('p1');
expect(listed.filter(skill => skill.name.startsWith('add-page'))).toEqual([
expect.objectContaining({
status: 'active',
content: 'Register it in routes.ts; add a test.',
sourceRunIds: ['r1', 'r2'],
}),
]);
});
it('leaves corroborated proposals for a person where the project says so', async () => {
const { project, run, skills, answers, all } = setup();
await project('p1', { skillAutoActivation: false });
for (const id of ['r1', 'r2']) {
await run(id, 'p1', { status: 'succeeded' });
answers.push({ skills: [{ name: 'add-page', description: 'When adding a page', content: `Do it (${id}).` }] });
await skills.harvest(TENANT, id);
}
expect(await all('p1')).toEqual([
expect.objectContaining({ status: 'proposed', content: 'Do it (r2).', sourceRunIds: ['r1', 'r2'] }),
]);
});
});
describe('how well skills work', () => {
it('counts the runs given a skill and retires a platform skill whose runs keep failing', async () => {
const { project, run, finish, use, all, store, skills } = setup();
await project('p1');
await finish(await run('r0', 'p1'), 'succeeded', { repairCount: 1, lastFailure: failure() });
const mine = await skills.create(owner, 'p1', { name: 'mine', description: 'Always', content: 'Be careful.' });
const good = await run('good', 'p1');
await use(good);
await use(good); // a repair round does not count twice
await finish(good, 'succeeded');
let [pitfall, written] = [
(await all('p1')).find(skill => skill.category === 'pitfall')!,
(await all('p1')).find(skill => skill.id === mine.id)!,
];
expect(pitfall).toMatchObject({ useCount: 1, successCount: 1, failureStreak: 0 });
expect(written).toMatchObject({ useCount: 1, successCount: 1 });
// Canceled without a failed check: neither success nor failure.
const changedMind = await run('cancel', 'p1');
await use(changedMind);
await store.transaction(TENANT, async tx => {
await tx.put('run', { ...changedMind, status: 'canceled' });
await settleSkillUsage(tx, { ...changedMind, status: 'canceled' });
});
for (let n = 1; n <= RETIRE_AFTER_FAILURES; n++) {
const failing = await run(`fail-${n}`, 'p1', { repairCount: 2 });
await use(failing);
await store.transaction(TENANT, tx => tx.put('run', { ...failing, status: 'canceled' }));
}
// Failures are found by the background maintenance.
await skills.maintain(TENANT);
[pitfall, written] = [
(await all('p1')).find(skill => skill.category === 'pitfall')!,
(await all('p1')).find(skill => skill.id === mine.id)!,
];
expect(pitfall).toMatchObject({
status: 'disabled',
retiredReason: 'failing',
useCount: 2 + RETIRE_AFTER_FAILURES,
failureCount: RETIRE_AFTER_FAILURES,
});
// A person's skill is only flagged by its counts; theirs to decide.
expect(written).toMatchObject({ status: 'active', failureStreak: RETIRE_AFTER_FAILURES });
const retiredOn = await store.read(TENANT, tx => tx.events(`fail-${RETIRE_AFTER_FAILURES}`));
expect(retiredOn.map(event => event.type)).toEqual(['skill.retired']);
// Enabling it again starts afresh.
const again = await skills.update(owner, pitfall.id, { status: 'active' });
expect(again).toMatchObject({ status: 'active', failureStreak: 0 });
expect(again.retiredReason).toBeUndefined();
expect(again.updatedBy).toBeUndefined();
});
it('retires a platform skill no run was given for a long time while its project kept running', async () => {
const { project, run, finish, all, skills, store } = setup();
await project('p1');
await finish(await run('r0', 'p1'), 'succeeded', { repairCount: 1, lastFailure: failure() });
// Long ago it was used; today's run has only newer skills in its prompt.
const old = new Date(Date.now() - (RETIRE_UNUSED_DAYS + 1) * 86_400_000).toISOString();
await store.transaction(TENANT, async tx => {
const [skill] = await tx.list<Skill>('skill', { projectId: 'p1' });
await tx.put('skill', { ...skill!, lastUsedAt: old, updatedAt: old });
await tx.put('skill', {
...stamp('fresh'),
projectId: 'p1',
name: 'fresh',
description: 'd',
content: 'c',
status: 'active',
sourceRunIds: [],
createdBy: 'owner',
} as Skill);
});
// A project that did not run keeps its skills.
expect(await skills.maintain(TENANT)).toEqual([]);
const today = await run('today', 'p1');
await store.transaction(TENANT, tx =>
tx.put('skill_usage', { ...stamp('today'), runId: today.id, projectId: 'p1', skillIds: ['fresh'] }),
);
const retired = await skills.maintain(TENANT);
expect(retired.map(skill => skill.category)).toEqual(['pitfall']);
expect((await all('p1')).find(skill => skill.category === 'pitfall')).toMatchObject({
status: 'disabled',
retiredReason: 'stale',
});
});
});
/** A zip whose entries are deflated, as zip tools write them. */
function deflatedZip(files: { path: string; content: string }[]) {
const locals: Buffer[] = [];
const centrals: Buffer[] = [];
let offset = 0;
for (const file of files) {
const name = Buffer.from(file.path);
const data = Buffer.from(file.content);
const packed = deflateRawSync(data);
const local = Buffer.alloc(30);
local.writeUInt32LE(0x04034b50, 0);
local.writeUInt16LE(20, 4);
local.writeUInt16LE(8, 8);
local.writeUInt32LE(crc32(data), 14);
local.writeUInt32LE(packed.length, 18);
local.writeUInt32LE(data.length, 22);
local.writeUInt16LE(name.length, 26);
const central = Buffer.alloc(46);
central.writeUInt32LE(0x02014b50, 0);
central.writeUInt16LE(20, 4);
central.writeUInt16LE(20, 6);
central.writeUInt16LE(8, 10);
central.writeUInt32LE(crc32(data), 16);
central.writeUInt32LE(packed.length, 20);
central.writeUInt32LE(data.length, 24);
central.writeUInt16LE(name.length, 28);
central.writeUInt32LE(offset, 42);
locals.push(local, name, packed);
centrals.push(central, name);
offset += 30 + name.length + packed.length;
}
const directory = Buffer.concat(centrals);
const end = Buffer.alloc(22);
end.writeUInt32LE(0x06054b50, 0);
end.writeUInt16LE(files.length, 8);
end.writeUInt16LE(files.length, 10);
end.writeUInt32LE(directory.length, 12);
end.writeUInt32LE(offset, 16);
return Buffer.concat([...locals, directory, end]);
}
describe('skills as files', () => {
it('reads back what export writes, and SKILL.md written elsewhere', () => {
const skill = {
name: 'pitfall-npm-test',
description: 'Before "npm test"',
content: '- It fails.',
category: 'pitfall' as const,
};
expect(parseSkillMarkdown(skillMarkdown(skill), 'x/SKILL.md')).toEqual({ ...skill, source: 'x/SKILL.md' });
expect(
parseSkillMarkdown(
"---\r\nname: 'Lazy Load'\r\ndescription: >\r\n When a page\r\n is slow\r\nallowed-tools: Read\r\n---\r\n# Steps\r\nDo it.\r\n",
'lazy/SKILL.md',
),
).toMatchObject({
name: 'lazy-load',
description: 'When a page is slow',
content: '# Steps\nDo it.',
category: 'workflow',
});
// No front matter: the name comes from the file, the description from the first line.
expect(parseSkillMarkdown('# Run the e2e suite first\n\nnpm run e2e', 'e2e-first.SKILL.md')).toMatchObject({
name: 'e2e-first',
description: 'Run the e2e suite first',
});
expect(() => parseSkillMarkdown('---\nname: x\n', 'a.md')).toThrow(/not closed/);
expect(() => parseSkillMarkdown('---\nname: x\ndescription: y\n---\n', 'a.md')).toThrow(/no instructions/);
expect(() => parseSkillMarkdown('x'.repeat(70 * 1024), 'big.md')).toThrow(/larger than/);
});
it('reads stored and deflated zips, skipping what is not a skill and refusing what is too large', () => {
const files = [
{ path: 'a/SKILL.md', content: '---\nname: a\ndescription: A\n---\n\nDo A.' },
{ path: 'a/scripts/run.sh', content: 'echo' },
{ path: '__MACOSX/a/._SKILL.md', content: 'junk' },
];
for (const archive of [zipFiles(files), deflatedZip(files)])
expect(readSkillArchive(archive)).toEqual({ files: [files[0]], ignored: 2 });
expect(() => readSkillArchive(Buffer.from('not a zip'))).toThrow(/not a zip/);
expect(() => readSkillArchive(Buffer.alloc(600 * 1024))).toThrow(/larger than/);
const bomb = deflatedZip([{ path: 'b/SKILL.md', content: 'x'.repeat(100 * 1024) }]);
expect(() => readSkillArchive(bomb)).toThrow(/larger than 64 KiB/);
const damaged = zipFiles([files[0]!]);
damaged[40] ^= 0xff; // a byte of the file's content
expect(() => readSkillArchive(damaged)).toThrow(/damaged/);
});
});
describe('moving skills between projects', () => {
it('imports an export into another project once, numbering names a different skill holds', async () => {
const { project, skills, all } = setup();
await project('p1');
await project('p2');
await skills.create(owner, 'p1', { name: 'add-page', description: 'Pages', content: 'Register it.' });
await skills.create(owner, 'p1', {
name: 'house-style',
description: 'Always',
content: 'Tabs.',
category: 'convention',
});
await skills.create(owner, 'p2', { name: 'add-page', description: 'Pages', content: 'Something else.' });
const exported = await skills.exportAll(owner, 'p1');
const archive = exported.content.toString('base64');
const result = await skills.importFiles(owner, 'p2', { archive }, 'import-key-0001');
expect(result.created.map(skill => [skill.name, skill.category, skill.status])).toEqual([
['add-page-2', 'workflow', 'active'],
['house-style', 'convention', 'active'],
]);
// The same request again answers the same; the same files again add nothing.
expect(await skills.importFiles(owner, 'p2', { archive }, 'import-key-0001')).toEqual(result);
const again = await skills.importFiles(owner, 'p2', { archive, status: 'proposed' }, 'import-key-0002');
expect(again.created).toEqual([]);
expect(again.skipped.map(item => item.reason)).toEqual(['identical', 'identical']);
expect(await all('p2')).toHaveLength(3);
// Loose files; one unreadable file is reported, the rest imported.
const loose = await skills.importFiles(
owner,
'p2',
{
files: [
{ path: 'review.SKILL.md', content: '---\ndescription: Before review\n---\nCheck it.' },
{ path: 'broken.md', content: '---\nname: x' },
],
status: 'proposed',
},
'import-key-0003',
);
expect(loose.created).toEqual([expect.objectContaining({ name: 'review', status: 'proposed' })]);
expect(loose.skipped).toEqual([expect.objectContaining({ source: 'broken.md', reason: 'invalid' })]);
await expect(
skills.importFiles(owner, 'p2', { files: [{ path: 'broken.md', content: '---\nname: x' }] }, 'import-key-0004'),
).rejects.toMatchObject({ code: 'NO_SKILLS' });
await expect(skills.importFiles(viewer, 'p2', { archive }, 'import-key-0005')).rejects.toMatchObject({
code: 'FORBIDDEN',
});
await expect(skills.importFiles(owner, 'p2', { archive })).rejects.toMatchObject({ code: 'IDEMPOTENCY_REQUIRED' });
});
it('copies skills to a project the person may shape, keeping their kind and state but not their history', async () => {
const { project, run, finish, skills, all } = setup();
await project('p1');
await project('p2');
await project('hidden', { memberIds: [] });
await finish(await run('r1', 'p1'), 'succeeded', { repairCount: 1, lastFailure: failure() });
const [pitfall] = await all('p1');
const copied = await skills.copy(owner, { skillIds: [pitfall!.id], projectId: 'p2' }, 'copy-key-0001');
expect(copied.created).toEqual([
expect.objectContaining({
projectId: 'p2',
name: 'pitfall-npm-test',
category: 'pitfall',
signature: 'verification:npm test',
status: 'active',
sourceRunIds: [],
createdBy: 'owner',
}),
]);
expect((await skills.copy(owner, { skillIds: [pitfall!.id], projectId: 'p2' }, 'copy-key-0002')).skipped).toEqual([
expect.objectContaining({ reason: 'identical' }),
]);
// The copy keeps learning in its new project: the same failure there updates it.
await finish(await run('r2', 'p2'), 'succeeded', { repairCount: 1, lastFailure: failure() });
expect(await all('p2')).toEqual([expect.objectContaining({ id: copied.created[0]!.id, sourceRunIds: ['r2'] })]);
// Someone who may not wish for the target may not copy into it, nor see a project they are not in.
await expect(
skills.copy(viewer, { skillIds: [pitfall!.id], projectId: 'p2' }, 'copy-key-0003'),
).rejects.toMatchObject({
code: 'FORBIDDEN',
});
await expect(
skills.copy(viewer, { skillIds: [pitfall!.id], projectId: 'hidden' }, 'copy-key-0004'),
).rejects.toMatchObject({
code: 'NOT_FOUND',
});
});
it('lists the skills of every project a person may see, filtered', async () => {
const { project, skills } = setup();
await project('p1');
await project('hidden', { memberIds: [] });
await skills.create(owner, 'p1', { name: 'one', description: 'Pages', content: 'Register routes.' });
await skills.create(owner, 'p1', { name: 'two', description: 'Style', content: 'Tabs.', category: 'convention' });
await skills.create(owner, 'hidden', { name: 'secret', description: 'Hidden', content: 'x' });
expect((await skills.search(owner, {})).map(skill => skill.name).sort()).toEqual(['one', 'secret', 'two']);
expect((await skills.search(viewer, {})).map(skill => skill.name).sort()).toEqual(['one', 'two']);
expect((await skills.search(viewer, { category: 'convention' })).map(skill => skill.name)).toEqual(['two']);
expect((await skills.search(viewer, { q: 'ROUTES' })).map(skill => skill.name)).toEqual(['one']);
expect(await skills.search(viewer, { status: 'proposed' })).toEqual([]);
await expect(skills.search(viewer, { projectId: 'hidden' })).rejects.toMatchObject({ code: 'NOT_FOUND' });
});
});