docs(01-01): complete hello app kernel plan

- Record task commits, deviations, and verification evidence
2026-09-16 13:03:39 +02:00
parent 2078f91a2b
commit 201973d741
1 changed files with 160 additions and 0 deletions
--- a/.planning/phases/01-framework-kernel-foundation/01-01-SUMMARY.md
+++ b/.planning/phases/01-framework-kernel-foundation/01-01-SUMMARY.md
@@ -0,0 +1,160 @@
+---
+phase: 01-framework-kernel-foundation
+plan: 01
+subsystem: kernel
+tags: [go, cobra, koanf, plugins, cli, workspace]
+
+requires: []
+provides:
+  - Manifest-driven code generation and app build
+  - Required plugin interface and activation
+  - Shared cobra command construction
+  - Ordered hello plugin manifest
+affects: [01-02, 01-03, 01-04]
+
+tech-stack:
+  added:
+    - github.com/spf13/cobra v1.10.2
+    - github.com/knadh/koanf/v2 v2.3.6
+    - github.com/knadh/koanf/parsers/yaml v1.1.1
+  patterns:
+    - Compiled plugins self-register in init(); Activate orders by Requires()
+    - Shared bonfire.NewRoot used by tool and app
+    - summer.yaml ordered plugin list drives generated imports
+
+key-files:
+  created:
+    - party/registry.go
+    - backpack/app.go
+    - pact/capabilities.go
+    - compass/config.go
+    - bonfire/command.go
+    - bonfire/root.go
+    - internal/build/build.go
+    - cmd/summer/main.go
+    - examples/hello/summer.yaml
+    - examples/hello/main.go
+    - examples/hello/plugins.gen.go
+    - go.work
+  modified:
+    - go.mod
+    - go.sum
+    - .gitignore
+
+key-decisions:
+  - "Plugin lives in party with Register/Boot(*backpack.App); backpack does not import party"
+  - "bonfire.NewRoot takes []bonfire.Command, not a party registry"
+  - "HasConfig.ConfigFS() named to match Plan 02"
+  - "Example modules use local replace for unpublished git.golem15.com/golem15/summercms v0.0.0"
+  - "Pin toolchain go1.27.0 in go.work and every example go.mod"
+
+patterns-established:
+  - "Pattern: blank-import plugins.gen.go plus explicit PluginIDs slice; never use init order for lifecycle"
+  - "Pattern: summer build validates module paths, quotes imports, and execs go build with separate args"
+
+requirements-completed: [KERN-01, KERN-02, KERN-03, KERN-04, CLI-01]
+
+duration: 15min
+completed: 2026-09-16
+---
+
+# Phase 1 Plan 1: Hello App Kernel Summary
+
+**Compiled-plugin hello app boots via party.Activate and runs greeter:hello through a shared cobra/bonfire kernel, built by `summer build` from an ordered summer.yaml manifest**
+
+## Performance
+
+- **Duration:** 15 min
+- **Started:** 2026-09-16T10:47:05Z
+- **Completed:** 2026-09-16T11:02:48Z
+- **Tasks:** 2
+- **Files modified:** 30
+
+## Accomplishments
+
+- Framework kernel packages (`party`, `backpack`, `pact`, `compass`, `bonfire`) boot two compiled hello plugins with all Register calls before any Boot
+- Permanent `examples/hello` app prints `app.name` from `config/app.yaml` via `greeter:hello`
+- `cmd/summer build` generates stable `main.go`/`plugins.gen.go` from `summer.yaml` and produces `bin/hello` without importing example plugins
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Make the hello app boot and dispatch a plugin command** - `96a8d38` (feat)
+2. **Task 2: Generate and build the hello app from its ordered manifest** - `2078f91` (feat)
+
+**Plan metadata:** pending (docs: complete plan)
+
+## Files Created/Modified
+
+- `party/registry.go` - Plugin interface, init registry, topo-sorted Activate
+- `backpack/app.go` - App container holding compass config; no party import
+- `pact/capabilities.go` - HasCommands, HasConfig; reserved KERN-03 names documented
+- `compass/config.go` - Load config/<section>.yaml and String dot-path lookup
+- `bonfire/command.go` / `bonfire/root.go` - Command values, Input/Output, shared cobra root
+- `internal/build/build.go` - Manifest parse, validated codegen, `go build` via CommandContext
+- `cmd/summer/main.go` - Framework tool entry using the same NewRoot
+- `examples/hello/` - Workspace app, two plugin modules, summer.yaml, generated main
+- `go.mod` / `go.work` - cobra, koanf, toolchain go1.27.0, four workspace modules
+
+## Decisions Made
+
+- Keep `Plugin` in `party` taking `*backpack.App` so `backpack` never imports `party`
+- `bonfire.NewRoot(name, []Command, io.Writer)` is the single command kernel for tool and app
+- Name `HasConfig.ConfigFS()` now so Plan 02 can load embedded plugin defaults without a rename
+- Add `replace` lines in example `go.mod` files; D-04 allows go.work or local replace, and `v0.0.0` is not fetchable from the private module host
+- Re-pin `toolchain go1.27.0` after `go mod tidy`, which drops a matching toolchain line
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Local replace for unpublished framework module**
+- **Found during:** Task 1 (module tidy)
+- **Issue:** `go mod tidy` in example modules tried to fetch `git.golem15.com/golem15/summercms@v0.0.0` over HTTPS and failed (private host, no tag)
+- **Fix:** Added `replace git.golem15.com/golem15/summercms => <relative>` in hello/plugin go.mod files, which D-04 already allows
+- **Files modified:** `examples/hello/go.mod`, `examples/hello/plugins/base/go.mod`, `examples/hello/plugins/greeter/go.mod`
+- **Verification:** `go vet`/`go test` in root and hello
+- **Committed in:** `96a8d38` (Task 1)
+
+**2. [Rule 2 - Missing Critical] Restore toolchain directive after tidy**
+- **Found during:** Task 1
+- **Issue:** `go mod tidy` removed `toolchain go1.27.0` from go.mod files because the local toolchain already matched
+- **Fix:** Re-added the directive to root and all example modules plus `go.work` (D-05)
+- **Files modified:** `go.mod`, `examples/hello/go.mod`, plugin go.mod files, `go.work`
+- **Verification:** files contain `toolchain go1.27.0`
+- **Committed in:** `96a8d38` (Task 1)
+
+---
+
+**Total deviations:** 2 auto-fixed (1 blocking, 1 missing critical)
+**Impact on plan:** Required for a buildable workspace of unpublished modules and the D-05 toolchain pin. No scope creep.
+
+## Issues Encountered
+
+- Spawn HEAD was `master` on this isolated Grok clone (`.git` is a directory, not a linked worktree). Created `worktree-agent-01a0a9d2` from `552cadb` without rewriting `refs/heads/master`. Commits live on the agent branch.
+
+## Authentication Gates
+
+None.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+Ready for `01-02-PLAN.md` (layered compass config, optional plugin composition, services, typed events). Hello already boots and `summer build` is the shared generate-and-compile function later plans extend.
+
+## Self-Check: PASSED
+
+- Created kernel, hello, and build files exist on disk
+- Commits `96a8d38` and `2078f91` exist
+- Root and hello `go vet ./...` and `go test ./...` passed
+- Two `summer build` runs left `main.go`/`plugins.gen.go` hashes unchanged; `./bin/hello greeter:hello` printed `hello-app`
+- `go list -deps ./cmd/summer` has no hello plugin packages
+- STATE.md and ROADMAP.md were not updated in this worktree
+
+---
+*Phase: 01-framework-kernel-foundation*
+*Completed: 2026-09-16*