continuous-intelligence/acdl
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 128 Wiki Activity

docs(P02): create 2-wave phase plan (REQ-02/03)

Browse Source 
---ci---
phase: 2
milestone: v1.0
status: plan
plan:
  waves: 2
  wave_1_infra_stub: [T-2.1..T-2.8 create 8 L1 modules]
  wave_2_coordination: [T-2.9 verify_phase02.sh, T-2.10 traceability]
  requirements_covered: [REQ-02, REQ-03]
  must_haves: 6
  verification:
    typecheck: bash -n + yaml load all 8 manifests
    test: scripts/verify_phase02.sh
    build: no-op
---/ci---

PLAN.md replaced with Phase 02 plan. Wave 1 (infra-stub-engineer) creates
the 8 L1 modules (one commit per L1). Wave 2 (lead-developer) adds the
verify script + traceability. backend/data/frontend personas have 0 tasks.
This commit is contained in:
Jon Chery
2026-07-21 13:13:39 +00:00
parent 59c330f012
commit ff5a82feed
1 changed files with 52 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.ciagent/PLAN.md
+52 -63
View File
@@ -1,96 +1,85 @@
---
phase: 01
name: repo-scaffolding
phase: 02
name: l1-modules
milestone: v1.0
milestone_type: feature
status: planned
requirements: [REQ-01, REQ-09, REQ-10]
requirements: [REQ-02, REQ-03]
must_haves:
- "Repo acdl-contracts exists under continuous-intelligence and is pushable (HTTP 200 on GET /repos/continuous-intelligence/acdl-contracts)"
- "Repo acdl-evidence exists under continuous-intelligence and is pushable (HTTP 200 on GET /repos/continuous-intelligence/acdl-evidence)"
- "Raw URL https://git.cloudinit.dev/continuous-intelligence/acdl-evidence/raw/branch/main/index.html returns HTTP 200 with placeholder HTML (D-012/D-016 substitute for Pages check)"
- "Branches qa and prod exist on acdl-contracts (visible stand-in for unsupported Gitea environments; D-013)"
- "scripts/gitea_setup.sh is idempotent and exits 0 (re-running against existing repos is a no-op)"
- "scripts/verify_phase01.sh passes: enumerates repos, fetches the raw index.html, lists qa/prod branches, exits 0"
- "All 8 L1 module folders exist under modules/l1/ with the exact names from REQ-02"
- "Each L1 has a manifest.yaml matching the schema in ARCHITECTURE.md (name, kind: l1, description, inputs: map of string keys)"
- "Each L1 has a mock_apply.sh that echoes '[L1: <name>] applying...', sleeps 1s, echoes '[L1: <name>] OK', exits 0 (D-007)"
- "All mock_apply.sh are executable (chmod +x) and bash -n clean"
- "All manifest.yaml files parse as valid YAML"
- "scripts/verify_phase02.sh passes: enumerates 8 L1s, validates each manifest, runs each mock_apply.sh, confirms exit 0 + expected output"
verification:
typecheck: "bash -n scripts/*.sh"
test: "scripts/verify_phase01.sh"
typecheck: "bash -n modules/l1/*/mock_apply.sh scripts/*.sh && python3 -c 'import yaml; [yaml.safe_load(open(f)) for f in glob.glob(\"modules/l1/*/manifest.yaml\")]'"
test: "scripts/verify_phase02.sh"
build: no-op
---
# Phase 01 — repo-scaffolding PLAN
# Phase 02 — l1-modules PLAN
## Goal
Stand up the three-repo scaffold under the `continuous-intelligence` Gitea org
and the Phase 01 visible artifacts in the local `acdl` checkout: the
Gitea-setup script, the workflow skeletons, and the Phase 01 verification
script. After this phase, Phases 02-05 can push stub modules, core scripts,
and workflows into the right repos.
Create the 8 L1 stub modules under `modules/l1/`. Each module has a
`manifest.yaml` (declared inputs, flat string map per D-017) and a uniform
`mock_apply.sh` (echo + 1s sleep + exit 0 per D-007/D-018). After this phase,
Phase 03 can compose L1s into L2 modules and `mock_executor.sh` can iterate
over an L2's L1 references.
## Requirements covered
- REQ-01: All demo code lives under `continuous-intelligence` Gitea org
- REQ-09: Three repos exist (`acdl`, `acdl-contracts`, `acdl-evidence`)
- REQ-10: reusable pipeline runs Dev → QA (approval) → Prod (approval) → Finalize; Phase 01 builds the skeleton (gates wired in Phase 04)
- REQ-02: 8 L1 module folders exist (exact names)
- REQ-03: each L1 has manifest.yaml + mock_apply.sh with the uniform behavior
## Waves (vertical slices, executed in domain priority order)
## Waves (vertical slices)
### Wave 1 — coordination (lead-developer)
### Wave 1 — infra-stub-engineer (creates the 8 L1s)
**Tasks:**
- **T-1.1** Add `.gitignore` (ignore `audit.json` artifacts, `__pycache__/`, `*.pyc`, `state.json`, `.env`). Create repo directory layout markers: `scripts/.gitkeep`, `modules/l1/.gitkeep`, `modules/l2/.gitkeep`, `.gitea/workflows/.gitkeep`. Add a top-level `README.md` with the project name, the 4-act demo summary, and a pointer to `.ciagent/PROJECT.md`.
- **T-1.2** Add `scripts/verify_phase01.sh` — the Phase 01 verification script. It reads `$ACDL_GITEA_TOKEN` from the env, calls the Gitea API to confirm both new repos exist, curls the raw `index.html` URL, lists branches on `acdl-contracts` looking for `qa` and `prod`, and prints a PASS/FAIL summary. Exits 0 on success, non-zero on any failure. Idempotent.
- **T-2.1** Create `modules/l1/l1-eks-fargate/{manifest.yaml, mock_apply.sh}`
- **T-2.2** Create `modules/l1/l1-iam-role/{manifest.yaml, mock_apply.sh}`
- **T-2.3** Create `modules/l1/l1-lambda/{manifest.yaml, mock_apply.sh}`
- **T-2.4** Create `modules/l1/l1-api-gateway/{manifest.yaml, mock_apply.sh}`
- **T-2.5** Create `modules/l1/l1-eventbridge/{manifest.yaml, mock_apply.sh}`
- **T-2.6** Create `modules/l1/l1-sqs/{manifest.yaml, mock_apply.sh}`
- **T-2.7** Create `modules/l1/l1-s3/{manifest.yaml, mock_apply.sh}`
- **T-2.8** Create `modules/l1/l1-cloudwatch/{manifest.yaml, mock_apply.sh}`
**Files owned (territory):**
- `.gitignore`, `README.md`
- `scripts/.gitkeep`, `modules/l1/.gitkeep`, `modules/l2/.gitkeep`, `.gitea/workflows/.gitkeep`
- `scripts/verify_phase01.sh`
Each L1's `manifest.yaml` declares 1-3 plausible inputs for that primitive
(e.g., `l1-s3` declares `bucket_name`, `region`, `retention_days`; `l1-iam-role`
declares `role_name`, `trust_policy`). Each `mock_apply.sh` follows the exact
uniform template from ARCHITECTURE.md.
**Commits:** one per task, `---ci---` block has `phase: 1, status: plan-as-execute, persona: lead-developer, task: T-1.x, requirements.covered: [REQ-01]`.
**Files owned (territory):** `modules/l1/**`
### Wave 2 — backend (backend-engineer)
**Commits:** one per task, `---ci---` block has `phase: 2, status: plan-as-execute, persona: infra-stub-engineer, task: T-2.x, requirements.covered: [REQ-02, REQ-03]`.
### Wave 2 — lead-developer (verification script + traceability)
**Tasks:**
- **T-2.1** Add `scripts/gitea_setup.sh`. Idempotent. Reads `$ACDL_GITEA_TOKEN` and `$GITEA_HOST` (default `https://git.cloudinit.dev`). Creates `acdl-contracts` and `acdl-evidence` under `continuous-intelligence` if missing (POST `/orgs/continuous-intelligence/repos` with `auto_init: true`, `default_branch: "main"`, `private: true`). Pushes a placeholder `index.html` to `acdl-evidence` main via the Gitea file-contents API (POST `/repos/{owner}/{repo}/contents/{path}` with base64 content + "Initial placeholder" commit message). Creates `qa` and `prod` branches on `acdl-contracts` from `main` via the Gitea branch API (POST `/repos/{owner}/{repo}/branches`). All HTTP errors are logged with status + body; the script is idempotent (409 / "already exists" treated as success). Uses `curl` + `python3 -c` for base64 encoding; no jq dependency.
- **T-2.2** Add `acdl/.gitea/workflows/pipeline.yml` skeleton. `on: workflow_call`. Four jobs: `dev` (runs-on ubuntu-latest, placeholder "Dev stage" step), `qa-gate` (needs dev, runs-on ubuntu-latest, placeholder "Awaiting QA approval" step; in Phase 04 this becomes a `workflow_dispatch` approval input per D-013), `prod-gate` (needs qa-gate, placeholder "Awaiting Prod approval"), `finalize` (needs prod-gate, placeholder "Commit audit.json to acdl-evidence"). All steps are explicit placeholders marked `# Phase 04 will implement`. Comment at top documents the branch-pin rule (`@milestone/v1.0-initial`).
- **T-2.3** Add `acdl-contracts/.gitea/workflows/issue-to-contract.yml` skeleton (committed to the `acdl` repo under `contracts-repo/.gitea/workflows/` as a reference copy; pushed to the actual `acdl-contracts` repo in Phase 04). `on: issues` with `types: [opened]`. One job `parse-and-trigger` with placeholder steps for: checkout, run `l3b_agent_stub.py`, commit `contract.yaml`, push, trigger the `acdl` pipeline via `workflow_dispatch` API (D-014). Marked `# Phase 04 will implement`.
- **T-2.9** Create `scripts/verify_phase02.sh`. It:
1. Enumerates `modules/l1/*/` and confirms exactly 8 folders with the 8 expected names.
2. For each L1: confirms `manifest.yaml` exists and parses as YAML with `name` matching the folder, `kind: l1`, and an `inputs:` map.
3. For each L1: confirms `mock_apply.sh` is executable, `bash -n` clean, runs in <2s, exits 0, and its stdout contains the `[L1: <name>] applying...` and `[L1: <name>] OK` markers.
4. Prints a PASS/FAIL summary; exits 0 on full success.
- **T-2.10** Update `.ciagent/REQUIREMENTS.md` (REQ-02/03 → covered pending VERIFY) and `.ciagent/ROADMAP.md` (Phase 02 → executing). No README change.
**Files owned (territory):**
- `scripts/gitea_setup.sh`
- `.gitea/workflows/pipeline.yml`
- `contracts-repo/.gitea/workflows/issue-to-contract.yml` (reference copy in the `acdl` repo; source of truth for Phase 04)
**Files owned (territory):** `scripts/verify_phase02.sh`, `.ciagent/REQUIREMENTS.md`, `.ciagent/ROADMAP.md`
**Commits:** one per task, `---ci---` block has `persona: backend-engineer, task: T-2.x, requirements.covered: [REQ-01 or REQ-09 or REQ-10]`.
**Commits:** one per task, `---ci---` block has `phase: 2, status: plan-as-execute, persona: lead-developer, task: T-2.9/2.10`.
### Wave 3 — coordination (lead-developer, verification wiring)
## Wave ordering
**Tasks:**
- Wave 1 (infra-stub-engineer) creates all 8 L1s. A single subagent gets all 8 tasks; it commits per task.
- Wave 2 (lead-developer) adds the verify script and traceability after the L1s exist.
- **T-3.1** Run `scripts/gitea_setup.sh` against the live Gitea (executed as part of EXECUTE; recorded as a commit only if it modifies repo state — it does not, so no commit. Instead, the verify run in Wave 3 confirms the artifacts exist via the API.) Add `scripts/verify_phase01.sh` invocation note to README.md ("Run `scripts/verify_phase01.sh` after `scripts/gitea_setup.sh` to confirm Phase 01 success criteria"). Update `.ciagent/REQUIREMENTS.md` Traceability table to mark REQ-01/09/10 as `covered` (pending VERIFY confirmation). Update `.ciagent/ROADMAP.md` Phase 01 status to `executing` (will flip to `complete` on SHIP).
`backend-engineer`, `data-engineer`, `frontend-engineer` have 0 tasks this phase.
**Files owned (territory):**
- `README.md` (update)
- `.ciagent/REQUIREMENTS.md` (traceability update only)
- `.ciagent/ROADMAP.md` (phase status update only)
## Dependencies
**Commits:** one for T-3.1 (a `chore(P01)` update with `phase: 1, status: execute, persona: lead-developer, task: T-3.1`).
## Wave ordering rationale
- Wave 1 (coordination) creates the directory skeleton + verification script so Wave 2's scripts have a place to live and a check to satisfy.
- Wave 2 (backend) builds the Gitea setup script and workflow skeletons.
- Wave 3 (coordination) wires the verification script into README and updates traceability after Wave 2's scripts exist.
- infra-stub-engineer and frontend-engineer have 0 tasks this phase (per PERSONAS.md), so their persona groups are skipped.
## Dependencies on other phases
None. Phase 01 is self-contained. Phases 02-05 depend on Phase 01 having created the two new repos and the workflow skeletons.
## Risk notes
- If `gitea_setup.sh` hits a 401/403, treat as an escalation (token scope insufficient). Per run.md Step 4: retry once, then escalate. Do NOT proceed to SHIP with uncreated repos.
- The Gitea file-contents API requires the file to NOT already exist on first POST. The script must check existence first (GET) and skip POST if 200. Otherwise 422.
- Creating branches requires the default branch to exist first (`auto_init: true` handles this).
- Depends on Phase 01 (the `modules/l1/.gitkeep` from T-1.1 is replaced by real folders).
- Phase 03 depends on this phase for L1 references in L2 compositions.