opencode-swarm 7.136.0 → 7.136.2

package/dist/services/skill-evaluator.d.ts

@@ -64,6 +64,23 @@ declare function evaluateContent(content: string, testCase: SkillEvalCase): {
     score: number;
     failures: string[];
 };
+/**
+ * Pure phrase-scoring function (issue #1822 — factored out so the governed
+ * skill optimizer's `project` scorer wrapper can invoke the SAME scoring logic
+ * the internal gate uses, without duplicating it). Behavior is identical to the
+ * previous inline implementation in `evaluateContent`.
+ *
+ * Score = requiredHits / max(1, required.length), minus a 1-point penalty if
+ * any forbidden phrase is present, clamped to >= 0.
+ */
+export declare function scoreSkillPhrases(args: {
+    content: string;
+    required?: string[];
+    forbidden?: string[];
+}): {
+    score: number;
+    failures: string[];
+};
 declare function hashNormalizedContent(content: string | undefined): string | undefined;
 export declare function evaluateSkillChange(req: EvaluateSkillChangeRequest): Promise<SkillEvaluationResult>;
 export declare function appendRejectedSkillEdit(req: EvaluateSkillChangeRequest, evaluation: SkillEvaluationResult): Promise<void>;

package/dist/services/skill-optimizer/activation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Activation + rollback (Workstream D, issue #1822).
+ *
+ * Safety model (per the revised plan + critic C2): slash commands invoked by a
+ * human do NOT go through scope-guard.ts (which is coder-only, line 83). The
+ * activation safety stack is therefore:
+ *   1. `toolPolicy: 'human-only'` on the `approve`/`activate`/`reject`/`rollback`
+ *      command entries — prevents agent `swarm_command` invocation;
+ *   2. an explicit `expectedContentHash` argument checked against the current
+ *      SKILL.md contentHash — refuses a stale base (`STALE_BASE`);
+ *   3. atomic write (snapshot-then-rename) after recording a rollback snapshot;
+ *   4. append-only history — rollback appends a new event, never deletes.
+ *
+ * No claim of `SCOPE_NOT_DECLARED` for these commands (that invariant applies
+ * to coder tool calls under a Task, not human slash commands).
+ */
+import { renameSync, unlinkSync, writeFileSync } from 'node:fs';
+export declare const _internals: {
+    writeFileSync: typeof writeFileSync;
+    renameSync: typeof renameSync;
+    unlinkSync: typeof unlinkSync;
+};
+export interface ActivateInput {
+    directory: string;
+    skillSlug: string;
+    candidateId: string;
+    actor: string;
+    /** Caller's view of the current SKILL.md contentHash — refuses stale base. */
+    expectedContentHash: string;
+}
+export interface ActivateResult {
+    activated: boolean;
+    reason: string;
+    /** Path to the rollback snapshot recorded before activation. */
+    rollbackSnapshotRef: string;
+}
+/**
+ * Activate a candidate: refuse stale base, snapshot the incumbent, atomic-write
+ * the candidate content to the skill root, record the `activated` event with
+ * user/origin + snapshot ref.
+ */
+export declare function activateCandidate(input: ActivateInput): Promise<ActivateResult>;
+export interface RollbackInput {
+    directory: string;
+    skillSlug: string;
+    candidateId: string;
+    actor: string;
+}
+export interface RollbackResult {
+    rolledBack: boolean;
+    reason: string;
+}
+/**
+ * Rollback an activation by restoring the snapshot. Appends a `rolled_back`
+ * event — history is NEVER deleted. The restored snapshot becomes the live
+ * SKILL.md content atomically.
+ */
+export declare function rollbackCandidate(input: RollbackInput): Promise<RollbackResult>;

package/dist/services/skill-optimizer/candidates.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Constrained candidate generation (Workstream B, issue #1822).
+ *
+ * A candidate is a constrained edit of ONE allowlisted `SKILL.md`. The
+ * generator:
+ *   - is deterministic-first (the deterministic proposal is the seed; LLM free
+ *     text is supplemental only);
+ *   - CANNOT see held-out contents/scores/evaluator implementation — its inputs
+ *     are an explicit allowlist (baseline content, eligible evidence,
+ *     counterexamples from the rejection ledger). Any attempt to inject a
+ *     claimed held-out task ID throws LEAKAGE_DETECTED (critic I2);
+ *   - enforces a trust region (max changed lines/bytes/sections; one target;
+ *     preserve frontmatter/schema/discoverability/progressive disclosure);
+ *   - treats historical evidence as untrusted DATA, not instructions (sanitized
+ *     before injection).
+ */
+import type { SkillOptConfig } from '../../config/schema.js';
+/** Allowlisted generator inputs — anything else is leakage. */
+export interface GeneratorInputs {
+    /** Current baseline SKILL.md content. */
+    baselineContent: string;
+    /** Eligible evidence entries (sanitized, untrusted-as-data). */
+    eligibleEvidence: readonly SanitizedEvidence[];
+    /** Counterexamples from the rejection ledger (prevents re-drafting rejects). */
+    counterexamples: readonly string[];
+    /** Edit/token budget for this round. */
+    budget: {
+        maxChangedLines: number;
+        maxChangedBytes: number;
+        maxChangedSections: number;
+    };
+}
+export interface SanitizedEvidence {
+    id: string;
+    triggers: string[];
+    requiredActions: string[];
+    forbiddenActions: string[];
+    confidence: number;
+}
+/** IDs of held-out test tasks the generator must never see. */
+export type ClaimedTestTaskIds = ReadonlySet<string>;
+/**
+ * Build the generator's input slice from raw materials. Throws LEAKAGE_DETECTED
+ * if any held-out task ID is referenced in evidence (defense-in-depth — the
+ * generator should never receive held-out task content, but we also refuse the
+ * IDs to prevent indirect leakage through metadata).
+ */
+export declare function buildGeneratorInputs(args: {
+    baselineContent: string;
+    eligibleEvidence: readonly SanitizedEvidence[];
+    counterexamples: readonly string[];
+    budget: SkillOptConfig;
+    claimedTestTaskIds: ClaimedTestTaskIds;
+}): GeneratorInputs;
+export interface DraftedCandidate {
+    content: string;
+    diffSummary: {
+        changedLines: number;
+        changedBytes: number;
+        changedSections: number;
+    };
+    rationale: string;
+    risks: string[];
+    rollbackSnapshot: string;
+    metric: {
+        eligibilityScore: number;
+    };
+}
+/** DI seam. The deterministic drafter is the default; LLM supplemental is optional. */
+export declare const _internals: {
+    /** Deterministic draft: appends a constrained "## Optimization Notes" section. */
+    draftDeterministic: typeof defaultDeterministicDraft;
+};
+declare function defaultDeterministicDraft(inputs: GeneratorInputs): DraftedCandidate;
+/** Enforce the trust region; throws TrustRegionViolation on breach. */
+export declare function enforceTrustRegion(candidate: DraftedCandidate, budget: {
+    maxChangedLines: number;
+    maxChangedBytes: number;
+    maxChangedSections: number;
+}): void;
+/** Equivalent-patch detection: identical content hash → no-op, stop convergence. */
+export declare function isEquivalentPatch(baselineContent: string, candidateContent: string): boolean;
+/**
+ * Produce a candidate from inputs. Deterministic-first; the LLM delegate (if
+ * wired) is supplemental and must stay within the same trust region.
+ */
+export declare function draftCandidate(inputs: GeneratorInputs): DraftedCandidate;
+export {};

package/dist/services/skill-optimizer/controller.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Serial controller (Workstream C, issue #1822).
+ *
+ * One project run + one target skill at a time, enforced by a cross-process
+ * lock with a stale-lock policy (inherited from `file-locks.ts` — 5 min stale
+ * TTL). The round flow:
+ *
+ *   acquireRunLock (project-wide) → acquireSkillLock (<slug>)
+ *     → freeze baseline (contentHash + snapshot)
+ *     → deterministic seed (Workstream A)
+ *     → draft constrained candidate (Workstream B)
+ *     → static smoke → smoke_validated
+ *     → evaluateCandidateV1 (split:'test') → validation_running
+ *       → decision.status → accepted_pending_approval | rejected | inconclusive
+ *   release (reverse order)
+ *
+ * Caps (enforced): max_rounds (draft/smoke retries before a validation),
+ * max_transient_retries (infra-retries before inconclusive), deadband
+ * (forwarded to the promotion policy), convergence_non_improvements (K
+ * draft/smoke non-progress stops). A completed validation (accept/reject/
+ * inconclusive) is terminal — the held-out set is single-use. Not enforced in
+ * v1: max_candidates_per_round (one candidate per round), max_tokens_per_round
+ * /spend accounting, a wall-clock round timer (max_round_time_ms is forwarded
+ * only as a per-task validation timeout), max_rejections and
+ * max_inconclusive_rounds (declared in the schema for forward-compatibility
+ * with a future multi-validation loop, but unused now that a single run
+ * performs at most one validation).
+ *
+ * Transient infra failures → inconclusive with bounded retry
+ * (`max_transient_retries`, default 5) BEFORE counting as a rejection.
+ * Non-transient failures → hard stop + `telemetry.loopDetected` + a
+ * `NON-TRANSIENT STOP` advisory (does NOT mutate the active skill).
+ *
+ * A test-set result NEVER auto-generates a round — `claimHeldOutTest`
+ * (`split:'test'`) throws `TestAlreadyConsumedError` on reuse. A single `run`
+ * therefore performs AT MOST ONE validation; draft/smoke retries are the only
+ * looped steps, and a completed validation (accept/reject/inconclusive) stops
+ * the loop. A re-test requires a fresh task set, i.e. a new `run`.
+ */
+import type { SkillOptConfig } from '../../config/schema.js';
+import type { EvaluationCandidateV1, EvaluationRunV1, PromotionDecisionV1 } from '../../evaluation/contracts.js';
+import type { EvaluationModelDispatcher } from '../../evaluation/model-dispatcher.js';
+import { evaluateCandidateV1 } from '../../evaluation/public-api.js';
+import { tryAcquireLock } from '../../parallel/file-locks.js';
+import { emit as emitTelemetry } from '../../telemetry.js';
+import { type GeneratorInputs } from './candidates.js';
+import { currentCandidateState } from './lifecycle.js';
+export type Origin = 'command:skill-opt:run' | 'command:skill-opt:plan';
+export interface RunRoundInput {
+    directory: string;
+    skillSlug: string;
+    config: SkillOptConfig;
+    /** Caller's session ID (for telemetry). */
+    sessionId?: string;
+    /** Evaluation dispatcher from CommandContext.evaluationModelDispatcher. */
+    dispatcher?: EvaluationModelDispatcher;
+    /** Model IDs to evaluate against. */
+    models: string[];
+    /** Evidence to seed the draft (if absent, the deterministic seed is used). */
+    seedEvidence?: GeneratorInputs['eligibleEvidence'];
+    /** Held-out task IDs the generator must not see (leakage defense). */
+    claimedTestTaskIds?: ReadonlySet<string>;
+    /** Test task fixtures for validation (assembled by the command layer). */
+    validationTasks: unknown[];
+    /**
+     * The root directory the evaluation substrate resolves task paths against
+     * (instructionPath, environment.path, scorer argv). This is where the
+     * command layer materialized the fixture files — NOT the project root.
+     * (F1 fix: previously the controller passed input.directory, causing
+     * file-not-found on every real validation.)
+     */
+    inputRoot?: string;
+    /** Baseline + candidate EvaluationCandidateV1 builders are derived from content. */
+    baselineModel: string;
+    candidateModel: string;
+    /** AbortSignal for cooperative cancellation. */
+    abortSignal?: AbortSignal;
+    /** Origin for lifecycle events. */
+    origin: Origin;
+    /** Dry-run: if true, plan only, do not execute validation. */
+    dryRun?: boolean;
+}
+export interface RunRoundResult {
+    candidateId: string;
+    decidedState: string;
+    decision?: PromotionDecisionV1;
+    run?: EvaluationRunV1;
+    stopped: boolean;
+    stopReason?: string;
+    error?: string;
+    /** True when a non-transient validation failure hard-stopped this round.
+     * The optimization loop must stop immediately (AGENTS.md invariant #9). */
+    hardStop?: boolean;
+}
+/** DI seam for lock + telemetry injection (AGENTS.md invariant #7). */
+/**
+ * Prepare candidate payloads inside inputRoot and compute substrate-compatible
+ * content hashes. Extracted to _internals so tests that mock evaluateCandidateV1
+ * can bypass the real filesystem hash computation (which is platform-sensitive).
+ */
+declare function prepareCandidatePayloads(inputRoot: string, candidateId: string, skillSlug: string, baselineModel: string, candidateModel: string, baselineContent: string, candidateContent: string): Promise<{
+    baseline: EvaluationCandidateV1;
+    candidate: EvaluationCandidateV1;
+}>;
+export declare const _internals: {
+    tryAcquireLock: typeof tryAcquireLock;
+    emitTelemetry: typeof emitTelemetry;
+    evaluateCandidateV1: typeof evaluateCandidateV1;
+    prepareCandidatePayloads: typeof prepareCandidatePayloads;
+};
+/** Execute a single optimization round for one skill. */
+export declare function runOptimizationRound(input: RunRoundInput): Promise<RunRoundResult>;
+/** Read convergence state (non-improvement count) for the K-stop check. */
+export declare function readConvergenceState(directory: string): {
+    nonImprovements: number;
+};
+/** Update convergence state after a round. */
+export declare function writeConvergenceState(directory: string, nonImprovements: number): void;
+export interface OptimizationLoopResult {
+    rounds: RunRoundResult[];
+    stopped: boolean;
+    stopReason: string;
+}
+/**
+ * Drive optimization rounds until a cap or stop condition is hit (reviewer CR3).
+ *
+ * IMPORTANT — held-out test set is single-use (final critic FC2): a validation
+ * call consumes the `split:'test'` task set (`claimHeldOutTest` throws
+ * `TestAlreadyConsumedError` on reuse). Therefore a single `run` performs AT
+ * MOST ONE validation; the loop's rounds are draft-and-smoke retries that can
+ * loop without consuming the held-out set (equivalent-patch, smoke-fail,
+ * draft-fail). Once a round reaches validation (accept/reject/inconclusive),
+ * the loop STOPS — a re-validation requires a fresh task set, i.e. a new `run`.
+ *
+ * Caps + stop conditions (all from `config`):
+ *   - `max_rounds`: hard cap on draft-and-smoke retries before a validation.
+ *   - `convergence_non_improvements`: K consecutive non-accept results stops.
+ *   - any non-transient hard stop, equivalent-patch, lock, or completed
+ *     validation stops immediately.
+ *
+ * Each round is a fresh candidate (mintCandidateId inside runOptimizationRound).
+ * A test-set result NEVER auto-generates a round — only this explicit loop does.
+ */
+export declare function runOptimizationLoop(input: RunRoundInput): Promise<OptimizationLoopResult>;
+/** Re-export current state helper for the command layer. */
+export { currentCandidateState };

package/dist/services/skill-optimizer/deterministic-seed.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Deterministic candidate seed (Workstream A, issue #1822 — #1771 lifecycle closure).
+ *
+ * The seed is deterministic-first: it composes the existing eligibility
+ * functions (`selectCandidateEntries` + `isSkillMaturityEligible` from
+ * skill-generator.ts) and sanitizes them into `GeneratorInputs`. LLM free text
+ * is supplemental only and is gated off by default (the controller may wire a
+ * delegate if `skill_opt.enabled === true` and a delegate is supplied).
+ */
+import type { SanitizedEvidence } from './candidates.js';
+export interface DeterministicSeedInput {
+    directory: string;
+    /** Override confidence/confirmation floors. */
+    minConfidence?: number;
+    minConfirmations?: number;
+}
+export interface DeterministicSeedResult {
+    evidence: readonly SanitizedEvidence[];
+    /** Count of considered entries that were filtered out (diagnostic). */
+    filteredOut: number;
+}
+/**
+ * Produce a deterministic seed of eligible evidence for a candidate draft.
+ * Mirrors the eligibility logic in `selectCandidateEntries` /
+ * `isSkillMaturityEligible` so the optimizer's seed is consistent with the
+ * rest of the skill system. LLM free text is supplemental only and not
+ * produced here.
+ */
+export declare function deterministicSeed(input: DeterministicSeedInput): Promise<DeterministicSeedResult>;

package/dist/services/skill-optimizer/lifecycle.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Lifecycle state machine for the governed skill optimizer (issue #1822).
+ *
+ * Legal transitions encode the durable lifecycle:
+ *   discovered → drafted → smoke_validated → validation_running
+ *                                            → accepted_pending_approval | rejected | inconclusive
+ *     accepted_pending_approval → activated | expired | rolled_back
+ *     inconclusive → drafted (re-entry with a fresh candidate + task set, D8)
+ *     activated → rolled_back
+ *     rejected → (terminal)
+ *     expired → (terminal)
+ *
+ * `recordTransition` wraps `store.appendEvent` with:
+ *   - legal-transition enforcement (IllegalTransitionError otherwise);
+ *   - replay-from-last-complete (restart never reruns a one-shot validation —
+ *     validation run refs are immutable; a re-validation is a NEW candidate);
+ *   - replay-after-write verification (inherited from the store).
+ */
+import { computeStateHash, type SkillOptEvent, type SkillOptState } from './store.js';
+export declare class IllegalTransitionError extends Error {
+    readonly from: SkillOptState | null;
+    readonly to: SkillOptState;
+    constructor(from: SkillOptState | null, to: SkillOptState);
+}
+export declare function isLegalTransition(from: SkillOptState | null, to: SkillOptState): boolean;
+export declare function assertTransition(from: SkillOptState | null, to: SkillOptState): void;
+export interface RecordTransitionInput {
+    directory: string;
+    skillSlug: string;
+    candidateId: string;
+    toState: SkillOptState;
+    eventType: string;
+    actor: string;
+    origin: string;
+    reason: string;
+    evidenceRefs?: string[];
+    contentHashBefore?: string | null;
+    contentHashAfter?: string | null;
+    payload?: Record<string, unknown>;
+}
+export interface RecordTransitionResult {
+    event: SkillOptEvent;
+    fromState: SkillOptState | null;
+    replayTruncated: boolean;
+}
+/**
+ * Record a lifecycle transition.
+ *
+ * 1. Replays the candidate ledger to derive the current `fromState` (restart-
+ *    safe). If the ledger tail is corrupt, quarantines the suffix and uses the
+ *    last complete event's `toState` as `fromState`.
+ * 2. Asserts the `from -> to` transition is legal.
+ * 3. Appends the event (hash-chained, fsync+rename, replay-after-write verify).
+ * 4. Refreshes the derived `state.json` projection.
+ *
+ * Restart rule: a one-shot validation is NEVER rerun. If `toState` is
+ * `validation_running` and the candidate already has a completed validation
+ * event, this throws — the caller must mint a new candidate ID for a re-test.
+ */
+export declare function recordTransition(input: RecordTransitionInput): Promise<RecordTransitionResult>;
+/** Convenience: current candidate state via replay (re-derived each call). */
+export declare function currentCandidateState(directory: string, skillSlug: string, candidateId: string): {
+    state: SkillOptState | null;
+    lastEvent: SkillOptEvent | null;
+    truncated: boolean;
+};
+/** Whether a candidate has reached a terminal state. */
+export declare function isTerminal(state: SkillOptState | null): boolean;
+/** Re-export for callers that need the hash helper. */
+export { computeStateHash };

package/dist/services/skill-optimizer/promoted-external-staleness.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Distinct `promoted_external` staleness policy (Workstream A, issue #1822).
+ *
+ * Today `curator.ts:1791` SKIPS promoted-external skills entirely during the
+ * staleness sweep. That means a promoted-external skill whose source knowledge
+ * changed (or which became unsupported) is never reconciled. This module
+ * provides the distinct policy the curator now consults:
+ *
+ *   - source-knowledge-changed → regenerate (advisory: the curator LOGS source
+ *     drift; it does not auto-regenerate promoted-external skills — the user
+ *     re-runs external discovery);
+ *   - wall-clock retirement (configurable) using the REAL usage signal (#1770),
+ *     with minimum-age and support safeguards, and a REVERSIBLE archive.
+ *
+ * The decision is advisory: the curator routes `retire` to `retireSkill`
+ * (reversible / marked); `regenerate` is log-only advisory (the user decides
+ * whether to re-run discovery/regeneration).
+ */
+export type PromotedExternalStalenessDecision = {
+    action: 'current';
+    reason: string;
+} | {
+    action: 'regenerate';
+    reason: string;
+    sourceKnowledgeIds: string[];
+} | {
+    action: 'retire';
+    reason: string;
+};
+export interface PromotedExternalStalenessInput {
+    directory: string;
+    skillSlug: string;
+    /** Frontmatter `skill_origin` — must be `promoted_external`. */
+    origin?: string;
+    /** Frontmatter `source_knowledge_ids` (the knowledge entries this skill came from). */
+    sourceKnowledgeIds?: string[];
+    /** Real usage counts (from the #1770 skill-usage signal). */
+    usage: {
+        appliedExplicitCount: number;
+        ignoredCount: number;
+        violatedCount: number;
+    };
+    /**
+     * Caller signals that the source knowledge entries have changed since the
+     * skill was promoted (F5 fix: makes the 'regenerate' action reachable).
+     * The curator compares the source knowledge IDs' current content/revision
+     * against what the skill was compiled from.
+     */
+    sourceChanged?: boolean;
+    /** Days since the skill was last regenerated / promoted. */
+    ageDays: number;
+    /** Configurable floor; defaults to 60. */
+    retirementMinAgeDays: number;
+}
+/**
+ * Parse `source_knowledge_ids`, `skill_origin`, and `promoted_at` from
+ * SKILL.md YAML frontmatter CONTENT. Pure (no I/O) so it is directly testable.
+ * Returns `{}` if frontmatter is absent or unparseable.
+ */
+export declare function parsePromotedExternalFrontmatter(content: string): {
+    origin?: string;
+    sourceKnowledgeIds?: string[];
+    promotedAt?: string;
+};
+/**
+ * Frontmatter helper: read a SKILL.md from disk and parse its frontmatter.
+ * Returns `{}` if absent or unparseable.
+ */
+export declare function readPromotedExternalFrontmatter(skillPath: string): {
+    origin?: string;
+    sourceKnowledgeIds?: string[];
+    promotedAt?: string;
+};
+/**
+ * Evaluate staleness for a promoted-external skill.
+ *
+ * Rules (in priority order):
+ *   1. If source knowledge IDs are present but no longer exist in the knowledge
+ *      store → `retire` (the source has been deleted; keeping a dangling skill
+ *      is worse than retiring).
+ *   2. If the skill has been ignored/violated far more than applied AND has
+ *      passed the minimum age floor → `retire` (real negative usage signal).
+ *   3. If source knowledge IDs are present and still exist but their content
+ *      hash changed since promotion (caller passes `sourceChanged: true`) →
+ *      `regenerate`.
+ *   4. Otherwise → `current`.
+ *
+ * `ageDays < retirementMinAgeDays` blocks retirement (minimum-age safeguard).
+ * Retirement is REVERSIBLE: `retireSkill` records a `retired.marker` and the
+ * skill can be restored (the curator's existing restore path).
+ */
+export declare function evaluatePromotedExternalStaleness(input: PromotedExternalStalenessInput): PromotedExternalStalenessDecision;
+/**
+ * Convenience: build the input for the curator from a skill's frontmatter + the
+ * skill-usage log. The curator already has the usage signal; this just reads
+ * the frontmatter pieces.
+ */
+export declare function buildPromotedExternalInputFromSkill(directory: string, skillSlug: string, usage: PromotedExternalStalenessInput['usage'], ageDays: number, retirementMinAgeDays: number): PromotedExternalStalenessInput | null;

package/dist/services/skill-optimizer/retirement.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Wall-clock retirement gate (Workstream A, issue #1822).
+ *
+ * Uses the REAL usage signal (#1770) plus minimum-age and support safeguards.
+ * Retirement is always REVERSIBLE: `retireSkill` (skill-generator.ts) records a
+ * `retired.marker` and the skill can be restored via the existing restore path.
+ *
+ * Also exposes the explicit `outcomeSignal === 0` (zero-evidence) boundary
+ * classification used by eligibility — distinct from the existing
+ * strongOutcomes test (`tests/unit/services/skill-generator.test.ts:731-758`),
+ * which covers `outcomeSignal === 0` WITH `strongOutcomes=true`. This module
+ * covers the zero-evidence branch (no positives, no negatives) explicitly.
+ */
+import type { RetrievalOutcome } from '../../hooks/knowledge-types.js';
+export type OutcomeSignalClass = 'positive' | 'negative' | 'zero_evidence';
+/**
+ * Classify an outcome signal. The zero-evidence branch (`=== 0` with no
+ * outcomes at all) is distinct from "balanced positives and negatives" —
+ * `computeOutcomeSignal` returns 0 for BOTH cases, but the eligibility gate
+ * treats zero as "neither boost nor penalize" only when there is genuinely no
+ * evidence. Callers that want the strict zero-evidence classification should
+ * pass the raw outcome counts.
+ */
+export declare function classifyOutcomeSignal(outcomes: RetrievalOutcome | undefined): {
+    signal: number;
+    classification: OutcomeSignalClass;
+};
+export interface RetirementEvaluation {
+    retire: boolean;
+    reason: string;
+}
+/**
+ * Evaluate whether a skill should be retired on the wall-clock schedule.
+ *
+ * Safeguards (issue #1822 Workstream A):
+ *   - minimum age: `ageDays >= minAgeDays` (floor, not a trigger);
+ *   - real usage: a decisive negative signal is required (#1770);
+ *   - support: a skill that is still occasionally applied is NOT retired even
+ *     if old (`applied > 0` blocks retirement unless the negative ratio is
+ *     extreme).
+ *
+ * Returns `{ retire: false }` for any skill failing the safeguards. Retirement
+ * is reversible (the caller uses `retireSkill`, which only marks).
+ */
+export declare function evaluateRetirement(args: {
+    usage: {
+        appliedExplicitCount: number;
+        ignoredCount: number;
+        violatedCount: number;
+        failedAfterShownCount: number;
+    };
+    ageDays: number;
+    minAgeDays: number;
+}): RetirementEvaluation;

package/dist/services/skill-optimizer/skill-eval-tasks.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Skill-eval task builder (issue #1822 — D1, critic C1/I4).
+ *
+ * The substrate's `builtin` scorer parses model output as `{caught:boolean}`
+ * JSON and ignores `argv` (`runner.ts:144-162`); only `kind:'project'` scorers
+ * consume `argv` (`runner.ts:175-228`). So the optimizer's skill-eval tasks
+ * use `kind:'project'` scorers that invoke the SHARED `scoreSkillPhrases`
+ * function (factored out of skill-evaluator.ts) via a small wrapper script.
+ *
+ * Rather than ship static fixture manifests with pre-computed `contentHash`
+ * values (fragile — any edit invalidates the hash), this module BUILDS valid
+ * `EvaluationTaskV1` objects at runtime and materializes their fixture files
+ * into a fresh `inputRoot`. The content hash is computed from the materialized
+ * files, guaranteeing consistency.
+ */
+import type { EvaluationTaskV1 } from '../../evaluation/contracts.js';
+/** A skill-eval case expressed as required/forbidden phrases (the gate model). */
+export interface SkillEvalTaskSpec {
+    id: string;
+    category: string;
+    protected?: boolean;
+    instruction: string;
+    requiredPhrases: string[];
+    forbiddenPhrases: string[];
+    /** Environment fixture body the candidate is evaluated against. */
+    environmentBody: string;
+}
+/**
+ * Default skill-eval task set — a minimal, curated set of phrase-based checks
+ * a generated/optimized SKILL.md should satisfy. These are intentionally
+ * generic (they check that a skill declares its trigger, required actions, and
+ * avoids forbidden shortcuts) so they apply across skill slugs. Project-specific
+ * eval cases live under `.swarm/skills/evals/<slug>/` (the existing gate).
+ */
+export declare const DEFAULT_SKILL_EVAL_TASKS: readonly SkillEvalTaskSpec[];
+/**
+ * Materialize a set of skill-eval task specs into a fresh `inputRoot` and
+ * return valid `EvaluationTaskV1[]` (with computed contentHashes). The scorer
+ * points at the bundled `score-skill-eval.cjs` wrapper, which reads the
+ * candidate content + phrase spec via the `SWARM_EVAL_*` env / artifact dir.
+ */
+export declare function buildSkillEvalTasks(args: {
+    inputRoot: string;
+    tasks?: readonly SkillEvalTaskSpec[];
+    /** Repo-relative path to the scorer wrapper (resolved against inputRoot). */
+    scorerRelPath: string;
+}): EvaluationTaskV1[];

package/dist/services/skill-optimizer/smoke.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Skill smoke validator — the `smoke_validated` transition (issue #1822).
+ *
+ * Composes existing primitives rather than duplicating them:
+ *   - `validateSkillPath` (path containment — knowledge-validator.ts);
+ *   - symlink/reparse denial (deny escape; mirrors bundled-skills.ts pattern);
+ *   - frontmatter schema check (YAML parse + required keys);
+ *   - the phrase-eval gate (`evaluateSkillChange` / `isRejectedSkillContent`
+ *     from skill-evaluator.ts) — refuses content the rejection ledger already
+ *     rejected;
+ *   - a bounded subprocess check via `spawnAsync` if the skill declares a
+ *     check command (cwd explicit, stdin ignored, timeout, kill, 512KB cap).
+ */
+import { validateSkillPath } from '../../hooks/knowledge-validator.js';
+import { spawnAsync } from '../../hooks/spawn-helper.js';
+import { evaluateSkillChange, isRejectedSkillContent } from '../skill-evaluator.js';
+export interface SmokeInput {
+    directory: string;
+    skillSlug: string;
+    /** Candidate SKILL.md content (not yet written to the skill root). */
+    candidateContent: string;
+    /** Incumbent SKILL.md content (current). Empty string if no incumbent. */
+    incumbentContent: string;
+    /** Optional check command the skill declares (e.g. `["bun", "test"]`). */
+    checkCommand?: string[];
+    /** Timeout for the optional check command. */
+    checkTimeoutMs?: number;
+}
+export interface SmokeResult {
+    ok: boolean;
+    verdict: 'COMPLIANT' | 'VIOLATED';
+    notes: string[];
+}
+export declare const _internals: {
+    validateSkillPath: typeof validateSkillPath;
+    isSymbolicLink: (p: string) => boolean;
+    escapedRoot: (root: string, target: string) => boolean;
+    realpath: (p: string) => string;
+    evaluateSkillChange: typeof evaluateSkillChange;
+    isRejectedSkillContent: typeof isRejectedSkillContent;
+    spawnAsync: typeof spawnAsync;
+};
+/** Validate a candidate skill before the validation-running transition. */
+export declare function validateSkillSmoke(input: SmokeInput): Promise<SmokeResult>;
+/** Read the incumbent SKILL.md content, or return empty string if absent. */
+export declare function readIncumbentContent(directory: string, skillSlug: string): string;