optbrew 0.1.2 → 0.1.3

package/skills/optbrew/references/ai-crawlers.json

@@ -5,7 +5,7 @@
   "engines": {
     "google": { "agent": "Googlebot", "role": "search", "source": "https://developers.google.com/search/docs/crawling-indexing/google-common-crawlers" },
     "google_ai": { "agent": "Googlebot", "role": "search", "source": "https://developers.google.com/search/docs/appearance/ai-features" },
-    "naver": { "agent": "Yeti", "role": "search", "source": "https://searchadvisor.naver.com/guide/seo-basic-robots" },
+    "naver": { "agent": "Yeti", "role": "search", "source": "https://searchadvisor.naver.com/guide/seo-basic-robots", "verified": "2026-10-15", "evidence": "The page (HTTP 200) uses `User-agent: Yeti` in its robots.txt examples; page text sha256 ff8ddc85c5dd42e0d1133abae6928fb9b42f67f35d1b2c89b40378009571ed49" },
     "chatgpt": { "agent": "OAI-SearchBot", "role": "search", "aliases": ["openai"], "source": "https://developers.openai.com/api/docs/bots" },
     "claude": { "agent": "Claude-SearchBot", "role": "search", "aliases": ["anthropic"], "source": "https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler" },
     "perplexity": { "agent": "PerplexityBot", "role": "search", "source": "https://docs.perplexity.ai/guides/bots" }

package/skills/optbrew/references/ai-crawlers.md

@@ -5,7 +5,7 @@
 | Protocol engine | robots.txt token | Role | Vendor statement (summary) |
 | --- | --- | --- | --- |
 | `google`, `google_ai` | Googlebot | search | Google's AI features need no extra technical requirement: a page must be indexed and snippet-eligible, and "robots.txt directives for Googlebot is the control for site owners" ([AI features](https://developers.google.com/search/docs/appearance/ai-features)). |
-| `naver` | Yeti | search | Naver Search Advisor robots guidance. |
+| `naver` | Yeti | search | Naver Search Advisor robots guidance ([robots.txt guide](https://searchadvisor.naver.com/guide/seo-basic-robots)): its robots.txt examples use `User-agent: Yeti`. Read again on 2026-10-15 (HTTP 200, page text sha256 `ff8ddc85c5dd42e0d1133abae6928fb9b42f67f35d1b2c89b40378009571ed49`). |
 | `chatgpt` (alias `openai`) | OAI-SearchBot | search | Sites opted out of OAI-SearchBot are not shown in ChatGPT search answers ([OpenAI bots](https://developers.openai.com/api/docs/bots)). |
 | `claude` (alias `anthropic`) | Claude-SearchBot | search | Blocking stops indexing for Claude search and may reduce visibility ([Anthropic](https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler)). |
 | `perplexity` | PerplexityBot | search | Surfaces and links sites in Perplexity results and is not used for foundation-model training ([Perplexity](https://docs.perplexity.ai/guides/bots)). |

package/skills/optbrew/references/api.md

@@ -1,8 +1,8 @@
 # Collection and optional API boundary
 
-The optbrew audit command is `node skills/optbrew/scripts/audit.mjs --context <run-context.json> --modules naver-searchadvisor,magnus-seo --output-dir <run-dir>`. It writes raw responses, one hashed `<sha256>.response.json` record per response (final URL, redirect chain and every collected header line, repeated lines kept separate), `collection.json`, `modules.json`, `observations.json` and `evidence-index.json` under `<run-dir>/evidence/`. The evidence index binds the run ID, context reference, raw response hashes, response record hashes (`responses`) and module/observation paths for later scoring and reporting. Reusing an output directory with an existing collection index is rejected. The audit never posts to a search engine or changes the site.
+The optbrew audit command is `node skills/optbrew/scripts/audit.mjs --context <run-context.json> --modules naver-searchadvisor,magnus-seo --output-dir <run-dir>`. It writes raw responses, one hashed `<sha256>.response.json` record per response (final URL, redirect chain and every collected header line, repeated lines kept separate), one hashed `<sha256>.failure.json` record per failed fetch (answered redirect hops and whether one more attempt got no response), `collection.json`, `modules.json`, `observations.json` and `evidence-index.json` under `<run-dir>/evidence/`. The evidence index binds the run ID, context reference, raw response hashes, response record hashes (`responses`), failure record hashes (`failures`) and module/observation paths for later scoring and reporting. Reusing an output directory with an existing collection index is rejected. The audit never posts to a search engine or changes the site.
 
-`RunContext.scope.allowed` is a nonempty list of `{ "origin": "https://example.org", "path_prefix": "/owned/" }`. An origin fixes scheme, host and effective port. The path prefix is segment bounded. `scope.local_targets` may list explicit `{ "host": "localhost", "port": 8765 }` pairs for a declared local target. Without this pair, loopback, private, link-local, ULA and mapped IPv4 addresses are blocked. The default ceilings are 50 URLs, depth 3, concurrency 2, 20 seconds, 5 MiB and 10 redirects. Lower limits may be set with `max_urls`, `max_depth` and `concurrency`. The request limit (`max_urls`, at most 50) decides only whether a new fetch may start: a fetch starts while fewer requests than the limit have been made, and a redirect chain that has started is completed. A chain follows at most min(10, `max_urls`) redirects, so the requests beyond the limit are at most `concurrency` x min(10, `max_urls`) (20 with the defaults). A failed fetch is booked as one request. The 20-second deadline covers DNS, redirects, connection and response together. Every redirect is checked against scope and fresh DNS; the Node transport connects to the vetted address and preserves TLS hostname verification. A host MCP or bulk crawler is selected only if it can guarantee the same boundary and cost controls.
+`RunContext.scope.allowed` is a nonempty list of `{ "origin": "https://example.org", "path_prefix": "/owned/" }`. An origin fixes scheme, host and effective port. The path prefix is segment bounded. `scope.local_targets` may list explicit `{ "host": "localhost", "port": 8765 }` pairs for a declared local target. Without this pair, loopback, private, link-local, ULA and mapped IPv4 addresses are blocked. The default ceilings are 50 URLs, depth 3, concurrency 2, 20 seconds, 5 MiB and 10 redirects. Lower limits may be set with `max_urls`, `max_depth` and `concurrency`. The request limit (`max_urls`, at most 50) is a hard ceiling for pages and auxiliary resources together: every request, each redirect hop included, takes one slot immediately before it is sent, and the total never exceeds the limit. A redirect chain the limit stops leaves its URL as a `request_limit` unknown, and the hops it already received stay recorded. A failed fetch counts the hops it received plus at most one attempt that got no response; both are written to a hashed `<sha256>.failure.json` record so report replay can prove the count. The 20-second deadline covers DNS, redirects, connection and response together. Every redirect is checked against scope and fresh DNS; the Node transport connects to the vetted address and preserves TLS hostname verification. A host MCP or bulk crawler is selected only if it can guarantee the same boundary and cost controls.
 
 The v0.1.0 direct Anthropic Messages adapter accepts only text-only `{model,max_tokens,messages}` requests. Each message has only `{role,content}` with string content. It accepts these exact model IDs: `claude-fable-5-1`, `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-haiku-5-5`. Anthropic's [model overview](https://platform.claude.com/docs/en/models/overview), checked 2026-10-14, lists a 1,000,000-token context window and 128,000 maximum output tokens for each. Every attempt must reserve at least `1,000,000 + request.max_tokens` in the `tokens` unit. The adapter requires exactly one token upper bound, a matching ledger budget and approval reference, and an `ANTHROPIC_API_KEY` environment variable. It rejects unknown models, extra fields, tools, web search, non-text input, currency-only bounds and smaller token reservations before any provider request. The official [token-counting guide](https://platform.claude.com/docs/en/build-with-claude/token-counting), checked 2026-10-14, calls count results estimates that may differ from billed input usage; they are not accepted as hard upper bounds.
 

package/skills/optbrew/references/report.md

@@ -22,7 +22,7 @@ Collector verdicts are replayed, not trusted. For each collector-sourced `index-
 
 `verified_local` uses the production binding: the change and its receipt name an `observation_id` and `observation_evidence_ref` for a passing after observation that the collector produced (so the audit replay covers it); that raw evidence entry is labelled `phase:"after"`, `environment:"local"` and the run target, and the after context is `local` for the same target. A byte-hash receipt or an agent-written observation alone leaves the finding `modified_unverified`. For `verified_production` the finding carries `resolution` (observation ID, evaluator type, source) and the Status cell reads `resolved by <evaluator_type> observation from <source_ref>`, so a model-attested resolution is visibly distinct from a collector-verified one; the production gating rules are unchanged. Native path mappings match whole path segments: the exported path starts with a single `/` (protocol-relative paths and absolute URLs on another host are refused) and equals the approved `path_prefix` or continues after a `/`.
 
-Collector verdicts for the families below come from one derivation, `scripts/core/derive.mjs`, which the audit runs on the live responses and the report runs again on the hashed raw evidence. Every derived observation must be in the packet and in the saved observations, and each packet observation must match its derivation in state, credit and evidence reference; an extra or missing collector observation is an error. The families: `fetch-response`; `index-policy`; `document-title` (missing or duplicated across the selected pages fails; a unique title stays `unknown`); `search-crawl-policy` for every engine with a token in `ai-crawlers.json`, judged on the declared robots file; `canonical-consistency` (a redirect chain of two or more hops, or a canonical target that returns an error, fails; a self-referencing or reachable canonical within one hop passes; the collector fetches in-scope canonical targets while the request count is under the limit); `discovery` (a selected public page that no collected page links to and no reachable declared sitemap lists fails when the crawl was complete and at least two pages were collected; a sitemap index or an incomplete crawl leaves it `unknown`; while any collected page has scripts and no anchors, an unlinked page is `unknown` unless a fetched sitemap that lists other pages leaves it out; entity-encoded hrefs are decoded and `index.html` equals its directory); `structured-data-truth` (a live JSON-LD block that does not parse fails; blocks inside HTML comments and empty placeholder blocks are ignored; parsing alone never passes); `naver-markup` (Open Graph, description, canonical, viewport, title repetition, CSS or JS blocked for Yeti); and, for runs that enable them, `fact-consistency` and `entity-identity`. Fact consistency compares name, address, phone and founding year across the selected pages. Values come only from Organization or LocalBusiness JSON-LD, `tel:` links (counted only on a page with no labelled or JSON-LD phone, so a mobile inquiry link never contradicts the landline) and explicitly labelled fields (`Phone:`, `Tel`, `Address:`, `Founded:` and Korean equivalents); prose, dates and numbers elsewhere are never read as facts, and a fax or registration number is not a phone. Addresses are compared after unifying street abbreviations, dropping postal codes and a trailing country, and treating a street address with or without city detail as the same. A page that presents itself as a branch (the word branch, 지점 or 지사 in its title or first heading, or a branch JSON-LD entity or a different `@id`) is a separate entity and is not compared. A reference value needs at least two pages and a unique majority; a page that disagrees, or whose JSON-LD disagrees with its own visible text, fails; a tie or a single page stays `unknown`. This is consistency between pages, not accuracy against an approved fact list. `entity-identity` (site unit) fails on conflicting names, Organization JSON-LD without `sameAs`, or no Organization JSON-LD on the home page while other pages have it. The `robots.txt` Sitemap line, og:image size, hreflang and JavaScript-only navigation are not scripted. Audit evidence from 0.1.1 or earlier has no request ledger or module list and lacks the families added in 0.1.2, so report replay refuses it with an "older optbrew release" error; run the audit again with 0.1.2 and build a new packet. Every audit also writes `ledger.json`: one entry per queued or rejected URL with its request count. Index it with `source_ref:"optbrew:collector"`. Replay checks that the skipped list, `limit_reached`, `request_count` and `evaluated_count` equal the ledger, that each response entry matches a hashed response record (requests = redirect hops + 1), that a request limit is claimed only when the requests recorded reach the limit, and that a selected page is skipped only for the request limit. The audit index also lists the modules that ran; every listed module must have its output in `modules.json`. All derived families above are computed from the collector evidence whether or not a module ran.
+Collector verdicts for the families below come from one derivation, `scripts/core/derive.mjs`, which the audit runs on the live responses and the report runs again on the hashed raw evidence. Every derived observation must be in the packet and in the saved observations, and each packet observation must match its derivation in state, credit and evidence reference; an extra or missing collector observation is an error. The families: `fetch-response`; `index-policy`; `document-title` (missing or duplicated across the selected pages fails; a unique title stays `unknown`); `search-crawl-policy` for every engine with a token in `ai-crawlers.json`, judged on the declared robots file; `canonical-consistency` (a redirect chain of two or more hops, or a canonical target that returns an error, fails; a self-referencing or reachable canonical within one hop passes; the collector fetches in-scope canonical targets within the request limit); `discovery` (a selected public page that no collected page links to and no reachable declared sitemap lists fails when the crawl was complete and at least two pages were collected; a sitemap index or an incomplete crawl leaves it `unknown`; an unlinked page is `unknown` when another collected page's own bytes (inline scripts included) name its path as a whole path, or when a script-only page loads a same-origin script file that was not collected, unless a fetched sitemap that lists other pages leaves it out (an inline script that builds the URL from pieces can still give a false orphan); entity-encoded hrefs are decoded and `index.html` equals its directory); `structured-data-truth` (a live JSON-LD block that does not parse fails; blocks inside HTML comments and empty placeholder blocks are ignored; parsing alone never passes); `naver-markup` (Open Graph, description, canonical, viewport, title repetition, CSS or JS blocked for Yeti); and, for runs that enable them, `fact-consistency` and `entity-identity`. Fact consistency compares name, address, phone and founding year across the selected pages. Values come only from Organization or LocalBusiness JSON-LD, `tel:` links (counted only on a page with no labelled or JSON-LD phone, so a mobile inquiry link never contradicts the landline) and explicitly labelled fields (`Phone:`, `Tel`, `Address:`, `Founded:` and Korean equivalents); prose, dates and numbers elsewhere are never read as facts, and a fax or registration number is not a phone. A national number written with spaces only (02 555 0142) is read in a label, and so are Korean nationwide representative numbers (15xx, 16xx or 18xx plus four digits). Addresses are compared after unifying street abbreviations, dropping postal codes and a trailing country, and treating a street address with or without city detail as the same. A page is a separate entity and is not compared only on structural evidence: JSON-LD `branchOf`, `parentOrganization` or a different `@id`; a branch-list URL path (`/branch/`, `/branches/`, `/locations/`, `/stores/`, `/지점/`); or the word branch, 지점 or 지사 in its title or first heading together with an address of its own that differs from the main entity's. A title word alone does not hide a wrong phone. A reference value needs at least two pages and a unique majority; a page that disagrees, or whose JSON-LD disagrees with its own visible text, fails; a tie or a single page stays `unknown`. This is consistency between pages, not accuracy against an approved fact list. `entity-identity` (site unit) fails on conflicting names, Organization JSON-LD without `sameAs`, or no Organization JSON-LD on the home page while other pages have it. The `robots.txt` Sitemap line, og:image size, hreflang and JavaScript-only navigation are not scripted. Audit evidence from 0.1.2 or earlier has no hashed failure records and lacks the 0.1.3 discovery and fact observations, so report replay refuses it with an "older optbrew release" error; run the audit again with 0.1.3 and build a new packet. Every audit also writes `ledger.json`: one entry per queued or rejected URL with its request count. Index it with `source_ref:"optbrew:collector"`. Replay checks that the skipped list, `limit_reached`, `request_count` and `evaluated_count` equal the ledger, that each response entry matches a hashed response record (requests = redirect hops + 1), that each failed fetch matches a hashed failure record (`*.failure.json`, listed in `failures`; requests = answered redirect hops + at most one attempt that got no response), that a URL appears in only one entry, that a failed fetch or a request-limit skip belongs to a URL with provenance (selected, auxiliary, or linked from a collected page), that the total never exceeds the request limit and a limit is claimed only when the recorded requests use all of it, and that a selected page is skipped only for the request limit. Index every `*.failure.json` file with `source_ref:"optbrew:collector"`, as for `*.response.json`. The audit index also lists the modules that ran; every listed module must have its output in `modules.json`. All derived families above are computed from the collector evidence whether or not a module ran.
 
 The report opens with a Headline per profile. At least 80% measured coverage and a verdict on every core access and indexing check print the score with its coverage; below 80% the headline is `insufficient coverage`, and with no verdict on a core check it is `insufficient core checks`, with the measured-subset score and the missing-data bounds, and `json.headline[]` carries `status` (`sufficient`, `insufficient_coverage`, `insufficient_core`), `coverage_exact`, `headline_score` (null when withheld), `measured_subset_score`, `coverage` and `missing_bounds`.
 

package/skills/optbrew/references/scoring.md

@@ -1,4 +1,4 @@
-# optbrew readiness scoring contract (evaluation 0.2.0)
+# optbrew readiness scoring contract (evaluation 0.3.0)
 
 This is a readiness audit. It does not predict indexing, rank, AI citations, accuracy, or revenue. `check-registry.json` holds the 22 unique families. `profiles.json` holds the five optbrew axis weight sets. Those weights, the middle-band CWV `q=0.5`, the score bands and the 80% coverage threshold are **optbrew rules**, not search engine weights or official sufficiency tests. `source_refs` names match the official references in `docs/superpowers/specs/2026-10-13-optbrew-sources.md` in the source repository.
 

package/skills/optbrew/scripts/audit.mjs

@@ -41,6 +41,7 @@ export async function runAudit({ context, modules, outputDir, transport, resolve
   const collection = await collect(context, { transport, resolve });
   const artifacts = [];
   const responses = [];
+  const failures = [];
   for (const artifact of collection.artifacts) {
     const { body, ...saved } = artifact;
     if (artifact.content_hash) {
@@ -68,6 +69,21 @@ export async function runAudit({ context, modules, outputDir, transport, resolve
       saved.response_ref = ref;
       responses.push({ normalized_url: artifact.normalized_url, evidence_ref: ref, content_hash });
     }
+    else {
+      // A failed fetch has no response, but its answered redirect hops were real requests: hash them in a failure record
+      // so the ledger can prove the count (answered hops plus at most one unanswered attempt).
+      const bytes = Buffer.from(`${JSON.stringify({ record_version: '1', kind: 'failure', requested_url: artifact.requested_url,
+        normalized_url: artifact.normalized_url, redirect_chain: artifact.redirect_chain, unanswered: artifact.unanswered ?? 0,
+        error: artifact.error }, null, 2)}\n`);
+      const content_hash = createHash('sha256').update(bytes).digest('hex');
+      const ref = path.join(evidenceDir, `${content_hash}.failure.json`);
+      try { await writeFile(ref, bytes, { flag: 'wx' }); }
+      catch (error) {
+        if (error.code !== 'EEXIST' || !Buffer.from(await readFile(ref)).equals(bytes)) throw error;
+      }
+      saved.failure_ref = ref;
+      failures.push({ normalized_url: artifact.normalized_url, evidence_ref: ref, content_hash });
+    }
     artifacts.push(saved);
   }
   const module_outputs = Object.fromEntries(modules.map(x => [x, []]));
@@ -104,7 +120,7 @@ export async function runAudit({ context, modules, outputDir, transport, resolve
     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' });
+    responses, failures }, null, 2)}\n`, { flag: 'wx' });
   return result;
 }
 

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

@@ -42,7 +42,7 @@ export async function createBundleManifest({ bundleRoot, releaseVersion }) {
   const evaluation_sources = selected(evaluationSourcePaths);
   const protocol_sources = selected(protocolSourcePaths);
   const identity = evaluation_sources.length && protocol_sources.length ? {
-    evaluation_version: '0.2.0', protocol_version: '0.1.0',
+    evaluation_version: '0.3.0', protocol_version: '0.1.0',
     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,

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

@@ -95,6 +95,7 @@ export async function fetchScoped(input, { context, transport = nodeTransport, r
   if (allowedAuxiliary) undeclaredAuxiliary(url, allowedAuxiliary);
   const requested_url = String(input);
   const redirect_chain = [];
+  let made = 0; // requests actually sent; an answered hop is in redirect_chain, an unanswered attempt is made - chain length
   const controller = new AbortController();
   const deadline = performance.now() + timeoutMs;
   let rejectTimeout;
@@ -116,13 +117,17 @@ export async function fetchScoped(input, { context, transport = nodeTransport, r
         error.redirect_chain = redirect_chain;
         throw error;
       }
+      made++;
       const response = await withinDeadline(transport({ url, address: addresses[0], timeoutMs: remainingMs, maxBytes, headers, signal: controller.signal }));
       if (!Number.isInteger(response?.status) || response.status < 100 || response.status > 599) throw new Error('invalid transport status');
       const body = text(response.body);
       if (body.length > maxBytes) throw new Error('response byte limit exceeded');
       const savedHeaders = safeHeaders(response.headers);
       if (REDIRECTS.has(response.status) && savedHeaders.location) {
-        if (hop === maxRedirects) throw new Error('redirect limit exceeded');
+        if (hop === maxRedirects) {
+          redirect_chain.push({ url: url.href, status: response.status, location: '[limit]' });
+          throw new Error('redirect limit exceeded');
+        }
         let next;
         try { next = assertUrlInScope(new URL(savedHeaders.location, url).href, context.scope); }
         catch {
@@ -149,7 +154,11 @@ export async function fetchScoped(input, { context, transport = nodeTransport, r
       };
     }
     throw new Error('redirect limit exceeded');
-  } catch (error) { error.redirect_chain ??= [...redirect_chain]; throw error; }
+  } catch (error) {
+    error.redirect_chain ??= [...redirect_chain];
+    error.unanswered = Math.max(0, made - error.redirect_chain.length);
+    throw error;
+  }
   finally { clearTimeout(timer); }
 }
 
@@ -214,25 +223,26 @@ export async function collect(context, { transport, resolve } = {}) {
       const item = queue[cursor++];
       if (requestCount >= limit) { skip(item.url, 'url_limit'); continue; }
       let used = 0;
-      // The budget decides whether a fetch may start. A redirect chain that has started is allowed to finish (at most
-      // maxRedirects further requests), so a chain is never cut in the middle by the limit.
+      // The budget is a hard ceiling: every request, redirect hops included, takes one slot immediately before it is sent.
+      // A chain the budget stops is a request_limit unknown whose answered hops are recorded.
       const reserveRequest = () => {
-        if (!used && requestCount >= limit) return false;
+        if (requestCount >= limit) return false;
         requestCount++; used++;
         return true;
       };
       let artifact;
-      // A chain is at most min(10, limit) redirects long, so the requests a started chain adds beyond the limit scale with
-      // the limit: at most concurrency x min(10, limit) in all.
-      try { artifact = await fetchScoped(item.url, { context, transport, resolve, allowedAuxiliary: allowedDocuments, reserveRequest, maxRedirects: Math.min(10, limit) }); }
+      try { artifact = await fetchScoped(item.url, { context, transport, resolve, allowedAuxiliary: allowedDocuments, reserveRequest }); }
       catch (error) {
         const reason = ['scope_rejected', 'redirect_outside_scope', 'auxiliary_undeclared', 'request_limit'].includes(error.code) ? error.code : 'fetch_failed';
         if (reason === 'request_limit' && !used) { skip(item.url, 'url_limit'); continue; }
         if (reason !== 'fetch_failed') skipped.push({ url: item.url, reason });
-        // A failed fetch has no hashed response record, so the requests it made cannot be proven later: it counts as one.
-        ledger.push({ url: item.url, requests: 1, outcome: 'error', skipped_reason: reason !== 'fetch_failed' ? reason : null, error: reason });
+        // The requests a failed fetch made are its answered hops (kept in the hashed failure record) plus at most one
+        // attempt that got no response, so the ledger can prove them.
+        const chain = error.redirect_chain ?? [];
+        const unanswered = error.unanswered ?? 0;
+        ledger.push({ url: item.url, requests: chain.length + unanswered, outcome: 'error', skipped_reason: reason !== 'fetch_failed' ? reason : null, error: reason });
         artifact = { requested_url: item.url, normalized_url: item.url, final_url: null, status: null,
-          headers: {}, header_lines: [], redirect_chain: error.redirect_chain ?? [], raw_html_ref: null, content_hash: null, capability: 'none',
+          headers: {}, header_lines: [], redirect_chain: chain, unanswered, raw_html_ref: null, content_hash: null, capability: 'none',
           source_ref: 'optbrew:collector', evidence_ref: null, error: reason, body: Buffer.alloc(0) };
       }
       if (!artifact.error) ledger.push({ url: item.url, requests: used, outcome: 'response', skipped_reason: null, error: null });

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

@@ -103,6 +103,18 @@ export function deriveObservations({ context, artifacts, collection = {}, textOf
       else if (canonicalState === 'pass') add('canonical-consistency', null, url, 'pass', 'Canonical target is this page or a reachable page and redirects stay within one hop', ref);
     }
   }
+  /** True when any other collected page's raw bytes name this page's path (whole path segment, not a longer path). */
+  const pathMentioned = ({ url, artifact }, bodies) => {
+    const own = canonicalUrl(url);
+    for (const target of new Set([url, artifact.final_url])) {
+      let path;
+      try { path = decodeURIComponent(new URL(target).pathname); } catch { continue; }
+      if (path === '/') continue;
+      const pattern = new RegExp(path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '(?![A-Za-z0-9_-])');
+      for (const [page, body] of bodies) if (page !== own && pattern.test(body)) return true;
+    }
+    return false;
+  };
   if (planned.has('discovery')) {
     const sitemapUrls = new Set();
     const brokenSitemaps = [];
@@ -118,12 +130,24 @@ export function deriveObservations({ context, artifacts, collection = {}, textOf
     }
     const htmlPages = artifacts.filter(x => x.capability === 'raw_html' && x.status === 200);
     const linked = new Map();
-    // A page with scripts and no anchors may build its navigation in the browser: its links are unknowable.
-    const scriptOnly = new Set();
+    // A page with scripts and no anchors may build its navigation in the browser. That only hides an orphan when the
+    // script can be read: an inline script is searched for the path below, and a same-origin script file that was not
+    // collected cannot be read at all.
+    const collected = new Set(artifacts.flatMap(x => [x.normalized_url, x.final_url].filter(Boolean).map(canonicalUrl)));
+    let uncollectedScript = false;
+    const bodies = new Map();
     for (const page of htmlPages) {
       const body = textOf(page);
+      bodies.set(canonicalUrl(page.normalized_url), body);
       const hrefs = anchorLinks(body, page.final_url);
-      if (!hrefs.length && /<script\b/i.test(body)) scriptOnly.add(canonicalUrl(page.normalized_url));
+      if (!hrefs.length && /<script\b/i.test(body)) {
+        for (const match of body.matchAll(/<script\b[^>]*\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)) {
+          try {
+            const source = new URL(decodeEntities(match[1] ?? match[2]), page.final_url);
+            if (source.origin === new URL(page.final_url).origin && !collected.has(canonicalUrl(source.href))) uncollectedScript = true;
+          } catch { /* malformed script URL */ }
+        }
+      }
       for (const href of hrefs) {
         const target = canonicalUrl(href);
         if (target && target !== canonicalUrl(page.final_url) && target !== canonicalUrl(page.normalized_url)) linked.set(target, (linked.get(target) ?? 0) + 1);
@@ -137,9 +161,10 @@ export function deriveObservations({ context, artifacts, collection = {}, textOf
       const inSitemap = keys.some(key => sitemapUrls.has(key));
       if (inSitemap || keys.some(key => linked.has(key)))
         add('discovery', null, url, 'pass', inSitemap ? 'Listed in a declared sitemap' : 'Linked from another collected page', artifact.evidence_ref);
-      // A page with scripts and no anchors may link any page from the browser, so while one exists an unlinked page is only
-      // an orphan when a fetched sitemap that lists other pages leaves it out. Otherwise the verdict stays unknown.
-      else if (htmlPages.length >= 2 && complete && !sitemapIndex && (!scriptOnly.size || sitemapUrls.size))
+      // An unlinked page is unknown when a collected page's own bytes (inline scripts included) name its path, or when a
+      // script file that could build the link was not collected, unless a fetched sitemap that lists other pages leaves
+      // it out. Anything else is an orphan.
+      else if (htmlPages.length >= 2 && complete && !sitemapIndex && (sitemapUrls.size || !(uncollectedScript || pathMentioned(row, bodies))))
         add('discovery', null, url, 'fail', `Not linked from any collected page and not in a sitemap${brokenSitemaps.length ? `; declared sitemap unusable: ${brokenSitemaps.join(', ')}` : ''}`, artifact.evidence_ref);
     }
   }

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

@@ -10,6 +10,12 @@ const FACT_TYPES = ['name', 'phone', 'year', 'address'];
 const ORG_TYPES = /^(?:Organization|Corporation|LocalBusiness|Store|Restaurant|CafeOrCoffeeShop|OnlineStore|NGO|[A-Za-z]*Business)$/;
 const squash = value => String(value).toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '');
 const BRANCH = /\b(?:branch)\b|지점|지사/i;
+// URL path segments that list branches: /branch/, /branches/, /locations/, /stores/, /지점/.
+const BRANCH_PATH = /^(?:branch|branches|locations|stores|지점)$/i;
+const branchPath = url => {
+  try { return new URL(url, 'http://page.invalid').pathname.split('/').some(part => BRANCH_PATH.test(decodeURIComponent(part))); }
+  catch { return false; }
+};
 
 const ABBREVIATIONS = [[/\bstreet\b/g, 'st'], [/\broad\b/g, 'rd'], [/\bavenue\b/g, 'ave'], [/\bboulevard\b/g, 'blvd'],
   [/\bdrive\b/g, 'dr'], [/\blane\b/g, 'ln'], [/\bsuite\b/g, 'ste'], [/\bfloor\b/g, 'fl'], [/\bbuilding\b/g, 'bldg']];
@@ -60,6 +66,8 @@ const addressText = address => typeof address === 'string' ? address : address &
 function phoneKey(text) {
   const clean = String(text).replace(/\(0\)/g, '');
   const digits = clean.replace(/\D/g, '');
+  // Korean nationwide representative numbers (15xx, 16xx, 18xx plus four digits) have eight digits.
+  if (/^1[568]\d{6}$/.test(digits)) return digits;
   if (digits.length < 9 || digits.length > 15) return null;
   return /^\s*\+?\s*82/.test(clean) && clean.trim().startsWith('+') && digits.startsWith('82') ? `0${digits.slice(2)}` : digits;
 }
@@ -72,6 +80,10 @@ const hardText = html => decodeEntities(stripInert(html).replace(/<[^>]+>/g, '\n
 // An international or parenthesised number may use spaces between its groups; a plain national number only dashes and dots.
 const LOOSE_PHONE = /^[+(]\s?[\d()]{1,6}(?:[-. ]?\(?\d{1,6}\)?){1,5}/;
 const STRICT_PHONE = /^\+?\d{1,4}(?:[-.]\d{1,6}){1,4}/;
+// In a label, a national number may use spaces only (02 555 0142, 010 1234 5678), and a nationwide representative number
+// is 15xx, 16xx or 18xx plus four digits. Neither is read in prose.
+const SPACED_NATIONAL_PHONE = /^0\d{1,2}(?: \d{3,4}){2}(?!\d)/;
+const REPRESENTATIVE_PHONE = /^1[568]\d{2}[- ]\d{4}(?!\d)/;
 /**
  * The number at the start of `rest`, ending at its own last digit group. A spaced number that is followed by more
  * digits or a bracketed digit is ambiguous, so only its dashed or dotted part is read, and a number longer than twelve
@@ -81,7 +93,14 @@ function readPhone(rest) {
   const usable = text => text && (phoneKey(text)?.length ?? 99) <= 13 ? text.trim() : null;
   const loose = LOOSE_PHONE.exec(rest)?.[0].trimEnd();
   if (loose && !/^[ \t]*[(\[]?\d/.test(rest.slice(loose.length)) && usable(loose)) return loose.trim();
-  return usable(STRICT_PHONE.exec(rest)?.[0]);
+  const strict = usable(STRICT_PHONE.exec(rest)?.[0]);
+  if (strict) return strict;
+  // Digits straight after a spaced number are ambiguous (02 555 0142 42 seats); a bracket after it is not (hours).
+  for (const pattern of [SPACED_NATIONAL_PHONE, REPRESENTATIVE_PHONE]) {
+    const match = pattern.exec(rest)?.[0];
+    if (match && !/^[ \t]*\d/.test(rest.slice(match.length)) && usable(match)) return match.trim();
+  }
+  return null;
 }
 
 /** Facts on one page: visible labelled values and JSON-LD / tel: values, keyed by fact type. */
@@ -124,10 +143,11 @@ export function pageFacts(html) {
       orgs.push(org);
     }
   }
-  // A page that presents itself as a branch has its own address and phone; it is a different entity, so it is not compared.
+  // A branch word in the title or first heading is only a hint (titleBranch). A page is a separate entity when its
+  // JSON-LD says so (branch), when its URL is a branch list, or when the hint comes with an address of its own.
   const heading = /<(?:title|h1)\b[^>]*>([\s\S]*?)<\/(?:title|h1)>/gi;
   const headings = [...live.matchAll(heading)].map(match => match[1]).join(' ');
-  return { visible, linked, tel, orgs, branch: BRANCH.test(headings) || orgs.some(org => org.branch) };
+  return { visible, linked, tel, orgs, branch: orgs.some(org => org.branch), titleBranch: BRANCH.test(headings) };
 }
 
 /**
@@ -150,7 +170,13 @@ export function compareFacts(allPages) {
   for (const page of allPages) for (const id of new Set(page.facts.orgs.map(org => org.id).filter(Boolean))) ids.set(id, (ids.get(id) ?? 0) + 1);
   const ranked = [...ids.entries()].sort((a, b) => b[1] - a[1]);
   const mainId = ranked.length && ranked[0][1] >= 2 && (ranked.length === 1 || ranked[0][1] > ranked[1][1]) ? ranked[0][0] : null;
-  const separate = page => page.facts.branch || (mainId && page.facts.orgs.some(org => org.id) && !page.facts.orgs.some(org => org.id === mainId));
+  const structural = page => page.facts.branch || branchPath(page.url) ||
+    (mainId && page.facts.orgs.some(org => org.id) && !page.facts.orgs.some(org => org.id === mainId));
+  // The main entity's addresses come from the pages with neither structure nor a branch word in the title.
+  const mainAddresses = [...new Set(allPages.filter(page => !structural(page) && !page.facts.titleBranch).flatMap(page => [...keysOf(page, 'address')]))];
+  // A branch word in the title counts only with a labelled address that is not the main entity's.
+  const ownAddress = page => { const own = keysOf(page, 'address'); return own.size > 0 && mainAddresses.length > 0 && ![...own].some(key => mainAddresses.some(main => sameAddress(key, main))); };
+  const separate = page => structural(page) || (page.facts.titleBranch && ownAddress(page));
   const pages = allPages.filter(page => !separate(page));
   const references = {};
   const deviations = new Map(allPages.map(page => [page.url, []]));

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

@@ -178,12 +178,32 @@ const pathWithin = (value, prefix, host) => {
   return wanted === '/' || actual === wanted || actual.startsWith(wanted.endsWith('/') ? wanted : `${wanted}/`);
 };
 
+/**
+ * A failed fetch has no response, but its answered redirect hops are real requests. They are replayed from the hashed
+ * failure record, which also says whether one more attempt got no response.
+ */
+function boundFailure(artifact, audit, requireRef) {
+  const entry = (audit.failures ?? []).find(x => x.normalized_url === artifact.normalized_url);
+  if (!artifact.failure_ref || !entry || entry.evidence_ref !== artifact.failure_ref) throw new ContractError('failure record missing for failed fetch');
+  const raw = requireRef(artifact.failure_ref, 'optbrew:collector');
+  if (raw.sha256 !== entry.content_hash) throw new ContractError('failure record hash differs from the audit index');
+  const record = JSON.parse(raw.text);
+  // At most ten redirects are followed, and the eleventh answer (a refused redirect) is the last hop that can be recorded.
+  if (record.kind !== 'failure' || ![0, 1].includes(record.unanswered) || !Array.isArray(record.redirect_chain) || record.redirect_chain.length > 11 ||
+      record.redirect_chain.some((hop, index) => typeof hop?.url !== 'string' || !(hop.status >= 300 && hop.status <= 399) ||
+        hop.url !== (index ? record.redirect_chain[index - 1].location : record.normalized_url)))
+    throw new ContractError('failure record is malformed');
+  for (const key of ['requested_url', 'normalized_url', 'redirect_chain', 'unanswered', 'error'])
+    if (!same(record[key], artifact[key])) throw new ContractError(`failure record differs from collection record: ${key}`);
+  return { ...artifact, ...record };
+}
+
 /**
  * Replay a collected response from its hashed record: final URL, redirect chain and header lines come from the
  * record, and the collection entry must agree with it. Bodyless failures have no response to bind.
  */
 function boundArtifact(artifact, audit, requireRef) {
-  if (!Number.isInteger(artifact.status)) return artifact;
+  if (!Number.isInteger(artifact.status)) return boundFailure(artifact, audit, requireRef);
   const entry = (audit.responses ?? []).find(x => x.normalized_url === artifact.normalized_url);
   if (!artifact.response_ref || !entry || entry.evidence_ref !== artifact.response_ref)
     throw new ContractError('response record missing for collected artifact');
@@ -364,15 +384,16 @@ function checkLedger(input, audit, collection, artifacts, requireRef) {
   const limit = Math.min(input.run_context.scope?.max_urls ?? 50, 50);
   if (ledger.limit !== limit) fail('request limit differs from the run scope');
   const total = entries.reduce((sum, entry) => sum + entry.requests, 0);
-  // The limit decides whether a fetch may start; a redirect chain that has started finishes. A chain is at most
-  // min(10, limit) redirects long and at most `concurrency` chains are in flight, so the overshoot is bounded by both.
-  const concurrency = Math.min(input.run_context.scope?.concurrency ?? 2, 2);
-  if (total > limit + concurrency * Math.min(10, limit)) fail('more requests than the limit');
+  // The limit is a hard ceiling: every request, redirect hops included, takes one slot before it is sent.
+  if (total > limit) fail('more requests than the limit');
+  // One URL, one entry. Skips for out-of-scope and undeclared auxiliary links are recorded per link and may repeat.
+  const identities = entries.filter(x => !(x.outcome === 'skipped' && ['outside_scope', 'auxiliary_undeclared'].includes(x.skipped_reason))).map(x => x.url);
+  if (new Set(identities).size !== identities.length) fail('duplicate ledger url: a URL appears in more than one entry');
   const responded = artifacts.filter(x => Number.isInteger(x.status));
   const failed = artifacts.filter(x => !Number.isInteger(x.status));
   const byUrl = outcome => new Map(entries.filter(x => x.outcome === outcome).map(x => [x.url, x]));
   const responses = byUrl('response'), errors = byUrl('error');
-  if (responses.size !== responded.length || audit.responses.length !== responded.length || errors.size !== failed.length)
+  if (responses.size !== responded.length || audit.responses.length !== responded.length || errors.size !== failed.length || audit.failures.length !== failed.length)
     fail('collected artifacts differ from the ledger or the response records');
   for (const artifact of responded) {
     const entry = responses.get(artifact.normalized_url);
@@ -383,16 +404,16 @@ function checkLedger(input, audit, collection, artifacts, requireRef) {
   for (const artifact of failed) {
     const entry = errors.get(artifact.normalized_url);
     if (!entry) fail(`failed fetch of ${artifact.normalized_url} is not recorded`);
-    // A failed fetch has no hashed response record, so nothing proves how many requests it made: it is always one.
-    // Neither the redirect chain nor any count inside collection.json can raise it, so a forger cannot pad the total.
-    if (entry.requests !== 1) fail(`failed fetch of ${artifact.normalized_url} is not booked as exactly one request`);
+    // The requests of a failed fetch are the answered hops of its hashed failure record plus at most one attempt that got
+    // no response; nothing in collection.json can raise them.
+    if (entry.requests !== artifact.redirect_chain.length + artifact.unanswered) fail(`failed fetch of ${artifact.normalized_url} does not match its hashed failure record`);
   }
   const key = x => `${x.url}|${x.reason ?? x.skipped_reason}`;
   const ledgerSkips = entries.filter(x => x.skipped_reason).map(key).sort();
   if (JSON.stringify((collection.skipped ?? []).map(key).sort()) !== JSON.stringify(ledgerSkips)) fail('skipped list differs from the ledger');
   const limited = entries.some(x => ['url_limit', 'request_limit'].includes(x.skipped_reason));
   if (collection.limit_reached !== limited) fail('limit_reached differs from the ledger');
-  if (limited && total < limit) fail('a request limit is claimed but fewer requests than the limit were made');
+  if (limited && total !== limit) fail('a request limit is claimed but the recorded requests do not use the whole limit');
   if (collection.request_count !== total || collection.evaluated_count !== entries.filter(x => x.requests > 0).length) fail('request or evaluated count differs from the ledger');
   const selected = new Set(input.run_context.protocol.page_types.flatMap(type => type.urls.map(x => x.normalized)));
   if (entries.some(x => selected.has(x.url) && x.skipped_reason && x.skipped_reason !== 'url_limit' && x.outcome === 'skipped')) fail('a selected page is skipped for a reason other than the request limit');
@@ -433,8 +454,8 @@ function checkAuditPhase(input, phase, snapshot, requireRef) {
   const savedObservations = JSON.parse(requireRef(audit.observations_ref).text);
   if (!Array.isArray(collection.artifacts) || !Array.isArray(audit.raw) || !Array.isArray(savedObservations))
     throw new ContractError('audit snapshot files incomplete');
-  if (!Array.isArray(audit.modules) || !audit.ledger_ref || !Array.isArray(audit.responses))
-    throw new ContractError('audit evidence was produced by an older optbrew release (it has no request ledger or module list); re-run the audit with optbrew 0.1.2 and build a new packet');
+  if (!Array.isArray(audit.modules) || !audit.ledger_ref || !Array.isArray(audit.responses) || !Array.isArray(audit.failures))
+    throw new ContractError('audit evidence was produced by an older optbrew release (it lacks the request ledger, module list or failure records); re-run the audit with optbrew 0.1.3 and build a new packet');
   for (const name of audit.modules) if (!Array.isArray(moduleOutputs[name])) throw new ContractError(`planned module output missing: ${name}`);
   const naverPlanned = audit.modules.includes('naver-searchadvisor');
   const rawRefs = new Set();