summercms/.planning/phases/01-framework-kernel-foundation/01-01-SUMMARY.md

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, requirements-completed, duration, completed

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	key-decisions	patterns-established	requirements-completed	duration	completed
01-framework-kernel-foundation	01	kernel	go cobra koanf plugins cli workspace		Manifest-driven code generation and app build Required plugin interface and activation Shared cobra command construction Ordered hello plugin manifest	01-02 01-03 01-04	added patterns github.com/spf13/cobra v1.10.2 github.com/knadh/koanf/v2 v2.3.6 github.com/knadh/koanf/parsers/yaml v1.1.1 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	created modified 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 go.mod go.sum .gitignore	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	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	KERN-01 KERN-02 KERN-03 KERN-04 CLI-01	15min	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/
  .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