opencode-swarm 7.62.1 → 7.63.0

package/dist/config/schema.d.ts

@@ -497,6 +497,7 @@ export declare const KnowledgeConfigSchema: z.ZodObject<{
     hive_max_entries: z.ZodDefault<z.ZodNumber>;
     auto_promote_days: z.ZodDefault<z.ZodNumber>;
     max_inject_count: z.ZodDefault<z.ZodNumber>;
+    delegate_max_inject_count: z.ZodDefault<z.ZodNumber>;
     inject_char_budget: z.ZodDefault<z.ZodNumber>;
     context_budget_threshold: z.ZodOptional<z.ZodNumber>;
     max_lesson_display_chars: z.ZodDefault<z.ZodNumber>;
@@ -520,6 +521,13 @@ export declare const KnowledgeConfigSchema: z.ZodObject<{
     default_max_phases: z.ZodDefault<z.ZodNumber>;
     todo_max_phases: z.ZodDefault<z.ZodNumber>;
     sweep_enabled: z.ZodDefault<z.ZodBoolean>;
+    retrieval: z.ZodOptional<z.ZodObject<{
+        mmr_lambda: z.ZodDefault<z.ZodNumber>;
+        cold_start_bonus: z.ZodDefault<z.ZodNumber>;
+        cold_start_max_age_phases: z.ZodDefault<z.ZodNumber>;
+        synonym_min_cooccurrence: z.ZodDefault<z.ZodNumber>;
+        synonym_map_max_pairs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type KnowledgeConfig = z.infer<typeof KnowledgeConfigSchema>;
 export declare const MemoryConfigSchema: z.ZodObject<{
@@ -1264,6 +1272,7 @@ export declare const PluginConfigSchema: z.ZodObject<{
         hive_max_entries: z.ZodDefault<z.ZodNumber>;
         auto_promote_days: z.ZodDefault<z.ZodNumber>;
         max_inject_count: z.ZodDefault<z.ZodNumber>;
+        delegate_max_inject_count: z.ZodDefault<z.ZodNumber>;
         inject_char_budget: z.ZodDefault<z.ZodNumber>;
         context_budget_threshold: z.ZodOptional<z.ZodNumber>;
         max_lesson_display_chars: z.ZodDefault<z.ZodNumber>;
@@ -1287,6 +1296,13 @@ export declare const PluginConfigSchema: z.ZodObject<{
         default_max_phases: z.ZodDefault<z.ZodNumber>;
         todo_max_phases: z.ZodDefault<z.ZodNumber>;
         sweep_enabled: z.ZodDefault<z.ZodBoolean>;
+        retrieval: z.ZodOptional<z.ZodObject<{
+            mmr_lambda: z.ZodDefault<z.ZodNumber>;
+            cold_start_bonus: z.ZodDefault<z.ZodNumber>;
+            cold_start_max_age_phases: z.ZodDefault<z.ZodNumber>;
+            synonym_min_cooccurrence: z.ZodDefault<z.ZodNumber>;
+            synonym_map_max_pairs: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     memory: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;

package/dist/hooks/delegate-ack-collector.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Delegate ack collection (Swarm Learning System, Change 1 / Task 1.5).
+ *
+ * A `tool.execute.after` hook on the `Task` tool. After a delegated subagent
+ * returns, this reconciles the directives that were shown to it (recovered by
+ * parsing the `<delegate_knowledge_directives>` block out of the delegation
+ * prompt) against the ack markers in the subagent's transcript:
+ *
+ *   - For every ack whose ID was actually shown, emit a receipt event of the
+ *     matching type (applied / ignored / violated / n_a). Acks for IDs that were
+ *     never shown are DROPPED (anti-spoofing).
+ *   - For every CRITICAL directive that was shown but never acknowledged, emit a
+ *     `violated` event with reason `unacknowledged` and append an audit line to
+ *     `.swarm/unacknowledged-criticals.jsonl`.
+ *
+ * Stateless by design: it re-parses the prompt rather than relying on
+ * cross-hook mutable state, so it is safe under parallel delegations. Fail-open:
+ * never throws, never blocks.
+ */
+export interface DelegateAckInput {
+    tool: unknown;
+    agent?: unknown;
+    sessionID?: unknown;
+    args?: unknown;
+}
+export interface DelegateAckOutput {
+    output?: unknown;
+}
+export interface CollectDelegateAcksResult {
+    emitted: Array<{
+        id: string;
+        type: string;
+    }>;
+    unacknowledgedCriticals: string[];
+}
+/**
+ * Core reconciliation used by both the runtime hook and tests. Returns a summary
+ * of what was emitted. Never throws.
+ */
+export declare function collectDelegateAcks(params: {
+    directory: string;
+    prompt: string;
+    transcript: string;
+    agent: string;
+    sessionId?: string;
+    taskId?: string;
+}): Promise<CollectDelegateAcksResult>;
+/**
+ * `tool.execute.after` adapter. Reconciles delegate acks for a completed Task.
+ */
+export declare function collectDelegateAcksAfter(directory: string, input: DelegateAckInput, output: DelegateAckOutput): Promise<void>;

package/dist/hooks/delegate-directive-injection.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Architect-side delegate directive injection (Swarm Learning System, Change 1 /
+ * Task 1.4).
+ *
+ * When the architect delegates via the `Task` tool, this `tool.execute.before`
+ * hook prepends the role-scoped `<delegate_knowledge_directives>` block to the
+ * subagent's prompt so the delegate sees the directives (and the ack contract)
+ * from its very first message. It mirrors the existing skill-injection pattern
+ * in src/index.ts, which already mutates `input.args.prompt`.
+ *
+ * This is ADVISORY (prompt enrichment): it must never throw or block a
+ * delegation. A retrieval failure simply leaves the prompt unchanged.
+ *
+ * NOTE on plan deviation: the implementation plan listed `src/agents/architect.ts`
+ * as the "delegation prompt builder". The architect is prompt-driven — real
+ * delegations are constructed by the model at runtime via the Task tool, so the
+ * code-accurate interception point is this hook, not the architect prompt
+ * template. The architect's own `<swarm_knowledge_directives>` injection is
+ * untouched.
+ */
+import type { KnowledgeConfig } from './knowledge-types.js';
+export interface DelegateInjectionInput {
+    tool: unknown;
+    agent?: unknown;
+    sessionID?: unknown;
+    args?: unknown;
+}
+/**
+ * Prepend the per-delegate directive block to a Task delegation's prompt.
+ * Returns the number of directives injected (0 when nothing was injected),
+ * primarily for test assertions. Never throws.
+ */
+export declare function injectDelegateDirectivesBefore(directory: string, input: DelegateInjectionInput, config: KnowledgeConfig): Promise<number>;

package/dist/hooks/knowledge-application.d.ts

@@ -8,15 +8,16 @@
 import type { KnowledgeApplicationResult } from './knowledge-types.js';
 export declare function resolveApplicationLogPath(directory: string): string;
 /**
- * Parse explicit knowledge-acknowledgment markers from architect text.
+ * Parse explicit knowledge-acknowledgment markers from architect/delegate text.
  * Recognised forms (case-insensitive, line-anchored or inline):
  *   KNOWLEDGE_APPLIED: <id>
  *   KNOWLEDGE_IGNORED: <id> reason=<reason>
  *   KNOWLEDGE_VIOLATED: <id> reason=<reason>
+ *   KNOWLEDGE_N_A: <id> reason=<reason>   (delegate contract, Change 1)
  */
 export interface ParsedAcknowledgment {
     id: string;
-    result: 'applied' | 'ignored' | 'violated';
+    result: 'applied' | 'ignored' | 'violated' | 'n_a';
     reason?: string;
 }
 export declare function parseAcknowledgments(text: string): ParsedAcknowledgment[];
@@ -38,7 +39,7 @@ export declare function recordKnowledgeShown(directory: string, ids: string[], c
 export declare function recordAcknowledgment(directory: string, ack: ParsedAcknowledgment, ctx: RecordContext): Promise<void>;
 /** Build the dedup key. Exported so test code and the runtime integration
  *  share the exact format. */
-export declare function buildAckDedupKey(sessionId: string, id: string, result: KnowledgeApplicationResult, now?: Date): string;
+export declare function buildAckDedupKey(sessionId: string, id: string, result: KnowledgeApplicationResult | 'n_a', now?: Date): string;
 /** Acknowledgment recording with dedup. Returns whether a record was actually
  *  written (false on dedup hit). dedupSet should be swarmState.knowledgeAckDedup
  *  in production; tests can pass a fresh Set. */

package/dist/hooks/knowledge-curator.d.ts

@@ -1,10 +1,68 @@
 /** Knowledge curator hook for opencode-swarm v6.17 two-tier knowledge system. */
-import type { KnowledgeConfig } from './knowledge-types.js';
+import type { CuratorLLMDelegate } from './curator.js';
+import type { ActionableDirectiveFields, KnowledgeConfig, SwarmKnowledgeEntry } from './knowledge-types.js';
+import { type InsightCandidate } from './micro-reflector.js';
+declare const seenRetroSections: Map<string, {
+    value: string;
+    timestamp: number;
+}>;
+/**
+ * Bound seenRetroSections to MAX_TRACKED_RETRO_SECTIONS entries, evicting the
+ * oldest-timestamp entries first. Called after every insert so the map can never
+ * exceed the cap regardless of how many distinct sessions appear within the
+ * 24-hour prune window.
+ */
+declare function capSeenRetroSections(): void;
+/** Record a seen-section hash and enforce the size cap in one step. */
+declare function recordSeenRetroSection(key: string, value: string, timestamp: number): void;
 /**
  * Check if the input is a write operation targeting an evidence file.
  * Exported for testing purposes only.
  */
 export declare function isWriteToEvidenceFile(input: unknown): boolean;
+/** Build the v3-schema enrichment prompt for a single prose lesson. */
+export declare function buildV3EnrichmentPrompt(lesson: string, category: string, tags: string[]): string;
+/**
+ * Parse + validate an enrichment response. Returns the sanitized fields when
+ * the output is shape-valid AND actionable, otherwise the list of missing
+ * requirements (for the RETRY follow-up). Untrusted-input hardened: only
+ * allowlisted fields are copied, then shape-validated by
+ * validateActionableFields (length caps, name patterns, injection checks).
+ */
+export declare function parseV3EnrichmentResponse(text: string): {
+    fields: ActionableDirectiveFields;
+} | {
+    missing: string[];
+};
+export interface EnrichmentQuotaOptions {
+    maxCalls: number;
+    window: 'utc' | 'local';
+}
+/**
+ * Enrich one prose lesson with v3 actionability fields via the curator LLM.
+ * One retry on schema failure (with a RETRY message naming the missing
+ * fields). Quota-gated per call via skill-improver-quota. Returns null when
+ * enrichment is unavailable (quota exhausted) or fails twice — the caller
+ * quarantines the entry. Never throws.
+ */
+export declare function enrichLessonToV3(params: {
+    directory: string;
+    llmDelegate: CuratorLLMDelegate;
+    lesson: string;
+    category: string;
+    tags: string[];
+    quota?: EnrichmentQuotaOptions;
+}): Promise<ActionableDirectiveFields | null>;
+/** Max insight candidates folded into the store per phase boundary. */
+export declare const MESO_INSIGHT_BATCH_LIMIT = 20;
+/**
+ * Atomically consume up to `batchLimit` insight candidates from
+ * `.swarm/insight-candidates.jsonl`, writing back the unconsumed tail under the
+ * same lock so concurrent micro-reflection appends are never lost. Fail-open.
+ */
+export declare function consumeInsightCandidates(directory: string, batchLimit?: number): Promise<InsightCandidate[]>;
+/** Build a SwarmKnowledgeEntry from an already-v3-actionable insight candidate. */
+export declare function insightCandidateToEntry(cand: InsightCandidate, projectName: string, phaseNumber: number, config: KnowledgeConfig): SwarmKnowledgeEntry;
 /**
  * Curate and store swarm knowledge entries from lessons.
  * @returns Promise resolving to an object with counts of stored, skipped, and rejected lessons.
@@ -13,10 +71,19 @@ export declare function curateAndStoreSwarm(lessons: string[], projectName: stri
     phase_number: number;
 }, directory: string, config: KnowledgeConfig, options?: {
     skipAutoPromotion?: boolean;
+    /**
+     * Change 4 (Task 4.2): LLM delegate used to enrich plain-prose lessons
+     * with v3 actionability fields before the Layer-5 gate. When absent,
+     * non-actionable lessons go straight to the unactionable queue.
+     */
+    llmDelegate?: CuratorLLMDelegate;
+    /** Quota knobs for enrichment calls (defaults: 10/day, utc window). */
+    enrichmentQuota?: EnrichmentQuotaOptions;
 }): Promise<{
     stored: number;
     skipped: number;
     rejected: number;
+    quarantined: number;
 }>;
 /**
  * Auto-promote swarm entries based on phase confirmations and age.
@@ -32,4 +99,9 @@ export declare const _internals: {
     curateAndStoreSwarm: typeof curateAndStoreSwarm;
     runAutoPromotion: typeof runAutoPromotion;
     createKnowledgeCuratorHook: typeof createKnowledgeCuratorHook;
+    seenRetroSections: typeof seenRetroSections;
+    recordSeenRetroSection: typeof recordSeenRetroSection;
+    capSeenRetroSections: typeof capSeenRetroSections;
+    MAX_TRACKED_RETRO_SECTIONS: number;
 };
+export {};

package/dist/hooks/knowledge-escalator.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Repeat-mistake escalator (Swarm Learning System, Change 3 / Task 3.2).
+ *
+ * When the same directive is violated >= {@link ESCALATION_THRESHOLD} times
+ * within {@link ESCALATION_WINDOW_DAYS} days (across sessions), it is
+ * auto-promoted to `directive_priority:'critical'` + `enforcement_mode:'enforce'`,
+ * its `escalation_history` gets a `repeat_violation` record, and an `escalation`
+ * event is emitted. Idempotent: an entry already at critical/enforce is never
+ * re-escalated, even on subsequent violations.
+ *
+ * Persistence goes through `rewriteKnowledge` (never a raw JSONL write). Fail-open:
+ * any error leaves the entry untouched and returns `escalated:false`.
+ */
+import type { DirectivePriority } from './knowledge-types.js';
+export declare const ESCALATION_WINDOW_DAYS = 30;
+export declare const ESCALATION_THRESHOLD = 2;
+export interface EscalationResult {
+    escalated: boolean;
+    entryId: string;
+    from?: DirectivePriority;
+    to?: DirectivePriority;
+    violationsInWindow?: number;
+    /** True when the entry was already critical/enforce (no-op, idempotent). */
+    alreadyEscalated?: boolean;
+}
+/**
+ * Evaluate and (if warranted) apply a repeat-violation escalation to a single
+ * entry. Call AFTER the triggering `violated` event has been persisted.
+ */
+export declare function maybeEscalateOnViolation(directory: string, entryId: string, now?: Date): Promise<EscalationResult>;
+export interface RecentEscalation {
+    entry_id: string;
+    from: string;
+    to: string;
+    reason: string;
+    at: string;
+}
+export declare const ESCALATION_DISPLAY_WINDOW_DAYS = 7;
+/**
+ * Read escalation events from the last `windowDays` days, newest first. Used by
+ * the architect briefing and `/swarm status`. Fail-open: returns [] on error.
+ */
+export declare function readRecentEscalations(directory: string, windowDays?: number, now?: Date): Promise<RecentEscalation[]>;
+/**
+ * Render the architect-briefing "Recently Escalated" subsection. Returns null
+ * when there is nothing to show (no empty header).
+ */
+export declare function buildEscalationBriefing(escalations: RecentEscalation[], windowDays?: number): string | null;
+/** Run the escalator for several entry IDs (deduped). Never throws. */
+export declare function escalateViolatedEntries(directory: string, entryIds: string[], now?: Date): Promise<EscalationResult[]>;

package/dist/hooks/knowledge-events.d.ts

@@ -29,7 +29,11 @@ export declare const KNOWLEDGE_EVENT_SCHEMA_VERSION = 1;
  */
 export declare const MAX_EVENT_LOG_ENTRIES = 5000;
 /** Retrieval modes that surface knowledge to an agent. */
-export type RetrievalEventMode = 'manual' | 'auto_injection' | 'coder_context' | 'review_context' | 'curator';
+export type RetrievalEventMode = 'manual' | 'auto_injection' | 'coder_context' | 'review_context' | 'curator'
+/** Per-delegate directive injection (Change 1): a delegated subagent
+ *  (coder/reviewer/test_engineer/sme/docs/designer/critic/curator) was shown
+ *  the subset of directives scoped to its role + expected tools. */
+ | 'delegate_inject';
 /** A retrieval: a query returned a ranked set of knowledge entries. */
 export interface RetrievedEvent {
     type: 'retrieved';
@@ -52,7 +56,13 @@ export interface RetrievedEvent {
 }
 /** A receipt: an agent explicitly considered a specific knowledge entry. */
 export interface ReceiptEvent {
-    type: 'acknowledged' | 'applied' | 'ignored' | 'contradicted' | 'violated';
+    type: 'acknowledged' | 'applied' | 'ignored' | 'contradicted' | 'violated'
+    /** Delegate decided a shown directive did not apply to its task (Change 1).
+     *  Recorded for auditability; never penalizes the entry's outcome signal. */
+     | 'n_a'
+    /** Architect explicitly accepted an unresolved critical violation at
+     *  phase_complete (Change 2, Task 2.4). Audit-only; never affects rollups. */
+     | 'override';
     schema_version?: number;
     event_id: string;
     trace_id: string;
@@ -63,6 +73,19 @@ export interface ReceiptEvent {
     task_id?: string;
     agent: string;
     reason?: string;
+    /**
+     * Origin discriminator (Change 2). Distinguishes reviewer-issued verdicts
+     * (`'reviewer'`) from delegate self-acks (`'delegate'`) without changing the
+     * `type`, so existing counter rollups (which switch on `type`) stay intact.
+     * A reviewer VERIFIED maps to type:'applied' with source:'reviewer'.
+     */
+    source?: 'delegate' | 'reviewer' | string;
+    /** Result of executing a directive's verification_predicate (Change 2). */
+    predicate_check?: {
+        predicate: string;
+        result: 'pass' | 'fail' | 'error';
+        detail: string;
+    };
     evidence?: {
         files?: string[];
         commands?: string[];
@@ -96,7 +119,19 @@ export interface ArchivedEvent {
     evidence?: string;
     previous_status?: string;
 }
-export type KnowledgeEvent = RetrievedEvent | ReceiptEvent | OutcomeEvent | ArchivedEvent;
+/** An escalation: a directive was auto-promoted by the repeat-mistake escalator. */
+export interface EscalationEvent {
+    type: 'escalation';
+    schema_version?: number;
+    event_id: string;
+    timestamp: string;
+    entry_id: string;
+    from: string;
+    to: string;
+    reason: string;
+    enforcement_mode?: string;
+}
+export type KnowledgeEvent = RetrievedEvent | ReceiptEvent | OutcomeEvent | ArchivedEvent | EscalationEvent;
 export type KnowledgeEventType = KnowledgeEvent['type'];
 /**
  * Event shape accepted by {@link appendKnowledgeEvent} / {@link recordKnowledgeEvent}.
@@ -154,6 +189,9 @@ export interface CounterRollup {
     ignored_count: number;
     violated_count: number;
     contradicted_count: number;
+    /** Count of explicit not-applicable decisions (Change 1). Auditable, neutral:
+     *  never contributes to the outcome ranking signal. */
+    n_a_count: number;
     succeeded_after_shown_count: number;
     failed_after_shown_count: number;
     /**
@@ -164,7 +202,15 @@ export interface CounterRollup {
     partial_after_shown_count: number;
     last_applied_at?: string;
     last_acknowledged_at?: string;
+    /**
+     * The most recent violation timestamps for this entry (ISO 8601, newest
+     * first, capped at the last {@link MAX_VIOLATION_TIMESTAMPS}). Feeds the
+     * repeat-mistake escalator (Change 3).
+     */
+    violation_timestamps: string[];
 }
+/** Cap on retained per-entry violation timestamps. */
+export declare const MAX_VIOLATION_TIMESTAMPS = 10;
 /**
  * Recompute per-entry counters deterministically from the immutable event log,
  * optionally folding in legacy `knowledge-application.jsonl` records.
@@ -189,6 +235,20 @@ export interface CounterRollup {
  * @param legacyRecords Optional legacy application records (any order).
  */
 export declare function recomputeCounters(events: KnowledgeEvent[], legacyRecords?: KnowledgeApplicationRecord[]): Map<string, CounterRollup>;
+/**
+ * Count how many of the given violation timestamps fall within `windowDays` of
+ * `now` (inclusive). Pure helper — deterministic given its inputs. Malformed
+ * timestamps are ignored.
+ */
+export declare function countViolationsInWindow(timestamps: string[], windowDays: number, now?: Date): number;
+/**
+ * Async convenience: count an entry's violations within a day-window. Counts
+ * directly from the event log + legacy application records so the result is
+ * INDEPENDENT of the {@link MAX_VIOLATION_TIMESTAMPS} display cap (the rollup's
+ * `violation_timestamps` keeps only the newest 10 and would undercount an entry
+ * with more in-window violations). Fail-open: returns 0 on error.
+ */
+export declare function countEntryViolationsInWindow(directory: string, entryId: string, windowDays: number, now?: Date): Promise<number>;
 /**
  * Fail-open rollup reader for hot paths. Search and promotion use this instead
  * of stale persisted counters so `knowledge_receipt` feedback affects ranking

package/dist/hooks/knowledge-injector.d.ts

@@ -7,8 +7,76 @@
  */
 import { recordKnowledgeShown } from './knowledge-application.js';
 import { recordKnowledgeEvent } from './knowledge-events.js';
-import type { KnowledgeConfig, MessageWithParts } from './knowledge-types.js';
+import type { RankedEntry } from './knowledge-reader.js';
+import type { DirectivePriority, KnowledgeConfig, MessageWithParts } from './knowledge-types.js';
 import { searchKnowledge } from './search-knowledge.js';
+/** Marker that uniquely identifies the delegate directive block in a transcript. */
+export declare const DELEGATE_DIRECTIVE_BLOCK_TAG = "<delegate_knowledge_directives>";
+/**
+ * Render a sanitized, deterministic `<delegate_knowledge_directives>` block for
+ * a delegated subagent (Change 1, Task 1.3). Entries are sorted by priority
+ * (critical first) then ID so the block is stable across runs and prompt caches
+ * remain warm. Returns null when there are no entries (no empty wrapper).
+ */
+export declare function buildDelegateDirectiveBlock(entries: RankedEntry[], cfg: KnowledgeConfig): string | null;
+/** A directive that was rendered into a delegate block, recovered by parsing. */
+export interface ShownDelegateDirective {
+    id: string;
+    priority: DirectivePriority;
+}
+/**
+ * Recover the directive IDs (and priorities) that were rendered into a
+ * `<delegate_knowledge_directives>` block. Used by the ack-collector
+ * (Task 1.5) to reconcile a delegate's ack markers against what was actually
+ * shown — only IDs present here are honored, so a delegate cannot fabricate an
+ * ack for a directive it never received. Returns [] when no block is present.
+ */
+export declare function parseDelegateDirectiveBlock(text: string): ShownDelegateDirective[];
+export interface InjectForDelegateParams {
+    directory: string;
+    agent: string;
+    expectedTools?: string[];
+    taskTitle?: string;
+    sessionId?: string;
+    config: KnowledgeConfig;
+    /**
+     * Phase label recorded on the emitted `delegate_inject` event. Threading the
+     * real plan phase (rather than the task title) lets the reviewer verdict loop
+     * and the phase-complete gate window directives by phase (Change 2).
+     */
+    phase?: string;
+    /** Test seam: override the search function. Defaults to the live one. */
+    searchFn?: typeof searchKnowledge;
+}
+export interface InjectForDelegateResult {
+    entries: RankedEntry[];
+    trace_id: string;
+}
+/**
+ * Retrieve the subset of active knowledge directives scoped to a delegated
+ * subagent's role + expected tools (Change 1, Task 1.2). Emits a single
+ * `retrieved` event tagged `mode:'delegate_inject'` with the capped, in-scope
+ * entry IDs. Fail-open: any error yields an empty result.
+ */
+export declare function injectForDelegate(params: InjectForDelegateParams): Promise<InjectForDelegateResult>;
+/** Returns true if this agent is the architect (the sole intended recipient of orchestrator-tier knowledge injection). */
+export declare function isOrchestratorAgent(agentName: string): boolean;
+/**
+ * Returns true if this agent is a delegated subagent that should receive the
+ * per-agent directive block. Swarm prefixes (e.g. `mega_coder`) are stripped so
+ * prefixed agent names still match their canonical role.
+ */
+export declare function isDelegatedAgent(agentName: string): boolean;
+/** Returns the default expected-tools list for a delegated agent role. */
+export declare function defaultExpectedToolsForAgent(agentName: string): string[];
+/**
+ * Per-delegate scope match implementing the Change-1 OR semantics: an entry is
+ * in scope for a delegate when it is untargeted (no agent and no tool scope),
+ * OR its `applies_to_agents` includes the delegate's role, OR its
+ * `applies_to_tools` intersects the delegate's expected tools. Swarm prefixes
+ * are stripped on both sides so `mega_coder` matches a bare `coder`.
+ */
+export declare function matchesDelegateScope(entry: Pick<RankedEntry, 'applies_to_agents' | 'applies_to_tools'>, role: string, expectedTools: readonly string[]): boolean;
 /**
  * Creates a knowledge injection hook that injects relevant knowledge into the
  * architect's message context at phase start. Supports caching for re-injection

package/dist/hooks/knowledge-types.d.ts

@@ -43,9 +43,19 @@ export interface RetrievalOutcome {
     succeeded_after_shown_count?: number;
     /** v2: phase-failure count after a "shown" (replaces failed_after_count). */
     failed_after_shown_count?: number;
+    /** v3: recent violation timestamps (newest-first, capped) folded from the
+     *  event-derived rollup. Surfaced for the repeat-mistake escalator. */
+    violation_timestamps?: string[];
 }
 /** v2: priority used by retrieval ranking and enforcement. */
 export type DirectivePriority = 'low' | 'medium' | 'high' | 'critical';
+/** One automatic escalation applied to a directive (Change 3). */
+export interface DirectiveEscalationRecord {
+    from: DirectivePriority;
+    to: DirectivePriority;
+    reason: 'repeat_violation' | string;
+    at: string;
+}
 /** v2: optional actionable-directive metadata attached to a knowledge entry. */
 export interface ActionableDirectiveFields {
     /** Trigger phrases that surface this entry (e.g. "coder delegation modifying source"). */
@@ -60,6 +70,15 @@ export interface ActionableDirectiveFields {
     applies_to_tools?: string[];
     /** Reviewer/test-engineer/runtime checks the directive expects. */
     verification_checks?: string[];
+    /**
+     * A single machine-checkable verification predicate (Change 2). DSL:
+     *   grep:<regex>:<path-glob>      pass when ripgrep finds zero matches
+     *   tool:<argv>                   pass when the (allowlisted, shell-free) command exits 0
+     *   file_not_modified:<path>      pass when the path is unchanged in the working tree
+     *   file_modified:<path>          pass when the path is changed in the working tree
+     * Runs fail-closed (parse error → error) with a hard 15s timeout, no shell.
+     */
+    verification_predicate?: string;
     /** Source pointers (file:line, plan section, etc.). Sanitized. */
     source_refs?: string[];
     /** UUIDs of source knowledge entries (for derived/clustered entries). */
@@ -70,6 +89,14 @@ export interface ActionableDirectiveFields {
     generated_skill_path?: string;
     /** Directive priority for ranking/enforcement. */
     directive_priority?: DirectivePriority;
+    /**
+     * Enforcement posture (Change 3). `'enforce'` makes the directive block at the
+     * point of violation; `'warn'` only records. Auto-set to `'enforce'` by the
+     * repeat-mistake escalator.
+     */
+    enforcement_mode?: 'warn' | 'enforce';
+    /** Audit trail of automatic escalations applied to this directive (Change 3). */
+    escalation_history?: DirectiveEscalationRecord[];
     /** ISO 8601 timestamp of last explicit application. */
     last_applied_at?: string;
     /** ISO 8601 timestamp of last explicit acknowledgment. */
@@ -83,7 +110,10 @@ export interface KnowledgeEntryBase extends ActionableDirectiveFields {
     tags: string[];
     scope: string;
     confidence: number;
-    status: 'candidate' | 'established' | 'promoted' | 'archived' | 'quarantined';
+    status: 'candidate' | 'established' | 'promoted' | 'archived' | 'quarantined'
+    /** Change 4: failed the actionability layer (no predicate or no scope tag).
+     *  Held out of the active store pending hardening by the skill-improver. */
+     | 'quarantined_unactionable';
     confirmed_by: PhaseConfirmationRecord[] | ProjectConfirmationRecord[];
     retrieval_outcomes: RetrievalOutcome;
     schema_version: number;
@@ -128,6 +158,8 @@ export interface KnowledgeConfig {
     auto_promote_days: number;
     /** Maximum knowledge entries to inject per architect message. Default: 5 */
     max_inject_count: number;
+    /** Maximum knowledge directives injected into a delegated subagent's prompt. Default: 8 */
+    delegate_max_inject_count?: number;
     /** Maximum total chars for the entire injection block. Default: 2000 */
     inject_char_budget?: number;
     /** Minimum headroom chars required before knowledge injection activates. Default: 300 */
@@ -172,6 +204,14 @@ export interface KnowledgeConfig {
     todo_max_phases: number;
     /** Enable age-based sweep of knowledge entries. Default: true */
     sweep_enabled: boolean;
+    /** Change 5: retrieval-upgrade tuning (MMR / cold-start / synonyms). */
+    retrieval?: {
+        mmr_lambda?: number;
+        cold_start_bonus?: number;
+        cold_start_max_age_phases?: number;
+        synonym_min_cooccurrence?: number;
+        synonym_map_max_pairs?: number;
+    };
 }
 export interface MessageInfo {
     role: string;

package/dist/hooks/knowledge-validator.d.ts

@@ -30,6 +30,44 @@ export declare function validateSkillPath(p: unknown): boolean;
 /** Validate the optional ActionableDirectiveFields block on a knowledge entry. */
 export declare function validateActionableFields(fields: ActionableDirectiveFields | undefined): ActionableValidationResult;
 export type { ActionableDirectiveFields, DirectivePriority };
+export interface ActionabilityResult {
+    actionable: boolean;
+    /** Present only when not actionable. */
+    reason?: 'missing_predicate' | 'missing_scope' | 'missing_predicate_and_scope';
+}
+/**
+ * Layer 5: an entry is actionable only when it carries at least one
+ * machine-checkable predicate AND at least one scope tag.
+ *
+ *   predicate := forbidden_actions | required_actions | verification_checks
+ *                | verification_predicate
+ *   scope     := applies_to_tools | applies_to_agents
+ *
+ * Plain-prose lessons (no predicate, no scope) are NOT actionable and must be
+ * quarantined rather than activated.
+ */
+export declare function validateActionability(entry: Pick<KnowledgeEntryBase, 'forbidden_actions' | 'required_actions' | 'verification_checks' | 'verification_predicate' | 'applies_to_tools' | 'applies_to_agents'>): ActionabilityResult;
+/** Returns `.swarm/knowledge-unactionable.jsonl` for the given directory. */
+export declare function resolveUnactionablePath(directory: string): string;
+/** One quarantined-unactionable record. */
+export interface UnactionableRecord extends KnowledgeEntryBase {
+    status: 'quarantined_unactionable';
+    unactionable_reason: string;
+    quarantined_at: string;
+}
+/**
+ * Persist an entry that failed the actionability layer to the unactionable
+ * queue (held out of the active store, pending hardening by the skill-improver).
+ * FIFO-capped at 200. Best-effort: throws only on lock failure for tests.
+ *
+ * Flooding tradeoff (Phase 4 review): duplicate prose lessons are NOT deduped
+ * at queue time, so a looping producer can fill the queue with duplicates and
+ * FIFO-evict older legitimate records. Accepted because (a) the cap bounds the
+ * damage at 200 records of plain text, (b) the hardening loop's promotion path
+ * dedups at commit time against the active store, and (c) queue producers are
+ * themselves quota- or phase-bounded. Revisit if telemetry shows real evictions.
+ */
+export declare function appendUnactionable(directory: string, entry: KnowledgeEntryBase, reason: string): Promise<void>;
 export interface QuarantinedEntry extends KnowledgeEntryBase {
     original_status: string;
     quarantine_reason: string;