@pellux/goodvibes-agent 1.4.4 → 1.5.1

package/src/agent/ics-timezone.ts

@@ -0,0 +1,172 @@
+/**
+ * ics-timezone.ts — Dependency-free IANA timezone conversion using Intl.
+ *
+ * Converts between wall-clock date-time strings and UTC milliseconds using
+ * Intl.DateTimeFormat with the target timezone. The approach:
+ *
+ *   1. Treat the wall-clock string as a UTC candidate instant.
+ *   2. Format that candidate in the target timezone using Intl.DateTimeFormat.
+ *   3. Measure the offset (delta between what Intl says the local time is vs.
+ *      what we fed in).
+ *   4. Correct the candidate by that delta.
+ *   5. Iterate once more to handle DST boundaries where step 3 may land on
+ *      the wrong side of the transition.
+ *
+ * Handles all three RFC 5545 DTSTART forms:
+ *   - UTC ('...Z'):    caller should not call this; pass through as-is.
+ *   - Floating (no TZID): kept as local/unzoned — caller treats as UTC.
+ *   - TZID-qualified:  converted here to a correct UTC instant.
+ *
+ * Unknown or unsupported TZID values fall back to treating the wall-clock as
+ * UTC (offset = 0). This is documented behaviour, not silent corruption.
+ */
+
+// ──────────────────────────────────────────────────────────────────
+// Intl formatter cache
+// ──────────────────────────────────────────────────────────────────
+
+// Maps TZID → Intl.DateTimeFormat (reuse across calls in a session)
+const fmtCache = new Map<string, Intl.DateTimeFormat | null>();
+
+/**
+ * Returns a cached Intl.DateTimeFormat for the given IANA timezone, or null
+ * if the timezone is unknown/unsupported by this runtime.
+ */
+function getFormatter(tzid: string): Intl.DateTimeFormat | null {
+  if (fmtCache.has(tzid)) return fmtCache.get(tzid)!;
+  try {
+    const fmt = new Intl.DateTimeFormat('en-US', {
+      timeZone: tzid,
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hour12: false,
+    });
+    fmtCache.set(tzid, fmt);
+    return fmt;
+  } catch {
+    // Unknown TZID — Intl throws RangeError for invalid timezone names
+    fmtCache.set(tzid, null);
+    return null;
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────
+// Core conversion helpers
+// ──────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a wall-clock string "YYYY-MM-DDTHH:MM:SS" into component parts.
+ * Returns null if the string does not match the expected form.
+ */
+function parseWallClock(wallClock: string): {
+  year: number; month: number; day: number;
+  hour: number; minute: number; second: number;
+} | null {
+  const m = wallClock.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})$/);
+  if (!m) return null;
+  return {
+    year: parseInt(m[1]!, 10),
+    month: parseInt(m[2]!, 10),
+    day: parseInt(m[3]!, 10),
+    hour: parseInt(m[4]!, 10),
+    minute: parseInt(m[5]!, 10),
+    second: parseInt(m[6]!, 10),
+  };
+}
+
+/**
+ * Format a UTC instant (ms) as its wall-clock representation in the given
+ * IANA timezone, returning "YYYY-MM-DDTHH:MM:SS".
+ *
+ * Uses the cached Intl.DateTimeFormat. Returns null if the formatter is
+ * unavailable (unknown TZID).
+ */
+export function utcMsToWallClock(utcMs: number, tzid: string): string | null {
+  const fmt = getFormatter(tzid);
+  if (!fmt) return null;
+
+  // Intl.DateTimeFormat.formatToParts gives us named fields.
+  const parts = fmt.formatToParts(new Date(utcMs));
+  const get = (t: string) => parts.find((p) => p.type === t)?.value ?? '00';
+
+  // hour12: false gives '00'-'23' for midnight through 11pm; some runtimes
+  // return '24' for midnight — normalise to '00'.
+  let hour = get('hour');
+  if (hour === '24') hour = '00';
+
+  return `${get('year')}-${get('month')}-${get('day')}T${hour}:${get('minute')}:${get('second')}`;
+}
+
+/**
+ * Convert a wall-clock date-time string ("YYYY-MM-DDTHH:MM:SS") in the given
+ * IANA timezone to a UTC timestamp (milliseconds since epoch).
+ *
+ * Algorithm (offset-derivation trick with one DST correction pass):
+ *   1. Treat wallClock as UTC candidate: candidateMs = Date.parse(wallClock + 'Z')
+ *   2. Ask Intl what the local time in tzid IS at that candidateMs → localAtCandidate
+ *   3. delta = candidateMs - Date.parse(localAtCandidate + 'Z')
+ *   4. correctedMs = candidateMs + delta
+ *   5. Verify: ask Intl what local time correctedMs is → should equal wallClock.
+ *      If not (DST gap/fold), use correctedMs anyway (it's the closest valid instant).
+ *
+ * Falls back to treating wallClock as UTC (returns Date.parse(wallClock + 'Z'))
+ * when:
+ *   - The TZID is unknown to Intl (not a valid IANA name)
+ *   - The wallClock string cannot be parsed
+ * The fallback is documented: callers see this as offset=0 (UTC treatment).
+ */
+export function wallClockToUtcMs(wallClock: string, tzid: string): number {
+  const parsed = parseWallClock(wallClock);
+  if (!parsed) {
+    // Malformed wall-clock — return as UTC
+    return Date.parse(`${wallClock}Z`);
+  }
+
+  const fmt = getFormatter(tzid);
+  if (!fmt) {
+    // Unknown TZID — fall back to UTC treatment (documented)
+    return Date.parse(`${wallClock}Z`);
+  }
+
+  // seed candidate from raw wall-clock treated as UTC
+  const candidateMs = Date.UTC(
+    parsed.year, parsed.month - 1, parsed.day,
+    parsed.hour, parsed.minute, parsed.second,
+  );
+
+  // first-pass offset correction (used as the gap fallback)
+  const firstLocal = utcMsToWallClock(candidateMs, tzid);
+  if (!firstLocal) return candidateMs;
+  const firstLocalParsed = parseWallClock(firstLocal);
+  if (!firstLocalParsed) return candidateMs;
+  const firstDelta = candidateMs - Date.UTC(
+    firstLocalParsed.year, firstLocalParsed.month - 1, firstLocalParsed.day,
+    firstLocalParsed.hour, firstLocalParsed.minute, firstLocalParsed.second,
+  );
+  const firstCorrected = candidateMs + firstDelta;
+
+  // iterate to a fixed point (converges <=3 passes for every valid wall-clock,
+  // incl. DST-transition-day post-transition hours)
+  let guess = firstCorrected;
+  for (let i = 0; i < 5; i++) {
+    const local = utcMsToWallClock(guess, tzid);
+    if (!local) return guess;
+    if (local === wallClock) return guess; // exact valid instant
+    const lp = parseWallClock(local);
+    if (!lp) return guess;
+    const delta = candidateMs - Date.UTC(
+      lp.year, lp.month - 1, lp.day,
+      lp.hour, lp.minute, lp.second,
+    );
+    if (delta === 0) return guess;
+    guess += delta;
+  }
+  // no fixed point => nonexistent spring-forward gap; return first-pass corrected
+  // (conventional forward-shift: 02:30 NY -> 03:30 EDT = 07:30Z), preserving the gap tests
+  return firstCorrected;
+}
+

package/src/agent/markdown-frontmatter.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared YAML-style frontmatter parser for agent markdown files.
+ *
+ * Parses the `---\nkey: value\n---` block at the top of a markdown file
+ * and optionally strips it from the body.
+ */
+
+/**
+ * Parse the frontmatter block from a markdown string.
+ * Returns a flat record of string key/value pairs.
+ * Keys inside the block that have no value component are ignored.
+ */
+export function parseMarkdownFrontmatter(content: string): Record<string, string> {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!match) return {};
+  const result: Record<string, string> = {};
+  for (const line of match[1].split('\n')) {
+    const [key, ...rest] = line.split(':');
+    if (key && rest.length > 0) result[key.trim()] = rest.join(':').trim();
+  }
+  return result;
+}
+
+/**
+ * Strip the leading frontmatter block from a markdown string and return the body.
+ * Trims the result unless `trim` is false.
+ */
+export function stripMarkdownFrontmatter(content: string, trim = true): string {
+  const body = content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+  return trim ? body.trim() : body;
+}

package/src/agent/memory-safety.ts

@@ -1,4 +1,4 @@
-const SECRET_PATTERNS: readonly RegExp[] = [
+export const SECRET_PATTERNS: readonly RegExp[] = [
   /-----BEGIN [A-Z ]*PRIVATE KEY-----/i,
   /\bsk-[A-Za-z0-9_-]{16,}\b/,
   /\bgh[pousr]_[A-Za-z0-9_]{16,}\b/i,

package/src/agent/note-registry.ts

@@ -92,13 +92,7 @@ function nowIso(): string {
   return new Date().toISOString();
 }
 
-function assertNoNoteSecretLikeText(fields: readonly string[]): void {
-  try {
-    assertNoSecretLikeText(fields);
-  } catch {
-    throw new Error('Notes cannot store secret-looking values. Store a secret reference or remove the sensitive text.');
-  }
-}
+
 
 function parseNote(value: unknown): AgentNoteRecord | null {
   if (!isRecord(value)) return null;
@@ -193,7 +187,7 @@ export class AgentNoteRegistry {
     const body = input.body.trim();
     this.validateRequired(title, body);
     const sourceUrl = input.sourceUrl?.trim() || undefined;
-    assertNoNoteSecretLikeText([title, body, sourceUrl ?? '', ...(input.tags ?? [])]);
+    assertNoSecretLikeText([title, body, sourceUrl ?? '', ...(input.tags ?? [])], 'Notes');
     const duplicate = store.notes.find((note) => note.title.toLowerCase() === title.toLowerCase());
     if (duplicate) throw new Error(`Note already exists ${duplicate.id}`);
     const timestamp = nowIso();
@@ -221,7 +215,7 @@ export class AgentNoteRegistry {
     const body = input.body === undefined ? existing.body : input.body.trim();
     this.validateRequired(title, body);
     const sourceUrl = input.sourceUrl === undefined ? existing.sourceUrl : input.sourceUrl.trim() || undefined;
-    assertNoNoteSecretLikeText([title, body, sourceUrl ?? '', ...(input.tags ?? [])]);
+    assertNoSecretLikeText([title, body, sourceUrl ?? '', ...(input.tags ?? [])], 'Notes');
     const duplicate = store.notes.find((note) => note.id !== existing.id && note.title.toLowerCase() === title.toLowerCase());
     if (duplicate) throw new Error(`Note already exists ${duplicate.id}`);
     const updated: AgentNoteRecord = {

package/src/agent/persona-discovery.ts

@@ -2,6 +2,7 @@ import { promises as fsPromises } from 'node:fs';
 import { join } from 'node:path';
 import type { ShellPathService } from '@/runtime/index.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+import { parseMarkdownFrontmatter, stripMarkdownFrontmatter } from './markdown-frontmatter.ts';
 
 export type PersonaOrigin = 'project-local' | 'global' | 'custom';
 
@@ -16,19 +17,6 @@ export interface DiscoveredPersonaRecord {
 
 const DIRECTORY_MARKERS: readonly string[] = ['PERSONA.md', 'persona.md'];
 
-function parseFrontmatter(content: string): Record<string, string> {
-  const match = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!match) return {};
-  const result: Record<string, string> = {};
-  for (const line of match[1].split('\n')) {
-    const [key, ...rest] = line.split(':');
-    if (key && rest.length > 0) {
-      result[key.trim()] = rest.join(':').trim();
-    }
-  }
-  return result;
-}
-
 function getPersonaDirectories(cwd: string, homeDir: string): Array<{ root: string; origin: PersonaOrigin }> {
   return [
     { root: join(cwd, '.goodvibes', 'personas'), origin: 'project-local' },
@@ -46,8 +34,8 @@ async function readPersonaFile(path: string, origin: PersonaOrigin): Promise<Dis
     return null;
   }
 
-  const frontmatter = parseFrontmatter(content);
-  const markdownBody = content.replace(/^---\n[\s\S]*?\n---\n?/, '').trim();
+  const frontmatter = parseMarkdownFrontmatter(content);
+  const markdownBody = stripMarkdownFrontmatter(content);
   const body = (frontmatter.system_prompt ?? markdownBody).trim();
   if (!body) return null;
   const name = frontmatter.name ?? path.split(/[\\/]/).pop()?.replace(/\.md$/i, '') ?? 'persona';

package/src/agent/persona-registry.ts

@@ -3,6 +3,7 @@ import { dirname } from 'node:path';
 import type { ShellPathService } from '@/runtime/index.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
 import { formatAgentRecordReviewState } from './record-labels.ts';
+import { containsSecretLikeText } from './memory-safety.ts';
 
 export type AgentPersonaSource = 'user' | 'agent' | 'imported' | 'system';
 export type AgentPersonaReviewState = 'fresh' | 'reviewed' | 'stale';
@@ -56,12 +57,6 @@ interface PersonaStoreFile {
 }
 
 const STORE_VERSION = 1;
-const SECRET_PATTERNS: readonly RegExp[] = [
-  /-----BEGIN [A-Z ]*PRIVATE KEY-----/i,
-  /\bsk-[A-Za-z0-9_-]{16,}\b/,
-  /\bgh[pousr]_[A-Za-z0-9_]{16,}\b/i,
-  /\b(?:password|passwd|api[_-]?key|token|secret)\s*[:=]\s*\S{6,}/i,
-];
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -103,10 +98,6 @@ function nowIso(): string {
   return new Date().toISOString();
 }
 
-function containsSecretLikeText(text: string): boolean {
-  return SECRET_PATTERNS.some((pattern) => pattern.test(text));
-}
-
 export function assertNoSecretLikeText(fields: readonly string[], ownerLabel = 'Agent local records'): void {
   if (fields.some((field) => containsSecretLikeText(field))) {
     throw new Error(`${ownerLabel} cannot store secret-looking values. Store a secret reference or remove the sensitive text.`);

package/src/agent/research-source-registry.ts

@@ -408,7 +408,11 @@ export class AgentResearchSourceRegistry {
 
   private readStore(): ResearchSourceStoreFile {
     if (!existsSync(this.storePath)) return { version: STORE_VERSION, sources: [] };
-    return parseStore(readFileSync(this.storePath, 'utf-8'));
+    try {
+      return parseStore(readFileSync(this.storePath, 'utf-8'));
+    } catch (error) {
+      throw new Error(`Could not read Agent research source store: ${error instanceof Error ? error.message : String(error)}`);
+    }
   }
 
   private writeStore(store: ResearchSourceStoreFile): void {

package/src/agent/routine-discovery.ts

@@ -2,6 +2,7 @@ import { promises as fsPromises } from 'node:fs';
 import { join } from 'node:path';
 import type { ShellPathService } from '@/runtime/index.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+import { parseMarkdownFrontmatter, stripMarkdownFrontmatter } from './markdown-frontmatter.ts';
 
 export type RoutineOrigin = 'project-local' | 'global' | 'custom';
 
@@ -16,19 +17,6 @@ export interface DiscoveredRoutineRecord {
 
 const DIRECTORY_MARKERS: readonly string[] = ['ROUTINE.md', 'routine.md'];
 
-function parseFrontmatter(content: string): Record<string, string> {
-  const match = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!match) return {};
-  const result: Record<string, string> = {};
-  for (const line of match[1].split('\n')) {
-    const [key, ...rest] = line.split(':');
-    if (key && rest.length > 0) {
-      result[key.trim()] = rest.join(':').trim();
-    }
-  }
-  return result;
-}
-
 function getRoutineDirectories(cwd: string, homeDir: string): Array<{ root: string; origin: RoutineOrigin }> {
   return [
     { root: join(cwd, '.goodvibes', 'routines'), origin: 'project-local' },
@@ -46,8 +34,8 @@ async function readRoutineFile(path: string, origin: RoutineOrigin): Promise<Dis
     return null;
   }
 
-  const frontmatter = parseFrontmatter(content);
-  const markdownBody = content.replace(/^---\n[\s\S]*?\n---\n?/, '').trim();
+  const frontmatter = parseMarkdownFrontmatter(content);
+  const markdownBody = stripMarkdownFrontmatter(content);
   const steps = (frontmatter.steps ?? markdownBody).trim();
   if (!steps) return null;
   const name = frontmatter.name ?? path.split(/[\\/]/).pop()?.replace(/\.md$/i, '') ?? 'routine';

package/src/agent/runtime-profile.ts

@@ -302,6 +302,7 @@ function selectDiscoveredRecords<T extends { readonly name: string; readonly pat
 
 function discoveredSkillToTemplate(skill: SkillRecord): AgentRuntimeProfileStarterTemplate['skills'][number] {
   if (!skill.body.trim()) throw new Error(`Discovered Agent skill ${skill.name} has no procedure body.`);
+  assertNoSecretLikeText([skill.name, skill.description, skill.body], `Discovered skill '${skill.name}'`);
   return {
     name: skill.name,
     description: skill.description || `Imported skill from ${skill.origin} skill file.`,
@@ -313,6 +314,7 @@ function discoveredSkillToTemplate(skill: SkillRecord): AgentRuntimeProfileStart
 
 function discoveredRoutineToTemplate(routine: DiscoveredRoutineRecord): AgentRuntimeProfileStarterTemplate['routines'][number] {
   if (!routine.steps.trim()) throw new Error(`Discovered Agent routine ${routine.name} has no steps.`);
+  assertNoSecretLikeText([routine.name, routine.description, routine.steps], `Discovered routine '${routine.name}'`);
   return {
     name: routine.name,
     description: routine.description || `Imported routine from ${routine.origin} markdown file.`,
@@ -323,6 +325,7 @@ function discoveredRoutineToTemplate(routine: DiscoveredRoutineRecord): AgentRun
 }
 
 function discoveredPersonaToTemplate(persona: DiscoveredPersonaRecord): AgentRuntimeProfileStarterTemplate['persona'] {
+  assertNoSecretLikeText([persona.name, persona.description, persona.body], `Discovered persona '${persona.name}'`);
   return {
     name: persona.name,
     description: persona.description || `Imported persona from ${persona.origin} markdown file.`,

package/src/agent/skill-discovery.ts

@@ -2,6 +2,7 @@ import { promises as fsPromises } from 'node:fs';
 import { join } from 'node:path';
 import type { ShellPathService } from '@/runtime/index.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+import { parseMarkdownFrontmatter, stripMarkdownFrontmatter } from './markdown-frontmatter.ts';
 
 export type SkillOrigin = 'project-local' | 'global' | 'custom';
 
@@ -16,19 +17,6 @@ export interface SkillRecord {
   frontmatter: Record<string, string>;
 }
 
-function parseFrontmatter(content: string): Record<string, string> {
-  const match = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!match) return {};
-  const result: Record<string, string> = {};
-  for (const line of match[1].split('\n')) {
-    const [key, ...rest] = line.split(':');
-    if (key && rest.length > 0) {
-      result[key.trim()] = rest.join(':').trim();
-    }
-  }
-  return result;
-}
-
 function getSkillDirectories(cwd: string, homeDir: string): Array<{ root: string; origin: SkillOrigin }> {
   return [
     { root: join(cwd, '.goodvibes', 'skills'), origin: 'project-local' },
@@ -46,8 +34,8 @@ async function readSkillFile(path: string, origin: SkillOrigin): Promise<SkillRe
     return null;
   }
 
-  const frontmatter = parseFrontmatter(content);
-  const body = content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+  const frontmatter = parseMarkdownFrontmatter(content);
+  const body = stripMarkdownFrontmatter(content, false);
   const name = frontmatter.name ?? path.split(/[\\/]/).pop()?.replace(/\.md$/, '') ?? 'skill';
   const description = frontmatter.description ?? frontmatter.summary ?? '';
   const dependencies = frontmatter.depends_on

package/src/agent/skill-draft-proposer.ts

@@ -0,0 +1,203 @@
+import { assertNoSecretLikeText } from './persona-registry.ts';
+import type { LearningCandidate } from '../tools/agent-harness-learning-curator-types.ts';
+import type { AgentSkillCreateInput } from './skill-registry-types.ts';
+
+/**
+ * The create-input payload produced for each proposed skill draft.
+ * Passed directly to AgentSkillRegistry.create().
+ */
+export interface SkillDraftPayload extends AgentSkillCreateInput {
+  /** Candidate that originated this draft, for ledger bookkeeping. */
+  readonly candidateId: string;
+  /** Human-readable label carried from the learning candidate. */
+  readonly candidateLabel: string;
+}
+
+export interface ProposeSkillDraftsInput {
+  /** Full ranked candidate list from buildLearningCandidates. */
+  readonly candidates: readonly LearningCandidate[];
+  /** Lower-cased name set of skills already in the registry (dedup guard). */
+  readonly existingSkillNames: ReadonlySet<string>;
+  /** Lower-cased name set of skills proposed in earlier passes (dedup guard). */
+  readonly previouslyProposedNames: ReadonlySet<string>;
+}
+
+/** Maximum draft proposals emitted per pass. */
+const MAX_PROPOSALS = 3;
+
+const PROVENANCE = 'auto-proposed-skill-draft';
+
+/** Convert an arbitrary string to a URL-safe kebab-case slug. */
+function slugify(value: string): string {
+  const slug = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return slug || 'skill';
+}
+
+/**
+ * Extract a one-line description from the proposalFields carried on the candidate.
+ * Prefers an explicit `description` field; falls back to the candidate label.
+ */
+function extractDescription(candidate: LearningCandidate): string {
+  const fields = candidate.proposalFields ?? {};
+  const desc = (fields.description ?? '').trim();
+  if (desc) return desc.split('\n')[0]?.trim() || desc;
+  return candidate.label.split('->')[0]?.trim() || candidate.label;
+}
+
+/**
+ * Build a stepwise procedure body from available candidate evidence.
+ * Uses proposalFields.notes / detail / triggers when present.
+ */
+function buildProcedureBody(candidate: LearningCandidate): string {
+  const fields = candidate.proposalFields ?? {};
+  const sections: string[] = [];
+
+  // Context block — reason and source
+  sections.push(`# ${extractDescription(candidate)}`);
+  sections.push('');
+  if (candidate.reason) {
+    sections.push(`## Origin`);
+    sections.push(candidate.reason.trim());
+    sections.push('');
+  }
+
+  // Triggers — derived from proposalFields.triggers or candidate.proposalTarget
+  const triggerHint = (fields.triggers ?? '').trim();
+  if (triggerHint) {
+    sections.push(`## When to use`);
+    sections.push(triggerHint);
+    sections.push('');
+  }
+
+  // Steps / body — prefer notes, then detail
+  const notes = (fields.notes ?? '').trim();
+  const detail = (fields.detail ?? '').trim();
+  const body = notes || detail;
+  if (body) {
+    sections.push(`## Steps`);
+    sections.push(body);
+    sections.push('');
+  }
+
+  // Tags / extra context
+  const tags = (fields.tags ?? '').trim();
+  if (tags) {
+    sections.push(`## Tags`);
+    sections.push(tags);
+    sections.push('');
+  }
+
+  sections.push(`## Notes`);
+  sections.push('This skill was auto-proposed from a learning candidate. Review and refine the steps before enabling.');
+
+  return sections.join('\n').trim();
+}
+
+/**
+ * Derive inferred trigger phrases from proposal fields and candidate metadata.
+ */
+function buildTriggers(candidate: LearningCandidate): readonly string[] {
+  const fields = candidate.proposalFields ?? {};
+  const raw = (fields.triggers ?? '').trim();
+  if (!raw) return [];
+  return raw
+    .split(/[,;]+/)
+    .map((t) => t.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Derive tags from proposal fields and provenance.
+ */
+function buildTags(candidate: LearningCandidate): readonly string[] {
+  const fields = candidate.proposalFields ?? {};
+  const raw = (fields.tags ?? '').trim();
+  const base = raw
+    ? raw.split(/[,;]+/).map((t) => t.trim()).filter(Boolean)
+    : [];
+  // Always include the auto-proposal marker so it's filterable
+  if (!base.includes('auto-proposed')) base.push('auto-proposed');
+  return base;
+}
+
+/**
+ * Pure function: given the current learning candidates and name registries, select
+ * up to MAX_PROPOSALS skill-worthy candidates and return their draft payloads.
+ *
+ * Hard rules:
+ * - Only 'proposal-ready' or 'ready-to-promote' candidates with proposalTarget === 'skill'
+ * - Max 3 proposals per pass
+ * - Dedupe against existingSkillNames, previouslyProposedNames, and names proposed this pass
+ *   (all comparisons use the kebab slug of the name, case-insensitive)
+ * - Skip any candidate whose text fields contain secret-like content
+ * - Skip any candidate whose derived name or description is empty
+ * - All drafts are created with enabled: false (caller's responsibility; registry enforces reviewState 'fresh')
+ */
+export function proposeSkillDrafts(input: ProposeSkillDraftsInput): readonly SkillDraftPayload[] {
+  const { candidates, existingSkillNames, previouslyProposedNames } = input;
+
+  const proposals: SkillDraftPayload[] = [];
+  // Within-pass dedup: track slugified names already proposed in this call.
+  const proposedThisPass = new Set<string>();
+
+  // Filter to skill-proposal candidates, sorted by priority desc (candidates
+  // from buildLearningCandidates are already sorted but we enforce it here for
+  // purity — the function should not depend on caller sort order).
+  const eligible = [...candidates]
+    .filter(
+      (c) =>
+        (c.status === 'proposal-ready' || c.status === 'ready-to-promote') &&
+        c.proposalTarget === 'skill',
+    )
+    .sort((a, b) => b.priority - a.priority);
+
+  for (const candidate of eligible) {
+    if (proposals.length >= MAX_PROPOSALS) break;
+
+    const description = extractDescription(candidate);
+    // Guard: skip candidates whose description is empty after extraction.
+    if (!description.trim()) continue;
+
+    const rawName = description.slice(0, 120); // registry normalizes further
+    // Guard: skip candidates whose derived name is empty.
+    if (!rawName.trim()) continue;
+
+    const name = slugify(rawName);
+    const nameLower = name.toLowerCase(); // slugify already lowercases
+
+    // Dedup against existing, previously proposed, and within-pass proposed.
+    if (
+      existingSkillNames.has(nameLower) ||
+      previouslyProposedNames.has(nameLower) ||
+      proposedThisPass.has(nameLower)
+    ) continue;
+
+    // Secret scan — skip candidate rather than throw, as individual dirty
+    // candidates should not block the whole pass
+    const procedure = buildProcedureBody(candidate);
+    const triggers = buildTriggers(candidate);
+    const tags = buildTags(candidate);
+    const fieldsToScan = [name, description, procedure, ...triggers, ...tags];
+    try {
+      assertNoSecretLikeText(fieldsToScan, 'Skill draft proposer');
+    } catch {
+      continue;
+    }
+
+    proposedThisPass.add(nameLower);
+    proposals.push({
+      candidateId: candidate.id,
+      candidateLabel: candidate.label,
+      name,
+      description,
+      procedure,
+      triggers: triggers.length > 0 ? triggers : undefined,
+      tags: tags.length > 0 ? tags : undefined,
+      enabled: false,
+      source: 'agent',
+      provenance: PROVENANCE,
+    });
+  }
+
+  return proposals;
+}