.ciagent/PLAN.md

@@ -0,0 +1,96 @@
+---
+phase: 01
+name: repo-scaffolding
+milestone: v1.0
+milestone_type: feature
+status: planned
+requirements: [REQ-01, REQ-09, REQ-10]
+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"
+verification:
+  typecheck: "bash -n scripts/*.sh"
+  test: "scripts/verify_phase01.sh"
+  build: no-op
+---
+
+# Phase 01 — repo-scaffolding 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.
+
+## 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)
+
+## Waves (vertical slices, executed in domain priority order)
+
+### Wave 1 — coordination (lead-developer)
+
+**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.
+
+**Files owned (territory):**
+- `.gitignore`, `README.md`
+- `scripts/.gitkeep`, `modules/l1/.gitkeep`, `modules/l2/.gitkeep`, `.gitea/workflows/.gitkeep`
+- `scripts/verify_phase01.sh`
+
+**Commits:** one per task, `---ci---` block has `phase: 1, status: plan-as-execute, persona: lead-developer, task: T-1.x, requirements.covered: [REQ-01]`.
+
+### Wave 2 — backend (backend-engineer)
+
+**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`.
+
+**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)
+
+**Commits:** one per task, `---ci---` block has `persona: backend-engineer, task: T-2.x, requirements.covered: [REQ-01 or REQ-09 or REQ-10]`.
+
+### Wave 3 — coordination (lead-developer, verification wiring)
+
+**Tasks:**
+
+- **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).
+
+**Files owned (territory):**
+- `README.md` (update)
+- `.ciagent/REQUIREMENTS.md` (traceability update only)
+- `.ciagent/ROADMAP.md` (phase status update only)
+
+**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).