diff --git a/MANIFEST.md b/MANIFEST.md index 0d6c919..93a1556 100644 --- a/MANIFEST.md +++ b/MANIFEST.md @@ -36,13 +36,43 @@ | DevOps | ✓ | ci-cd, environments | | Infrastructure as Code | ✓ | terraform, opentofu, state, modules | | Kubernetes | ✓ | workloads, networking, storage, rbac, helm, kustomize | +| GitOps + Operators | ✓ | argocd, flux, operators, progressive-delivery | +| 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 | + +## Examples + +> Examples are illustrative markdown with fenced code only (no standalone runtime artifacts per D-020 / D-025). The `examples/` directory listing closes the v0.2 ESC-002 drift (IDEATE-17, ATELIER-91). P5 examples populate this section. + +| Path | Status | Notes | +|------|--------|-------| +| `examples/good/` | (pending P5) | Good-example directory — to be populated by v0.3 P5 | +| `examples/bad/` | (pending P5) | Bad-example directory — to be populated by v0.3 P5 | +| `examples/good/api-endpoint.md` | (pending P5) | v0.1 example — to be listed when P5 back-fills | +| `examples/good/react-component.md` | (pending P5) | v0.1 example — to be listed when P5 back-fills | +| `examples/good/db-schema.md` | (pending P5) | v0.1 example — to be listed when P5 back-fills | +| `examples/good/error-handler.md` | (pending P5) | v0.1 example — to be listed when P5 back-fills | +| `examples/bad/god-object.md` | (pending P5) | v0.1 example — to be listed when P5 back-fills | +| `examples/bad/silent-error.md` | (pending P5) | v0.1 example — to be listed when P5 back-fills | +| `examples/bad/leaky-abstraction.md` | (pending P5) | v0.1 example — to be listed when P5 back-fills | +| `examples/good/terraform-module.md` | (pending P5) | v0.2 example — to be listed when P5 back-fills | +| `examples/good/k8s-deployment.md` | (pending P5) | v0.2 example — to be listed when P5 back-fills | +| `examples/bad/terraform-unlocked-state.md` | (pending P5) | v0.2 example — to be listed when P5 back-fills | +| `examples/bad/k8s-bare-pod-no-resources.md` | (pending P5) | v0.2 example — to be listed when P5 back-fills | +| `examples/good/gitops-pr.md` | (pending P5) | v0.3 example — to be authored in P5 | +| `examples/good/ai-ml-reproducibility.md` | (pending P5) | v0.3 example — to be authored in P5 | +| `examples/bad/i18n-string-concat.md` | (pending P5) | v0.3 example — to be authored in P5 | +| `examples/bad/compliance-audit-log.md` | (pending P5) | v0.3 example — to be authored in P5 | + +> **Note:** The `examples/` section structure is established here (P4) so P5 can populate it. Files marked "pending P5" do not yet exist; they will be authored in Phase 5 and promoted from `pending` to `✓` upon completion. Listing them here as `pending` makes the manifest authoritative about what *will* exist and prevents drift. ## Cross-Cutting | Document | Purpose | |-----------------------------------|----------------------------------| -| `matrix/principles-matrix.md` | Maps domain → core principles (13 domains, 130 P-rules post-v0.2) | -| `matrix/domain-coverage.md` | Maps core → domains; per-domain coverage | -| `review/agent-checklist.md` | Pre-completion agent checklist (incl. IaC + k8s triggers) | -| `review/peer-review-checklist.md` | Human peer-review checklist (incl. IaC + k8s sections) | -| `review/anti-patterns.md` | Catalog of violations (incl. IaC + k8s + chaos anti-patterns) | \ No newline at end of file +| `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 diff --git a/matrix/domain-coverage.md b/matrix/domain-coverage.md index 1b52a36..769eb4e 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 13 (v0.1: 11; v0.2: infrastructure-as-code, kubernetes) | Universal | -| C2 Clarity | v0.1: uiux, api, data, testing, observability, errors, documentation, devops; v0.2: infrastructure-as-code, kubernetes | 10 | -| C3 Simplicity | v0.1: security, data, testing, performance, documentation, concurrency, devops | 7 | -| C4 Locality | v0.1: testing, concurrency; v0.2: infrastructure-as-code, kubernetes | 4 | -| C5 Reversibility | v0.1: api, data, uiux, concurrency, devops; v0.2: infrastructure-as-code, kubernetes | 7 | -| C6 Composability | v0.1: api, security, observability, errors, documentation, concurrency; v0.2: infrastructure-as-code, kubernetes | 8 | -| C7 Observability | v0.1: api, data, testing, performance, observability, errors, devops; v0.2: infrastructure-as-code, kubernetes | 9 | -| C8 Economy | v0.1: security, testing, performance, observability, concurrency; v0.2: kubernetes | 6 | +| 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 | ## Interpretation @@ -39,6 +39,10 @@ | DevOps | C1, C2, C3, C5, C7 | Reproducibility + rollback | | Infrastructure as Code | C1, C2, C3, C4, C5, C6, C7 | Declarative + state + composition; broadest derivation alongside Concurrency | | Kubernetes | C1, C2, C4, C5, C6, C7, C8 | Declarative + reversibility + economy; broad derivation (7 C-rules) | +| GitOps + Operators | C1, C2, C3, C4, C5, C6, C7, C8 | Source-of-truth + reconciliation + pull-locality + least privilege; broadest derivation (8 C-rules, tied with i18n) | +| 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 | ## v0.2 Domain Coverage (per IDEATE-03 schema) @@ -47,10 +51,21 @@ | Infrastructure as Code | 10 | 4 (terraform, opentofu, state, modules) | ✓ | complete | | Kubernetes | 10 | 6 (workloads, networking, storage, rbac, helm, kustomize) | ✓ | complete | +## v0.3 Domain Coverage (per IDEATE-03 schema) + +| Domain | P-count | Derived-doc-count | Manifest-listed | Status | +|--------|---------|-------------------|-----------------|--------| +| GitOps + Operators | 10 | 4 (argocd, flux, operators, progressive-delivery) | ✓ | complete | +| AI / ML | 10 | 4 (data-versioning, model-evaluation, serving, monitoring-drift) | ✓ | complete | +| i18n | 10 | 4 (locale-resources, formatting, rtl-bidi, testing-i18n) | ✓ | complete | +| Compliance | 10 | 4 (audit-logs, data-retention, policy-as-code, evidence) | ✓ | complete | + ## 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. -- **Concurrency**, **Infrastructure as Code**, and **Kubernetes** are tied for the broadest derivation (7 C-rules each) — these domains touch the most core concerns. +- **Concurrency**, **Infrastructure as Code**, and **Kubernetes** are tied for the broadest derivation among v0.1/v0.2 platform domains (7 C-rules each) — these domains touch the most core concerns. +- **GitOps + Operators** and **i18n** are tied for the single broadest-derivation domain overall (8 C-rules each: C1–C8). GitOps adds C4 (pull-credential locality) alongside its source-of-truth/reconciliation/least-privilege derivation; i18n touches correctness, clarity, simplicity, locality, reversibility, composability, observability, and economy (expansion accommodation). This is consistent with both domains' cross-cutting nature. - **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. \ No newline at end of file +- **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 diff --git a/matrix/principles-matrix.md b/matrix/principles-matrix.md index 41a4012..74bd66b 100644 --- a/matrix/principles-matrix.md +++ b/matrix/principles-matrix.md @@ -205,8 +205,68 @@ C5=Reversibility · C6=Composability · C7=Observability · C8=Economy | P9 Config and Secrets Sep | C2 | Clarity of configuration | | P10 Roll Forward, Roll Back | C5 | Reversibility of deploys | -## Coverage Summary (post-v0.2) +## GitOps + Operators -- 13 domains (11 v0.1 + 2 v0.2: infrastructure-as-code, kubernetes) -- 130 domain principles total (110 v0.1 + 20 v0.2) +| GitOps Principle | Core | Why | +|---------------------------|------|---------------------------------------| +| P1 Git is the Source of Truth | C1, C5 | Correctness of source; reversibility via history | +| P2 Declarative Over Imperative | C2, C3 | Clarity of intent; simplicity of expression | +| P3 Pull, Don't Push | C1, C4 | Correctness via security; locality of credentials | +| P4 Continuous Reconciliation | C7, C1 | Observability of drift; correctness of converge loop | +| P5 State is Immutable and Versioned | C5 | Reversibility through history | +| P6 Operators Encode Domain Knowledge | C6, C2 | Composability of expertise; clarity of operations | +| P7 Progressive Delivery is Reversible | C5, C1 | Reversibility of promotion; correctness of abort | +| P8 Reconcile, Don't Mutate by Hand | C1, C7 | Correctness of source of truth; observability of drift | +| P9 Failure is Observable and Surfaced | C7 | Observability of sync/rollout health | +| P10 Least Privilege Reconciliation | C1, C8 | Correctness via security; economy of trust | + +## AI / ML + +| AI/ML Principle | Core | Why | +|---------------------------|------|---------------------------------------| +| P1 Reproducibility is the First Class | C1, C5 | Correctness of runs; reversibility of reproduction | +| P2 Data is Versioned, Not Just Code | C5, C7 | Reversibility of data; observability of dataset lineage | +| P3 Lineage is Traceable End-to-End | C7, C1 | Observability of predictions; correctness of provenance | +| P4 Evaluation is Defined Before Training | C1, C2 | Correctness of metrics; clarity of thresholds | +| P5 Models are Versioned Artifacts | C5, C6 | Reversibility of model rollbacks; composability of registry | +| P6 Serving is Observable | C7 | Observability of inference | +| P7 Drift is Expected and Detected | C7, C1 | Observability of drift; correctness of detection | +| P8 Inference Inputs are Validated | C1 | Correctness at serving boundary | +| P9 Pipelines Compose, Notebooks Don't | C6, C2 | Composability of steps; clarity of contracts | +| P10 Rollback Includes the Model | C5 | Reversibility at the model layer | + +## i18n + +| i18n Principle | Core | Why | +|---------------------------|------|---------------------------------------| +| P1 Source Language is a Locale, Not the Default | C2, C1 | Clarity; correctness of localization model | +| P2 Locale Identifiers are Standardized | C2, C6 | Clarity; composability of BCP 47 | +| P3 Resources are External, Not Inline | C4, C6 | Locality of strings; composability of resources | +| P4 Plural and Gender are Parameterized | C1, C6 | Correctness across locales; composability of message format | +| P5 Formatting is Locale-Aware | C1, C7 | Correctness of formats; observability of format correctness | +| P6 Text Direction is a Layout Primitive | C1, C4 | Correctness of RTL/bidi; locality of direction | +| P7 Layout Accommodates Expansion | C8, C3 | Economy of rework; simplicity of flexible layout | +| P8 Pseudo-Locales Test Early | C7, C5 | Observability of bugs early; reversibility of finding late | +| P9 Images and Icons are Cultural | C1, C2 | Correctness; clarity of cultural meaning | +| P10 Translation is Reversible and Versioned | C5 | Reversibility of localization changes | + +## Compliance + +| Compliance Principle | Core | Why | +|---------------------------|------|---------------------------------------| +| P1 Audit Logs are Append-Only | C1, C5 | Correctness of audit; reversibility of immutable record | +| P2 Every Significant Action is Logged | C7, C1 | Observability of actions; correctness of audit set | +| P3 Retention is Policy, Not Storage | C5, C8 | Reversibility of lifecycle; economy of storage | +| P4 Policy is Code | C6, C2 | Composability of policy; clarity of rules | +| P5 Policy is Evaluated as a Gate | C1, C5 | Correctness of enforcement; reversibility of block | +| P6 Evidence is Collected Continuously | C7, C3 | Observability of posture; simplicity of audit | +| P7 Identity is Attributable | C1, C7 | Correctness of attribution; observability of subject | +| P8 Subject Access is Honored | C1, C5 | Correctness of rights; reversibility of deletion/export | +| 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) + +- 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 diff --git a/review/agent-checklist.md b/review/agent-checklist.md index bd08d51..0a0e37d 100644 --- a/review/agent-checklist.md +++ b/review/agent-checklist.md @@ -147,6 +147,56 @@ If the task touches a domain, run that domain's checklist: - [ ] Rollout history retained; rollback tested (P10) - [ ] Namespaces used to bound blast radius; not `default` in prod (P6) +### If GitOps + Operators (see `domains/gitops-operators/`) +- [ ] Desired state lives in git, not in the cluster (P1) +- [ ] Configuration is declarative, not imperative scripts (P2) +- [ ] Reconciliation is pull-based; no external push credentials into the cluster (P3) +- [ ] Reconciliation loop runs continuously; drift auto-corrected (P4) +- [ ] Every change is a commit; history is the audit/rollback path (P5) +- [ ] Operational knowledge encoded as CRDs/controllers, not runbooks (P6) +- [ ] Progressive delivery (canary/blue-green) has a tested abort/rollback path (P7) +- [ ] No manual `kubectl apply`/`kubectl edit` on GitOps-managed resources (P8) +- [ ] Sync failures, health degradation, and rollout stalls emit status + notifications (P9) +- [ ] Controller credentials scoped to reconciled namespaces/resources; no cluster-admin GitOps robot (P10) + +### If AI / ML (see `domains/ai-ml/`) +- [ ] Scope check: this is engineering discipline (data versioning, evaluation, serving, drift), NOT algorithm/model design (D-023) — reject algorithm-design content +- [ ] Every training run is reproducible from pinned data + code + config + environment (P1) +- [ ] Datasets, features, and splits are versioned artifacts with lineage; `git` alone is insufficient (P2) +- [ ] Any deployed prediction traces back through model → training run → dataset → source (P3) +- [ ] Metrics, splits, and thresholds declared a priori; no post-hoc metric cherry-picking (P4) +- [ ] Models are pinned, immutable, registry-tracked artifacts; never "the latest" (P5) +- [ ] Inference latency, throughput, input distributions, and prediction confidence are observed (P6) +- [ ] Data drift, concept drift, and prediction drift are monitored; a drift signal is an incident (P7) +- [ ] Inference inputs validated against the model's contract (schema, ranges, types); out-of-contract rejected (P8) +- [ ] Training/serving flows are composable pipelines with explicit steps; notebooks not in production (P9) +- [ ] Serving rollback restores the prior model artifact, not just the prior code (P10) + +### If i18n (see `domains/i18n/`) +- [ ] Source language treated as one locale among many, not the "neutral" default (P1) +- [ ] Locale identifiers use BCP 47 tags; no ad-hoc locale codes (P2) +- [ ] User-facing strings in locale resource files, not concatenated inline in code (P3) +- [ ] Plural/gender/select use ICU MessageFormat (or equivalent); no `if (n == 1)` branching (P4) +- [ ] Dates, times, numbers, currencies, units via ICU/CLDR/`Intl`; no hand-rolled formatters (P5) +- [ ] RTL/bidi is a first-class layout concern; logical CSS properties (`start`/`end`) over physical (`left`/`right`) (P6) +- [ ] Layouts accommodate translation expansion; no fixed pixel widths for text (P7) +- [ ] Pseudo-locales (accented, lengthened, RTL-mirrored) used to test before real translations arrive (P8) +- [ ] Icons, colors, and imagery reviewed for locale-sensitivity; no locale-bound symbols treated as universal (P9) +- [ ] Resource files versioned; a bad translation is a rollback, not a hot-patch (P10) + +### If Compliance (see `domains/compliance/`) +- [ ] Scope check: framework-agnostic — no regulation-specific (GDPR/HIPAA/SOC2/PCI) content (D-024) +- [ ] Audit records are immutable once written; deletion/mutation is itself an auditable incident (P1) +- [ ] The set of auditable actions is defined a priori; "we forgot to log it" is a violation (P2) +- [ ] Data lifetime is declared and enforced as policy; deletion at end-of-life is a feature (P3) +- [ ] Compliance policy expressed in versioned, reviewable, testable code (OPA/Cedar/Kyverno/Sentinel), not spreadsheets/prose (P4) +- [ ] Policy violations block before the action (admission/CI/CD-time), not after the audit (P5) +- [ ] Evidence gathered as a byproduct of operation, not assembled manually at audit time (P6) +- [ ] Every logged action traces to an authenticated principal; no shared/generic identities (P7) +- [ ] Data-subject rights (access, export, deletion) are operations with defined contracts and audit trails (P8) +- [ ] 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) + ## Final Gate - [ ] Have I read the relevant domain's first-principles? diff --git a/review/anti-patterns.md b/review/anti-patterns.md index de735af..5895c20 100644 --- a/review/anti-patterns.md +++ b/review/anti-patterns.md @@ -163,4 +163,65 @@ When you see a pattern listed here, it is a defect. Cite the principle it violat |--------------|----------|-----| | Orphaned P-rule (a domain principle with no matrix row) | matrix completeness, C6 | Breaks the conflict-resolution arbiter; the rule has no core trace | | Deployable example artifact (standalone `.tf`/`.yaml` under `examples/`) | PROJECT.md "no runtime code", D-025 | Violates the docs-only contract; examples must be `.md` with fenced code | -| Unlisted v0.2 doc (new doc not added to MANIFEST) | manifest rule | Not part of the framework by definition | \ No newline at end of file +| Unlisted v0.2 doc (new doc not added to MANIFEST) | manifest rule | Not part of the framework by definition | + +## v0.3 Chaos Anti-Patterns (from IDEATE-20, IDEATE-24, IDEATE-25, IDEATE-27) + +These are named, cross-cutting violations specific to the v0.3 domains. Reject on sight. + +| Anti-Pattern | Breaches | Why | +|--------------|----------|-----| +| GitOps push-pattern (external CI pushes manifests to the cluster instead of an in-cluster agent pulling from git) | gitops P3 Pull, Don't Push; C1, C4 | Inverts the source-of-truth flow; requires push credentials into the cluster; breaks the reconciliation model (IDEATE-24, D-042) | +| i18n LTR-only assumption (layout assumes left-to-right; no `dir` attribute, physical CSS properties only) | i18n P6 Text Direction is a Layout Primitive; C1, C4 | Disqualifying for RTL/Bidi users; locale-correctness violation (IDEATE-25, D-043) | +| AI/ML orphan-model (a deployed prediction endpoint whose model has no lineage trace — no record of training run, dataset, or version) | ai-ml P3 Lineage is Traceable End-to-End; C7, C1 | Unreviewable, unrollbackable; the model is an unattributed artifact (IDEATE-27, D-045) | +| Compliance mutable audit log (audit records can be edited or deleted by an operator) | compliance P1 Audit Logs are Append-Only; C1, C5 | Destroys the audit trail; the audit log's value is immutability — mutation is itself an incident | + +### v0.3 Deployable Artifact Types (IDEATE-20, D-020) + +The following standalone file types are forbidden under `examples/` and elsewhere in the framework. Examples are `.md` files with fenced code only. + +| Forbidden standalone artifact | Belongs in | Why | +|-------------------------------|-----------|-----| +| `.po` / `.pot` resource files | fenced code in `examples/good/`/`examples/bad/*.md` | Runtime localization artifact; violates docs-only contract | +| `.rego` / `.cedar` / `.sentinel` policy files | fenced code in `examples/*.md` | Runtime policy artifact; violates docs-only contract | +| Model artifacts (`.pkl`, `.onnx`, `.pt`, `.h5`, `.safetensors`) | fenced code + prose in `examples/*.md` | Runtime model artifact; violates docs-only contract | +| 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.3 Domain-Specific Anti-Patterns + +### GitOps + Operators + +| Anti-Pattern | Breaches | Why | +|--------------|----------|-----| +| Push-based deploy (external CI `kubectl apply` into the cluster) | P3 Pull, Don't Push | Inverts the model; requires push credentials; bypasses reconciliation | +| Manual `kubectl apply`/`kubectl edit` on a GitOps-managed resource | P8 Reconcile, Don't Mutate by Hand | Unreconciled drift; the next loop overwrites it — silent and unattributed | +| `cluster-admin` GitOps robot (controller bound to cluster-admin) | P10 Least Privilege Reconciliation | Overbroad grant; blast radius = entire cluster | +| No sync-failure notification (silent drift on health degradation) | P9 Failure is Observable and Surfaced | Silent drift is the bug the loop was supposed to surface | + +### AI / ML + +| Anti-Pattern | Breaches | Why | +|--------------|----------|-----| +| Unreproducible training run (unpinned data, code, config, or environment) | P1 Reproducibility is the First Class | Unreviewable; cannot debug, cannot rollback | +| "Use the latest model" (serving points at `model:latest` instead of a pinned version) | P5 Models are Versioned Artifacts | Unversioned drift; rollback undefined | +| Notebook in production (training/serving flow is a Jupyter notebook) | P9 Pipelines Compose, Notebooks Don't | No contracts, no composition, no reproducibility | +| Orphan model (deployed prediction with no lineage trace) | P3 Lineage is Traceable End-to-End | Unattributed artifact; cannot trace to data/code (IDEATE-27) | + +### i18n + +| Anti-Pattern | Breaches | Why | +|--------------|----------|-----| +| Inline string concatenation (`"Hello, " + name + "!"` in code) | P3 Resources are External, Not Inline | Not extractable; breaks translations; word-order differs per locale | +| `if (n == 1)` plural branching (hand-rolled plural logic) | P4 Plural and Gender are Parameterized | Wrong for Arabic, Russian, Polish; ICU MessageFormat handles plurals | +| LTR-only layout (no `dir` attribute, physical CSS `left`/`right`) | P6 Text Direction is a Layout Primitive | Disqualifying for RTL/Bidi (IDEATE-25) | +| Hand-rolled date/number formatter (`new Date().toString()`, manual string formatting) | P5 Formatting is Locale-Aware | Locale-incorrect; ignores ICU/CLDR | + +### Compliance + +| Anti-Pattern | Breaches | Why | +|--------------|----------|-----| +| Mutable audit log (operator can `UPDATE`/`DELETE` audit records) | P1 Audit Logs are Append-Only | Destroys the audit trail; mutation is itself an incident | +| Shared/generic identity in audit (`admin` or `system` as the actor for all actions) | P7 Identity is Attributable | No attribution; no accountability; cannot investigate | +| Secret leaked in audit log (request body or token captured in an audit event) | P9 Secrets and Sensitive Data are Redacted in Audit | Audit log becomes a secret exfiltration channel | +| Manual evidence assembly at audit time (scramble to collect logs/scans/attestations on demand) | P6 Evidence is Collected Continuously | Audit-unready; evidence gathered under pressure is incomplete and unreliable | \ No newline at end of file diff --git a/review/peer-review-checklist.md b/review/peer-review-checklist.md index 807e1bd..4329c09 100644 --- a/review/peer-review-checklist.md +++ b/review/peer-review-checklist.md @@ -79,6 +79,56 @@ Run the relevant domain section from `agent-checklist.md` (UI/UX, API, Security, - [ ] Are ConfigMaps and Secrets separate? - [ ] Is the rollback path tested, not assumed? +### If GitOps + Operators +- [ ] Is desired state sourced from git, not from the cluster? +- [ ] Is configuration declarative, not imperative scripts? +- [ ] Is reconciliation pull-based (no external push credentials into the cluster)? +- [ ] Does the reconciliation loop run continuously and auto-correct drift? +- [ ] Is every change a commit, with history as the audit/rollback path? +- [ ] Is operational knowledge encoded as CRDs/controllers, not runbooks humans must remember? +- [ ] Does progressive delivery (canary/blue-green) have a tested abort/rollback path? +- [ ] Are there manual `kubectl apply`/`kubectl edit` on GitOps-managed resources? (flag as incident) +- [ ] Do sync failures, health degradation, and rollout stalls emit status + notifications? +- [ ] Are controller credentials scoped to reconciled namespaces/resources (no cluster-admin GitOps robot)? + +### If AI / ML +- [ ] Scope check: is this engineering discipline (data versioning, evaluation, serving, drift), NOT algorithm/model design? (D-023 — reject algorithm-design content) +- [ ] Is every training run reproducible from pinned data + code + config + environment? +- [ ] Are datasets, features, and splits versioned artifacts with lineage (not just `git`)? +- [ ] Can any deployed prediction trace back through model → training run → dataset → source? +- [ ] Are metrics, splits, and thresholds declared a priori (no post-hoc metric cherry-picking)? +- [ ] Are models pinned, immutable, registry-tracked artifacts (never "the latest")? +- [ ] Is inference observable (latency, throughput, input distributions, prediction confidence)? +- [ ] Are data drift, concept drift, and prediction drift monitored (drift signal = incident)? +- [ ] Are inference inputs validated against the model's contract (schema, ranges, types)? +- [ ] Are training/serving flows composable pipelines (not notebooks in production)? +- [ ] Does serving rollback restore the prior model artifact, not just the prior code? + +### If i18n +- [ ] Is the source language treated as one locale among many, not the "neutral" default? +- [ ] Do locale identifiers use BCP 47 tags (no ad-hoc locale codes)? +- [ ] Are user-facing strings in locale resource files (not concatenated inline in code)? +- [ ] Do plural/gender/select use ICU MessageFormat (no `if (n == 1)` branching)? +- [ ] Are dates, times, numbers, currencies, units formatted via ICU/CLDR/`Intl` (no hand-rolled formatters)? +- [ ] Is RTL/bidi a first-class layout concern (logical CSS properties over physical)? +- [ ] Do layouts accommodate translation expansion (no fixed pixel widths for text)? +- [ ] Are pseudo-locales used to test before real translations arrive? +- [ ] Are icons, colors, and imagery reviewed for locale-sensitivity? +- [ ] Are resource files versioned (bad translation = rollback, not hot-patch)? + +### If Compliance +- [ ] Scope check: is this framework-agnostic (no regulation-specific GDPR/HIPAA/SOC2/PCI content)? (D-024) +- [ ] Are audit records immutable once written (deletion/mutation is itself an auditable incident)? +- [ ] Is the set of auditable actions defined a priori ("we forgot to log it" is a violation)? +- [ ] Is data lifetime declared and enforced as policy (deletion at end-of-life is a feature)? +- [ ] Is compliance policy expressed in versioned, reviewable, testable code (not spreadsheets/prose)? +- [ ] Do policy violations block before the action (admission/CI/CD-time, not after the audit)? +- [ ] Is evidence gathered as a byproduct of operation (not assembled manually at audit time)? +- [ ] Does every logged action trace to an authenticated principal (no shared/generic identities)? +- [ ] Are data-subject rights (access, export, deletion) operations with defined contracts and audit trails? +- [ ] 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)? + ## Review Etiquette - **Comment, don't command.** "This could be X" not "Change this to X."