Skip to content

v1.8.0 — Typed handoffs, automated rule audit, API contracts

Choose a tag to compare

View all tags
@DuqueOM DuqueOM released this 08 Aug 15:13
· 271 commits to main since this release
archive/v1.8.0
7ba9258

Note

Historical audit snapshot. This release belongs to the v1.0–v1.12 line that
shipped during the post-audit remediation sprint (2026-04-15 → 2026-04-29).
Per docs/RELEASING.md
these tags are immutable historical snapshots; the active public release line
is now v0.x
hardening, with v1.0.0 reserved for the first verified GKE+EKS cloud E2E rollout.
See CHANGELOG.md for the reclassification rationale.

Release date: 2026-04-24

Minor release (v1.8.0) focused on the agentic runtime layer: typed
inter-agent contracts, an append-only audit log, two new operational
skills (rule-audit + performance-degradation-rca), and public API
contract versioning.

No breaking runtime changes. No migration required for existing services.

Highlights

Typed handoffs + AuditLog (B1)

Problem: agents were passing dicts to each other. A missing key or
mistyped value surfaced only during Kubernetes apply, hours downstream.

Fix:

  • common_utils/agent_context.py — frozen dataclasses already existed
    (v1.6) for EDAHandoff, TrainingArtifact, BuildArtifact,
    SecurityAuditResult, DeploymentRequest. This release validates
    them comprehensively with 25 new unit tests and hardens invariants:
    • AuditEntry refuses success in CONSULT/STOP without approver
    • AuditEntry now carries risk_signals + base_mode (ADR-010 trail)
    • DeploymentRequest re-verified: prod blocks non-STOP mode and
      failing audits at construction
  • AuditLog class — thread-safe append-only JSONL writer with
    record_operation() that extracts signals from a RiskContext
    automatically. One function call to persist an auditable op.

rule-audit skill (B2)

Problem: invariants D-01..D-27 lived in documentation. Nothing
automatically CHECKED whether a service complies.

Fix: new .windsurf/skills/rule-audit/SKILL.md — a READ-ONLY
compliance scanner. Per-invariant grep/rg/yq/conftest command.
Emits ops/rule_audit.jsonl with evidence (file:line or metric).
--subset flag for scoped runs (probes, pdb, security, closed-loop,
all). Integrates with AuditLog so scans are part of the ops trail.

performance-degradation-rca skill (B3)

Problem: concept-drift-analysis handles single-slice RCA. Full
incidents need to correlate sliced metrics + drift + deploy history +
upstream data + logger health — and produce a blameless RCA doc.

Fix: new .windsurf/skills/performance-degradation-rca/SKILL.md.
Five-stream evidence correlation. Synthesizes one of R1..R5:

  • R1 Model regression (deploy-correlated)
  • R2 Concept drift (gradual, no deploy)
  • R3 Data-quality / semantic shift (PSI > 2× threshold)
  • R4 Monitoring failure (logger degraded → verdict inconclusive)
  • R5 Compound (escalate to architecture review)

Produces docs/incidents/{date}-{service}.md with evidence and
5-business-day corrective actions.

API contract versioning (B4, D-28)

Problem: Pydantic schemas silently drifted. A field rename broke every
client downstream.

Fix:

  • new rule 14 .windsurf/rules/14-api-contracts.md with semver table
    (additive=minor, renames/narrows=major)
  • templates/service/tests/contract/test_openapi_snapshot.py — fails
    if openapi.snapshot.json diverges from the live TestClient response
  • templates/service/scripts/refresh_contract.py — regenerates the
    snapshot (run after any intentional schema edit)
  • CI guard: PR that changes openapi.snapshot.json without a matching
    app.version bump is rejected
  • D-28 added to AGENTS.md anti-pattern table

Why a snapshot, not full Pact? Engineering Calibration: 1-3 services
with homogeneous clients. The snapshot catches 99% of breaking changes
with 10% of the infra.

New files

  • .windsurf/skills/rule-audit/SKILL.md
  • .windsurf/skills/performance-degradation-rca/SKILL.md
  • .windsurf/rules/14-api-contracts.md
  • templates/service/tests/contract/__init__.py
  • templates/service/tests/contract/test_openapi_snapshot.py
  • templates/service/scripts/refresh_contract.py
  • templates/tests/unit/test_agent_context.py
  • releases/v1.8.0.md (this file)

Changed files

  • templates/common_utils/agent_context.py — AuditEntry validation,
    AuditLog writer, risk_signals + base_mode fields
  • AGENTS.md — D-28 added

Test counts

  • Unit tests: 100 passing (was 75 in v1.7.1)
    • test_agent_context.py: 25 new tests

Migration (v1.7.1 → v1.8.0)

No runtime changes required. Optional adoption:

  1. Contract snapshot — for services with public APIs:

    cd {service-root}
python scripts/refresh_contract.py
# commit openapi.snapshot.json

    Add the CI guard block from rule 14 to .github/workflows/ci.yml.

  2. Audit log — instrument critical operations:

    from common_utils.agent_context import AuditLog, AgentMode, Environment
from common_utils.risk_context import get_risk_context

ctx = get_risk_context()
final = ctx.escalate(AgentMode.AUTO)
AuditLog().record_operation(
    agent="Agent-MLTrainer",
    operation="train_model",
    environment=Environment.STAGING,
    base_mode=AgentMode.AUTO,
    final_mode=final,
    risk_context=ctx,
    inputs={"dataset_sha": "..."},
    outputs={"mlflow_run_id": "..."},
    approver="alice" if final != AgentMode.AUTO else None,
)

  3. Run rule-audit on the service once to surface existing gaps:
    Invoke the rule-audit skill (read-only; no code changes).

Related documentation

  • AGENTS.md — invariant reference (D-01..D-28)
  • ADR-010 — dynamic Behavior Protocol (v1.7.1, feeds AuditLog)
  • ADR-011 — environment promotion gates (v1.7.1)
  • rule 14 — API contracts (new)
Assets 2
Loading