14 Commits

Author SHA1 Message Date
Jon Chery bee9d02f01 feat(P40): contract interpolation + environment JSON schema
---ci---
project: acdl
phase: 40
milestone: v1.9
status: execute
---/ci---

Phase 40 — contract-interpolation (REQ-103, REQ-104, D-081):

Interpolation:
- core/contract_resolver.py: _expand_vars(value, context) recursively
  expands ${env.<field>} + ${contract.<field>} tokens (dotted paths
  supported, e.g. ${env.state_backend.bucket}). Unknown tokens raise
  ValueError (fail loud). Expansion is post-schema-validation,
  pre-IR-resolution.
- resolve() accepts environment_override (D-088) — overrides the
  contract's environment field BEFORE schema validation so interpolation
  context is consistent.
- env context loaded via _load_env (self-contained, works as script +
  package import); 'environment' alias for env 'name' so
  ${env.environment} resolves.

Environment schema + bindings:
- schemas/environment.schema.json (draft 2020-12): name, account_id,
  region, state_backend, network, runner_role_arn, autonomy, confidence_threshold.
- core/environments/qa.json, prod.json, dr.json placeholder bindings
  (attested, thresholds 0.75/0.90/0.95, placeholder account_id with
  stderr warning at load).
- core/environment_check.py: load(env_name) helper + placeholder warning.

Sample contracts:
- contracts/static-assets.yaml + microservice.yaml use
  acdl-${env.environment}-${contract.module}-${env.account_id}-${env.region}
  naming pattern (region + account id + environment).

Tests: +35 (test_environment_schema.py, test_interpolation.py,
test_sample_contracts_interpolate.py). 406 passed; run_ci.sh green;
run_platform.sh --check-only green. Existing fixture-based tests
preserved (instance.json static fixtures unaffected).
2026-07-23 04:30:30 +00:00
Jon Chery 3562f6f771 docs(P36): schemas/adapters/pipelines READMEs (REQ-97, REQ-98, REQ-99)
---ci---
project: acdl
phase: 36
milestone: v1.8
status: execute
---/ci---

- schemas/README.md: how to write schemas, wire into platform, test in
  CI, dependencies, existing catalog, adding a new schema.
- pipelines/README.md: how to write pipeline contracts, wire into
  workflows, test, dependencies, existing catalog, adding a new pipeline.
- adapters/README.md: how to write adapters (Terraform + policy patterns),
  wire into platform, test, dependencies, existing catalog, adding a new
  adapter.
- tests/test_docs_coverage.py: 6 tests validating all 3 READMEs exist
  with required sections.

Tests: +6 (344 -> 350). All pass.
2026-07-22 22:22:18 +00:00
Jon Chery 8145eee8fc feat(P32): deletion-protection-by-default + L2 feature flag (REQ-86, REQ-87)
---ci---
project: acdl
phase: 32
milestone: v1.8
status: execute
---/ci---

- All 11 L1 primitives now have deletion_protection NFR (boolean, default true).
- Adapter emits `lifecycle { prevent_destroy = true }` when NFR is true;
  omits it when false. Default is true when NFR is absent.
- L2 composition resolver propagates inputs.deletion_protection to all
  children NFRs. When false, all resources get deletion_protection=false.
- Stack schema updated with optional features object (deletion_protection,
  uptime_enabled).
- Contract schema description updated to document deletion_protection
  and uptime_enabled inputs.

Tests: +5 (307 -> 312). All pass.
2026-07-22 22:12:42 +00:00
Jon Chery 2e2064559a verify(P22-27): code review — 1 P0 auto-fixed, 2 P1 security fixes, 2 P2 nits
acdl-ci / Lint (push) Successful in 8s
acdl-ci / Test (push) Successful in 25s
acdl-ci / Platform check-only (offline) (push) Successful in 10s
---ci---
project: acdl
phase: 22-27
milestone: v1.7
status: verify
lessons:
  - P0 fix: run_platform.sh check-only assertions were hardcoded to static-assets; generalized for all contracts
  - P1 fix: URL-encode contractId in GitHub issue search to prevent query injection
  - P1 fix: validate consumerRepo format against invoking principal identity (P1-2)
  - P2 fix: tagging-standard.json description referenced .yaml instead of .py
  - P2 fix: removed unused graph_resource_name_utils import in acdl_tagging.py
---/ci---

Multi-persona code review of the v1.7 milestone (130 files, +5568/-353).

P0 (1, auto-fixed):
  - run_platform.sh --check-only hardcoded static-assets assertions broke
    for other contracts (microservice). Generalized to structural checks.

P1 security fixes applied (2 of 9):
  - P1-1: URL-encode contractId in GitHub search query (injection prevention)
  - P1-2: Validate consumerRepo format (org/repo) when caller identity present

P1 flagged for post-hoc (7):
  - P1-3: SSM uses AWS-managed key, not platform CMK (ACDL_KMS_KEY_ID not set)
  - P1-4: WAF custom rules emit invalid HCL (attribute vs block syntax)
  - P1-5: WAF default_action input silently ignored (always emits allow {})
  - P1-6: consumer_invoke_policy.json has placeholder account ID (needs substitution)
  - P1-7: L2 composition outputs section not implemented in resolver
  - P1-8: terraform/spike/*.tf overwritten by run_platform.sh (state contamination)
  - P1-9: GitHub API URLs hardcoded (Gitea deployments silently fail)

P2 nits fixed (2 of 8):
  - P2-2: tagging-standard.json description referenced .yaml instead of .py
  - P2-3: unused graph_resource_name_utils import removed

Tests: 275 passed (was 272; +3 caller identity validation tests).
2026-07-22 21:09:52 +00:00
Jon Chery 4bd07a4fae feat(P27): validated per-module examples (D-058) + schema glob fix
Add modules/<name>/examples/ directories with simple.yaml + complex.yaml
(+ mysql.yaml for RDS) for every primitive and module pattern. All 25
example contracts validate against schemas/contract.schema.json. Update
the contract schema to allow object/array input values (for env vars).
Fix the platform-test schema-validation glob to modules/*/*/examples/*.yaml
to match the nested l1/l2 path structure. Update the microservice sample
contract note (env objects now permitted by the schema).

---ci---
project: acdl
phase: 27
milestone: v1.7
status: execute
---/ci---
2026-07-22 20:22:45 +00:00
Jon Chery 1fd37a2843 feat(P23): tagging standard + Wiz adapter + Kyverno adapter
Phase 23 (v1.7) — tagging standards and security adapters.

* schemas/tagging-standard.json (D-054): canonical required-tags schema
  (acdl:owner, acdl:contract, acdl:environment, acdl:cost-center).
* adapters/terraform/policy/custom_rules/acdl_tagging.py: Checkov custom
  rule (ACDL_TAG_NAMING) loaded via --external-checks-dir; closes D-043
  (synthetic SKIPPED record replaced by real PASS/FAIL records).
* checkov_adapter.py: removed _emit_tag_naming_skipped(), added
  ACDL_TAG_NAMING to RULE_MAP, updated docstring.
* scripts/run_platform.sh: both Checkov invocations pass
  --external-checks-dir adapters/terraform/policy/custom_rules/.
* adapters/wiz/ (D-052): Wiz adapter translating issue records to
  PolicyCheckResult (engine: "wiz"); graceful degradation emits
  WIZ_NOT_CONFIGURED SKIPPED when unconfigured; is_configured() gate.
* adapters/kyverno/ (D-053): Kyverno adapter translating PolicyReport
  results to PolicyCheckResult (engine: "kyverno"); ready but inactive
  for Terraform-only stacks; 3 sample ClusterPolicies in policies/.
* schemas/policy_check_result.schema.json: engine enum += "wiz".
* tests: fixtures + test_wiz_adapter.py (8 tests) + test_kyverno_adapter.py
  (13 tests); updated test_checkov_adapter.py to not expect the removed
  synthetic ACDL_TAG_NAMING SKIPPED record.
* scripts/run_ci.sh: lint stage compiles the new adapter modules.

202 tests pass; CI pipeline OK (lint + test + check-only).

Deviations:
- Wiz adapt() had an AttributeError on bare-list top-level input
  (data.get() on a list); fixed to dispatch on isinstance(data, list)
  before calling .get(). No spec change — bare-list handling is implied
  by the original docstring's "data if isinstance(data, list)" branch.
- Kyverno _to_pcr({}) defaults result to "skipped" (entry.get("result",
  "skip") -> "skip"), not "error"; test expectation corrected. Added an
  explicit unknown-result-string test to cover the "error" fallback.

---ci---
project: acdl
phase: 23
milestone: v1.7
status: execute
---/ci---
2026-07-22 20:00:46 +00:00
Jon Chery f68f85c9fd review(v1.5): READY TO SHIP — multi-persona code review
acdl-ci / Lint (push) Successful in 7s
acdl-ci / Test (push) Successful in 15s
acdl-ci / Platform check-only (offline) (push) Successful in 9s
---ci---
project: acdl
phase: 20
milestone: v1.5
status: review
verdict: READY TO SHIP
p0: 1 (fixed — contract path resolution in deploy workflow)
p1: 6 (flagged post-hoc)
---/ci---

Multi-persona review of v1.5 phase 20 (docs + reusable deploy workflow).

P0 (blocking) — AUTO-FIXED:
- C1: scripts/run_platform.sh contract path resolution broken in deploy
  workflow. The reusable workflow invokes run_platform.sh from the consumer
  workspace root with a relative contract path (.acdl/contract.yaml), but
  run_platform.sh does `cd "$ROOT"` (platform repo) early, so the relative
  path resolved against the platform repo and the pipeline could never run.
  Fix (commit 75c2274): capture CALLER_CWD before cd "$ROOT"; resolve
  caller-supplied relative paths against CALLER_CWD; default no-arg contract
  stays relative to ROOT (preserves platform-local CI). Reproduced pre-fix;
  verified post-fix.

P1 (important) — FLAGGED FOR POST-HOC REVIEW (do not block ship):
- C2: ref: v1.4 in the deploy workflow platform checkout — no v1.4 tag exists
  (only v1.4.0 / v1.4.1). Operator must create a floating v1.4 tag or change
  the ref to v1.4.1.
- C3: modules/l2/{static-asset,microservice}/README.md still use @v1 in their
  Usage examples; missed by the v1.4 bump.
- S1: static-key override is not wired. ACDL_AWS_* env vars on the OIDC step
  are not read by aws-actions/configure-aws-credentials@v4 (it reads AWS_*
  or its own access-key/secret-key inputs). The README/CONSUMER_GUIDE claim
  a working override that doesn't function as written. Needs a conditional
  step or renamed env vars + input wiring.
- S2: README overstates ABAC repo:org/repo:ref:... scoping. The workflow
  constructs a numeric role name (github.repository_id); the actual claim
  enforcement lives in the IAM trust policy, not in this workflow.
- T1: no deploy-workflow triggers conformance test (CI workflow has one;
  deploy doesn't). Minor — reusable workflows use workflow_call, not push
  triggers, but the contract's triggers field is then unenforced.
- A1: terraform/spike/terraform.tf uploaded as artifact leaks the AWS account
  ID via the state-backend bucket name. Recommend excluding terraform.tf or
  gating artifact upload to non-public repos.

P2 (nits) — listed for awareness: floating-tag terminology imprecision (M1),
  header comment "Gitea Actions" in the GitHub copy (M2, intentional byte-
  identical), pip install split (P1-perf), comment drift in pipelines/deploy.yaml
  header (C4), module README internal inconsistency (C5).

Verdict: READY TO SHIP. The one P0 is fixed. The 6 P1s are post-hoc items —
the deploy workflow is a scaffold whose first real consumer run requires
operator setup (tag, IAM role, secrets) that gates go-live. The P1s should
be addressed before any consumer invokes uses: acdl/.gitea/workflows/
deploy.yml@v1.4 in earnest.

Tests: 154 pass (19 new). run_ci.sh green.
2026-07-22 17:24:28 +00:00
Jon Chery 895a2f3806 docs(P20): specify phase 20 — consumer happy path + reusable deploy workflow (v1.5)
---ci---
project: acdl
phase: 20
milestone: v1.5
status: specify
---/ci---

Add v1.5 milestone to ROADMAP.md + REQUIREMENTS.md. Phase 20 covers
REQ-46 (README consumer model + mermaid + L3B/spike scrub), REQ-47
(generic CONSUMER_GUIDE.md + versioned uses: + consumer-scoped prereqs
+ run-time platform fetch), REQ-48 (zero-trust OIDC/ABAC credentials +
static-key override + daily rotation), REQ-49 (reusable byte-identical
deploy.yml Gitea+GitHub implementing pipelines/deploy.yaml), REQ-50
(contracts/static-asset.yaml @v1.4), REQ-51 (deploy-workflow conformance
tests). Update config.json milestone to v1.5.
2026-07-22 17:09:23 +00:00
Jon Chery e050e65158 feat(P19): central pipeline contract + shell reproducibility + output streaming (v1.4.1)
acdl-ci / Lint (push) Successful in 8s
acdl-ci / Test (push) Successful in 14s
acdl-ci / Platform check-only (offline) (push) Successful in 9s
---ci---
project: acdl
phase: 19
milestone: v1.4
status: execute
---

Add declarative pipeline contract (schemas/pipeline.schema.json +
pipelines/ci.yaml) as single source of truth for both Gitea Actions (dev)
and GitHub Actions (production) workflows. Both workflow files are
byte-identical and validated against the contract by 32 new tests.

Add scripts/run_ci.sh for shell reproducibility — mirrors the CI pipeline
locally (lint → test → check-only), exits 0 with 'CI PIPELINE OK'.

Update scripts/run_platform.sh to stream output by default: terraform
init/validate/plan via tee, Checkov compliance results with per-record
severity/rule/pass-fail, and emitted Terraform in --check-only. New
--quiet flag for log-only mode.

Requirements: REQ-43 (central pipeline contract), REQ-44 (shell
reproducibility), REQ-45 (output streaming). 122 tests pass (90 + 32).
2026-07-22 15:10:54 +00:00
Jon Chery 3508671377 refactor(modules): remove thin-composition layer; rewrite all module READMEs
The L2 thin-composition layer (composition.json + contract_resolver.py +
contract schema + sample contracts) has been removed completely. The
implementation was unsatisfactory and is deferred for a later redesign.

- Delete: composition.json x2, contract_resolver.py, contracts/ x2,
  contract.schema.json
- Patch: run_platform.sh now loads a pre-existing IR instance instead of
  resolving a contract (the downstream adapter/checkov/confidence/outbox
  pipeline is unchanged)
- Prune: L2 entries removed from registry.json (L1 entries unchanged)
- Rewrite: all 7 L1 module READMEs in plain language (no jargon), each
  with Resources/Inputs/Outputs/Usage/Compliance-extension-points/Versioning
  sections derived from interface.json
- Add: 2 L2 placeholder READMEs noting the composition is under redesign
- Add: modules-ir/README.md catalog index + README-TEMPLATE.md

---ci---
project: acdl
phase: 17
milestone: v1.3
status: execute
---/ci---
2026-07-22 13:54:40 +00:00
Jon Chery d103a37419 docs(P14): plan-as-execute + verify (v1.2.4)
---ci---
project: acdl
phase: 14
milestone: v1.2
status: verify
verdict: VERIFIED
requirements:
  covered: [REQ-32]
---/ci---

Phase 14 plan-as-execute + verify. scripts/verify_phase14.sh green.
l2-microservice composition (6 L1s, 2 wire kinds); contract schema
extended (inputs allow objects + healthcheck); resolver extended
(array-form wires, child->child refs, multi-resource L1 expansion);
adapter extended (ref: interpolation translation). v1.2 IR: 11 resources.
v1.1 S3 regression byte-identical. Ready to ship v1.2.4.
2026-07-21 21:12:17 +00:00
Jon Chery 6ed93f0311 phase: 7, status: plan-as-execute, persona: security-engineer, task: T-7.4..T-7.8
---ci---
project: acdl
phase: 7
milestone: v1.1
status: plan-as-execute
persona: security-engineer
task: [T-7.4, T-7.5, T-7.6, T-7.7, T-7.8]
requirements.covered: [REQ-18, REQ-20, REQ-21]
---/ci---

Wave 3 (security-engineer, 5 files sequential):

- T-7.4: schemas/policy_check_result.schema.json (REQ-18 schema half) —
  canonical shape from ARCHITECTURE.md §12.6; engine enum
  [checkov,kyverno,opa]; severity enum [critical,high,medium,low,info];
  result enum [pass,fail,skipped,error]. Validates as Draft 2020-12;
  valid instance validates.

- T-7.5: adapters/terraform/policy/checkov_adapter.py (REQ-18 adapter
  half) — Checkov JSON -> PolicyCheckResult; RULE_MAP has all 11 Checkov
  rule IDs (CKV_AWS_41/45/46/20/57/24/25/1/40/7/33) mapped to the 4 L2
  checks + tag/naming; emits ACDL_TAG_NAMING SKIPPED per D-043; stdlib
  only; tolerates both Checkov JSON shapes. Synthetic fixture produces 3
  records all valid against the schema.

- T-7.6: platform/audit_ledger_design.md (REQ-20) — three tiers (S3
  Object Lock compliance 7yr, acdl-evidence hot index, DynamoDB outbox
  RPO=0); spike scope (D-041) = hash chain + outbox write; v1.2 build-out
  = Object Lock + JWS (KMS key, quarterly rotation) + async worker + DLQ
  + daily checkpoints. Outbox item shape, RPO/RTO table, decision trail.

- T-7.7: platform/hitl_matrix_design.md (REQ-21 design half) —
  pre-execution gate model; Gitea-specific mechanics (workflow_dispatch +
  gitea.actor per D-042, no Environments API); full 8-concern matrix
  verbatim from §10.4; timeout 1d warn / 2d freeze; rejection -> HELD +
  supersedes; CODEOWNERS routing; SoD pointer to the .py.

- T-7.8: platform/separation_of_duties.py (REQ-21 impl half) —
  check(outbox_client, contract_id, current_prod_approver) -> (ok,
  reason); None outbox -> no-op; equal -> SEPARATION_OF_DUTIES_VIOLATION;
  distinct -> ok; route_halt_artifact stub; stdlib only (duck-typed
  outbox_client). All 5 SoD cases verified.
2026-07-21 18:45:28 +00:00
Jon Chery f8e99ed906 phase: 7, status: plan-as-execute, persona: platform-engineer+backend-engineer, task: T-7.2+T-7.3
---ci---
project: acdl
phase: 7
milestone: v1.1
status: plan-as-execute
persona: platform-engineer+backend-engineer
task: [T-7.2, T-7.3]
requirements.covered: [REQ-17, REQ-22]
---/ci---

Wave 2 (parallel): two independent JSON Schemas, different owners.

- T-7.2 (platform-engineer): schemas/ir.schema.json — Target Stack IR
  (JSON Schema draft 2020-12). Resources with typed inputs/outputs/NFRs,
  relationships (single parent per child), composition tree max-depth-5,
  policy hooks. Substrate-agnostic (no Terraform block keywords, no aws_
  provider prefixes; type values are IR types like aws:s3:bucket). module
  pins L1 by name@semver (W3.D). shared_keyword reserved for v2. Validates
  as Draft 2020-12; minimal l2-static-asset IR instance validates.

- T-7.3 (backend-engineer): schemas/contract.schema.json — consumer
  contract (JSON Schema draft 2020-12). Per-env mandatory (W3.E): dev
  stack+environment; qa adds validation.e2eSuite+loadTest; prod adds
  runbook+dashboard+oncall; dr adds drDrillRef. inputs always optional.
  profile: agentic marker; naturalLanguageIntent required when agentic
  (fixed: if-condition requires profile to be present before checking
  const). environment enum has no staging. Validates as Draft 2020-12;
  spike dev contract validates; qa/prod/dr/agentic negative cases reject.
2026-07-21 18:43:33 +00:00
Jon Chery e044a2de0d phase: 6, status: plan-as-execute, persona: lead-developer, task: T-6.1..T-6.4
---ci---
project: acdl
phase: 6
milestone: v1.1
status: plan-as-execute
persona: lead-developer
tasks: [T-6.1, T-6.2, T-6.3, T-6.4]
---/ci---

Archive the v1.0 demo under demo/ (D-037) and reorient the repo to the
real platform. Wave 1 of the Phase 06 plan.

- T-6.1: git mv modules/, scripts/, evidence-ui/, contracts/,
  contracts-repo/, .gitea/ -> demo/; mv ACDL_DEMO.md + runner-data/ -> demo/
- T-6.2: scaffold new v1.1 top-level dirs (platform/, schemas/, adapters/,
  terraform/, modules-ir/) with .gitkeep
- T-6.3: create top-level scripts/verify_phase06.sh (v1.1 verify scripts
  live at top-level, NOT demo/scripts/ which holds the v1.0 demo verify
  scripts)
- T-6.4: rewrite README.md to reflect the real platform (vision +
  architecture links, new layout, status v1.1 active); add runner-data/
  to .gitignore

All moves via git mv (history preserved). Repo root now contains only
README.md, demo/, docs/, .ciagent/, and the new empty v1.1 dirs.
2026-07-21 18:27:21 +00:00