From 79d88469d3003504468e064d0ad870031ac2b653 Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Mon, 16 Nov 2026 14:21:44 +0100 Subject: [PATCH] Hero-module: execution plan (Workflow Planning) Co-Authored-By: Claude Sonnet 5.5 --- .../features/hero-module/aidlc-state.md | 21 ++- aidlc-docs/features/hero-module/audit.md | 12 ++ .../inception/plans/execution-plan.md | 168 ++++++++++++++++++ 3 files changed, 193 insertions(+), 8 deletions(-) create mode 100644 aidlc-docs/features/hero-module/inception/plans/execution-plan.md diff --git a/aidlc-docs/features/hero-module/aidlc-state.md b/aidlc-docs/features/hero-module/aidlc-state.md index 3198a56..7c659fe 100644 --- a/aidlc-docs/features/hero-module/aidlc-state.md +++ b/aidlc-docs/features/hero-module/aidlc-state.md @@ -5,7 +5,7 @@ - **Feature Slug**: hero-module - **Project Type**: Brownfield - **Start Date**: 2026-11-16 -- **Current Stage**: INCEPTION - Requirements Analysis (requirements.md written, waiting for approval) +- **Current Stage**: INCEPTION - Workflow Planning (execution plan written, waiting for approval) - **Branch**: feature/hero-module (worktree K:\Development\Projects\SlpModularCms-contact-forms, from master b2cacfe) ## Workspace State @@ -43,12 +43,17 @@ ### 🔵 INCEPTION PHASE - [x] Workspace Detection (classification: Feature) - [x] Reverse Engineering (skipped: targeted review) -- [x] Requirements Analysis (requirements.md written, awaiting approval) -- [ ] User Stories -- [ ] Workflow Planning -- [ ] Application Design -- [ ] Units Generation +- [x] Requirements Analysis (approved by Bryan 2026-11-16) +- [x] User Stories (SKIP: one persona, acceptance criteria in the requirements) +- [x] Workflow Planning (execution-plan.md, awaiting approval) +- [ ] Application Design - EXECUTE +- [ ] Units Generation - EXECUTE ### 🟢 CONSTRUCTION PHASE -- [ ] Not started +- [ ] Functional Design - EXECUTE +- [ ] NFR Requirements - EXECUTE +- [ ] NFR Design - EXECUTE +- [ ] Infrastructure Design - CONDITIONAL (only if storage is a shared directory) +- [ ] Code Generation - EXECUTE (per unit H0 to H6) +- [ ] Build and Test - EXECUTE ### 🟡 OPERATIONS PHASE -- [ ] Undecided +- [ ] SKIP (Q19 = B; points go into the joint production checklist) diff --git a/aidlc-docs/features/hero-module/audit.md b/aidlc-docs/features/hero-module/audit.md index b71dc5a..7154c67 100644 --- a/aidlc-docs/features/hero-module/audit.md +++ b/aidlc-docs/features/hero-module/audit.md @@ -47,3 +47,15 @@ **Context**: Requirements Analysis complete, waiting for Bryan's approval (via the SLS session). --- + +## Requirements approved; Workflow Planning + +**Timestamp**: 2026-11-16T00:00:00Z + +**User Input**: "Bryan heeft het Hero-requirements-document goedgekeurd (2026-11-16). Ga verder met Workflow Planning en Application Design. ... (1) De tekstenlijst per sectie voor Bryans review (vraag 15) is niet nodig: Bryan heeft het volledige src/i18n/nl.json van SLS al ... (2) SLS-titel in 3 regels met schermlezertekst afgeleid uit de regels: dat werk ik uit voor de SLS-kant ... Houd het datamodel (title met regelafbrekingen) daarop aan. (3) Stem JSON-vorm, markernamen, golden files en het crop/focus-model af met de ASF-sessie; leg de keuze (focuspunt voor object-position of door de host uitgesneden varianten) met een korte aanbeveling aan Bryan voor." (relayed by SLP Software - SLS - Main) + +**AI Response**: Wrote execution-plan.md (Application Design, Units Generation and the design stages execute; User Stories and Reverse Engineering skipped; no Operations phase; units H0 to H6). Asked for approval of the plan before starting Application Design. + +**Context**: Workflow Planning; waiting for approval. + +--- diff --git a/aidlc-docs/features/hero-module/inception/plans/execution-plan.md b/aidlc-docs/features/hero-module/inception/plans/execution-plan.md new file mode 100644 index 0000000..2d7a72d --- /dev/null +++ b/aidlc-docs/features/hero-module/inception/plans/execution-plan.md @@ -0,0 +1,168 @@ +# Execution Plan: hero-module + +## Detailed Analysis Summary + +### Transformation Scope (Brownfield) +- **Transformation Type**: Single new module plus extensions in Core (media serving, host injection) and the admin frontend; a small CI change. +- **Primary Changes**: New `SlpModularCms.Modules.Hero` (+ Tests); image pipeline (validation, metadata stripping, variants, focus/crop); media serving with content-hash addresses; hero injection markers in the host (`HtmlMarkerEditor` / `HtmlMarkerInjector`, preload in the head, `hero` key in `#cms-data`); admin screens; seed script; release-branch condition on the SLP production jobs. +- **Related Components**: `SlpModularCms.Core` (Hosting/Website, rate limiting, texts), `SlpModularCms.Api` (master composition), `Api.SlpSoftware`, `Api.AndreaSlopFotografie` (module reference and committed defaults, `SiteContractTests`), `frontend/` (admin), `.gitea/workflows/continuous_integration.yaml`, `scripts/`, `openapi/slpsoftware.v1.json`, docs. The websites (SLS, ASF) change on their side. + +### Change Impact Assessment +- **User-facing changes**: Yes. The hero of both websites is rendered from CMS content; the admin gets a Hero screen; the public pages change when the sites adopt the markers. +- **Structural changes**: Yes. A new module, a new media-serving path and new injection parts. +- **Data model changes**: Yes. New tables (hero, slides, images/variants) and an EF migration. +- **API changes**: Yes. New public `GET /api/v1/hero`, new management endpoints, new media route; no change to existing contracts (NFR-08). +- **NFR impact**: Yes. LCP, upload safety (decompression bombs, memory), platform support (win-x64, linux-arm64), storage that survives deploys. + +### Component Relationships +```mermaid +flowchart LR + Admin["Admin frontend
(Hero screen)"] + Hero["Modules.Hero
(new)"] + Core["Core
(media serving, injection, texts)"] + Api["Api (master) and site projects"] + SLS["SLP Software website"] + ASF["ASF website"] + CI["CI workflow"] + Admin --> Hero + Hero --> Core + Api --> Hero + Core --> SLS + Core --> ASF + CI -.-> Api + classDef new fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000; + classDef exist fill:#BBDEFB,stroke:#1565C0,stroke-width:1px,color:#000; + classDef ext fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px,color:#000; + class Hero new; + class Admin,Core,Api,CI exist; + class SLS,ASF ext; +``` +Text alternative: the admin talks to the new Hero module; the module uses Core for media and injection; the master and site projects reference it; Core serves both websites. + +- **Primary Component**: `SlpModularCms.Modules.Hero` (Major, new). +- **Shared Components**: `SlpModularCms.Core` (Minor: new injection parts and media route), `frontend/` (Minor: new feature folder). +- **Dependent Components**: the two websites (golden files and markers agreed with the ASF and SLS sessions); `Api.*` projects (Configuration-only: module reference). +- **Supporting Components**: CI workflow (Minor: release-branch condition), docs and checklist. + +### Risk Assessment +- **Risk Level**: Medium to High (image processing of untrusted uploads; a native library on several platforms; contract with two sites). +- **Rollback Complexity**: Moderate (the module can be switched off per site; the baked hero stays; one migration). +- **Testing Complexity**: Complex (image fixtures, platform matrix, golden files for injection, LCP measurement on test hosts). + +## Workflow Visualization + +```mermaid +flowchart TD + Start(["User Request"]) + + subgraph INCEPTION["🔵 INCEPTION PHASE"] + WD["Workspace Detection
COMPLETED"] + RE["Reverse Engineering
SKIP"] + RA["Requirements Analysis
COMPLETED"] + US["User Stories
SKIP"] + WP["Workflow Planning
IN PROGRESS"] + AD["Application Design
EXECUTE"] + UG["Units Generation
EXECUTE"] + end + + subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"] + FD["Functional Design
EXECUTE"] + NFRA["NFR Requirements
EXECUTE"] + NFRD["NFR Design
EXECUTE"] + ID["Infrastructure Design
CONDITIONAL"] + CG["Code Generation
(Planning + Generation)
EXECUTE"] + BT["Build and Test
EXECUTE"] + end + + Start --> WD + WD --> RA + RA --> WP + WP --> AD + AD --> UG + UG --> FD + FD --> NFRA + NFRA --> NFRD + NFRD --> ID + ID --> CG + CG --> BT + 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 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 FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style NFRA fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style NFRD 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 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 Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + style INCEPTION fill:#BBDEFB,stroke:#1565C0,color:#000 + style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,color:#000 + linkStyle default stroke:#333,stroke-width:2px +``` +Text alternative: Inception (detection, requirements done; planning in progress; application design and units to execute; reverse engineering and user stories skipped) leads to construction (design stages per unit, code generation, build and test) and ends without an Operations phase. + +## Phases to Execute + +### 🔵 INCEPTION PHASE +- [x] Workspace Detection (COMPLETED) +- [x] Reverse Engineering (SKIPPED: targeted review; `_shared/` artifacts exist) +- [x] Requirements Analysis (COMPLETED, approved by Bryan 2026-11-16) +- [x] User Stories (SKIPPED) + - **Rationale**: One persona (the site administrator) plus the two websites as consumers; the requirements already carry the acceptance criteria and the contract is agreed with the two site sessions. +- [x] Execution Plan (IN PROGRESS) +- [ ] Application Design - EXECUTE + - **Rationale**: New module and new Core components (image pipeline, media store, injection parts); public JSON shape, marker names and crop/focus model (A3, A4) and the storage decision (A2) are decided here, with the ASF and SLS sessions. +- [ ] Units Generation - EXECUTE + - **Rationale**: Several independent pieces (CI condition, image pipeline, module backend, media serving, injection, admin UI, seed and docs) with a dependency order. + +### 🟢 CONSTRUCTION PHASE +- [ ] Functional Design - EXECUTE (per unit where needed: hero and slide rules, focus/crop model, injection output) + - **Rationale**: New data model and business rules (validation of targets, scheduling, slide selection, variant choice). +- [ ] NFR Requirements - EXECUTE (image pipeline and injection units) + - **Rationale**: Library choice (AVIF, licence, win-x64 and linux-arm64), upload limits, LCP and weight budgets (A1, A6, A7). +- [ ] NFR Design - EXECUTE (image pipeline unit) + - **Rationale**: Decompression-bomb protection, bounded parallelism, timeouts, failure behaviour (SECURITY-05, 11, 15). +- [ ] Infrastructure Design - CONDITIONAL + - **Rationale**: Only if storage is a shared directory (A2); with storage in the database it is skipped. Decided in Application Design. +- [ ] Code Generation - EXECUTE (ALWAYS), per unit, build and tests after every unit +- [ ] Build and Test - EXECUTE (ALWAYS) + - **Rationale**: Full suite, OpenAPI snapshot, golden files with ASF, smoke test extended, LCP measured on both test hosts. + +### 🟡 OPERATIONS PHASE +- SKIP (decided at Requirements Analysis, Q19 = B). The hero points go into `docs/release-checklist-productie.md`. + +## Proposed Units (to be confirmed in Units Generation) + +| Unit | Content | Depends on | +|---|---|---| +| H0 | CI: `release/*` condition on `publish-sls-production` and `deploy-sls-production`, docs | none (can be merged early) | +| H1 | Image pipeline: validation by content, metadata stripping, resize/compress, variants, focus/crop arithmetic (pure, property-tested) | library decision | +| H2 | Hero module backend: entities, migration, admin CRUD, public `GET /hero`, validation, schedule, texts, OpenAPI | H1 for upload | +| H3 | Media storage and serving (hash addresses, immutable cache, nosniff, rate limits) | H1 | +| H4 | Host injection (region marker, head preload, `hero` key in `#cms-data`, cache invalidation, golden files with ASF) | H2, H3 | +| H5 | Admin frontend: hero form, slide list, upload with focus/crop and preview | H2, H3 | +| H6 | Seed script (test), docs, release checklist, smoke test extension | H2 to H5 | + +## Package Change Sequence +1. H0 (independent; can go to master first). +2. H1, then H2 and H3 (parallel after H1). +3. H4 and H5 (parallel after H2 and H3). +4. H6, then Build and Test on the test hosts with the websites' markers. + +## Estimated Timeline +- **Total Stages**: 11 to execute (Application Design, Units Generation, Functional Design, NFR Requirements, NFR Design, Infrastructure Design if needed, Code Generation per unit, Build and Test), 3 skipped or not applicable. +- **Estimated Duration**: roughly 6 to 9 working days of build time across the units, excluding the websites' own work and Bryan's review time. + +## Success Criteria +- **Primary Goal**: The hero of both sites comes from the CMS, is live within about a minute, and the LCP element is in the first HTML without a regression. +- **Key Deliverables**: `SlpModularCms.Modules.Hero`, media serving, host injection with golden files, admin Hero screen, seed script, `release/*` condition, docs and checklist update. +- **Quality Gates**: Security rules compliant (blocking); property tests for the pure functions; full suite green; OpenAPI snapshot updated; smoke tests on both test hosts; LCP measured; no merge or production deploy without Bryan's go. +- **Integration Testing**: Both websites with the markers on the test hosts. +- **Operational Readiness**: Covered by the joint production checklist (no Operations phase).