feat: make Core reports commercially production-ready

2026-07-29 13:12:11 +07:00
parent 67d482ae7f
commit 7f01cf980a
27 changed files with 1197 additions and 23 deletions
@@ -0,0 +1,52 @@
+# Core-only commercial product audit
+
+Audit date: 2026-07-29  
+Reference project: `Basic Design (Screen&Report)_v2.7`
+
+## Problem reproduced
+
+The previous empty-state overview displayed READY and operational-looking
+zeroes before any governed run existed. Core, Domain Pipeline, and Provider
+Telemetry were not separated, so a customer could not tell which capability
+was installed, optional, or waiting for evidence.
+
+Evidence:
+
+- `00-init-empty-state.png`
+- `01-assurance-overview.png`
+- `02-run-dossier-h1-h7.png`
+- `03-h6-trace-filtered.png`
+
+## Corrected product contract
+
+- `casan init --edition core` writes `.casan/discovery.json` and
+  `.casan/readiness.json`.
+- Core can be `ready` while Domain Pipeline is `not_configured`/`discovered`
+  and Provider Telemetry is `optional_unavailable`.
+- The overview hides operational KPIs until a governed run exists.
+- The empty H6 view hides failure, latency, token, cost, coverage, chart and
+  export controls rather than displaying fabricated zeroes.
+- HTML/JSON export remains on-demand.
+- `casan pipeline --help` never executes a pipeline; a missing project runner
+  returns `CASAN_PIPELINE_NOT_CONFIGURED` without marking Core failed.
+
+Evidence:
+
+- `04-commercial-readiness-empty-state.png`
+- `05-commercial-h6-empty-state.png`
+- `06-basic-design-commercial-overview.png`
+- `07-basic-design-commercial-h6.png`
+
+## Acceptance evidence
+
+- clean Core-only vendored init: Core `ready`, Domain Pipeline
+  `not_configured`, Provider Telemetry `optional_unavailable`;
+- no application source or `apps/` directory created by Core init;
+- Basic Design discovery: Core `ready_with_attention` because Claude/Codex are
+  healthy while the selected VS Code route lacks its extension; Domain
+  Pipeline `discovered`; Provider Telemetry `available`;
+- Basic Design H1–H7 domain smoke: seven controls passed;
+- Inspect latest run opens the interactive H1–H7 dossier;
+- Open H6 opens the trace-filtered AgentOps dossier;
+- Core and DevKit release artifacts build and pass extracted-artifact smoke;
+- hybrid install suite: 104 pass, 0 fail.
@@ -13,6 +13,7 @@ sh install.sh --level devkit
 cd /path/to/my-project
 casan init --project ticketing --client claude,codex
 casan doctor
+casan readiness --refresh
 casan verify-harness
 ```

@@ -31,6 +32,16 @@ The viewer is single-project, offline-capable and read-only. It starts lazily on
 `127.0.0.1`, so projects do not need Platform, Node/npm or an always-running
 service merely to inspect H1–H7 and H6.

+The dashboard and CLI expose three independent states:
+
+- Core: installation acceptance and client activation;
+- Domain Pipeline: optional project-specific SRS→test configuration;
+- Provider Telemetry: optional model/provider token and cost coverage.
+
+`not_configured` Domain Pipeline and `optional_unavailable` Provider Telemetry
+do not block Core. `casan report export` is on-demand and must not run after
+every prompt.
+
 Use this for developer workstations and managed CI runners. CI must install the
 same release recorded by `.casan/version.lock` before running gates.

@@ -0,0 +1,64 @@
+# CASAN Commercial Readiness Contract
+
+## Promise
+
+After `casan init`, a repository can use CASAN Core prompt assurance and the
+Local Assurance Viewer without modifying application source, installing a
+Domain Pack, running a domain pipeline, or exporting HTML after every prompt.
+
+CASAN never turns missing evidence into zero and never calls an installation
+READY when a required client activation step remains.
+
+## State model
+
+| Dimension | Ready state | Non-blocking state | Owner |
+|---|---|---|---|
+| Core | `ready`, `ready_with_attention` | — | CASAN runtime + selected client |
+| Domain Pipeline | `configured` | `discovered`, `not_configured` | Project team |
+| Provider Telemetry | `available` | `optional_unavailable` | Client/provider adapter |
+
+Core installation acceptance uses H1–H7 as an installation contract:
+
+1. H1 project configuration exists and is valid;
+2. H2 selected client integration is installed and trust is explicit;
+3. H3 local report capability exists in the resolved runtime;
+4. H4 enforcement mode is disclosed (`observe` is a warning);
+5. H5 evidence directories are writable;
+6. H6 provider token/cost telemetry is measured when available and explicitly
+   optional when unavailable;
+7. H7 bootstrap and version/hash pin exist.
+
+When at least one selected client route is operational but another selected
+route fails the deep doctor check, Core is `ready_with_attention`: reports and
+governed prompts remain usable through the healthy route, while the broken
+route is shown as an explicit activation action.
+
+These checks do not claim that a real prompt run is H1–H7 certified. Run
+certification is created only from canonical lifecycle evidence after a prompt.
+
+## CASAN-owned files
+
+- `.casan/discovery.json`: bounded read-only discovery projection;
+- `.casan/readiness.json`: shared CLI/viewer state;
+- `.casan/domain.json`: optional reference to a project-owned manifest.
+
+No command above creates requirements, traceability mappings, tests, source
+files or a fake runnable pipeline.
+
+## Operator path
+
+```bash
+casan init
+casan doctor
+casan readiness --refresh
+casan view
+
+# Optional, only for project-specific SRS→test acceptance
+casan domain discover
+casan domain configure path/to/project.manifest.json
+casan pipeline --help
+```
+
+`casan pipeline` runs only when the project provides
+`scripts/run-casan-pipeline.mjs`. Otherwise it returns
+`CASAN_PIPELINE_NOT_CONFIGURED` while leaving Core fully usable.
@@ -7,6 +7,7 @@ reports. Platform is not a prerequisite for basic visibility.

 Core owns the single-project review loop:

+- commercial readiness split into Core, Domain Pipeline, and Provider Telemetry;
 - latest assurance receipt and run history;
 - interactive H1→H7 evidence spine;
 - H6 runtime, reliability, token/cost coverage, freshness and findings;
@@ -38,6 +39,7 @@ review artifact, not the evidence source of truth.

 ```bash
 casan report latest
+casan readiness --refresh
 casan view [trace-id] [--no-open]

 casan report export [trace-id] --format html|json [-o path]
@@ -52,6 +54,11 @@ casan dashboard stop
 When Platform code is installed, `casan dashboard` manages the centralized
 Control Plane. `casan view` remains the predictable Core single-project viewer.

+An empty project must not show operational zeroes or a fabricated READY
+verdict. Before the first governed prompt, the overview shows installation
+readiness and actionable onboarding only. Operational KPIs appear after
+canonical run evidence exists.
+
 ## Runtime and packaging contract

 - Python standard library only; no Node/npm or network dependency.
@@ -109,6 +116,8 @@ The Core viewer is releasable only when all of these pass:
 6. browser validation covers the report hierarchy, interaction and responsive
   navigation;
 7. existing harness, DevKit installation and packaging suites remain green.
+8. a clean `casan init --edition core` project reports Core ready without
+   requiring a Domain Pack, provider token/cost telemetry, or app-source edits.

 ## Maturity statement

@@ -1,7 +1,8 @@
 # CASAN Domain Pack Guide

-A **Domain Pack** is the per-project data the harness needs to govern YOUR domain. It lives
-at `apps/<project>/domain/` and is selected via `CASAN_DOMAIN_ROOT`. The harness code
+A **Domain Pack** is optional per-project data the harness needs for a
+project-specific SRS→test pipeline. Core prompt assurance and visual reporting
+do not require it. A pack commonly lives at `apps/<project>/domain/`. The harness code
 (`packages/casan-harness/`) never contains domain data — this is what makes it reusable.

 Scaffold template: `packages/casan-devkit/templates/domain-pack/`.
@@ -39,9 +40,18 @@ apps/<project>/domain/

 ## Wire it up
 ```bash
+casan domain discover
+casan domain configure apps/<project>/domain/project.manifest.json
+casan domain status
+
+# Existing automation remains supported
 export CASAN_PROJECT_MANIFEST=apps/<project>/domain/project.manifest.json
 bin/casan gate                 # runs domain-dependent suites against your pack
 ```
+`casan domain configure` writes only `.casan/domain.json`; it references an
+existing in-project manifest and never copies, rewrites or invents application
+requirements, source mappings or tests.
+
 `domain_root` is also recorded per-project in `packages/casan-harness/config/project-registry.json`
 so `bin/casan reuse` can prove multi-project reuse.