From 02090cde6a286f7e4c18a41a778a90fc4c60d0a5 Mon Sep 17 00:00:00 2001 From: Mike Kell Date: Fri, 22 May 2026 09:17:08 -0400 Subject: [PATCH] docs: add suggested improvements to master development brief --- .markdownlint.json | 6 + docs/development/build_execution_tracker.md | 40 ++++- docs/development/master_development_brief.md | 153 ++++++++++++++++++- 3 files changed, 187 insertions(+), 12 deletions(-) create mode 100644 .markdownlint.json diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..9fad2e8 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,6 @@ +{ + "MD013": false, + "MD024": { + "siblings_only": true + } +} \ No newline at end of file diff --git a/docs/development/build_execution_tracker.md b/docs/development/build_execution_tracker.md index 70cce4e..d287a85 100644 --- a/docs/development/build_execution_tracker.md +++ b/docs/development/build_execution_tracker.md @@ -2,10 +2,10 @@ ## Current status -- main baseline updated through: publishing-ux-hardening -- main baseline commit: `b81016d` (2026-04-11) -- next branch: feat/multi-select-groundwork -- current stage: Stage 3 — Web application operator efficiency +- main baseline updated through: list-efficiency-improvements (Stage 3 complete) +- main baseline commit: merge of `feat/list-efficiency-improvements` (2026-05-22) +- next branch: feat/android-app-shell +- current stage: Stage 4 — Android application foundation ## Slice tracker @@ -59,7 +59,37 @@ ### feat/multi-select-groundwork -- status: queued (Stage 3A — next) +- status: merged to main +- date: 2026-05-22 +- inspection: complete +- implementation: complete +- files changed: + - `feature_wordpress/lib/src/application/product_publishing_controller.dart` — added multi-selection state (`toggleMultiSelect`, `clearMultiSelection`, `selectAllVisible`, `isMultiSelected`, `multiSelectedIds`, `multiSelectedCount`) + - `feature_wordpress/lib/src/presentation/widgets/product_draft_card.dart` — added optional leading checkbox for multi-select mode + - `feature_wordpress/lib/src/presentation/product_publishing_page.dart` — added `_MultiSelectBar` with selected-count display, Select All, and Clear actions + - `feature_wordpress/test/product_publishing_controller_test.dart` — added 15 new multi-select tests +- tests: passed (262/262 feature_wordpress) +- analyze: passed +- brief updated: yes + +### feat/list-efficiency-improvements + +- status: merged to main +- date: 2026-05-22 +- inspection: complete +- implementation: complete +- files changed: + - `feature_wordpress/lib/src/application/product_publishing_controller.dart` — added `ListDensity` enum, compact/standard view toggle, staleness detection (`isStale()`, `staleCount()` with 30-day threshold), keyboard navigation (`selectNextDraft`/`selectPreviousDraft` with wrapping) + - `feature_wordpress/lib/src/presentation/widgets/product_draft_card.dart` — added compact two-row layout variant, description snippet in standard card, stale indicator icon, `Flexible` overflow handling + - `feature_wordpress/lib/src/presentation/product_publishing_page.dart` — wired `Focus`+`onKeyEvent` for arrow keys and density toggle button + - `feature_wordpress/test/product_publishing_controller_test.dart` — added 32 new tests +- tests: passed (294/294 feature_wordpress, 5/5 kell_web dashboard) +- analyze: passed +- brief updated: yes + +### feat/android-app-shell + +- status: queued (Stage 4A — next) - inspection: pending - implementation: pending - tests: pending diff --git a/docs/development/master_development_brief.md b/docs/development/master_development_brief.md index e13dbf3..f3d8f83 100644 --- a/docs/development/master_development_brief.md +++ b/docs/development/master_development_brief.md @@ -45,14 +45,23 @@ Rules: ### Platform structure -- `apps/kell_web` exists. +- `apps/kell_web` exists — active, wired to shared packages. +- `apps/kell_mobile` exists — scaffolded as default Flutter template, **not yet integrated** with shared packages. - Shared packages include: - - `core` - - `design_system` - - `feature_inventory` - - `feature_wordpress` - - `feature_orders` - - `feature_policy` + - `core` — shared domain/application abstractions + - `design_system` — theme (colors, spacing, theme) and shared widgets (KcCard, KcStatusChip) + - `feature_inventory` — domain, application, data (fake), and presentation layers + - `feature_wordpress` — domain, application, data (fake + WooCommerce), and presentation layers (most mature feature) + - `feature_orders` — domain, application, data (fake), and presentation layers + - `feature_policy` — domain, application, data (fake), and presentation layers +- Scaffolded but **empty stub** packages (created, no implementation yet): + - `auth` — authentication/authorization (stub only) + - `data` — shared data layer (stub only) + - `integrations` — shared integration abstractions (stub only) + - `feature_finance` — financial analysis feature (stub only) + - `feature_mrp` — craft manufacturing/MRP feature (stub only) + - `feature_social` — social media management feature (stub only) +- `tools/` directory exists but is empty. - App shell, routing, dashboard, reusable shell widgets, `AppServices`, and `AppScope` are implemented. - Dashboard uses app-composed repository data. - Vertical slices exist for Inventory, Products/Publishing, Orders, and Policy/Governance. @@ -227,11 +236,16 @@ Create the Android app entry and shell for the existing platform. - ensure FAKE mode works cleanly on Android first - mobile shell/navigation should stay simple and consistent with shared app structure +##### Current state note + +> `kell_mobile` exists as a default Flutter counter template. It does **not** yet reference any shared packages (`core`, `design_system`, `feature_*`). This stage must replace the template with a proper app shell that mirrors the `kell_web` composition pattern (`AppServices`, `AppScope`, routing, shell). + ##### Definition of done - app runs on Android emulator/device in FAKE mode - shell, navigation, and core screens render - analyze/tests remain clean +- `kell_mobile/pubspec.yaml` references shared packages #### Stage 4B — Android publishing surface @@ -322,6 +336,110 @@ Do not begin until: --- +## Suggested improvements (identified from codebase analysis) + +This section captures structural improvements, coverage gaps, and maturity enhancements identified through codebase analysis against the architecture documentation and current implementation state. Items here are candidates for future stages or can be woven into existing stages as appropriate. + +### 1. Stub package activation roadmap + +The following packages exist as scaffolded stubs with no implementation. Each needs an activation plan aligned to architecture documentation: + +| Package | Architecture Reference | Priority | Notes | +| ----------------- | --------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | +| `auth` | Enterprise Identity & Access Architecture | High | No auth layer exists; all access is currently uncontrolled. Required before any multi-user or production deployment. | +| `data` | Enterprise Data Architecture | Medium | Shared data abstractions/caching could reduce duplication across feature repositories. | +| `integrations` | Enterprise Integration & Orchestration Architecture | Medium | Shared integration contracts could formalize API client patterns currently embedded in `feature_wordpress`. | +| `feature_finance` | Financial Analysis Components | Low | Architecture docs exist but no implementation. Defer until core WordPress/Inventory workflows mature. | +| `feature_mrp` | Craft Manufacturing / MRP Components | Low | Architecture docs exist but no implementation. Defer until inventory workflows mature. | +| `feature_social` | Social Media Management Components | Low | Architecture docs exist but no implementation. Defer until core platform stabilizes. | + +**Recommendation:** Add a **Stage 7 — Infrastructure package activation** to the roadmap covering `auth`, `data`, and `integrations` before expanding into new feature domains. + +### 2. Design system expansion + +The `design_system` package currently contains: + +- Theme: `KcColors`, `KcSpacing`, `KcTheme` +- Widgets: `KcCard`, `KcStatusChip` + +**Gaps identified:** + +- No shared typography scale +- No shared button/action component library +- No responsive layout utilities for cross-platform (web + mobile) +- No shared empty state, loading state, or error state patterns +- Shell widgets (`EmptyStatePanel`, `SectionHeader`, `SummaryCard`) live in `kell_web` app rather than `design_system` + +**Recommendation:** Before or during Stage 4 (Android), migrate reusable shell widgets into `design_system` and add responsive layout primitives. This prevents duplication between `kell_web` and `kell_mobile`. + +### 3. Cross-platform shell composition strategy + +`kell_web` uses a well-structured composition pattern (`AppServices`, `AppScope`, `AppConfig`, `Bootstrap`). `kell_mobile` has none of this — it's a default counter app. + +**Recommendation:** Extract a shared shell composition pattern or at minimum define a documented convention so that `kell_mobile` mirrors the `kell_web` architecture. Consider whether `AppServices`, `AppScope`, and bootstrap logic should move to a shared `core` or `app_shell` package, or remain duplicated with a documented contract. + +### 4. CI/CD for Flutter applications + +Currently, CI/CD exists only for MkDocs documentation publishing. There is no automated pipeline for: + +- Flutter `dart analyze` on PRs +- Flutter test execution on PRs +- Flutter build validation (web + Android) +- Test result reporting or quality gates + +**Recommendation:** Add a **Stage 4 prerequisite or parallel track** to establish Flutter CI/CD in Forgejo Actions before the Android expansion adds more surfaces to validate. + +### 5. Test coverage visibility and quality gates + +Test counts are tracked manually in this brief (e.g., `294/294 passed`). There is no: + +- Automated test count reporting +- Coverage measurement +- Minimum coverage threshold enforcement +- Test trend tracking across slices + +**Recommendation:** Introduce coverage tooling and reporting as part of CI/CD establishment. Even lightweight coverage tracking (total tests, pass rate per package) would improve confidence during the Android expansion. + +### 6. Build execution tracker synchronization + +The `build_execution_tracker.md` is stale: + +- Shows `feat/multi-select-groundwork` as "queued" when it was merged 2026-05-22 +- Does not include `feat/list-efficiency-improvements` at all +- `current status` section references Stage 3 as current when Stage 3 is complete + +**Recommendation:** Update the tracker immediately and consider whether the tracker should be auto-generated or at minimum updated as part of the standard slice completion checklist. + +### 7. Image and media management + +Architecture documentation (`traceability-index.md` coverage gaps) identifies "Product image / media synchronization workflow" as a gap. The current publishing workflow handles text fields only. + +**Recommendation:** Plan a future stage for image/media management once existing narrow edits are stable on both platforms. This aligns with the architecture gap analysis. + +### 8. Error tracking and observability + +No monitoring, error tracking, or analytics strategy exists for the Flutter applications. In production use: + +- Runtime errors are invisible unless the operator sees them +- No crash reporting +- No usage analytics to guide prioritization + +**Recommendation:** Add lightweight error reporting and observability as a future stage, particularly important before any production WP-mode deployment beyond a single operator. + +### 9. Empty tools directory + +The `tools/` directory under `kell_creations_apps` exists but contains nothing. + +**Recommendation:** Either populate with development tooling (code generation scripts, analysis helpers, CI scripts) or remove to avoid confusion. If CI/CD scripts are planned, this is a natural home. + +### 10. Missing feature parity documentation + +The architecture documentation describes rich capabilities across all domains (Inventory, MRP, WordPress, Social Media, Financial Analysis), but actual implementation maturity varies dramatically. Only `feature_wordpress` has substantial implementation. + +**Recommendation:** Add a **feature maturity matrix** to this brief or a companion document that maps architecture aspirations to actual implementation status per feature package. This would make prioritization conversations clearer. + +--- + ## Required development workflow for every slice For every branch/stage: @@ -336,6 +454,7 @@ For every branch/stage: 8. Summarize changed files and validation results. 9. Open PR into `main`. 10. Merge only after clean review and validation. +11. **Update this brief and the build execution tracker** after merge. --- @@ -367,4 +486,24 @@ Working rules: 5. Add/update focused tests. 6. Run validation. 7. Report changed files and validation results. +8. Update master_development_brief.md and build_execution_tracker.md after merge. ``` + +--- + +## Appendix: Feature maturity matrix + +| Package | Domain Layer | Application Layer | Data (Fake) | Data (Real) | Presentation | Tests | Maturity | +| ------------------- | ------------ | ----------------- | ----------- | -------------- | ------------------------------ | ------- | -------------------- | +| `feature_wordpress` | ✅ Complete | ✅ Complete | ✅ Complete | ✅ WooCommerce | ✅ Complete | 294 | **Production-ready** | +| `feature_inventory` | ✅ Complete | ✅ Complete | ✅ Complete | ❌ None | ✅ Complete | Minimal | **Fake-only MVP** | +| `feature_orders` | ✅ Complete | ✅ Complete | ✅ Complete | ❌ None | ✅ Complete | Some | **Fake-only MVP** | +| `feature_policy` | ✅ Complete | ✅ Complete | ✅ Complete | ❌ None | ✅ Complete | Minimal | **Fake-only MVP** | +| `feature_finance` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | None | **Scaffolded only** | +| `feature_mrp` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | None | **Scaffolded only** | +| `feature_social` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | None | **Scaffolded only** | +| `auth` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | N/A | None | **Scaffolded only** | +| `data` | ❌ Stub | N/A | N/A | ❌ None | N/A | None | **Scaffolded only** | +| `integrations` | ❌ Stub | N/A | N/A | ❌ None | N/A | None | **Scaffolded only** | +| `design_system` | N/A | N/A | N/A | N/A | ✅ Partial (theme + 2 widgets) | Minimal | **Foundation only** | +| `core` | ✅ Partial | N/A | N/A | N/A | N/A | Minimal | **Foundation only** |