@thinkingai/ae-cli 6.1.19 → 6.1.21

package/skills/ae-analysis/references/adhoc_run.md

@@ -4,7 +4,7 @@ Run one unified ad-hoc analysis inline query from an AI-facing model definition.
 
 Use this command for AI-facing ad-hoc model analysis. Do not use removed ad-hoc QP builder or schema helper commands.
 
-Typical closed loop: express the business question as an AI-facing definition -> let the compiler resolve metadata -> use `analysis filter-value list` only when an exact stored value remains unknown -> optionally resolve a physical route -> run -> verify `resolved`, warnings, and actual scope -> drill down only through the returned query context.
+Submit the requested metrics, windows, filters and groups together in the selected model definition. Reuse verified canonical metadata; resolve unknown metadata with [`metadata_resolution.md`](metadata_resolution.md) before execution. Use `analysis filter-value list` only when a needed stored filter value remains unknown.
 
 Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `run` command instead of `adhoc export`.
 
@@ -15,6 +15,7 @@ ae-cli analysis adhoc run \
   --project-id <project_id> \
   --model-type <model_type> \
   --definition '<json>' \
+  [--intent-snapshot '<snapshot_json>'] \
   [--resolutions '<confirmed_resolution_json>'] \
   [--request-id cli_<32 lowercase hex>] \
   [--use-cache true|false] \
@@ -28,16 +29,17 @@ ae-cli analysis adhoc run \
 
 ## AI models
 
-Read [`ai_models.md`](ai_models.md) for the single 12-model `model_type` registry, AI-facing `definition`, and SQL dynamic params contract.
+Read the shared registry and building blocks in [`ai_models.md`](ai_models.md), then open `ai_models/<model_type>.md` directly for the selected model. Do not search for section line numbers or load other model files. For event period totals plus daily trends, use the `day` + `comparison_time_ranges` example in [`ai_models/event.md`](ai_models/event.md). Read [`ai_models/sql.md`](ai_models/sql.md) and its dynamic params contract only for SQL.
 
-For SQL model definitions, do not invent table or column names. If the table reference is known, inspect columns with `analysis-meta datatable columns-get`; if the table is unknown, ask for it instead of guessing.
+For SQL model definitions, use [`sql_table_list.md`](sql_table_list.md) to discover an unknown table, then [`sql_table_columns.md`](sql_table_columns.md) with the exact returned `table_ref` and the same `usage=analysis`. A known authorized table can go directly to column inspection. Ask only when discovered candidates remain ambiguous or the required data source is unavailable; do not invent table or column names.
 
 ## Input
 
 - `--project-id`: target project ID.
 - `--model-type`: one of the 12 AI-facing model names from [`ai_models.md`](ai_models.md). Do not pass `scenario`, `history_tag`, or `cluster`; tags and cohorts/clusters are separate capabilities.
 - `--definition`: model-specific AI-facing definition JSON.
-- `--resolutions`: only after user confirmation, pass deterministic bindings keyed by compiler error path. Keep `--definition` unchanged; follow [`../metadata_resolution.md`](../metadata_resolution.md).
+- `--intent-snapshot`: use when the caller supplies an existing snapshot containing `schema_version: 1`, non-empty `requirement`, `definition`, and `model_type`. The CLI checks that its definition and model match the submitted values locally; the snapshot is never sent to Gateway.
+- `--resolutions`: only after user confirmation, pass deterministic bindings keyed by compiler error path. Keep each bound field's path and original wording; fill the other confirmed model parameters in `--definition`. Follow [`metadata_resolution.md`](metadata_resolution.md).
 
 Omit `--preview-rows` to use the current model and cluster synchronous row limit. An explicit value must be positive and cannot exceed that runtime limit; agents should normally pass 100 to bound context. `--timeout-seconds` defaults to 120 and has a maximum of 180. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
 
@@ -58,14 +60,22 @@ The response may include:
 - `query_context_id`: Redis-backed context for follow-ups from this bounded synchronous preview.
 - `sources[].drilldown`: compact allowed-action summary. Detailed coordinate options are read lazily with `analysis query-context get`; `preview_rows` remains the selection boundary.
 - `title` / `rows` / `returned_rows` / `has_more`: tabular preview fields. `total` appears only when the backend supplies an exact total. When `has_more` is true, use `adhoc export`; there is no next-page request.
+- `row_metadata` / `column_metadata`, when returned: align with row/column positions. Event `scope=total` identifies a total row; `period_values` specifies stage aggregates. Time comparisons repeat metric titles in separate column blocks, so preserve indexes. See [event result totals](ai_models/event.md#event-totals-and-comparison-columns).
 - `result`: direct result for non-tabular models. Path results also return top-level `returned_rows` and `has_more` using the per-level node contract above.
 - `request_id`: lifecycle request id.
+- `definition`: normalized AI-facing definition used for compilation. Tag/cluster filters expose the effective `cluster_date_policy`; `AUTO` means each analysis date uses its matching computed result, while an omitted policy defaults to `LATEST`.
 - `actual_cluster_query_scope`, optional `actual_slave_cluster_id`, and `cluster_query_scope_source`: actual physical data route. Verify these before comparing results or following the query context.
 
 Execution failures are returned as command failures with `request_id`; only the explicit project-no-data condition is a successful empty result. Do not interpret an empty object as evidence that a failed query succeeded.
 
-The execute, `--validate`, and `--dry-run` paths all compile the AI-facing definition. If metadata resolution needs clarification, the command fails with `AI_QP_COMPILE_FAILED`; inspect `meta.compile_status`, `meta.errors[]`, `meta.resolved`, and `meta.warnings`. Each metadata error retains `path`, `slot_kind`, `raw_value`, `allowed_resource_types`, `search_targets`, and `candidates`. Follow [`../metadata_resolution.md`](../metadata_resolution.md); do not guess from display text.
+Use the inline result directly. See [result handling](analysis_data_retrieval.md#preserve-and-interpret-results) when local processing or a requested file is needed.
 
-For a complex definition, finish the complete user-requested definition first, validate that exact definition once, and then run the same definition once. Never execute a simplified variant that omits requested filters or groups just to obtain a result. If validation rejects fields, inspect this command's model contract or capability schema once, correct all reported fields together, and revalidate the complete definition.
+The execute, `--validate`, and `--dry-run` paths all compile the AI-facing definition. If metadata resolution needs clarification, the command fails with `AI_QP_COMPILE_FAILED`; inspect `meta.compile_status`, `meta.errors[]`, `meta.resolved`, and `meta.warnings`. Each metadata error retains `path`, `slot_kind`, `raw_value`, `allowed_resource_types`, `search_targets`, and `candidates`. Follow [`metadata_resolution.md`](metadata_resolution.md); do not guess from display text.
 
-Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Use the context only with an action advertised by the selected source, call `analysis query-context get`, and assemble the coordinate only from its returned option fragments. Do not pass raw QP or infer a coordinate from display text.
+For `meta.compile_status=invalid_argument`, correct the reported parameter paths in the current definition and submit that corrected definition. For metadata `need_clarification`, use the returned candidates and [confirmation workflow](metadata_resolution.md). Once the requested meaning and required parameters are ready, execute directly.
+
+If a concrete field mismatch remains unexplained by the loaded reference, inspect this command's model contract or capability schema once. A preflight is conditional on that input problem: validate that exact definition once, then run the same definition once. Preserve all requested filters and groups through corrections.
+
+For a gateway `oneOf` error, focus on the selected `model_type` branch and shared input fields; other model branches are alternatives, not additional requirements. Apply every relevant correction together (for example, both `event_property_name` and string-valued `values` for funnel step filters). Local `INVALID_ANALYSIS_DEFINITION` is a pre-dispatch input failure, not a query failure. Passing this narrow local check is not proof that the full backend schema or query has passed. Follow the failure-evidence rules in `../SKILL.md` and honor the user's retry limit.
+
+When the request needs a drilldown action advertised by the selected source, read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md), call `analysis query-context get`, and assemble the coordinate from its returned option fragments. Do not pass raw QP or infer a coordinate from display text.

package/skills/ae-analysis/references/agent_review_detail.md

@@ -0,0 +1,11 @@
+# analysis-meta agent-review detail
+
+Use this to read current item states and versions. Input requires project scope and a string batch ID. Output is one review batch with its immutable snapshots. Do not use approval state alone as proof of certification.
+
+Preserve item-level `reused_batch_id` and `reused_item_id` as strings when present. They link unchanged proposals to their original review while keeping the current batch's complete item coverage and request identity.
+
+```bash
+ae-cli analysis-meta agent-review detail --project-id 1 --batch-id '9007199254740993'
+```
+
+Capability: `metadata.agent_review.detail`. L2 flags validate project scope and preserve the batch ID as a decimal string. Output includes snapshots as objects, `review_url`, notification status and items with `client_item_id`, string `id`, `version`, `review_state`, `execution_state`, and `validity_state`. Do not infer certification from APPROVED alone; inspect successful execution and its audit record. Re-fetch current versions before preparing decisions and after writes; never round IDs through JavaScript numbers.

package/skills/ae-analysis/references/agent_review_evidence.md

@@ -0,0 +1,46 @@
+# analysis-meta agent-review evidence
+
+Use this to read current Common evidence for one resolved asset before drafting its review explanation. This read does not create a batch, write review records, notify, or certify. It does not run report queries. Do not use it as proof of a submitted proposal or approval. The proposed CERTIFY action selects the same snapshot handler used by creation; it is not executed by this command.
+
+L2 admission: owned by Common ta-cli / AgentReviewService. Typed project validation, lossless string target keys and fixed governance defaults avoid constructing a mutation-shaped JSON payload manually. This command is the read-only evidence step of the report-review workflow, not an alternative submission command. It uses `metadata.agent_review.evidence` through the analysis Gateway, CLI-token authentication, `metadata:read`, and the exact project function `assetAuthentication`.
+
+```bash
+ae-cli analysis-meta agent-review evidence \
+  --project-id <project_id> --target-type <target_type> --target-key '<exact_target_key>'
+```
+
+Resolve the project and target first; placeholders are not literal values. Target keys remain strings, including report/dashboard IDs above JavaScript's safe-integer limit and nonnumeric metadata names. Common determines which target types it supports; the CLI does not invent new types or coerce keys to numbers.
+
+Input contains `project_id`, `review_type:ASSET_GOVERNANCE`, `target_ref:{type,key}`, `action_type:CERTIFY`, and `proposal_payload:{authentication_status:1}`. There are no decision, source, or submission flags. `--validate` and `--dry-run` use their separate nonmutating Gateway endpoints; neither is an evidence fetch unless the returned contract explicitly includes the snapshot. Use normal read execution to obtain current evidence. Permission or unsupported-capability failures stop the dependent proposal; do not use a direct backend call or a dummy submission to obtain evidence.
+
+Output `data` contains `schema_version:"1.0"`, `review_type`, `target_ref`, `evidence_snapshot`, `evidence_hash`, and `target_revision`. Preserve the server snapshot and revision/hash as returned; do not compute authoritative hashes from CLI-reformatted JSON. This is a current read, not a lock or submission. Common create stores the submitted snapshot; it does not refresh it or restore omitted fields. Record gap-only evidence responses in the source ledger and follow [independent Agent preflight](agent_review_preflight.md) before declaring a draft ready. Detail readback checks that the submitted evidence and interpretation survived storage, not that Common regenerated them.
+
+`evidence_hash` includes collection time and can change across evidence reads even when business facts are unchanged. Do not use the full snapshot hash to detect cross-scan business changes or trigger another submission/notification. `target_revision` identifies the saved definition and can confirm its configuration version; it is not a revision of all sampled usage/signals. Compare material facts and proposal content separately, preserving unknown versus zero/false. Evidence reads do not submit: preserve the chosen source response and compare important stored facts with the exact reviewed draft, rather than relying on full-snapshot hashes from different collection or serialization stages.
+
+## Report Analysis Fields
+
+For reports, inspect `data.evidence_snapshot.analysis`. The AI's `evidence_refs` are rooted at `evidence_snapshot.analysis`, without the CLI envelope's `data` prefix. The table describes the current schema, not guaranteed populated facts for every model. Use only paths that actually exist in the response and support the stated fact. A present key with null is unknown, not zero, false, no filter, or an execution default. Empty collections may reflect unavailable extraction, not absence of a business rule. Read `limitations` and parse status before interpreting them.
+
+| Field under `evidence_snapshot.analysis` | Meaning and boundary |
+| --- | --- |
+| `schema_version`, `scope`, `kind`, `model`, `model_type` | Analysis version and saved report model. `scope:SAVED_REPORT_ONLY` excludes effective dashboard overrides and runtime execution. |
+| `raw` | Original saved `events`, `event_view`, and `visual_view` configuration. These may be strings, structured values, or null; do not replace them with invented normalized content. |
+| `query_config` | Decoded `events`, `event_view`, and `visual_view`; decoding failure is a limitation, not an empty successful query. |
+| `normalized_definition` | Native converter output when available, including model-specific metrics, time configuration, SQL or `params` only when actually returned. It is not a guarantee of resolved runtime parameters. |
+| `measures` | Ordered model-specific statistical measures. Event measures may expose `aggregation`, `aggregation_code`, `aggregation_name`, `distinct`, `formula`, `formula_dependencies`, and per-measure `filters`. SQL measures are the extracted aggregate projections; they are not all output columns. |
+| `dimensions` | Saved event grouping or SQL grouping syntax, not executed rows or proven complete column lineage. |
+| `filters` | Saved report/common filters or extracted SQL WHERE/HAVING with their scope. Inspect per-measure filters as well. Do not infer absent constraints from a null or empty extraction. |
+| `time_range` | Saved `recent_day`, `start_time`, `end_time`, `time_particle_size`, comparison fields and related period settings. Interpret the actual saved range; do not replace it with asset-usage window days or today's date. |
+| `timezone` | Execution timezone is not established by the current report extractor. Null remains unknown; do not assume a user, project, dashboard, or local-machine default. |
+| `sql` | SQL-only `raw`, `parse_status`, `select_columns`, `select_distinct`, `from`, `where`, `group_by`, `having`, `order_by`, `limit`, and `offset`, subject to parse status and limitations. |
+| `sources`, `limitations` | Source provenance and explicit extraction boundaries. Preserve unsupported models, unexpanded dependencies, dashboard overrides not applied, and unresolved runtime conditions. |
+
+`source_path` is provenance, not an automatic replacement for AI `evidence_refs`. For example, a measure's source path can identify the saved configuration blob while the factual explanation cites the actual returned `evidence_snapshot.analysis.measures[0].aggregation_name`. Use that example only if index 0 and the nonnull field really exist and support the statement. Never mechanically copy source paths, generate indexes from expected fields, or claim reference resolution proves the statement's meaning.
+
+## SQL Interpretation Boundaries
+
+For `PARSED` output, explain each actual `sql.select_columns` entry in source order, keeping its `index`, alias/name, expression, distinctness and supported aggregation/formula evidence. Duplicate aliases remain separate columns. `columns` contains syntactic references, not verified table lineage or runtime types. `PARTIAL` and wildcard entries require explicit coverage limits; never expand `SELECT *` by guessing.
+
+When Common returns `DYNAMIC`, cite `evidence_snapshot.analysis.sql.raw` and, only if present, `evidence_snapshot.analysis.normalized_definition.params` for an explicitly labeled original-text interpretation. Describe visible template text and unresolved parameters, not substituted SQL or effective output. Do not invent `select_columns`, substitute runtime values, or claim an empty projection list proves there are no columns. Do not fill factual query-column sections from a guessed parse. `UNAVAILABLE` or `UNSUPPORTED` similarly retains only what the response actually proves; report the limitation rather than claiming a complete calculation review.
+
+None of these reads proves query execution, returned rows, complete business semantics, approval, or certification. Complete the normal sequence in [submit-to-page](agent_review_submit_to_page.md): resolve/export, read every report, fetch evidence, draft supported AI explanations, submit only with authorization, then compare detail readback.

package/skills/ae-analysis/references/agent_review_list.md

@@ -0,0 +1,9 @@
+# analysis-meta agent-review list
+
+Use this to locate recent batches. Input requires project scope and optionally an integer limit. Output is the `batches` array. Do not use this bounded directory as a complete-history export.
+
+```bash
+ae-cli analysis-meta agent-review list --project-id 1 --limit 20
+```
+
+Capability: `metadata.agent_review.list`. Returns `batches`, a bounded list of visible recent batches. The typed project ID and integer limit (default 20, range 1..500) form the L2 directory contract. This is not a paginated complete-history export. Do not treat absence from this recent list as proof no earlier proposal exists; retain task batch IDs and proposal fingerprints. Use detail for item versions and records for execution evidence.

package/skills/ae-analysis/references/agent_review_preflight.md

@@ -0,0 +1,96 @@
+# Agent Review Preflight
+
+Use for preparing or checking review-page materials, including a local-only rehearsal. This is an Agent workflow, not a Common admission rule. Read alongside [submit-to-page](agent_review_submit_to_page.md). A CLI validation success is not a quality approval.
+
+## Authorization and Isolation
+
+Record `LOCAL_ONLY` or `SUBMISSION_AUTHORIZED` from the user's current instructions before starting. `LOCAL_ONLY` prohibits creating batches, notifications, decisions, certification, retries and metric writes, even after a quality PASS. Use only project resolution, recommendation export and necessary evidence/history reads through the project CLI. Keep all drafts and checks local; do not invoke submission commands just to test the review. Existing explicit submission authorization remains valid only while not revoked or narrowed; a newer no-submit request takes precedence over all earlier authorization. Quality PASS or retry exhaustion never creates authorization.
+
+Use a fresh-context reviewer subagent that did not author the material. Give it this reference, the raw evidence files, the exact draft and the scope/source ledger; do not give it the author's quality conclusion or ask it to confirm correctness. It has no submission or rewrite authority. Never substitute a second persona in the same conversation for isolation. If independent subagents are unavailable, record `NOT_REVIEWED` with `REVIEWER_UNAVAILABLE` and disclose unchecked scope. Do not self-approve or spend three attempts on the same unavailable reviewer; follow the warning continuation policy below.
+
+For an explicit audit-only request, the independent reviewer may run these checks directly without spawning another reviewer. Its findings are the audit result, not self-approval of authored text.
+
+## Prepare Once, Interpret in Batches
+
+1. Resolve the host/project, export the candidate pool, and apply the existing rejection/20 -> 50 -> 100 procedure. Preserve the original export file. Record CLI/source revision, loaded Skill path and file hashes so an installed old Skill cannot silently stand in for the tested one.
+2. Build a scope ledger accounting for every candidate: retained, existing certified context, same-definition rejection, or an explicit evidence gap. Account separately for metric-creation candidates, which are not CERTIFY proposals. A missing explanation is unfinished work, not a reason to silently remove an asset. Preserve shared asset identity and retained relations.
+3. Split retained assets into manageable business-domain chunks, with a per-item checklist. Read actual definitions before writing each chunk. Authoring subagents may work on disjoint chunks, but none may approve its own work. Complete and merge every chunk before calling a batch complete; do not stop at representative examples or fill remaining entries with templates.
+4. Keep narrative entries separately keyed by `client_item_id`. Scripts may join these entries to the packet, never compose their sentences. Deep-copy each original `evidence_snapshot`, including `asset`, `signals`, `definition`, `analysis`, revisions and source provenance when present. Copy candidate source/evidence links too. The abbreviated transport example is not a field allowlist.
+5. For a gap-only evidence read, preserve the entire original response and record its asset identity and file in the source ledger. The reviewer must verify any replacement/addition against that response. Never replace an existing value merely to agree with prose or recompute server hashes. Common stores the submitted packet; it does not fill omitted statistics or author explanations.
+6. Complete [per-asset priorities and cross-asset comparisons](agent_review_priorities_comparisons.md) after merging chunks. Supply evidence-backed `recommendation`, classified `comparisons` and explicit `comparison_review` coverage; missing fields are not a default priority or proof of no conflict.
+
+## Required Independent Checks
+
+The reviewer performs both passes on the complete retained scope. It may use scripts for deterministic comparisons, but must itself interpret the definitions for the semantic pass.
+
+### A. Evidence and Coverage
+
+- Match by full scoped `target_ref` and stable item ID, not name. Reconcile all candidates, all draft items and every displayed relation with the scope ledger. Missing or duplicate coverage cannot PASS.
+- Structurally compare each draft snapshot with its original source, preserving all original fields, array order and values. Check `signals` explicitly: missing, null and zero are different. Available heat/users/impact must not disappear while remaining only in prose. Record exact mismatching paths. Verify any permitted enrichment against its saved evidence response; a draft-authored value is not source evidence.
+- Keep usage provenance. Export ranking fields such as `heat_count90d` can differ from selected `evidence_snapshot.signals` values. Do not overwrite either or call this alone corruption. Explain which source/window a numerical claim uses. The 90-day usage window is not the report's saved query time.
+- Resolve every factual `evidence_refs` path and check the value, not just path existence. Verify revisions, source links, hierarchy and documented exclusions. Save machine-check results with checked item IDs and uncovered IDs.
+- Cross-check counted entities, filter/group fields and formula dependencies in actual definitions against the exported dependency graph. All relation IDs resolving does not prove all dependencies were exported. Record missing dependencies as source gaps; never invent asset IDs or evidence-backed edges. Use the relevant read-only CLI lookup only when it can resolve that gap, and preserve its response before adding a verified relation.
+
+### B. Meaning, Not Filled Fields
+
+- Review every retained item's recommendation, and every retained dashboard/report's definition-based explanation. Track checked IDs; sampling cannot establish a whole-batch PASS. If the scope is too large, split the review across fresh reviewers with disjoint ID lists and combine their coverage and findings.
+- Dashboard: explain the business question jointly answered by its actual child reports and why this particular combination merits review. A title plus heat and "stabilize downstream definitions" is insufficient.
+- Report: explain the actual counted entity, unit, aggregation/formula, measure-level and report-level filters, grouping and saved time semantics. Read raw/normalized configuration when the generic extractor loses model-specific meaning; for example a distinct count may count a company property rather than users. Empty generic measures/dimensions do not establish absent measures/grouping.
+- For entity counts, inspect saved entity configuration (such as `measures[].config.quotaEntities` when present), the distinct key and denominator, not only `user_count` or null `identity_scope`. For rank/retention models with empty generic measures, inspect the available `normalized_definition` model section first; do not repeatedly fetch the same evidence just because the generic projection is empty.
+- SQL: inspect saved SQL and parameter definitions, even for DYNAMIC/PARTIAL status. Explain supported aggregation, joins and predicates from the original text, clearly separated from unresolved runtime values. Do not invent projections or lineage, and do not use "see the report definition" as the calculation explanation. State the specific unresolved parameter, branch or wildcard and its decision impact, rather than treating all dynamic SQL as unreadable.
+- Compare summaries, purposes, calculations, limitations and questions after removing asset names (including Chinese corner quotes), IDs, dates and numbers. Repeated shapes flag items for definition-based review, not mechanical paraphrasing. Different strings and correct citation syntax do not prove meaningful explanation; conversely a genuinely shared rule can be valid if each item's evidence supports it.
+- Unknown facts stay unknown. Verify that "no grouping/filter" and distinct-entity claims are actually supported. Risks must be item-specific evidence gaps, not speculative warnings attached to every asset.
+- Apply the priority/comparison reference: verify review urgency separately from certification outcome, examine both definitions and cross-topic peers, distinguish equivalent/different-scope/insufficient evidence from possible conflicts, and require reciprocal conflict links. Record graded/unassessed coverage, classified pair outcomes and unchecked peers. These checks share the same maximum 3 corrections, never a new budget per pair.
+
+## Review Artifact and Repair
+
+Write a local `preflight-review.json` with:
+
+```json
+{
+  "mode": "LOCAL_ONLY",
+  "decision": "NEEDS_REVISION",
+  "repair_attempt": 0,
+  "max_repair_attempts": 3,
+  "reviewer_id": "<independent agent ID>",
+  "source_sha256": "<original evidence file hash>",
+  "draft_sha256": "<exact reviewed file hash>",
+  "expected_item_ids": [],
+  "checked_evidence_ids": [],
+  "checked_semantic_ids": [],
+  "unreviewed_ids": [],
+  "findings": [
+    {
+      "item_id": "<asset ID>",
+      "field": "<draft field>",
+      "code": "<EVIDENCE_LOSS|UNSUPPORTED_CLAIM|BOILERPLATE|INCOMPLETE|SCOPE_GAP>",
+      "source_ref": "<raw file and supporting path>",
+      "problem": "<concrete mismatch>",
+      "required_action": "<evidence to read or content to repair>"
+    }
+  ]
+}
+```
+
+The reviewer, not the author or transport script, sets `PASS` only when both passes cover the entire expected scope and no blocking finding remains. Source limitations may remain when honestly explained and the core interpretation is supported; unresolved core meaning cannot PASS. Do not put this local artifact into the Common packet or treat it as authoritative server evidence.
+
+On `NEEDS_REVISION`, the author reopens cited definitions, restores evidence or rewrites the actual interpretation. Adding asset names, IDs, numeric details, synonyms or prefixes merely to defeat repeated-text checks is prohibited. Re-review changed narratives independently and rerun full evidence/coverage checks.
+
+Allow at most **three correction attempts per logical material packet**. Initial drafting/review is attempt 0 and does not consume a correction. Each subsequent author revision plus independent re-review consumes one attempt (1, 2, 3); stop correcting immediately on PASS. Persist the counter and link each finding to the changed fields and the reviewer's resolved/unresolved result. After review of attempt 3 still returns NEEDS_REVISION, do not start attempt 4: retain the failed quality verdict and continue with warnings under the policy below. Replacing subagents, renaming files, regenerating drafts, changing source run IDs, or resuming the same task must not reset this counter. Do not quietly reduce the batch, skip the reviewer or label unfinished work complete. A new retry budget requires explicit user authorization. This is a ceiling, not a quota: stop correcting earlier when no meaningful repair is possible with available evidence and scope; record why, and do not spend attempts on unchanged retries.
+
+## Continue With Disclosed Quality Issues
+
+Quality verdict and submission authorization are separate. A failed quality review must not block an already authorized material-submission workflow after the bounded correction loop. Apply these outcomes without asking for redundant authorization:
+
+| Mode | Quality outcome | Next action |
+| --- | --- | --- |
+| `LOCAL_ONLY` | Any, including PASS or attempt-3 failure | `LOCAL_ARTIFACT_ONLY`: return draft, review and unresolved issues; never submit or notify. |
+| `SUBMISSION_AUTHORIZED` | PASS | Submit the reviewed material through the normal CLI path. |
+| `SUBMISSION_AUTHORIZED` | NEEDS_REVISION after attempt 3, or documented no-progress stop | `SUBMIT_WITH_WARNINGS`: submit the latest material and disclose remaining issues; never relabel it PASS. |
+| `SUBMISSION_AUTHORIZED` | NOT_REVIEWED because an independent reviewer is unavailable | `SUBMIT_WITH_WARNINGS`: disclose unavailable review and unchecked scope; do not pretend a review happened. |
+
+Before warning-mode dispatch, put a concise Chinese notice in the existing `batch.ai_summary.summary`: actual correction count, unresolved issue categories and affected scope, and that the material is being handed to human review without a quality PASS. Add item-specific `limitations` or `open_questions` for the affected assets where supported, with concrete verification actions; do not duplicate a generic warning on every asset. Keep the full item/field/finding list in the local report and give its location to the user. These are draft annotations, not new Common schema fields or fabricated source facts. Unknown values remain unknown; never invent statistics, definitions or references to make a request valid.
+
+Any change to the draft or source invalidates its previous PASS. Bind each independent review to its exact source/draft hashes. Record the final dispatch hash separately from the last reviewed hash and enumerate warning-only additions. Run deterministic structure/evidence comparisons after adding warnings; warning annotation does not start a fourth semantic correction or fabricate a new review. Preserve NEEDS_REVISION/NOT_REVIEWED and the actual coverage.
+
+This continuation applies only to Agent quality findings, not missing submission authorization, invalid required fields, broken evidence references, authentication/permission failures, or transport/server errors. Keep ordinary CLI/Common validation and error handling; do not bypass it, silently drop items, switch to a less checked API, or claim success without a returned batch ID. After actual submission, compare stored detail with the final dispatched material, report remaining quality issues and the review-page link, and do not automatically approve or resubmit. In LOCAL_ONLY, these network steps remain forbidden even when warning-mode policy would otherwise apply.

package/skills/ae-analysis/references/agent_review_priorities_comparisons.md

@@ -0,0 +1,76 @@
+# Review Priority and Definition Comparisons
+
+Read after interpreting individual assets and before [independent preflight](agent_review_preflight.md). These are Agent assessments inside each item's `ai_summary`, not new Common admission rules, certification decisions or server evidence. Generate them in LOCAL_ONLY rehearsals too, without submitting anything.
+
+## Per-Asset Review Priority
+
+Write `recommendation.priority` as `HIGH`, `MEDIUM` or `LOW`, with a concrete Chinese `priority_reason` and `evidence_refs`. This ranks human review attention, not whether certification should pass, fail or be deferred. Do not duplicate `ai_summary.summary` into `recommendation.reason`; the summary remains the single item recommendation reason.
+
+- Consider actual business use, distinct users, dependency/reuse scope, decision importance and definition clarity together. State which verified facts make this item more or less urgent within its business domain. A heavily reused foundational field can deserve attention despite little direct viewing.
+- Heat alone, source order, asset type, a copied name or a numeric cutoff is not the decision. Scripts may expose comparable facts, never assign grades or template the rationale. Do not invent business criticality when only usage is known.
+- A consequential suspected conflict can raise review urgency while lowering confidence in certification. LOW means lower review priority, not "defer certification". HIGH is not approval or proof of accuracy. Do not force a distribution or mark everything HIGH to satisfy the priority filter.
+- Preserve usage provenance and windows; missing values are not zero. If evidence cannot support a grade, omit `priority`, explain the specific gap in `priority_reason` and count the item as unassessed in preflight. Never default unassessed assets to MEDIUM or claim full coverage.
+
+Local priority `evidence_refs` resolve against that item's unchanged `evidence_snapshot`, including signals, definitions and lineage. Evidence outside that snapshot must be identified in the source ledger rather than silently copied into authoritative fields.
+
+## Cross-Asset Comparison Pass
+
+After merging authoring chunks, compare candidate peers across dashboards and business-topic boundaries. Chunk-level review alone is insufficient. Build a local comparison ledger: scoped item identities, common business question, which definition facts were read, outcome, and why potential peers were included or excluded. Do not compare every pair indiscriminately: use same/similar business meaning, shared measure/entity, actual formula/SQL and dependency overlap to shortlist. Names and "copy" suffixes are retrieval hints, never conclusions.
+
+Compare the actual counted entity and distinct key, unit, numerator/denominator, aggregation, filter scope, grouping, time semantics, joins and exclusions. For dashboards compare the child-report sets and the meaning of their shared business measures; visual/name similarity alone is not a conflict. Normalize structural syntax only for retrieval; semantic equivalence remains an Agent judgment. Do not execute report queries just to compare saved definitions.
+
+Before assigning a priority or comparison outcome, cross-check these common interpretation traps against the raw definition:
+
+- Preserve relative/dynamic time selectors alongside saved absolute dates; cached dates alone do not prove a fixed historical window or justify a lower priority. If selector resolution is unavailable, name that uncertainty.
+- Read the actual formula operands and JOIN predicates. A projected/grouped ID is not necessarily a join key; a token denominator is not a message count. Verify claimed grouping differences on both sides.
+- Missing, null, empty, zero and explicit false are distinct evidence states. Do not infer default filter behavior or turn a missing status/environment filter into an intentional business-scope difference without evidence.
+- A field's display name does not prove its timing boundaries or virtual-property formula. Keep unsupported semantic relationships INSUFFICIENT_EVIDENCE rather than asserting equivalence or safe coexistence.
+- After chunk integration, reconcile the comparison ledger and coverage with the actual peer entries. Remove resolved author handoff tasks, retain real evidence gaps, and investigate obvious same-measure peers before claiming the stated scope COMPLETE.
+
+Write `comparisons[]` only for meaningful examined peers, each with:
+
+| Field | Contract |
+| --- | --- |
+| `other_item_key` | The peer's exact `client_item_id` in this packet, not a report ID or display name. |
+| `target_ref` | The peer's unchanged full scoped target reference; must agree with `other_item_key`. |
+| `classification` | One of the four outcomes below. New materials must supply it. |
+| `similarities` | Chinese explanation of the shared business meaning that justified comparison. |
+| `differences` | Concrete definition differences, or explicit supported equivalence; not just "definitions differ". |
+| `impact` | Business interpretation/decision affected by the difference, not raw evidence paths. |
+| `review_question` | For a possible conflict, what the human should establish about intended scope/authority. For other outcomes, state any remaining question without manufacturing a need to choose one winner. |
+| `evidence_refs` | Two or more scoped evidence references covering both sides, as described below. |
+
+Classifications:
+
+- `POSSIBLE_CONFLICT`: evidence supports the same intended business concept and overlapping scope, but incompatible entity/formula/filter/time semantics could yield competing answers. State the precise incompatibility and uncertainty; the Agent does not decide which asset is authoritative.
+- `EQUIVALENT`: examined definitions express the same meaning in the reviewed scope. Shared assets appearing under multiple dashboards are one identity, not a self-comparison or conflict. Identical definitions on distinct assets may warrant consolidation discussion, not a conflict badge.
+- `RELATED_DIFFERENT_SCOPE`: related concept with an explicitly supported difference in purpose, population, grain or time scope that explains coexistence. Do not infer intended scope merely to dismiss an unexplained difference.
+- `INSUFFICIENT_EVIDENCE`: a relevant peer was found, but missing definitions or unresolved parameters prevent classification. Name the missing facts. Do not claim a proven conflict or no conflict.
+
+Both endpoints of every in-packet `POSSIBLE_CONFLICT` must contain reciprocal comparisons with the same classification, reversed identities and correctly oriented evidence/differences. Keep both assets in their normal groups and keep all human review actions available. Do not remove one or assume an original is authoritative over its copy. Pair comparisons never authorize changing certification status.
+
+Comparison references are strings of the form `items[client_item_id=<exact ID>].evidence_snapshot.<actual path>`, resolved by keyed identity, not array position. Include at least one supporting path from each endpoint; verify that the values support the stated difference. Keep these cross-item refs in `comparisons[].evidence_refs`; report `analysis_explanation` retains its existing item-local `evidence_snapshot.analysis...` contract. References are provenance for Agent checks, not fields for Common to interpret or manufacture.
+
+In the current page contract, actionable peer links require both assets in the retained packet. Record relevant out-of-pool or rejected peers in the local ledger and disclose the comparison boundary; use only necessary read-only CLI evidence lookups. Do not restore rejected branches or fabricate a peer ID just to create a badge. An unexamined external peer prevents a whole-project no-conflict claim.
+
+## Explicit Coverage, Not Empty-by-Default
+
+Every item also carries `comparison_review`:
+
+```json
+{
+  "status": "COMPLETE",
+  "scope": "<examined candidate pool and relevant peer scope, in Chinese>",
+  "compared_item_keys": [],
+  "reason": "<what was checked and why no relevant peer exists, or a concise outcome>",
+  "missing_evidence": []
+}
+```
+
+`status` is `COMPLETE`, `PARTIAL` or `NOT_REVIEWED`. COMPLETE means the stated comparison scope was examined, not that the whole project has no conflicts. A relevant pair classified INSUFFICIENT_EVIDENCE requires PARTIAL and named missing evidence. An empty `comparisons` array is acceptable after a supported no-peer review; by itself it proves nothing. List the actual compared IDs, not every asset in a topic. This coverage object is stored with AI material for audit; do not assume older pages render it.
+
+## Preflight and Bounded Repair
+
+The independent reviewer checks per-item priority coverage and evidence, cross-chunk candidate selection, both definitions for each pair, classifications, reciprocal conflict edges, identity/refs and whether the wording claims more coverage than was checked. It must challenge both false conflict badges and likely missed conflicts. Record counts by priority (including unassessed), comparison outcome, unique unordered conflict pairs, affected items, and incomplete comparisons. Count pair A-B once, not twice because of reciprocal entries.
+
+Use the same logical-packet correction budget in preflight: at most 3 corrections total, not 3 for each priority, pair or reviewer. On exhausted quality corrections, preserve the findings and follow authorized warning continuation. LOCAL_ONLY always ends with local files. Missing priority, incomplete comparison, and poor rationale are Agent quality findings, not new CLI/Common rejection rules.

package/skills/ae-analysis/references/agent_review_records.md

@@ -0,0 +1,9 @@
+# analysis-meta agent-review records
+
+Use this to audit a known batch. Input requires project scope and a string batch ID. Output is the `records` array. Do not use audit events as current asset-definition evidence.
+
+```bash
+ae-cli analysis-meta agent-review records --project-id 1 --batch-id '9007199254740993'
+```
+
+Capability: `metadata.agent_review.records`. Returns `records`, immutable batch, review, execution, retry and notification events. L2 flags require the project and a lossless decimal batch ID. Distinguish human approval from execution attempts and successful results. Do not use historical records as current asset evidence or repeatedly poll unchanged records for notifications.

package/skills/ae-analysis/references/agent_review_retry.md

@@ -0,0 +1,12 @@
+# analysis-meta agent-review retry
+
+Use this to execute an authorized retry. Input requires project scope, string batch ID, operation key and failed item IDs. Do not use retry to approve pending proposals.
+
+```bash
+ae-cli analysis-meta agent-review retry --project-id 1 --batch-id '9007199254740993' \
+  --client-request-id retry_002 --item-ids '["9007199254740994"]' --dry-run
+```
+
+Capability: `metadata.agent_review.retry`. Requires `assetAuthentication` and metadata write scope. L2 provides validated, unique string IDs, bounded selection and an explicit replay key. Retry only selected failed executions under their existing valid approvals after explicit retry intent. Do not retry successful items, manufacture approval for deferred/rejected items, or use retry from an unattended submission-only task. Read current detail first. A manual retry uses a new key; a network replay uses the exact previous key and payload. Validation/dry-run performs no mutation and does not guarantee current domain eligibility.
+
+Output includes refreshed detail, `submission_id`, and per-item `results`; inspect failures individually and read records for the linked execution attempts. Do not describe success until the selected executions actually succeeded.

package/skills/ae-analysis/references/agent_review_review.md

@@ -0,0 +1,16 @@
+# analysis-meta agent-review review
+
+Use this only for explicit human decisions. Input requires project scope, string batch ID, operation key and versioned decisions. Do not use submission authorization as approval authorization.
+
+Record a human's explicit decisions for existing versioned items. APPROVE executes certification immediately; DEFER and REJECT record opinions without certifying. Do not call this from a submission-only unattended task. Creating a review batch does not authorize this command.
+
+```bash
+ae-cli analysis-meta agent-review review --project-id 1 --batch-id '9007199254740993' \
+  --client-request-id decision_001 \
+  --decisions '[{"item_id":"9007199254740994","version":1,"decision":"DEFER","reason":"Need refreshed evidence"}]' \
+  --dry-run
+```
+
+Capability: `metadata.agent_review.review`. Requires the exact project function `assetAuthentication` and metadata write scope. L2 validates string IDs, nonnegative item versions (initial version 0 is valid), unique targets, APPROVE/DEFER/REJECT and mandatory nonblank reasons for DEFER/REJECT. Read detail first; preserve its versions. A preview invokes no mutations and does not reserve versions. Execute with explicit decision authorization, without changing the reviewed scope.
+
+Output is refreshed detail plus `submission_id` and per-item `results`. A successful response can contain failed executions; inspect each result and read detail/records. Same operation key replays the same decisions. A new human decision uses a new key. On stale-version or evidence conflicts, re-read and obtain a fresh decision; never automatically approve changed content.