# AWP Standard-Practice Gap Decisions **Date:** 2026-08-19 **Status:** Accepted. All five recommendations below are binding direction; implementation timing follows `AWP-INCREMENTAL-DELIVERY-PLAN.md`. **Purpose:** Add only the highest-value established engineering practices that materially reduce AWP design/delivery risk, preferring standards/FOSS over custom subsystems. ## 1. Already adopted: durable Decision records / ADR projection AWP has one first-class `Decision` primitive across project scopes. The Project Decision Log and architecture ADRs are projections of canonical Decision state rather than competing truth sources. Canonical spec: - `docs/specs/domains/approvals-decisions.md` - `docs/specs/domains/approvals-decisions.html` Accepted history is superseded, not rewritten. ## 2. R1 — Architecture conformance / fitness checks **Status:** ACCEPTED — required from Increment 0. ### Gap AWP has binding architecture rules, but written rules alone can erode during incremental implementation. Examples: ```text gateway -> contracts only domain -X-> Hono domain -X-> provider SDK types gateway -X-> DBOS/Kubernetes/control repositories agents/runners -X-> reusable publication authority ``` ### Decision Architecture invariants become executable CI checks as early as the architecture they protect. Working representation may fit existing `CIInvariant` rather than requiring another primitive: ```text architecture invariant id Decision/rationale link detector affected modules severity exemption + expiry ``` Exemptions must be explicit, time-bounded where appropriate, and visible in the Decision/quality trail. ### FOSS Prefer `dependency-cruiser` (MIT) for TypeScript/JavaScript module/dependency rules unless a verified Platform capability already provides the same enforcement more simply. ### Increment placement Increment 0 onward. This is architecture protection, not a later CI-control-plane luxury. ## 3. R2 — Threat modeling as conditional design work **Status:** ACCEPTED — conditional per project/Plan; mandatory for AWP before the privileged Increment-1 dogfood lifecycle. ### Gap AWP has trust/security rules but needs a structured way to ask what can go wrong when a change crosses meaningful security/privacy/trust boundaries. ### Decision `ThreatModel` is a conditional Planning/design artifact, triggered by risk rather than required for every Plan. Typical triggers: ```text public ingress/auth change new credential/provider connection privileged execution production-control capability PII/sensitive data multi-tenancy security-boundary change new untrusted-code execution path ``` A ThreatModel records threats, mitigations, residual risks, trust/data flows and links to Decisions/requirements. For AWP itself, maintain a threat model before Increment 1 is Design Complete because it combines provider credentials, Git publication authority, Kubernetes execution and untrusted agent code. ### FOSS Prefer OWASP threat-modeling conventions and OWASP Threat Dragon for DFD/threat/mitigation authoring when useful. AWP should own the semantic artifact/links, not rebuild a diagram/threat-model editor without a concrete reason. ### Increment placement - AWP project practice: before privileged Increment 1. - Product Planning capability: Increment 2 Real Planning. - Policy/approval integration deepens in Increment 3. ## 4. R3 — Artifact SBOM + verifiable build provenance **Status:** ACCEPTED — required when meaningful distributable artifacts exist; fully productized in Increment 6. ### Gap Scanning/signing alone do not tell us exactly what is inside an artifact and how it was built. ```text scan -> known problems SBOM -> included components signature -> signer/attester provenance -> source/build inputs/process ``` ### Decision Release/build evidence includes where applicable: ```text immutable artifact digest source revision SBOM build provenance / builder identity build inputs signature/attestation verification vulnerability result bound to artifact digest ``` The evidence belongs to AWP `Artifact`/provenance semantics rather than a parallel dashboard. ### Standards/FOSS ```text CycloneDX preferred; SPDX accepted SLSA + in-toto compatible provenance Trivy for scanning and initially SBOM generation where sufficient Cosign for signing/attestation ORAS for generic OCI evidence transport Syft (Apache-2.0) only when a dedicated SBOM generator provides a concrete advantage over the existing Trivy path ``` This avoids adding a redundant tool merely because one exists. ### Increment placement If AWP distributes package/image artifacts before Increment 6, its own build pipeline starts producing this evidence earlier. Full AWP Artifact/Release semantics land with Increment 6 Release and Deployment. ## 5. R4 — Explicit API/contract compatibility policy and gates **Status:** ACCEPTED — policy early; enforcement activates when a contract has stable/external consumers. ### Gap AWP has runtime-neutral contracts but must distinguish intentional breaking evolution from accidental compatibility breaks. ### Decision When a contract has a compatibility boundary: ```text canonical machine-readable contract -> proposed change -> compatibility diff -> breaking? no -> normal review yes -> explicit Decision + migration/versioning policy ``` This applies to HTTP APIs and, where relevant, public adapter/event/schema contracts. Do **not** prematurely freeze internal dogfood contracts that can still change atomically with all consumers. Compatibility gates protect declared compatibility boundaries, not every internal TypeScript type. ### Standards/FOSS Use OpenAPI for HTTP contracts where applicable. Prefer `oasdiff` (Apache-2.0) for OpenAPI breaking-change detection instead of building a custom diff engine. ### Increment placement - Policy/interface rules defined with early transport/contracts architecture work. - Gate activates as soon as a stable/external consumer exists. - CI-control-plane integration becomes first-class in Increment 5. - Stable public API/adapter SDK hardening continues in Increment 9 productization. ## 6. R5 — Reliability objectives / SLO / error-budget policy **Status:** ACCEPTED BUT PARKED — lowest priority for current dogfooding; target Increment 9/external productization. ### Gap Telemetry tells us what happened, but a mature externally operated service eventually needs explicit objectives for what reliability is acceptable. ### Decision For long-lived externally operated services, Planning eventually supports a conditional `ReliabilityPlan` containing a small set of user-relevant SLIs/SLOs and optional error-budget policy. Possible AWP examples later: ```text control-plane availability/latency workflow dispatch success realtime recovery/freshness AgentRun dispatch latency CI result-ingestion freshness deployment-control success ``` ### Dogfooding priority R5 does **not** block current dogfooding increments. Increment 0 still needs basic telemetry, health and failure visibility. It does not need an SLO/error-budget subsystem. Formal SLO/error-budget productization waits until the decision is made to operate AWP as a real external/enterprise product. ### Standards/FOSS Prefer OpenSLO (Apache-2.0) as the portable representation. If Prometheus-compatible metrics are used later, prefer Sloth or Pyrra (Apache-2.0) for operational rule generation rather than building an AWP SLO engine. ## 7. Increment priority summary ```text DOGFOOD NOW R1 architecture conformance Increment 0 R2 threat model for AWP before Increment 1 AS CAPABILITY BECOMES REAL R2 conditional Planning threat model Increment 2 R4 contract compatibility when stable consumers exist / CI in 5 R3 artifact evidence when artifacts distribute / full in 6 PARKED UNTIL EXTERNAL PRODUCTIZATION R5 SLO / error-budget model Increment 9 ``` ## 8. What we deliberately still do not add Do not turn maturity checklists into product scope without a concrete need. Keep dependency-update bots, heavyweight compliance frameworks, dedicated chaos platforms, full ITSM/change-management systems, generic policy engines and similar machinery trigger-based. Binding rule: > Prefer a small durable AWP semantic contract plus a proven standard/FOSS implementation tool over rebuilding commodity machinery. ## 9. Delivery authority Implementation priority is determined by `AWP-INCREMENTAL-DELIVERY-PLAN.md`, not by this document's section order. The five practices are accepted. Their timing must never become an excuse to replace the end-to-end dogfooding sequence with a horizontal architecture/Planning/CI/security waterfall.