Quality trace

quality_trace

Best-effort persistence of governance quality snapshots.

Each init_check run appends one JSON line to ~/axm/quality/{package}.jsonl capturing the score, grade and the list of actionable failures, stamped with a UTC timestamp and the current git HEAD.

The file is an append-only history: the current state of a repo is the last line of a given kind; a trend is obtained by filtering on sha at read time (deduplication is a reader concern, never a writer one).

Design contract: observability must never break a check. Every failure here (no git, unwritable disk, malformed payload) is swallowed — the caller's ToolResult is returned unchanged regardless.

normalize_fails(data)

Extract actionable failures from an audit/init data payload.

audit emits failed: [{rule_id, message, fix_hint, ...}]. init_check emits failures: [{name, message, fix, ...}]. Both are normalized to {rule_id, message, fix_hint}.

Source code in packages/axm-init/src/axm_init/quality_trace.py

def normalize_fails(data: Mapping[str, object]) -> list[dict[str, object]]:
    """Extract actionable failures from an audit/init ``data`` payload.

    ``audit`` emits ``failed: [{rule_id, message, fix_hint, ...}]``.
    ``init_check`` emits ``failures: [{name, message, fix, ...}]``.
    Both are normalized to ``{rule_id, message, fix_hint}``.
    """
    raw = data.get("failed")
    if raw is None:
        raw = data.get("failures")
    if not isinstance(raw, Sequence):
        return []
    fails: list[dict[str, object]] = []
    for entry in raw:
        if not isinstance(entry, Mapping):
            continue
        fails.append(
            {
                "rule_id": entry.get("rule_id") or entry.get("name"),
                "message": entry.get("message"),
                "fix_hint": entry.get("fix_hint") or entry.get("fix"),
            }
        )
    return fails

record_quality_snapshot(*, path, kind, data)

Append one quality snapshot line for path; never raise.

Parameters:

Name	Type	Description	Default
path	str	Path to the audited project (its directory name becomes the history file name).	required
kind	TraceKind	"audit" (axm-audit) or "governance" (axm-init).	required
data	Mapping[str, object]	The ToolResult.data dict — must carry score/grade and a failed/failures list.	required

Source code in packages/axm-init/src/axm_init/quality_trace.py

def record_quality_snapshot(
    *,
    path: str,
    kind: TraceKind,
    data: Mapping[str, object],
) -> None:
    """Append one quality snapshot line for ``path``; never raise.

    Args:
        path: Path to the audited project (its directory name becomes the
            history file name).
        kind: ``"audit"`` (axm-audit) or ``"governance"`` (axm-init).
        data: The ``ToolResult.data`` dict — must carry ``score``/``grade``
            and a ``failed``/``failures`` list.
    """
    try:
        project_path = Path(path).resolve()
        package = project_path.name
        sha, branch = _git_head(project_path)
        line = {
            "ts": datetime.now(UTC).isoformat(timespec="seconds"),
            "repo": package,
            "sha": sha,
            "branch": branch,
            "kind": kind,
            "score": data.get("score"),
            "grade": data.get("grade"),
            "fails": normalize_fails(data),
        }
        out_dir = _quality_dir()
        out_dir.mkdir(parents=True, exist_ok=True)
        target = out_dir / f"{package}.jsonl"
        with target.open("a", encoding="utf-8") as fh:
            fh.write(json.dumps(line, default=str) + "\n")
    except Exception:  # noqa: BLE001 - observability must never break a check
        return