@qvac/harness 0.2.7 → 0.2.8

package/dist-lib/lib/tools/weather-lookup/report.js

@@ -0,0 +1,56 @@
+import { describePlace } from './place.js';
+const MAX_DAYS = 3;
+const DAY_LABELS = ['today', 'tomorrow'];
+const RANGE = '\u2013';
+const NOON = 4;
+function firstValue(values) {
+    return values?.[0]?.value?.trim() ?? '';
+}
+export function placeOf(json) {
+    const area = json.nearest_area?.[0];
+    if (area === undefined)
+        return null;
+    const place = {
+        area: firstValue(area.areaName),
+        region: firstValue(area.region),
+        country: firstValue(area.country)
+    };
+    return place.area || place.region || place.country ? place : null;
+}
+export function renderReport(json, place, asked, verified) {
+    const lines = [headline(place, asked, verified)];
+    const now = json.current_condition?.[0];
+    if (now !== undefined)
+        lines.push(currentLine(now));
+    const days = json.weather?.slice(0, MAX_DAYS) ?? [];
+    for (const [index, day] of days.entries())
+        lines.push(dailyLine(day, index));
+    return lines.join('\n');
+}
+function headline(place, asked, verified) {
+    const resolved = describePlace(place);
+    if (verified)
+        return resolved;
+    return `${resolved} (not "${asked}" — this is where it resolved)`;
+}
+function currentLine(now) {
+    const parts = [`Now: ${now.temp_C ?? '?'}°C / ${now.temp_F ?? '?'}°F`];
+    const desc = firstValue(now.weatherDesc);
+    if (desc)
+        parts.push(desc);
+    if (now.FeelsLikeC !== undefined)
+        parts.push(`feels like ${now.FeelsLikeC}°C`);
+    if (now.humidity !== undefined)
+        parts.push(`humidity ${now.humidity}%`);
+    if (now.windspeedKmph !== undefined)
+        parts.push(`wind ${now.windspeedKmph} km/h`);
+    return parts.join(', ');
+}
+function dailyLine(day, index) {
+    const label = DAY_LABELS[index];
+    const date = `${day.date ?? '?'}${label === undefined ? '' : ` (${label})`}`;
+    const celsius = `${day.mintempC ?? '?'}${RANGE}${day.maxtempC ?? '?'}°C`;
+    const fahrenheit = `${day.mintempF ?? '?'}${RANGE}${day.maxtempF ?? '?'}°F`;
+    const desc = firstValue(day.hourly?.[NOON]?.weatherDesc);
+    return `${date}: ${celsius} / ${fahrenheit}${desc ? `, ${desc}` : ''}`;
+}

package/dist-lib/lib/tools/weather-lookup.d.ts

@@ -0,0 +1,8 @@
+import type { ToolDefinition } from '../capabilities/completion.ts';
+import type { FetchFn } from './http-request.ts';
+import { type HostResolver } from './url-guard.ts';
+export interface WeatherLookupToolOptions {
+    fetch?: FetchFn;
+    resolveHost?: HostResolver;
+}
+export declare function createWeatherLookupTool({ fetch: fetchImpl, resolveHost }?: WeatherLookupToolOptions): ToolDefinition;

package/dist-lib/lib/tools/weather-lookup.js

@@ -0,0 +1,110 @@
+import defaultFetch from '#no-redirect-fetch';
+import { AbortController } from 'bare-abort-controller';
+import { lookupHost } from '../dns-lookup.js';
+import { isRedirectStatus } from './http-request/utils.js';
+import { resolveOutboundUrl } from './url-guard.js';
+import { checkQualifier, cityMatches, describePlace, qualifierOf } from './weather-lookup/place.js';
+import { placeOf, renderReport } from './weather-lookup/report.js';
+const WEATHER_HOST = 'wttr.in';
+const LOOKUP_TIMEOUT_MS = 15_000;
+const MAX_BODY_BYTES = 400_000;
+export function createWeatherLookupTool({ fetch: fetchImpl, resolveHost = lookupHost } = {}) {
+    return {
+        name: 'weather_lookup',
+        toolset: 'http-request',
+        skillGated: true,
+        autoApprove: true,
+        description: 'Look up the current weather and a three-day forecast for a place, via wttr.in. ' +
+            'Returns the place the service resolved on its first line, then the conditions now and ' +
+            'one line per day. Use it for any question about weather, temperature or forecast.',
+        parameters: {
+            type: 'object',
+            properties: {
+                location: {
+                    type: 'string',
+                    description: 'The place exactly as the user wrote it, including any country or state: ' +
+                        '"Nassau, Bahamas", "Paris, Texas", "London"'
+                }
+            },
+            required: ['location']
+        },
+        effect: () => 'read',
+        resource: () => ({ kind: 'host', label: WEATHER_HOST }),
+        async execute(args, ctx) {
+            const raw = args.location;
+            if (typeof raw !== 'string' || raw.trim().length === 0) {
+                return { error: 'location must be a non-empty string' };
+            }
+            const location = raw.trim();
+            if (ctx?.signal?.aborted)
+                return { error: 'weather_lookup cancelled' };
+            const url = new URL(`https://${WEATHER_HOST}/${encodeURIComponent(location)}?format=j1`);
+            const fetch = fetchImpl ?? defaultFetch;
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(undefined), LOOKUP_TIMEOUT_MS);
+            const onCallerAbort = () => controller.abort(undefined);
+            ctx?.signal?.addEventListener('abort', onCallerAbort);
+            try {
+                const check = await resolveOutboundUrl(url, resolveHost, ctx?.signal);
+                if (check.blocked)
+                    return { error: check.blocked };
+                const response = await fetch(url, {
+                    method: 'GET',
+                    headers: { Accept: 'application/json' },
+                    signal: controller.signal,
+                    redirect: 'manual',
+                    validatedAddresses: check.addresses,
+                    maxBytes: MAX_BODY_BYTES
+                });
+                if (isRedirectStatus(response.status)) {
+                    return { error: `${WEATHER_HOST} redirected the lookup for "${location}"` };
+                }
+                const body = await response.text();
+                if (/location not found/i.test(body))
+                    return { content: notFound(location) };
+                if (response.status !== 200) {
+                    return { error: unavailable(`it answered HTTP ${response.status}`) };
+                }
+                let json;
+                try {
+                    json = JSON.parse(body);
+                }
+                catch {
+                    return { error: unavailable('it did not return a forecast') };
+                }
+                const place = placeOf(json);
+                if (place === null)
+                    return { content: notFound(location) };
+                const qualifier = qualifierOf(location);
+                const verdict = qualifier === null ? null : checkQualifier(qualifier, place);
+                const named = cityMatches(location, place);
+                if (verdict === 'contradiction' && !named) {
+                    return {
+                        content: `No such place: "${location}". ${WEATHER_HOST} resolved it to ` +
+                            `${describePlace(place)}, which is somewhere else.`
+                    };
+                }
+                const verified = qualifier === null ? named : verdict === 'match';
+                return { content: renderReport(json, place, location, verified) };
+            }
+            catch (err) {
+                if (ctx?.signal?.aborted)
+                    return { error: 'weather_lookup cancelled' };
+                if (controller.signal.aborted) {
+                    return { error: `weather_lookup timed out after ${LOOKUP_TIMEOUT_MS} ms` };
+                }
+                return { error: unavailable(err instanceof Error ? err.message : String(err)) };
+            }
+            finally {
+                clearTimeout(timeout);
+                ctx?.signal?.removeEventListener('abort', onCallerAbort);
+            }
+        }
+    };
+}
+function unavailable(reason) {
+    return `The weather service could not be reached: ${reason}.`;
+}
+function notFound(location) {
+    return `No such place: "${location}". ${WEATHER_HOST} does not know it.`;
+}

package/dist-lib/lib/tools/web-fetch.js

@@ -1,15 +1,15 @@
 import defaultFetch from '#no-redirect-fetch';
 import { AbortController } from 'bare-abort-controller';
-import { lookupHost } from "../dns-lookup.js";
-import { AbortedError } from "../helpers/race-abort.js";
-import { extractEmbeddedState } from "../web-fetch/embedded-state.js";
-import { extractPageText, looksLikeHtml } from "../web-fetch/extract.js";
-import { imageFileName, pageImageUrls } from "../web-fetch/images.js";
-import { pageVideoRef } from "../web-fetch/video.js";
-import { MAX_HTML_CHARS } from "../web-search/fetch-html.js";
-import { BROWSER_UA } from "../web-search/user-agents.js";
-import { isRedirectStatus } from "./http-request/utils.js";
-import { resolveOutboundUrl } from "./url-guard.js";
+import { lookupHost } from '../dns-lookup.js';
+import { AbortedError } from '../helpers/race-abort.js';
+import { extractEmbeddedState } from '../web-fetch/embedded-state.js';
+import { extractPageText, looksLikeHtml } from '../web-fetch/extract.js';
+import { imageFileName, pageImageUrls } from '../web-fetch/images.js';
+import { pageVideoRef } from '../web-fetch/video.js';
+import { MAX_HTML_CHARS } from '../web-search/fetch-html.js';
+import { BROWSER_UA } from '../web-search/user-agents.js';
+import { isRedirectStatus } from './http-request/utils.js';
+import { resolveOutboundUrl } from './url-guard.js';
 const SMALL_CONTEXT_TOKENS = 12_288;
 const SMALL_CONTEXT_CHARS = 6_000;
 const LARGE_CONTEXT_CHARS = 16_000;

package/dist-lib/lib/tools/web-search.js

@@ -1,6 +1,6 @@
 import defaultFetch from '#fetch';
-import { formatResultsForPrompt } from "../web-search/format-results.js";
-import { searchWeb } from "../web-search/orchestrator.js";
+import { formatResultsForPrompt } from '../web-search/format-results.js';
+import { searchWeb } from '../web-search/orchestrator.js';
 const nodeFetch = async (url, init) => {
     const res = await defaultFetch(url, init);
     return { ok: res.ok, status: res.status, text: () => res.text() };

package/dist-lib/lib/transport.js

@@ -1,6 +1,6 @@
 import c from 'compact-encoding';
 import { Duplex } from 'streamx';
-export { settleOnClose } from "./rpc-session.js";
+export { settleOnClose } from './rpc-session.js';
 export function clientSessions(pipe) {
     let current = session(pipe);
     pipe.on('data', (chunk) => current.push(chunk));

package/dist-lib/lib/validating-lookup.js

@@ -1,4 +1,4 @@
-import { isPrivateOrBlocked } from "./tools/private-ip.js";
+import { isPrivateOrBlocked } from './tools/private-ip.js';
 export class BlockedAddressError extends Error {
     code = 'EBLOCKEDADDR';
     constructor(hostname, address) {

package/dist-lib/lib/web-fetch/embedded-state.js

@@ -1,4 +1,4 @@
-import { decodeHtmlEntities } from "../web-search/html-helpers.js";
+import { decodeHtmlEntities } from '../web-search/html-helpers.js';
 const LDJSON_SCRIPT = /<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
 const JSON_SCRIPT = /<script[^>]*type=["']application\/json["'][^>]*>([\s\S]*?)<\/script>/gi;
 const INLINE_SCRIPT = /<script\b(?![^>]*\bsrc=)(?![^>]*type=["']application\/(?:ld\+)?json["'])[^>]*>([\s\S]*?)<\/script>/gi;

package/dist-lib/lib/web-fetch/extract.js

@@ -1,4 +1,4 @@
-import { decodeHtmlEntities, stripHtmlTags } from "../web-search/html-helpers.js";
+import { decodeHtmlEntities, stripHtmlTags } from '../web-search/html-helpers.js';
 const NOISE_BLOCKS = [
     'script',
     'style',

package/dist-lib/lib/web-fetch/images.js

@@ -1,4 +1,4 @@
-import { decodeHtmlEntities } from "../web-search/html-helpers.js";
+import { decodeHtmlEntities } from '../web-search/html-helpers.js';
 const META_TAG = /<meta\s[^>]*>/gi;
 const IMAGE_ATTR = /(?:property|name)=["'](?:og:image(?::secure_url|:url)?|twitter:image)["']/i;
 const META_CONTENT = /content=["']([^"']+)["']/i;

package/dist-lib/lib/web-fetch/video.js

@@ -1,4 +1,4 @@
-import { decodeHtmlEntities } from "../web-search/html-helpers.js";
+import { decodeHtmlEntities } from '../web-search/html-helpers.js';
 const META_TAG = /<meta\s[^>]*>/gi;
 const VIDEO_ATTR = /(?:property|name)=["']og:video(?::secure_url|:url)?["']/i;
 const META_CONTENT = /content=["']([^"']+)["']/i;

package/dist-lib/lib/web-search/engine-registry.js

@@ -1,10 +1,10 @@
-import { searchAol } from "./engines/aol.js";
-import { searchBing } from "./engines/bing.js";
-import { searchBrave } from "./engines/brave.js";
-import { searchDuckDuckGo } from "./engines/duckduckgo.js";
-import { searchGoogle } from "./engines/google.js";
-import { searchWikipedia } from "./engines/wikipedia.js";
-import { searchYahoo } from "./engines/yahoo.js";
+import { searchAol } from './engines/aol.js';
+import { searchBing } from './engines/bing.js';
+import { searchBrave } from './engines/brave.js';
+import { searchDuckDuckGo } from './engines/duckduckgo.js';
+import { searchGoogle } from './engines/google.js';
+import { searchWikipedia } from './engines/wikipedia.js';
+import { searchYahoo } from './engines/yahoo.js';
 export const DEFAULT_MAX_RESULTS = 8;
 export const ENGINES = [
     { name: 'duckduckgo', fn: searchDuckDuckGo },

package/dist-lib/lib/web-search/engines/aol.js

@@ -1,6 +1,6 @@
-import { fetchHtml } from "../fetch-html.js";
-import { clean } from "../html-helpers.js";
-import { urlMatchesHost } from "../url-helpers.js";
+import { fetchHtml } from '../fetch-html.js';
+import { clean } from '../html-helpers.js';
+import { urlMatchesHost } from '../url-helpers.js';
 function decodeRuUrl(encoded) {
     try {
         const href = decodeURIComponent(encoded);

package/dist-lib/lib/web-search/engines/bing.js

@@ -1,7 +1,7 @@
-import { fetchHtml } from "../fetch-html.js";
-import { clean } from "../html-helpers.js";
-import { urlMatchesHost } from "../url-helpers.js";
-import { SAFARI_UA } from "../user-agents.js";
+import { fetchHtml } from '../fetch-html.js';
+import { clean } from '../html-helpers.js';
+import { urlMatchesHost } from '../url-helpers.js';
+import { SAFARI_UA } from '../user-agents.js';
 function isOrganicBingUrl(url) {
     return url.startsWith('http') && !urlMatchesHost(url, 'bing.com') && !url.includes('msockid=');
 }

package/dist-lib/lib/web-search/engines/brave.js

@@ -1,5 +1,5 @@
-import { fetchHtml } from "../fetch-html.js";
-import { clean } from "../html-helpers.js";
+import { fetchHtml } from '../fetch-html.js';
+import { clean } from '../html-helpers.js';
 function parseSnippetBlock(inner) {
     const urlMatch = inner.match(/<a[^>]*href="(https?:\/\/(?!imgs\.search\.brave)[^"]*)"[^>]*>/i);
     if (!urlMatch) {

package/dist-lib/lib/web-search/engines/duckduckgo.js

@@ -1,6 +1,6 @@
-import { fetchHtml } from "../fetch-html.js";
-import { clean } from "../html-helpers.js";
-import { urlMatchesHost } from "../url-helpers.js";
+import { fetchHtml } from '../fetch-html.js';
+import { clean } from '../html-helpers.js';
+import { urlMatchesHost } from '../url-helpers.js';
 function extractDdgUrl(raw) {
     if (raw.includes('uddg=')) {
         const m = raw.match(/uddg=([^&]+)/);

package/dist-lib/lib/web-search/engines/google.js

@@ -1,7 +1,7 @@
-import { fetchHtml } from "../fetch-html.js";
-import { clean } from "../html-helpers.js";
-import { urlMatchesHost } from "../url-helpers.js";
-import { GOOGLE_GSA_UA } from "../user-agents.js";
+import { fetchHtml } from '../fetch-html.js';
+import { clean } from '../html-helpers.js';
+import { urlMatchesHost } from '../url-helpers.js';
+import { GOOGLE_GSA_UA } from '../user-agents.js';
 function resolveGoogleUrl(rawUrl) {
     if (rawUrl.startsWith('/url?q=')) {
         return decodeURIComponent(rawUrl.slice(7).split('&')[0] || '');

package/dist-lib/lib/web-search/engines/wikipedia.js

@@ -1,5 +1,5 @@
-import { fetchJson } from "../fetch-html.js";
-import { clean } from "../html-helpers.js";
+import { fetchJson } from '../fetch-html.js';
+import { clean } from '../html-helpers.js';
 function extractSearchItems(data) {
     if (typeof data !== 'object' || data === null) {
         return [];

package/dist-lib/lib/web-search/engines/yahoo.js

@@ -1,6 +1,6 @@
-import { fetchHtml } from "../fetch-html.js";
-import { clean } from "../html-helpers.js";
-import { urlMatchesHost } from "../url-helpers.js";
+import { fetchHtml } from '../fetch-html.js';
+import { clean } from '../html-helpers.js';
+import { urlMatchesHost } from '../url-helpers.js';
 function decodeRuUrl(encoded) {
     try {
         const href = decodeURIComponent(encoded);

package/dist-lib/lib/web-search/fetch-html.js

@@ -1,5 +1,5 @@
 import { AbortController } from 'bare-abort-controller';
-import { BROWSER_UA } from "./user-agents.js";
+import { BROWSER_UA } from './user-agents.js';
 export const ENGINE_TIMEOUT_MS = 8000;
 export const MAX_HTML_CHARS = 2_000_000;
 export class TimeoutError extends Error {

package/dist-lib/lib/web-search/merge-results.js

@@ -1,4 +1,4 @@
-import { normalizeUrl } from "./url-normalize.js";
+import { normalizeUrl } from './url-normalize.js';
 const WEAK_RESULT_PENALTY = 0.2;
 function scoreFor(r) {
     const base = 1 / r.position;

package/dist-lib/lib/web-search/orchestrator.js

@@ -1,6 +1,6 @@
-import { DEFAULT_MAX_RESULTS, ENGINES } from "./engine-registry.js";
-import { TimeoutError } from "./fetch-html.js";
-import { mergeResults } from "./merge-results.js";
+import { DEFAULT_MAX_RESULTS, ENGINES } from './engine-registry.js';
+import { TimeoutError } from './fetch-html.js';
+import { mergeResults } from './merge-results.js';
 export function classifyEngineError(reason) {
     return reason instanceof TimeoutError ? 'timeout' : 'error';
 }

package/dist-lib/schema/baseline.js

@@ -2,7 +2,7 @@ import fs from 'bare-fs';
 import path from 'bare-path';
 import process from 'bare-process';
 import { spawnSync } from 'bare-subprocess';
-import { previousReleaseTags } from "./release-tags.js";
+import { previousReleaseTags } from './release-tags.js';
 export function rewindSpec(root, dirs, { carries, keep }) {
     if (process.env.SCHEMA_NO_BASELINE)
         return [];

package/dist-lib/schema/build.js

@@ -3,9 +3,9 @@ import { fileURLToPath } from 'bare-url';
 import HRPCBuilder from 'hrpc';
 import Hyperschema from 'hyperschema';
 import HyperschemaTS from 'hyperschema-ts';
-import { resetHrpcIds, rewindSpec, unstageSpec } from "./baseline.js";
-import { writeBind, writeClient } from "./generate.js";
-import { registerHarnessApi, registerHarnessTypes } from "./harness.js";
+import { resetHrpcIds, rewindSpec, unstageSpec } from './baseline.js';
+import { writeBind, writeClient } from './generate.js';
+import { registerHarnessApi, registerHarnessTypes } from './harness.js';
 const dir = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(dir, '..');
 const SPEC_DIR = path.join(dir, '..', 'spec');

package/dist-lib/schema/release-tags.d.ts

@@ -1,4 +1,5 @@
-export declare function currentReleaseLine(root: string): string;
+import { Version } from 'bare-semver';
+export declare function currentReleaseVersion(root: string): Version;
 export declare function previousReleaseTags(root: string, { count, carries }: {
     count?: number;
     carries: string;

package/dist-lib/schema/release-tags.js

@@ -2,24 +2,26 @@ import fs from 'fs';
 import path from 'path';
 import { spawnSync } from 'child_process';
 import { Version } from 'bare-semver';
-export function currentReleaseLine(root) {
+export function currentReleaseVersion(root) {
     const file = path.join(root, 'package.json');
     const { version } = JSON.parse(fs.readFileSync(file, 'utf8'));
-    const parsed = /^(\d+)\.(\d+)/.exec(version);
-    if (!parsed)
-        throw new Error(`no release line in package version ${version}`);
-    return `${parsed[1]}.${parsed[2]}`;
+    try {
+        return Version.parse(version);
+    }
+    catch {
+        throw new Error(`no release version in package version ${version}`);
+    }
 }
 const TAG_PREFIX = 'v';
 export function previousReleaseTags(root, { count = 3, carries }) {
-    const current = currentReleaseLine(root);
+    const current = currentReleaseVersion(root);
     const listed = spawnSync('git', ['tag', '-l', `${TAG_PREFIX}*`], { cwd: root });
     if (listed.status !== 0)
         throw new Error(`git tag -l failed: ${listed.stderr ?? ''}`);
     const newestPerLine = new Map();
     for (const line of (listed.stdout?.toString() ?? '').split('\n')) {
         const parsed = parseTag(line.trim());
-        if (!parsed || parsed.line === current)
+        if (!parsed || Version.compare(parsed.version, current) > 0)
             continue;
         const winner = newestPerLine.get(parsed.line);
         if (!winner || Version.compare(parsed.version, winner.version) > 0) {

package/docs/decisions/2026-09-10-skill-wording-is-measured-offline.md

@@ -0,0 +1,63 @@
+---
+id: ADR-2026-09-10-skill-wording-is-measured-offline
+status: active
+introduced_by: PR-2160
+supersedes: []
+---
+
+# A skill's wording is measured on the real small model before it ships
+
+## Decision
+
+A change to a bundled skill's `SKILL.md` that is meant to change model behaviour is measured before
+it lands: the candidate body and the current one run through `examples/skill-eval` on
+the real local 2B model, against a corpus of user-worded prompts, with the skill's tools answered
+from recorded fixtures and every reply judged by deterministic rules. The winning variant records
+its scores in the skill's front matter (`version:` plus a comment the model never sees).
+
+The eval drives `Harness.completion` in-process, swaps variants through the skills overlay
+(`writeSkillFile` / `deleteOverlaySkill`), and never uses a second model as a judge. Baseline is
+the bundled `@qvac/skills` tree, or any checkout named by `--skills-dir`.
+
+## Context
+
+The default mobile model is a 2B. It copies examples it is shown and ignores rules it cannot copy,
+and a wording that reads better to a human routinely scores worse on it. The weather skill's Nassau
+defect (QVAC-24701) was one line of guidance; nine candidate rewrites were tried and seven of them
+fixed the ticket prompt while regressing plain-city prompts through wrong URL suffixes. Only a
+measured comparison separated them, and only categories, not totals, showed the trade.
+
+Judging with a larger model was rejected: its verdicts vary run to run, cost a second inference per
+sample, and hide which rule failed. String laws over the call the model made and the reply it
+gave are reproducible and name the failure.
+
+Live network was rejected for the loop itself: wttr.in's answers change hourly and the source
+keys its format on the User-Agent. Recorded fixtures keep runs comparable; `--record` refreshes them
+deliberately, with the product's User-Agent.
+
+## Alternatives Considered
+
+- A Playwright smoke that sends one prompt through the desktop UI. It proves the wiring, not the
+  wording: one sample, no categories, no variant swap, and the UI adds minutes per run.
+- Tuning by hand in the TUI. Two repeats of a 130-run corpus already swing by about three runs;
+  a handful of manual tries cannot see a five-point change.
+
+## Consequences
+
+- A skill PR that changes model-facing text states its before/after category table, from this eval
+  or an equivalent pack, and keeps the score history in the front matter.
+- A new skill that needs measuring adds a pack (corpus, fake tools, judge) under
+  `examples/skill-eval/packs/`; the runner, routes, gap accounting and report are shared.
+- Differences under about five runs per 130 are noise at two repeats. Three repeats decide.
+- The eval is not CI: it needs the model weights and about four seconds per run. It is run by hand
+  and its output lives under the gitignored `output/`.
+- It lives here rather than in `@qvac/skills` because a pack is harness code: `world()` builds the
+  tools the model is offered. Here it needs no dependency the repo does not already have, and
+  `--variant` and `--skills-dir` already reach a skill body in another checkout.
+- Revisit if the SDK exposes a sampler seed (paired repeats would tighten the noise band) or if a
+  judge model becomes cheap and stable enough to grade open-ended replies.
+
+## When Agents Should Read This
+
+Read this when changing the paths, workflows, runtime boundaries, or platform
+behavior listed for this ADR in `docs/decisions/INDEX.md`.

package/docs/decisions/2026-09-16-a-lookup-reports-the-place-it-resolved.md

@@ -0,0 +1,70 @@
+---
+id: ADR-2026-09-16-a-lookup-reports-the-place-it-resolved
+status: active
+introduced_by: PR-52
+supersedes: []
+---
+
+# A provider that can silently resolve the wrong thing gets a typed tool, not a skill rule
+
+## Decision
+
+When a third-party lookup can answer `200` for a resource the user did not ask for, the harness owns
+the check in a typed tool rather than leaving it to skill prose. `weather_lookup` is the first: it
+asks wttr.in for the structured `format=j1` body, compares the place the geocoder resolved against
+the country or state the request named, refuses the answer when they contradict, and puts the
+resolved place on the first line of every report it does return.
+
+A skill keeps the judgement that is genuinely the model's: whether to call at all, and what location
+to send. The tool keeps the part that is arithmetic.
+
+## Context
+
+QVAC-24701 shipped a tuned `weather` skill and still failed QA. "What's the weather like in
+Xyzzyville, Atlantis?" produced a correct call, `200`, and the body
+`Xyzzyville, Atlantis: 🌦 +86°F`, which the model relayed. wttr.in echoes the request string back as
+the label and geocodes it fuzzily, so its answer for a place that does not exist is the weather of
+whatever it landed on — Atlantis, Florida. The same mechanism means a bare `Rome` currently answers
+with Lomé, in Togo.
+
+No wording can catch that. The skill already tells the model to report a failure on a non-200 or a
+`location not found` body; here the status and the body both look right, and the only evidence to the
+contrary is `nearest_area` inside a 40 KB JSON document the agent's context cannot hold and the
+response truncator would clip. Deciding whether "Atlantis" agrees with "Florida, United States of
+America" is string comparison with an alias table, which is the work a 2B is worst at and code is
+best at. Measured behaviour agrees: "ask before acting" rules top out near 30 % on that model in any
+wording.
+
+Only the qualifier is verified, never the city. The geocoder answers with the nearest populated area,
+which for a large city is routinely a neighbourhood that does not carry the city's name — São Paulo
+resolves to Liberdade, Sydney to Kirribilli, Tbilisi to Okrokana. Nine of thirty large cities probed
+would have been rejected by a city check. The region and country are reliable, and they are exactly
+what a wrong resolution gets wrong.
+
+## Alternatives Considered
+
+- An `operations.json` entry, the existing declarative path for provider calls. Every compiled
+  operation is a write: approval-gated, and its only response shaping is `pick` over top-level keys.
+  It cannot validate or refuse, and it would put an approval dialog in front of a weather question.
+- Keeping `http_request` and asking the skill for `format=j1`. The body does not fit the context, the
+  truncator clips it, and the comparison still lands on the model.
+- A wttr.in-specific hook that issues a second `j1` request and appends the resolved place to the
+  `http_request` result. Hidden coupling, two requests per answer, and the model still has to read it.
+
+## Consequences
+
+- The tool is `skillGated`, so its schema costs nothing until the weather skill body is in context,
+  and `autoApprove`, so the SDK does not inject a second `intent` argument into a one-argument read.
+  It names the `http-request` toolset, so the per-agent switch still turns it off.
+- A skill that grants `weather_lookup` requires a harness that has it. The bundled `weather` skill
+  keeps working on older harnesses only while it still grants `http_request`.
+- The alias table is data and will need names added. A qualifier it does not know falls back to a
+  plain substring match against the region and country, which is the behaviour it had before.
+- Adding a tool for every provider is not the intent. The trigger is specific: a provider that can
+  answer successfully about the wrong resource, where the evidence exists but not in a form the model
+  can be asked to check.
+
+## When Agents Should Read This
+
+Read this when changing the paths, workflows, runtime boundaries, or platform
+behavior listed for this ADR in `docs/decisions/INDEX.md`.