From c5745de37c8fd93f938871ba1d77f705d00f7668 Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Wed, 22 Jul 2026 18:17:28 +0000 Subject: [PATCH] =?UTF-8?q?docs(P21):=20specify=20phase=2021=20=E2=80=94?= =?UTF-8?q?=20consumer-facing=20docs=20restructure=20(v1.6)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ---ci--- project: acdl phase: 21 milestone: v1.6 status: specify ---/ci--- Add v1.6 milestone to ROADMAP.md + REQUIREMENTS.md. Phase 21 covers REQ-52 (scrub .ciagent/.gitea from consumer docs), REQ-53 (rename acdl_platform -> platform), REQ-54 (docs/ Jekyll Pages restructure), REQ-55 (L2->modules, L1->primitives, composition->pattern prose), REQ-56 (forge->platform runners), REQ-57 (README repository roles restated), REQ-58 (Features + Roadmap), REQ-59 (mermaid fix + security-checks + infrastructure-apply), REQ-60 (credentials minus go-gitea/waivers), REQ-61 (environments concept + onboarding scaffold). Update config.json milestone to v1.6. --- .ciagent/REQUIREMENTS.md | 41 ++++++++++++++++++++++++++++++++++++++-- .ciagent/ROADMAP.md | 32 ++++++++++++++++++++++++++++++- .ciagent/config.json | 2 +- 3 files changed, 71 insertions(+), 4 deletions(-) diff --git a/.ciagent/REQUIREMENTS.md b/.ciagent/REQUIREMENTS.md index b715b22..2332b0c 100644 --- a/.ciagent/REQUIREMENTS.md +++ b/.ciagent/REQUIREMENTS.md @@ -132,6 +132,28 @@ - **REQ-50:** `contracts/static-asset.yaml` uses a versioned `uses:` reference (`@v1.4`, MAJOR+MINOR) — not bare `@v1` or `@main` — as the canonical example the consumer guide points at. - **REQ-51:** `tests/test_pipeline_contract.py` is extended to validate the new deploy workflows: both files exist, are byte-identical, and conform to `schemas/deploy-pipeline.schema.json` (stages present, names match `pipelines/deploy.yaml` stage names). The existing CI-workflow conformance tests continue to pass unchanged. +## v1.6 (Active — consumer-facing docs restructure + terminology normalization + environments concept) + +### Category: Internal-surface scrub +- **REQ-52:** No consumer-facing documentation (README.md, docs/**, modules/**/README.md, contracts/**) references `.ciagent/` — it is local CIAgent metadata, never visible to platform engineers or consumers. The README repository-layout table has no `.ciagent/` row. No `.gitea/` references appear in consumer-facing docs (consumers use GitHub only); the README repository-layout table has no `.gitea/workflows/` row. +- **REQ-53:** `acdl_platform/` is renamed to `platform/` across the directory, all imports in tests/scripts/pipelines/workflows, and all doc references. `grep -R "acdl_platform" .` (excluding `.ciagent/`, `demo/`, `.git/`) returns 0 hits. The test suite passes after the rename. + +### Category: Docs site restructure +- **REQ-54:** `docs/` is restructured into a Jekyll-style GitHub Pages site: `docs/_config.yml`, `docs/index.md` (landing), `docs/modules/` (catalog + per-module Pages-friendly copies), `docs/contracts/index.md`, `docs/pipeline/index.md` + `docs/pipeline/versioning.md`, `docs/environments/index.md`, `docs/consumer-guide.md`, `docs/architecture.md` (consolidated from architecture.md + architecture-v1.0.md, current-architecture only), `docs/vision.md`. No `.ciagent/` links anywhere in `docs/`. Consumer-facing content (modules, contracts, pipeline, versioning) lives in Pages. + +### Category: Terminology normalization +- **REQ-55:** Consumer-facing docs drop the "L2" nomenclature — L2 modules are referred to as "modules". "L1" label is dropped in consumer-facing docs — L1 primitives are referred to as "primitives". The "composition" terminology is changed to "pattern" for modules in prose (the on-disk `composition.json` files and code references are unchanged this phase). A roadmap entry records that "composition" will later describe the thin orchestration where consumers dynamically create a module directly from the contract file (future implementation, not implemented now). +- **REQ-56:** The term "forge" is replaced in consumer-facing docs with "platform runners" / "platform-managed" as appropriate. The term "forge" remains only in internal architecture docs. + +### Category: README rewrite +- **REQ-57:** README.md repository-roles section is restated to match reality: a consumer repo contains (a) its application code, (b) one or more contracts (`.acdl/contract.yaml`), and (c) one or more CI definitions (a thin `.github/workflows/deploy.yml` that `uses:` the central reusable workflow, pointing at the appropriate environment + contract). The platform repo (this one) owns modules/adapters/schemas/pipelines/scripts/workflows. A consumer never clones the platform repo. +- **REQ-58:** README.md Status section is replaced with a Features list (referenceable by consumers and platform engineers) and a Roadmap subsection listing only planned future features (no internal CIAgent status, no version-by-version changelog). +- **REQ-59:** README.md "How the platform works" mermaid diagram is revised so all node text is visible (no overflow): labels are split with `
`, boxes widened as needed. A security-checks stage is added before the policy-checks stage. Specific tools (Checkov, Terraform) are not named — they are "security checks (adapter)", "policy checks (adapter)", "infrastructure plan". An "infrastructure apply" stage is added at the appropriate level (dev only, after confidence). +- **REQ-60:** README.md Credentials & zero-trust section removes the "go-gitea/gitea#36988 blocked" mention and the "waivers D-039/D-047" language (not consumer/platform-engineer facing). It states: default OIDC + ABAC; alternative is a static AWS key (GitHub Secrets for platform-runner runs, or `.env.secrets` locally) with the expectation of daily rotation (platform-managed for runner runs) or out-of-band rotation (consumer-managed for local `.env.secrets`). + +### Category: Environments concept + onboarding +- **REQ-61:** The concept of platform-managed environments is introduced: consumers are not required to provide an AWS account, VPC, subnet, S3 state bucket, or runner key. `docs/environments/index.md` documents that a named environment is a platform-owned AWS account + network + state backend + IAM role surfaced to the consumer via ABAC, selected by name in the contract. The old README environments table (dev/qa/prod/dr) is removed completely. A minimal onboarding scaffold exists: `platform/environments/` with a sample `dev.json` + README, `platform/environment_check.py`, a wire-in at the top of `scripts/run_platform.sh`, a friendly first-run onboarding message when no environment is defined for the repo, and `tests/test_environment_check.py` covering the missing-env and present-env cases. + ## Out of Scope (v1.2) | REQ | Original criterion | Clarified criterion (effective) | Decision | @@ -222,7 +244,7 @@ | REQ-44 | 19 | complete (v1.4.1) | | REQ-45 | 19 | complete (v1.4.1) | -### v1.5 (active — consumer happy path + zero-trust docs + reusable deploy workflow) +### v1.5 (prior — consumer happy path + zero-trust docs + reusable deploy workflow, complete) | Requirement | Phase | Status | |-------------|-------|--------| @@ -231,4 +253,19 @@ | REQ-48 | 20 | complete (v1.5.0) | | REQ-49 | 20 | complete (v1.5.0) | | REQ-50 | 20 | complete (v1.5.0) | -| REQ-51 | 20 | complete (v1.5.0) | \ No newline at end of file +| REQ-51 | 20 | complete (v1.5.0) | + +### v1.6 (active — consumer-facing docs restructure + terminology normalization + environments concept) + +| Requirement | Phase | Status | +|-------------|-------|--------| +| REQ-52 | 21 | pending | +| REQ-53 | 21 | pending | +| REQ-54 | 21 | pending | +| REQ-55 | 21 | pending | +| REQ-56 | 21 | pending | +| REQ-57 | 21 | pending | +| REQ-58 | 21 | pending | +| REQ-59 | 21 | pending | +| REQ-60 | 21 | pending | +| REQ-61 | 21 | pending | \ No newline at end of file diff --git a/.ciagent/ROADMAP.md b/.ciagent/ROADMAP.md index fe97170..041b54a 100644 --- a/.ciagent/ROADMAP.md +++ b/.ciagent/ROADMAP.md @@ -8,6 +8,7 @@ - **v1.3 (complete):** module documentation + thin-composition removal. The L2 composition layer is removed; module READMEs are built out. Tag `v1.3.2`. - **v1.4 (complete):** central pipeline contract + shell reproducibility + output streaming. A declarative pipeline contract (`schemas/pipeline.schema.json` + `pipelines/ci.yaml`) binds the Gitea and GitHub workflows to a single source of truth. `scripts/run_ci.sh` mirrors the CI pipeline locally. `scripts/run_platform.sh` streams terraform/checkov output by default. - **v1.5 (complete, tag `v1.5.0`):** consumer happy path + zero-trust docs + reusable deploy workflow. README rewritten so the consumer model is unambiguous (consumer owns only contract + app code; the rest is the platform source). Platform-flow + consumer-guide diagrams converted to mermaid. Legacy surface + implementation nomenclature removed from docs. Credentials section rewritten for zero-trust OIDC + ABAC (with a static-key override + daily rotation). A generic `docs/CONSUMER_GUIDE.md` (all L2 modules, versioned `uses:`, consumer-scoped prereqs, run-time platform fetch) replaces the module-specific guide. A byte-identical reusable `deploy.yml` workflow (Gitea + GitHub) implements `pipelines/deploy.yaml` and is invoked by consumer repos via a versioned tag. +- **v1.6 (active):** consumer-facing docs restructure + terminology normalization + environments concept. `docs/` becomes a Jekyll-style GitHub Pages site. `acdl_platform/` is renamed to `platform/`. L2 → "modules", L1 → "primitives", "composition" → "pattern" in prose. README restructured: Features + Roadmap (no internal status), repository roles restated (consumer = app code + contracts + CI definitions), mermaid fixed (visible text, security-checks + infrastructure-apply stages, no tool names), credentials section minus go-gitea/waivers. Platform-managed environments concept + a minimal onboarding scaffold. `.ciagent/` + `.gitea/` references removed from all consumer-facing docs. - **v1.0 demo URL:** https://git.cloudinit.dev/continuous-intelligence/acdl-evidence/raw/branch/main/index.html --- @@ -302,4 +303,33 @@ locally. - `contracts/static-asset.yaml` uses `uses: acdl/pipelines/deploy.yaml@v1.4`. - `tests/test_pipeline_contract.py` validates the deploy workflows (exist, byte-identical, schema-conformant); the extended test suite passes; `bash scripts/run_ci.sh` exits 0. -After Phase 20: COMPLETE gate — review → ship `v1.5.0` → audit. \ No newline at end of file +After Phase 20: COMPLETE gate — review → ship `v1.5.0` → audit. + +--- + +## v1.6 (Active — consumer-facing docs restructure + terminology normalization + environments concept) + +The v1.6 milestone restructures the consumer-facing documentation into a real +GitHub Pages site, normalizes the terminology (L2 → "modules", L1 → +"primitives", "composition" → "pattern", "forge" → "platform runners"), renames +`acdl_platform/` to `platform/`, rewrites the README (Features + Roadmap, +restated repository roles, fixed mermaid, cleaned credentials section), removes +all `.ciagent/` + `.gitea/` references from consumer surfaces, and introduces +the concept of platform-managed environments with a minimal first-run onboarding +scaffold. + +### Phase 21 — docs-restructure-and-terminology-normalization +- **Description:** Rename `acdl_platform/` → `platform/` (directory + all code/test/script/pipeline/workflow references; tests green). Restructure `docs/` into a Jekyll-style GitHub Pages site (`_config.yml`, `index.md`, `modules/`, `contracts/`, `pipeline/`, `environments/`, `consumer-guide.md`, consolidated `architecture.md`, `vision.md`). Rewrite `README.md`: remove `.ciagent/` + `.gitea/workflows/` rows; restate consumer repo model (app code + 1+ contracts + CI definitions `uses:`-ing the central workflow); replace Status with Features + Roadmap (planned only); fix the mermaid (visible text, add security-checks stage before policy, no tool names, add infrastructure-apply stage); remove the environments table; clean the credentials section (no go-gitea/waivers, keep daily/out-of-band rotation); forge → platform runners/platform-managed. Update `docs/consumer-guide.md`: drop L2 (→ modules), composition → pattern (prose), remove `.gitea/` (GitHub only), forge → platform runners, mermaid updated. Update `modules/` READMEs: L1 → primitives, L2 → modules, composition → pattern (prose only, files kept); bump stale `@v1` → `@v1.4`. Consolidate `docs/architecture.md` + `docs/architecture-v1.0.md` into a single current-architecture `docs/architecture.md`. Add `docs/environments/index.md` (platform-managed AWS account/network/state/runner; consumer provides none). Add a minimal onboarding scaffold: `platform/environments/` dir + sample `dev.json` + README, `platform/environment_check.py`, wire-in at the top of `scripts/run_platform.sh`, friendly onboarding message when no environment is defined, `tests/test_environment_check.py`. Add a roadmap entry: "composition" will later describe the thin orchestration where consumers dynamically create a module directly from the contract file (future implementation, not this phase). +- **Status:** active +- **Depends on:** [20] +- **Requirements:** REQ-52, REQ-53, REQ-54, REQ-55, REQ-56, REQ-57, REQ-58, REQ-59, REQ-60, REQ-61 +- **Success Criteria:** + - `grep -R "\.ciagent" docs/ README.md` returns 0 hits; `grep -R "\.gitea" docs/ README.md modules/ contracts/` returns 0 hits. + - `grep -R "acdl_platform" .` (excluding `.ciagent/`, `demo/`, `.git/`) returns 0 hits; the test suite passes after the rename. + - `docs/` has the Jekyll structure (`_config.yml`, `index.md`, `modules/`, `contracts/`, `pipeline/`, `environments/`); no `.ciagent/` links in `docs/`. + - Consumer-facing docs have no "L2"/"L1" labels (modules/primitives) and no "forge" term; "composition" → "pattern" in prose. + - README.md has Features + Roadmap (no version changelog); repository roles restated; mermaid visible + security-checks + infrastructure-apply stages + no tool names; no environments table; credentials section has no go-gitea/waivers. + - `docs/environments/index.md` exists; `platform/environments/` + `dev.json` + `environment_check.py` + `run_platform.sh` wire-in + `tests/test_environment_check.py` exist and pass. + - `bash scripts/run_ci.sh` exits 0; `python3 -m pytest tests/ -v` passes (154 + new environment-check tests). + +After Phase 21: COMPLETE gate — review → ship `v1.6.0` → audit. \ No newline at end of file diff --git a/.ciagent/config.json b/.ciagent/config.json index 70ca8ed..1c8d0dc 100644 --- a/.ciagent/config.json +++ b/.ciagent/config.json @@ -4,7 +4,7 @@ { "slug": "acdl", "name": "Agentic Cloud Delivery Platform", - "milestone": "v1.5", + "milestone": "v1.6", "status": "active" } ],