docs(P21): specify phase 21 — consumer-facing docs restructure (v1.6)
---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.
This commit is contained in:
Jon Chery
@@ -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 `<br/>`, 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) |
|
||||
| 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 |
|
||||
+31
-1
@@ -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.
|
||||
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.
|
||||
@@ -4,7 +4,7 @@
|
||||
{
|
||||
"slug": "acdl",
|
||||
"name": "Agentic Cloud Delivery Platform",
|
||||
"milestone": "v1.5",
|
||||
"milestone": "v1.6",
|
||||
"status": "active"
|
||||
}
|
||||
],
|
||||
|
||||
Reference in New Issue
Block a user