atheos-blog-lxc/aidlc-docs/plans/execution-plan.md

Execution Plan — atheos-blog-lxc

Stage: INCEPTION — Workflow Planning Date: 2026-09-29 Deploy Target: Proxmox LXC (Alpine 3.23) on node scotty (.69). No K3s flavour, no CI.

---

Detailed Analysis Summary

Change Impact Assessment

• User-facing changes: Yes — a new web UI (Atheos) becomes reachable on the LAN.
• Structural changes: Yes — one new Proxmox guest (VMID 136).
• Data model changes: No — Atheos is database-less; it stores config in files.
• API changes: No.
• NFR impact: Low — a small single-purpose guest; NFRs already captured in requirements.md.
• Existing systems touched: scotty gains a guest + a template download. armistace/blog is read (cloned) only — never pushed to by the agent.

Risk Assessment

• Risk Level: Medium — the steps are well understood, but Atheos-on-Alpine is under-documented (C-1) and the install has a browser-driven first-run step.
• Rollback Complexity: Easy — pct destroy 136 removes the guest; nothing else is mutated.
• Testing Complexity: Simple-to-Moderate — all acceptance criteria are observable (served page, file on disk, git remote, survives reboot).

Component Relationships

• Primary component: LXC 136 on scotty.
• Internal: nginx → php-fpm (unix socket) → Atheos PHP app → workspace/ filesystem.
• External (read-only): git.aridgwayweb.com/armistace/blog (public clone).
• Operator-owned: SSH key, git identity, Atheos login — the agent creates none of these.

---

Workflow Visualization

flowchart TD
    Start(["User Request"])
    subgraph INCEPTION["🔵 INCEPTION PHASE"]
        WD["Workspace Detection<br/><b>COMPLETED</b>"]
        RE["Reverse Engineering<br/><b>SKIPPED</b>"]
        RA["Requirements Analysis<br/><b>COMPLETED</b>"]
        US["User Stories<br/><b>SKIPPED</b>"]
        WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
        AD["Application Design<br/><b>EXECUTE</b>"]
        UG["Units Generation<br/><b>EXECUTE</b>"]
    end
    subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
        FD["Functional Design<br/><b>SKIP</b>"]
        NFRA["NFR Requirements<br/><b>SKIP</b>"]
        NFRD["NFR Design<br/><b>SKIP</b>"]
        ID["Infrastructure Design<br/><b>EXECUTE</b>"]
        CG["Code Generation<br/><b>EXECUTE</b>"]
        BT["Build and Test<br/><b>EXECUTE</b>"]
    end
    subgraph OPERATIONS["🟡 OPERATIONS PHASE"]
        OPS["Operations<br/><b>PLACEHOLDER</b>"]
    end
    Start --> WD --> RA --> WP --> AD --> UG --> ID --> CG --> BT --> End(["Complete"])
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style FD fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style NFRA fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style NFRD fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style UG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style ID fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style OPS fill:#FFF59D,stroke:#F9A825,stroke-width:2px,color:#000
linkStyle default stroke:#333,stroke-width:2px

(Plain-text equivalent for Matrix: WD ✅ → RA ✅ → WP ✅ → AD ▶ → UG ▶ → ID ▶ → CG ▶ → BT ▶ → Done. Skipped: RE, US, FD, NFRA, NFRD.)

---

Phases to Execute

🔵 INCEPTION PHASE

• Workspace Detection — COMPLETED
• Reverse Engineering — SKIP (greenfield repo; the estate recon was folded into Workspace Detection and recorded in aidlc-state.md → Existing Estate Facts)
• Requirements Analysis — COMPLETED
• User Stories — SKIP (user-confirmed; single operator, no app code. A requirement→unit map substitutes for unit-of-work-story-map.md, per the skipped-stories rule)
• Workflow Planning — COMPLETED
• Application Design — EXECUTE (minimal depth)
  • Rationale: there are distinct components with real interfaces (nginx ↔ php-fpm socket, Atheos ↔ workspace, git ↔ remote). Recording them at minimal depth gives the handoff a component map and drives unit boundaries. Minimal, not comprehensive — no app code exists to design.
• Units Generation — EXECUTE
  • Rationale: genuinely multi-unit work (guest, web stack, app, VCS, docs) with an ordering dependency.

🟢 CONSTRUCTION PHASE

• Functional Design — SKIP
  • Rationale: no business logic to design; the "functions" are package installs and config files already specified in requirements.md.
• NFR Requirements — SKIP
  • Rationale: all NFRs already captured (requirements.md §3); nothing new surfaces at construction.
• NFR Design — SKIP
  • Rationale: same — NFRs here are simple resource/reboot-survival constraints, not a design problem.
• Infrastructure Design — EXECUTE
  • Rationale: this is the real design work for an infra project — the guest spec, storage choice, template provenance, network mode, resource sizing, and the OpenRC service wiring. Getting this wrong is the main risk (C-1/C-2/C-3).
• Code Generation — EXECUTE (always)
  • Rationale: the provisioning script + the docs are the deliverables.
• Build and Test — EXECUTE (always)
  • Rationale: here "build and test" = apply against the live node and verify, plus the reboot-survival cycle (AC-6). Not a compiled artifact.

🟡 OPERATIONS PHASE

• Operations — PLACEHOLDER (future deployment/monitoring workflows)

---

Unit Plan (provisional — finalised in Units Generation)

Unit	Scope	Depends on	Primary ACs
U1	LXC creation: download Alpine 3.23 template on scotty, pct create 136 (20 GB root, 2 vCPU, 1 GB, onboot, unprivileged), base config, timezone, package index	—	AC-1
U2	Web stack: nginx + php83-fpm + php83-{session,zip,openssl,mbstring}, allow_url_fopen, php-fpm pool, nginx vhost	U1	AC-2
U3	Atheos install: fetch pinned upstream commit into the web root, correct ownership/permissions on config.php, data/, workspace/, plugins/, themes/	U2	AC-2, AC-3
U4	Git + clone: install git, safe.directory, committer identity (non-armistace), clone armistace/blog into workspace/, leave remote HTTP	U1, U3	AC-3, AC-4, AC-5
U5	Repo + docs: README.md, RUNBOOK.md (incl. SSH remote-switch + operator credential steps), docs/security-notes.md, docs/resiliency-notes.md, re-provision script	U1–U4	AC-7

---

Estimated Timeline

No wall-clock estimate offered — fabricating one would be worse than omitting it. The work is 5 units, several of which are a handful of commands each; the only genuinely uncertain step is U3 (Atheos-on-Alpine, risk C-1). Each unit ends in a verifiable state, so progress is measurable even without a time estimate.

---

Success Criteria

• Primary goal: a LAN-reachable Atheos on Alpine where armistace/blog is cloned and editable, with credentials owned entirely by the operator.
• Key deliverables: LXC 136 on scotty; Atheos served by nginx/PHP; the blog clone in the workspace; README + RUNBOOK + re-provision script; security/resiliency TODO notes.
• Quality gates:
  • AC-1…AC-8 all demonstrated with real command output (not assertions)
  • Atheos served (not 502/404) — verified over HTTP from the LAN
  • Reboot-survival verified (AC-6), not assumed
  • No Python/pelican present (AC-8) — proves scope was respected
  • No armistace credential or git identity created by the agent (FR-11)
  • Independent review of the generated provisioning script before the Build-and-Test gate
  • audit.md complete and append-only; aidlc-state.md current