# Engineering Practice Architecture Specification **Status:** Accepted cross-cutting specification. Implementation timing is governed by `../../plans/AWP-INCREMENTAL-DELIVERY-PLAN.md`. **Date:** 2026-08-19 ## 1. Purpose Define the small set of established engineering practices AWP treats as cross-cutting architecture/quality requirements without turning them into a process waterfall or rebuilding mature tooling. The governing rule is: > Prefer a small durable AWP semantic contract plus a proven standard/FOSS implementation tool over rebuilding commodity machinery. ## 2. Incremental-delivery constraint These practices do not create a horizontal prerequisite phase. ```text Increment 0/1 dogfood path -> use only the practices required by the risks/contracts present -> deepen them as later increments add CI, release, deployment and productization ``` Canonical delivery order: [`../../plans/AWP-INCREMENTAL-DELIVERY-PLAN.md`](../../plans/AWP-INCREMENTAL-DELIVERY-PLAN.md). ## 3. R1 Architecture conformance ### Requirement Binding architecture boundaries must have executable detectors when practical. Initial 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 ``` Architecture checks should be represented through existing quality/CI invariant semantics rather than inventing a separate product subsystem unless later evidence requires one. Every exemption records rationale, owner, scope and expiry/review trigger. ### Tooling Prefer `dependency-cruiser` for TypeScript/JavaScript dependency rules unless an existing verified Platform capability is simpler. ### Timing Required from Increment 0 for boundaries already created. ## 4. R2 Conditional threat modeling ### Requirement A `ThreatModel` is a conditional design/Planning artifact when a Project or Plan crosses a material security, privacy or trust boundary. Typical triggers: ```text public ingress/authentication new credential/provider connection privileged execution production-control authority PII/sensitive data multi-tenancy security-boundary changes untrusted-code execution ``` A ThreatModel records: ```text scope trust/data-flow diagram assets threats mitigations residual risks accepted risks linked Decisions/requirements owner/review trigger ``` AWP itself requires a maintained threat model before privileged Increment 1 dogfooding is Design Complete. ### Tooling Use OWASP threat-modeling conventions. Prefer OWASP Threat Dragon for diagram/threat/mitigation authoring when useful instead of building an AWP threat-model editor. ### Timing AWP project practice before Increment 1; conditional Planning capability in Increment 2; deeper policy/approval integration in Increment 3. ## 5. R3 SBOM and verifiable build provenance ### Requirement For meaningful distributable artifacts, preserve evidence bound to immutable artifact identity: ```text artifact digest source revision SBOM build provenance / builder identity build inputs signature/attestation verification vulnerability result bound to digest ``` Scanning, SBOM, signing and provenance remain distinct evidence types. ### Standards/tooling ```text CycloneDX preferred; SPDX accepted SLSA + in-toto compatible provenance Trivy for scanning and initially SBOM generation when sufficient Cosign for signing/attestation ORAS for generic OCI evidence transport Syft only when a dedicated SBOM generator gives a concrete advantage ``` ### Timing Start when AWP first distributes meaningful packages/images. Full AWP `Artifact`/`Release` product semantics arrive in Increment 6. ## 6. R4 API/contract compatibility ### Requirement A compatibility gate applies to declared compatibility boundaries, not every internal type. ```text canonical contract -> proposed change -> compatibility diff -> compatible: normal review -> breaking: explicit Decision + migration/versioning policy ``` Applicable contract classes include HTTP APIs and, when declared stable/externally consumed, adapter/event/schema contracts. Internal dogfood contracts may evolve atomically with all consumers until they are explicitly promoted to a compatibility boundary. ### Standards/tooling Use OpenAPI for HTTP contracts where applicable. Prefer `oasdiff` for breaking OpenAPI change detection. ### Timing Define the policy with early transport/contracts architecture work. Activate the gate as soon as stable/external consumers exist. Integrate deeply with CI in Increment 5 and harden stable public API/SDK commitments in Increment 9. ## 7. R5 Reliability/SLO/error-budget policy ### Requirement R5 is accepted but explicitly parked for external productization. Dogfooding requires telemetry, health and failure visibility, but **not** an SLO/error-budget subsystem. When AWP becomes an externally operated product, long-lived services may receive a `ReliabilityPlan` with: ```text user-relevant SLIs SLO targets measurement window/source error-budget policy where useful owner/review cadence linked release/incident policy ``` Do not force ReliabilityPlan onto libraries/CLIs or invent 100% objectives. ### Standards/tooling Prefer OpenSLO as a portable representation. If Prometheus-compatible metrics are used, prefer Sloth or Pyrra for operational rule generation rather than building an AWP SLO engine. ### Timing Increment 9 / external-enterprise productization. It is non-blocking for current dogfooding. ## 8. Decision and traceability integration Material adoption/exemption/supersession decisions use the canonical [`../domains/approvals-decisions.md`](../domains/approvals-decisions.md) `Decision` primitive. Architecture, security, compatibility and reliability rules must link back to the Decision/requirement that created them where practical. ## 9. Quality/CI integration R1 and R4 become `CIInvariant`/check requirements at the earliest reliable enforcement point. R2 may produce security verification requirements. R3 produces release/artifact evidence requirements. R5 may later influence release/deployment gates when an error-budget policy is active. The verification discipline remains: use the smallest check that can meaningfully falsify the property, broaden only for a recorded reason, and stop when sufficient valid evidence exists. ## 10. Acceptance criteria This specification is satisfied when: 1. Increment-0 architecture boundaries have executable checks where practical. 2. AWP has a maintained threat model before privileged Increment-1 dogfooding. 3. Distributed artifacts gain SBOM/provenance/signature/scan evidence as soon as applicable. 4. Stable/external API contracts cannot break silently. 5. Internal dogfood contracts are not prematurely frozen merely because compatibility tooling exists. 6. R5 does not block dogfooding and is visibly parked for productization. 7. Commodity mechanics are delegated to standards/FOSS tooling instead of rebuilt in AWP without a demonstrated gap. ## 11. Platform Reuse Relevant package(s): to be evaluated during the Increment-0 Platform package audit. Decision: reuse an existing Platform invariant/contract facility where it materially reduces duplication; otherwise integrate the named FOSS tools directly behind AWP semantics. What AWP owns: requirement meaning, Decision links, policy, lifecycle/gate semantics and operator UX. What tools own: dependency analysis, threat-model authoring UI, SBOM generation, compatibility diffing, SLO rule generation. Pinned versions: resolved immediately before the increment that first executes each tool.