Aller au contenu

CLI Audits

Status

Current operator guide.

This page documents the audit posture of the CMonChoix CLI. The architecture of read services remains documented in:

Purpose

CLI audits observe and explain the current state of the Platform without changing business truth, projections or runtime configuration.

They are used to:

  • establish a reproducible baseline;
  • compare implementations or runs;
  • explain residual differences;
  • qualify ambiguous or unresolved cases;
  • validate a proposed change before enabling mutation;
  • produce evidence for an operational decision.

Canonical invocation

Run WP-CLI from the repository root through the worker service:

docker compose exec platform-worker wp <command> --allow-root

Before relying on a command, verify its registered help:

docker compose exec platform-worker wp help <command> --allow-root

Do not use textual grep over the raw output of wp cli cmd-dump --format=json as a command-presence test. Parse the JSON tree or use wp help.

Audit contract

An audit command must be read-only by default.

It may:

  • read source, staging, normalized or projection data;
  • execute deterministic comparisons;
  • calculate metrics and evidence;
  • write reports to stdout or to an explicitly requested artifact file.

It must not:

  • update offer or product truth;
  • clear or replace images;
  • rebuild projections implicitly;
  • install or mutate schema;
  • alter runtime options, queue state or locks;
  • silently switch to a corrective mode.

A command that can mutate state is not classified as an audit merely because it exposes a dry-run option.

Evidence model

An industrial audit reports more than a single success ratio. Its output should expose, when applicable:

  • total rows considered;
  • rows eligible for evaluation;
  • rows checked;
  • matched and mismatched rows;
  • skipped rows grouped by reason;
  • unknown or ambiguous evidence;
  • confidence distribution;
  • proposed replacements;
  • mutations requested and mutations actually performed;
  • run, feed, vertical and rule identifiers.

Counts must reconcile. Every scanned row must end in an explicit outcome bucket.

Media Quality

Media Quality follows an audit-first and non-destructive policy.

The default flow is:

normalized offer
      ↓
evidence extraction
      ↓
rule evaluation
      ↓
classification and diagnostics
      ↓
report only

The audit may classify an image as matched, mismatched, unknown or ambiguous and may propose a replacement candidate. It must not clear image_norm merely because a mismatch is detected.

A replacement is permitted only through an explicitly enabled mutation path and only when the configured confidence threshold and evidence requirements are satisfied.

Historical runs in which images were already cleared must be regenerated before comparing new Media Quality metrics. Otherwise, the audit measures previously mutated data rather than the current projection behavior.

See Media Quality Engine.

establish baseline
      ↓
comparison audit
      ↓
difference-family analysis
      ↓
resolution or evidence analysis
      ↓
simulation / virtual patch
      ↓
rerun audit on regenerated data
      ↓
validation report

Regenerate the relevant projection whenever a previous implementation may have mutated the evaluated columns.

Choosing an audit

Question Documentation
Compare old and new behavior Real sample comparison
Group residual differences Difference family audit
Explain resolution-state differences Resolution status audit
Inspect what remains after a change Remaining audit
Review catalog output Catalog audit
Simulate without writing Simulation or Virtual patch
Export cases for manual review Candidate dump or Virtual candidates dump
Conclude the validation cycle Validation report

Output and exit codes

Human-readable output should remain concise and operational. Structured output should be available when the command supports automation.

Recommended exit-code contract:

  • 0: audit completed and its acceptance criteria passed;
  • non-zero: invalid invocation, technical failure, incomplete evaluation or failed acceptance criteria.

A command must not return success solely because it completed technically when its explicit validation threshold failed.

Reproducibility

Every audit result used for a decision should record enough context to be reproduced:

  • command and arguments;
  • git revision;
  • runtime/plugin revision when distinct;
  • run or feed identifier;
  • evaluated vertical or scope;
  • timestamp;
  • relevant configuration and thresholds.

Invariants

  1. Audit mode is read-only by default.
  2. Mutating behavior requires an explicit, separately documented action.
  3. Metrics reconcile to the evaluated population.
  4. Unknown evidence is never presented as a successful match.
  5. A high global KPI never hides unresolved critical cases.
  6. Historical destructive mutations require data regeneration before comparison.
  7. CLI adapters delegate calculations and persistence to application or domain services.
  8. Audit commands do not depend on the public frontend stack.

See also