AGENTS.md

Repository purpose

This repository contains reusable Amazon Ads Agent Skills. The canonical business logic lives under skills/<skill-name>/SKILL.md and must remain portable across Codex, Claude Code, WorkBuddy, and other Agent Skills-compatible runtimes.

First-run / installation guidance

For a fresh runtime, repository URL, or manual checkout, read docs/GETTING-STARTED.md before inventing runtime-specific install paths. The stable default is repository-workspace mode: clone the whole repository, open the repository root, keep AGENTS.md plus the canonical skills/ tree and shared references together, then progressively load only the Skill needed for the task.

A runtime manifest or cloned directory is not proof that Skill discovery succeeded. Verify a fresh setup with the bootstrap/smoke-test prompts in docs/GETTING-STARTED.md. If automatic discovery fails, explicitly load the matching skills/<name>/SKILL.md; for cross-domain work use skills/amazon-ads-optimizer/SKILL.md.

Skill discovery

• Treat every skills/*/SKILL.md as an independently invocable skill.
• Read only the matching skill first; load shared files from references/, playbooks/ and schemas/ only when needed.
• For a custom host without native Skill discovery, use scripts/resolve_skill_context.py: expose only the metadata catalog at discovery time, preload exactly one selected SKILL.md, and treat returned resources as on-demand pointers. Do not preload all Skill bodies, docs/research/, or evals/ merely because they exist.
• For cross-domain requests, use skills/amazon-ads-optimizer/SKILL.md as the orchestrator.
• For recurring weekly/Monday account reviews, start with playbooks/weekly-review.md, then load only specialist Skills required by material findings.
• When the task asks whether a previous optimization worked, route to skills/post-change-review/SKILL.md before proposing another edit on the same entity.
• When prior actions may overlap a new decision, load references/optimization-memory.md and retrieve only the bounded relevant entity history.
• When compared windows come from different APIs, MCPs, exports, warehouses or semantic/report versions, load references/data-lineage.md before making high-confidence trend or causal claims.
• When a decision depends on what the active MCP/connector can actually expose for the required profile, report, metric, dimension, history, pagination, freshness or semantic identity, load references/connector-capability.md; treat Partial, Unsupported and Unknown as acquisition-path evidence states, never as metric zero.
• Resolve decision-required connector capability IDs from references/connector-capability-catalog.json via scripts/resolve_skill_capabilities.py; do not invent new capability IDs ad hoc. When a causal review uses a registered decision_surface, pass that surface to the resolver so its versioned material-control set is attached to entity-state-readback; generic readback support must not substitute for exact control_types_exposed coverage. When a machine-readable connector capability snapshot is available, feed the resolved required IDs and merged data requirements into scripts/evaluate_connector_capability_gate.py before metric interpretation; Degraded/Blocked must cap the dependent decision to conservative classes instead of preserving high confidence.
• When a bid, budget, placement or other monetary-control Skill must turn a direction/raw estimate into a concrete magnitude, load references/action-sizing.md; do not invent a repository-global change percentage or damping constant.
• When a recommendation depends on a time-varying platform capability, exact platform limit, control eligibility, or console/API availability, load references/platform-capability-lineage.md and reconcile source date + capability scope before using the fact as action-safe.
• Historical replay fixtures under evals/ are test inputs, not reusable operating instructions; do not load them during ordinary account analysis unless explicitly running an eval.
• Do not duplicate business logic into this file.

Default operating mode

Default to Suggest mode. Analysis may propose actions, but no skill or playbook in this repository directly modifies a live Amazon Ads account.

Modes:

1. Read-only — inspect and explain data.
2. Suggest — generate recommended actions without applying them. Default.
3. Shadow — simulate actions for review/backtesting.
4. Execute — only after explicit authorization; hand validated actions to an external connector/executor.

Safety rules

• Skill-eval trigger observation integrity (v2.6.0): In the read-only paired effectiveness summarizer, a supplied non-null trial.triggered must be a real boolean on measured and non-measured trials alike. Reject strings, numbers, arrays, objects and placeholders instead of silently dropping them from the trigger-rate denominator. Missing/null remain unmeasured, not false/zero. Report trigger_observed_count alongside trigger_rate and trial_count to expose partial coverage; the rate is computed only from comparable measured pairs with boolean trigger observations. This does not prove external harness provenance, full discovery coverage, causal lift, or live Amazon Ads write authority.
• Single-run Skill-eval identity integrity (v2.5.0): The read-only paired summarizer must not report Measured from missing, malformed, padded or whole-label unresolved benchmark/skill/fixture/model/runtime/evaluator identity, invalid evaluation mode, or a malformed supplied non-null config/tool/evidence hash. Require concrete declared identity, not a repeated Unknown/Partial/N/A placeholder. Preserve omitted/null optional hashes, explicit null no-rubric, legitimate opaque identifiers, paired measurements and missing ≠ zero. This checks only internal claims, not external harness authenticity, statistical significance or live Ads write authority.
• Skill-effectiveness resource metric integrity (v2.4.0): The read-only paired summarizer rejects present malformed tokens (must be a non-negative integer, not bool/float/string/NaN/Infinity) and latency_ms (finite non-negative number, not bool/string/NaN/Infinity), including excluded scorer/harness trials. Missing and explicit null remain unmeasured, never zero. Prevent invalid means, silent omission of supplied invalid values and non-standard JSON; do not claim statistical significance, authentic external harness provenance, or live Ads write authority.
• Global Skill-effectiveness trial execution identity (v2.3.0): scripts/summarize_skill_effectiveness.py rejects duplicate trial_id anywhere in one paired benchmark, even across distinct pair_id values, opposite variants, or scorer/harness/insufficient-evidence trials. One execution is not two independent samples; reject ambiguous reuse rather than inflate pair counts or coerce excluded evidence to zero. Preserve distinct IDs, paired variants, explicit null non-measured outcomes, and read-only evaluation. This checks declared identifiers, not whether two distinct IDs actually represent independent model executions or statistically significant lift.
• Skill-effectiveness longitudinal identity integrity (v2.2.0): Equal placeholder or malformed measurement identities are not proof of comparable Skill results. For scripts/evaluate_skill_effectiveness_comparability.py, treat whole-label Unknown/Partial/Missing/Unsupported/Unavailable/Not Available/Not Supported/Not Applicable/N/A, non-string and padded values as Unknown across fixture, model, harness, config, tools, evidence and evaluator/rubric identity. Preserve valid opaque IDs containing such words, actual concrete mismatches as Not Comparable, and explicitly null rubric_version as a valid no-rubric declaration. No source authentication, statistical causal claim, Amazon Ads write or new Skill follows; read-only evaluation only.
• Explicit Stream v1/v2 dataset identity parity (v2.1.0): A resolved v1 or v2 source explicitly supplying stream_dataset must use a concrete, unpadded non-placeholder string. Null, blank, non-string, whole-label Unknown/Partial/Missing/Unsupported/Unavailable/Not Applicable remain Unknown, even with Verified reconciliation. Correctly normalize whitespace, hyphens and underscores without consuming literal letters (the prior regex incorrectly consumed 's'). Preserve omitted legacy metadata and opaque concrete labels. This is internal read-only consistency, not source authentication, complete delivery, causal lift or live Ads write authority; external authorized Connector/Executor owns ingestion and mutations.
• Stream v1 delta delivery and idempotency (v2.0.0, breaking): Deprecated Marketing Stream v1 sends incremental changes and requires consumer deduplication by idempotency_id. The read-only scripts/evaluate_metric_aggregation_gate.py returns Unknown for v1 additive/disjoint summation unless stream_delta_reconciliation contains exactly idempotency_id_coverage, idempotency_id_deduplication, and delivery_window_coverage, all Verified. Missing/Partial/Unknown/malformed proof cannot become zero or Allowed. Legacy v1 stream_reconciliation_status intentionally changes from Not Applicable to Unknown or Verified; downstream callers must migrate. V2 uses highest-version-per-record selection instead; never cross-apply proofs. This is an internal read-side declaration check, not independent source authentication, complete history, causal lift or live Ads write authority. External authorized Connector/Executor owns ingestion, retries, deduplication, reconciliation and mutations.
• Stream v2 explicit dataset identity (v1.116.0): When a resolved Stream v2 source explicitly supplies stream_dataset, null, non-string, blank, padded, or whole-label Unknown/Partial/Missing/Unsupported/Unavailable/Not Applicable cannot support Verified additive summation. Return Unknown, never zero. Omitted legacy dataset and concrete opaque labels remain compatible. This is internal read-only evidence validation, not source authentication, complete delivery, causal lift or live Ads write authority; the external authorized Executor owns mutations.
• Unproven extra direct arrays in observed SP rule events (v1.115.0): For positive mid-window Sponsored Products schedule/event/budget rule transitions, the optional rule_collection_evidence certifies only schedule_rules/event_rules or active_budget_rules. Reject any other direct array in either event-side rule state as Unknown, even if empty or repeated. Existing descendant JSON-pointer proof cannot certify a sibling direct array. Preserve valid rule collections, scalar extra evidence and non-exhaustive legacy event compatibility. This is internal read-only consistency, not authenticated source data, full-window event capture or Ads write authority.
• Unproven non-rule SP event arrays (v1.114.0): Positive mid-window Sponsored Products targeting_or_routing and audience_bid_adjustment events cannot promote unproven direct routing arrays or nested routing/audience arrays (including empty lists) to verified competing-control evidence. Return Unknown on either phase; preserve valid scalar routing and flat audience transitions. Existing endpoint completeness helpers apply. This does not prove source authenticity, full-window coverage or live Ads write authority.
• Optional paired SP rule-event descendant pointer proof (v1.113.0): A positive mid-window SP schedule/event/budget rule transition with nested member arrays may provide rule_descendant_collection_evidence with independent before/after RFC 6901 JSON Pointer maps rooted at each event-side state. Require the outer rule_collection_evidence and exact coverage of every descendant list (including empty arrays); each pointer must have Complete enumeration, Complete pagination and Supported capability with no extra fields or unmapped pointers. One-sided, partial, malformed or invented paths return Unknown. Omitted descendant proof retains the v1.112.0 conservative Unknown for nested arrays; flat legacy events remain compatible. This is normalized read-only evidence, not Amazon-native schema, source authentication, complete event-history proof or live Ads write authority.
• Mid-window SP rule descendant completeness (v1.112.0): A Complete rule_collection_evidence declaration only covers the outer schedule/event/budget rule list, never arrays nested inside a rule member. On positively observed SP bid/budget control_events, fail closed to Unknown for any nested list descendant (including empty) without independent evidence; the current event contract cannot carry descendant JSON-pointer proof. Reuse the endpoint deep-list guard, preserve valid flat rules and optional legacy outer proof, and never infer full-window capture, zero or Ads write authority.
• Optional paired mid-window SP rule collection proof (v1.111.0): A positively observed rule/budget control_events transition may supply rule_collection_evidence with independent before and after completeness declarations for schedule_rules/event_rules or active_budget_rules. When supplied, both phases must name every relevant collection and each must state Complete enumeration, Complete pagination and Supported capability. Partial, truncated, unsupported, malformed, one-sided or unmapped proof returns Unknown; a complete declaration permits the already-valid observed transition but does not authenticate its source or establish full-window event-log coverage. Omitted proof preserves legacy non-exhaustive behavior, never proof of continuity. No new Skill, dependency or live Ads writes; external authorized Executor owns mutations.
• Unmapped Sponsored Products placement evidence (v1.110.0): For registered SP bid/budget causal surfaces, endpoint and positively observed mid-window placement states must contain only the three supported normalized placement keys (top_of_search, rest_of_search, product_pages) plus optional amazon_business. Extra adapter keys are unmapped material-control evidence, not verified new placement dimensions or a confounder: return Unknown, even if the extra key is repeated in both readbacks. Keep measured zero/false separate from missing, preserve valid Amazon Business evidence, and require a dated adapter/registry contract before recognizing new keys. This does not prove full-window capture or authorize Ads writes; only the external authorized Executor may mutate accounts.
• Intervening SP rule activation evidence parity (v1.109.0): For positively observed mid-window control_events on registered Sponsored Products bid/budget causal surfaces, a shared rule_id in schedule/event bid rules or active budget rules must have paired presence of optional activation_status and activation_effective_at in event before_state and after_state. One-sided metadata is missing evidence, not a verified transition: return Unknown, never infer inactive/zero. Reuse endpoint identity-keyed parity; preserve both-absent legacy metadata, valid status/time changes, and genuinely added/removed rule identities. This is not complete event capture, continuous rule-execution proof, Amazon API-native schema, or Ads write authority. Read-only/Suggest/Shadow; external authorized Executor owns live mutations.
• Co-observed SP routing/placement coherence (v1.108.0): For positive mid-window control_events on registered SP bid/budget surfaces, two different controls sharing one concrete source.readback_id represent a co-observed state. Reject a before/after phase combining targeting_or_routing.retailer_scope=ACROSS_RETAILERS with placement_adjustment.amazon_business as Unknown, consistent with the endpoint invariant. Do not join different or missing readbacks merely because timestamps coincide; retain valid Amazon Store/business combinations and non-exhaustive event compatibility. This is internal read-only evidence consistency, not Amazon API payload authentication, full-window proof or live-write permission.
• Intervening event observation collision guard (v1.107.0): A concrete event source readback_id cannot represent different exact UTC event instants (including nanoseconds). Two positively observed rows for the same material control at the same instant cannot assert incompatible before/after transitions; return Unknown instead of a fabricated Confounded or Treatment Isolated. Preserve multiple different controls in one readback, equivalent timezone offsets, distinct event readbacks, identical duplicate deliveries, and optional missing readback IDs. Do not demand a contiguous event-state chain from an explicitly non-exhaustive log or claim full-window capture. Read-only/Suggest/Shadow; external authorized Executor owns live Ads writes.
• Explicit nested null material-state evidence (v1.106.0): Complete/observed endpoint controls and positively observed mid-window control_events cannot treat an explicit JSON null inside material state objects/lists as stable or changed evidence. Return Unknown; preserve real zero/false, omitted optional fields, and optional null metadata outside state. This is read-only internal evidence validation, not authenticated full-window control history or live Ads write authority.
• Intervening SP optional budget evidence parity (v1.105.0): For registered Sponsored Products bid/budget reviews, a positively observed mid-window control_events budget transition cannot compare an optional base/effective daily budget or average-daily-budget policy present on only one event side. Return Unknown rather than manufacturing a Confounded or Treatment Isolated judgment. On bid surfaces, both-absent optional fields remain legacy-compatible; budget-change surfaces still require the full budget state. Preserve the existing positively observed Amazon Business placement addition/removal as a confounder rather than misclassifying it as unknown. No full-window event coverage, API authentication or Ads write permission follows.
• Intervening SP budget/routing event-value gate (v1.104.0): On registered Sponsored Products bid/budget causal surfaces, positively observed control_events must not bypass endpoint-supported budget amount/policy or site/retailer routing semantics. For a budget-change surface, require complete normalized base/effective daily budgets, active budget-rule list and policy in each event-side budget state. On a bid-change surface, retain legacy partial budget shape but reject any explicitly invalid amounts/policy. Reject unknown site restrictions, invalid retailer scopes, across-retailers plus Amazon Business exclusive routing, one-sided retailer-scope transition evidence and non-scalar labels as Unknown. Do not convert missing/partial/unsupported/unknown to zero. Valid event changes remain confounders or treatment evidence only under existing guards; no complete history/source authentication or Ads write authority follows.
• Observed SP intervening event value integrity (v1.103.0): A positively observed mid-window control_events record cannot bypass the existing Sponsored Products bid, video, placement, audience or bidding-strategy value semantics merely because its evidence_status is observed. Reject invalid/non-numeric/negative/boolean modifiers, incomplete placement surfaces, duplicate/unusable audience members and unrecognized or invalid rule-based bidding guardrails as Unknown, not Confounded or Treatment Isolated. Valid decimal strings, observed zero, supported bidding aliases and actual competing changes remain compatible. These are normalized read-side checks, not Amazon API event schemas, full-window event coverage, source authentication or live-write authority.
• Observed intervening material-control events (v1.102.0): Two complete endpoint readbacks cannot establish continuous rule/budget/placement stability. When a post readback explicitly supplies control_events, require each event to have concrete unique identity, the same account/campaign/source scope, a known-offset RFC3339 instant strictly inside the baseline/post window, positively observed evidence, registered material control type and usable different before/after states. A positively observed competing mid-window transition is Confounded even if the control later reverted; malformed, source-mismatched, reused readback, out-of-window or unsupported events are Unknown. Omitted/empty optional events retain endpoint-only compatibility but are never proof of exhaustive event capture or uninterrupted control execution. This is normalized read-side evidence, not an Amazon API event schema, source authentication, attribution proof or live Ads write permission.
• N/A material state and member evidence (v1.101.0): A complete/observed material-control inventory cannot treat whole-label N/A or Not Applicable (including whitespace/hyphen/underscore variants) as a known control state, nested value, schedule/event/budget rule_id, or audience identity. Return Unknown, never Treatment Isolated/Comparable. Valid opaque strings containing these substrings, genuine zero/false and real confounders remain compatible. This read-only sentinel gate does not authenticate raw Amazon Ads API observations, prove continuous rule activation or permit live writes.
• Reused readback transition provenance (v1.100.0): A reused concrete source.readback_id must not carry contradictory per-control transition_provenance (management mode, actor, actor-evidence status, reason, or transition-observed instant). One-sided provenance is unresolved. Compare supplied known-offset RFC3339 instants in exact UTC time, including nanoseconds. Return Unknown, not Comparable. Distinct readbacks, both-absent/null legacy provenance and offset-equivalent times remain compatible. This read-only consistency gate does not prove external actor identity, full-window rule execution, or authorize Ads writes.
• Scope/source N/A identity guard (v1.99.0): A repeated whole-label N/A or Not Applicable (including whitespace, underscore or hyphen variants) cannot certify marketplace, profile, campaign, entity, account, source-system, acquisition-channel or connector identity. Return Unknown rather than Treatment Isolated or Comparable. Preserve valid opaque identifiers containing these substrings. This read-only check is not external source authentication, continuous control-history proof or Ads write permission.
• Reused readback control-evidence integrity (v1.98.0): A concrete source.readback_id identifies one observation, so equal ID plus equal observed_at and equal control values is insufficient when the same control has contradictory effective_at or evidence_status. Compare known-offset RFC3339 effective instants in UTC with full fractional precision; one-sided null/missing effective time is unresolved. Distinct IDs, omitted/null legacy IDs, equivalent offset spellings and unchanged evidence remain compatible. This is internal read-only consistency, not authenticated Amazon Ads history, continuous-control proof or live write authority.
• Control readback observation provenance integrity (v1.97.0): Explicit non-null source.readback_id must be a concrete, unpadded string, not Unknown/Partial/Unsupported/Missing/Unavailable/Not Available/Not Supported/Not Applicable/N/A. A reused concrete readback ID must identify the same exact UTC observed_at instant (including fractional precision), even if controls happen to match. Null/omitted legacy IDs, distinct valid IDs and offset-equivalent instants remain compatible. This is internal evidence consistency, not authenticated Amazon Ads history, continuous-control proof or live write authority.
• Control-state readback identity reuse (v1.96.0): An explicit source.readback_id identifies one observed readback, not a reusable connector or campaign ID. When baseline/post reuse the same non-null ID but show different material control states, return Unknown, not Treatment Isolated/Confounded/Directional. Distinct IDs, legacy omissions and unchanged states remain compatible. This does not authenticate raw API responses, prove full-window history, or authorize Ads writes.
• Ready holdout explicit material re-verification chronology (v1.95.0): When comparison.boundary_monitoring.material_scope_changes[].reverified_at is explicitly supplied, require a known-offset RFC3339 instant and exact UTC ordering change.timestamp <= reverified_at <= latest_verified_at. Explicit null/Unknown, unknown offsets, before-change or after-latest timestamps are unresolved, never proof of a clean boundary. Omitted legacy reverified_at stays optional; the existing reverified: true requirement remains. This does not authenticate external control history, guarantee full-window coverage, or authorize live Amazon Ads writes.
• Ready holdout exact fractional chronology (v1.94.0): Preserve every supplied RFC3339 fractional-second digit when ordering Ready holdout launch/latest boundary checks, positively verified isolation proof, and material scope changes. Python datetime.fromisoformat truncates beyond six digits; compare UTC whole seconds plus the original exact fractional part instead. A 100-nanosecond-later proof/change cannot be treated as simultaneous with a clean check. Preserve known-offset format validation, optional legacy omissions, and exploratory states. Internal chronology is not authenticated full-window Amazon Ads control evidence or write authority.
• Ready holdout latest-monitoring chronology: When supplied, comparison.boundary_monitoring.latest_verified_at cannot predate any valid, positively verified comparison.isolation_evidence[].verified_at. Compare UTC instants, not timestamp strings. Omitted optional legacy fields, unverified evidence and exploratory plans retain compatibility. This internal record check cannot authenticate external source evidence, prove full-window rule execution or grant live Amazon Ads write authority.
• Ready holdout verification timestamps: Ready holdouts require known-offset RFC3339 verification instants (T separator, optional fractional seconds, Z or ±HH:MM) for supplied boundary latest/launch verification, material-change timestamps and verified isolation timestamps. Reject -00:00, space separators and second-resolution timezone offsets. Preserve valid offset chronology, optional legacy omissions and exploratory plans. This is internal evidence consistency, not external authentication, continuous-control proof or live Ads write permission.
• A Ready combined readout and standalone direct-sum gate must reject additive or non-additive-deduplicated declarations for explicitly named Amazon Ads benchmark purchase/add-to-cart/detail-page-view/branded-search rates, cost per purchase/detail-page view, and percent of purchases new to brand. These are derived numerator/denominator metrics (Amazon Ads benchmark reporting, updated 2026-10-06), not directly summable counts. Preserve additive Purchases/Impressions, exploratory and non-combined plans, omitted legacy standalone names, and valid ratio-derived semantics. This is bounded internal metadata contradiction detection, not source authentication, denominator completeness, cross-product attribution or permission for Amazon Ads writes.
• A Ready experiment with comparison.requires_combined_readout=true must have concrete, unpadded primary and guardrail metric names. Whole-label Unknown/Partial/Missing/Unsupported/Unavailable/Not Available/Not Supported/Not Applicable/N/A, blanks and non-string names cannot authorize a combined decision merely because aggregation semantics are declared additive or ratio-derived. Concrete labels containing these words as substrings remain valid. Non-combined Ready and exploratory plans retain legacy compatibility. This is internal metric-identity consistency, not raw Ads source authentication, denominator proof, causal attribution or write permission.
• For a Ready experiment, explicitly supplied comparison.requires_combined_readout must be a genuine JSON boolean (true or false), not null, Unknown, Partial, numeric, list, or object. Explicitly unresolved readout necessity cannot bypass the combined-readout ratio/derived KPI consistency gate. Omitted legacy fields, genuine false, and exploratory Shadow/Hold/Redesign plans retain compatibility. This check does not infer actual cross-campaign joins, authenticate source data, or grant live Amazon Ads write authority.
• The standalone read-only aggregation gate distinguishes an omitted optional metric_name from explicitly unresolved identity. With additive semantics, explicit null, blank, whole-label Unknown/Partial/Missing/Unsupported/Unavailable/Not Available/Not Supported/Not Applicable/N/A or non-string metric names cannot authorize direct summation even if rows are declared disjoint; return Unknown. Concrete names containing these words as substrings and omitted legacy names retain ordinary checks. This is not source authentication, denominator proof, causal attribution, or Ads write permission.
• A Ready holdout must distinguish an omitted optional comparison.boundary_monitoring from an explicitly supplied unresolved value (null, scalar, or list). If monitoring is supplied, it must be an object; explicitly supplied launch_verified_at must be a timezone-aware valid instant, and explicitly supplied material_scope_changes must be an array (possibly empty). Missing optional fields preserve legacy compatibility; Shadow Only/Hold/Redesign may preserve unknowns. This is read-only record consistency, not proof of continuous delivery, external authentication, or live Ads write authority.
• Canonical cost/return ratios CPA (cost per acquisition/action), CPM (cost per thousand impressions), vCPM (viewable CPM), and ROI (return on investment) are derived KPIs, not additive quantities. Both scripts/evaluate_metric_aggregation_gate.py and Ready combined experiment validation must reject additive or non_additive_deduplicated claims for these bounded whole-token names. Preserve existing ROAS/ACOS/TACOS/CVR/CTR/CPC checks, additive Spend/Impressions, legacy unnamed calls, exploratory and non-combined plans. This is a narrow metadata contradiction check, not proof of source authenticity, compatible denominators, conversion attribution, incremental profit, or live Ads write authority.
• The standalone read-only scripts/evaluate_metric_aggregation_gate.py must not authorize direct summation when a supplied metric_name is a bounded canonical ratio KPI (ROAS, ACOS, TACOS, CVR, CTR, CPC) but metric_semantics.aggregation_semantics incorrectly claims additive. Return Blocked for this contradiction; keep unknown semantics Unknown and existing unnamed callers compatible. A name check is not source authentication, denominator completeness, safe recomputation, or Ads write permission. Preserve 15 Skills and external authorized Executor.
• A Ready experiment must not infer ad-attributed conversion semantics solely from the substring "sale" inside a non-ad retail or unrelated metric name. Whole, unambiguous Total Retail Sales, Retail Sales, Organic Sales, and Sales Rank are not ad-attributed conversion measures, and Wholesale Traffic is not a sale metric. Bare/ambiguous Sales or Total Sales, explicit Ad-Attributed Sales, Purchases, and any explicitly declared conversion family retain attribution-family/version checks. Apply to primary and guardrail metrics. This narrow name-boundary correction does not authenticate retail source/grain/date, prove incrementality, convert missing values to zero, or grant Ads write authority.
• A Ready experiment with comparison.requires_combined_readout=true cannot claim canonical ratio KPIs (ROAS, ACOS, TACOS, CVR, CTR, CPC) are additive or non_additive_deduplicated. For bounded metric names, require metric_semantics.aggregation_semantics=ratio_or_derived for primary and decision-driving guardrail metrics. This is a narrow contradiction check: it does not compute ratios, prove source disjointness or complete denominators, unify TACOS with ad-attributed ACOS, infer missing data as zero, or grant live Ads write authority. Other additive metrics, non-combined and exploratory plans retain compatibility.
• A Ready experiment cannot bypass conversion attribution identity by labeling ACOS, CVR, attributed orders/units, or units sold as traffic/Unknown. The metric-name gate complements Purchases/Sales/ROAS and requires concrete conversion family, attribution family and semantic version for both primary and guardrail metrics. Use token boundaries for ACOS/CVR so TACOS (ad spend / total retail sales) is not automatically equated with attributed ACOS. Do not infer all total retail orders are ad-attributed. Exploratory plans and actual non-conversion metrics remain compatible; this is internal read-only consistency, not external reporting authentication or Ads write authority.
• A Ready experiment cannot bypass conversion metric attribution requirements by declaring an obvious Purchases/Sales/ROAS primary metric or guardrail as a non-conversion/Unknown metric_family. The semantic validator must detect the conversion display name independently, require a concrete conversion family and resolved, unpadded attribution_family / semantic_version; whole-label Unknown/Partial/Missing/Unsupported/Not Applicable is not a resolved semantic identity. Do not infer a universal Amazon API schema from this repository guard; non-conversion and exploratory plans remain compatible. This adds no remote source authentication or live Ads write authority.
• A Ready holdout cannot treat isolation_evidence[].verified: true plus a whole-label Unknown/Unsupported/Partial/Missing/Unavailable/Not Available/Not Supported, blank or whitespace-padded evidence as verified isolation. When source or verified_at is explicitly supplied on a verified item, require a concrete unpadded source and timezone-aware timestamp; explicit null/invalid optional fields remain unresolved. Omitted optional fields preserve legacy Ready compatibility; Shadow/Hold/Redesign can retain unknowns. This is a read-only evidence-consistency check, not independent remote delivery authentication, Amazon-native entitlement, causal proof or write permission.
• When a Ready holdout explicitly supplies comparison.boundary_monitoring, require current_status = Clean and a valid timezone-aware latest_verified_at even without material changes. Optional launch_verified_at must be valid and at or before the latest verification. Missing/unknown status, absent/invalid latest verification and impossible launch chronology cannot prove monitored isolation. Absent monitoring remains legacy-compatible; Shadow/Hold/Redesign may retain unresolved evidence. This is an internal read-only consistency gate, not continuous-control proof, external delivery authentication or Ads write permission.
• A Ready holdout with recorded comparison.boundary_monitoring.material_scope_changes requires each material change to have explicit boolean reverified: true, in addition to the existing latest-verification chronology and Clean boundary status. Missing, null, false, numeric or string claims are unresolved and must not be promoted to Ready merely because latest_verified_at is later. Exploratory Shadow Only/Hold/Redesign can retain incomplete records; this is a repository-owned evidence gate, not independent Amazon Ads delivery authentication or write permission.
• A Ready experiment plan requires concrete, unpadded marketplace/profile/entity-type and treatment entity identities. Whole-label Unknown/Unsupported/Partial/Missing/Unavailable/Not Available/Not Supported are unresolved evidence, never valid scope. Reject duplicate treatment IDs and, when comparison.control_entity_ids is supplied, unresolved/duplicate control IDs or exact treatment/control overlap; valid opaque IDs containing these substrings remain valid. Unresolved exploratory Shadow Only/Hold/Redesign plans remain representable. This is repository-owned read-only readiness validation, not Amazon-native ID syntax, holdout delivery verification or live Ads write permission.
• For registered Sponsored Products bid/budget causal comparisons, complete, identity-verified schedule_rules, event_rules, and active_budget_rules are sets keyed by unique concrete rule_id, not ordered histories. The comparator may ignore member enumeration order only for these three validated collections when comparing control state; it must still detect changed member fields, additions/removals, activation changes, invalid/duplicate/one-sided evidence, and changes in other material arrays. Equal rule sets do not prove continuous execution, full-window trigger coverage, eligibility, raw source authenticity or causal lift. No Ads write authority is added.
• Feature-specific eligibility source independence covers capability-level evidence[].reference as well as binding IDs, surface IDs and binding-level probe references across all observed connector capabilities (including non-required/Unsupported). Reusing any of these normalized probe references cannot prove Eligible or Ineligible and degrades to Unknown. A distinct label is not external response authentication, advertiser entitlement, causality or write authority; 15 Skills and external Executor boundaries remain unchanged.
• Feature eligibility source independence applies across all observed connector capabilities in the same snapshot, not only the current decision's required IDs. A feature-specific source_reference colliding with any binding ID, surface ID or supporting probe reference (including unrequired, Unverified or Unsupported capability probes) cannot prove either Eligible or Ineligible; degrade to Unknown. Required-capability access checks remain unchanged. Different references are only a narrow consistency check, not raw HTTP authentication, entitlement verification or write authority.
• Feature eligibility source-reference independence must compare against all bindings on each required connector capability, including Unverified/Unknown/Unsupported probes, not only Verified read-side bindings. A reused binding ID, surface ID or supporting evidence reference is not independent entitlement proof even when another binding legitimately verifies connector access. Both Eligible and Ineligible self-references degrade to Unknown; distinct references remain only a narrow consistency check, not raw Amazon API authentication. This adds no write authority.
• For registered Sponsored Products bid/budget causal comparisons, both control-state snapshots must carry a concrete scope.campaign_id in addition to existing marketplace and account identity evidence. Two omitted/null campaign IDs cannot establish the same campaign, even if the profile and all observed controls match; classify as Unknown, not Treatment Isolated or Comparable. Other registered surfaces retain their existing scope contract. This is a read-only identity guard, not an Amazon-native schema, eligibility proof, continuous-rule-history proof or write permission.
• Feature-specific eligibility is not independently evidenced when its source_reference exactly repeats a Verified required connector binding's binding_id, surface_id, or supporting evidence.reference. This self-reference yields feature_source_independence_effect=unknown and degrades the feature decision (including a self-referential Ineligible claim); unrelated capability references are not compared. A distinct label only passes this narrow consistency check and never authenticates raw Amazon Ads HTTP, proves feature enrollment or grants write authority. Keep 15 Skills and external Executor boundary intact.
• When a named feature eligibility decision declares as_of, a connector capability snapshot captured after that decision instant cannot prove read-side coverage as of the earlier time. Missing/invalid/unknown-offset capture is also Unknown: feature_snapshot_chronology_effect=unknown degrades the final gate unless another independent block applies. Equal/earlier capture only passes chronology, not entitlement, freshness, or source authenticity. Do not reuse the eligibility evidence TTL as a connector TTL; explicit connector freshness and supporting binding timestamps remain independent. Calls without a feature requirement remain compatible. No Amazon Ads writes are authorized.
• Connector capability and exact advertiser/campaign scope do not establish feature enrollment. For a decision requiring a named feature, provide a concrete feature_eligibility_requirement matching the exact expected_scope advertiser/campaign/marketplace and a separately supplied feature-specific Verified eligibility record with concrete source/reference and valid observation time. Verified Eligible can pass the eligibility subgate only alongside all connector checks; Verified Ineligible blocks; missing, partial, unknown, stale, future, generic product-group, unverified or mismatched records degrade. Never equate Amazon Ads advertiser product-group eligibility with Amazon Business exclusive campaign enrollment, infer absent metrics as zero, or treat a normalized Verified label as authenticated raw API proof. No live Ads writes or external Executor behavior is introduced.
• An explicitly observed connector access_mode=observe may pass only when the required capability is declared observe by the canonical catalog and an independently Verified binding, concrete source/scope and all other data/freshness gates pass. Observation-only access cannot substantiate read/report capabilities or grant Amazon Ads write authority. Write-only stays Blocked; mixed/unknown stay Degraded. This is a repository-owned read-side evidence contract, not Amazon-native permission or proof of metric completeness.
• When a decision depends on an exact advertiser account or campaign, set expected_scope.advertiser_account_id and/or campaign_id and require a concrete matching scope.advertiser_account_ids / campaign_ids on both the capability and an independently Verified binding. These opaque IDs compare case-sensitively; same marketplace/ad product does not prove same account/campaign. Missing scope never implies global coverage; Unknown/Partial membership is not zero or verified exclusion. Legacy requests without exact identity scope remain compatible. This is read-side provenance only, not advertiser/campaign feature eligibility, raw HTTP authentication, live delivery or write authority.
• For Global Sponsored Products campaign readback, an echoed placeholder or whitespace-padded global-account, campaign, explicit request, connector-source, or raw marketplace crosswalk identity cannot establish a verified post-write match. Return Unknown, not Confirmed, even when the request, 207 receipt, state and budget rows repeat the same unavailable label. Whole-label Unknown/Unsupported/Partial/Missing/Unavailable/Not Available/Not Supported are unusable; legitimate IDs containing those substrings remain valid. Legacy country-code-only and index-only receipts remain compatible. This is repository-owned evidence validation, not an Amazon-native ID grammar, proof of marketplace/advertiser eligibility, raw HTTP authentication or permission to execute.
• A reporting generation declared active or sunset_scheduled with a sunset_at earlier than the same connector snapshot's captured_at has unreconciled lifecycle evidence. When that generation is required, return data_contract_effect=unknown / Degraded, not high-confidence Pass. This does not assert that the report was retired, that Amazon's planned dates cannot change, or that unavailable metrics are zero. Future/equal sunsets, explicit retired blocking, and no-generation requirements retain their existing behavior. All dates are compared as offset-aware instants; actual Ads writes remain outside this repository.
• For an exact history-window requirement, an observed per-grain available_through more than one calendar day beyond the connector snapshot capture cannot prove already available history. Degrade to Unknown rather than high-confidence Pass, even if requested dates precede capture. The one-day allowance is only for date-only bounds without marketplace timezone, not an Amazon latency SLA or proof of data maturity. Never infer zero or authorize live Ads writes.
• A requested historical reporting history_window.grain must be concrete and unpadded; matching Unknown/Unsupported/Partial/Missing/Unavailable/Not Available/Not Supported labels do not prove historical availability. A padded connector-observed matching grain, including alongside a concrete match, is ambiguous and degrades rather than passing. Preserve valid case-insensitive grains and verified dates; do not infer metric zero, per-metric history, API entitlement or write authorization.
• A reporting-generation requirement must name a concrete, non-placeholder, unpadded identity. Repeating Unknown or Unsupported on both sides is not verified reporting-generation comparability. A connector-observed generation that is missing, placeholder, or whitespace-padded degrades to Unknown rather than asserting a real generation mismatch or matching it. Valid concrete generations still match case-insensitively; a concrete mismatch blocks. This is a repository-owned read-side provenance rule, not an Amazon API enum, permission to write, or proof of source authenticity.
• An observed, nonempty connector scope list with unmatched Unknown/Partial/malformed members yields scope_effect=unknown and a Degraded, not Blocked, final capability gate: unknown membership cannot prove exclusion. An omitted/empty/unbounded capability scope remains Blocked (no global assumption); a fully concrete unmatched scope also remains Blocked. A concrete match can pass the scope preflight subject to verified binding and all other gates. Do not infer marketplace/advertiser/campaign eligibility, actual delivery or write authorization from this distinction.
• A requested connector decision scope must be a concrete identity, not a repeated Unknown/Unsupported/Partial/Missing/Unavailable/Not Available/Not Supported label or whitespace-padded string. For a capability or verified binding scope, a matching concrete member proves only that bounded connector surface; an unmatched list containing an unavailable/malformed member is Unknown, not proof of marketplace, ad-product, region or account-type exclusion. A fully concrete unmatched list remains blocked. No scope list alone establishes Amazon Business advertiser/campaign eligibility, account entitlement, actual delivery, or authority to write.
• A Supported/Verified read capability must also have a concrete snapshot-level connector_id. A missing, blank, placeholder (Unknown/Unsupported/Partial/Missing/Unavailable/Not Available/Not Supported) or whitespace-padded connector identity degrades the entire decision, even with multiple valid bindings. Optional source_system and acquisition_channel may be omitted for legacy snapshots, but when explicitly provided they must be concrete identities, not null/placeholder/whitespace-padded values. This is a repository-owned read-side provenance check, not authentication of remote API responses, proof of account eligibility, or permission to write.
• A Supported connector capability with a Verified binding still needs a concrete read-side access_mode. A write-only capability is Blocked; mixed, unknown, missing, malformed or unsupported modes are Degraded. Only explicit read, report, export or stream access can pass the access-mode preflight, subject to other evidence gates. A second binding or snapshot default mode cannot override write-only access. This repository-owned read-side check does not authenticate remote tool behavior, grant write permission, or replace an authorized external Executor.
• A Verified connector binding is not independently identified by an unavailable placeholder in its binding ID, surface ID or supporting evidence kind/reference. Reject whole-label Unknown/Unsupported/Partial/Missing/Unavailable/Not Available/Not Supported and whitespace-padded verification identifiers before high-confidence Pass. A separate valid binding can still qualify; this does not authenticate remote responses, establish advertiser eligibility, or grant write authority.
• A connector capability marked Supported and a binding marked Verified do not override impossible chronology. Independently validate snapshot capture, binding verification, and explicitly dated supporting evidence even when no freshness horizon was requested. A future/malformed/unknown-offset binding or evidence timestamp is not a verified surface and must not produce high-confidence Pass. This read-side rule does not authenticate raw HTTP, confer platform entitlement, or authorize writes.
• Never invent missing advertising data, source lineage, optimization history, or action-sizing precision.
• Repeated Unknown/Unsupported/Partial/Missing/Unavailable/Not Available/Not Supported, blank or whitespace-padded labels are not valid marketplace, profile, campaign, entity, advertiser-account, connector, source-system or acquisition-channel identities. Reject before claiming causal isolation; do not equate a shared placeholder with a shared account or data lineage. Real observed IDs and both-absent legacy optional connector IDs remain supported. This is read-side validation, not an Amazon-native ID format or account-entitlement check.
• For every material control, even a non-registry extra control, an explicitly observed state containing an exact missing/unknown/unsupported/partial/unavailable placeholder, a blank scalar string, or a non-finite numeric leaf cannot prove stability or treatment isolation. Reject such evidence recursively without turning it into zero, False or an absent control. Valid observed zero, boolean switches, descriptive values and verified complete collections remain usable; this is a repository-owned read-side check, not an Amazon API enum or a substitute for control-specific capability and eligibility proof.
• Do not recommend aggressive bid/budget changes when sample size is insufficient.
• A raw economic or directional estimate is not automatically an action-safe final magnitude; require an explicit account/caller policy, calibrated response, defensible marginal headroom, experiment design, or another auditable sizing basis for a concrete proposed value.
• Check marketplace, profile/account scope, currency, timezone, attribution window, date range, promotion context, data freshness and source comparability before high-confidence recommendations.
• Treat extracted_at and available_through as different concepts; a freshly fetched downstream table may still be incomplete for recent event dates.
• For registered Sponsored Products bid/budget causal comparisons, bidding_strategy must use a recognized source-supported normalized strategy. Simple dynamic_down_only, dynamic_up_and_down and fixed string labels (hyphen variants allowed) are supported. Rule-based bidding requires a structured state { "strategy": "rule_based", "roas_guardrail": 3 } with a finite, strictly positive observed ROAS ratio; a bare rule_based label, unknown guardrail or unverified extra rule fields cannot prove treatment isolation. This rule-based ROAS guardrail is distinct from schedule/event bid-rule lists. These are repository-owned read-side labels, not Amazon-native API enums or proof of activation, eligibility or actual auction bids.
• For registered Sponsored Products bid/budget causal comparisons, a complete audience_bid_adjustment list must contain unique nonblank audience_id identities and finite nonnegative bid_boost values. Missing, duplicate, malformed, unknown or unsupported members cannot prove treatment isolation. This is a repository-normalized read-side contract, not an Amazon API payload.
• For registered Sponsored Products bid/budget causal comparisons, base_bid must be an observed finite nonnegative numeric value or plain decimal string; Unknown/Unsupported/Partial, booleans, negative/non-finite values, percentages and structured placeholders are not valid bid evidence. This is not a universal platform bid-minimum/maximum claim.
• For Sponsored Products bid/budget causal comparisons, video_bid_adjustment must be a source-supported finite nonnegative numeric observation (or plain decimal string), not Unknown/Unsupported/Partial, a boolean, a percent string, or a non-finite value. The comparator does not establish marketplace eligibility or an exact platform upper bound.
• For Sponsored Products causal comparisons, an explicitly supplied Amazon Business placement bid modifier is a distinct material placement value. Reject invalid/unknown/unsupported values and one-sided missing evidence; both-absent legacy snapshots do not prove B2B capability, ineligibility or zero. Verify account/marketplace/retailer scope independently before action-safe B2B conclusions.
• For registered Sponsored Products bid/budget causal comparisons, optional normalized targeting_or_routing.state.retailer_scope accepts only AMAZON_STORE or ACROSS_RETAILERS and must be present on both snapshots or neither. Across-retailers scope contradicts an explicitly supplied Amazon Business placement modifier (even numeric zero) or AMAZON_BUSINESS-exclusive site routing; return Unknown, not a stable/zero B2B control. Both-absent legacy scope remains compatible but does not prove retailer, marketplace, campaign or connector eligibility. These are repository-owned read-side labels, not Amazon-native API enums or verified delivery.
• For registered Sponsored Products bid/budget causal comparisons, targeting_or_routing.state.site_restriction must be a source-supported recognized normalized routing label (ALL_ELIGIBLE or AMAZON_BUSINESS). Missing, unknown, unsupported, partial, malformed or unmapped site restrictions cannot prove stable delivery even when repeated in both snapshots. These repository-owned labels do not prove account/marketplace eligibility, connector completeness or Amazon-native enum equivalence; new modes require explicit adapter mapping and dated capability verification.
• For Global SP readback, accept only country codes explicitly supported by the current dated Amazon Global Sponsored Products guide. An unsupported/new code is Unknown until official eligibility is reverified; do not silently substitute UK for GB or a raw marketplace ID for a country code.
• When Global SP query page response bodies are explicitly retained, require complete per-page campaigns[] and nextToken evidence and exact one-page native campaign membership; contradictory or partial response evidence is Unknown. Legacy traces without response bodies are not independently authenticated.
• For optional Global SP native query-request evidence, validate exact campaign/product/scope filters and per-page continuation requests against the pagination trace; an echoed query fingerprint is not independent authentication. Incomplete or contradictory explicit request evidence is Unknown, never an inferred empty/zero result.
• Treat a time-varying platform capability as lineage-bearing evidence: if current official/API/account evidence materially conflicts or scope/supersession is unresolved, fail closed on the exact numeric rule instead of silently choosing a convenient percentage, limit or formula.
• Treat Prime Day, Best Deal, Lightning Deal, Coupon, Prime-exclusive promotions, stockouts, listing suppression, major price changes, and parent/variation-family retail changes as potential confounders.
• Before reversing or stacking another action on the same entity, check whether a recent action is still inside its validation window when history is available.
• Distinguish proposed, applied, readback confirmed, and worked; none of these imply the next stage automatically.
• If history is unavailable or partial, expose that limitation instead of treating the ledger as complete.
• Prefer Hold, Experiment Only, or Manual Review when application is unknown/drifted, evaluation is still pending, source comparability is unresolved, action magnitude lacks a defensible sizing basis, or a new action would contaminate an active experiment unless a safety guardrail triggered.
• Weekly reviews must include a hold list; do not force every material entity into an action.
• Do not place credentials, refresh tokens, client secrets, profile IDs, account IDs, or customer secrets in generated files or logs.
• Any Execute plan must include evidence, confidence, guardrails, validation window, and rollback criteria.
• A Rollback Candidate is a proposal only; this repository does not perform the rollback itself.
• For registered Sponsored Products bid/budget causal comparisons, a Complete schedule/event bid-rule or active budget-rule collection must also have usable member evidence: unique nonblank normalized rule_id and finite nonnegative observed bid_increase (schedule/event) or increase_percent (active budget). Missing, duplicate, unknown, unsupported, boolean, negative and non-finite member values are Unknown, not zero or unchanged. This is a read-side evidence contract, not an Amazon API payload, activation proof or bid-composition formula.
• For registered Sponsored Products bid/budget causal comparisons, an optional normalized schedule/event/active-budget rule member activation_status is accepted only as active, inactive, or scheduled; repeated Unknown/Unsupported, malformed or one-sided activation status on a shared rule_id is Unknown, not an unchanged control. Absence on both legacy snapshots remains backward-compatible but does not prove activation or continuous rule execution. This field is repository-owned read-side evidence, not an Amazon-native enum or a substitute for time-window proof.
• For the same SP rule members, an explicitly supplied optional activation_effective_at must be a timezone-aware RFC3339 transition instant no later than its snapshot's observed_at, paired with an explicit valid activation_status, and present on both snapshots for the same rule_id. Invalid, future, status-less or one-sided transition-time evidence is Unknown. A changed valid transition time is a competing control. Both-absent legacy evidence is accepted without claiming full-window execution, event-trigger or timezone coverage.
• Connector freshness requirements must use finite non-negative max_age_seconds; NaN, infinity or overflowing numeric horizons are invalid and must never bypass stale-evidence checks. This is an internal read-side invariant, not an Amazon Ads API TTL or permission to execute writes.

Shared references, playbooks and evals

• Weekly operating cadence: playbooks/weekly-review.md
• Metrics: references/amazon-ads-metrics.md
• Optimization framework: references/optimization-framework.md
• Decision boundaries: references/decision-boundaries.md
• Contextual action sizing: references/action-sizing.md
• Platform capability version/scope lineage: references/platform-capability-lineage.md
• Benchmark policy: references/benchmark-policy.md
• Optimization memory: references/optimization-memory.md
• Canonical data model: references/data-schema.md
• Source lineage and cross-source comparability: references/data-lineage.md
• Active MCP/connector capability evidence: references/connector-capability.md and schemas/connector-capability-snapshot.json
• Canonical connector capability IDs / Skill decision profiles: references/connector-capability-catalog.json
• Action proposal schema: schemas/optimization-action.json
• Action/readback/evaluation event schema: schemas/optimization-event.json
• Derived entity-history schema: schemas/entity-history.json
• Experiment plan schema: schemas/experiment-plan.json
• Historical replay framework: evals/README.md
• Eval-case schema: schemas/eval-case.json
• Paired Skill-effectiveness result schema: schemas/skill-effectiveness-benchmark.json
• Decision-time measurement-state projector: scripts/project_measurement_history.py
• Paired with/without-Skill benchmark summarizer: scripts/summarize_skill_effectiveness.py

Evaluation rules

When adding or changing decision logic, prefer adding a focused synthetic replay fixture for material failure modes.

• Keep deterministic contract checks separate from capability evals.
• Every fixture must remain valid under scripts/validate_evals.py: valid JSON, allowed contract fields/enums, collision-free ID, filename/ID alignment, and an existing repository-local entrypoint.
• Score decision behavior rather than exact prose.
• Use met, not_met, or insufficient_evidence; do not coerce missing evidence into pass/fail.
• A fixture may allow multiple conservative outcomes, but must list forbidden unsafe behaviors explicitly.
• Do not weaken a fixture merely because a current model fails it; change the Skill only when the fixture represents the intended behavior.
• Prefer synthetic identifiers and values. Never commit client/account secrets or proprietary exports as fixtures.
• Eval fixtures must remain closed-world by default and must not trigger live Amazon Ads writes.
• For important with-Skill / without-Skill comparisons, keep pair identity and harness/model/tool/evidence configuration aligned. scripts/summarize_skill_effectiveness.py fails closed on missing/duplicate pair variants and reports measured deltas only; it does not claim statistical significance.

Read-only repository utilities

The repository includes deterministic helpers for derived memory and evaluation summaries. These are not Amazon Ads executors.

• scripts/project_measurement_history.py reads an optimization-event slice from stdin and projects only the newest traceable evidence_snapshot into latest_measurement_state. It fails closed on requested scope mismatch, preserves unknown, retired_or_deleted and Not Comparable, and never converts unavailable history to zero.
• scripts/resolve_skill_capabilities.py resolves canonical required/optional connector capability IDs plus profile-owned data_requirements for a registered Skill decision profile and can merge explicit task-level constraints such as an exact history_window. Task requirements may only strengthen profile policy, must target a required capability, and retain profile/task provenance. Pass the merged requirements unchanged to the connector capability gate. It never calls a connector or grants write authority.
• scripts/evaluate_connector_capability_gate.py reads a connector capability snapshot plus required capability IDs from stdin and returns Pass, Degraded, or Blocked. It is read-only, never calls a connector, and enforces missing_evidence_policy = never_zero for Partial/Unsupported/Unknown/absent capability evidence. Optional per-capability data_requirements additionally gate exact reporting generation and history availability: retired/mismatched generations or unavailable/retired required history block; partial/unknown required history degrades rather than becoming zero. A task-level history_window checks exact start/end dates against the matching observed grain; no cross-grain coverage inference is allowed.
• scripts/evaluate_global_sp_readback.py classifies a single Global SP campaign-update 207 receipt against complete post-write per-marketplace configured-state readback. It is read-only; partialSuccess/error, incomplete pagination, missing marketplace/account/source evidence or ambiguous batches never become Confirmed. If the adapter explicitly retains native campaign monetary budgets, contradictory currency/amount/recurrence/marketplace evidence cannot confirm a requested daily monetary-budget update. See references/global-sp-readback-evidence.md.
• scripts/evaluate_global_sp_target_batch_readback.py conservatively classifies a single-call, homogeneous Global SP positive-target batch: full 207 index coverage, unique request/target identity and per-success independent query evidence are mandatory. Each item reuses the single-target readback gate. Only all-Confirmed items yield batch Confirmed; unknown evidence takes precedence over partial/drifted. No Ads calls, retries or Executor reconciliation. See references/global-sp-target-batch-readback.md.
• scripts/evaluate_global_sp_adgroup_bid_readback.py independently classifies one external Global SP ad-group update receipt against source-supported, complete per-marketplace native-currency default-bid query evidence. It requires explicit external request/receipt binding, account/campaign/ad-group identity, query capability, pagination, and freshness; it never performs Ads writes, retries, or target-bid verification. See references/global-sp-adgroup-bid-readback.md.
• scripts/evaluate_global_sp_adgroup_batch_readback.py verifies one homogeneous Global SP multi-ad-group update call with complete 207 index coverage, unique ad-group/request identities and independently complete per-marketplace native-currency default-bid readback for each successful item. Any ambiguous evidence returns Unknown, and no Ads write/retry/executor action occurs. See references/global-sp-adgroup-batch-readback.md.
• scripts/evaluate_global_sp_mixed_plan_readback.py classifies an externally asserted complete, single-account Global SP optimization plan across campaign/ad-group/target or homogeneous batch readback gates. It binds each manifest component and ordered request IDs, rejects repeated entities, forged component verdicts and unsupported plan intent, and never upgrades partial/unknown child evidence to whole-plan confirmation. The manifest's completeness/authenticity must be guaranteed by the external authorized Executor; this helper does not verify a plan ledger or perform writes/retries/reconciliation. See references/global-sp-mixed-plan-readback.md.
• scripts/evaluate_global_sp_target_bid_readback.py independently verifies one positive KEYWORD/PRODUCT target bid update in one Global SP marketplace, requiring target-specific identity, native-currency Decimal bid, bound 207 receipt, query freshness, completeness and connector evidence. It does not verify ad-group defaults, negative/THEME targets, auction outcomes, or batch writes. See references/global-sp-target-bid-readback.md.
• scripts/evaluate_metric_aggregation_gate.py is a read-only policy gate for direct summation. It permits a sum only when metric aggregation semantics are explicitly additive and source rows are explicitly disjoint; unknown semantics never default to additive, and non-additive de-duplicated or ratio/derived metrics are blocked from direct summation. When source identity resolves to Marketing Stream v2 (including a coherent generic Stream channel with stream_generation=v2), the same gate also requires independently verified full record-key coverage and highest streamBatch.version selection before aggregation; Stream v2 totals are not v1 deltas. For Stream v1, it instead requires verified idempotency_id coverage, deduplication and delivery-window completeness before summing deltas; missing proof now returns Unknown (v2.0.0 breaking migration).
• scripts/evaluate_skill_effectiveness_comparability.py compares two benchmark measurement identities before longitudinal interpretation. Fixture/evaluator/rubric/model/runtime/config/tool/evidence mismatches return Not Comparable; missing identity returns Unknown, never implicit comparability. It is read-only.
• scripts/summarize_skill_effectiveness.py reads benchmark trial records that conform to schemas/skill-effectiveness-benchmark.json. It validates paired with_skill / without_skill trials and reports counts/rates/deltas only from pairs where both arms were actually measured. Scorer/harness errors and insufficient-evidence arms exclude the whole pair rather than being imputed as zero quality. It does not call a model, invoke a live agent runtime, or mutate an advertiser account.

Actual model/harness execution remains an external evaluation-runner concern. Raw transcripts and provider credentials should stay outside normal Skill loading paths and outside committed fixtures unless explicitly synthetic and safe.

Agent Skills frontmatter compatibility

SKILL.md frontmatter must stay compatible with the Agent Skills specification and strict reference validators.

Allowed top-level fields are:

• name — required and must match the parent directory name;
• description — required and should state both capability and trigger/use case;
• license — optional; repository-owned Skills should normally use MIT;
• compatibility — optional, only when environment requirements are material;
• metadata — optional string-to-string map for repository-specific metadata;
• allowed-tools — optional/experimental and should not be used to broaden execution authority.

Do not add custom top-level fields such as display_name, display_name_en, description_zh, description_en, version or author. Put repository-specific values under metadata instead.

Keep name within the Agent Skills naming constraints and description within the specification limit. Metadata compatibility is part of multi-agent portability; a Skill that works in one permissive runtime but fails strict validation is not considered portable.

• A Ready combined readout must treat whitespace-obfuscated whole-label Not Applicable metric names as unresolved for both primary and guardrail identities. Normalize actual whitespace (including repeated spaces, tabs, newlines and Unicode whitespace) alongside hyphens/underscores before the exact placeholder comparison. Do not reject concrete names merely containing these words, and do not change exploratory/non-combined legacy behavior. This is read-only internal evidence validation, not source authentication, a zero measurement, or live Ads write permission.
• scripts/project_measurement_history.py rejects unresolved or padded expected/observed scope identities; missing/unknown scope never becomes a usable measurement identity. Concrete IDs with placeholder substrings remain allowed.

Versioning and releases

VERSION is the canonical repository release version. Keep the README version label and all runtime manifests (.codex-plugin/plugin.json, .claude-plugin/plugin.json, and .workbuddy-plugin/plugin.json) synchronized with it, and add the release entry to CHANGELOG.md.

Use semantic versioning for release-worthy changes:

• PATCH — backward-compatible bug fixes, documentation corrections, research/source maintenance, or internal changes that do not materially expand a public decision/runtime contract.
• MINOR — backward-compatible new capability, materially stronger decision/safety/data/runtime behavior, new optional schema surface, or another substantial improvement users should be able to identify as a new release.
• MAJOR — breaking changes to public schemas, CLI/output contracts, canonical Skill/capability identity, runtime integration contracts, or changes that require downstream migration.

Trigger/discovery summaries must expose both the observed boolean denominator and explicit coverage status (complete, partial, or unmeasured). A rate without coverage status must not be interpreted as full-population coverage; missing/null remains unmeasured, never false or zero.

A material MINOR/MAJOR change must not merge while the repository continues to advertise the previous release indefinitely. Classify version impact in the pull request; when a bump is required, update VERSION, README, all runtime manifests, and CHANGELOG.md in the same PR. Do not add repository release versions to individual SKILL.md top-level frontmatter.

Deterministic repository validation

After changing a Skill, its supporting references, shared references, schemas, playbooks, eval fixtures, validators, projector/summarizer utilities, or runtime manifests, run:

python -m unittest discover -s tests -v
python scripts/validate_skills.py .
python scripts/validate_evals.py .

The validators are intentionally dependency-free and check repository invariants that should fail before a runtime or eval harness discovers them interactively. Unit tests additionally cover measurement-state projection, realized-ad projection, experiment-plan semantics, paired effectiveness aggregation and release/runtime compatibility.

Skill/package validation checks:

• every direct child of skills/ contains SKILL.md;
• required name / description frontmatter exists;
• top-level frontmatter stays within the Agent Skills allowed field set;
• Skill name matches its folder name;
• nested SKILL.md files are rejected;
• relative Markdown references from SKILL.md stay inside the repository and resolve to existing paths.

Eval-contract validation checks:

• every evals/fixtures/*.json file parses as JSON;
• required/allowed fixture and expected-result fields are respected;
• mode and acceptable-decision values stay within the closed-world schema contract;
• fixture ID matches filename and does not collide;
• entrypoint stays inside the repository and exists;
• rubric/required-observation contracts do not positively require live mutation.

.github/workflows/validate-skills.yml runs unit tests plus both validators for relevant pushes and pull requests when GitHub Actions is enabled. Do not treat a local or CI pass as proof of Amazon Ads decision quality; deterministic structure/contract checks complement, rather than replace, capability replay behavior checks.

Contribution rules

New skills must:

• use kebab-case directory names;
• include Agent Skills-compatible YAML frontmatter with at least name and description;
• keep custom metadata under the metadata map rather than inventing top-level fields;
• keep the core SKILL.md concise and progressively load shared references;
• state required inputs, workflow, output contract, safety checks, and stop conditions;
• output proposals rather than performing live account mutation.

Add a playbook instead of a new Skill when the new material is primarily a recurring operating rhythm that composes existing Skills rather than a distinct decision capability.

Shared memory/history features should prefer append-first events plus derived compact summaries rather than mutable prose logs.

When a change materially affects source comparability, negatives, bid/budget reversals or sizing, retail causality, Mixed-ASIN safety, growth qualification, experiments, readback, or rollback decisions, add or update a replay fixture when practical.

Measurement scope validation

When an event contains an observed scope object, validate all scope fields even if expected_scope is omitted.

When an event explicitly supplies an account_identity object, it must contain at least one advertiser or regional profile identifier. Weak-only claims such as country_code are partial identity, not missing identity, and must fail closed. Missing account_identity remains distinct from an explicit incomplete claim. Unresolved placeholders and padded values are invalid provenance; absence of a scope object remains distinct from an unresolved supplied scope. Do not convert unresolved or missing scope to zero, false, or a usable identity.

Realization measurement scope validation

When a realization event supplies marketplace or profile scope, validate all scope fields even if expected_scope is omitted. Unresolved placeholders and padded values are invalid provenance; absence of marketplace/profile scope remains distinct from a supplied partial/unresolved scope. Legacy entity-only events remain compatible without upgrading to verified scope.

Partial scope claim validation

When an event supplies marketplace or profile_scope, it is a scope claim even if the entity object is absent or malformed. Reject the event as partial/unresolved provenance rather than downgrading it to a legacy unbound event. Missing scope remains distinct from supplied partial scope.

Account identity validation

Account identity fields in read-only measurement/realization projections must be concrete, unpadded strings. Whole-label unresolved values such as Unknown, Partial, Missing, Unsupported, Unavailable, Not Applicable and N/A are invalid provenance. Missing account identity remains missing; concrete opaque IDs containing these words as a substring remain valid. Do not convert unresolved or missing account identity to zero, false, or a usable join key.

Weak-only account identity claim validation

When an event explicitly supplies an account_identity object, it must contain at least one advertiser or regional profile identifier. Weak-only claims such as country_code are incomplete identity and must fail closed rather than being silently downgraded to missing identity. Missing account_identity remains distinct from an explicit incomplete claim.