From 7fdd143d039e149f6435365d9afd82e01b520c7d Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Wed, 5 Aug 2026 16:12:57 +0000 Subject: [PATCH] =?UTF-8?q?docs(P04):=20complete=20matrix+review+manifest+?= =?UTF-8?q?architecture=20=E2=80=94=20v0.4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ---ci--- project: atelier phase: 4 milestone: v0.4 status: complete phase_role: execution phase_tag: v0.3.4 requirements: covered: [ATELIER-106, ATELIER-107, ATELIER-108, ATELIER-109, ATELIER-110, ATELIER-111, ATELIER-117] partial: [] ---/ci--- --- .ciagent/atelier/ARCHITECTURE.md | 38 +++++++++++++++++- MANIFEST.md | 25 +++++++++--- matrix/domain-coverage.md | 55 +++++++++++++++++++++----- matrix/principles-matrix.md | 39 +++++++++++++++++-- review/agent-checklist.md | 31 +++++++++++++++ review/anti-patterns.md | 66 ++++++++++++++++++++++++++++++++ review/peer-review-checklist.md | 33 ++++++++++++++++ 7 files changed, 267 insertions(+), 20 deletions(-) diff --git a/.ciagent/atelier/ARCHITECTURE.md b/.ciagent/atelier/ARCHITECTURE.md index 6ebef39..e69d43d 100644 --- a/.ciagent/atelier/ARCHITECTURE.md +++ b/.ciagent/atelier/ARCHITECTURE.md @@ -16,8 +16,18 @@ atelier/ │ ├── gitops-operators/ # v0.3: GitOps + Operators (argocd, flux, operators, progressive-delivery) │ ├── ai-ml/ # v0.3: ML engineering (data-versioning, model-evaluation, serving, monitoring-drift) │ ├── i18n/ # v0.3: internationalization (locale-resources, formatting, rtl-bidi, testing-i18n) -│ └── compliance/ # v0.3: compliance/audit (audit-logs, data-retention, policy-as-code, evidence) +│ ├── compliance/ # v0.3: compliance/audit (audit-logs, data-retention, policy-as-code, evidence) +│ ├── edge/ # v0.4: edge computing (cdn, offline-first, iot, sync) +│ └── messaging/ # v0.4: cross-process messaging (queues, pubsub, streams, delivery-semantics) ├── languages/ # Language-specific application of domains +│ ├── typescript.md # v0.1 first-principles stub +│ ├── python.md # v0.1 first-principles stub +│ ├── go.md # v0.1 first-principles stub +│ ├── rust.md # v0.1 first-principles stub +│ ├── ts-*.md # v0.4: 4 derived docs (ts-types, ts-tooling, ts-async, ts-testing) +│ ├── py-*.md # v0.4: 4 derived docs (py-types, py-tooling, py-async, py-testing) +│ ├── go-*.md # v0.4: 4 derived docs (go-types, go-tooling, go-concurrency, go-testing) +│ └── rs-*.md # v0.4: 4 derived docs (rs-ownership, rs-tooling, rs-async, rs-testing) ├── review/ # Evaluation checklists and anti-patterns ├── matrix/ # Cross-reference: domain ↔ core └── examples/ # Worked examples (good + bad) @@ -106,4 +116,28 @@ From the v0.3 ideation stage (IDEATE-17..30), the following architectural refine - **Core Principle Coverage table (IDEATE-19 → ATELIER-81):** `matrix/domain-coverage.md` contains two tables — the per-domain row schema table (covered by v0.2 IDEATE-03) AND the "Core Principle Coverage" table mapping C1–C8 → domains. Both must be extended for the 4 new domains; the C-rule counts shift (e.g., C4 Locality adds i18n + gitops; C5 Reversibility adds ai-ml + compliance + gitops + i18n). - **Cross-link type unchanged:** v0.3 introduces no new cross-link type. All cross-links remain one-directional outward from new domains to existing (D-033). No back-link edits to v0.1/v0.2 content. -See `.ciagent/atelier/RESEARCH.md` "v0.3 Research" for the full prior-art survey and principle inventory rationale, and `.ciagent/atelier/PERSONAS.md` for the v0.3 persona roster (5 active: lead-developer, tech-writer, domain-expert + 2 phase-specific platform-engineer, ml-engineer; 3 default personas deactivated). \ No newline at end of file +See `.ciagent/atelier/RESEARCH.md` "v0.3 Research" for the full prior-art survey and principle inventory rationale, and `.ciagent/atelier/PERSONAS.md` for the v0.3 persona roster (5 active: lead-developer, tech-writer, domain-expert + 2 phase-specific platform-engineer, ml-engineer; 3 default personas deactivated). + +## v0.4 Domain Additions + +Two new top-level domains and a language-derived extension expand the tree under the same hierarchy rules. All follow the v0.1/v0.2/v0.3 contract: docs-only markdown with illustrative code fences (no runtime/deployable artifacts per D-020). Total matrix grows from 170 → 190 domain principles across 17 → 19 domains. + +- **`edge/`** — edge computing domain. Owns the proximity/location/constraint angle (D-061): compute near the user or data source, offline as a first-class state, constrained resources declared, sync conflicts bounded, partition-survivable telemetry. Boundary vs `performance/` (generic measurement/optimization), `observability/` (generic structured telemetry), and `concurrency/` (in-process primitives): edge owns only the proximity/location/disconnection concerns that arise at the network edge — performance's locality is algorithmic, edge's locality is geographic (C4). 10 P-rules, broad derivation (7 C-rules: C1, C3, C4, C5, C6, C7, C8). Depends on `core/`. Cross-links are one-directional outward (D-026 extended): `performance/frontend` (P6 geographic cache invalidation vs generic caching), `performance/P4` (P3 constrained-device vs generic resource bounds), `observability/metrics` + `observability/logging` (P10 local-first telemetry), `concurrency/patterns` (P5 offline write-queue analog), `security/secrets` (P9 device identity), `security/input-validation` (P6 cache poisoning), `data/migrations` (P4 schema migration under sync). Edge↔messaging intra-v0.4 cross-links resolve bidirectionally in P5 (ATELIER-114, IDEATE-40): `edge/iot.md` → `messaging/queues` (MQTT QoS parallels to delivery semantics). Derived docs: `cdn.md`, `offline-first.md`, `iot.md`, `sync.md`. + +- **`messaging/`** — cross-process messaging domain. Owns the cross-process/network-failure-model angle (D-062): messages as contracts, explicit delivery semantics, idempotent consumers, bounded backpressure, observable lag. Boundary vs `concurrency/` (in-process/crash-failure-model): messaging's queue fails by network partition/broker restart/consumer crash-and-retry; concurrency's queue fails by OOM or thread crash. The discriminator is the failure model (D-062). 10 P-rules, broad derivation (7 C-rules: C1, C2, C4, C5, C6, C7, C8). Depends on `core/`. Cross-links are one-directional outward (D-026 extended): `concurrency/patterns` (P6 broker-backed bounded queue vs in-process Pattern 5; P3 cross-process idempotent retry vs in-process retry), `observability/metrics` + `observability/tracing` (P10 broker signals), `data/schema-design` (P1/P9 message schema evolution), `errors/patterns` (P5 errors as data for poison messages), `edge/iot` (P4 — bidirectional resolution of the MQTT QoS cross-link per IDEATE-40). Derived docs: `queues.md`, `pubsub.md`, `streams.md`, `delivery-semantics.md`. + +### v0.4 Language-Derived Extension + +The `languages/` tree extends from a first-principles-only stub (v0.1) to a full derived-doc tree (v0.4). Each of the 4 v0.1 stubs (`typescript.md`, `python.md`, `go.md`, `rust.md`) is extended with a pointer to its 4 derived docs (16 total). Language-derived docs **apply, not derive** domain principles (D-063): they introduce **no new P-rules** and **no new matrix rows** (D-066). Every section header names the traced core C-rule(s) AND the traced domain P-rule(s) inline (e.g., `## Nominal vs Structural Typing (C1 Correctness, Data P7 Type Fidelity, API P1 Contract Fidelity)`). The first-principles stubs retain their existing section structure — **no P1–P10 numbering** is added to languages (D-063); languages are an application lens, not a principle source, preserving the `core > domains > languages` ordering ("conflicts go UP, never sideways"). + +The `matrix/principles-matrix.md` gains **no language rows** — it stays at 190 P-rules / 19 domains (D-066). Language-derived-doc traceability is captured in a new `## Languages Coverage` sub-table in `matrix/domain-coverage.md` (exactly 16 rows, one per derived doc) — the verifiable aggregate; inline section-headers are the per-doc detail. Every derived doc traces to ≥1 domain P-rule (D-066, no orphans). + +Derived docs by language: +- **TypeScript** — `ts-types.md`, `ts-tooling.md`, `ts-async.md`, `ts-testing.md` +- **Python** — `py-types.md`, `py-tooling.md`, `py-async.md`, `py-testing.md` +- **Go** — `go-types.md`, `go-tooling.md`, `go-concurrency.md`, `go-testing.md` +- **Rust** — `rs-ownership.md`, `rs-tooling.md`, `rs-async.md`, `rs-testing.md` + +The manifest (`MANIFEST.md`) is extended with a new `## Languages` section (D-065) listing the 4 v0.1 stubs (closing pre-existing drift parallel to the v0.2 ESC-002 / ATELIER-91 precedent) and the 16 new v0.4 derived docs. The `review/` docs (agent-checklist, peer-review-checklist, anti-patterns) gain edge, messaging, and language-derived trigger sections. Examples (P5) are illustrative markdown with fenced code only — no standalone `.ts`/`.py`/`.go`/`.rs` runtime artifacts (D-020 docs-only contract, extended in v0.4 to language-derived-doc artifact types). + +See `.ciagent/atelier/RESEARCH-v0.4.md` for the full prior-art survey (Akamai/Cloudflare, Kafka/RabbitMQ/NATS, Jepsen, Reactive Streams, CloudEvents, CRDTs, PouchDB, MQTT/CoAP) and `.ciagent/atelier/PERSONAS.md` for the v0.4 persona roster (5 active: lead-developer, tech-writer, domain-expert + 2 phase-specific edge-engineer, languages-engineer). \ No newline at end of file diff --git a/MANIFEST.md b/MANIFEST.md index f98fb09..7b180b4 100644 --- a/MANIFEST.md +++ b/MANIFEST.md @@ -40,6 +40,21 @@ | AI / ML | ✓ | data-versioning, model-evaluation, serving, monitoring-drift | | i18n | ✓ | locale-resources, formatting, rtl-bidi, testing-i18n | | Compliance | ✓ | audit-logs, data-retention, policy-as-code, evidence | +| Edge | ✓ | cdn, offline-first, iot, sync | +| Messaging | ✓ | queues, pubsub, streams, delivery-semantics | + +## Languages + +> Language docs apply (not derive) domain principles. They introduce +> no new P-rules and no new matrix rows (D-063, D-066). First- +> principles stubs from v0.1; derived docs added in v0.4. + +| Language | First Principles | Derived Documents | +|----------|------------------|-------------------| +| TypeScript | ✓ (v0.1 stub) | ts-types, ts-tooling, ts-async, ts-testing | +| Python | ✓ (v0.1 stub) | py-types, py-tooling, py-async, py-testing | +| Go | ✓ (v0.1 stub) | go-types, go-tooling, go-concurrency, go-testing | +| Rust | ✓ (v0.1 stub) | rs-ownership, rs-tooling, rs-async, rs-testing | ## Examples @@ -71,8 +86,8 @@ | Document | Purpose | |-----------------------------------|----------------------------------| -| `matrix/principles-matrix.md` | Maps domain → core principles (17 domains, 170 P-rules post-v0.3) | -| `matrix/domain-coverage.md` | Maps core → domains; per-domain coverage (incl. v0.3 Core Principle Coverage) | -| `review/agent-checklist.md` | Pre-completion agent checklist (incl. IaC + k8s + gitops + ai-ml + i18n + compliance triggers) | -| `review/peer-review-checklist.md` | Human peer-review checklist (incl. IaC + k8s + gitops + ai-ml + i18n + compliance sections) | -| `review/anti-patterns.md` | Catalog of violations (incl. IaC + k8s + gitops + ai-ml + i18n + compliance + v0.3 chaos anti-patterns) | \ No newline at end of file +| `matrix/principles-matrix.md` | Maps domain → core principles (19 domains, 190 P-rules post-v0.4) | +| `matrix/domain-coverage.md` | Maps core → domains; per-domain coverage (incl. v0.4 Core Principle Coverage + Languages Coverage sub-table) | +| `review/agent-checklist.md` | Pre-completion agent checklist (incl. edge + messaging + language-derived triggers) | +| `review/peer-review-checklist.md` | Human peer-review checklist (incl. edge + messaging + language-derived sections) | +| `review/anti-patterns.md` | Catalog of violations (incl. edge + messaging + language-derived + v0.4 chaos anti-patterns + .ts/.py/.go/.rs artifact types) | \ No newline at end of file diff --git a/matrix/domain-coverage.md b/matrix/domain-coverage.md index 9bca719..a00d387 100644 --- a/matrix/domain-coverage.md +++ b/matrix/domain-coverage.md @@ -6,14 +6,14 @@ | Core Principle | Domains that derive from it | Count | |----------------|---------------------------|-------| -| C1 Correctness | All 17 (v0.1: 11; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance) | Universal | -| C2 Clarity | v0.1: uiux, api, data, testing, observability, errors, documentation, devops; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance | 14 | -| C3 Simplicity | v0.1: security, data, testing, performance, documentation, concurrency, devops; v0.2: infrastructure-as-code; v0.3: gitops-operators, i18n, compliance | 11 | -| C4 Locality | v0.1: testing, concurrency; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, i18n | 6 | -| C5 Reversibility | v0.1: api, data, uiux, concurrency, devops; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance | 11 | -| C6 Composability | v0.1: api, security, observability, errors, documentation, concurrency; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance | 12 | -| C7 Observability | v0.1: api, data, testing, performance, observability, errors, devops; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance | 13 | -| C8 Economy | v0.1: security, testing, performance, observability, concurrency; v0.2: kubernetes; v0.3: gitops-operators, i18n, compliance | 9 | +| C1 Correctness | All 19 (v0.1: 11; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance; v0.4: edge, messaging) | Universal | +| C2 Clarity | v0.1: uiux, api, data, testing, observability, errors, documentation, devops; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance; v0.4: messaging | 16 | +| C3 Simplicity | v0.1: security, data, testing, performance, documentation, concurrency, devops; v0.2: infrastructure-as-code; v0.3: gitops-operators, i18n, compliance; v0.4: edge | 12 | +| C4 Locality | v0.1: testing, concurrency; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, i18n; v0.4: edge, messaging | 8 | +| C5 Reversibility | v0.1: api, data, uiux, concurrency, devops; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance; v0.4: edge, messaging | 13 | +| C6 Composability | v0.1: api, security, observability, errors, documentation, concurrency; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance; v0.4: edge, messaging | 14 | +| C7 Observability | v0.1: api, data, testing, performance, observability, errors, devops; v0.2: infrastructure-as-code, kubernetes; v0.3: gitops-operators, ai-ml, i18n, compliance; v0.4: edge, messaging | 15 | +| C8 Economy | v0.1: security, testing, performance, observability, concurrency; v0.2: kubernetes; v0.3: gitops-operators, i18n, compliance; v0.4: edge, messaging | 11 | ## Interpretation @@ -43,6 +43,8 @@ | AI / ML | C1, C2, C5, C6, C7 | Reproducibility + lineage + serving observability | | i18n | C1, C2, C3, C4, C5, C6, C7, C8 | Locale + formatting + direction + reversibility; broadest derivation (8 C-rules) | | Compliance | C1, C2, C3, C5, C6, C7, C8 | Audit + policy-as-code + retention + posture | +| Edge | C1, C3, C4, C5, C6, C7, C8 | Proximity + offline + constraint; broad derivation (7 C-rules) | +| Messaging | C1, C2, C4, C5, C6, C7, C8 | Cross-process delivery + ordering + idempotency; broad derivation (7 C-rules) | ## v0.2 Domain Coverage (per IDEATE-03 schema) @@ -60,6 +62,39 @@ | i18n | 10 | 4 (locale-resources, formatting, rtl-bidi, testing-i18n) | ✓ | complete | | Compliance | 10 | 4 (audit-logs, data-retention, policy-as-code, evidence) | ✓ | complete | +## v0.4 Domain Coverage (per IDEATE-03 schema) + +| Domain | P-count | Derived-doc-count | Manifest-listed | Status | +|--------|---------|-------------------|-----------------|--------| +| Edge | 10 | 4 (cdn, offline-first, iot, sync) | ✓ | complete | +| Messaging | 10 | 4 (queues, pubsub, streams, delivery-semantics) | ✓ | complete | + +## Languages Coverage (v0.4, per D-066) + +> Language-derived docs apply existing domain P-rules. They introduce +> no new matrix rows (D-063, D-066). The sub-table is the verifiable +> aggregate; inline section-headers are the per-doc detail. Every +> derived doc traces to ≥1 domain P-rule (D-066, no orphans). + +| Language | Derived Doc | Traced Domain P-rules | Traced Core C-rules | +|----------|-------------|------------------------|---------------------| +| TypeScript | ts-types.md | Data P7, API P1, Errors P1 | C1, C5, C6 | +| TypeScript | ts-tooling.md | DevOps P2, DevOps P1, Documentation P1, DevOps P9 | C1, C2, C6, C8 | +| TypeScript | ts-async.md | Concurrency P7, Concurrency P8, Concurrency P9, Errors P5, Errors P1 | C1, C2, C5 | +| TypeScript | ts-testing.md | Testing P1, Testing P2, Testing P3, Testing P7, Testing P9, Data P7 | C1, C2 | +| Python | py-types.md | Data P7, API P1, Errors P1 | C1, C2, C6 | +| Python | py-tooling.md | DevOps P2, DevOps P1, Documentation P1, DevOps P9 | C1, C2, C3, C8 | +| Python | py-async.md | Concurrency P1, Concurrency P7, Concurrency P8, Concurrency P9, Errors P5, Errors P1 | C1, C2, C5, C6 | +| Python | py-testing.md | Testing P1, Testing P2, Testing P3, Testing P7, Testing P9, Concurrency P10 | C1, C2 | +| Go | go-types.md | Data P7, API P1, Errors P1, Errors P3 | C1, C2, C6 | +| Go | go-tooling.md | DevOps P2, DevOps P1, Concurrency P6, Documentation P1, DevOps P9 | C1, C2, C3, C7, C8 | +| Go | go-concurrency.md | Concurrency P1, Concurrency P3, Concurrency P5, Concurrency P6, Concurrency P7, Concurrency P8, Concurrency P9 | C1, C3, C4, C5, C6, C8 | +| Go | go-testing.md | Testing P1, Testing P2, Testing P3, Testing P7, Testing P9, Concurrency P6, Concurrency P10, API P1 | C1, C2 | +| Rust | rs-ownership.md | Concurrency P1, Concurrency P3, Concurrency P5, Data P7 | C1, C3, C4 | +| Rust | rs-tooling.md | DevOps P2, DevOps P1, Documentation P1, DevOps P9 | C1, C2, C3, C5, C8 | +| Rust | rs-async.md | Concurrency P5, Concurrency P7, Concurrency P8, Concurrency P9 | C1, C3, C5, C6, C8 | +| Rust | rs-testing.md | Testing P1, Testing P2, Testing P3, Testing P7, Testing P9, Concurrency P10, Documentation P1 | C1, C2 | + ## Gaps and Notes - No domain derives from only one C-rule. The minimum is 4 (UI/UX: C1, C2, C3, C5, C7 — actually 5). Every domain is multi-rooted. @@ -68,4 +103,6 @@ - **UI/UX** and **API** are the most user-facing; they emphasize C2 (Clarity) heavily. - **Security** is the only domain with explicit non-tradeable declarations; this promotes 8 of its rules to C1-equivalent per `core/conflict-resolution.md` §6. - **v0.2 expansion:** C4 (Locality) grew from 2 to 4 domains (added infrastructure-as-code state locality, kubernetes namespace blast-radius). C6 (Composability) grew from 6 to 8. The two new domains are broad-derivation domains (7 C-rules each), consistent with Concurrency's breadth. -- **v0.3 expansion:** C3 (Simplicity) grew from 7 to 11 (added gitops-operators declarative simplicity, i18n flexible layout, compliance structural redaction). C4 (Locality) grew from 4 to 6 (added gitops-operators pull-credential locality, i18n resource/text-direction locality). C5 (Reversibility) grew from 7 to 11 (added all four v0.3 domains — gitops history, ai-ml reproducibility, i18n translation versioning, compliance append-only/retention). C6 (Composability) grew from 8 to 12. C7 (Observability) grew from 9 to 13 (added all four v0.3 domains — reconciliation, drift detection, format correctness, posture). C2 (Clarity) grew from 10 to 14. The v0.3 expansion broadens every non-universal C-rule's coverage, confirming the four new domains are cross-cutting and well-rooted. \ No newline at end of file +- **v0.3 expansion:** C3 (Simplicity) grew from 7 to 11 (added gitops-operators declarative simplicity, i18n flexible layout, compliance structural redaction). C4 (Locality) grew from 4 to 6 (added gitops-operators pull-credential locality, i18n resource/text-direction locality). C5 (Reversibility) grew from 7 to 11 (added all four v0.3 domains — gitops history, ai-ml reproducibility, i18n translation versioning, compliance append-only/retention). C6 (Composability) grew from 8 to 12. C7 (Observability) grew from 9 to 13 (added all four v0.3 domains — reconciliation, drift detection, format correctness, posture). C2 (Clarity) grew from 10 to 14. The v0.3 expansion broadens every non-universal C-rule's coverage, confirming the four new domains are cross-cutting and well-rooted. +- **v0.4 expansion:** C2 (Clarity) grew from 14 to 16 (added messaging P1/P2/P4 — contract clarity). C4 (Locality) grew from 6 to 8 (added edge P1/P8 geographic locality, messaging P7 partition locality). C5 (Reversibility) grew from 11 to 13 (added edge P2/P4/P7/P10 reconciliation + degradation, messaging P5/P8/P9 replay + evolution). C6 (Composability) grew from 12 to 14 (added edge P8 fleet composition, messaging P7/P9 partition + version composition). C7 (Observability) grew from 13 to 15 (added edge P10 partition-survivable telemetry, messaging P8/P10 durable-log + lag). C8 (Economy) grew from 9 to 11 (added edge P3/P9 constrained resources + trust, messaging P6 bounded backpressure). C3 (Simplicity) grew from 11 to 12 (added edge P6 explicit invalidation simplicity). Both v0.4 domains are broad-derivation (7 C-rules each), consistent with the v0.2/v0.3 precedent. +- **Languages Coverage (v0.4, D-066):** The 16 language-derived docs (4 languages × 4 docs) apply existing domain P-rules; they introduce no new matrix rows (D-063, D-066). The sub-table above is the verifiable aggregate — every derived doc traces to ≥1 domain P-rule (no orphans). Languages are an application lens, not a principle source. \ No newline at end of file diff --git a/matrix/principles-matrix.md b/matrix/principles-matrix.md index 74bd66b..55fd5ec 100644 --- a/matrix/principles-matrix.md +++ b/matrix/principles-matrix.md @@ -265,8 +265,39 @@ C5=Reversibility · C6=Composability · C7=Observability · C8=Economy | P9 Secrets and Sensitive Data are Redacted in Audit | C1, C3 | Correctness via security; simplicity of structural redaction | | P10 Compliance Posture is Observable | C7, C1 | Observability of compliance; correctness of posture | -## Coverage Summary (post-v0.3) +## Edge -- 17 domains (11 v0.1 + 2 v0.2: infrastructure-as-code, kubernetes; 4 v0.3: gitops-operators, ai-ml, i18n, compliance) -- 170 domain principles total (110 v0.1 + 20 v0.2 + 40 v0.3) -- Every domain P-rule traces to ≥1 core C-rule (C1–C8). No orphans. \ No newline at end of file +| Edge Principle | Core | Why | +|-------------------------------------------------------|-------|--------------------------------------------------| +| P1 Proximity is the Design Driver | C4, C1 | Locality of compute near user/data; correctness via latency | +| P2 Offline is a First-Class State | C1, C5 | Correctness under partition; reversibility of reconciliation | +| P3 Resources are Constrained and Declared | C8, C1 | Economy of constrained nodes; correctness of declared bounds | +| P4 Sync Conflicts are Bounded, Not Infinite | C1, C5 | Correctness of convergence; reversibility of divergent state | +| P5 Edge Operations are Idempotent | C1 | Correctness under retry | +| P6 Cache Invalidation is Explicit | C1, C3 | Correctness of cached state; simplicity of defined invalidation | +| P7 Partial Degradation is Engineered | C1, C5 | Correctness of degraded modes; reversibility of recovery | +| P8 Geographic Distribution is a First-Class Constraint | C4, C6 | Locality of placement; composability of the fleet | +| P9 Identity is Constrained at the Edge | C1, C8 | Correctness via security; economy of trust | +| P10 Edge Observability Survives Partition | C7, C5 | Observability of the fleet; reversibility of buffered telemetry | + +## Messaging + +| Messaging Principle | Core | Why | +|--------------------------------------------------|-------|--------------------------------------------------| +| P1 Messages are Contracts | C1, C2 | Correctness of the exchange; clarity of the schema boundary | +| P2 Ordering is a Property, Not an Assumption | C1, C2 | Correctness of order; clarity of the guarantee | +| P3 Consumers are Idempotent | C1 | Correctness under redelivery | +| P4 Delivery Semantics are Explicit | C1, C2 | Correctness of the chosen semantic; clarity of the tradeoff | +| P5 Dead-Letter Handling is Defined | C1, C5 | Correctness of poison-message routing; reversibility of reprocessing | +| P6 Backpressure is Bounded | C1, C8 | Correctness of bounded backlog; economy of broker memory | +| P7 Partitioning is Intentional | C4, C6 | Locality of order; composability of parallelism | +| P8 Replay and Retention are Configured | C5, C7 | Reversibility of replay; observability of the durable log | +| P9 Schemas Evolve Compatibly | C5, C6 | Reversibility of schema changes; composability of versions | +| P10 Messaging is Observable | C7, C1 | Observability of lag/DLQ; correctness of backlog detection | + +## Coverage Summary (post-v0.4) + +- 19 domains (11 v0.1 + 2 v0.2: infrastructure-as-code, kubernetes; 4 v0.3: gitops-operators, ai-ml, i18n, compliance; 2 v0.4: edge, messaging) +- 190 domain principles total (110 v0.1 + 20 v0.2 + 40 v0.3 + 20 v0.4) +- Every domain P-rule traces to ≥1 core C-rule (C1–C8). No orphans. +- Language-derived docs (16) apply existing domain P-rules; they introduce no new matrix rows (D-063, D-066). See `matrix/domain-coverage.md` `## Languages Coverage` sub-table. \ No newline at end of file diff --git a/review/agent-checklist.md b/review/agent-checklist.md index 0a0e37d..ee068be 100644 --- a/review/agent-checklist.md +++ b/review/agent-checklist.md @@ -197,6 +197,37 @@ If the task touches a domain, run that domain's checklist: - [ ] Audit logs do not leak secrets; redaction is structural, not opportunistic (P9) - [ ] System reports its own compliance state (drift from policy, open violations, retention status) (P10) +### If Edge (see `domains/edge/`) +- [ ] Compute is placed near the user/data source; latency is treated as a correctness constraint, not a perf preference (P1) +- [ ] The system continues to operate offline; partition is the norm, not the exception; reconciliation happens on reconnect (P2) +- [ ] Edge-node resource constraints (CPU/memory/power/bandwidth) are declared per node class, not assumed infinite (P3) +- [ ] Sync conflicts converge; no oscillation or infinite sync loops (P4) +- [ ] Sync, cache-fill, and device commands are idempotent — retries are safe (P5) +- [ ] Edge caches have an explicit TTL or invalidation strategy; no TTL-less caches under partition (P6) +- [ ] Partial degradation is a designed state with a defined contract, not a crash (P7) +- [ ] Routing, fan-out, and data placement are location-aware decisions, not accidents of deployment (P8) +- [ ] Edge-device credentials are scoped and per-device; no edge node is a cluster-admin-equivalent (P9) +- [ ] Telemetry is local-first: buffered on-node and forwarded on reconnect; partition does not blind the operator (P10) + +### If Messaging (see `domains/messaging/`) +- [ ] Messages have an explicit, versioned schema; producer and consumer agree on shape before exchange (P1) +- [ ] Ordering guarantees (per-partition, global, none) are explicit and documented; "FIFO" is backed by the broker contract (P2) +- [ ] Consumers are idempotent — redelivery is deduped via idempotency keys or deterministic processing (P3) +- [ ] Delivery semantics (at-least-once/at-most-once/exactly-once) are a declared choice per channel (P4) +- [ ] Poison messages route to a dead-letter queue; the DLQ is observable and drainable (P5) +- [ ] Backpressure is bounded — consumer lag visible, max-unacked bounded, retry budget capped (P6) +- [ ] Partition key choice is a documented design decision (ordering vs parallelism vs hotspots) (P7) +- [ ] Retention windows and replay-from-offset are explicit; the broker is a durable log, not a pipe (P8) +- [ ] Schema changes are backward/forward-compatible; breaking changes are versioned migrations, not silent shape edits (P9) +- [ ] Consumer lag, DLQ depth, throughput, and consumer-group health are observed; silent backlog is a bug (P10) + +### If Language-Derived Docs (see `languages/`) +- [ ] Scope check: no new P-rules introduced — every section traces to an existing domain P-rule (D-063, D-066) +- [ ] Every section header names ≥1 traced domain P-rule AND the core C-rule(s) inline (e.g., `## Nominal vs Structural Typing (C1 Correctness, Data P7 Type Fidelity, API P1 Contract Fidelity)`) +- [ ] Fenced code examples are in-language and illustrative only — no standalone `.ts`/`.py`/`.go`/`.rs` runtime artifacts (D-020) +- [ ] The first-principles stub retains its section structure — no P1–P10 numbering added to languages (D-063) +- [ ] Cross-links to traced domain docs are present (≥1 outbound per derived doc, ATELIER-114) + ## Final Gate - [ ] Have I read the relevant domain's first-principles? diff --git a/review/anti-patterns.md b/review/anti-patterns.md index 5895c20..c338f8f 100644 --- a/review/anti-patterns.md +++ b/review/anti-patterns.md @@ -188,6 +188,72 @@ The following standalone file types are forbidden under `examples/` and elsewher | Signed manifests as standalone files (`.sig`, `.att`, `.intoto.jsonl`) | fenced code in `examples/*.md` | Runtime attestation artifact; violates docs-only contract | | Standalone `.yaml` / `.tf` / `.sh` | fenced code in `examples/*.md` | (Carried forward from v0.2) Runtime deployable artifact | +## v0.4 Chaos Anti-Patterns (from IDEATE-36, IDEATE-37, D-068, ATELIER-110) + +These are named, cross-cutting violations specific to the v0.4 domains. Single-breach per D-068. Reject on sight. + +| Anti-Pattern | Breaches | Why | +|--------------|----------|-----| +| Edge sync conflict loop (two nodes oscillate divergent state forever; no convergence) | edge P4 Sync Conflicts are Bounded, Not Infinite; C1, C5 | Infinite oscillation is a correctness failure, not eventual consistency; the sync is a livelock | +| Edge TTL-less cache (edge cache with no TTL and no explicit invalidation; stale forever under partition) | edge P6 Cache Invalidation is Explicit; C1, C3 | Stale-forever under partition is a silent correctness defect | +| Edge blocking call on constrained device (a synchronous blocking I/O call on a low-power IoT device with no timeout) | edge P3 Resources are Constrained, P5 (retry safety); C8, C1 | Blocks the constrained node; no timeout = hang; retry is unsafe without idempotency | +| Messaging shared subscription (two consumers share one subscription; each message processed by an arbitrary consumer, breaking per-consumer ordering and idempotency) | messaging P2 Ordering, P3 Idempotency; C1 | Shared subscription breaks ordering and dedup; the `messaging-shared-subscription` bad example lives here | +| Messaging blocking consumer (a consumer blocks on a slow downstream call with no timeout; the broker re-delivers to the same stuck consumer) | messaging P6 Backpressure is Bounded; C1, C8 | Blocks the partition; lag grows; no backpressure escape | +| Messaging unbounded retry / no DLQ (a poison message is retried forever with no dead-letter queue; the consumer never makes progress) | messaging P5 Dead-Letter Handling is Defined; C1, C5 | Infinite retry is a livelock; poison messages must DLQ | + +### v0.4 Deployable Artifact Types (IDEATE-36, D-020) + +The following standalone file types are forbidden under `languages/` and elsewhere in the framework (carried forward from v0.2/v0.3 and extended for language-derived docs). All examples and derived-doc code are `.md` files with fenced code only. + +| Forbidden standalone artifact | Belongs in | Why | +|-------------------------------|-----------|-----| +| Standalone `.ts` file | fenced code in `languages/*.md` (or `examples/*.md`) | Runtime TypeScript artifact; violates docs-only contract (v0.4 extension) | +| Standalone `.py` file | fenced code in `languages/*.md` (or `examples/*.md`) | Runtime Python artifact; violates docs-only contract (v0.4 extension) | +| Standalone `.go` file | fenced code in `languages/*.md` (or `examples/*.md`) | Runtime Go artifact; violates docs-only contract (v0.4 extension) | +| Standalone `.rs` file | fenced code in `languages/*.md` (or `examples/*.md`) | Runtime Rust artifact; violates docs-only contract (v0.4 extension) | +| Standalone `.yaml` / `.tf` / `.sh` | fenced code in `examples/*.md` | (Carried forward from v0.2/v0.3) Runtime deployable artifact | + +### v0.4 Language-Derived-Doc Anti-Patterns + +| Anti-Pattern | Breaches | Why | +|--------------|----------|-----| +| Language-derived doc introducing a new P-rule (e.g., "TS P1", "Python P2") | D-063, ARCHITECTURE.md hierarchy, matrix row-count invariant | Languages apply, not derive; breaks the hierarchy (`core > domains > languages`) and the 190-row invariant | +| Language-derived doc with no domain P-rule trace (orphan section — header names no domain P-rule) | D-066, matrix completeness | No trace = no traceability; the doc is not connected to the framework | +| Language-derived doc with runtime artifact (standalone `.ts`/`.py`/`.go`/`.rs` file) | D-020, PROJECT.md no-runtime-code | Violates the docs-only contract; must be fenced code in `.md` | +| Language first-principles stub gaining P1–P10 numbering | D-063 | Languages are not domains; no P-rules to number; breaks the apply-don't-derive scope | + +## v0.4 Domain-Specific Anti-Patterns + +### Edge + +| Anti-Pattern | Breaches | Why | +|--------------|----------|-----| +| Central-region-only deployment for a latency-bound workload | P1 Proximity is the Design Driver | Violates the proximity constraint; latency is a correctness defect | +| App that crashes on disconnect (no offline state) | P2 Offline is a First-Class State | Partition is the norm; crash-on-disconnect is unengineered | +| Undeclared edge-node resource budget (assumes infinite CPU/memory) | P3 Resources are Constrained and Declared | Unbounded = OOM on constrained nodes | +| Sync loop that oscillates forever (CRDT without merge-semantics, LWW without monotonic clock) | P4 Sync Conflicts are Bounded | Livelock; convergence is never reached | +| Non-idempotent edge write (cache-fill or device command retried with side effects) | P5 Edge Operations are Idempotent | Retry doubles the side effect | +| TTL-less edge cache under partition | P6 Cache Invalidation is Explicit | Stale-forever; silent staleness | +| Crash-on-node-failure (no partial-degradation contract) | P7 Partial Degradation is Engineered | Whole-system crash on one node's failure | +| Random geographic placement (no location-aware routing) | P8 Geographic Distribution is a First-Class Constraint | Latency and data-residency uncontrolled | +| Shared edge-device credential (one key for the whole fleet) | P9 Identity is Constrained at the Edge | One compromise = fleet compromise | +| Fire-and-forget telemetry (no on-node buffer; data lost on partition) | P10 Edge Observability Survives Partition | Partition blinds the operator | + +### Messaging + +| Anti-Pattern | Breaches | Why | +|--------------|----------|-----| +| Schemaless message (no versioned contract; consumer parses by guess) | P1 Messages are Contracts | No boundary; consumer breaks silently on shape change | +| "It's FIFO" with no documented partition contract | P2 Ordering is a Property, Not an Assumption | Undocumented ordering = assumed ordering = wrong ordering | +| Non-idempotent consumer under at-least-once delivery | P3 Consumers are Idempotent | Redelivery doubles the effect | +| Unstated delivery semantic (at-least-once vs exactly-once guessed) | P4 Delivery Semantics are Explicit | The tradeoff is made blindly | +| No dead-letter queue (poison message retried forever or dropped) | P5 Dead-Letter Handling is Defined | Livelock or silent loss | +| Unbounded retry budget (no cap; slow consumer stalls the partition) | P6 Backpressure is Bounded | Lag grows without bound | +| Default partition key (no rationale; hotspot or wrong-order) | P7 Partitioning is Intentional | Hotspot or ordering violation | +| Ephemeral broker (no retention; no replay) | P8 Replay and Retention are Configured | Not a durable log; replay impossible | +| Silent schema change (producer breaks consumers with no version bump) | P9 Schemas Evolve Compatibly | Breaking change without migration | +| Silent backlog (no lag metric; consumer falls behind invisibly) | P10 Messaging is Observable | Cannot fix what you cannot see | + ## v0.3 Domain-Specific Anti-Patterns ### GitOps + Operators diff --git a/review/peer-review-checklist.md b/review/peer-review-checklist.md index 4329c09..b7a6bbc 100644 --- a/review/peer-review-checklist.md +++ b/review/peer-review-checklist.md @@ -129,6 +129,39 @@ Run the relevant domain section from `agent-checklist.md` (UI/UX, API, Security, - [ ] Do audit logs avoid leaking secrets (redaction is structural, not opportunistic)? - [ ] Does the system report its own compliance state (drift from policy, open violations, retention status)? +### If Edge +- [ ] Scope check: is this the proximity/location/constraint angle, NOT generic perf or in-process concurrency? (D-061 — reject generic-performance or in-process-concurrency content as out-of-scope) +- [ ] Is compute placed near the user/data source, with latency treated as a correctness constraint (not a perf preference)? (P1) +- [ ] Does the system continue to operate offline; is partition the norm, not the exception? (P2) +- [ ] Are edge-node resource constraints (CPU/memory/power/bandwidth) declared per node class, not assumed infinite? (P3) +- [ ] Do sync conflicts converge; is there no oscillation or infinite sync loop? (P4) +- [ ] Are sync, cache-fill, and device commands idempotent (retries safe)? (P5) +- [ ] Do edge caches have an explicit TTL or invalidation strategy (no TTL-less caches under partition)? (P6) +- [ ] Is partial degradation a designed state with a defined contract (not a crash)? (P7) +- [ ] Are routing, fan-out, and data placement location-aware decisions? (P8) +- [ ] Are edge-device credentials scoped and per-device (no edge cluster-admin)? (P9) +- [ ] Is telemetry local-first (buffered on-node, forwarded on reconnect; partition does not blind the operator)? (P10) + +### If Messaging +- [ ] Scope check: is this cross-process/network-failure-model, NOT in-process concurrency? (D-062 — reject in-process-concurrency content as out-of-scope) +- [ ] Do messages have an explicit, versioned schema (producer and consumer agree on shape)? (P1) +- [ ] Are ordering guarantees (per-partition, global, none) explicit and documented? (P2) +- [ ] Are consumers idempotent (redelivery deduped via idempotency keys or deterministic processing)? (P3) +- [ ] Are delivery semantics (at-least-once/at-most-once/exactly-once) a declared choice per channel? (P4) +- [ ] Do poison messages route to a dead-letter queue (DLQ observable and drainable)? (P5) +- [ ] Is backpressure bounded (consumer lag visible, max-unacked bounded, retry budget capped)? (P6) +- [ ] Is partition key choice a documented design decision (ordering vs parallelism vs hotspots)? (P7) +- [ ] Are retention windows and replay-from-offset explicit (durable log, not pipe)? (P8) +- [ ] Are schema changes backward/forward-compatible (breaking changes are versioned migrations)? (P9) +- [ ] Are consumer lag, DLQ depth, throughput, and consumer-group health observed (silent backlog is a bug)? (P10) + +### If Language-Derived Docs +- [ ] Scope check: apply, don't derive — no new P-rules, no new matrix rows (D-063, D-066 — reject any "TS P1"/"Python P2" etc. new-P-rule content) +- [ ] Does every section header name ≥1 traced domain P-rule AND the core C-rule(s) inline? +- [ ] Are fenced code examples in-language and illustrative only (no standalone `.ts`/`.py`/`.go`/`.rs` runtime artifacts)? (D-020) +- [ ] Does the first-principles stub retain its section structure (no P1–P10 numbering added to languages)? (D-063) +- [ ] Are cross-links to traced domain docs present (≥1 outbound per derived doc)? (ATELIER-114) + ## Review Etiquette - **Comment, don't command.** "This could be X" not "Change this to X."