cassis-cli 1.6.0__tar.gz → 1.7.0__tar.gz

{cassis_cli-1.6.0 → cassis_cli-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 1.6.0
+Version: 1.7.0
 Summary: Validate, test and evaluate your Cassis ontology from your terminal, then publish it
 License: Apache-2.0
 License-File: LICENSE
@@ -132,6 +132,11 @@ cassis schema push schema.sql
 # List the projects the API key can reach (id, name, published version, dialect):
 cassis projects list
 
+# Refresh the issues from the conversations nobody has analyzed yet (the same pass as the
+# webapp's "Analyze conversations" button; waits for the result, --no-wait returns at once,
+# and Ctrl-C cancels the run server-side and exits 130):
+cassis issues analyze
+
 # Triage the issues Cassis raised (filter by --status/--impact/--cause; --json for raw output):
 cassis issues list --status open
 cassis issues show 019f0000-0000-7000-8000-0000000000e1
@@ -190,9 +195,9 @@ cassis ontology fmt --check
 | Code | Meaning                                                                        |
 | ---- | ------------------------------------------------------------------------------ |
 | 0    | Ontology is valid (check) / pulled (pull) / uploaded (upload) / eval run completed all-passed (eval run) / every probe completed (test — whatever its outcome; probes are informational, don't gate CI on them) |
-| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; schema push: failed or cancelled detection run, or the project won't accept the push (a run is already in flight, or it is warehouse-connected rather than DDL-only); source-changes show: no such change in the project) |
+| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema push: failed or cancelled detection run, or the project won't accept the push (a run is already in flight, or it is warehouse-connected rather than DDL-only); source-changes show: no such change in the project) |
 | 2    | Usage error (missing API key or project, no ontology directory, unreadable file, tree over the size limits) |
-| 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another eval run already active, out of credits, or `--timeout` reached |
+| 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another eval run or issue analysis already active, out of credits, or `--timeout` reached |
 
 Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
 20,000 ontology files / 100 MB total (path + content bytes) — sized for ontologies of

{cassis_cli-1.6.0 → cassis_cli-1.7.0}/README.md

@@ -110,6 +110,11 @@ cassis schema push schema.sql
 # List the projects the API key can reach (id, name, published version, dialect):
 cassis projects list
 
+# Refresh the issues from the conversations nobody has analyzed yet (the same pass as the
+# webapp's "Analyze conversations" button; waits for the result, --no-wait returns at once,
+# and Ctrl-C cancels the run server-side and exits 130):
+cassis issues analyze
+
 # Triage the issues Cassis raised (filter by --status/--impact/--cause; --json for raw output):
 cassis issues list --status open
 cassis issues show 019f0000-0000-7000-8000-0000000000e1
@@ -168,9 +173,9 @@ cassis ontology fmt --check
 | Code | Meaning                                                                        |
 | ---- | ------------------------------------------------------------------------------ |
 | 0    | Ontology is valid (check) / pulled (pull) / uploaded (upload) / eval run completed all-passed (eval run) / every probe completed (test — whatever its outcome; probes are informational, don't gate CI on them) |
-| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; schema push: failed or cancelled detection run, or the project won't accept the push (a run is already in flight, or it is warehouse-connected rather than DDL-only); source-changes show: no such change in the project) |
+| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema push: failed or cancelled detection run, or the project won't accept the push (a run is already in flight, or it is warehouse-connected rather than DDL-only); source-changes show: no such change in the project) |
 | 2    | Usage error (missing API key or project, no ontology directory, unreadable file, tree over the size limits) |
-| 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another eval run already active, out of credits, or `--timeout` reached |
+| 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another eval run or issue analysis already active, out of credits, or `--timeout` reached |
 
 Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
 20,000 ontology files / 100 MB total (path + content bytes) — sized for ontologies of

{cassis_cli-1.6.0 → cassis_cli-1.7.0}/cassis_cli/api.py

@@ -635,7 +635,11 @@ def post_eval_run_cancel(
 
 
 class IssueNotFoundError(ApiError):
-    """The project has no issue (or occurrence) with this id."""
+    """The project has no issue, occurrence or issue-analysis run with this id.
+
+    Raised off the server's exact 404 detail, so it separates "this id doesn't
+    exist" from "this project isn't in scope for your key", which 404s too.
+    """
 
 
 def _get_issue_json(
@@ -645,8 +649,14 @@ def _get_issue_json(
     *,
     params: Optional[dict[str, str]] = None,
     not_found_message: Optional[str] = None,
+    not_found_detail: str = "Issue not found",
 ) -> Any:
-    """GET an issues URL with the shared error mapping."""
+    """GET an issues URL with the shared error mapping.
+
+    `not_found_detail` is the server's exact 404 detail for "this id does not
+    exist in the project" — `"Issue not found"` for issues and occurrences,
+    `"Issue-analysis run not found"` for analysis runs.
+    """
     try:
         with _client(transport=transport) as client:
             response = client.get(url, params=params, headers={"Authorization": f"Bearer {api_key}"})
@@ -657,8 +667,8 @@ def _get_issue_json(
         raise AuthError("The Cassis API rejected the API key (invalid or expired).")
     # Exact-match wire contract with the issue endpoints' 404 detail (see the
     # issue routes in backend/app/endpoints/ci.py): it distinguishes a missing
-    # issue or occurrence (exit 1) from a project-scope 404 (exit 3).
-    if response.status_code == 404 and not_found_message and _detail_or_text(response) == "Issue not found":
+    # issue, occurrence or run (exit 1) from a project-scope 404 (exit 3).
+    if response.status_code == 404 and not_found_message and _detail_or_text(response) == not_found_detail:
         raise IssueNotFoundError(not_found_message)
     if response.status_code in (403, 404):
         raise _project_scope_error(response)
@@ -925,3 +935,102 @@ def post_ontology_test(
     if not isinstance(result, dict) or "status" not in result:
         raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
     return result
+
+
+class IssueAnalysisActiveError(ApiError):
+    """An issue-analysis run is already in flight for the project (HTTP 409)."""
+
+
+class NothingToAnalyzeError(ApiError):
+    """Every conversation on the project has already been analyzed (HTTP 422)."""
+
+
+_ANALYSIS_RUN_KEYS = ("id", "status", "total_chats", "chats_analyzed", "occurrences_created", "issues_touched")
+
+
+def _check_analysis_run_shape(result: Any, url: str) -> dict[str, Any]:
+    if not isinstance(result, dict) or not all(key in result for key in _ANALYSIS_RUN_KEYS):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def post_issue_analysis_start(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST /api/ci/projects/{project_id}/issue-analysis/runs and return the run record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issue-analysis/runs"
+    try:
+        with _client(transport=transport) as client:
+            response = client.post(url, headers={"Authorization": f"Bearer {api_key}"})
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    if response.status_code == 409:
+        raise IssueAnalysisActiveError(
+            "An issue analysis is already running for this project — wait for it to finish, "
+            "or cancel it from the webapp's Issues page."
+        )
+    if response.status_code == 422 and "analyz" in response.text.lower():
+        # The route takes no body, so its 422 is the server's "nothing to
+        # analyze" answer; any other 422 falls through to the generic error.
+        raise NothingToAnalyzeError("Nothing to analyze: every conversation on this project has already been analyzed.")
+    if response.status_code in (403, 404):
+        raise _project_scope_error(response)
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+    return _check_analysis_run_shape(_parse_json_response(response, url), url)
+
+
+def get_issue_analysis_run(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    run_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """GET /api/ci/projects/{project_id}/issue-analysis/runs/{run_id} and return the run record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issue-analysis/runs/{run_id}"
+    return _check_analysis_run_shape(
+        _get_issue_json(
+            url,
+            api_key,
+            transport,
+            not_found_message=f"No issue-analysis run {run_id} in this project.",
+            not_found_detail="Issue-analysis run not found",
+        ),
+        url,
+    )
+
+
+def post_issue_analysis_cancel(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    run_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> None:
+    """POST /api/ci/projects/{project_id}/issue-analysis/runs/{run_id}/cancel."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issue-analysis/runs/{run_id}/cancel"
+    try:
+        with _client(transport=transport) as client:
+            response = client.post(url, headers={"Authorization": f"Bearer {api_key}"})
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    # Same exact-match contract as `get_issue_analysis_run`: a missing run is
+    # not a project-scope problem.
+    if response.status_code == 404 and _detail_or_text(response) == "Issue-analysis run not found":
+        raise IssueNotFoundError(f"No issue-analysis run {run_id} in this project.")
+    if response.status_code in (403, 404):
+        raise _project_scope_error(response)
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")

{cassis_cli-1.6.0 → cassis_cli-1.7.0}/cassis_cli/common.py

@@ -20,6 +20,9 @@ EXIT_OK = 0
 EXIT_VALIDATION_FAILED = 1
 EXIT_USAGE = 2
 EXIT_TRANSPORT = 3
+# Conventional "terminated by SIGINT" code: the user pressed Ctrl-C while a
+# command was waiting on a server-side run (which the command cancels first).
+EXIT_INTERRUPTED = 130
 
 # Request ceilings of the /api/ci file-tree endpoints, mirrored so oversized
 # trees fail fast with a clear message before any upload. Sized for ~10,000

{cassis_cli-1.6.0 → cassis_cli-1.7.0}/cassis_cli/eval.py

@@ -30,6 +30,7 @@ from cassis_cli.api import (
 )
 from cassis_cli.common import (
     DEFAULT_BASE_PATH,
+    EXIT_INTERRUPTED,
     EXIT_OK,
     EXIT_TRANSPORT,
     EXIT_USAGE,
@@ -41,7 +42,6 @@ from cassis_cli.common import (
 
 app = typer.Typer(no_args_is_help=True, help="Eval commands.")
 
-EXIT_INTERRUPTED = 130
 
 # Result statuses that count as "passed"; everything else is a failure or error.
 _PASSED = "passed"
@@ -134,6 +134,9 @@ def _print_results_table(results: list[dict[str, Any]]) -> None:
 
 def _print_summary(run: dict[str, Any]) -> None:
     summary = run.get("summary") or {}
+    if summary.get("error"):
+        # A failed run carries its reason here (e.g. the worker was lost).
+        typer.secho(f"Run error: {str(summary['error'])[:300]}", fg=typer.colors.RED)
     total = summary.get("total", run.get("total_cases"))
     passed = summary.get("passed", 0)
     accuracy = summary.get("accuracy")
@@ -498,7 +501,8 @@ def run(
             typer.echo(f"Follow it at: {run_url}")
         raise typer.Exit(EXIT_OK)
 
-    typer.echo(f"Eval run {run_id} started: {total} cases against {ontology_label!r}.")
+    # To stderr under --json so `cassis eval run --json | jq` gets only the record.
+    typer.echo(f"Eval run {run_id} started: {total} cases against {ontology_label!r}.", err=json_output)
 
     try:
         final_run, results = _wait_for_run(
@@ -509,13 +513,15 @@ def run(
             total=total,
             poll_interval=poll_interval,
             timeout=timeout,
+            json_output=json_output,
         )
     except KeyboardInterrupt:
-        typer.echo("")
-        typer.echo("Interrupted — cancelling the run...")
+        # To stderr under --json, for the same reason as `issues analyze`.
+        typer.echo("", err=json_output)
+        typer.echo("Interrupted — cancelling the run...", err=json_output)
         try:
             post_eval_run_cancel(api_url=api_url, api_key=api_key, project_id=project_id, run_id=run_id)
-            typer.echo("Run cancelled.")
+            typer.echo("Run cancelled.", err=json_output)
         except ApiError as exc:
             typer.secho(f"Could not cancel the run: {exc}", fg=typer.colors.RED, err=True)
         raise typer.Exit(EXIT_INTERRUPTED)
@@ -550,9 +556,12 @@ def _wait_for_run(
     total: int,
     poll_interval: float,
     timeout: float,
+    json_output: bool = False,
 ) -> "tuple[dict[str, Any], list[dict[str, Any]]]":
     """Poll the run until terminal. Returns (run, results).
 
+    Progress lines go to stderr under --json so stdout stays the JSON record.
+
     Exits 3 directly on timeout, on an auth failure (fail fast — retrying a
     revoked key can't succeed), or after several consecutive poll failures.
     The server-side run keeps going in all three cases.
@@ -587,7 +596,7 @@ def _wait_for_run(
         passed = sum(1 for r in results if r.get("status") == _PASSED)
         line = f"{done}/{total} cases done — {passed} ✓ {done - passed} ✗"
         if line != last_line:
-            typer.echo(line)
+            typer.echo(line, err=json_output)
             last_line = line
 
         if run_record.get("status") in _TERMINAL_RUN_STATUSES:

{cassis_cli-1.6.0 → cassis_cli-1.7.0}/cassis_cli/guide.py

@@ -31,7 +31,7 @@ GUIDE_FILENAME = "AGENTS.md"
 # Monotonic version of the doctrine text below. Bump it whenever
 # ontology_design_guide.md changes (a backend test enforces the pairing) — it
 # is what lets an older writer recognize a newer guide and leave it alone.
-DOCTRINE_VERSION = 5
+DOCTRINE_VERSION = 6
 
 # Must stay byte-identical to backend/app/services/ontology_guide.py::_BANNER —
 # the server-side git export writes the same file, and differing banners would

{cassis_cli-1.6.0 → cassis_cli-1.7.0}/cassis_cli/issues.py

@@ -3,12 +3,14 @@
 Issues are what the product found wrong while answering questions (an ontology
 gap, missing data). Listing, reading the evidence behind an occurrence, and
 resolving or dismissing them from a checkout keeps the fix loop next to the
-ontology files instead of in the webapp.
+ontology files instead of in the webapp; `analyze` refreshes them from the
+conversations that arrived since the last pass, without waiting for the nightly one.
 """
 
 from __future__ import annotations
 
 import json
+import time
 from pathlib import Path
 from typing import Any, Optional
 
@@ -18,14 +20,20 @@ from cassis_cli.api import (
     ApiError,
     AuthError,
     IssueNotFoundError,
+    NothingToAnalyzeError,
     get_issue,
+    get_issue_analysis_run,
     get_issue_evidence,
     get_issues,
+    post_issue_analysis_cancel,
+    post_issue_analysis_start,
     post_issue_status,
 )
 from cassis_cli.common import (
     DEFAULT_BASE_PATH,
+    EXIT_INTERRUPTED,
     EXIT_OK,
+    EXIT_TRANSPORT,
     EXIT_USAGE,
     EXIT_VALIDATION_FAILED,
     api_failure,
@@ -288,7 +296,7 @@ def resolve(
     api_url: str = _API_URL_OPTION,
     base_path: str = _BASE_PATH_OPTION,
 ) -> None:
-    """Mark an issue resolved — the ontology change that fixes it has landed.
+    """Mark an issue resolved — the ontology change that fixes it is published.
 
     Exits 0 on success, 1 when the issue does not exist in the project, 2 on
     usage errors, 3 on transport/API errors.
@@ -352,3 +360,178 @@ def reopen(
         api_url=api_url,
         base_path=base_path,
     )
+
+
+_TERMINAL_ANALYSIS_STATUSES = frozenset({"completed", "failed", "cancelled"})
+
+# Consecutive poll failures tolerated before giving up — same tolerance as
+# `eval run`: a transient blip must not abandon a multi-minute run, a
+# permanently broken poll must not spin until --timeout.
+_MAX_CONSECUTIVE_POLL_FAILURES = 5
+
+
+@app.command()
+def analyze(
+    path: Path = _PATH_OPTION,
+    project_id: Optional[str] = _PROJECT_OPTION,
+    api_key: Optional[str] = _API_KEY_OPTION,
+    api_url: str = _API_URL_OPTION,
+    base_path: str = _BASE_PATH_OPTION,
+    wait: bool = typer.Option(
+        True,
+        "--wait/--no-wait",
+        help="Wait for the analysis to finish and print its summary (default), or just print the run id.",
+    ),
+    poll_interval: float = typer.Option(5.0, "--poll-interval", help="Seconds between status polls."),
+    timeout: float = typer.Option(1800.0, "--timeout", help="Give up waiting after this many seconds."),
+    json_output: bool = typer.Option(False, "--json", help="Print the final run record as raw JSON."),
+) -> None:
+    """Analyze the conversations nobody has analyzed yet, turning what went wrong into issues.
+
+    The same pass as the webapp's "Analyze conversations" button — it runs on
+    Cassis's workers, so a Ctrl-C or a lost connection never kills it — started
+    on demand instead of waiting for the nightly one. When every conversation is
+    already analyzed the command is a no-op and exits 0, so a job re-running it
+    on a quiet project stays green. Exits 0 when the run completes, 1 when it
+    fails or is cancelled, 2 on usage errors, 3 on transport errors, when a run
+    is already in flight, or on --timeout (the run keeps going server-side).
+    Ctrl-C cancels the run and exits 130.
+    """
+    api_key = require_api_key(api_key)
+    project_id = resolve_project_id(project_id, path / Path(base_path), quiet=json_output)
+
+    try:
+        run = post_issue_analysis_start(api_url=api_url, api_key=api_key, project_id=project_id)
+    except NothingToAnalyzeError as exc:
+        if json_output:
+            typer.echo(json.dumps({"run": None, "message": str(exc)}, indent=2))
+        else:
+            typer.echo(str(exc))
+        raise typer.Exit(EXIT_OK) from exc
+    except (AuthError, ApiError) as exc:  # covers IssueAnalysisActiveError too
+        raise api_failure(exc) from exc
+
+    run_id = str(run["id"])
+    total = int(run.get("total_chats") or 0)
+
+    if not wait:
+        if json_output:
+            typer.echo(json.dumps({"run": run}, indent=2))
+        else:
+            typer.echo(f"Analysis run {run_id} started: {total} conversation(s) to analyze.")
+            typer.echo("It keeps going server-side; the results land on the webapp's Issues page.")
+        raise typer.Exit(EXIT_OK)
+
+    if not json_output:
+        typer.echo(f"Analysis run {run_id} started: {total} conversation(s) to analyze.")
+
+    try:
+        final_run = _wait_for_analysis(
+            api_url=api_url,
+            api_key=api_key,
+            project_id=project_id,
+            run_id=run_id,
+            poll_interval=poll_interval,
+            timeout=timeout,
+            quiet=json_output,
+        )
+    except KeyboardInterrupt:
+        # To stderr under --json: stdout is the machine's, and these lines would
+        # land in front of the JSON document a caller is parsing.
+        typer.echo("", err=json_output)
+        typer.echo("Interrupted — cancelling the analysis...", err=json_output)
+        try:
+            post_issue_analysis_cancel(api_url=api_url, api_key=api_key, project_id=project_id, run_id=run_id)
+            typer.echo("Analysis cancelled. Conversations analyzed so far keep their occurrences.", err=json_output)
+        except ApiError as exc:
+            typer.secho(f"Could not cancel the analysis: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_INTERRUPTED)
+
+    if json_output:
+        typer.echo(json.dumps({"run": final_run}, indent=2))
+    else:
+        _print_analysis_outcome(final_run)
+
+    if final_run.get("status") == "completed":
+        raise typer.Exit(EXIT_OK)
+    raise typer.Exit(EXIT_VALIDATION_FAILED)
+
+
+def _wait_for_analysis(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    run_id: str,
+    poll_interval: float,
+    timeout: float,
+    quiet: bool,
+) -> dict[str, Any]:
+    """Poll the run until terminal and return its final record.
+
+    Exits 3 directly on timeout, on an auth failure (fail fast — retrying a
+    revoked key can't succeed), or after several consecutive poll failures.
+    The server-side run keeps going in all three cases.
+    """
+    deadline = time.monotonic() + timeout
+    last_line = ""
+    failures = 0
+    while time.monotonic() < deadline:
+        try:
+            run = get_issue_analysis_run(api_url=api_url, api_key=api_key, project_id=project_id, run_id=run_id)
+        except AuthError as exc:
+            typer.secho(f"{exc} The analysis keeps going server-side.", fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_TRANSPORT) from exc
+        except IssueNotFoundError as exc:
+            # The run is gone (purged): nothing to keep polling for.
+            raise _not_found_failure(exc) from exc
+        except ApiError as exc:
+            failures += 1
+            if failures >= _MAX_CONSECUTIVE_POLL_FAILURES:
+                typer.secho(
+                    f"Polling failed {failures} times in a row ({exc}). "
+                    "Giving up — the analysis keeps going server-side; see the webapp's Issues page.",
+                    fg=typer.colors.RED,
+                    err=True,
+                )
+                raise typer.Exit(EXIT_TRANSPORT) from exc
+            typer.secho(f"(poll failed, retrying: {exc})", fg=typer.colors.YELLOW, err=True)
+            time.sleep(poll_interval)
+            continue
+        failures = 0
+
+        line = (
+            f"{run.get('chats_analyzed', 0)}/{run.get('total_chats', 0)} conversations analyzed — "
+            f"{run.get('occurrences_created', 0)} occurrence(s) found"
+        )
+        if not quiet and line != last_line:
+            typer.echo(line)
+            last_line = line
+
+        if run.get("status") in _TERMINAL_ANALYSIS_STATUSES:
+            return run
+        time.sleep(poll_interval)
+
+    typer.secho(
+        f"Timed out after {timeout:.0f}s waiting for analysis run {run_id}. "
+        "The analysis keeps going server-side — see the webapp's Issues page.",
+        fg=typer.colors.YELLOW,
+        err=True,
+    )
+    raise typer.Exit(EXIT_TRANSPORT)
+
+
+def _print_analysis_outcome(run: dict[str, Any]) -> None:
+    status = run.get("status")
+    if status == "completed":
+        typer.echo("")
+        typer.echo(
+            f"Analysis complete: {run.get('chats_analyzed', 0)} conversation(s) analyzed, "
+            f"{run.get('occurrences_created', 0)} occurrence(s) found, "
+            f"{run.get('issues_touched', 0)} issue(s) created or updated."
+        )
+        typer.echo("Review them with `cassis issues list`.")
+    elif status == "cancelled":
+        typer.secho("Analysis cancelled before it finished.", fg=typer.colors.YELLOW, err=True)
+    else:
+        typer.secho(f"Analysis failed: {run.get('error') or 'unknown error'}", fg=typer.colors.RED, err=True)

{cassis_cli-1.6.0 → cassis_cli-1.7.0}/cassis_cli/ontology_design_guide.md

@@ -440,6 +440,15 @@ checkout:
 Merging the pull request syncs and publishes the ontology; nothing reaches
 production answers until then.
 
+When the change came from a Cassis issue, merging is still not the last step.
+Confirm the published version contains it (`cassis status`, or
+`get_project_status` over MCP), then propose resolving that issue —
+`cassis issues resolve <id>`, or `update_issue_status`. Propose it to whoever
+owns the project: resolving needs the editor or admin role, and it records an
+outcome without changing any ontology. Never resolve before publication, and
+never silently — an issue nobody resolves stays in the triage queue and reads
+as a gap that was never fixed.
+
 ---
 
 *This guide is the single canonical home for Cassis ontology modeling doctrine.

{cassis_cli-1.6.0 → cassis_cli-1.7.0}/cassis_cli/schema.py

@@ -231,7 +231,8 @@ def push(
         raise typer.Exit(EXIT_TRANSPORT) from exc
 
     run_id = run["run_id"]
-    typer.echo(f"Detection run started: {run_id}")
+    # To stderr under --json so `cassis schema push --json | jq` gets only the record.
+    typer.echo(f"Detection run started: {run_id}", err=json_output)
 
     run = _wait_for_detection_run(
         api_url=api_url,
@@ -262,6 +263,7 @@ def push(
         typer.secho(
             f"✓ Detection completed: {total} change(s) to review." if total else "✓ Detection completed: no changes.",
             fg=typer.colors.GREEN,
+            err=json_output,
         )
         raise typer.Exit(EXIT_OK)
     if run_status == "failed":

{cassis_cli-1.6.0 → cassis_cli-1.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cassis-cli"
-version = "1.6.0"
+version = "1.7.0"
 description = "Validate, test and evaluate your Cassis ontology from your terminal, then publish it"
 readme = "README.md"
 license = { text = "Apache-2.0" }