agent-nuvira 3.3.0 → 3.3.1

package/dist/learning/run-trace.d.ts

@@ -0,0 +1,164 @@
+/**
+ * The Run Trace — the loop's representation of ITS OWN behaviour.
+ *
+ * WHY THIS EXISTS (the "it took no concern out of it" audit):
+ *
+ * A user asked agent-nuvira, in as many words, "why are you asking me this again
+ * and again?" — and the turn did not acknowledge it. Not because the model was
+ * incapable, but because **nothing in the architecture held the fact that it had
+ * asked four times**. The loop's counters measure the loop's own NUDGES
+ * (`permissionNudges < 1`), not the model's repeated questions; the gates judge
+ * the CURRENT step's text; and the transcript is not a data structure anything
+ * reasons over. So the agent could not notice a loop, could not answer a
+ * question about one, and could not stop one.
+ *
+ * That is the whole difference between an agent that reviews its own actions and
+ * one that merely executes a pipeline: a REPRESENTATION of the run. This module
+ * is it. Every question the agent asks is recorded with a *shape*, every refused
+ * tool call is recorded with its reason, and every mutation is recorded with its
+ * target — so the run can answer three questions it previously could not:
+ *
+ *   1. "Have I already asked this?"  -> the repetition gate refuses to re-ask.
+ *   2. "What did the user answer?"   -> the earlier answer is handed back.
+ *   3. "Why are you asking again?"   -> a self-report the model answers FROM.
+ *
+ * SCOPE: per CONVERSATION, like the intent envelope — the dashboard console
+ * keeps one plan store per session and re-injects it every turn, so the trace
+ * outlives the turn and a loop across turns is visible. Storage is bounded (the
+ * last N entries), so a long conversation cannot grow it without limit.
+ *
+ * DELIBERATELY DETERMINISTIC AND LLM-FREE: like `autonomy-policy.ts`, this is a
+ * guard rail around a model's own instinct. Asking a model "are you looping?" on
+ * every step is both expensive and unreliable; counting is neither. The model is
+ * asked to INTERPRET the trace only when the user asks about it.
+ */
+/** The salient content of a question — what it is actually about. */
+export interface QuestionShape {
+    /** Explicit targets: backticked text, file paths, command names. */
+    targets: string[];
+    /** Significant words, boilerplate removed. */
+    tokens: string[];
+}
+/**
+ * Reduce a question to its salient shape.
+ *
+ * Targets are the strongest signal: if two questions both name `node -c
+ * script.js`, they are the same ask however differently they are phrased. Tokens
+ * are the fallback for a question with no explicit target.
+ */
+export declare function questionShape(question: string): QuestionShape;
+/** Above this overlap two questions are treated as the same ask. */
+export declare const SAME_QUESTION_OVERLAP = 0.6;
+/**
+ * Is this the same question as an earlier one?
+ *
+ * Targets first — a shared target means the same thing is being asked about,
+ * which is the reliable signal ("May I run `node -c script.js`?" vs "Run a
+ * JavaScript syntax check (`node -c script.js`)?"). Only when neither has a
+ * target does token overlap decide, so a genuinely different question with the
+ * same shape ("which runtime?" … "which database?") is not counted as a repeat.
+ */
+export declare function isSameQuestion(a: QuestionShape, b: QuestionShape): boolean;
+/** One question the agent asked. */
+interface AskRecord {
+    question: string;
+    shape: QuestionShape;
+    /** False when the gate settled it without showing the user. */
+    shown: boolean;
+    /** The user's answer, when there was one. */
+    answer?: string;
+    at: number;
+}
+/** How many of each record the trace keeps (bounded — a long run must not grow). */
+export declare const MAX_TRACE_ENTRIES = 60;
+/** The trace's counts, as data (see {@link RunTrace.snapshot}). */
+export interface RunTraceSnapshot {
+    /** Questions the agent asked, including the ones a gate suppressed. */
+    asks: number;
+    /** Questions that actually reached the user — the interruptions they felt. */
+    shownAsks: number;
+    /** Questions that repeated one already asked (the loop signal). */
+    repeatedAsks: number;
+    /** Tool calls refused, by any gate. */
+    refusals: number;
+    /** Workspace mutations applied. */
+    mutations: number;
+    /** The distinct files changed. */
+    paths: string[];
+}
+/**
+ * The run's own behaviour, as data.
+ *
+ * A class (not a plain array) because every consumer asks a QUESTION of it —
+ * "have I asked this?", "what was the answer?", "did I loop?" — and those
+ * questions should be answered in one place rather than re-derived by each
+ * caller.
+ */
+export declare class RunTrace {
+    private asks;
+    private refusals;
+    private mutations;
+    /** Prior asks that are the SAME question as this one (excluding it). */
+    priorAskMatches(question: string): AskRecord[];
+    /** The most recent SHOWN answer to this question, if the user gave one. */
+    priorAnswer(question: string): string | undefined;
+    /** Record that the agent asked something, and whether the user saw it. */
+    recordAsk(question: string, shown: boolean, answer?: string): void;
+    /** Prior refusals of the SAME tool for the SAME reason. */
+    priorRefusalMatches(tool: string, detail: string): number;
+    recordRefusal(tool: string, reason: string, detail: string): void;
+    recordMutation(tool: string, path?: string): void;
+    countAsks(): number;
+    countShownAsks(): number;
+    /**
+     * How many questions were asked more than once. The single number that says
+     * "this run looped on the conversation" — and the metric the fix is judged by.
+     */
+    repeatedAskCount(): number;
+    /**
+     * The counts, as a plain object — for surfaces that need the NUMBERS rather
+     * than the prose (the loop's result, the eval metric, the dashboard badge).
+     *
+     * `shownAsks` is the one that matters to a user: how many times the run
+     * actually stopped and asked them something. `asks` counts attempts, which is
+     * the number a gate can influence before the user ever sees it.
+     */
+    snapshot(): RunTraceSnapshot;
+    /** Distinct questions, each with how many times it was asked and its answer. */
+    askSummary(): Array<{
+        question: string;
+        times: number;
+        answer?: string;
+    }>;
+    distinctMutationPaths(): string[];
+    /**
+     * The trace as text, for the model to answer FROM.
+     *
+     * Written for a reader that must not mistake it for a summary of the work: it
+     * describes the agent's OWN behaviour, so the number it leads with is the one
+     * a stuck run needs to see — how often it repeated itself.
+     */
+    selfReport(): string;
+}
+/**
+ * The correction handed back when the turn closes on a question the user has
+ * ALREADY answered.
+ *
+ * Deliberately does NOT say "proceed": a bare order to carry on would be unsafe
+ * when the answer was "no". It says the answer is already in hand — so act on
+ * it, or state plainly what blocks you. That is the difference between stopping
+ * a loop and bulldozing a decision.
+ */
+export declare function repeatNudge(question: string, answer?: string): string;
+/** Is the user asking about the agent's own behaviour? */
+export declare function detectProcessComplaint(text: string): boolean;
+/** Is this object usable as a trace key (a session handle)? */
+export declare function isTraceKey(key: unknown): key is object;
+/** The trace for a conversation, created on first use. */
+export declare function runTraceFor(key: object): RunTrace;
+/** The trace for a conversation, or undefined when none exists yet. */
+export declare function peekRunTrace(key: object | undefined): RunTrace | undefined;
+/** Drop the trace (the conversation ended). */
+export declare function clearRunTrace(key: object | undefined): void;
+export {};
+//# sourceMappingURL=run-trace.d.ts.map

package/dist/learning/run-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-trace.d.ts","sourceRoot":"","sources":["../../src/learning/run-trace.ts"],"names":[],"mappings":"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"}

package/dist/learning/run-trace.js

@@ -0,0 +1,342 @@
+/**
+ * The Run Trace — the loop's representation of ITS OWN behaviour.
+ *
+ * WHY THIS EXISTS (the "it took no concern out of it" audit):
+ *
+ * A user asked agent-nuvira, in as many words, "why are you asking me this again
+ * and again?" — and the turn did not acknowledge it. Not because the model was
+ * incapable, but because **nothing in the architecture held the fact that it had
+ * asked four times**. The loop's counters measure the loop's own NUDGES
+ * (`permissionNudges < 1`), not the model's repeated questions; the gates judge
+ * the CURRENT step's text; and the transcript is not a data structure anything
+ * reasons over. So the agent could not notice a loop, could not answer a
+ * question about one, and could not stop one.
+ *
+ * That is the whole difference between an agent that reviews its own actions and
+ * one that merely executes a pipeline: a REPRESENTATION of the run. This module
+ * is it. Every question the agent asks is recorded with a *shape*, every refused
+ * tool call is recorded with its reason, and every mutation is recorded with its
+ * target — so the run can answer three questions it previously could not:
+ *
+ *   1. "Have I already asked this?"  -> the repetition gate refuses to re-ask.
+ *   2. "What did the user answer?"   -> the earlier answer is handed back.
+ *   3. "Why are you asking again?"   -> a self-report the model answers FROM.
+ *
+ * SCOPE: per CONVERSATION, like the intent envelope — the dashboard console
+ * keeps one plan store per session and re-injects it every turn, so the trace
+ * outlives the turn and a loop across turns is visible. Storage is bounded (the
+ * last N entries), so a long conversation cannot grow it without limit.
+ *
+ * DELIBERATELY DETERMINISTIC AND LLM-FREE: like `autonomy-policy.ts`, this is a
+ * guard rail around a model's own instinct. Asking a model "are you looping?" on
+ * every step is both expensive and unreliable; counting is neither. The model is
+ * asked to INTERPRET the trace only when the user asks about it.
+ */
+/**
+ * Words that carry no signal about WHAT is being asked — permission boilerplate
+ * and ordinary English. Stripping them is what lets "May I run `node -c
+ * script.js` to verify?" and "Run a JavaScript syntax check (`node -c
+ * script.js`)?" collapse to the same question.
+ */
+const STOPWORDS = new Set([
+    'the', 'and', 'you', 'your', 'yours', 'for', 'with', 'that', 'this', 'these', 'those',
+    'are', 'was', 'were', 'can', 'may', 'should', 'would', 'could', 'will', 'shall',
+    'please', 'want', 'like', 'let', 'me', 'us', 'to', 'of', 'in', 'on', 'at', 'by', 'it',
+    'is', 'be', 'been', 'do', 'does', 'did', 'doing', 'have', 'has', 'had', 'not', 'no',
+    'yes', 'ok', 'okay', 'a', 'an', 'i', 'we', 'my', 'our', 'about', 'then', 'than',
+    'run', 'running', 'ran', 'verify', 'verifying', 'verified', 'check', 'checking',
+    'perform', 'performing', 'before', 'after', 'now', 'again', 'sure', 'proceed',
+    'continue', 'go', 'ahead', 'use', 'using', 'make', 'making', 'need', 'needs', 'help',
+    'just', 'also', 'here', 'there', 'what', 'why', 'how', 'some', 'any', 'all',
+]);
+/** Normalize text for comparison (case, whitespace, punctuation-insensitive). */
+function normalize(text) {
+    return String(text ?? '')
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}./_-]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** File-ish and command-ish targets, matched without requiring backticks. */
+const FILE_TARGET_RE = /\b[\w./-]+\.(?:js|cjs|mjs|ts|tsx|jsx|json|css|scss|html|md|py|go|rs|java|rb|yml|yaml|sh|toml|sql)\b/gi;
+// NOTE: deliberately no `go`/`make`/`bun`-style English-word collisions — a
+// command NAME is a target, but "make the logo bigger" must not become one, or
+// two unrelated questions would collide on the shared word "make".
+const COMMAND_TARGET_RE = /\b(?:node|npm|npx|pnpm|yarn|deno|python3?|pip3?|git|tsc|vitest|jest|mocha|cargo|docker|kubectl|curl|gh)\b[^\s`.,;:!?)]*/gi;
+/**
+ * Reduce a question to its salient shape.
+ *
+ * Targets are the strongest signal: if two questions both name `node -c
+ * script.js`, they are the same ask however differently they are phrased. Tokens
+ * are the fallback for a question with no explicit target.
+ */
+export function questionShape(question) {
+    const text = String(question ?? '');
+    const targets = new Set();
+    for (const m of text.matchAll(/`([^`]+)`/g)) {
+        const t = normalize(m[1]);
+        if (t)
+            targets.add(t);
+    }
+    for (const m of text.matchAll(FILE_TARGET_RE))
+        targets.add(normalize(m[0]));
+    for (const m of text.matchAll(COMMAND_TARGET_RE)) {
+        const t = normalize(m[0]);
+        if (t)
+            targets.add(t);
+    }
+    const tokens = [...new Set(normalize(text).split(' ').filter((w) => w.length >= 3 && !STOPWORDS.has(w)))];
+    return { targets: [...targets].sort(), tokens };
+}
+/** Jaccard overlap of two token sets (0 when either is empty). */
+function jaccard(a, b) {
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    const setB = new Set(b);
+    const shared = a.filter((t) => setB.has(t)).length;
+    return shared / (a.length + b.length - shared);
+}
+/** Above this overlap two questions are treated as the same ask. */
+export const SAME_QUESTION_OVERLAP = 0.6;
+/**
+ * Is this the same question as an earlier one?
+ *
+ * Targets first — a shared target means the same thing is being asked about,
+ * which is the reliable signal ("May I run `node -c script.js`?" vs "Run a
+ * JavaScript syntax check (`node -c script.js`)?"). Only when neither has a
+ * target does token overlap decide, so a genuinely different question with the
+ * same shape ("which runtime?" … "which database?") is not counted as a repeat.
+ */
+export function isSameQuestion(a, b) {
+    if (a.targets.length > 0 && b.targets.length > 0) {
+        return a.targets.some((t) => b.targets.includes(t));
+    }
+    return jaccard(a.tokens, b.tokens) >= SAME_QUESTION_OVERLAP;
+}
+/** How many of each record the trace keeps (bounded — a long run must not grow). */
+export const MAX_TRACE_ENTRIES = 60;
+/**
+ * The run's own behaviour, as data.
+ *
+ * A class (not a plain array) because every consumer asks a QUESTION of it —
+ * "have I asked this?", "what was the answer?", "did I loop?" — and those
+ * questions should be answered in one place rather than re-derived by each
+ * caller.
+ */
+export class RunTrace {
+    asks = [];
+    refusals = [];
+    mutations = [];
+    /** Prior asks that are the SAME question as this one (excluding it). */
+    priorAskMatches(question) {
+        const shape = questionShape(question);
+        return this.asks.filter((a) => isSameQuestion(shape, a.shape));
+    }
+    /** The most recent SHOWN answer to this question, if the user gave one. */
+    priorAnswer(question) {
+        const matches = this.priorAskMatches(question).filter((a) => a.shown && a.answer);
+        return matches.length > 0 ? matches[matches.length - 1].answer : undefined;
+    }
+    /** Record that the agent asked something, and whether the user saw it. */
+    recordAsk(question, shown, answer) {
+        this.asks.push({
+            question: String(question ?? ''),
+            shape: questionShape(question),
+            shown,
+            ...(answer ? { answer } : {}),
+            at: Date.now(),
+        });
+        if (this.asks.length > MAX_TRACE_ENTRIES)
+            this.asks.shift();
+    }
+    /** Prior refusals of the SAME tool for the SAME reason. */
+    priorRefusalMatches(tool, detail) {
+        const signature = normalize(detail).slice(0, 200);
+        return this.refusals.filter((r) => r.tool === tool && r.signature === signature).length;
+    }
+    recordRefusal(tool, reason, detail) {
+        this.refusals.push({
+            tool,
+            signature: normalize(detail).slice(0, 200),
+            detail: String(detail ?? '').slice(0, 200),
+            at: Date.now(),
+        });
+        if (this.refusals.length > MAX_TRACE_ENTRIES)
+            this.refusals.shift();
+    }
+    recordMutation(tool, path) {
+        this.mutations.push({ tool, ...(path ? { path } : {}), at: Date.now() });
+        if (this.mutations.length > MAX_TRACE_ENTRIES)
+            this.mutations.shift();
+    }
+    countAsks() {
+        return this.asks.length;
+    }
+    countShownAsks() {
+        return this.asks.filter((a) => a.shown).length;
+    }
+    /**
+     * How many questions were asked more than once. The single number that says
+     * "this run looped on the conversation" — and the metric the fix is judged by.
+     */
+    repeatedAskCount() {
+        let repeats = 0;
+        for (let i = 0; i < this.asks.length; i += 1) {
+            for (let j = 0; j < i; j += 1) {
+                if (isSameQuestion(this.asks[i].shape, this.asks[j].shape)) {
+                    repeats += 1;
+                    break;
+                }
+            }
+        }
+        return repeats;
+    }
+    /**
+     * The counts, as a plain object — for surfaces that need the NUMBERS rather
+     * than the prose (the loop's result, the eval metric, the dashboard badge).
+     *
+     * `shownAsks` is the one that matters to a user: how many times the run
+     * actually stopped and asked them something. `asks` counts attempts, which is
+     * the number a gate can influence before the user ever sees it.
+     */
+    snapshot() {
+        return {
+            asks: this.asks.length,
+            shownAsks: this.countShownAsks(),
+            repeatedAsks: this.repeatedAskCount(),
+            refusals: this.refusals.length,
+            mutations: this.mutations.length,
+            paths: this.distinctMutationPaths(),
+        };
+    }
+    /** Distinct questions, each with how many times it was asked and its answer. */
+    askSummary() {
+        const groups = [];
+        for (const ask of this.asks) {
+            const hit = groups.find((g) => isSameQuestion(g.shape, ask.shape));
+            if (hit) {
+                hit.times += 1;
+                if (ask.shown && ask.answer)
+                    hit.answer = ask.answer;
+            }
+            else {
+                groups.push({ shape: ask.shape, question: ask.question, times: 1, answer: ask.shown ? ask.answer : undefined });
+            }
+        }
+        return groups.map(({ question, times, answer }) => ({
+            question,
+            times,
+            ...(answer ? { answer } : {}),
+        }));
+    }
+    distinctMutationPaths() {
+        return [...new Set(this.mutations.map((m) => m.path).filter((p) => Boolean(p)))];
+    }
+    /**
+     * The trace as text, for the model to answer FROM.
+     *
+     * Written for a reader that must not mistake it for a summary of the work: it
+     * describes the agent's OWN behaviour, so the number it leads with is the one
+     * a stuck run needs to see — how often it repeated itself.
+     */
+    selfReport() {
+        const lines = ['[Run trace — your own behaviour this conversation]'];
+        const shown = this.countShownAsks();
+        const repeated = this.repeatedAskCount();
+        if (this.asks.length === 0) {
+            lines.push('You have not asked the user any questions.');
+        }
+        else {
+            lines.push(`You asked ${this.asks.length} question(s); ${shown} reached the user; ` +
+                `${repeated} of them repeated a question you had already asked.`);
+            for (const s of this.askSummary()) {
+                const answer = s.answer ? ` — the user answered: "${s.answer}"` : ' — no answer recorded';
+                lines.push(`  • asked ${s.times}×: ${s.question.slice(0, 140)}${answer}`);
+            }
+        }
+        if (this.refusals.length > 0) {
+            lines.push(`Refused tool calls: ${this.refusals.length}.`);
+            for (const r of this.refusals.slice(-5)) {
+                lines.push(`  • ${r.tool}: ${r.detail}`);
+            }
+        }
+        const paths = this.distinctMutationPaths();
+        lines.push(paths.length > 0
+            ? `Files you changed: ${paths.slice(0, 10).join(', ')}${paths.length > 10 ? ` (+${paths.length - 10} more)` : ''}.`
+            : 'You have not changed any files.');
+        if (repeated > 0) {
+            lines.push('You REPEATED a question the user had already answered. Do not ask it again: ' +
+                'the answer above is the answer. Either act on it, or state plainly what blocks you.');
+        }
+        return lines.join('\n');
+    }
+}
+/**
+ * The correction handed back when the turn closes on a question the user has
+ * ALREADY answered.
+ *
+ * Deliberately does NOT say "proceed": a bare order to carry on would be unsafe
+ * when the answer was "no". It says the answer is already in hand — so act on
+ * it, or state plainly what blocks you. That is the difference between stopping
+ * a loop and bulldozing a decision.
+ */
+export function repeatNudge(question, answer) {
+    return ('You just asked a question the user has ALREADY answered in this conversation: ' +
+        `"${String(question ?? '').slice(0, 200)}". ` +
+        (answer ? `Their answer was: "${answer}". ` : '') +
+        'Do NOT ask it again. Act on the answer you already have, or — if it genuinely ' +
+        'does not settle the matter — say plainly what blocks you and what you need, instead ' +
+        'of repeating the question. Repeating a question the user has answered is the one ' +
+        'behaviour they will read as the agent being stuck.');
+}
+// ─── Frame detection: when is the user asking ABOUT the run? ────────────────
+/**
+ * The user asking about the agent's OWN behaviour ("why are you asking me this
+ * again and again?", "stop asking every second", "you keep asking permission").
+ *
+ * This is a distinct frame from a request: it is not work to be done, it is a
+ * question about the run. It must route the trace to the model rather than the
+ * ordinary "the request does not authorize files" analysis path — which is what
+ * previously happened, so the complaint was answered with planning prose and the
+ * loop continued.
+ */
+const PROCESS_COMPLAINT_RE = new RegExp([
+    '\\b(?:why|how\\s+come)\\b[^?]{0,80}\\b(?:ask|asks|asking|question|questions|prompt|prompts|prompting|permission)\\b',
+    '\\b(?:stop|quit|enough)\\s+(?:it\\s+)?(?:with\\s+)?(?:the\\s+)?(?:asking|questions|prompts|permission)\\b',
+    '\\byou\\s+(?:keep|kept|are\\s+always)\\s+asking\\b',
+    '\\bask(?:ing)?\\s+(?:me\\s+)?(?:again|repeatedly|every\\s+(?:second|time|step|turn))\\b',
+    '\\bsame\\s+question\\b',
+    '\\b(?:permission|approval)\\s+(?:again|every)\\b',
+].join('|'), 'i');
+/** Is the user asking about the agent's own behaviour? */
+export function detectProcessComplaint(text) {
+    const t = String(text ?? '').trim();
+    if (!t)
+        return false;
+    return PROCESS_COMPLAINT_RE.test(t);
+}
+// ─── Per-conversation storage ───────────────────────────────────────────────
+const traces = new WeakMap();
+/** Is this object usable as a trace key (a session handle)? */
+export function isTraceKey(key) {
+    return (typeof key === 'object' && key !== null) || typeof key === 'function';
+}
+/** The trace for a conversation, created on first use. */
+export function runTraceFor(key) {
+    let trace = traces.get(key);
+    if (!trace) {
+        trace = new RunTrace();
+        traces.set(key, trace);
+    }
+    return trace;
+}
+/** The trace for a conversation, or undefined when none exists yet. */
+export function peekRunTrace(key) {
+    return isTraceKey(key) ? traces.get(key) : undefined;
+}
+/** Drop the trace (the conversation ended). */
+export function clearRunTrace(key) {
+    if (isTraceKey(key))
+        traces.delete(key);
+}
+//# sourceMappingURL=run-trace.js.map

package/dist/learning/run-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-trace.js","sourceRoot":"","sources":["../../src/learning/run-trace.ts"],"names":[],"mappings":"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"}

package/dist/learning/skill-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-store.d.ts","sourceRoot":"","sources":["../../src/learning/skill-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAkB,MAAM,kBAAkB,CAAC;AAwD5E;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAa;;IAe1B;;;;;;;OAOG;IACH,iBAAiB,IAAI,MAAM;IA8C3B;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IA6BxB;;;OAGG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAW7B;;;OAGG;IACH,MAAM,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,KAAK,EAAE;IAiBzC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE;IAa9B;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IA0CrC;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAS1B;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IA4B3B;;;OAGG;IACH,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAqBvC;;;OAGG;IACH,cAAc,CAAC,OAAO,GAAE,OAAe,GAAG,MAAM;IA4ChD;;OAEG;IACH,UAAU,IAAI,YAAY;IAyC1B;;OAEG;IACH,KAAK,IAAI,IAAI;IAUb;;OAEG;IACH,gBAAgB,IAAI,KAAK,CAAC;QACxB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IAeF;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;IA6BlD;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAS5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAoGvB,OAAO,CAAC,SAAS;IAajB,OAAO,CAAC,SAAS;CAIlB;AAMD,wBAAgB,aAAa,IAAI,UAAU,CAK1C;AAED,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}
+{"version":3,"file":"skill-store.d.ts","sourceRoot":"","sources":["../../src/learning/skill-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAkB,MAAM,kBAAkB,CAAC;AAwD5E;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAa;;IAe1B;;;;;;;OAOG;IACH,iBAAiB,IAAI,MAAM;IA8C3B;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IA6BxB;;;OAGG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAW7B;;;OAGG;IACH,MAAM,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,KAAK,EAAE;IAiBzC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE;IAa9B;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IA0CrC;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAS1B;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IA4B3B;;;OAGG;IACH,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAqBvC;;;OAGG;IACH,cAAc,CAAC,OAAO,GAAE,OAAe,GAAG,MAAM;IA4ChD;;OAEG;IACH,UAAU,IAAI,YAAY;IAyC1B;;OAEG;IACH,KAAK,IAAI,IAAI;IAUb;;OAEG;IACH,gBAAgB,IAAI,KAAK,CAAC;QACxB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IAeF;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;IA6BlD;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAS5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAyGvB,OAAO,CAAC,SAAS;IAajB,OAAO,CAAC,SAAS;CAIlB;AAMD,wBAAgB,aAAa,IAAI,UAAU,CAK1C;AAED,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/learning/skill-store.js

@@ -14,7 +14,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveNuviraHome } from '../config/paths.js';
-import { MAX_SKILLS } from './skill-types.js';
+import { MAX_SKILLS, SKILL_PRECEDENCE_NOTE } from './skill-types.js';
 import { ALL_BUNDLED_SKILLS as BUNDLED_SKILLS } from '../skills/bundled-skills.js';
 import { logger } from '../utils/logger.js';
 // ─── Constants ──────────────────────────────────────────────────────────────
@@ -553,6 +553,10 @@ export class SkillStore {
                 sections.push(`- **${param.name}** ${required}${defaultVal}: ${param.description}`);
             }
         }
+        // Precedence — stated before the steps so they are read as methodology,
+        // never as an authorisation to override the live request.
+        sections.push('\n## Precedence');
+        sections.push(SKILL_PRECEDENCE_NOTE);
         // Steps (the core methodology)
         sections.push('\n## Execution Steps');
         sections.push('\nFollow these steps in order:');