optbrew 0.1.2 → 0.2.0

package/skills/optbrew/scripts/adapters/anthropic.mjs

@@ -3,9 +3,9 @@ import { createHash } from 'node:crypto';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { reserveCost, settleCost } from '../core/cost-ledger.mjs';
+import { endpoints, limits } from '../core/config.mjs';
 
-const ENDPOINT = new URL('https://api.anthropic.com/v1/messages');
-const VERSION = '2023-06-01';
+const ENDPOINT = new URL(endpoints().anthropic_messages);
 // Official model overview, checked 2026-10-14. Accepted requests reserve the full context window plus max output.
 const MODELS = new Map(['claude-fable-5-1', 'claude-opus-5-5', 'claude-sonnet-5-5', 'claude-haiku-5-5']
   .map(id => [id, { contextTokens: 1_000_000, maxOutputTokens: 128_000 }]));
@@ -16,7 +16,7 @@ async function nodeTransport({ headers, body, timeoutMs, signal }) {
       const chunks = []; let size = 0;
       res.on('data', chunk => {
         size += chunk.length;
-        if (size > 5242880) { req.destroy(new Error('provider response too large')); return; }
+        if (size > limits().max_bytes) { req.destroy(new Error('provider response too large')); return; }
         chunks.push(chunk);
       });
       res.on('end', () => resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString('utf8') }));
@@ -76,12 +76,12 @@ export async function requestAnthropic({ context, request, env = process.env, tr
     try { reservation = await reserveCost(ledgerPath, { provider: 'anthropic', upperBounds, approvalRef: decision.approval_ref, runId: context.run_id }); }
     catch { return observation(request, 'cost_reservation_failed'); }
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 20000);
+    const timer = setTimeout(() => controller.abort(), limits().timeout_ms);
     let response;
     try {
       response = await Promise.race([
         transport({ url: ENDPOINT, headers: { 'content-type': 'application/json', 'x-api-key': env.ANTHROPIC_API_KEY,
-          'anthropic-version': VERSION }, body, timeoutMs: 20000, signal: controller.signal }),
+          'anthropic-version': endpoints().anthropic_version }, body, timeoutMs: limits().timeout_ms, signal: controller.signal }),
         new Promise((_, reject) => controller.signal.addEventListener('abort', () => reject(new Error('timeout')), { once: true })),
       ]);
     } catch {

package/skills/optbrew/scripts/adapters/imports.mjs

@@ -1,4 +1,141 @@
+import { inflateRawSync } from 'node:zlib';
 import { validateEntity, ContractError } from '../core/contracts.mjs';
+import { limits, versions } from '../core/config.mjs';
+
+// ZIP record signatures and the two compression methods Search Console's export uses.
+const ZIP_END = 0x06054b50;
+const ZIP_CENTRAL = 0x02014b50;
+const ZIP_STORED = 0;
+const ZIP_DEFLATED = 8;
+const ZIP_END_SIZE = 22;
+const ZIP_CENTRAL_SIZE = 46;
+const ZIP_LOCAL_SIZE = 30;
+// Search Console dates its performance report in Pacific time; Naver Search Advisor in Korea time.
+const GSC_TIMEZONE = 'America/Los_Angeles';
+const NAVER_TIMEZONE = 'Asia/Seoul';
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const NAVER_PERIOD = /(\d{4})[.-](\d{2})[.-](\d{2})\s*~\s*(\d{4})[.-](\d{2})[.-](\d{2})/;
+// Column names as the English and Korean screens print them.
+const DATE_COLUMNS = ['date', '날짜', '일자'];
+const CLICK_COLUMNS = ['clicks', '클릭수', '클릭'];
+const IMPRESSION_COLUMNS = ['impressions', '노출수', '노출'];
+
+/** A file the owner handed over that cannot be used; `reason` is a short code the report shows next to the missing numbers. */
+const unusable = reason => Object.assign(new Error(reason), { reason });
+
+/** The entries of a ZIP archive, read from its central directory. */
+function zipEntries(bytes) {
+  try {
+    let end = bytes.length - ZIP_END_SIZE;
+    while (end >= 0 && bytes.readUInt32LE(end) !== ZIP_END) end--;
+    if (end < 0) throw unusable('export_not_a_zip');
+    let offset = bytes.readUInt32LE(end + 16);
+    const entries = [];
+    for (let count = bytes.readUInt16LE(end + 10); count > 0; count--) {
+      if (bytes.readUInt32LE(offset) !== ZIP_CENTRAL) throw unusable('export_zip_damaged');
+      const [nameLength, extraLength, commentLength] = [28, 30, 32].map(at => bytes.readUInt16LE(offset + at));
+      entries.push({ name: bytes.toString('utf8', offset + ZIP_CENTRAL_SIZE, offset + ZIP_CENTRAL_SIZE + nameLength), method: bytes.readUInt16LE(offset + 10),
+        compressed: bytes.readUInt32LE(offset + 20), original: bytes.readUInt32LE(offset + 24), local: bytes.readUInt32LE(offset + 42) });
+      offset += ZIP_CENTRAL_SIZE + nameLength + extraLength + commentLength;
+    }
+    return entries;
+  } catch (error) { throw error.reason ? error : unusable('export_zip_damaged'); }
+}
+
+/** The text of one archive entry; an entry larger than the collection byte limit is refused, so a small file cannot expand into memory. */
+function zipText(bytes, entry) {
+  if (entry.original > limits().max_bytes) throw unusable('export_file_too_large');
+  try {
+    const start = entry.local + ZIP_LOCAL_SIZE + bytes.readUInt16LE(entry.local + 26) + bytes.readUInt16LE(entry.local + 28);
+    const data = bytes.subarray(start, start + entry.compressed);
+    if (entry.method === ZIP_STORED) return data.toString('utf8');
+    if (entry.method === ZIP_DEFLATED) return inflateRawSync(data, { maxOutputLength: limits().max_bytes }).toString('utf8');
+  } catch { throw unusable('export_zip_damaged'); }
+  throw unusable('export_zip_method_unsupported');
+}
+
+/** Rows of a CSV text (quoted cells, doubled quotes, CRLF), without a leading byte-order mark. */
+function csvRows(text) {
+  const rows = [];
+  let row = [], cell = '', quoted = false;
+  const input = text.replace(/^/, '');
+  for (let i = 0; i < input.length; i++) {
+    const char = input[i];
+    if (quoted) {
+      if (char === '"' && input[i + 1] === '"') { cell += '"'; i++; }
+      else if (char === '"') quoted = false;
+      else cell += char;
+    } else if (char === '"') quoted = true;
+    else if (char === ',') { row.push(cell); cell = ''; }
+    else if (char === '\n' || char === '\r') {
+      if (char === '\r' && input[i + 1] === '\n') i++;
+      row.push(cell); cell = '';
+      if (row.some(value => value !== '')) rows.push(row);
+      row = [];
+    } else cell += char;
+  }
+  row.push(cell);
+  if (row.some(value => value !== '')) rows.push(row);
+  return rows;
+}
+
+const column = (header, names) => header.findIndex(name => names.includes(name.trim().toLowerCase()));
+const count = value => { const number = Number(String(value).replace(/,/g, '')); return Number.isFinite(number) ? number : null; };
+
+/** Clicks and impressions as totals, with ctr as their ratio. */
+function trafficRows(clicks, impressions, label) {
+  return [
+    { metric_id: 'clicks', value: clicks, provider_definition: `${label}: clicks summed over the rows of the export` },
+    { metric_id: 'impressions', value: impressions, provider_definition: `${label}: impressions summed over the rows of the export` },
+    ...(impressions > 0 ? [{ metric_id: 'ctr', value: clicks / impressions, numerator: clicks, denominator: impressions,
+      provider_definition: `${label}: clicks divided by impressions over the rows of the export` }] : []),
+  ];
+}
+
+/** Search Console's CSV export: the archive's daily table (date, clicks, impressions) gives the totals and the period. */
+function readGsc(bytes) {
+  const archive = zipEntries(bytes);
+  for (const entry of archive.filter(x => x.name.toLowerCase().endsWith('.csv'))) {
+    const [header, ...body] = csvRows(zipText(bytes, entry));
+    if (!header) continue;
+    const [date, clicks, impressions] = [DATE_COLUMNS, CLICK_COLUMNS, IMPRESSION_COLUMNS].map(names => column(header, names));
+    if (date < 0 || clicks < 0 || impressions < 0 || !body.length || !body.every(row => ISO_DATE.test(row[date]))) continue;
+    const days = body.map(row => row[date]).sort();
+    const totals = body.map(row => [count(row[clicks]), count(row[impressions])]);
+    if (totals.some(pair => pair.includes(null))) throw unusable('export_numbers_unreadable');
+    return { provider: 'gsc', window: { start: days[0], end: days.at(-1), timezone: GSC_TIMEZONE }, sample_selection: { kind: 'all' },
+      rows: trafficRows(totals.reduce((sum, pair) => sum + pair[0], 0), totals.reduce((sum, pair) => sum + pair[1], 0), 'Search Console performance report') };
+  }
+  throw unusable('export_table_not_found');
+}
+
+/** Naver Search Advisor's pasted table: tab- or space-separated, a header with the click and impression columns, and the period printed above it. */
+function readNaver(bytes) {
+  const text = bytes.toString('utf8').replace(/^/, '');
+  const period = NAVER_PERIOD.exec(text);
+  if (!period) throw unusable('export_period_missing');
+  const lines = text.split(/\r?\n/).map(line => line.split(/\t| {2,}/).map(cell => cell.trim()).filter(Boolean));
+  const at = lines.findIndex(cells => column(cells, CLICK_COLUMNS) >= 0 && column(cells, IMPRESSION_COLUMNS) >= 0);
+  if (at < 0) throw unusable('export_table_not_found');
+  const [clicks, impressions] = [CLICK_COLUMNS, IMPRESSION_COLUMNS].map(names => column(lines[at], names));
+  const body = lines.slice(at + 1).filter(cells => cells.length > Math.max(clicks, impressions) && count(cells[clicks]) !== null && count(cells[impressions]) !== null);
+  if (!body.length) throw unusable('export_numbers_unreadable');
+  const [start, end] = [period.slice(1, 4), period.slice(4, 7)].map(parts => parts.join('-'));
+  // A pasted top-N table lists only its leading rows, so its totals say nothing about the whole site.
+  return { provider: 'naver', window: { start, end, timezone: NAVER_TIMEZONE }, sample_selection: { kind: 'unknown' },
+    rows: trafficRows(body.reduce((sum, cells) => sum + count(cells[clicks]), 0), body.reduce((sum, cells) => sum + count(cells[impressions]), 0), 'Naver Search Advisor table as pasted') };
+}
+
+/**
+ * The numbers an owner's export holds: `gsc` is the Search Console CSV export (a zip), `naver` the table pasted from Search
+ * Advisor as text. Returns `{ provider, window, sample_selection, rows }` for `normalizeImport`; a file that cannot be read
+ * throws an error whose `reason` names why, so the caller can report the gap instead of failing.
+ */
+export function readOwnerExport(kind, bytes) {
+  if (kind === 'gsc') return readGsc(bytes);
+  if (kind === 'naver') return readNaver(bytes);
+  throw unusable('export_kind_unknown');
+}
 
 const providers = new Set(['gsc', 'ga4', 'google_ai', 'bing_ai', 'naver', 'se_ranking']);
 const day = 86400000;
@@ -61,7 +198,7 @@ export function normalizeImport(provider, rows, metadata) {
     const dimensions = ['property', 'hostname', 'path', 'query', 'search_type', 'device', 'country', 'aggregation'];
     const dimension = key => row.filters?.[key] ?? metadata[key] ?? 'unknown';
     const export_scope = Object.fromEntries(dimensions.map(key => [key, metadata[key] ?? 'unknown']));
-    const observation = { schema_version: '1.0.0', metric_id: `${provider}:${row.metric_id}`,
+    const observation = { schema_version: versions().contract_schema, metric_id: `${provider}:${row.metric_id}`,
       value_state, value, numerator: row.numerator ?? null, denominator: row.denominator ?? null,
       definition: row.definition ?? row.provider_definition ?? metadata.provider_definition,
       filters: { ...(row.filters ?? {}), provider, property: dimension('property'),

package/skills/optbrew/scripts/audit.mjs

@@ -1,111 +1,25 @@
 #!/usr/bin/env node
-import { createHash } from 'node:crypto';
-import { spawn } from 'node:child_process';
 import { realpathSync } from 'node:fs';
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { validateEntity } from './core/contracts.mjs';
-import { collect, declaredRobotsIndex } from './core/collector.mjs';
-import { auditCollected } from '../modules/naver-searchadvisor/scripts/audit.mjs';
-import { deriveObservations } from './core/derive.mjs';
+import { runStages, stages } from './core/stages.mjs';
 
-const magnusScript = fileURLToPath(new URL('../modules/magnus-seo/scripts/aeo_audit.py', import.meta.url));
 const supported = new Set(['naver-searchadvisor', 'magnus-seo']);
-
-async function magnus(artifact) {
-  return new Promise(resolve => {
-    const child = spawn(process.platform === 'win32' ? 'python' : 'python3', [magnusScript, '--stdin', '--source-url', artifact.final_url, '--json'],
-      { stdio: ['pipe', 'pipe', 'pipe'] });
-    const chunks = []; let bytes = 0;
-    child.stdout.on('data', chunk => { bytes += chunk.length; if (bytes > 5242880) child.kill(); else chunks.push(chunk); });
-    child.on('error', () => resolve({ status: 'unavailable', reason: 'python_unavailable' }));
-    child.on('close', code => {
-      if (code !== 0) return resolve({ status: 'unavailable', reason: 'python_audit_failed' });
-      try { resolve(JSON.parse(Buffer.concat(chunks).toString('utf8'))); }
-      catch { resolve({ status: 'unavailable', reason: 'python_output_invalid' }); }
-    });
-    child.stdin.on('error', () => {});
-    child.stdin.end(artifact.body);
-  });
-}
+// The collection and the derivation of the collector verdicts: the stages `run.mjs` also runs, without rendering, field data or scoring.
+const AUDIT_STAGES = ['collect', 'derive'];
 
 /** Persist collector bytes and offline module output in the same run evidence directory. */
 export async function runAudit({ context, modules, outputDir, transport, resolve }) {
   validateEntity('RunContext', context);
   if (!Array.isArray(modules) || modules.some(x => !supported.has(x)) || !outputDir) throw new Error('unsupported modules or output directory');
-  const evidenceDir = path.join(outputDir, 'evidence');
-  await mkdir(evidenceDir, { recursive: true });
-  try { await access(path.join(evidenceDir, 'collection.json')); throw new Error('run evidence index already exists'); }
-  catch (error) { if (error.code !== 'ENOENT') throw error; }
-  const collection = await collect(context, { transport, resolve });
-  const artifacts = [];
-  const responses = [];
-  for (const artifact of collection.artifacts) {
-    const { body, ...saved } = artifact;
-    if (artifact.content_hash) {
-      const name = `${artifact.content_hash}.${artifact.capability === 'raw_html' ? 'html' : 'bin'}`;
-      const ref = path.join(evidenceDir, name);
-      try { await writeFile(ref, body, { flag: 'wx' }); }
-      catch (error) {
-        if (error.code !== 'EEXIST' || !Buffer.from(await readFile(ref)).equals(body)) throw error;
-      }
-      saved.raw_html_ref = artifact.capability === 'raw_html' ? ref : null;
-      saved.evidence_ref = ref;
-    } else saved.evidence_ref = path.join(evidenceDir, 'collection.json');
-    if (Number.isInteger(artifact.status)) {
-      // Hash the final URL, redirect chain and response header lines next to the raw body so the report replays from them.
-      const bytes = Buffer.from(`${JSON.stringify({ record_version: '1', requested_url: artifact.requested_url,
-        normalized_url: artifact.normalized_url, final_url: artifact.final_url, status: artifact.status,
-        redirect_chain: artifact.redirect_chain, header_lines: artifact.header_lines,
-        content_hash: artifact.content_hash, capability: artifact.capability }, null, 2)}\n`);
-      const content_hash = createHash('sha256').update(bytes).digest('hex');
-      const ref = path.join(evidenceDir, `${content_hash}.response.json`);
-      try { await writeFile(ref, bytes, { flag: 'wx' }); }
-      catch (error) {
-        if (error.code !== 'EEXIST' || !Buffer.from(await readFile(ref)).equals(bytes)) throw error;
-      }
-      saved.response_ref = ref;
-      responses.push({ normalized_url: artifact.normalized_url, evidence_ref: ref, content_hash });
-    }
-    artifacts.push(saved);
-  }
-  const module_outputs = Object.fromEntries(modules.map(x => [x, []]));
-  const declaredRobots = new Set((context.protocol.auxiliary_resources ?? [])
-    .filter(resource => resource.kind === 'robots').map(resource => resource.normalized));
-  const selectedUrls = new Set(context.protocol.page_types.flatMap(type => type.urls.map(x => x.normalized)));
-  for (const artifact of collection.artifacts) {
-    if (!selectedUrls.has(artifact.normalized_url) || artifact.capability !== 'raw_html' || artifact.status !== 200) continue;
-    const html = artifact.body.toString('utf8');
-    if (modules.includes('naver-searchadvisor')) {
-      const robotsIndex = declaredRobotsIndex(collection.artifacts, declaredRobots, artifact.final_url);
-      const robots = robotsIndex < 0 ? null : collection.artifacts[robotsIndex];
-      const robotsEvidenceRef = robots?.status === 200 ? artifacts[robotsIndex].evidence_ref : null;
-      const output = auditCollected({ artifact, html, engines: context.protocol.engines,
-        robotsArtifact: robots ? { ...robots, body: robots.body.toString('utf8') } : null });
-      output.robots_evidence_ref = robotsEvidenceRef;
-      module_outputs['naver-searchadvisor'].push(output);
-    }
-    if (modules.includes('magnus-seo')) module_outputs['magnus-seo'].push(await magnus(artifact));
-  }
-  // Verdicts come from one derivation shared with the report replay.
-  const bodies = new Map(collection.artifacts.map(x => [x.normalized_url, x.body]));
-  const observations = deriveObservations({ context, artifacts, collection,
-    textOf: x => bodies.get(x.normalized_url)?.toString('utf8') ?? null });
-  const result = { context_ref: context.evidence_ref, artifacts, observations, module_outputs,
-    evidence_ref: path.join(evidenceDir, 'evidence-index.json'), discovered_count: collection.discovered_count,
-    evaluated_count: collection.evaluated_count, request_count: collection.request_count, skipped: collection.skipped, limit_reached: collection.limit_reached };
-  await writeFile(path.join(evidenceDir, 'collection.json'), `${JSON.stringify({ artifacts, discovered_count: collection.discovered_count,
-    evaluated_count: collection.evaluated_count, request_count: collection.request_count, skipped: collection.skipped, limit_reached: collection.limit_reached }, null, 2)}\n`, { flag: 'wx' });
-  await writeFile(path.join(evidenceDir, 'ledger.json'), `${JSON.stringify({ entries: collection.ledger, limit: Math.min(context.scope?.max_urls ?? 50, 50) }, null, 2)}\n`, { flag: 'wx' });
-  await writeFile(path.join(evidenceDir, 'modules.json'), `${JSON.stringify(module_outputs, null, 2)}\n`, { flag: 'wx' });
-  await writeFile(path.join(evidenceDir, 'observations.json'), `${JSON.stringify(observations, null, 2)}\n`, { flag: 'wx' });
-  await writeFile(result.evidence_ref, `${JSON.stringify({ run_id: context.run_id, context_ref: context.evidence_ref,
-    collection_ref: path.join(evidenceDir, 'collection.json'), module_output_ref: path.join(evidenceDir, 'modules.json'),
-    observations_ref: path.join(evidenceDir, 'observations.json'), ledger_ref: path.join(evidenceDir, 'ledger.json'), modules,
-    raw: artifacts.map(x => ({ normalized_url: x.normalized_url, evidence_ref: x.evidence_ref, content_hash: x.content_hash })),
-    responses }, null, 2)}\n`, { flag: 'wx' });
-  return result;
+  const parts = stages().filter(stage => AUDIT_STAGES.includes(stage.name));
+  const { state } = await runStages(parts, { context, modules, out: outputDir, route: { transport, resolve } }, {});
+  const { audit } = state;
+  return { context_ref: context.evidence_ref, artifacts: audit.artifacts, observations: state.observations, module_outputs: audit.module_outputs,
+    evidence_ref: state.store.indexRef, discovered_count: audit.discovered_count, evaluated_count: audit.evaluated_count,
+    request_count: audit.request_count, skipped: audit.skipped, limit_reached: audit.limit_reached };
 }
 
 if (process.argv[1] && realpathSync(path.resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))) {

package/skills/optbrew/scripts/cli.mjs

@@ -5,6 +5,8 @@ import { fileURLToPath } from 'node:url';
 import { score } from './core/score.mjs';
 import { compare } from './core/compare.mjs';
 import { writeReport } from './core/report.mjs';
+import { htmlReportWriter } from './core/report-page.mjs';
+import { MigrationRequired } from './core/migration.mjs';
 
 /** Local calculation CLI. */
 export async function runCli(argv = process.argv.slice(2)) {
@@ -16,7 +18,8 @@ export async function runCli(argv = process.argv.slice(2)) {
     packet.evidence_root = path.resolve(path.dirname(input), packet.evidence_root ?? '.');
     const relative = path.relative(await realpath(path.dirname(input)), await realpath(packet.evidence_root));
     if (relative === '..' || relative.startsWith(`..${path.sep}`)) throw new Error('evidence root must stay under packet run directory');
-    return writeReport(packet, path.resolve(argv[4]));
+    // The page is written beside the other two, as a run writes it. A packet does not record the guidance level, so the full steps are used.
+    return writeReport(packet, path.resolve(argv[4]), { renderHtml: htmlReportWriter({ level: 'beginner', target: packet.run_context?.target, synthetic: packet.data_class === 'synthetic' }) });
   } else if (argv.length === 5 && argv[0] === 'score' && argv[1] === '--input' && argv[3] === '--output' && argv[2] && argv[4]) {
     result = score(JSON.parse(await readFile(argv[2], 'utf8')));
     destination = path.resolve(argv[4]);
@@ -37,5 +40,5 @@ export async function runCli(argv = process.argv.slice(2)) {
 }
 
 if (process.argv[1] && realpathSync(path.resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))) {
-  runCli().catch(error => { process.stderr.write(`${error.name}: ${error.message}\n`); process.exitCode = 1; });
+  runCli().catch(error => { process.stderr.write(`${error instanceof MigrationRequired ? '' : `${error.name}: `}${error.message}\n`); process.exitCode = 1; });
 }

package/skills/optbrew/scripts/core/bundle.mjs

@@ -1,13 +1,27 @@
 import { createHash } from 'node:crypto';
 import { readFile, readdir } from 'node:fs/promises';
 import path from 'node:path';
+import { versions } from './config.mjs';
 
 const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+/** Hash a file as committed: a checkout with core.autocrlf may turn LF into CRLF. A NUL byte marks a binary file, hashed as is. */
+export const fileDigest = bytes => digest(bytes.includes(0) ? bytes : Buffer.from(bytes.toString('latin1').replaceAll('\r\n', '\n'), 'latin1'));
 const manifestName = 'bundle-manifest.json';
+/**
+ * The files whose bytes decide a verdict or a score: the registry, profiles and scoring rules, the code that turns evidence into
+ * verdicts (derive, every check, the index-target, judgment, fact, link and page-selection rules, the vendored Naver audit) and the
+ * Korean catalog the verdict sentences come from. A bundle that changes any of them has a different `evaluation_hash` (T22 S1).
+ * `checks/*` is listed file by file; a test fails when a file is added to that folder and not here.
+ */
 export const evaluationSourcePaths = ['references/check-registry.json', 'references/profiles.json',
-  'references/scoring.md', 'references/measurement.md', 'scripts/core/score.mjs', 'scripts/core/weights.mjs',
-  'scripts/core/contracts.mjs', 'scripts/core/compare.mjs', 'scripts/core/metrics.mjs', 'scripts/core/bootstrap.mjs'];
-export const protocolSourcePaths = ['references/schemas/contract.schema.json', 'scripts/core/protocol.mjs'];
+  'references/scoring.md', 'references/measurement.md', 'references/messages.ko.json', 'scripts/core/score.mjs', 'scripts/core/weights.mjs',
+  'scripts/core/contracts.mjs', 'scripts/core/compare.mjs', 'scripts/core/metrics.mjs', 'scripts/core/bootstrap.mjs',
+  'scripts/core/derive.mjs', 'scripts/core/index-targets.mjs', 'scripts/core/judgments.mjs', 'scripts/core/facts.mjs',
+  'scripts/core/link-graph.mjs', 'scripts/core/page-select.mjs', 'modules/naver-searchadvisor/scripts/audit.mjs',
+  ...['canonical-consistency', 'cwv-field', 'discovery', 'document-title', 'entity-identity', 'fact-consistency', 'fetch-response', 'index-policy',
+    'index', 'internal-navigation', 'locale-links', 'naver-markup', 'observation', 'prepare', 'render-content', 'search-crawl-policy',
+    'structured-data-truth'].map(name => `scripts/core/checks/${name}.mjs`)];
+export const protocolSourcePaths = ['references/schemas/contract.schema.json', 'references/limits.json', 'scripts/core/protocol.mjs'];
 
 /** Match the package.json skill exclusions for generated Python cache files. */
 export function isDistributedBundlePath(relative) {
@@ -29,33 +43,36 @@ async function listFiles(root, relative = '') {
   return result.sort();
 }
 
-/** Hash every distributed file; the manifest never hashes itself. */
-export async function createBundleManifest({ bundleRoot, releaseVersion }) {
+/** Hash every distributed file; the manifest never hashes itself. `sources` names the identity files; verification passes the lists a manifest recorded. */
+export async function createBundleManifest({ bundleRoot, releaseVersion, sources = { evaluation: evaluationSourcePaths, protocol: protocolSourcePaths } }) {
   if (!/^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(releaseVersion)) throw new Error('invalid release version');
   const files = [];
   for (const name of await listFiles(bundleRoot)) {
-    files.push({ path: name, sha256: digest(await readFile(path.join(bundleRoot, name))) });
+    files.push({ path: name, sha256: fileDigest(await readFile(path.join(bundleRoot, name))) });
   }
   // Synthetic install fixtures contain only SKILL.md; production release checks completeness.
   const selected = paths => paths.every(name => files.some(file => file.path === name))
     ? paths.map(name => files.find(file => file.path === name)) : [];
-  const evaluation_sources = selected(evaluationSourcePaths);
-  const protocol_sources = selected(protocolSourcePaths);
+  const evaluation_sources = selected(sources.evaluation);
+  const protocol_sources = selected(sources.protocol);
   const identity = evaluation_sources.length && protocol_sources.length ? {
-    evaluation_version: '0.2.0', protocol_version: '0.1.0',
+    evaluation_version: versions().evaluation, protocol_version: versions().protocol,
     evaluation_sources, evaluation_hash: digest(JSON.stringify(evaluation_sources)),
     protocol_sources, protocol_hash: digest(JSON.stringify(protocol_sources)) } : {};
-  return { schema_version: '1.0.0', release_version: releaseVersion,
+  return { schema_version: versions().bundle_manifest_schema, release_version: releaseVersion,
     ...identity, files, bundle_hash: digest(JSON.stringify(files)) };
 }
 
-/** Verify the exact allowlist, byte hashes, and aggregate hash. */
+const recordedPaths = (list, fallback) => Array.isArray(list) ? list.map(file => file?.path) : fallback;
+
+/** Verify the exact allowlist, byte hashes, and aggregate hash. Identity is recomputed over the source lists the manifest recorded, so an older bundle with fewer sources still verifies. */
 export async function verifyBundle({ bundleRoot, manifest }) {
   const errors = [];
   let actual;
-  try { actual = await createBundleManifest({ bundleRoot, releaseVersion: manifest?.release_version }); }
+  try { actual = await createBundleManifest({ bundleRoot, releaseVersion: manifest?.release_version, sources: {
+    evaluation: recordedPaths(manifest?.evaluation_sources, evaluationSourcePaths), protocol: recordedPaths(manifest?.protocol_sources, protocolSourcePaths) } }); }
   catch (error) { return { status: 'invalid', checked_files: 0, errors: [{ path: '', code: error.message }], bundle_hash: null }; }
-  if (!Array.isArray(manifest?.files) || manifest.schema_version !== '1.0.0') errors.push({ path: manifestName, code: 'invalid_manifest' });
+  if (!Array.isArray(manifest?.files) || manifest.schema_version !== versions().bundle_manifest_schema) errors.push({ path: manifestName, code: 'invalid_manifest' });
   const expected = new Map(Array.isArray(manifest?.files) ? manifest.files.map(f => [f.path, f.sha256]) : []);
   const found = new Map(actual.files.map(f => [f.path, f.sha256]));
   if (expected.size !== manifest?.files?.length) errors.push({ path: manifestName, code: 'duplicate_path' });

package/skills/optbrew/scripts/core/capabilities.mjs

@@ -1,6 +1,10 @@
+import { messageOf } from './messages.mjs';
+
 /** Match actual evidence surfaces to requested checks without inventing missing capability. */
 export function selectCapabilities(available, requirements) {
-  const selected = []; const missing = []; const limitations = [];
+  const selected = []; const missing = []; const limitations = []; const limitation_messages = [];
+  // Each limitation keeps its English text and, at the same position, the catalog key and values of its Korean sentence.
+  const limit = (text, message) => { limitations.push(text); limitation_messages.push(message); };
   for (const requirement of requirements) {
     const names = requirement === 'structured_data' ? ['raw_html'] : [requirement];
     const candidate = available.find(item => names.includes(item.capability) && item.bounded === true &&
@@ -8,12 +12,12 @@ export function selectCapabilities(available, requirements) {
     if (!candidate || (requirement === 'bulk_crawl' && candidate.cost_enforcement !== 'code')) {
       missing.push(requirement);
       if (requirement === 'bulk_crawl' && available.some(item => item.capability === 'bulk_crawl'))
-        limitations.push('bulk_crawl: boundary or cost enforcement is host_policy/unverified');
+        limit('bulk_crawl: boundary or cost enforcement is host_policy/unverified', messageOf('cost.bulk-crawl-unverified'));
       continue;
     }
     selected.push({ capability: candidate.capability, provider: candidate.provider, tool_ref: candidate.tool_ref,
       cost_enforcement: candidate.cost_enforcement });
-    if (candidate.cost_enforcement === 'host_policy') limitations.push(`${candidate.provider}: host_policy cannot enforce paid cost in code`);
+    if (candidate.cost_enforcement === 'host_policy') limit(`${candidate.provider}: host_policy cannot enforce paid cost in code`, messageOf('cost.host-policy', { provider: candidate.provider }));
   }
-  return { selected, missing, limitations };
+  return { selected, missing, limitations, limitation_messages };
 }

package/skills/optbrew/scripts/core/cdp.mjs

@@ -0,0 +1,105 @@
+/** A DevTools transport is `{ send(text), close(), onmessage, onclose }`; the client sets the two callbacks. */
+
+/** Chrome's `--remote-debugging-pipe`: JSON texts, each ended by a NUL byte, written to fd 3 and read from fd 4. */
+export function pipeTransport(writable, readable) {
+  let pending = [];
+  const transport = {
+    onmessage: null,
+    onclose: null,
+    send: text => { writable.write(`${text}\0`); },
+    close: () => { writable.destroy(); readable.destroy(); },
+  };
+  // A write to a pipe that Chrome has closed raises EPIPE; the client already sees the close.
+  writable.on('error', () => {});
+  readable.on('error', () => {});
+  readable.on('data', chunk => {
+    pending.push(chunk);
+    if (chunk.indexOf(0) === -1) return;
+    const all = Buffer.concat(pending);
+    let start = 0;
+    for (let end = all.indexOf(0); end !== -1; end = all.indexOf(0, start)) {
+      const text = all.toString('utf8', start, end);
+      start = end + 1;
+      transport.onmessage?.(text);
+    }
+    pending = start < all.length ? [all.subarray(start)] : [];
+  });
+  readable.on('close', () => transport.onclose?.());
+  return transport;
+}
+
+/** The port variant: a browser-level WebSocket from `DevToolsActivePort`, using the global `WebSocket` (Node 22.4+). */
+export function webSocketTransport(url) {
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocket(url);
+    const transport = {
+      onmessage: null,
+      onclose: null,
+      send: text => { socket.send(text); },
+      close: () => { socket.close(); },
+    };
+    socket.addEventListener('message', event => transport.onmessage?.(String(event.data)));
+    socket.addEventListener('close', () => transport.onclose?.());
+    socket.addEventListener('open', () => resolve(transport), { once: true });
+    socket.addEventListener('error', () => reject(new Error('devtools websocket failed')), { once: true });
+  });
+}
+
+/**
+ * `CdpClient = { send(method, params?, sessionId?), on(event, fn) }` over one transport. `on` hands the handler
+ * `(params, sessionId)` and returns a function that removes it. Errors name the method, never the parameters.
+ */
+export function createCdpClient(transport, { timeoutMs }) {
+  let nextId = 0;
+  const pending = new Map();
+  const handlers = new Map();
+  let closed = false;
+
+  transport.onmessage = text => {
+    let message;
+    try { message = JSON.parse(text); } catch { return; }
+    if (message.id !== undefined) {
+      const entry = pending.get(message.id);
+      if (!entry) return;
+      pending.delete(message.id);
+      clearTimeout(entry.timer);
+      if (message.error) entry.reject(new Error(`${entry.method}: ${message.error.message}`));
+      else entry.resolve(message.result ?? {});
+    } else if (message.method) {
+      for (const fn of [...handlers.get(message.method) ?? []]) fn(message.params ?? {}, message.sessionId);
+    }
+  };
+  transport.onclose = () => {
+    closed = true;
+    for (const [id, entry] of pending) {
+      pending.delete(id);
+      clearTimeout(entry.timer);
+      entry.reject(new Error(`${entry.method}: devtools connection closed`));
+    }
+  };
+
+  return {
+    send(method, params, sessionId) {
+      if (closed) return Promise.reject(new Error(`${method}: devtools connection closed`));
+      const id = ++nextId;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error(`${method}: devtools command timed out`));
+        }, timeoutMs);
+        pending.set(id, { method, resolve, reject, timer });
+        try { transport.send(JSON.stringify({ id, method, params, sessionId })); }
+        catch (error) {
+          pending.delete(id);
+          clearTimeout(timer);
+          reject(error);
+        }
+      });
+    },
+    on(event, fn) {
+      if (!handlers.has(event)) handlers.set(event, new Set());
+      handlers.get(event).add(fn);
+      return () => { handlers.get(event).delete(fn); };
+    },
+  };
+}

package/skills/optbrew/scripts/core/checks/canonical-consistency.mjs

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { visibleText } from '../html.mjs';
+import { makeObservation, problem, unitKey } from './observation.mjs';
+
+const FAMILY = 'canonical-consistency';
+const REDIRECT_CHAIN = problem('Redirect chain of two or more hops', 'canonical-consistency.redirect-chain');
+const TARGET_STATUS = problem('canonical target does not return a successful status', 'canonical-consistency.target-status');
+const INVALID_URL = problem('canonical is not a valid URL', 'canonical-consistency.invalid-url');
+const NO_POLICY = 'The page declares no canonical URL and does not redirect';
+const REPEATED = 'Another audited page has the same title or body text, so whether this page needs a representative URL is not established';
+
+/** Redirect depth, and whether the declared canonical points at this page or at a reachable one. */
+export const canonicalConsistency = {
+  family_id: FAMILY,
+  message_keys: [REDIRECT_CHAIN, TARGET_STATUS, INVALID_URL].map(item => item.message_key),
+  derive({ pageRows, artifacts }) {
+    const out = [];
+    // Pages that share their body text with another audited page, or their title, by url.
+    const bodyText = html => visibleText(/<body\b[^>]*>([\s\S]*)/i.exec(String(html ?? ''))?.[1] ?? html);
+    const bodyOf = new Map(pageRows.map(row => [row, createHash('sha256').update(bodyText(row.html)).digest('hex')]));
+    const repeated = new Map();
+    for (const row of pageRows) {
+      const others = pageRows.filter(other => other !== row && other.artifact.final_url !== row.artifact.final_url);
+      const urls = others.filter(other => bodyOf.get(other) === bodyOf.get(row) || row.titleKey !== null && other.titleKey === row.titleKey).map(other => other.url);
+      if (urls.length) repeated.set(row.url, urls);
+    }
+    for (const { url, artifact, info } of pageRows) {
+      const hops = artifact.redirect_chain?.length ?? 0;
+      let canonicalState = null, canonicalProblem = null;
+      const measurement = { redirect_hops: hops, canonical_target: null, canonical_status: null };
+      if (info.canonical) {
+        try {
+          const target = new URL(info.canonical, artifact.final_url); target.hash = '';
+          measurement.canonical_target = target.href;
+          const other = artifacts.find(x => x.normalized_url === target.href || x.final_url === target.href);
+          if (target.href === artifact.final_url || target.href === artifact.normalized_url) canonicalState = 'pass';
+          else if (other && other.status >= 200 && other.status < 300) canonicalState = 'pass';
+          else if (other && Number.isInteger(other.status)) { canonicalState = 'fail'; canonicalProblem = TARGET_STATUS; measurement.canonical_status = other.status; }
+        } catch { canonicalState = 'fail'; canonicalProblem = INVALID_URL; }
+      }
+      // Fixed sentences; the hop count, the target and its status are page-specific and travel in the measurement.
+      const observe = (state, stated) => out.push(makeObservation({ family_id: FAMILY, unit_key: unitKey(FAMILY, url), state, evidence_ref: artifact.evidence_ref, ...stated }));
+      const problems = [...(hops >= 2 ? [REDIRECT_CHAIN] : []), ...(canonicalProblem ? [canonicalProblem] : [])];
+      if (problems.length) observe('fail', { problems, extra: { measurement: { ...measurement, problems: problems.map(item => item.text) } } });
+      else if (canonicalState === 'pass') observe('pass', { reason: 'Canonical target is this page or a reachable page and redirects stay within one hop', extra: { measurement } });
+      // With no canonical tag the page declares no representative URL: after one redirect hop the redirect is that policy and nothing
+      // disagrees with it; with no redirect either, there is no policy to be consistent with. That holds only for a page no other
+      // audited page repeats: a page with the same title or body as another is one that needs a representative URL.
+      else if (!info.canonical && hops < 2 && repeated.has(url)) observe('unknown', { reason: REPEATED, extra: { measurement: { ...measurement, repeated_with: repeated.get(url) } } });
+      else if (!info.canonical && hops === 1) observe('pass', { reason: 'No canonical is declared; the one redirect hop is the page\'s URL policy and stays within the limit', extra: { measurement } });
+      else if (!info.canonical && hops === 0) observe('not_applicable', { reason: NO_POLICY, extra: { measurement,
+        applicability_decision: { condition: 'no_representative_url_policy', reason: NO_POLICY, evidence_ref: artifact.evidence_ref } } });
+    }
+    return out;
+  },
+};