agent-nuvira 3.5.7 → 3.5.10

package/dist/learning/assessment-protocol.d.ts

@@ -0,0 +1,120 @@
+/**
+ * PROJECT-ASSESSMENT PROTOCOL — the evidence rules for "assess this codebase"
+ * asks (audit / code review / "find the bugs").
+ *
+ * WHY THIS EXISTS (the side-by-side audit, 2026-10-16). Two agents on the SAME
+ * model (DeepSeek V4.1 Flash), the same prompt, the same small project
+ * (`/Users/dheeraj/Documents/cal`, 12 files, ~276 LOC), told not to change
+ * anything. One ran the project's own modules and the real page in a browser;
+ * the other — this CLI — reasoned over what it had read, re-created the engine
+ * by hand inside `code_execution`, and published the copy's output as the app's
+ * behaviour. The comparison isolates four defects that are NOT about model
+ * quality, because the model was identical:
+ *
+ *   1. A COPY WAS REPORTED AS THE ARTIFACT. Its top-severity finding said
+ *      "typing `alert(1)` into the display and pressing `=` runs the code",
+ *      "verified" against a hand-copied engine — while the shipped display
+ *      input is `disabled`, the keyboard filter drops every letter, and no
+ *      button emits one, so that input cannot be produced at all. The sink is
+ *      real and LATENT; the reachability claim was false. Worse, its remediation
+ *      ("reject identifiers in the whitelist") does not close the sink, because
+ *      a char-code `Function(...)` escape needs only letters, digits, commas and
+ *      parens — measured against the real module.
+ *   2. NO MEASUREMENT. "`999999999!` hangs the tab indefinitely" — measured on
+ *      the real engine it is ~31 s (3.09 s at n=1e8, linear), and the indefinite
+ *      case needs more digits than that. A magnitude nobody measured is a
+ *      guess wearing a severity label.
+ *   3. GREEN TESTS READ AS COVERAGE. The project's 10 tests all pass, and all 10
+ *      drive `evaluateExpression` — while the UI buttons call
+ *      `evaluateScientific`, which is missing cases for 8 of the 14 buttons. The
+ *      tested path is not the shipped path; that gap IS the root cause, and the
+ *      audit that stopped at "tests pass" could not see it.
+ *   4. THE ANSWER STOPPED MID-SENTENCE. Its report forward-referenced a
+ *      "dead code — noted at the end" section, ran out of output budget two
+ *      findings later, and ended inside a word. A dangling forward reference in a
+ *      truncated answer costs the reader the whole tail of the report.
+ *
+ * WHAT THIS MODULE IS. A deterministic, LLM-free classifier plus one block of
+ * text. It changes what the agent must be able to SHOW for a finding, not the
+ * shape of the report: the strengths that run already had — severity labels,
+ * exact `file:line`, mechanism, a fix recipe, the artifact-inheritance check
+ * (does the built bundle carry the same bug?), and finishing in seconds — are
+ * kept and are named in the block as the format to keep.
+ *
+ * ROUND TWO (the head-to-head audit, 2026-10-16). A second side-by-side run —
+ * same model, same prompt, same snapshot, this time on a Python desktop app
+ * (`/Users/dheeraj/Documents/anuj_voice`, 60 modules) — scored this CLI's audit
+ * against another agent's. It found six defects the five rules above did not
+ * cover, and every one is a SHAPE OF CHECK rather than a missing fact:
+ *
+ *   6. IT READ THE MODULES AND NOT THE SEAMS. The three findings it missed all
+ *      lived in the joins: a constant compared against the wrong version
+ *      (`_MIN_APP_VERSION = '0.1.0'` gating every real add-on out), a manifest
+ *      field parsed and consumed nowhere (`dependencies`), and a recursive
+ *      merge that silently drops nested defaults when the file is partial.
+ *   7. IT DID NOT RUN THE PROJECT'S OWN TOOLING. The tree shipped
+ *      `tools/dead_code_audit.py` and a packaging validator, its plan NAMED the
+ *      tools directory, and it ran neither — while a shipped checker was the
+ *      artifact that reported the release defect. See `self-check-discovery.ts`.
+ *   8. IT CITED A FILE IN THE REPO AS EVIDENCE. It repeated a claim from a
+ *      prior `ASSESSMENT.md` sitting in the tree without resolving that file's
+ *      own `file:line` references — which were, on measurement, pointing at the
+ *      accelerator table rather than the code the claim described.
+ *   9. IT ASSERTED A MEASUREMENT IT HAD NOT TAKEN. Its plan reported
+ *      `14 failed / 422 passed` before any command in the transcript had run,
+ *      and its appendix documented a command that does not reproduce those
+ *      numbers. Both are provenance failures, not the model being wrong.
+ *  10. IT ASKED A USER WHO WAS NOT THERE for permission to run a read-only
+ *      probe, and self-answered only because the run was unattended.
+ *  11. IT LEFT ITS SCRATCH FILES IN THE TREE IT WAS AUDITING.
+ *
+ * Rules 6-11 are the mechanical half of that gap: four of them are checks the
+ * agent can perform on its own output before delivering it.
+ *
+ * NARROWNESS IS THE DESIGN. The block is injected ONLY for an assessment ask: a
+ * change request ("fix the bug", "add tests") must be byte-identical to a build
+ * without this feature, which is why {@link isProjectAssessmentGoal} requires an
+ * explicit finding/audit shape rather than the word "review" on its own. An
+ * authored ask is excluded via the existing deliverable taxonomy, so "write a
+ * review of this novel" never gets a bug-hunting protocol.
+ */
+/**
+ * The block's rules, written as one message. Kept deterministic (an array of
+ * lines joined here) so tests assert on the rules rather than on prose
+ * formatting, and so a truncated edit cannot silently drop a rule.
+ */
+export declare const ASSESSMENT_PROTOCOL_RULES: readonly string[];
+/**
+ * The injected block. Returns '' for every non-assessment ask (the caller then
+ * injects nothing, so the turn is byte-identical to one from a build without
+ * this module).
+ *
+ * It deliberately does NOT prescribe a report template: the findings format from
+ * a normal run — severity, `file:line`, mechanism, fix — is named as the thing to
+ * KEEP, so the protocol adds evidence discipline without flattening the answer.
+ */
+export declare function assessmentProtocolBlock(goal: string, opts?: {
+    selfChecks?: string;
+}): string;
+/**
+ * Is this goal a PROJECT ASSESSMENT — a request for findings about existing code,
+ * rather than a change to it or an authored document?
+ *
+ * Two shapes qualify, and nothing else does:
+ *   - an explicit finding request ("identify the bugs in the project", "what's
+ *     broken here") — the shape the side-by-side audit took;
+ *   - an assessment verb aimed at code ("assess the project at …", "review the
+ *     codebase", "audit this API").
+ *
+ * The exclusions are as load-bearing as the matches: requiring a code target keeps
+ * "review this sentence" and "review my notes" out, and a LONG-FORM authored ask is
+ * excluded so "write a 20 page review of this codebase" stays a document task.
+ *
+ * The authored exclusion is deliberately the NARROW one (`isLongFormAuthoredGoal`,
+ * not `isAuthoredGoal`): the broad predicate is claimed by the word "report", and
+ * the verbatim audit goal ends "…report the file and line … this is an assessment
+ * only" — a broad guard silently drops exactly the ask this module exists for. The
+ * code-target requirement already keeps prose asks that never mention code out.
+ */
+export declare function isProjectAssessmentGoal(goal: string): boolean;
+//# sourceMappingURL=assessment-protocol.d.ts.map

package/dist/learning/assessment-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assessment-protocol.d.ts","sourceRoot":"","sources":["../../src/learning/assessment-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AAyBH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAsEtD,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACjC,MAAM,CAqBR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAO7D"}

package/dist/learning/assessment-protocol.js

@@ -0,0 +1,236 @@
+/**
+ * PROJECT-ASSESSMENT PROTOCOL — the evidence rules for "assess this codebase"
+ * asks (audit / code review / "find the bugs").
+ *
+ * WHY THIS EXISTS (the side-by-side audit, 2026-10-16). Two agents on the SAME
+ * model (DeepSeek V4.1 Flash), the same prompt, the same small project
+ * (`/Users/dheeraj/Documents/cal`, 12 files, ~276 LOC), told not to change
+ * anything. One ran the project's own modules and the real page in a browser;
+ * the other — this CLI — reasoned over what it had read, re-created the engine
+ * by hand inside `code_execution`, and published the copy's output as the app's
+ * behaviour. The comparison isolates four defects that are NOT about model
+ * quality, because the model was identical:
+ *
+ *   1. A COPY WAS REPORTED AS THE ARTIFACT. Its top-severity finding said
+ *      "typing `alert(1)` into the display and pressing `=` runs the code",
+ *      "verified" against a hand-copied engine — while the shipped display
+ *      input is `disabled`, the keyboard filter drops every letter, and no
+ *      button emits one, so that input cannot be produced at all. The sink is
+ *      real and LATENT; the reachability claim was false. Worse, its remediation
+ *      ("reject identifiers in the whitelist") does not close the sink, because
+ *      a char-code `Function(...)` escape needs only letters, digits, commas and
+ *      parens — measured against the real module.
+ *   2. NO MEASUREMENT. "`999999999!` hangs the tab indefinitely" — measured on
+ *      the real engine it is ~31 s (3.09 s at n=1e8, linear), and the indefinite
+ *      case needs more digits than that. A magnitude nobody measured is a
+ *      guess wearing a severity label.
+ *   3. GREEN TESTS READ AS COVERAGE. The project's 10 tests all pass, and all 10
+ *      drive `evaluateExpression` — while the UI buttons call
+ *      `evaluateScientific`, which is missing cases for 8 of the 14 buttons. The
+ *      tested path is not the shipped path; that gap IS the root cause, and the
+ *      audit that stopped at "tests pass" could not see it.
+ *   4. THE ANSWER STOPPED MID-SENTENCE. Its report forward-referenced a
+ *      "dead code — noted at the end" section, ran out of output budget two
+ *      findings later, and ended inside a word. A dangling forward reference in a
+ *      truncated answer costs the reader the whole tail of the report.
+ *
+ * WHAT THIS MODULE IS. A deterministic, LLM-free classifier plus one block of
+ * text. It changes what the agent must be able to SHOW for a finding, not the
+ * shape of the report: the strengths that run already had — severity labels,
+ * exact `file:line`, mechanism, a fix recipe, the artifact-inheritance check
+ * (does the built bundle carry the same bug?), and finishing in seconds — are
+ * kept and are named in the block as the format to keep.
+ *
+ * ROUND TWO (the head-to-head audit, 2026-10-16). A second side-by-side run —
+ * same model, same prompt, same snapshot, this time on a Python desktop app
+ * (`/Users/dheeraj/Documents/anuj_voice`, 60 modules) — scored this CLI's audit
+ * against another agent's. It found six defects the five rules above did not
+ * cover, and every one is a SHAPE OF CHECK rather than a missing fact:
+ *
+ *   6. IT READ THE MODULES AND NOT THE SEAMS. The three findings it missed all
+ *      lived in the joins: a constant compared against the wrong version
+ *      (`_MIN_APP_VERSION = '0.1.0'` gating every real add-on out), a manifest
+ *      field parsed and consumed nowhere (`dependencies`), and a recursive
+ *      merge that silently drops nested defaults when the file is partial.
+ *   7. IT DID NOT RUN THE PROJECT'S OWN TOOLING. The tree shipped
+ *      `tools/dead_code_audit.py` and a packaging validator, its plan NAMED the
+ *      tools directory, and it ran neither — while a shipped checker was the
+ *      artifact that reported the release defect. See `self-check-discovery.ts`.
+ *   8. IT CITED A FILE IN THE REPO AS EVIDENCE. It repeated a claim from a
+ *      prior `ASSESSMENT.md` sitting in the tree without resolving that file's
+ *      own `file:line` references — which were, on measurement, pointing at the
+ *      accelerator table rather than the code the claim described.
+ *   9. IT ASSERTED A MEASUREMENT IT HAD NOT TAKEN. Its plan reported
+ *      `14 failed / 422 passed` before any command in the transcript had run,
+ *      and its appendix documented a command that does not reproduce those
+ *      numbers. Both are provenance failures, not the model being wrong.
+ *  10. IT ASKED A USER WHO WAS NOT THERE for permission to run a read-only
+ *      probe, and self-answered only because the run was unattended.
+ *  11. IT LEFT ITS SCRATCH FILES IN THE TREE IT WAS AUDITING.
+ *
+ * Rules 6-11 are the mechanical half of that gap: four of them are checks the
+ * agent can perform on its own output before delivering it.
+ *
+ * NARROWNESS IS THE DESIGN. The block is injected ONLY for an assessment ask: a
+ * change request ("fix the bug", "add tests") must be byte-identical to a build
+ * without this feature, which is why {@link isProjectAssessmentGoal} requires an
+ * explicit finding/audit shape rather than the word "review" on its own. An
+ * authored ask is excluded via the existing deliverable taxonomy, so "write a
+ * review of this novel" never gets a bug-hunting protocol.
+ */
+import { isLongFormAuthoredGoal } from './deliverable-class.js';
+/**
+ * Verbs that ask for judgement ABOUT the code rather than a change TO it.
+ * `analyse`/`analyze` are here because "analyse the codebase" is the same ask.
+ */
+const ASSESS_VERBS = /\b(assess|audit|review|critique|inspect|analyse|analyze|evaluate)\b/i;
+/**
+ * The thing being judged. Required alongside a bare verb so "review this
+ * sentence" cannot pull a code-audit protocol into the turn.
+ */
+const CODE_TARGETS = /\b(code\s*-?\s*base|project|repo(?:sitory)?|source\s+tree|files?|modules?|packages?|app(?:lication)?|backend|frontend|api|scripts?|src)\b/i;
+/** "find the bugs", "identify issues", "list defects", "spot the risks" … */
+const FIND_FLAWS = /\b(find|finding|identify|list|spot|locate|uncover|report|surface|hunt\s+for|look\s+for)\b[^.!?]{0,60}\b(bugs?|issues?|defects?|problems?|flaws?|vulnerabilit(?:y|ies)|smells?|errors?|risks?|weaknesses?|bugs?\s+and)\b/i;
+/** "what's wrong with this project", "what is broken in the code" … */
+const WHATS_WRONG = /\bwhat(?:'s| is| are| s)\s+(?:wrong|broken|missing|bad|the\s+(?:bugs?|issues?|problems?|risks?|defects?))\b/i;
+/**
+ * The block's rules, written as one message. Kept deterministic (an array of
+ * lines joined here) so tests assert on the rules rather than on prose
+ * formatting, and so a truncated edit cannot silently drop a rule.
+ */
+export const ASSESSMENT_PROTOCOL_RULES = [
+    '1. MEASURE THE ARTIFACT, NOT A COPY.',
+    '   Run the project\'s own code: import the real module, call the real function,',
+    '   drive the real page, endpoint or CLI. Never paste a copy of the logic into a',
+    '   scratch script and present its output as the app\'s behaviour — a copy can',
+    '   differ from the shipped code, and that gap is where wrong findings come from.',
+    '   If you did reason from a copy, tag the finding `REASONED` instead of `MEASURED`.',
+    '   MEASURE THE CONSEQUENCE TOO: when the impact is data loss or corruption, run',
+    '   the path against a temp copy and report the observed end state, not a guess.',
+    '',
+    '2. REACHABILITY BEFORE SEVERITY.',
+    '   Before a UI / endpoint / input defect is called real, show that a user can',
+    '   produce the triggering input: name the handler, the filter, the disabled',
+    '   field, the route. A sink with no reachable input is LATENT — say "latent" and',
+    '   name the path that would make it live. Never describe an unreachable path as',
+    '   something the user can type.',
+    '',
+    '3. QUANTIFY RESOURCE CLAIMS.',
+    '   Every hang / freeze / leak / DoS / slow-path claim needs a number you',
+    '   measured (use the real code and say what you ran: "3.09 s at n=1e8, linear"),',
+    '   and anything you did not measure must be labelled an extrapolation.',
+    '   If you cannot measure it, tag the finding `UNMEASURED` and say which command',
+    '   would produce the number — an admitted gap is honest, a magnitude you never',
+    '   measured reads as a fact and is not one.',
+    '',
+    '4. GREEN TESTS ARE NOT COVERAGE.',
+    '   Say what the tests actually call and whether that is the path users take.',
+    '   When a tested function and the shipped dispatch differ, name which one is',
+    '   tested and which one runs — that gap is usually the root cause of the bug',
+    '   you just found, and it survives every green test run.',
+    '',
+    '5. FINISH WHAT YOU REFERENCE.',
+    '   Never forward-reference a section you might not deliver ("noted at the end",',
+    '   "see below"): write it where you reference it. If you are near your output',
+    '   limit, cut SCOPE, not the end of a sentence — close the finding you are in,',
+    '   then add a final `## Not covered` list. An answer that stops mid-sentence is',
+    '   a failed answer, however good the part before it was.',
+    '',
+    '6. CHECK THE SEAMS, NOT ONLY THE MODULES. For every CONSTANT, ask what it is',
+    '   compared against (a version gate against a hardcoded floor disables the',
+    '   feature it guards); for every PARSED FIELD, find its consumer (an unread',
+    '   config or manifest key is a capability that does not exist); for every',
+    '   recursive MERGE or default table, feed it PARTIAL input and see which',
+    '   defaults survive.',
+    '',
+    '7. RUN WHAT THE PROJECT ALREADY SHIPS. Run the self-checks below and any you',
+    '   find (a `tools/` auditor, a validator, a CI script) before concluding — a',
+    '   shipped checker is the highest-provenance evidence there is, and cannot be',
+    '   a hallucination. Give a delegate the EXACT file or suite to run, and read',
+    '   its "not found" as nothing tested. Skipping one? Name it as a gap, never',
+    '   silently.',
+    '',
+    '8. A FILE IN THE REPO IS A CLAIM, NOT A FACT. A prior report, notes file or',
+    '   README is evidence of what someone asserted, not of what the code does.',
+    '   Resolve its `file:line` references yourself first, saying which you checked.',
+    '',
+    '9. NEVER CLAIM A MEASUREMENT YOU HAVE NOT TAKEN. A number belongs in the',
+    '   answer only after the command that produced it ran IN THIS TURN; never mark',
+    '   a step done on a result you have not seen, and re-run every command you cite',
+    '   to confirm it prints the numbers beside it. An unreproducible command',
+    '   invalidates its finding.',
+    '',
+    '10. DECIDE; DO NOT ASK FOR WHAT YOU MAY ALREADY DO. Reading, listing, searching',
+    '    and running read-only probes are yours. Ask only where the answer is the',
+    '    user\'s call and cannot be inferred; with nobody there, record the choice',
+    '    you made, never a question.',
+    '',
+    '11. LEAVE THE TREE AS YOU FOUND IT. Keep scratch files, probes and reports',
+    '    OUTSIDE the audited repository (a temp dir) and say where; if a deliverable',
+    '    must land in the tree, name every file you added and what to delete.',
+];
+/**
+ * The injected block. Returns '' for every non-assessment ask (the caller then
+ * injects nothing, so the turn is byte-identical to one from a build without
+ * this module).
+ *
+ * It deliberately does NOT prescribe a report template: the findings format from
+ * a normal run — severity, `file:line`, mechanism, fix — is named as the thing to
+ * KEEP, so the protocol adds evidence discipline without flattening the answer.
+ */
+export function assessmentProtocolBlock(goal, opts = {}) {
+    if (!isProjectAssessmentGoal(goal))
+        return '';
+    const parts = [
+        '## ⚠️ TASK PROTOCOL: PROJECT ASSESSMENT (findings, not changes)',
+        'Keep the report shape you already use — severity-labelled findings, exact',
+        '`file:line`, the mechanism, a fix, and which artifacts inherit the bug. Add',
+        'these evidence rules on top; a finding that breaks one is not yet a finding:',
+        '',
+        ...ASSESSMENT_PROTOCOL_RULES,
+        '',
+        'Also: read the whole tree in as FEW passes as possible (one call listing many',
+        'paths beats one call per file) BEFORE you start verifying, and record the exact',
+        'command and observed output next to each finding so it can be re-run by someone',
+        'who was not there.',
+    ];
+    // The project's own checks (see `self-check-discovery.ts`) are appended only
+    // when the caller found some, so a project that declares none produces the
+    // exact block a build without that module produces.
+    const selfChecks = (opts.selfChecks || '').trim();
+    if (selfChecks)
+        parts.push('', selfChecks);
+    return parts.join('\n');
+}
+/**
+ * Is this goal a PROJECT ASSESSMENT — a request for findings about existing code,
+ * rather than a change to it or an authored document?
+ *
+ * Two shapes qualify, and nothing else does:
+ *   - an explicit finding request ("identify the bugs in the project", "what's
+ *     broken here") — the shape the side-by-side audit took;
+ *   - an assessment verb aimed at code ("assess the project at …", "review the
+ *     codebase", "audit this API").
+ *
+ * The exclusions are as load-bearing as the matches: requiring a code target keeps
+ * "review this sentence" and "review my notes" out, and a LONG-FORM authored ask is
+ * excluded so "write a 20 page review of this codebase" stays a document task.
+ *
+ * The authored exclusion is deliberately the NARROW one (`isLongFormAuthoredGoal`,
+ * not `isAuthoredGoal`): the broad predicate is claimed by the word "report", and
+ * the verbatim audit goal ends "…report the file and line … this is an assessment
+ * only" — a broad guard silently drops exactly the ask this module exists for. The
+ * code-target requirement already keeps prose asks that never mention code out.
+ */
+export function isProjectAssessmentGoal(goal) {
+    const g = (goal || '').trim();
+    if (!g)
+        return false;
+    // A long-form authored deliverable wins: the prose IS the deliverable here.
+    if (isLongFormAuthoredGoal(g))
+        return false;
+    if (FIND_FLAWS.test(g) || WHATS_WRONG.test(g))
+        return true;
+    return ASSESS_VERBS.test(g) && CODE_TARGETS.test(g);
+}
+//# sourceMappingURL=assessment-protocol.js.map

package/dist/learning/assessment-protocol.js.map

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

package/dist/learning/assessment-turn-context.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ASSESSMENT TURN CONTEXT — the ONE seam every surface builds an assessment ask
+ * through.
+ *
+ * WHY THIS EXISTS. `assessment-protocol.ts` answers "what must a findings turn be
+ * able to show?", `self-check-discovery.ts` answers "what does this project
+ * already check?", and `perf-probe.ts` answers "how would its startup cost be
+ * measured?" — three modules, one prompt section, and four turn entries that all
+ * run assessment asks (the CLI chat and the dashboard and the gateway chat through
+ * `ChatCommand.runChatAnswer`, `nuvira execute` through `runLoopExecutor` and
+ * `runPipelineTool`, and a delegated sub-agent through the child runtime).
+ *
+ * Measured before this module existed: the section was assembled inline in
+ * `chat.ts`, so it reached exactly one entry. An assessment run through
+ * `nuvira execute` — the surface a batch/scripted audit actually uses — got the
+ * plain ask with none of the rules, which is the "capability lands on one surface
+ * and quietly misses three" drift `src/parity/surfaces.ts` was written to make
+ * visible. Assembling it here means the surfaces cannot disagree about what an
+ * assessment ask is, and a rule added once lands everywhere.
+ *
+ * THE ORDER IS THE DESIGN, not an optimisation detail. `isProjectAssessmentGoal`
+ * is a pure regex over the goal and runs FIRST: for every ordinary turn — the
+ * overwhelming majority — this function does no filesystem work at all and returns
+ * an empty block, so such a turn is byte-identical to one from a build without any
+ * of these modules. Only once a turn IS an assessment ask does it read the project
+ * directory.
+ *
+ * BEST-EFFORT BY CONTRACT, like the modules it composes. A missing/unreadable
+ * workspace, or a project with nothing discoverable, yields the rules block alone:
+ * the protocol still applies, and no turn is ever broken by a discovery failure.
+ */
+import type { MachineFacts } from './machine-facts.js';
+/** What an assessment turn contributes to the prompt, and how much of it. */
+export interface AssessmentTurnContext {
+    /** True when the goal is a findings ask — the detector, exposed once. */
+    isAssessment: boolean;
+    /** The prompt section: '' for every non-assessment ask. */
+    block: string;
+    /** How many of the project's own checks were named (0 when none/not probed). */
+    selfChecks: number;
+    /** Whether a performance-probe section was included. */
+    perfProbes: boolean;
+}
+/**
+ * Build the assessment section for one turn.
+ *
+ * @param goal the user's ask, verbatim (the detector reads it, so do not rewrite it first)
+ * @param dir  the directory the turn is scoped to (the project being assessed)
+ * @param opts.facts machine facts, injectable for tests
+ */
+export declare function buildAssessmentTurnContext(goal: string, dir: string, opts?: {
+    facts?: MachineFacts;
+}): AssessmentTurnContext;
+//# sourceMappingURL=assessment-turn-context.d.ts.map

package/dist/learning/assessment-turn-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assessment-turn-context.d.ts","sourceRoot":"","sources":["../../src/learning/assessment-turn-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,YAAY,EAAE,OAAO,CAAC;IACtB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,UAAU,EAAE,OAAO,CAAC;CACrB;AAKD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,YAAY,CAAA;CAAO,GAClC,qBAAqB,CAyBvB"}

package/dist/learning/assessment-turn-context.js

@@ -0,0 +1,71 @@
+/**
+ * ASSESSMENT TURN CONTEXT — the ONE seam every surface builds an assessment ask
+ * through.
+ *
+ * WHY THIS EXISTS. `assessment-protocol.ts` answers "what must a findings turn be
+ * able to show?", `self-check-discovery.ts` answers "what does this project
+ * already check?", and `perf-probe.ts` answers "how would its startup cost be
+ * measured?" — three modules, one prompt section, and four turn entries that all
+ * run assessment asks (the CLI chat and the dashboard and the gateway chat through
+ * `ChatCommand.runChatAnswer`, `nuvira execute` through `runLoopExecutor` and
+ * `runPipelineTool`, and a delegated sub-agent through the child runtime).
+ *
+ * Measured before this module existed: the section was assembled inline in
+ * `chat.ts`, so it reached exactly one entry. An assessment run through
+ * `nuvira execute` — the surface a batch/scripted audit actually uses — got the
+ * plain ask with none of the rules, which is the "capability lands on one surface
+ * and quietly misses three" drift `src/parity/surfaces.ts` was written to make
+ * visible. Assembling it here means the surfaces cannot disagree about what an
+ * assessment ask is, and a rule added once lands everywhere.
+ *
+ * THE ORDER IS THE DESIGN, not an optimisation detail. `isProjectAssessmentGoal`
+ * is a pure regex over the goal and runs FIRST: for every ordinary turn — the
+ * overwhelming majority — this function does no filesystem work at all and returns
+ * an empty block, so such a turn is byte-identical to one from a build without any
+ * of these modules. Only once a turn IS an assessment ask does it read the project
+ * directory.
+ *
+ * BEST-EFFORT BY CONTRACT, like the modules it composes. A missing/unreadable
+ * workspace, or a project with nothing discoverable, yields the rules block alone:
+ * the protocol still applies, and no turn is ever broken by a discovery failure.
+ */
+import { assessmentProtocolBlock, isProjectAssessmentGoal } from './assessment-protocol.js';
+import { buildSelfCheckBlock, readProjectSelfChecks } from './self-check-discovery.js';
+import { buildPerfProbeBlock, detectPerfProbeInput } from './perf-probe.js';
+/** The empty result — also what a non-assessment ask returns, by value. */
+const NOT_ASSESSMENT = { isAssessment: false, block: '', selfChecks: 0, perfProbes: false };
+/**
+ * Build the assessment section for one turn.
+ *
+ * @param goal the user's ask, verbatim (the detector reads it, so do not rewrite it first)
+ * @param dir  the directory the turn is scoped to (the project being assessed)
+ * @param opts.facts machine facts, injectable for tests
+ */
+export function buildAssessmentTurnContext(goal, dir, opts = {}) {
+    // The gate first: a non-assessment ask must not touch the filesystem.
+    if (!isProjectAssessmentGoal(goal))
+        return { ...NOT_ASSESSMENT };
+    let selfChecksBlock = '';
+    let selfCheckCount = 0;
+    try {
+        const checks = readProjectSelfChecks(dir);
+        selfCheckCount = checks.length;
+        selfChecksBlock = buildSelfCheckBlock(checks);
+    }
+    catch {
+        // Discovery is best-effort: the rules still apply without it.
+    }
+    let perfBlock = '';
+    try {
+        perfBlock = buildPerfProbeBlock(detectPerfProbeInput(dir, opts.facts));
+    }
+    catch {
+        // A probe section that cannot be detected is simply not offered.
+    }
+    const section = [selfChecksBlock.trim(), perfBlock.trim()].filter(Boolean).join('\n\n');
+    const block = assessmentProtocolBlock(goal, { selfChecks: section });
+    if (block === '')
+        return { ...NOT_ASSESSMENT };
+    return { isAssessment: true, block, selfChecks: selfCheckCount, perfProbes: perfBlock.trim() !== '' };
+}
+//# sourceMappingURL=assessment-turn-context.js.map

package/dist/learning/assessment-turn-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assessment-turn-context.js","sourceRoot":"","sources":["../../src/learning/assessment-turn-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAC5F,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAe5E,2EAA2E;AAC3E,MAAM,cAAc,GAA0B,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAEnH;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,IAAY,EACZ,GAAW,EACX,OAAiC,EAAE;IAEnC,sEAAsE;IACtE,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC;IAEjE,IAAI,eAAe,GAAG,EAAE,CAAC;IACzB,IAAI,cAAc,GAAG,CAAC,CAAC;IACvB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;QAC1C,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;QAC/B,eAAe,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;IAChE,CAAC;IAED,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,IAAI,CAAC;QACH,SAAS,GAAG,mBAAmB,CAAC,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACzE,CAAC;IAAC,MAAM,CAAC;QACP,iEAAiE;IACnE,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxF,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;IACrE,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC;IAC/C,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;AACxG,CAAC"}

package/dist/learning/exhaustion-report.d.ts

@@ -17,7 +17,10 @@
  *      WALL-CLOCK TIME each cooling one frees up (a wait length is unactionable;
  *      "free at 18:42" is something a person can plan around);
  *   3. what the system itself is doing about it (routing to an untried model,
- *      or waiting for a window) — stated as the system's job, not the user's;
+ *      or waiting for a window) — stated as the system's job, not the user's,
+ *      and NEVER a promise it cannot keep: under a HELD pin nothing else is
+ *      tried by design, so the report says that instead of "an untried model
+ *      comes next automatically" (see `pinnedHeld`);
  *   4. the concrete levers only the user can pull: recharge/replace a rejected
  *      credential, knowingly accept a weaker model, or narrow the ask.
  *
@@ -78,6 +81,26 @@ export interface ExhaustionInput {
      * says what releasing it would actually mean.
      */
     pinnedModel?: string;
+    /**
+     * True when that pin is HELD — the named model is the only one allowed to
+     * serve this turn, so no other model will be tried, now or on the next
+     * attempt.
+     *
+     * WHY THIS IS A SEPARATE INPUT FROM `pinnedModel`, and the bug it fixes. A pin
+     * is a contract about which model runs, and it is now the DEFAULT for a named
+     * pair — so the common case of a failed pinned turn is "stopped on purpose",
+     * not "ran out of pool". Measured on the real CLI (2026-10-16, model pinned to
+     * a pair the provider does not serve): the report still said *"This was a
+     * routing gap, not a shortage: only 1 of 5 eligible models were actually
+     * tried. The next attempt routes to an untried model automatically — you do
+     * not need to trigger anything."* Every clause of that is false while the pin
+     * holds. The walk stopped after one model because the USER's own contract
+     * forbade the other four, so it is neither a pool gap nor a shortage, and
+     * nothing at all happens next until the pin is released. Promising a silent
+     * automatic switch is the worst possible wording here: it tells the user to
+     * wait for a retry that the same run will refuse to perform.
+     */
+    pinnedHeld?: boolean;
     /**
      * The underlying failure line, when there is one (e.g. the provider's own
      * rejection text). Rendered as a `Reason:` line so a specific, actionable

package/dist/learning/exhaustion-report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exhaustion-report.d.ts","sourceRoot":"","sources":["../../src/learning/exhaustion-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,UAAU,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACnC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,cAAc,GAAG,QAAQ,CAAC;IACtD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kFAAkF;IAClF,WAAW,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxE,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,oDAAoD;AACpD,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuBxD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAyJ9E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAQjF"}
+{"version":3,"file":"exhaustion-report.d.ts","sourceRoot":"","sources":["../../src/learning/exhaustion-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,UAAU,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACnC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,cAAc,GAAG,QAAQ,CAAC;IACtD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kFAAkF;IAClF,WAAW,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxE,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,oDAAoD;AACpD,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuBxD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAoK9E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAQjF"}

package/dist/learning/exhaustion-report.js

@@ -17,7 +17,10 @@
  *      WALL-CLOCK TIME each cooling one frees up (a wait length is unactionable;
  *      "free at 18:42" is something a person can plan around);
  *   3. what the system itself is doing about it (routing to an untried model,
- *      or waiting for a window) — stated as the system's job, not the user's;
+ *      or waiting for a window) — stated as the system's job, not the user's,
+ *      and NEVER a promise it cannot keep: under a HELD pin nothing else is
+ *      tried by design, so the report says that instead of "an untried model
+ *      comes next automatically" (see `pinnedHeld`);
  *   4. the concrete levers only the user can pull: recharge/replace a rejected
  *      credential, knowingly accept a weaker model, or narrow the ask.
  *
@@ -117,7 +120,11 @@ export function buildExhaustionReport(input) {
     // models remained untouched. Presenting that as an outage is the dishonesty
     // the user called out when a healthy pool sat unused behind "no model
     // available".
-    const routingGap = poolMeasured && triedAttempts.length > 0 && poolSize > triedAttempts.length;
+    // A held pin is NOT a routing gap: the untried models were left alone because
+    // the caller's pin forbids them, not because the walk fell short. Reporting it
+    // as a gap would also promise the automatic next attempt that the pin blocks.
+    const pinHeld = input.pinnedHeld === true;
+    const routingGap = !pinHeld && poolMeasured && triedAttempts.length > 0 && poolSize > triedAttempts.length;
     const emptyPool = poolMeasured && poolSize === 0;
     const parts = [];
     const attemptCount = triedAttempts.length;
@@ -161,7 +168,10 @@ export function buildExhaustionReport(input) {
     }
     // ── What the SYSTEM is doing (never a question to the user) ──────────────
     parts.push('');
-    if (routingGap) {
+    if (pinHeld) {
+        parts.push(`Nothing else will be tried while the pin holds: ${input.pinnedModel ? input.pinnedModel : 'the model you named'} is the only one that may serve this run, so this is a deliberate stop and not a model shortage.`);
+    }
+    else if (routingGap) {
         parts.push(`This was a routing gap, not a shortage: only ${attemptCount} of ${poolSize} eligible models were actually tried. The next attempt routes to an untried model automatically — you do not need to trigger anything.`);
     }
     else if (emptyPool) {
@@ -194,9 +204,11 @@ export function buildExhaustionReport(input) {
     }
     options.push({
         code: 'weaker-model',
-        text: input.pinnedModel
-            ? `You pinned ${input.pinnedModel}, so nothing was run on a weaker model — say so explicitly if you would rather allow a weaker or cheaper one for this task.`
-            : 'Allow a weaker or cheaper model for this task and accept that its answer may need more checking.',
+        text: pinHeld
+            ? `Release the pin to let another model answer — set NUVIRA_STRICT_MODEL=0 on the CLI, or turn the chat's lock off in the dashboard. Until you do, nothing else is tried, by design.`
+            : input.pinnedModel
+                ? `You pinned ${input.pinnedModel}, so nothing was run on a weaker model — say so explicitly if you would rather allow a weaker or cheaper one for this task.`
+                : 'Allow a weaker or cheaper model for this task and accept that its answer may need more checking.',
     });
     options.push({
         code: 'narrow',