@thinkingai/ae-cli 6.0.48 → 6.1.0-project-role-upsert.1

package/skills/ae-experiment-insight/scripts/analyze_experiment.py

@@ -0,0 +1,478 @@
+#!/usr/bin/env python3
+"""Calculate deterministic SRM and treatment-versus-control comparisons."""
+
+from __future__ import annotations
+
+import json
+import math
+import sys
+from typing import Any
+
+
+def normal_ppf(probability: float) -> float:
+    """Return the inverse standard-normal CDF using Acklam's approximation."""
+    if not 0.0 < probability < 1.0:
+        raise ValueError("probability must be between 0 and 1")
+    a = (
+        -3.969683028665376e01,
+        2.209460984245205e02,
+        -2.759285104469687e02,
+        1.383577518672690e02,
+        -3.066479806614716e01,
+        2.506628277459239e00,
+    )
+    b = (
+        -5.447609879822406e01,
+        1.615858368580409e02,
+        -1.556989798598866e02,
+        6.680131188771972e01,
+        -1.328068155288572e01,
+    )
+    c = (
+        -7.784894002430293e-03,
+        -3.223964580411365e-01,
+        -2.400758277161838e00,
+        -2.549732539343734e00,
+        4.374664141464968e00,
+        2.938163982698783e00,
+    )
+    d = (
+        7.784695709041462e-03,
+        3.224671290700398e-01,
+        2.445134137142996e00,
+        3.754408661907416e00,
+    )
+    low = 0.02425
+    high = 1.0 - low
+    if probability < low:
+        q = math.sqrt(-2.0 * math.log(probability))
+        return (
+            (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5])
+            / ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1.0)
+        )
+    if probability <= high:
+        q = probability - 0.5
+        r = q * q
+        return (
+            (((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5])
+            * q
+            / (((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1.0)
+        )
+    q = math.sqrt(-2.0 * math.log(1.0 - probability))
+    return -(
+        (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5])
+        / ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1.0)
+    )
+
+
+def regularized_gamma_q(shape: float, value: float) -> float:
+    """Return the regularized upper incomplete gamma function Q(shape, value)."""
+    if shape <= 0.0 or value < 0.0:
+        raise ValueError("invalid gamma arguments")
+    if value == 0.0:
+        return 1.0
+    epsilon = 3e-14
+    minimum = 1e-300
+    max_iterations = 10000
+    log_gamma = math.lgamma(shape)
+
+    if value < shape + 1.0:
+        term = 1.0 / shape
+        total = term
+        current = shape
+        for _ in range(max_iterations):
+            current += 1.0
+            term *= value / current
+            total += term
+            if abs(term) < abs(total) * epsilon:
+                lower = total * math.exp(-value + shape * math.log(value) - log_gamma)
+                return max(0.0, min(1.0, 1.0 - lower))
+        raise ValueError("gamma series did not converge")
+
+    b = value + 1.0 - shape
+    c = 1.0 / minimum
+    d = 1.0 / b
+    h = d
+    for iteration in range(1, max_iterations + 1):
+        coefficient = -iteration * (iteration - shape)
+        b += 2.0
+        d = coefficient * d + b
+        if abs(d) < minimum:
+            d = minimum
+        c = b + coefficient / c
+        if abs(c) < minimum:
+            c = minimum
+        d = 1.0 / d
+        delta = d * c
+        h *= delta
+        if abs(delta - 1.0) < epsilon:
+            result = math.exp(-value + shape * math.log(value) - log_gamma) * h
+            return max(0.0, min(1.0, result))
+    raise ValueError("gamma continued fraction did not converge")
+
+
+def beta_continued_fraction(a: float, b: float, x: float) -> float:
+    max_iterations = 10000
+    epsilon = 3e-14
+    minimum = 1e-300
+    qab = a + b
+    qap = a + 1.0
+    qam = a - 1.0
+    c = 1.0
+    d = 1.0 - qab * x / qap
+    if abs(d) < minimum:
+        d = minimum
+    d = 1.0 / d
+    h = d
+    for iteration in range(1, max_iterations + 1):
+        even = 2 * iteration
+        coefficient = iteration * (b - iteration) * x / ((qam + even) * (a + even))
+        d = 1.0 + coefficient * d
+        if abs(d) < minimum:
+            d = minimum
+        c = 1.0 + coefficient / c
+        if abs(c) < minimum:
+            c = minimum
+        d = 1.0 / d
+        h *= d * c
+
+        coefficient = -(a + iteration) * (qab + iteration) * x / (
+            (a + even) * (qap + even)
+        )
+        d = 1.0 + coefficient * d
+        if abs(d) < minimum:
+            d = minimum
+        c = 1.0 + coefficient / c
+        if abs(c) < minimum:
+            c = minimum
+        d = 1.0 / d
+        delta = d * c
+        h *= delta
+        if abs(delta - 1.0) < epsilon:
+            return h
+    raise ValueError("beta continued fraction did not converge")
+
+
+def regularized_beta(a: float, b: float, x: float) -> float:
+    if a <= 0.0 or b <= 0.0 or not 0.0 <= x <= 1.0:
+        raise ValueError("invalid beta arguments")
+    if x == 0.0:
+        return 0.0
+    if x == 1.0:
+        return 1.0
+    front = math.exp(
+        math.lgamma(a + b) - math.lgamma(a) - math.lgamma(b)
+        + a * math.log(x) + b * math.log(1.0 - x)
+    )
+    if x < (a + 1.0) / (a + b + 2.0):
+        return front * beta_continued_fraction(a, b, x) / a
+    return 1.0 - front * beta_continued_fraction(b, a, 1.0 - x) / b
+
+
+def student_t_two_sided_p(t_value: float, degrees_freedom: float) -> float:
+    x = degrees_freedom / (degrees_freedom + t_value * t_value)
+    return regularized_beta(degrees_freedom / 2.0, 0.5, x)
+
+
+def student_t_critical(alpha: float, degrees_freedom: float) -> float:
+    low = 0.0
+    high = 1.0
+    while student_t_two_sided_p(high, degrees_freedom) > alpha:
+        high *= 2.0
+        if high > 1e6:
+            raise ValueError("could not bracket t critical value")
+    for _ in range(100):
+        middle = (low + high) / 2.0
+        if student_t_two_sided_p(middle, degrees_freedom) > alpha:
+            low = middle
+        else:
+            high = middle
+    return (low + high) / 2.0
+
+
+def validate_groups(params: dict[str, Any]) -> list[dict[str, Any]]:
+    groups = params.get("groups")
+    if not isinstance(groups, list) or len(groups) < 2:
+        raise ValueError("groups must contain at least two groups")
+    names: set[str] = set()
+    for group in groups:
+        if not isinstance(group, dict):
+            raise ValueError("every group must be an object")
+        name = group.get("name")
+        if not isinstance(name, str) or not name:
+            raise ValueError("every group must have a non-empty name")
+        if name in names:
+            raise ValueError(f"duplicate group name: {name}")
+        names.add(name)
+    return groups
+
+
+def calculate_srm(
+    groups: list[dict[str, Any]],
+    expected_allocations: dict[str, Any],
+    alpha_srm: float,
+) -> dict[str, Any]:
+    names = [group["name"] for group in groups]
+    if set(expected_allocations) != set(names):
+        raise ValueError("expected_allocations keys must exactly match group names")
+    allocations = {name: float(expected_allocations[name]) for name in names}
+    if any(value <= 0.0 for value in allocations.values()):
+        raise ValueError("expected allocations must be positive")
+    if not math.isclose(sum(allocations.values()), 1.0, rel_tol=0.0, abs_tol=1e-9):
+        raise ValueError("expected allocations must sum to 1.0")
+
+    observed: dict[str, int] = {}
+    for group in groups:
+        assigned = group.get("assigned")
+        if isinstance(assigned, bool) or not isinstance(assigned, int) or assigned < 0:
+            raise ValueError("every group must have a non-negative integer assigned count")
+        observed[group["name"]] = assigned
+    total = sum(observed.values())
+    if total == 0:
+        raise ValueError("total assigned count must be greater than 0")
+
+    expected = {name: total * allocations[name] for name in names}
+    chi_square = sum(
+        (observed[name] - expected[name]) ** 2 / expected[name] for name in names
+    )
+    degrees_freedom = len(names) - 1
+    p_value = regularized_gamma_q(degrees_freedom / 2.0, chi_square / 2.0)
+    return {
+        "chi_square": chi_square,
+        "degrees_freedom": degrees_freedom,
+        "p_value": p_value,
+        "alpha": alpha_srm,
+        "srm_detected": p_value < alpha_srm,
+        "observed": observed,
+        "expected": expected,
+    }
+
+
+def binary_comparison(
+    control: dict[str, Any],
+    treatment: dict[str, Any],
+    alpha: float,
+) -> dict[str, Any]:
+    n0 = int(control.get("sample_size", 0))
+    n1 = int(treatment.get("sample_size", 0))
+    x0 = int(control.get("successes", -1))
+    x1 = int(treatment.get("successes", -1))
+    if n0 <= 0 or n1 <= 0:
+        raise ValueError("binary sample_size must be greater than 0")
+    if not 0 <= x0 <= n0 or not 0 <= x1 <= n1:
+        raise ValueError("binary successes must be between 0 and sample_size")
+    p0 = x0 / n0
+    p1 = x1 / n1
+    difference = p1 - p0
+    pooled = (x0 + x1) / (n0 + n1)
+    pooled_se = math.sqrt(pooled * (1.0 - pooled) * (1.0 / n0 + 1.0 / n1))
+    if pooled_se == 0.0:
+        z_value = 0.0 if difference == 0.0 else math.copysign(math.inf, difference)
+        p_value = 1.0 if difference == 0.0 else 0.0
+    else:
+        z_value = difference / pooled_se
+        p_value = math.erfc(abs(z_value) / math.sqrt(2.0))
+    interval_se = math.sqrt(
+        p0 * (1.0 - p0) / n0 + p1 * (1.0 - p1) / n1
+    )
+    critical = normal_ppf(1.0 - alpha / 2.0)
+    relative_lift = None if p0 == 0.0 else difference / p0
+    return {
+        "control_value": p0,
+        "treatment_value": p1,
+        "absolute_difference": difference,
+        "relative_lift": relative_lift,
+        "test": "two_sided_pooled_two_proportion_z",
+        "statistic": z_value,
+        "p_value": p_value,
+        "confidence_interval_absolute": [
+            difference - critical * interval_se,
+            difference + critical * interval_se,
+        ],
+    }
+
+
+def continuous_comparison(
+    control: dict[str, Any],
+    treatment: dict[str, Any],
+    alpha: float,
+) -> dict[str, Any]:
+    n0 = int(control.get("sample_size", 0))
+    n1 = int(treatment.get("sample_size", 0))
+    mean0 = float(control.get("mean"))
+    mean1 = float(treatment.get("mean"))
+    sd0 = float(control.get("standard_deviation"))
+    sd1 = float(treatment.get("standard_deviation"))
+    if n0 < 2 or n1 < 2:
+        raise ValueError("continuous sample_size must be at least 2")
+    if sd0 < 0.0 or sd1 < 0.0:
+        raise ValueError("standard_deviation must be non-negative")
+    variance0 = sd0 * sd0 / n0
+    variance1 = sd1 * sd1 / n1
+    standard_error = math.sqrt(variance0 + variance1)
+    difference = mean1 - mean0
+    if standard_error == 0.0:
+        t_value = 0.0 if difference == 0.0 else math.copysign(math.inf, difference)
+        p_value = 1.0 if difference == 0.0 else 0.0
+        degrees_freedom = math.inf
+        critical = normal_ppf(1.0 - alpha / 2.0)
+    else:
+        t_value = difference / standard_error
+        denominator = (
+            variance0 * variance0 / (n0 - 1)
+            + variance1 * variance1 / (n1 - 1)
+        )
+        degrees_freedom = (
+            math.inf if denominator == 0.0 else (variance0 + variance1) ** 2 / denominator
+        )
+        if math.isinf(degrees_freedom):
+            p_value = math.erfc(abs(t_value) / math.sqrt(2.0))
+            critical = normal_ppf(1.0 - alpha / 2.0)
+        else:
+            p_value = student_t_two_sided_p(t_value, degrees_freedom)
+            critical = student_t_critical(alpha, degrees_freedom)
+    relative_lift = None if mean0 == 0.0 else difference / mean0
+    return {
+        "control_value": mean0,
+        "treatment_value": mean1,
+        "absolute_difference": difference,
+        "relative_lift": relative_lift,
+        "test": "two_sided_welch_t",
+        "statistic": t_value,
+        "degrees_freedom": degrees_freedom,
+        "p_value": p_value,
+        "confidence_interval_absolute": [
+            difference - critical * standard_error,
+            difference + critical * standard_error,
+        ],
+    }
+
+
+def calculate(params: dict[str, Any]) -> dict[str, Any]:
+    groups = validate_groups(params)
+    metric_type = params.get("metric_type")
+    if metric_type not in {"binary", "continuous"}:
+        raise ValueError("metric_type must be binary or continuous")
+    control_name = params.get("control")
+    by_name = {group["name"]: group for group in groups}
+    if control_name not in by_name:
+        raise ValueError("control must match one group name")
+
+    alpha = float(params.get("alpha", 0.05))
+    alpha_srm = float(params.get("alpha_srm", 0.01))
+    if not 0.0 < alpha < 0.5 or not 0.0 < alpha_srm < 0.5:
+        raise ValueError("alpha and alpha_srm must be between 0 and 0.5")
+    multiple_testing = params.get("multiple_testing", "bonferroni")
+    if multiple_testing not in {"bonferroni", "none"}:
+        raise ValueError("multiple_testing must be bonferroni or none")
+
+    srm = None
+    expected_allocations = params.get("expected_allocations")
+    if expected_allocations is not None:
+        if not isinstance(expected_allocations, dict):
+            raise ValueError("expected_allocations must be an object")
+        srm = calculate_srm(groups, expected_allocations, alpha_srm)
+
+    control = by_name[control_name]
+    comparisons: list[dict[str, Any]] = []
+    number_of_comparisons = len(groups) - 1
+    comparison_alpha = (
+        alpha / number_of_comparisons
+        if multiple_testing == "bonferroni"
+        else alpha
+    )
+    for treatment in groups:
+        if treatment["name"] == control_name:
+            continue
+        result = (
+            binary_comparison(control, treatment, comparison_alpha)
+            if metric_type == "binary"
+            else continuous_comparison(control, treatment, comparison_alpha)
+        )
+        difference = result["absolute_difference"]
+        significant = result["p_value"] < comparison_alpha
+        if significant and difference > 0:
+            classification = "statistically_significant_positive"
+        elif significant and difference < 0:
+            classification = "statistically_significant_negative"
+        else:
+            classification = "inconclusive_at_selected_alpha"
+        result.update(
+            {
+                "control": control_name,
+                "treatment": treatment["name"],
+                "comparison_alpha": comparison_alpha,
+                "statistically_significant": significant,
+                "classification": classification,
+            }
+        )
+        comparisons.append(result)
+
+    exposure_coverage: dict[str, float] = {}
+    for group in groups:
+        assigned = group.get("assigned")
+        sample_size = group.get("sample_size")
+        if (
+            isinstance(assigned, int)
+            and assigned > 0
+            and isinstance(sample_size, int)
+            and sample_size >= 0
+        ):
+            exposure_coverage[group["name"]] = sample_size / assigned
+
+    warnings: list[str] = []
+    if len(comparisons) > 1 and multiple_testing == "none":
+        warnings.append(
+            "P-values are unadjusted across treatments; confirm that this matches the pre-registered policy."
+        )
+    if srm and srm["srm_detected"]:
+        warnings.append(
+            "SRM was detected from assignment counts; diagnose allocation before using causal comparisons."
+        )
+
+    return {
+        "ok": True,
+        "data": {
+            "metric_type": metric_type,
+            "control": control_name,
+            "familywise_alpha": alpha,
+            "multiple_testing": multiple_testing,
+            "comparison_alpha": comparison_alpha,
+            "srm": srm,
+            "exposure_coverage": exposure_coverage,
+            "comparisons": comparisons,
+            "warnings": warnings,
+        },
+    }
+
+
+def main() -> int:
+    try:
+        if len(sys.argv) != 2:
+            raise ValueError("usage: analyze_experiment.py '<json-object>'")
+        raw = sys.argv[1]
+        params = json.load(sys.stdin) if raw == "-" else json.loads(raw)
+        if not isinstance(params, dict):
+            raise ValueError("input must be a JSON object")
+        print(json.dumps(calculate(params), ensure_ascii=False, indent=2, allow_nan=False))
+        return 0
+    except (ValueError, TypeError, KeyError, json.JSONDecodeError) as error:
+        print(
+            json.dumps(
+                {
+                    "ok": False,
+                    "error": {
+                        "type": "validation",
+                        "code": "INVALID_INPUT",
+                        "message": str(error),
+                    },
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/ae-project-semantic/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: ae-project-semantic
+description: "Use when generating, testing, submitting, reviewing, or publishing governed project semantic candidates from AE/TE project asset packages. This skill owns progressive asset-scope consent, recommendation quality gates, evidence authority, topic-domain grouping, candidate JSON generation, CLI closed-loop validation, and frontend review acceptance. Do not use it for ordinary analysis questions that only consume already published semantics."
+---
+
+# ae-project-semantic
+
+Project semantics are governed L2 project-wide business concepts, rules, calculation conventions, and default asset-selection methods. They sit above dashboards and reports. Dashboards, reports, events, properties, and metrics are L1 evidence and execution assets; they are not project semantics by themselves.
+
+Use `ae-cli` only. Do not write the database directly for recommendations, approvals, or releases.
+
+## Boundary
+
+- Use this skill to generate or evaluate project semantic recommendations.
+- Use `ae-analysis` to consume already published project semantics during analysis tasks.
+- Frontend can review, edit, approve, reject, and publish candidates; it must not generate recommendations.
+- Start with governed authenticated dashboards/reports. Broader project assets may be inspected only after explicit user consent and must retain their lower authority in evidence and confidence. Events, properties, metrics, background documents, and notes can provide supporting evidence only, never the primary L2 candidate subject.
+
+## Required Workflow
+
+1. Resolve the project and host.
+2. Read both recommendation references before inspecting candidates:
+   - [`references/recommendation-quality.md`](references/recommendation-quality.md) for the governed L2 quality bar;
+   - [`references/query-routing-v5.md`](references/query-routing-v5.md) for the current query-routing, recall-shortcut, and analysis-playbook discovery protocol.
+3. Check existing published project semantics:
+
+```bash
+ae-cli project-semantic list --project-id <project_id>
+```
+
+4. Export governed authenticated project assets and semantic snapshot context by default:
+
+```bash
+ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope governed --output <tmp>/project-semantic-assets --force
+```
+
+When `--host` points directly to a locally started Common service instead of the deployed analysis gateway, scope the empty gateway domain to that command so the request uses Common's native `/api/cli/v1` route. Do not export this override globally:
+
+```bash
+AE_CLI_CAPABILITY_GATEWAY_DOMAIN= ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope governed --output <tmp>/project-semantic-assets --force --host http://127.0.0.1:8992
+```
+
+5. Inspect `asset_scope`, `exported_asset_count`, `authenticated_asset_count`, `unauthenticated_asset_count`, `truncated`, work-unit count, and definition-family count before scanning. If `truncated=true`, warn that the package hit a compatibility limit. If the governed package is too sparse to support useful problem frames, report the actual counts and ask whether to re-export active collaborative assets. Do not broaden automatically:
+
+```bash
+ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope collaborative --output <tmp>/project-semantic-assets --force
+```
+
+If that package is still too sparse, report its counts and ask separately whether to export all valid project dashboards/reports and their referenced metadata:
+
+```bash
+ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope all_visible --output <tmp>/project-semantic-assets --force
+```
+
+`governed` is authenticated + collaborative + active in the recent 90-day window. `collaborative` removes only the authentication requirement. `all_visible` removes authentication, collaboration, and recency filters while still excluding deleted, frozen, hidden, offline, or otherwise invalid assets. Export is project-administrator-only; no per-user visibility filtering is required inside `all_visible`. Asset authentication is a separate governance write and must never be changed implicitly by scanning.
+
+6. Read the package in this order:
+   - `manifest.json`, `.asset-package.json`, `catalog/published.jsonl`, `catalog/disabled.jsonl` when present, `catalog/active-candidates.jsonl`, and `catalog/rejected-candidates.jsonl` to build the exclusion and revision context;
+   - `indexes/work-units.jsonl` as the dashboard-first investigation queue, preserving its usage-priority order while rotating across distinct business themes;
+   - `indexes/definition-families.jsonl` and compact dashboard/report records to compare reusable definition variants;
+   - `indexes/asset-directory.jsonl` and `indexes/governance-coverage.jsonl` for supporting evidence;
+   - `details/normalized/**` only for candidate-bearing or conflicting families, and `details/raw/**` only when the normalized definition is insufficient.
+
+   The service owns deterministic parsing, key-field normalization, definition signatures, usage ordering, and catalog assembly. The Agent owns business topic discovery, evidence interpretation, counterexample review, and candidate wording. Display names, descriptions, and notes remain evidence for interpretation, but they never make two otherwise identical definitions distinct. Do not load every detail file into context up front or delegate business judgment to a project-specific keyword table or deterministic template generator.
+
+7. Compare the proposed behavior against published, disabled, active-candidate, and rejected catalogs. Disabled semantics are suppression context: do not consume, recreate, or update them through recommendation generation. A project administrator can explicitly enable them later. Produce `CREATE` only for a genuinely new semantic, `UPDATE` when an active semantic needs a material revision, and no candidate when the package is already covered. Zero new candidates is a valid successful recommendation result.
+
+8. Validate the Agent-authored file against the exact exported package. This command checks only deterministic contract rules such as required fields, supported enums, catalog conflicts, duplicate fingerprints, and resolvable evidence references. `passed=true` is not a semantic-quality approval:
+
+```bash
+ae-cli project-semantic candidate validate --asset-package <tmp>/project-semantic-assets --submit-file <tmp>/project-semantic-candidates.json
+```
+
+9. Perform a separate Agent quality-review pass over the unchanged candidate file and the evidence it cites. Apply the Hard Quality Bar and `references/recommendation-quality.md`; do not rely on the generation pass to approve its own wording. For every candidate, record `PASS`, `REVISE`, or `INSUFFICIENT_EVIDENCE` with concrete findings and evidence references. Revise and repeat both deterministic validation and Agent review until every submitted candidate is `PASS`. A successful empty recommendation is preferable to weak filler.
+
+10. Submit the unchanged validated and Agent-reviewed file. Use `.asset-package.json.snapshot_hash`, or the `snapshot_hash` returned by `candidate validate`:
+
+```bash
+ae-cli project-semantic candidate submit --project-id <project_id> --submit-file <tmp>/project-semantic-candidates.json --snapshot-hash <snapshot_hash>
+```
+
+11. Review and enable through CLI when validating the full closed loop:
+
+```bash
+ae-cli project-semantic candidate list --project-id <project_id>
+ae-cli project-semantic candidate get --project-id <project_id> --candidate-id <candidate_id>
+ae-cli project-semantic candidate enable --project-id <project_id> --candidate-ids '["candidate_1"]'
+ae-cli project-semantic get --project-id <project_id> --id <semantic_id> --mark-used
+```
+
+Lifecycle management is deliberately separate from recommendation review:
+
+```bash
+ae-cli project-semantic disable --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>
+ae-cli project-semantic list --project-id <project_id> --status disabled
+ae-cli project-semantic delete-impact --project-id <project_id> --semantic-id <semantic_id>
+ae-cli project-semantic delete --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>
+ae-cli project-semantic enable --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>
+```
+
+Disable means “do not consume and do not recommend again.” From disabled state, either enable the same semantic or inspect impact and physically delete it. Physical deletion means the semantic is absent and may be rediscovered by a future scan. Never delete merely to regenerate recommendations.
+
+## Hard Quality Bar
+
+A candidate file is not acceptable unless all of these are true:
+
+- It starts from governed evidence, or records the explicitly approved broader scope and lowers confidence for claims that depend on unauthenticated assets.
+- It groups by L2 business topic domain before generating candidates.
+- Every topic group includes the submit-contract fields `topic_domain_key`, `topic_domain_title`, `topic_group_key`, and `topic_group_title`.
+- It does not create one candidate per asset.
+- It does not promote an event/property/metric name into a project semantic title.
+- Each candidate binds `resource_refs` with real asset names/types/ids or names from the package.
+- Each candidate explains what it means, where it applies, how to use it, and what it excludes.
+- Each candidate body covers business definition, applicable questions, decision or calculation rules, Agent usage, and boundaries or exceptions in the project's natural language. Exact headings are not a machine contract.
+- The concrete business judgment belongs in the decision or calculation content; asset names and counts belong in `resource_refs`, `evidence`, and `recommendation_reason`, not in the semantic body.
+- A batch fails review when candidates reuse the same body with only asset names or counts changed.
+- Each candidate includes evidence excerpts or source titles that show why it was recommended.
+- Each candidate changes how the Agent interprets a business question, selects default assets, or applies a project-wide rule.
+- Each candidate declares one of the evidence-backed recommendation kinds in `query-routing-v5.md`: `QUERY_ROUTING`, `RECALL_SHORTCUT`, or `ANALYSIS_PLAYBOOK`.
+- A formula, threshold, state, event, property, report, or asset name is supporting L1 evidence, never a standalone candidate.
+- A route must contain a meaningful asset-choice branch; a shortcut must contain a minimal bundle plus stop and fallback; a playbook must be note-backed or explicitly labeled as a structure-inferred recommended path.
+- Existing published and disabled semantics are checked before submission; disabled semantics suppress recreation.
+- An unauthenticated asset may support a route, shortcut, or playbook only when definitions, work-unit structure, usage, or notes provide corroboration. Never present it as a certified project rule solely because it was exported.
+- Sparse evidence is either skipped or marked lower confidence; do not inflate weak recommendations.
+
+## Generic Extraction Protocol
+
+The protocol must work unchanged for games, retail, finance, SaaS, operations, and unknown project domains.
+
+1. Inventory evidence without deciding themes. Separate authenticated and unauthenticated dashboards/reports, record the export scope and selection reason, and keep existing governed semantics and supporting L1 metadata distinct.
+2. Discover semantic families only from evidence that was actually read. Use these cross-domain dimensions as questions, not as prefilled answers:
+   - business object, state, and alias;
+   - analysis subject and deduplication grain;
+   - measure, aggregation, numerator, denominator, and transformation;
+   - inclusion, exclusion, and filter scope;
+   - query range, cohort window, observation window, and freshness;
+   - unit, currency, normalization, and attribution;
+   - default asset selection and relationships between assets;
+   - applicability, exception, and conflict boundaries.
+3. Compare definition variants inside each family. A candidate may state a default only when evidence shows one authoritative variant. Conflicting variants require a disambiguation rule or a warning, not an invented standard.
+4. Form a topic domain after the semantic families are understood. The domain title must come from the project's natural business language and explain why its candidates are reviewed together.
+5. Generate a candidate only when removing it would make a future Agent more likely to choose the wrong business object, asset, grain, formula, scope, unit, window, or exception.
+6. For every claim in the body, identify direct supporting evidence. Keep asset names and excerpts in `resource_refs`, `evidence`, and `recommendation_reason`; keep reusable business knowledge in `content`.
+7. Compare candidates by resulting Agent behavior. Merge candidates that lead to the same interpretation and execution; split candidates that answer independently searchable questions.
+8. Run a counterexample pass: inspect minority definitions and assets that may violate the proposed rule. Narrow or drop unsupported conclusions.
+9. Before wording candidates, form evidence-backed problem frames and assign asset roles. Use `query-routing-v5.md`; do not optimize for candidate count or one-candidate-per-asset coverage.
+10. Keep a decision ledger for discovered problem frames, including routed, shortcut, playbook, definition-only, and evidence-insufficient dispositions.
+
+## Anti-Overfitting Rule
+
+- Never encode a customer, project name, project ID, asset ID, expected topic title, expected candidate title, or expected candidate count in this skill or CLI generation code.
+- Never start from a fixed industry taxonomy or keyword dictionary. Keywords may locate evidence only after a semantic family is discovered; they must not determine the result.
+- A test package is an evaluation sample, not a source of reusable rules. Tune the protocol only when the change is defensible across unrelated domains.
+- Quality is measured by evidence support and changed Agent behavior, not by matching a previously approved list of topics.
+
+## User-Facing Recommendation Display
+
+When showing CLI recommendation results to a user, never flatten candidates into a single numbered list. The user-facing answer must use the same hierarchy as the candidate JSON and frontend review UI:
+
+```text
+Project semantic recommendation scan completed
+
+Summary:
+- Topic domains: <N>
+- Candidate semantics: <N>
+- Validation: passed | failed
+
+Topic domain: <topic_domain_title> (<candidate_count> semantics)
+- [<semantic_type>] <candidate title>
+  <one-sentence summary>
+  Evidence: <asset title 1>, <asset title 2>, ...
+```
+
+Rules:
+
+- Show topic domains first, then candidates under each domain.
+- Include each domain's semantic count.
+- Include each candidate's semantic type, title, short summary, and primary evidence asset titles.
+- If the CLI command returns `topic_groups`, use that field directly for the display order and counts.
+- Keep the full JSON path or submit command separate from the human summary.
+- Do not present a flat list like `1. semantic A 2. semantic B ...` unless the user explicitly asks for raw candidate order.
+
+## Output Discipline
+
+When reporting recommendation results, include:
+
+- commands run;
+- asset scope, exported/authenticated/unauthenticated asset counts, and snapshot hash;
+- topic domains, semantic counts per domain, and candidate titles grouped under each domain;
+- evidence assets per candidate;
+- quality warnings, if any;
+- problem-frame coverage and rejected shallow-opportunity warnings;
+- submit/review/release IDs after writes.