optbrew 0.0.0-stage → 0.1.1

package/skills/optbrew/references/report.md

@@ -0,0 +1,25 @@
+# Report packet and evidence contract (v0.1.0)
+
+`node skills/optbrew/scripts/cli.mjs report --input <packet.json> --output-dir <new-directory>` writes `report.json` and `report.md`. It makes no network or paid calls. It refuses to replace an existing report. A report is a local audit artifact; a local passing verification does not establish deployment, indexing, traffic, ranking, citations, or business impact.
+
+`ReportPacket` retains the approved `run_context`, raw `baseline.input`, optional `after.input`, their `score()` results, `compare()` result, metrics, findings, changes, costs, remaining work, and source identity. `evidence_root` points to the run directory. The CLI resolves a relative root against the packet's directory. Each `evidence_index` item has `{ref,sha256,kind,run_id,source_ref?,source_url?}`. Every indexed file is reopened, checked against its SHA-256, and contained by the resolved run directory. The context file at each phase's `run_context.evidence_ref` must contain exactly that run context.
+
+An applicability `evidence_ref` points to JSON `{run_id,target,protocol_hash,approved_by,decisions}`. Each decision is `{scope:"family",family_id,condition,reason}`, `{scope:"url",normalized_url,condition,reason}`, or `{scope:"unit",unit_key,condition,reason}`. A matching record identifies the decision and its approval context; it does not independently prove the underlying site fact. Missing or unrelated decisions are contract errors. Unknown checks remain in the denominator.
+
+Collector phases use `audit_snapshots:[{phase:"baseline"|"after",audit_ref,context_ref}]`, one Task 5 evidence index per phase. A baseline-only packet may use legacy `audit_ref`. The audit's run/context, observation file, collection file, module output, artifact `evidence_ref` and non-null raw body hash must match that phase. A bodyless DNS/timeout artifact has `content_hash:null`, points to the collection file, and remains `unknown`; it is not compared to the collection file hash as though it were a body. Same-URL before/after observations must use their own snapshot and raw ref.
+
+Owner export metrics replay through `normalizeImport()` from evidence JSON `{kind:"native_export",run_id,provider,rows,metadata}`. `run_context.protocol.target_identity` is a comparison-relevant, hashed field. It contains `{target,native_properties:[{provider,property,hostname?,path_prefix?,evidence_ref}],panel?}`. Each native mapping ref points to a run/target/provider/property/approval record. Known row hostname and path must fit its approved mapping. The native metadata supplies `collected_at` with offset and `last_complete_date` in the report timezone; a pair needs complete, adjacent 28-day windows, identical definition, provider definition, full sample selection, filters, panel and timezone. Missing completeness or a changed cohort yields no delta. Imported provider origin and completeness remain attributed to the owner's export.
+
+AI panel metrics replay through `measurePanel()` from `{kind:"panel",run_id,provider_origin,panel,responses,evaluations}`. Frozen `target_identity.panel` is `{target_entity,target_domains,competitor_entities,evidence_ref}` and has a matching approved mapping file. Questions, engine, surface, model, search use, locale, region and target identity must match the frozen run. Every response has `response_ref` (indexed redacted provider response) and `extraction_ref` (indexed `{run_id,response_id,raw_ref,raw_sha256,normalized_response}` receipt). Every evaluation has `evidence_ref` for an indexed `{run_id,response_id,approved_by,evaluation}` receipt. Evaluable citations have `source_evidence_ref` whose index entry `source_url` equals the cited URL. Evaluable claims have `fact_id` and `source_evidence_ref`, and their `panel.fact_list_ref` opens an approved `{run_id,target_entity,approved_by,facts:[{fact_id,...}]}` list. Missing material is a contract error. These links preserve attribution; they do not independently authenticate a provider or prove factual truth.
+
+The persisted `CostLedger` snapshot is indexed at `costs.evidence_ref`; unknown settlement, observed overrun and `host_policy` limitations stay visible. Do not include secrets, account tokens, personal records, or private card text in a packet or evidence directory.
+
+Findings merge only when check, unit and normalized problem text agree. Every contributing source remains on the merged finding. A finding must match a failed or unknown check observation. The curated remediation catalog chooses only an applicable, directly relevant mechanism; official sources lead the evidence order. A remote finding has a proposed change location and validation method but remains `proposed_only`. A `ChangeRecord` receipt binds run ID, change ID, target, path, environment, after hash, status, and passing checks whose indexed changed bytes have that hash. Production also requires a deployment receipt for the same target/path/hash and an explicitly linked passing `after` observation. Every required linked change must pass; local pass plus production pending remains pending. Receipts and hashes establish this local evidence chain, not external deployment truth. No SEO gain is predicted. Hypothetical readiness changes belong in a separately marked scenario, never in `after`.
+
+For `verification.status:"passed"`, the indexed receipt has `{run_id,change_id,target,path,environment,after_hash,status,checks:[{id,status:"passed",observed,evidence_ref,after_hash}]}`. Each check's ref opens the changed bytes. Production adds `deployed:true`, `deployment:{target,path,after_hash,evidence_ref}`, and `observation_id` / `observation_evidence_ref` in both receipt and `ChangeRecord.verification`. The deployment evidence file repeats run, target, path, hash, environment `production` and `confirmed_by`. The matching `after` observation must resolve the linked finding in a run context with the same target and `production` environment. Its indexed evidence entry also identifies `phase:"after"`, that target and `environment:"production"`; absent or different attribution leaves the finding unverified. Other comparison-condition changes may still yield `not_comparable` without invalidating a same-target verification. A pending receipt cannot combine with another passed change to finish a finding.
+
+Collector verdicts are replayed, not trusted. For each collector-sourced `index-policy`, `document-title` and `search-crawl-policy` observation the report reopens the preserved raw bytes of the same phase and rebuilds the verdict with the code the audit used. Index directives come from the HTML `<head>` meta tags (comments and script, style, textarea and title text are ignored) and the collected `X-Robots-Tag` header. The generic `robots` directives combine with the target engine's own (`googlebot` for Google, `yeti` for Naver); a header prefixed with another crawler name does not apply, and a crawler prefix scopes only the header line that carries it. Meta directives may be separated by commas or semicolons. A robots meta tag inside `<template>` or `<noscript>` is conservatively counted as a noindex directive. A present title replays as `unknown` because uniqueness and descriptiveness need separate evidence; a missing title replays as `fail`; reviewed duplicate-title or semantic verdicts from other evaluators are not rejected for having a title. A crawl-policy verdict needs the declared `robots` auxiliary artifact, its content hash, the page's final URL and a target engine, then recomputes `pass` or `fail` from the robots bytes. Every collected response is replayed from its hashed `*.response.json` record: the collection entry must equal the record, the final URL must follow the recorded redirect chain (no redirect means the final URL is the normalized request URL), and header lines come from the record, so index every `responses[].evidence_ref` from the audit index with `source_ref:"optbrew:collector"`. A selected page must be either collected or listed in `skipped`, and an indexed collector artifact requires its baseline audit snapshot. Every observation the collector plans for a selected page (fetch, title, index and, for Naver with a disallowing declared robots file, crawl policy) must be present in the packet and in the saved observations; a missing one is an error, never a silent pass. A redirected URL binds its requested unit to the artifact first; the module output must describe that artifact's final URL (`requested_url` and `redirect_chain` stay with it). A header-only `noindex` finding uses the same HTML plus header replay as the observation and must belong to the finding's own unit.
+
+`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 `/`.
+
+Both formats show four tables: score, remediation, actual outcomes, and remaining work. Score arithmetic comes from `score()` and `compare()`. Actual outcome pairs require the same native metric definition, filters, sample selection and panel, plus two adjacent complete 28-day windows. An absent or ambiguous value stays unknown. Markdown escapes pipes, HTML and line breaks in evidence and titles. `data_class:synthetic` labels fixture reports and cannot be presented as observed production performance.

package/skills/optbrew/references/routing.md

@@ -0,0 +1,15 @@
+# Situation routing
+
+필요한 분기의 GUIDE만 연다. 모든 모듈 출력은 관찰 후보이며 한 URL·문제·검사는 한 번만 채점한다. 무료 경로는 허용된 공개 HTTP/HTML과 사용 가능한 호스트 도구를 사용한다. 원본 HTML, 렌더, 소유자 패널과 AI 제공자 응답의 출처를 각각 기록한다.
+
+| 상황 | 주력 | 보완·입력 | 산출물 |
+|---|---|---|---|
+| 기술 차단·색인 | [mblode audit](../modules/mblode-seo/references/audit.md), [marketing SEO audit](../modules/marketing-search/skills/seo-audit/GUIDE.md) | 네이버 목표면 [Naver](../modules/naver-searchadvisor/GUIDE.md); HTTP·원본 HTML·허용된 렌더·소유자 URL 검사 | 차단·오류·unknown과 근거 |
+| URL·템플릿 구조 | [mblode](../modules/mblode-seo/GUIDE.md), [site architecture](../modules/marketing-search/skills/site-architecture/GUIDE.md) | 대량 생성 요청일 때만 [programmatic SEO](../modules/marketing-search/skills/programmatic-seo/GUIDE.md) | 고정 URL 표본·링크·템플릿 개선안 |
+| 페이지 수집 | [Firecrawl SEO audit](../modules/firecrawl-seo-audit/GUIDE.md) | 같은 경계와 비용을 보장하는 호스트 HTTP/브라우저 기능 | 원본·렌더 구분 및 raw 참조 |
+| 질문·답변·엔티티 | [Magnus](../modules/magnus-seo/GUIDE.md), [AI SEO](../modules/marketing-search/skills/ai-seo/GUIDE.md) | [content strategy](../modules/marketing-search/skills/content-strategy/GUIDE.md), [schema](../modules/marketing-search/skills/schema/GUIDE.md); 고정 질문·사실 목록 | 근거 있는 답변·사실 정정안 |
+| 네이버 노출 | [Naver](../modules/naver-searchadvisor/GUIDE.md) | mblode 기술 근거, Yeti 응답·마크업·Search Advisor 소유자 자료 | 네이버 범위의 관찰과 unknown |
+| AI 인용·경쟁 비교 | [SE Ranking](../modules/seranking-seo/skills/seo-ai-search-share-of-voice/GUIDE.md) | 승인된 API 또는 날짜가 있는 내보내기, Magnus 질문 프로토콜 | 엔진별 인용 실측; 무료 감사의 필수 조건 아님 |
+| 유입·전환 비교 | [mblode monitoring](../modules/mblode-seo/references/monitoring.md), [analytics](../modules/marketing-search/skills/analytics/GUIDE.md) | 같은 소유 속성·필터·완결된 28일 창 | 실제 성과와 비교 가능성 |
+
+호스트 도구의 경계·비용 강제가 확인되지 않으면 사용하지 않는다. 직접 Anthropic v0.1.0은 [api.md](api.md)의 텍스트 전용 Messages 형태와 정확한 모델 ID 네 개만 지원한다. 다른 API와 SE Ranking 실행은 각자의 승인·상한·능력 근거가 있어야 한다. 호스트 정책만 비용을 강제하면 그 한계를 보고한다.

package/skills/optbrew/references/schemas/contract.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://optbrew.local/schemas/contract.schema.json",
+  "title": "optbrew persisted entities v1.0.0",
+  "$defs": {
+    "ApplicabilityDecision": { "type": "object", "additionalProperties": false, "required": ["condition", "reason", "evidence_ref"], "properties": { "condition": { "type": "string" }, "reason": { "type": "string" }, "evidence_ref": { "type": "string" } } },
+    "UrlRef": { "type": "object", "additionalProperties": false, "required": ["original", "normalized"], "properties": { "original": { "type": "string", "format": "uri" }, "normalized": { "type": "string", "format": "uri" }, "public_indexing": { "type": "boolean" }, "indexing_decision": { "$ref": "#/$defs/ApplicabilityDecision" } } },
+    "AuxiliaryResource": { "type": "object", "additionalProperties": false, "required": ["kind", "original", "normalized"], "properties": { "kind": { "enum": ["robots", "sitemap", "policy"] }, "original": { "type": "string", "format": "uri" }, "normalized": { "type": "string", "format": "uri" } } },
+    "PageType": { "type": "object", "required": ["id", "urls"], "properties": { "id": { "type": "string" }, "urls": { "type": "array", "items": { "$ref": "#/$defs/UrlRef" } } } },
+    "FamilyPlan": { "type": "object", "additionalProperties": false, "required": ["family_id", "applicable"], "properties": { "family_id": { "type": "string" }, "applicable": { "type": "boolean" }, "urls": { "type": "array", "items": { "type": "string" } }, "engines": { "type": "array", "items": { "type": "string" } }, "applicability_decision": { "$ref": "#/$defs/ApplicabilityDecision" } } },
+    "Question": { "type": "object", "required": ["id", "question", "category"], "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "category": { "enum": ["brand", "non_brand"] }, "goal": { "type": "string" } } },
+    "Protocol": { "type": "object", "additionalProperties": false, "required": ["page_types", "engines", "families", "locale", "region", "browser", "device", "question_panel", "surfaces", "models", "search_enabled"], "properties": {
+      "page_types": { "type": "array", "items": { "$ref": "#/$defs/PageType" } }, "engines": { "type": "array", "items": { "type": "string" } }, "families": { "type": "array", "items": { "$ref": "#/$defs/FamilyPlan" } },
+      "auxiliary_resources": { "type": "array", "items": { "$ref": "#/$defs/AuxiliaryResource" } },
+      "locale": { "type": "string" }, "region": { "type": "string" }, "browser": { "type": "string" }, "device": { "type": "string" }, "question_panel": { "type": "array", "items": { "$ref": "#/$defs/Question" } }, "surfaces": { "type": "array" }, "models": { "type": "array" }, "search_enabled": { "type": ["boolean", "null"] },
+      "target": { "type": ["string", "object"] }, "environment": { "type": "string" }, "evaluation_version": { "type": "string" }, "protocol_version": { "type": "string" }, "target_identity": { "type": "object" }
+    } },
+    "RunContext": { "type": "object", "required": ["schema_version", "run_id", "target", "environment", "goals", "allowed_changes", "scope", "protocol", "evaluation_version", "protocol_version", "data_sources", "cost_decision", "evidence_ref"], "properties": {
+      "schema_version": { "const": "1.0.0" }, "run_id": { "type": "string" }, "target": { "type": ["string", "object"] }, "environment": { "type": "string" }, "goals": { "type": "array" }, "allowed_changes": { "type": "array" }, "scope": { "type": "object" }, "protocol": { "$ref": "#/$defs/Protocol" }, "evaluation_version": { "type": "string" }, "protocol_version": { "type": "string" }, "data_sources": { "type": "array" }, "cost_decision": { "type": "object" }, "evidence_ref": { "type": "string" }
+    } },
+    "CheckObservation": { "type": "object", "required": ["schema_version", "observation_id", "check_id", "family_id", "unit_key", "state", "q", "partial_basis", "reason", "evaluator_type", "source_ref", "evidence_ref"], "properties": {
+      "schema_version": { "const": "1.0.0" }, "observation_id": { "type": "string" }, "check_id": { "type": "string" }, "family_id": { "type": "string" }, "unit_key": { "type": "string" }, "state": { "enum": ["pass", "partial", "fail", "unknown", "not_applicable"] }, "q": { "type": ["number", "null"], "minimum": 0, "maximum": 1 }, "partial_basis": { "type": ["object", "null"] }, "reason": { "type": "string" }, "evaluator_type": { "enum": ["human", "host_model", "external_model", "code"] }, "source_ref": { "type": "string" }, "evidence_ref": { "type": "string" }, "applicability_decision": { "$ref": "#/$defs/ApplicabilityDecision" }, "blocker": { "type": "boolean" }, "measurement": { "type": "object" }
+    } },
+    "MetricObservation": { "type": "object", "required": ["schema_version", "metric_id", "value_state", "value", "numerator", "denominator", "definition", "filters", "window", "panel_hash", "provider_definition", "sample_selection", "source_ref", "evidence_ref"], "properties": {
+      "schema_version": { "const": "1.0.0" }, "metric_id": { "type": "string" }, "value_state": { "enum": ["measured", "unknown", "zero_or_missing", "not_applicable"] }, "value": { "type": ["number", "null"] }, "numerator": { "type": ["number", "null"] }, "denominator": { "type": ["number", "null"] }, "definition": { "type": "string" }, "filters": { "type": "object" }, "window": { "$ref": "#/$defs/MetricWindow" }, "panel_hash": { "type": ["string", "null"] }, "provider_definition": { "type": "string" }, "sample_selection": { "type": "object" }, "source_ref": { "type": "string" }, "evidence_ref": { "type": "string" }
+    } },
+    "MetricWindow": { "type": "object", "required": ["start", "end", "timezone"], "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "timezone": { "type": "string" } } },
+    "ComparisonResult": { "type": "object", "required": ["status", "score_deltas", "reasons"], "properties": { "status": { "enum": ["comparable", "not_comparable", "no_after"] }, "score_deltas": { "type": "array" }, "reasons": { "type": "array", "items": { "type": "string" } } } },
+    "Finding": { "type": "object", "required": ["schema_version", "finding_id", "check_id", "unit_key", "priority", "blocker", "message", "source_ref", "evidence_ref", "remediation_ids", "status"], "properties": {
+      "schema_version": { "const": "1.0.0" }, "finding_id": { "type": "string" }, "check_id": { "type": "string" }, "unit_key": { "type": "string" }, "priority": { "type": "string" }, "blocker": { "type": "boolean" }, "message": { "type": "string" }, "source_ref": { "type": "string" }, "evidence_ref": { "type": "string" }, "remediation_ids": { "type": "array" }, "status": { "type": "string" }
+    } },
+    "ChangeRecord": { "type": "object", "required": ["schema_version", "change_id", "finding_ids", "environment", "path", "before_hash", "after_hash", "backup_ref", "verification", "evidence_ref"], "properties": {
+      "schema_version": { "const": "1.0.0" }, "change_id": { "type": "string" }, "finding_ids": { "type": "array" }, "environment": { "type": "string" }, "path": { "type": "string" }, "before_hash": { "type": "string" }, "after_hash": { "type": "string" }, "backup_ref": { "type": "string" }, "verification": { "type": "object" }, "evidence_ref": { "type": "string" }
+    } },
+    "CostLedger": { "type": "object", "required": ["schema_version", "run_id", "budgets", "reservations", "settlements", "approval_ref", "source_ref"], "properties": {
+      "schema_version": { "const": "1.0.0" }, "run_id": { "type": "string" }, "budgets": { "type": "array" }, "reservations": { "type": "array" }, "settlements": { "type": "array" }, "approval_ref": { "type": ["string", "null"] }, "source_ref": { "type": "string" }
+    } },
+    "ScoreResult": { "type": "object", "required": ["schema_version", "evaluation_version", "profile", "A", "M", "N", "score", "coverage", "missing_bounds", "band", "readiness_status", "blockers", "unknown_core", "source_ref"], "properties": {
+      "schema_version": { "const": "1.0.0" }, "evaluation_version": { "type": "string" }, "profile": { "type": "string" }, "A": { "type": "number" }, "M": { "type": "number" }, "N": { "type": "number" }, "score": { "type": ["number", "null"] }, "coverage": { "type": ["number", "null"] }, "missing_bounds": { "type": ["array", "null"] }, "band": { "type": ["string", "null"] }, "readiness_status": { "enum": ["blocked", "unverified", "provisional", "measured", "not_applicable"] }, "blockers": { "type": "array" }, "unknown_core": { "type": "array" }, "source_ref": { "type": "string" }
+    } },
+    "ScoreInput": { "type": "object", "required": ["schema_version", "run_context", "observations"], "properties": {
+      "schema_version": { "const": "1.0.0" }, "run_context": { "$ref": "#/$defs/RunContext" }, "observations": { "type": "array", "items": { "$ref": "#/$defs/CheckObservation" } }
+    } },
+    "ReportPacket": { "type": "object", "required": ["schema_version", "run_context", "baseline", "after", "comparison", "metrics", "findings", "changes", "costs", "remaining", "evidence_root", "evidence_index", "source_ref"], "properties": {
+      "schema_version": { "const": "1.0.0" }, "run_context": { "$ref": "#/$defs/RunContext" }, "baseline": { "type": "object", "required": ["input", "scores"], "properties": { "input": { "$ref": "#/$defs/ScoreInput" }, "scores": { "type": "array", "items": { "$ref": "#/$defs/ScoreResult" } } } }, "after": { "type": ["object", "null"] }, "comparison": { "$ref": "#/$defs/ComparisonResult" }, "metrics": { "type": "array", "items": { "$ref": "#/$defs/MetricObservation" } }, "findings": { "type": "array", "items": { "$ref": "#/$defs/Finding" } }, "changes": { "type": "array", "items": { "$ref": "#/$defs/ChangeRecord" } }, "costs": { "$ref": "#/$defs/CostLedger" }, "remaining": { "type": "array" }, "evidence_root": { "type": "string" }, "evidence_index": { "type": "array", "items": { "type": "object", "required": ["ref", "sha256", "kind", "run_id"], "properties": { "ref": { "type": "string" }, "sha256": { "type": "string" }, "kind": { "type": "string" }, "run_id": { "type": "string" }, "source_ref": { "type": "string" }, "source_url": { "type": "string" } } } }, "audit_ref": { "type": "string" }, "audit_snapshots": { "type": "array" }, "source_ref": { "type": "string" }, "data_class": { "enum": ["synthetic", "real", "unknown"] }, "capabilities": { "type": "object" }
+    } },
+    "InstallRecord": { "type": "object", "required": ["schema_version", "scope_id", "release_version", "bundle_hash", "source", "managed_root", "targets", "file_hashes", "previous_releases", "transaction", "source_ref"], "properties": {
+      "schema_version": { "const": "1.0.0" }, "scope_id": { "type": "string" }, "release_version": { "type": "string" }, "bundle_hash": { "type": "string" }, "source": { "type": "string" }, "managed_root": { "type": "string" }, "targets": { "type": "array" }, "file_hashes": { "type": "object" }, "previous_releases": { "type": "array" }, "transaction": { "type": "object" }, "source_ref": { "type": "string" }
+    } }
+  }
+}

package/skills/optbrew/references/scoring.md

@@ -0,0 +1,62 @@
+# optbrew readiness scoring contract (evaluation 0.1.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.
+
+## Fixed input
+
+`ScoreInput` is `{schema_version:"1.0.0",run_context:RunContext,observations:CheckObservation[]}`. The JSON Schema in `schemas/contract.schema.json` names this and the nine persisted entities. `validateEntity(typeName,value)` returns the value or throws `ContractError`. `freezeProtocol(run_context)` returns `{protocol,protocol_hash}`. Its hash covers the selected URLs and page types, indexing intent, family condition codes, engines, location/language, panel and surface/model/search settings, browser/device, target, environment and separate evaluation/protocol versions. It excludes `run_id`, evidence paths, collection times and explanatory decision text. Changing a comparison condition requires re-evaluation from preserved raw data or `not_comparable`.
+
+Every `run_context.protocol.families` entry is `{family_id,applicable,urls?,engines?,applicability_decision?}`. A `ScoreInput` must explicitly decide all 22 entries. False requires `{condition,reason,evidence_ref}` with a condition allowed for that family in `check-registry.json`; true forbids a decision. The reason and evidence reference must be nonempty. Unknown facts or missing collection data leave applicable units `unknown`; they do not remove denominator weight. `urls` and `engines`, when supplied, must equal the entire applicable selected set. To exclude one optional unit, submit an evidence-backed `not_applicable` observation for that unit. A subset in a family plan is rejected. NEO is reported only for a Naver target.
+
+Every selected URL is a public audit target and always gets `fetch-response`. Its optional `public_indexing` defaults to true. An intentional non-index target sets `public_indexing:false` and supplies `indexing_decision:{condition:"not_public_index_target",reason,evidence_ref}`. Public-index targets automatically get `index-policy` and `discovery`; target engines also get `search-crawl-policy`. Naver as a target automatically activates `naver-markup`. Bare flags cannot turn these families off. A selected URL still gets `fetch-response` if intentionally non-indexed. An unreachable, uncollected or unclear check is `unknown`, never N/A.
+
+`check-registry.json` fixes every family's `verdict_mode` and `na_conditions`. The family-level exclusion and unit N/A condition codes are:
+
+| Family | Allowed condition codes |
+|---|---|
+| fetch-response | none |
+| search-crawl-policy | `no_public_index_target`, `no_target_engine` (whole family only) |
+| index-policy, discovery | `no_public_index_target` (whole family only) |
+| render-content | `not_render_dependent` |
+| document-title | `not_html` |
+| canonical-consistency | `no_representative_url_policy` |
+| internal-navigation | `not_link_based` |
+| structured-data-truth | `markup_not_used_or_selected` |
+| locale-links | `single_locale` |
+| naver-markup | `naver_not_target` (whole family only), `not_html` (unit) |
+| lcp-field, inp-field, cls-field | `outside_performance_scope` |
+| question-coverage | `no_fixed_questions` (whole family only) |
+| claim-support | `no_material_claims` |
+| answer-clarity | `no_matching_questions` |
+| original-value | `simple_contact_or_support` |
+| entity-identity | `no_identified_entity` (whole family only) |
+| fact-consistency | `no_evaluable_facts` |
+| freshness-truth | `no_date_or_currentness` |
+| source-transparency | `not_required_for_purpose` |
+
+These codes identify a condition and point to evidence; the reference alone does not verify the evidence's truth. The collecting agent must preserve the actual evidence. A missing approved fact list for `fact-consistency`, or missing field performance data, is `unknown`, not an exclusion.
+
+`question_panel` contains fixed `{id,question,category,goal?}` entries. Category is `brand` or `non_brand`; IDs are unique. `question-coverage` and `answer-clarity` require a nonempty panel. A partial `question-coverage` ratio uses the fixed panel length as its denominator.
+
+Each page type has a stable ID and an array of `{original,normalized}` HTTP(S) URLs. Normalized URLs must be unique across types. Unit keys are deterministic:
+
+| Unit scope | Key | Examples |
+|---|---|---|
+| URL | `family_id\|normalized_url` | `index-policy\|https://example.com/` |
+| Engine and URL | `family_id\|engine\|normalized_url` | `search-crawl-policy\|google\|https://example.com/` |
+| Origin | `family_id\|origin` | `lcp-field\|https://example.com` |
+| Site | `family_id\|site` | `question-coverage\|site` |
+
+`CheckObservation.check_id` equals its registered `family_id` in this evaluation version. Multiple modules can submit the same unit and verdict; it counts once. An unregistered unit or conflicting verdict is a contract error. For `pass` and `fail`, `q` is exactly 1 and 0. For `unknown` and `not_applicable`, `q` and `partial_basis` are null. Unit N/A also requires `applicability_decision:{condition,reason,evidence_ref}`; core policy units and fixed site/public units cannot use N/A. A confirmed noindex or target crawler block is `fail`, `q=0`, and a blocker. Missing policy evidence is `unknown`.
+
+The 14 binary families do not accept partial; their applicable units use pass, fail or unknown. Optional units may use N/A only under the allowed condition decision above. `lcp-field`, `inp-field`, `cls-field`, `answer-clarity` and `original-value` accept `partial_basis:{kind:"threshold_half"}` with `q=0.5`. `question-coverage`, `claim-support` and `fact-consistency` accept `partial_basis:{kind:"ratio",numerator:int,denominator:positive_int}` with a matching interior ratio. `question-coverage` also requires denominator equal to the fixed panel length. A CWV verdict requires `measurement:{value,percentile:75,source_type:"field",unit}`; use `ms` for LCP/INP and `unitless` for CLS. An absent field measurement is `unknown`, not N/A.
+
+## Weight and status calculation
+
+`compileUnits(input,profile)` divides positive axis weight by applicable families, then engines, then fixed page types and URLs. Each nonempty page type gets equal share; URLs within a type get equal share. Site and origin units do not multiply with page count. Units marked `not_applicable` are removed and the remaining units in that family are renormalized. If a whole family has no units, it is removed from its axis. If an axis has no applicable families, the remaining positive axes are renormalized to 100. LLMO's P axis has zero weight. A weighted unit is `{key,family_id,engine,url,weight,state,q}`.
+
+`scoreWeighted(units)` returns raw weighted totals `A` (applicable), `M` (measured) and `N` (measured credit), plus one-decimal display percentages: `score=100N/M`, `coverage=100M/A`, `missing_bounds=[100N/A,100(N+A-M)/A]`. `score` is null when `M=0`; `coverage` and `missing_bounds` are null when `A=0`. The bounds are all-missing-fail and all-missing-pass extremes, not a confidence interval. Internal comparisons use raw values with `1e-9` tolerance; display rounds only at the end.
+
+`score(input)` returns ordered `ScoreResult[]` for SEO, optional NEO, AEO, GEO and LLMO. SEO is the default aggregate and is calculated directly, never from the mean of profile scores. Each result includes `{schema_version,evaluation_version,profile,A,M,N,score,coverage,missing_bounds,band,readiness_status,blockers,unknown_core,source_ref}`. Bands are `focus_improvement` (0–59), `major_improvement` (60–79), `additional_improvement` (80–94), and `remaining_review` (95–100). Status precedence is `not_applicable` for `A=0`, then `blocked` for confirmed access/crawl/noindex failures or an explicit severe-fact blocker, then `unverified` for unknown applicable access/index core units, then `provisional` below 80% measured coverage, else `measured`. `measured` means only that this optbrew readiness audit has enough measured coverage by its own rule.
+
+Run a stored input without service access: `node skills/optbrew/scripts/cli.mjs score --input input.json --output score.json`. The output is the same JSON `ScoreResult[]` as the library call. The CLI validates before writing.

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

@@ -0,0 +1,116 @@
+import https from 'node:https';
+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';
+
+const ENDPOINT = new URL('https://api.anthropic.com/v1/messages');
+const VERSION = '2023-06-01';
+// 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 }]));
+
+async function nodeTransport({ headers, body, timeoutMs, signal }) {
+  return new Promise((resolve, reject) => {
+    const req = https.request(ENDPOINT, { method: 'POST', headers, signal }, res => {
+      const chunks = []; let size = 0;
+      res.on('data', chunk => {
+        size += chunk.length;
+        if (size > 5242880) { 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') }));
+      res.on('error', reject);
+    });
+    req.setTimeout(timeoutMs, () => req.destroy(new Error('provider timeout')));
+    req.on('error', reject);
+    req.end(body);
+  });
+}
+
+function observation(request, error, extra = {}) {
+  return { provider: 'anthropic', surface: 'messages_api', model: request?.model ?? null,
+    search_enabled: Array.isArray(request?.tools) && request.tools.some(x => /^web_search_/.test(x.type ?? '')),
+    request_id: null, response_ref: null, usage: null, valid: false, error, evidence_ref: null, ...extra };
+}
+
+function actualUsage(bounds, usage) {
+  if (!usage || typeof usage !== 'object') return null;
+  const values = bounds.map(bound => {
+    let amount;
+    if (bound.unit === 'tokens' && [usage.input_tokens, usage.output_tokens].every(x => Number.isSafeInteger(x) && x >= 0))
+      amount = usage.input_tokens + usage.output_tokens +
+        (usage.cache_creation_input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0);
+    return Number.isSafeInteger(amount) && amount >= 0 ? { ...bound, amount } : null;
+  });
+  return values.every(Boolean) ? values : null;
+}
+
+function supportedRequest(request) {
+  if (!request || typeof request !== 'object' || Array.isArray(request) ||
+      Object.keys(request).some(key => !['model', 'max_tokens', 'messages'].includes(key))) return false;
+  const model = MODELS.get(request.model);
+  return Boolean(model && Number.isInteger(request.max_tokens) && request.max_tokens > 0 &&
+    request.max_tokens <= model.maxOutputTokens && Array.isArray(request.messages) && request.messages.length > 0 &&
+    request.messages.every(message => message && typeof message === 'object' && !Array.isArray(message) &&
+      Object.keys(message).every(key => ['role', 'content'].includes(key)) &&
+      ['user', 'assistant'].includes(message.role) && typeof message.content === 'string' && message.content.length > 0));
+}
+
+/** Optional paid call; every attempt has a reservation and unknown billing keeps its cap. */
+export async function requestAnthropic({ context, request, env = process.env, transport = nodeTransport, ledgerPath }) {
+  const decision = context?.cost_decision;
+  const upperBounds = decision?.providers?.anthropic?.upper_bounds;
+  if (!decision?.approval_ref || !Array.isArray(upperBounds) || !upperBounds.length || !ledgerPath)
+    return observation(request, 'cost_decision_required');
+  if (!env?.ANTHROPIC_API_KEY) return observation(request, 'api_key_missing');
+  let body;
+  try { body = JSON.stringify(request); request = JSON.parse(body); }
+  catch { return observation(request, 'unsupported_direct_request'); }
+  if (!supportedRequest(request)) return observation(request, 'unsupported_direct_request');
+  const requiredTokens = MODELS.get(request.model).contextTokens + request.max_tokens;
+  if (upperBounds.length !== 1 || upperBounds[0].unit !== 'tokens' || !Number.isSafeInteger(upperBounds[0].amount) ||
+      upperBounds[0].amount < requiredTokens) return observation(request, 'upper_bound_unverified');
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let reservation;
+    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);
+    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 }),
+        new Promise((_, reject) => controller.signal.addEventListener('abort', () => reject(new Error('timeout')), { once: true })),
+      ]);
+    } catch {
+      await settleCost(ledgerPath, reservation.reservation_id, 'unknown');
+      return observation(request, 'transport_or_timeout_unknown_billing');
+    } finally { clearTimeout(timer); }
+    let parsed;
+    try { parsed = JSON.parse(Buffer.isBuffer(response.body) ? response.body.toString('utf8') : response.body); }
+    catch { await settleCost(ledgerPath, reservation.reservation_id, 'unknown'); return observation(request, 'malformed_provider_json_unknown_billing'); }
+    const actual = actualUsage(upperBounds, parsed?.usage);
+    const settled = await settleCost(ledgerPath, reservation.reservation_id, actual ?? 'unknown');
+    const overrun = settled.reservations.some(x => x.reservation_id === reservation.reservation_id && x.status === 'overrun');
+    if (response.status >= 200 && response.status < 300 && parsed?.type === 'message') {
+      const safeBody = JSON.stringify(parsed).replaceAll(env.ANTHROPIC_API_KEY, '[REDACTED]');
+      const evidenceDir = path.join(path.dirname(ledgerPath), 'evidence', 'provider');
+      const evidenceRef = path.join(evidenceDir, `anthropic-${createHash('sha256').update(safeBody).digest('hex')}.json`);
+      try {
+        await mkdir(evidenceDir, { recursive: true });
+        try { await writeFile(evidenceRef, `${safeBody}\n`, { flag: 'wx' }); }
+        catch (error) {
+          if (error.code !== 'EEXIST' || await readFile(evidenceRef, 'utf8') !== `${safeBody}\n`) throw error;
+        }
+      } catch { return observation(request, 'provider_evidence_persist_failed'); }
+      return observation(request, overrun ? 'observed_cost_overrun' : null, { valid: !overrun, request_id: typeof parsed.id === 'string' ? parsed.id : null,
+        response_ref: evidenceRef, usage: parsed.usage ?? null, evidence_ref: evidenceRef });
+    }
+    if (overrun) return observation(request, 'observed_cost_overrun', { usage: parsed?.usage ?? null });
+    if (![429, 500, 502, 503, 504].includes(response.status) || attempt === 1)
+      return observation(request, `provider_http_${Number(response.status) || 'error'}`);
+  }
+  return observation(request, 'attempt_limit');
+}

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

@@ -0,0 +1,81 @@
+import { validateEntity, ContractError } from '../core/contracts.mjs';
+
+const providers = new Set(['gsc', 'ga4', 'google_ai', 'bing_ai', 'naver', 'se_ranking']);
+const day = 86400000;
+const datePattern = /^\d{4}-\d{2}-\d{2}$/;
+function dateValue(value) {
+  if (typeof value !== 'string' || !datePattern.test(value)) throw new ContractError('invalid complete local date');
+  const time = Date.parse(`${value}T00:00:00Z`);
+  if (!Number.isFinite(time) || new Date(time).toISOString().slice(0, 10) !== value) throw new ContractError('invalid complete local date');
+  return time;
+}
+function dateString(time) { return new Date(time).toISOString().slice(0, 10); }
+
+/** Caller supplies the last complete date in the named timezone. */
+export function completeWindows(lastCompleteDate, timezone) {
+  const end = dateValue(lastCompleteDate);
+  try { new Intl.DateTimeFormat('en', { timeZone: timezone }); }
+  catch { throw new ContractError('invalid timezone'); }
+  if (!timezone) throw new ContractError('timezone required');
+  return { before: { start: dateString(end - 55 * day), end: dateString(end - 28 * day), timezone },
+    after: { start: dateString(end - 27 * day), end: lastCompleteDate, timezone } };
+}
+
+/** Owner export rows retain provider meaning and source filters; no cross-provider synthesis. */
+export function normalizeImport(provider, rows, metadata) {
+  if (!providers.has(provider) || !Array.isArray(rows) || !metadata || typeof metadata !== 'object')
+    throw new ContractError('invalid provider export');
+  const required = ['timezone', 'collected_at', 'source_ref', 'evidence_ref'];
+  for (const field of required) if (typeof metadata[field] !== 'string' || !metadata[field])
+    throw new ContractError(`import metadata requires ${field}`);
+  const { window, sample_selection } = metadata;
+  if (!window || window.timezone !== metadata.timezone || dateValue(window.start) > dateValue(window.end) ||
+      !sample_selection || !['all', 'positive_only', 'unknown'].includes(sample_selection.kind))
+    throw new ContractError('invalid window or sample selection');
+  if (!Number.isFinite(Date.parse(metadata.collected_at)) || !/[zZ]|[+-]\d\d:\d\d$/.test(metadata.collected_at))
+    throw new ContractError('collected_at requires timezone');
+  if (metadata.last_complete_date !== undefined) dateValue(metadata.last_complete_date);
+  return rows.map(row => {
+    if (!row || typeof row.metric_id !== 'string' || !row.metric_id ||
+        typeof (row.provider_definition ?? metadata.provider_definition) !== 'string' ||
+        !(row.provider_definition ?? metadata.provider_definition).trim())
+      throw new ContractError('native metric definition required');
+    if (row.filters && (typeof row.filters !== 'object' || Array.isArray(row.filters)))
+      throw new ContractError('row filters must be an object');
+    for (const key of ['property', 'aggregation'])
+      if (row.filters?.[key] != null && metadata[key] != null && row.filters[key] !== metadata[key])
+        throw new ContractError(`row ${key} conflicts with export scope`);
+    if (sample_selection.kind === 'positive_only' &&
+        (['citation_response_rate', 'all_question_citation_rate', 'overall_citation_rate'].includes(row.metric_id) ||
+         row.denominator_scope === 'all_questions'))
+      throw new ContractError('positive-only sample cannot estimate all-question citation rate');
+    const ambiguousZero = provider === 'google_ai' && row.value === 0 && row.missing_mask !== false;
+    const ambiguousDisplay = provider === 'google_ai' && (['~', '-'].includes(row.display_state) || ['~', '-'].includes(row.value));
+    const ambiguousMask = row.missing_mask === true;
+    const value_state = row.value_state ?? (ambiguousZero || ambiguousDisplay || ambiguousMask ? 'zero_or_missing' :
+      row.value === null || row.value === undefined ? 'unknown' : 'measured');
+    if ((ambiguousZero || ambiguousDisplay || ambiguousMask) && value_state === 'measured')
+      throw new ContractError('Google AI export zero requires a known nonmissing mask');
+    const value = value_state === 'measured' ? row.value : null;
+    if (value_state === 'measured' && !Number.isFinite(value)) throw new ContractError('measured value must be finite');
+    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}`,
+      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'),
+        hostname: dimension('hostname'), search_type: dimension('search_type'),
+        device: dimension('device'), country: dimension('country'),
+        aggregation: dimension('aggregation'), collected_at: metadata.collected_at,
+        ...(metadata.last_complete_date ? { last_complete_date: metadata.last_complete_date } : {}),
+        path: dimension('path'), query: dimension('query'), export_scope },
+      window: { ...window }, panel_hash: null,
+      provider_definition: row.provider_definition ?? metadata.provider_definition,
+      sample_selection: { ...sample_selection,
+        ...(value_state === 'not_applicable' ? { exclusion_reason: row.not_applicable_reason } : {}) },
+      source_ref: metadata.source_ref,
+      evidence_ref: row.evidence_ref ?? metadata.evidence_ref };
+    return validateEntity('MetricObservation', observation);
+  });
+}

package/skills/optbrew/scripts/audit.mjs

@@ -0,0 +1,145 @@
+#!/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 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';
+
+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);
+  });
+}
+
+function observation(artifact, family, state, reason, engine = null, evidenceRef = artifact.evidence_ref) {
+  const unit_key = `${family}|${engine ? `${engine}|` : ''}${artifact.normalized_url}`;
+  const value = { schema_version: '1.0.0', observation_id: createHash('sha256').update(unit_key).digest('hex'),
+    check_id: family, family_id: family, unit_key,
+    state, q: state === 'pass' ? 1 : state === 'fail' ? 0 : null, partial_basis: null, reason,
+    evaluator_type: 'code', source_ref: 'optbrew:collector', evidence_ref: evidenceRef };
+  return validateEntity('CheckObservation', value);
+}
+
+/** 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 observations = [];
+  const planned = new Set(context.protocol.families.filter(x => x.applicable).map(x => x.family_id));
+  const selectedUrls = new Set(context.protocol.page_types.flatMap(type => type.urls.map(x => x.normalized)));
+  const declaredRobots = new Set((context.protocol.auxiliary_resources ?? [])
+    .filter(resource => resource.kind === 'robots').map(resource => resource.normalized));
+  const publicUrls = new Set(context.protocol.page_types.flatMap(type => type.urls.filter(x => x.public_indexing !== false).map(x => x.normalized)));
+  for (const artifact of collection.artifacts) {
+    const saved = artifacts.find(x => x.normalized_url === artifact.normalized_url);
+    if (planned.has('fetch-response') && selectedUrls.has(artifact.normalized_url)) observations.push(observation(saved, 'fetch-response',
+      artifact.error || artifact.status < 200 || artifact.status >= 300 && artifact.status < 400 ? 'unknown' : artifact.status >= 400 ? 'fail' : 'pass',
+      artifact.error ? 'Request did not finish' : `HTTP ${artifact.status}`));
+    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 (planned.has('document-title') && selectedUrls.has(artifact.normalized_url))
+        observations.push(observation(saved, 'document-title', output.title ? 'unknown' : 'fail',
+          output.title ? 'Raw HTML has a title; uniqueness and descriptiveness are not established' : 'Raw HTML has no title'));
+      if (planned.has('index-policy') && publicUrls.has(artifact.normalized_url)) {
+        const blocked = output.index_blocked;
+        observations.push(observation(saved, 'index-policy', blocked ? 'fail' : 'pass',
+          blocked ? 'Raw response blocks indexing for the target engine' : 'Raw response has no applicable noindex directive'));
+      }
+      if (planned.has('search-crawl-policy') && publicUrls.has(artifact.normalized_url) &&
+          context.protocol.engines.includes('naver') && output.robots?.yeti_allowed === false)
+        observations.push(observation(saved, 'search-crawl-policy', 'fail', 'Collected robots.txt disallows Yeti path', 'naver', robotsEvidenceRef));
+    }
+    if (modules.includes('magnus-seo')) module_outputs['magnus-seo'].push(await magnus(artifact));
+  }
+  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, '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'),
+    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;
+}
+
+if (process.argv[1] && realpathSync(path.resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))) {
+  try {
+    const args = process.argv.slice(2);
+    const option = name => { const i = args.indexOf(name); return i < 0 ? null : args[i + 1]; };
+    const contextPath = option('--context');
+    const moduleText = option('--modules');
+    const outputDir = option('--output-dir');
+    if (!contextPath || !moduleText || !outputDir || args.length !== 6) throw new Error('usage: node skills/optbrew/scripts/audit.mjs --context <run-context.json> --modules naver-searchadvisor,magnus-seo --output-dir <run-dir>');
+    const context = JSON.parse(await readFile(contextPath, 'utf8'));
+    const result = await runAudit({ context, modules: moduleText.split(','), outputDir });
+    process.stdout.write(`${JSON.stringify({ evidence_ref: result.evidence_ref, evaluated_count: result.evaluated_count, request_count: result.request_count,
+      observations: result.observations.length })}\n`);
+  } catch (error) { process.stderr.write(`audit failed: ${error.message}\n`); process.exitCode = 2; }
+}

package/skills/optbrew/scripts/cli.mjs

@@ -0,0 +1,41 @@
+import { readFile, realpath, mkdir, rename, writeFile, rm } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { score } from './core/score.mjs';
+import { compare } from './core/compare.mjs';
+import { writeReport } from './core/report.mjs';
+
+/** Local calculation CLI. */
+export async function runCli(argv = process.argv.slice(2)) {
+  const usage = 'usage: cli.mjs score --input <file> --output <file> | compare --before <file> --after <file> --output <file> | report --input <packet.json> --output-dir <directory>';
+  let result, destination;
+  if (argv.length === 5 && argv[0] === 'report' && argv[1] === '--input' && argv[3] === '--output-dir' && argv[2] && argv[4]) {
+    const input = path.resolve(argv[2]);
+    const packet = JSON.parse(await readFile(input, 'utf8'));
+    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]));
+  } 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]);
+  } else if (argv.length === 7 && argv[0] === 'compare' && argv[1] === '--before' && argv[3] === '--after' &&
+      argv[5] === '--output' && argv[2] && argv[4] && argv[6]) {
+    const before = JSON.parse(await readFile(argv[2], 'utf8'));
+    const after = JSON.parse(await readFile(argv[4], 'utf8'));
+    result = compare(before, after);
+    destination = path.resolve(argv[6]);
+  } else throw new Error(usage);
+  await mkdir(path.dirname(destination), { recursive: true });
+  const temp = `${destination}.${process.pid}.tmp`;
+  try {
+    await writeFile(temp, `${JSON.stringify(result, null, 2)}\n`, { flag: 'wx' });
+    await rename(temp, destination);
+  } finally { await rm(temp, { force: true }); }
+  return result;
+}
+
+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; });
+}