feat(migrate): add lifecycle commands and standalone authoring (#18)

Add apply/require startup policies and five database-only migration commands.

Provide standalone corestack-goose creation and reconciliation with fresh
provider-local Go registrations. Default optional --dir to the working directory.
Document the production boundary and source recovery requirements.

Closes #9

.gitea/workflows/docs-check.yml

@@ -12,4 +12,4 @@ jobs:
         with:
           go-version-file: go.mod
           cache: false
-      - run: go run ./cmd/docs check
+      - run: go run ./cmd/corestack-docs check

.goreleaser.yaml

@@ -1,10 +1,10 @@
 version: 2
-project_name: docs
+project_name: corestack-docs
 
 builds:
-  - id: docs
-    main: ./cmd/docs
-    binary: docs
+  - id: corestack-docs
+    main: ./cmd/corestack-docs
+    binary: corestack-docs
     env:
       - CGO_ENABLED=0
     goos: [darwin, linux]
@@ -14,7 +14,7 @@ builds:
 
 archives:
   - formats: [tar.gz]
-    name_template: "docs_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+    name_template: "corestack-docs_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
 
 checksum:
   name_template: checksums.txt

AGENTS.md

@@ -3,7 +3,7 @@
 ## Commands
 - Check: `go build ./...`, `go vet ./...`, `go test -race ./...`, `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 run ./...`; from the project root, run the TODO check below.
 - Generate: No code generation is configured; format with `gofmt -w .`.
-- Documentation: `go run ./cmd/docs check`; create records with `go run ./cmd/docs new adr|plan "Title"`. This checker repository uses its local implementation as the source of truth.
+- Documentation: `go run ./cmd/corestack-docs check`; create records with `go run ./cmd/corestack-docs new adr|plan "Title"`. This checker repository uses its local implementation as the source of truth.
 
 ## Scope and decisions
 - Before editing under a directory with its own AGENTS.md, read it. Scoped files: none currently; this root governs the repository, including nested Go modules unless nearer instructions override it.
@@ -28,7 +28,7 @@
 
 Go module `go.auvem.com/corestack`.
 
-- Docs format (the spec `docs check` implements): `docs/docs-format.md`.
+- Docs format (the spec `corestack-docs check` implements): `docs/docs-format.md`.
 - Decisions live in `docs/adr/`, plans in `docs/plans/`. Records are permanent; never rename them.
 - Add dependencies only to the module that needs them; heavy dependencies go in nested modules (see the [module-boundary ADR](/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md)).
 

README.md

@@ -1,26 +1,26 @@
 # corestack go
 
-Shared Go building blocks. Includes `docs`, a checker for architecture decision records (ADRs) and implementation plans; `page`, Bob keyset pagination; and `lifecycle`, a service and worker coordinator.
+Shared Go building blocks. Includes `corestack-docs`, a checker for architecture decision records (ADRs) and implementation plans; `page`, Bob keyset pagination; and `lifecycle`, a service and worker coordinator.
 
 ## migrate
 
 [`migrate`](migrate/README.md) configures Goose providers for embedded SQL and Go
 migrations, with structured logging and Postgres startup locking.
 
-## docs
+## corestack-docs
 
 Install:
 
 ```sh
-go install go.auvem.com/corestack/cmd/docs@latest
+go install go.auvem.com/corestack/cmd/corestack-docs@latest
 ```
 
 Use, from a repository root:
 
 ```sh
-docs new adr "Use Example Queue for background jobs"   # creates docs/adr/<id>.md
-docs new plan "Adopt Example Queue"                    # creates docs/plans/<id>.md
-docs check [--root DIR]                                # prints path:line: message; exit 1 on problems
+corestack-docs new adr "Use Example Queue for background jobs"   # creates docs/adr/<id>.md
+corestack-docs new plan "Adopt Example Queue"                    # creates docs/plans/<id>.md
+corestack-docs check [--root DIR]                                # prints path:line: message; exit 1 on problems
 ```
 
 The format is specified in [docs/docs-format.md](docs/docs-format.md); that document is the complete rule set. Exit status is `0` when every record is valid, `1` when problems are reported and `2` for usage errors.
@@ -63,6 +63,27 @@ for at least two signals, and subscription cleanup. Nil signals disable receptio
 There are no signal subscriptions, process exits, external dependencies or CLI
 integration in this package.
 
+## lifecycle/cli
+
+`go.auvem.com/corestack/lifecycle/cli` adapts native `urfave/cli/v3` commands.
+Bind `Serve(config, modules)` to run selected services, or `Action(config, modules,
+fn)` for a one-off with selected setup/cleanup and module services suppressed.
+See the [executable serve/inspect example](lifecycle/cli/example_test.go).
+
+`Run(ctx, cliRoot, args)` accepts argv including the program name and returns the
+exit code and inspectable error: success/help/graceful first signal is 0, usage is
+2, and runtime/lifecycle failure is 1. Runtime failures dominate mixed errors.
+Run prints diagnostics without exiting; the caller owns process exit. Nil signals
+subscribe to SIGINT/SIGTERM during adapted actions; injected channels stay caller
+owned. The private lifecycle App does not expose managed-worker admission.
+
+Use fresh command trees and leave `ExitErrHandler`, `OnUsageError` and
+`CommandNotFound` unset; Run owns those hooks. Other native hooks run outside the
+adapted lifecycle action. Native environment/custom validation and generated-help
+parse failures can return 1 with native diagnostics; custom pre-lifecycle
+validators may return `urfavecli.Exit(err, 2)` for usage. Help and flags use native
+urfave/cli declarations, without a configuration or environment facade.
+
 ## Status
 
 No support is guaranteed. Breaking changes, including to the format rules, may happen before 1.0 and are listed in the release notes.

cmd/corestack-docs/main.go

@@ -1,4 +1,4 @@
-// Command docs creates and checks ADR and plan records. See docs/docs-format.md.
+// Command corestack-docs creates and checks ADR and plan records. See docs/docs-format.md.
 package main
 
 import (
@@ -12,8 +12,8 @@ import (
 )
 
 const usage = `usage:
-  docs new adr|plan "Title"
-  docs check [--root DIR]
+  corestack-docs new adr|plan "Title"
+  corestack-docs check [--root DIR]
 `
 
 func main() { os.Exit(run(os.Args[1:], os.Stdout, os.Stderr, time.Now())) }
@@ -32,13 +32,13 @@ func run(args []string, stdout, stderr io.Writer, now time.Time) int {
 		}
 		path, err := docs.New(".", args[1], args[2], now)
 		if err != nil {
-			fmt.Fprintf(stderr, "docs: %v\n", err)
+			fmt.Fprintf(stderr, "corestack-docs: %v\n", err)
 			return 1
 		}
 		fmt.Fprintln(stdout, path)
 		return 0
 	case "check":
-		fs := flag.NewFlagSet("docs check", flag.ContinueOnError)
+		fs := flag.NewFlagSet("corestack-docs check", flag.ContinueOnError)
 		fs.SetOutput(stderr)
 		root := fs.String("root", ".", "repository root")
 		if err := fs.Parse(args[1:]); err != nil || fs.NArg() != 0 {
@@ -49,7 +49,7 @@ func run(args []string, stdout, stderr io.Writer, now time.Time) int {
 		}
 		res, err := docs.Check(*root)
 		if err != nil {
-			fmt.Fprintf(stderr, "docs: %v\n", err)
+			fmt.Fprintf(stderr, "corestack-docs: %v\n", err)
 			return 1
 		}
 		for _, p := range res.Problems {

cmd/corestack-goose/internal/authoring/authoring.go

@@ -0,0 +1,424 @@
+// Package authoring owns the standalone tool's bounded migration source format.
+// It requires one writer and a complete source backup; it never accesses a DB.
+package authoring
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"go/ast"
+	"go/format"
+	"go/parser"
+	"go/token"
+	"io"
+	"math"
+	"os"
+	"path/filepath"
+	"slices"
+	"strconv"
+	"strings"
+	"text/template"
+	"time"
+
+	"github.com/pressly/goose/v3"
+)
+
+const marker = "// Code generated by corestack-goose. DO NOT EDIT.\n"
+const goTemplate = `package migrations
+import (
+ "context"
+ "database/sql"
+ "github.com/pressly/goose/v3"
+)
+func migration{{.CamelName}}(version int64) *goose.Migration {
+ return goose.NewGoMigration(version, &goose.GoFunc{RunTx: up{{.CamelName}}}, &goose.GoFunc{RunTx: down{{.CamelName}}})
+}
+func up{{.CamelName}}(ctx context.Context, tx *sql.Tx) error {
+ return nil
+}
+func down{{.CamelName}}(ctx context.Context, tx *sql.Tx) error {
+ return nil
+}
+`
+
+type migration struct {
+	name, factory string
+	version       int64
+	data          []byte
+}
+
+type change struct {
+	source, dest string
+	data         []byte
+	replace      bool
+}
+
+type sourceSet struct {
+	dir        string
+	migrations []migration
+	register   []byte
+}
+
+// Create stages Goose's supported templates, then publishes a preflighted set.
+// Go names use lowercase ASCII words separated by underscores. All versions and
+// identifiers must be unique across the directory; existing bodies are preserved.
+func Create(dir, name, kind string) error {
+	if !validName(name) || (kind != "sql" && kind != "go") {
+		return errors.New("create: expected lowercase_words name and sql|go")
+	}
+	set, err := scan(dir)
+	if err != nil {
+		return err
+	}
+	stage, err := os.MkdirTemp("", "corestack-goose-*")
+	if err != nil {
+		return err
+	}
+	defer os.RemoveAll(stage)
+	var tmpl *template.Template
+	if kind == "go" {
+		tmpl, err = template.New("migration").Parse(goTemplate)
+		if err != nil {
+			return err
+		}
+	}
+	if err := goose.CreateWithTemplate(nil, stage, tmpl, name, kind); err != nil {
+		return fmt.Errorf("stage creation: %w", err)
+	}
+	entries, err := os.ReadDir(stage)
+	if err != nil {
+		return err
+	}
+	if len(entries) != 1 {
+		return errors.New("stage creation: expected one migration")
+	}
+	filename := entries[0].Name()
+	data, err := os.ReadFile(filepath.Join(stage, filename))
+	if err != nil {
+		return err
+	}
+	if kind == "go" {
+		filename = strings.TrimSuffix(filename, ".go") + "_migration.go"
+		data, err = format.Source(data)
+		if err != nil {
+			return err
+		}
+	}
+	item, err := parseMigration(filename, data)
+	if err != nil {
+		return err
+	}
+	items := append(slices.Clone(set.migrations), item)
+	if err := validate(items); err != nil {
+		return err
+	}
+	register, err := aggregate(items)
+	if err != nil {
+		return err
+	}
+	changes := []change{{dest: filename, data: data}}
+	changes = appendRegister(changes, set, register)
+	return publish(set, changes, writeExclusive)
+}
+
+// Fix preserves sequential IDs and allocates timestamp IDs after their maximum.
+// It never rewrites migration bodies or database history. Commit or separately
+// back up all sources first; on failure restore that backup before retrying.
+func Fix(dir string) error {
+	set, err := scan(dir)
+	if err != nil {
+		return err
+	}
+	items := slices.Clone(set.migrations)
+	var highest int64
+	for _, item := range items {
+		if !timestamp(item.version) && item.version > highest {
+			highest = item.version
+		}
+	}
+	var changes []change
+	for i := range items {
+		if !timestamp(items[i].version) {
+			continue
+		}
+		if highest == math.MaxInt64 {
+			return errors.New("fix: sequential version overflow")
+		}
+		highest++
+		old := items[i].name
+		items[i].version = highest
+		items[i].name = fmt.Sprintf("%05d_%s", highest, strings.SplitN(old, "_", 2)[1])
+		changes = append(changes, change{source: old, dest: items[i].name, data: items[i].data})
+	}
+	if err := validate(items); err != nil {
+		return err
+	}
+	register, err := aggregate(items)
+	if err != nil {
+		return err
+	}
+	changes = appendRegister(changes, set, register)
+	return publish(set, changes, writeExclusive)
+}
+
+func timestamp(version int64) bool {
+	t, err := time.Parse("20060102150405", strconv.FormatInt(version, 10))
+	return err == nil && t.Unix() > 0
+}
+
+func validName(name string) bool {
+	for _, word := range strings.Split(name, "_") {
+		if word == "" {
+			return false
+		}
+		for _, r := range word {
+			if r < 'a' || r > 'z' {
+				return false
+			}
+		}
+	}
+	return true
+}
+
+func parseMigration(name string, data []byte) (migration, error) {
+	item := migration{name: name, data: data}
+	ext := filepath.Ext(name)
+	parts := strings.SplitN(strings.TrimSuffix(name, ext), "_", 2)
+	if len(parts) != 2 {
+		return item, fmt.Errorf("unsupported migration filename %s", name)
+	}
+	raw := parts[0]
+	if strings.IndexFunc(raw, func(r rune) bool { return r < '0' || r > '9' }) >= 0 {
+		return item, fmt.Errorf("invalid version in %s", name)
+	}
+	v, err := strconv.ParseInt(raw, 10, 64)
+	if err != nil || v <= 0 {
+		return item, fmt.Errorf("invalid positive int64 version in %s", name)
+	}
+	item.version = v
+	if ext == ".sql" {
+		return item, nil
+	}
+	logical, ok := strings.CutSuffix(parts[1], "_migration")
+	if !ok || !validName(logical) {
+		return item, fmt.Errorf("unsupported Go filename %s: use <version>_<lowercase_words>_migration.go", name)
+	}
+	var camel strings.Builder
+	for _, word := range strings.Split(logical, "_") {
+		camel.WriteString(strings.ToUpper(word[:1]) + word[1:])
+	}
+	item.factory = "migration" + camel.String()
+	file, err := parser.ParseFile(token.NewFileSet(), name, data, 0)
+	if err != nil {
+		return item, fmt.Errorf("parse %s: %w", name, err)
+	}
+	if file.Name.Name != "migrations" {
+		return item, fmt.Errorf("%s: expected package migrations", name)
+	}
+	count := 0
+	for _, decl := range file.Decls {
+		fn, ok := decl.(*ast.FuncDecl)
+		if !ok || fn.Name.Name != item.factory {
+			continue
+		}
+		var signature bytes.Buffer
+		if err := format.Node(&signature, token.NewFileSet(), fn.Type); err != nil {
+			return item, err
+		}
+		if fn.Recv != nil || signature.String() != "func(version int64) *goose.Migration" || fn.Body == nil {
+			return item, fmt.Errorf("%s: expected %s(version int64) *goose.Migration factory", name, item.factory)
+		}
+		count++
+	}
+	if count != 1 {
+		return item, fmt.Errorf("%s: expected one %s factory", name, item.factory)
+	}
+	return item, nil
+}
+
+func validate(items []migration) error {
+	slices.SortFunc(items, func(a, b migration) int {
+		if a.version < b.version {
+			return -1
+		}
+		if a.version > b.version {
+			return 1
+		}
+		return 0
+	})
+	factories := make(map[string]bool)
+	for i, item := range items {
+		if i > 0 {
+			previous := items[i-1]
+			if previous.version == item.version {
+				return fmt.Errorf("duplicate version: %s and %s", previous.name, item.name)
+			}
+			if previous.name >= item.name {
+				return fmt.Errorf("lexical/numeric order disagreement: %s and %s; use consistent padding", previous.name, item.name)
+			}
+		}
+		if item.factory != "" {
+			if factories[item.factory] {
+				return fmt.Errorf("duplicate factory %s", item.factory)
+			}
+			factories[item.factory] = true
+		}
+	}
+	return nil
+}
+
+func aggregate(items []migration) ([]byte, error) {
+	var out strings.Builder
+	out.WriteString(marker + "\n// Package migrations contains application-owned SQL and Go migrations.\n// corestack-goose owns this aggregate; registrations are provider-local.\npackage migrations\n\nimport \"github.com/pressly/goose/v3\"\n\n// GoMigrations returns fresh provider-local registrations on every call.\nfunc GoMigrations() []*goose.Migration {\nreturn []*goose.Migration{\n")
+	for _, item := range items {
+		if item.factory != "" {
+			fmt.Fprintf(&out, "%s(%d),\n", item.factory, item.version)
+		}
+	}
+	out.WriteString("}\n}\n")
+	return format.Source([]byte(out.String()))
+}
+
+func scan(dir string) (sourceSet, error) {
+	set := sourceSet{dir: dir}
+	absolute, err := filepath.Abs(dir)
+	if err != nil {
+		return set, err
+	}
+	resolved, err := filepath.EvalSymlinks(absolute)
+	if err != nil {
+		return set, err
+	}
+	if resolved != absolute {
+		return set, fmt.Errorf("%s: symlink paths are unsupported", dir)
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return set, err
+	}
+	for _, entry := range entries {
+		name := entry.Name()
+		if name != "register.go" && filepath.Ext(name) != ".go" && filepath.Ext(name) != ".sql" {
+			continue
+		}
+		info, err := entry.Info()
+		if err != nil {
+			return set, err
+		}
+		if !info.Mode().IsRegular() {
+			return set, fmt.Errorf("%s: expected regular file", name)
+		}
+		data, err := os.ReadFile(filepath.Join(dir, name))
+		if err != nil {
+			return set, err
+		}
+		if name == "register.go" {
+			set.register = data
+			continue
+		}
+		item, err := parseMigration(name, data)
+		if err != nil {
+			return set, err
+		}
+		set.migrations = append(set.migrations, item)
+	}
+	if err := validate(set.migrations); err != nil {
+		return set, err
+	}
+	expected, err := aggregate(set.migrations)
+	if err != nil {
+		return set, err
+	}
+	if set.register != nil {
+		normalized, err := format.Source(set.register)
+		if err != nil || !bytes.HasPrefix(set.register, []byte(marker)) || !bytes.Equal(normalized, expected) {
+			return set, errors.New("register.go: unsupported or drifted aggregate; restore the complete source backup")
+		}
+	} else {
+		for _, item := range set.migrations {
+			if item.factory != "" {
+				return set, errors.New("register.go missing: restore the complete source backup")
+			}
+		}
+	}
+	return set, nil
+}
+
+func appendRegister(changes []change, set sourceSet, data []byte) []change {
+	if bytes.Equal(data, set.register) {
+		return changes
+	}
+	return append(changes, change{dest: "register.go", data: data, replace: set.register != nil})
+}
+
+func writeExclusive(path string, data []byte) error {
+	file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o666)
+	if err != nil {
+		return err
+	}
+	_, writeErr := io.Copy(file, bytes.NewReader(data))
+	return errors.Join(writeErr, file.Close())
+}
+
+// invariant: publish complete destinations before deleting sources; a failure
+// stops the plan and requires manual source restoration, never an automatic retry.
+func publish(set sourceSet, changes []change, write func(string, []byte) error) error {
+	if len(changes) == 0 {
+		return nil
+	}
+	for _, op := range changes {
+		if !op.replace {
+			if _, err := os.Lstat(filepath.Join(set.dir, op.dest)); !errors.Is(err, os.ErrNotExist) {
+				return fmt.Errorf("destination %s exists or cannot be checked: %w", op.dest, errors.Join(err, os.ErrExist))
+			}
+		}
+	}
+	stage, err := os.MkdirTemp(set.dir, ".corestack-goose-*")
+	if err != nil {
+		return err
+	}
+	defer os.RemoveAll(stage)
+	for i, op := range changes {
+		if err := writeExclusive(filepath.Join(stage, strconv.Itoa(i)), op.data); err != nil {
+			return fmt.Errorf("stage %s: %w", op.dest, err)
+		}
+	}
+	var completed []string
+	for i, op := range changes {
+		dest := filepath.Join(set.dir, op.dest)
+		if op.replace {
+			var current []byte
+			info, statErr := os.Lstat(dest)
+			if statErr != nil || !info.Mode().IsRegular() {
+				err = fmt.Errorf("aggregate is no longer regular: %w", errors.Join(statErr, os.ErrInvalid))
+			} else {
+				current, err = os.ReadFile(dest)
+				if err == nil && !bytes.Equal(current, set.register) {
+					err = errors.New("aggregate changed since preflight")
+				}
+				if err == nil {
+					err = os.Rename(filepath.Join(stage, strconv.Itoa(i)), dest)
+				}
+			}
+		} else {
+			err = write(dest, op.data)
+		}
+		if err == nil {
+			completed = append(completed, op.dest)
+			if op.source != "" {
+				err = os.Remove(filepath.Join(set.dir, op.source))
+				if err == nil {
+					completed = append(completed, "removed "+op.source)
+				}
+			}
+		}
+		if err != nil {
+			var outstanding []string
+			for _, pending := range changes[i:] {
+				outstanding = append(outstanding, fmt.Sprintf("%s -> %s", pending.source, pending.dest))
+			}
+			return fmt.Errorf("authoring stopped: %w; completed %v; inspect current/partial destination %s; outstanding %v; restore complete source backup before retry", err, completed, op.dest, outstanding)
+		}
+	}
+	return nil
+}

cmd/corestack-goose/internal/authoring/authoring_test.go

@@ -0,0 +1,313 @@
+package authoring
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func directory(t *testing.T) string {
+	t.Helper()
+	dir, err := filepath.EvalSymlinks(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	return dir
+}
+func put(t *testing.T, dir, name string, data []byte) {
+	t.Helper()
+	if err := os.WriteFile(filepath.Join(dir, name), data, 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+func snapshot(t *testing.T, dir string) map[string]string {
+	t.Helper()
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	result := map[string]string{}
+	for _, entry := range entries {
+		if entry.IsDir() {
+			result[entry.Name()] = "<directory>"
+			continue
+		}
+		data, err := os.ReadFile(filepath.Join(dir, entry.Name()))
+		if err != nil {
+			t.Fatal(err)
+		}
+		result[entry.Name()] = string(data)
+	}
+	return result
+}
+func seedGo(t *testing.T, dir, name string, version int64) {
+	t.Helper()
+	if err := Create(dir, name, "go"); err != nil {
+		t.Fatal(err)
+	}
+	set, err := scan(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	item := set.migrations[len(set.migrations)-1]
+	old := item.name
+	item.name = fmt.Sprintf("%05d_%s", version, strings.SplitN(old, "_", 2)[1])
+	item.version = version
+	if err := os.Rename(filepath.Join(dir, old), filepath.Join(dir, item.name)); err != nil {
+		t.Fatal(err)
+	}
+	set.migrations[len(set.migrations)-1] = item
+	data, err := aggregate(set.migrations)
+	if err != nil {
+		t.Fatal(err)
+	}
+	put(t, dir, "register.go", data)
+}
+func TestCreateFixAndPreserveEdits(t *testing.T) {
+	dir := directory(t)
+	seedGo(t, dir, "test", 20261028093000)
+	name := "20261028093000_test_migration.go"
+	before := snapshot(t, dir)[name]
+	edited := strings.Replace(before, "return nil", "// application body\n return tx.QueryRowContext(ctx, \"SELECT 1\").Err()", 1)
+	put(t, dir, name, []byte(edited))
+	put(t, dir, "00007_existing.sql", []byte("-- +goose Up\nSELECT 1;\n-- +goose Down\nSELECT 1;\n"))
+	put(t, dir, "20261028103000_next.sql", []byte("-- +goose Up\nSELECT 2;\n-- +goose Down\nSELECT 2;\n"))
+	if err := Fix(dir); err != nil {
+		t.Fatal(err)
+	}
+	after := snapshot(t, dir)
+	if after["00008_test_migration.go"] != edited || after["00009_next.sql"] == "" || !strings.Contains(after["register.go"], "migrationTest(8)") {
+		t.Fatal(after)
+	}
+	if err := Fix(dir); err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(after, snapshot(t, dir)) {
+		t.Fatal("repeated fix changed set")
+	}
+	if err := Create(dir, "new_sql", "sql"); err != nil {
+		t.Fatal(err)
+	}
+	if err := Fix(dir); err != nil {
+		t.Fatal(err)
+	}
+	if snapshot(t, dir)["00010_new_sql.sql"] == "" {
+		t.Fatal("creation failed to preserve sequence")
+	}
+}
+func TestPreflightRejections(t *testing.T) {
+	for _, tc := range []struct {
+		name    string
+		prepare func(*testing.T, string)
+		want    string
+	}{
+		{"duplicate", func(t *testing.T, d string) { put(t, d, "00001_one.sql", nil); put(t, d, "1_two.sql", nil) }, "duplicate version"},
+		{"invalid", func(t *testing.T, d string) { put(t, d, "-1_bad.sql", nil) }, "invalid version"},
+		{"zero", func(t *testing.T, d string) { put(t, d, "00000_bad.sql", nil) }, "positive int64"},
+		{"overflow", func(t *testing.T, d string) { put(t, d, "9223372036854775808_bad.sql", nil) }, "positive int64"},
+		{"order", func(t *testing.T, d string) { put(t, d, "2_two.sql", nil); put(t, d, "10_ten.sql", nil) }, "order disagreement"},
+		{"output-order", func(t *testing.T, d string) { put(t, d, "1_one.sql", nil); put(t, d, "20261028093000_two.sql", nil) }, "order disagreement"},
+		{"factory", func(t *testing.T, d string) {
+			seedGo(t, d, "example", 1)
+			p := filepath.Join(d, "00001_example_migration.go")
+			b, err := os.ReadFile(p)
+			if err != nil {
+				t.Fatal(err)
+			}
+			put(t, d, filepath.Base(p), bytes.ReplaceAll(b, []byte("version int64"), []byte("version int")))
+		}, "expected migrationExample"},
+		{"package", func(t *testing.T, d string) {
+			seedGo(t, d, "example", 1)
+			b := snapshot(t, d)["00001_example_migration.go"]
+			put(t, d, "00001_example_migration.go", []byte(strings.Replace(b, "package migrations", "package other", 1)))
+		}, "package migrations"},
+		{"stock", func(t *testing.T, d string) { put(t, d, "00001_example.go", []byte("package migrations")) }, "unsupported Go filename"},
+		{"missing-aggregate", func(t *testing.T, d string) {
+			seedGo(t, d, "example", 1)
+			if err := os.Remove(filepath.Join(d, "register.go")); err != nil {
+				t.Fatal(err)
+			}
+		}, "register.go missing"},
+		{"drift", func(t *testing.T, d string) {
+			seedGo(t, d, "example", 1)
+			b := snapshot(t, d)["register.go"]
+			put(t, d, "register.go", []byte(strings.Replace(b, "migrationExample(1)", "migrationExample(2)", 1)))
+		}, "drifted aggregate"},
+		{"handwritten", func(t *testing.T, d string) { put(t, d, "register.go", []byte("package migrations")) }, "drifted aggregate"},
+		{"destination-dir", func(t *testing.T, d string) {
+			put(t, d, "20261028093000_one.sql", nil)
+			if err := os.Mkdir(filepath.Join(d, "00001_one.sql"), 0o700); err != nil {
+				t.Fatal(err)
+			}
+		}, "regular file"},
+		{"sequential-overflow", func(t *testing.T, d string) {
+			put(t, d, "0000020261028093000_one.sql", nil)
+			put(t, d, "9223372036854775807_last.sql", nil)
+		}, "sequential version overflow"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := directory(t)
+			tc.prepare(t, dir)
+			before := snapshot(t, dir)
+			// Directories are checked separately; every file must survive preflight unchanged.
+			err := Fix(dir)
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("wanted %s: %v", tc.want, err)
+			}
+			if !reflect.DeepEqual(before, snapshot(t, dir)) {
+				t.Fatal("preflight failure changed files")
+			}
+		})
+	}
+}
+func TestCreateValidationAndCollisions(t *testing.T) {
+	for _, name := range []string{"", "../bad", "Test", "bad__name", "bad2", "bad-name"} {
+		if err := Create(directory(t), name, "go"); err == nil {
+			t.Fatalf("accepted %q", name)
+		}
+	}
+	if err := Create(directory(t), "valid", "other"); err == nil {
+		t.Fatal("accepted unsupported type")
+	}
+	dir := directory(t)
+	seedGo(t, dir, "example", 1)
+	before := snapshot(t, dir)
+	if err := Create(dir, "example", "go"); err == nil || !strings.Contains(err.Error(), "duplicate factory") {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(before, snapshot(t, dir)) {
+		t.Fatal("rejected create changed sources")
+	}
+}
+func TestSymlinksRejected(t *testing.T) {
+	dir := directory(t)
+	link := filepath.Join(directory(t), "link")
+	if err := os.Symlink(dir, link); err != nil {
+		t.Fatal(err)
+	}
+	if err := Fix(link); err == nil || !strings.Contains(err.Error(), "symlink") {
+		t.Fatal(err)
+	}
+	source := filepath.Join(directory(t), "source")
+	if err := os.WriteFile(source, nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink(source, filepath.Join(dir, "00001_one.sql")); err != nil {
+		t.Fatal(err)
+	}
+	if err := Fix(dir); err == nil || !strings.Contains(err.Error(), "regular file") {
+		t.Fatal(err)
+	}
+}
+func TestTimestampClassification(t *testing.T) {
+	for _, tc := range []struct {
+		v    int64
+		want bool
+	}{{1, false}, {19700101000000, false}, {19700101000001, true}, {19691231235959, false}, {20260230093000, false}, {20261028093000, true}} {
+		if got := timestamp(tc.v); got != tc.want {
+			t.Fatalf("%d timestamp=%v", tc.v, got)
+		}
+	}
+}
+func TestPartialPublicationAndManualRecovery(t *testing.T) {
+	dir := directory(t)
+	seedGo(t, dir, "example", 20261028093000)
+	before := snapshot(t, dir)
+	set, err := scan(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	item := set.migrations[0]
+	item.name = "00001_example_migration.go"
+	item.version = 1
+	aggregateData, err := aggregate([]migration{item})
+	if err != nil {
+		t.Fatal(err)
+	}
+	changes := []change{{source: set.migrations[0].name, dest: item.name, data: item.data}, {dest: "00002_next.sql", data: []byte("example")}, {dest: "register.go", replace: true, data: aggregateData}}
+	failure := errors.New("injected disk failure")
+	err = publish(set, changes, func(path string, data []byte) error {
+		if strings.HasSuffix(path, "00002_next.sql") {
+			if err := writeExclusive(path, []byte("partial")); err != nil {
+				t.Fatal(err)
+			}
+			return failure
+		}
+		return writeExclusive(path, data)
+	})
+	if !errors.Is(err, failure) || !strings.Contains(err.Error(), "completed [00001_example_migration.go removed 20261028093000_example_migration.go]") || !strings.Contains(err.Error(), "outstanding") || !strings.Contains(err.Error(), "restore complete source backup") {
+		t.Fatal(err)
+	}
+	if snapshot(t, dir)["00002_next.sql"] != "partial" {
+		t.Fatal("partial destination not reported/preserved")
+	}
+	if err := Fix(dir); err == nil {
+		t.Fatal("inconsistent interrupted set accepted")
+	}
+	// Manual recovery restores all paths, including untracked sources and aggregate.
+	for name := range snapshot(t, dir) {
+		if err := os.Remove(filepath.Join(dir, name)); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for name, data := range before {
+		put(t, dir, name, []byte(data))
+	}
+	if err := Fix(dir); err != nil {
+		t.Fatal(err)
+	}
+	if snapshot(t, dir)["00001_example_migration.go"] == "" {
+		t.Fatal("recovered fix failed")
+	}
+}
+func TestExclusiveDestinationAndAggregateRecheck(t *testing.T) {
+	dir := directory(t)
+	if err := Fix(dir); err != nil {
+		t.Fatal(err)
+	}
+	set, err := scan(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	put(t, dir, "00001_collision.sql", []byte("existing"))
+	err = publish(set, []change{{dest: "00001_collision.sql", data: []byte("replace")}}, writeExclusive)
+	if err == nil || snapshot(t, dir)["00001_collision.sql"] != "existing" {
+		t.Fatal("overwrote destination", err)
+	}
+	err = writeExclusive(filepath.Join(dir, "00001_collision.sql"), []byte("replace"))
+	if !errors.Is(err, os.ErrExist) {
+		t.Fatal(err)
+	}
+	err = publish(set, []change{{dest: "00002_ok.sql"}, {dest: "register.go", replace: true, data: []byte("new")}}, func(path string, data []byte) error {
+		put(t, dir, "register.go", []byte("editor changed"))
+		return writeExclusive(path, data)
+	})
+	if err == nil || !strings.Contains(err.Error(), "aggregate changed since preflight") || snapshot(t, dir)["register.go"] != "editor changed" {
+		t.Fatal(err)
+	}
+}
+
+func TestRemovalFailureStopsPublication(t *testing.T) {
+	dir := directory(t)
+	source := "20261028093000_one.sql"
+	if err := os.Mkdir(filepath.Join(dir, source), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	put(t, filepath.Join(dir, source), "block-removal", nil)
+	err := publish(sourceSet{dir: dir}, []change{{source: source, dest: "00001_one.sql", data: []byte("complete destination")}, {dest: "00002_later.sql"}}, writeExclusive)
+	if err == nil || !strings.Contains(err.Error(), "completed [00001_one.sql]") || !strings.Contains(err.Error(), "outstanding") {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "00002_later.sql")); !errors.Is(err, os.ErrNotExist) {
+		t.Fatal("continued after remove failure", err)
+	}
+	data, err := os.ReadFile(filepath.Join(dir, "00001_one.sql"))
+	if err != nil || string(data) != "complete destination" {
+		t.Fatalf("destination lost: %s %v", data, err)
+	}
+}

cmd/corestack-goose/main.go

@@ -0,0 +1,40 @@
+// Command corestack-goose authors provider-local SQL and Go migrations offline.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	urfavecli "github.com/urfave/cli/v3"
+	"go.auvem.com/corestack/cmd/corestack-goose/internal/authoring"
+)
+
+func main() {
+	if err := command().Run(context.Background(), os.Args); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func command() *urfavecli.Command {
+	root := &urfavecli.Command{Name: "corestack-goose", Usage: "Author migrations before deployment"}
+	for _, name := range []string{"create", "fix"} {
+		root.Commands = append(root.Commands, &urfavecli.Command{Name: name,
+			Flags: []urfavecli.Flag{&urfavecli.StringFlag{Name: "dir", Value: ".", Usage: "Migration directory (defaults to the current working directory)"}},
+			Action: func(_ context.Context, cmd *urfavecli.Command) error {
+				if name == "create" {
+					if cmd.NArg() != 2 {
+						return fmt.Errorf("usage: create [--dir <dir>] <name> sql|go")
+					}
+					return authoring.Create(cmd.String("dir"), cmd.Args().Get(0), cmd.Args().Get(1))
+				}
+				if cmd.NArg() != 0 {
+					return fmt.Errorf("usage: fix [--dir <dir>]")
+				}
+				return authoring.Fix(cmd.String("dir"))
+			},
+		})
+	}
+	return root
+}

cmd/corestack-goose/main_test.go

@@ -0,0 +1,148 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+func TestGeneratedConsumerAndArtifactBoundary(t *testing.T) {
+	root, err := filepath.Abs("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	dir, err := filepath.EvalSymlinks(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	execute := func(cwd, name string, args ...string) []byte {
+		t.Helper()
+		cmd := exec.CommandContext(t.Context(), name, args...)
+		cmd.Dir = cwd
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatalf("%s %v: %v\n%s", name, args, err, out)
+		}
+		return out
+	}
+	tool := filepath.Join(dir, "corestack-goose")
+	execute(root, "go", "build", "-o", tool, "./cmd/corestack-goose")
+	migrations := filepath.Join(dir, "migrations")
+	if err := os.Mkdir(migrations, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	osName := "windows"
+	if runtime.GOOS == "windows" {
+		osName = "linux"
+	}
+	for i, tc := range []struct{ name, kind string }{{"initial", "sql"}, {"test", "go"}, {"create_test", "go"}, {osName, "go"}} {
+		if i%2 == 0 {
+			execute(migrations, tool, "create", tc.name, tc.kind)
+			execute(migrations, tool, "fix")
+		} else {
+			execute(dir, tool, "create", "--dir", migrations, tc.name, tc.kind)
+			execute(dir, tool, "fix", "--dir", migrations)
+		}
+	}
+	execute(dir, tool, "fix", "--dir", migrations)
+	entries, err := os.ReadDir(migrations)
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantFiles := []string{"00001_initial.sql", "00002_test_migration.go", "00003_create_test_migration.go", "00004_" + osName + "_migration.go", "register.go"}
+	if len(entries) != len(wantFiles) {
+		t.Fatalf("migration files: %v", entries)
+	}
+	for i, entry := range entries {
+		if entry.Name() != wantFiles[i] {
+			t.Fatalf("migration file: got %s, want %s", entry.Name(), wantFiles[i])
+		}
+	}
+	entries, err = os.ReadDir(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(entries) != 2 || entries[0].Name() != "corestack-goose" || entries[1].Name() != "migrations" {
+		t.Fatalf("unexpected writes outside migration directory: %v", entries)
+	}
+	source, err := os.ReadFile("testdata/consumer/main.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "main.go"), source, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	module := fmt.Sprintf("module example.com/consumer\n\ngo 1.27.1\n\nrequire go.auvem.com/corestack v0.0.0\nreplace go.auvem.com/corestack => %s\n", filepath.ToSlash(root))
+	if err := os.WriteFile(filepath.Join(dir, "go.mod"), []byte(module), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	binary := filepath.Join(dir, "consumer")
+	execute(dir, "go", "build", "-mod=mod", "-o", binary, ".")
+	out := execute(dir, binary, filepath.Join(dir, "consumer.db"))
+	if !strings.Contains(string(out), "version=4 pending=false versions=1,2,3,4 fresh=true isolated-pending=true") {
+		t.Fatal(string(out))
+	}
+	// Decode package identities rather than guessing from substring matches in go list.
+	deps := execute(dir, "go", "list", "-deps", "-json", ".")
+	decoder := json.NewDecoder(bytes.NewReader(deps))
+	adapterFound := false
+	for decoder.More() {
+		var dep struct{ ImportPath string }
+		if err := decoder.Decode(&dep); err != nil {
+			t.Fatal(err)
+		}
+		if dep.ImportPath == "go.auvem.com/corestack/migrate/lifecycle" {
+			adapterFound = true
+		}
+		if dep.ImportPath == "go.auvem.com/corestack/cmd/corestack-goose" || strings.HasPrefix(dep.ImportPath, "go.auvem.com/corestack/cmd/corestack-goose/") {
+			t.Fatalf("production imports authoring: %s", dep.ImportPath)
+		}
+	}
+	if !adapterFound {
+		t.Fatal("production fixture did not import runtime adapter")
+	}
+	toolSymbols := execute(dir, "go", "tool", "nm", tool)
+	toolEntries := map[string]bool{}
+	for _, line := range strings.Split(string(toolSymbols), "\n") {
+		fields := strings.Fields(line)
+		if len(fields) >= 3 {
+			toolEntries[fields[len(fields)-1]] = true
+		}
+	}
+	for _, entry := range []string{"github.com/pressly/goose/v3.CreateWithTemplate", "go.auvem.com/corestack/cmd/corestack-goose/internal/authoring.Create", "go.auvem.com/corestack/cmd/corestack-goose/internal/authoring.Fix"} {
+		if !toolEntries[entry] {
+			t.Fatalf("standalone authoring entrypoint missing: %s", entry)
+		}
+	}
+	runtimeFound := false
+	symbols := execute(dir, "go", "tool", "nm", binary)
+	for _, line := range strings.Split(string(symbols), "\n") {
+		fields := strings.Fields(line)
+		if len(fields) < 3 {
+			continue
+		}
+		symbol := fields[len(fields)-1]
+		if symbol == "go.auvem.com/corestack/migrate/lifecycle.Commands" {
+			runtimeFound = true
+		}
+		if strings.HasPrefix(symbol, "go.auvem.com/corestack/cmd/corestack-goose/") {
+			t.Fatalf("authoring symbol linked: %s", symbol)
+		}
+		for _, entry := range []string{"Create", "CreateWithTemplate", "Fix", "SetSequential"} {
+			full := "github.com/pressly/goose/v3." + entry
+			if symbol == full || strings.HasPrefix(symbol, full+".") {
+				t.Fatalf("upstream authoring entrypoint linked: %s", symbol)
+			}
+		}
+	}
+	if !runtimeFound {
+		t.Fatal("runtime command symbol missing from production executable")
+	}
+	t.Log("standalone create/fix; unchanged generated SQL+safe-suffix Go compiled and applied; runtime dependency identities and linker symbols verified")
+}

cmd/corestack-goose/testdata/consumer/main.go

@@ -0,0 +1,90 @@
+// Command consumer verifies generated registrations and the production boundary.
+package main
+
+import (
+	"context"
+	"database/sql"
+	"embed"
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+
+	"example.com/consumer/migrations"
+	"github.com/pressly/goose/v3"
+	urfavecli "github.com/urfave/cli/v3"
+	"go.auvem.com/corestack/lifecycle"
+	"go.auvem.com/corestack/lifecycle/cli"
+	"go.auvem.com/corestack/migrate"
+	adapter "go.auvem.com/corestack/migrate/lifecycle"
+	_ "modernc.org/sqlite"
+)
+
+//go:embed migrations
+var files embed.FS
+
+func main() {
+	ctx := context.Background()
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	var db *sql.DB
+	dbModule := lifecycle.Module{Name: "database", Setup: func(context.Context) error { var err error; db, err = sql.Open("sqlite", os.Args[1]); return err }, Teardown: func(context.Context) error { return db.Close() }}
+	resolver := func(context.Context) (*goose.Provider, error) {
+		return migrate.New(db, goose.DialectSQLite3, files, "migrations", logger, migrations.GoMigrations()...)
+	}
+	root := &urfavecli.Command{Name: "consumer", Commands: []*urfavecli.Command{adapter.Commands(lifecycle.Config{Logger: logger}, []lifecycle.Module{dbModule}, resolver)}}
+	code, err := cli.Run(ctx, root, []string{"consumer", "migrate", "up"})
+	must(err)
+	if code != 0 {
+		panic(code)
+	}
+	db, err = sql.Open("sqlite", os.Args[1])
+	must(err)
+	defer db.Close()
+	p, err := resolver(ctx)
+	must(err)
+	version, err := p.GetDBVersion(ctx)
+	must(err)
+	if version != 4 {
+		panic(version)
+	}
+	pending, err := p.HasPending(ctx)
+	must(err)
+	if pending {
+		panic("pending after apply")
+	}
+	statuses, err := p.Status(ctx)
+	must(err)
+	if len(statuses) != 4 {
+		panic(len(statuses))
+	}
+	for i, status := range statuses {
+		if status.Source.Version != int64(i+1) || status.State != goose.StateApplied {
+			panic(status)
+		}
+	}
+	a, b := migrations.GoMigrations(), migrations.GoMigrations()
+	if len(a) != 3 || len(b) != 3 {
+		panic("missing safe-suffix Go migrations")
+	}
+	for i := range a {
+		if a[i] == b[i] || a[i].Version != int64(i+2) || b[i].Version != int64(i+2) {
+			panic("registration/version isolation")
+		}
+	}
+	isolatedDB, err := sql.Open("sqlite", ":memory:")
+	must(err)
+	defer isolatedDB.Close()
+	isolated, err := migrate.New(isolatedDB, goose.DialectSQLite3, files, "migrations", logger, migrations.GoMigrations()...)
+	must(err)
+	pending, err = isolated.HasPending(ctx)
+	must(err)
+	if !pending {
+		panic("provider isolation")
+	}
+	fmt.Println("version=4 pending=false versions=1,2,3,4 fresh=true isolated-pending=true")
+}
+func must(err error) {
+	if err != nil {
+		panic(err)
+	}
+}

docs/adr/20261023T214738672Z-adopt-a-checked-format-for-adrs-and-implementation-plans.md

@@ -80,3 +80,5 @@ The format is specified in [docs-format](/docs/docs-format.md). It uses the MADR
 ## More Information
 
 MADR 4: https://adr.github.io/madr/. The specification is [docs-format](/docs/docs-format.md); the implementation lands in the same pull request that records this decision.
+
+Note (2026-10-28): the CLI was renamed from `docs` (`cmd/docs`) to `corestack-docs` (`cmd/corestack-docs`) so `go install` does not produce an ambiguous `docs` binary. The decision is unchanged.

docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md

@@ -49,3 +49,7 @@ This decision establishes the boundary before the planned packages are added. Th
 * Heavy-dependency and independently versioned packages avoid overlapping ownership of an import path with older root-module versions.
 * Each nested module needs its own dependency maintenance, checks, and prefixed release tags. That bookkeeping is reserved for packages that need the boundary.
 * Root-module consumers share version bumps even when only another core package changes. Moving a shipped root package into a nested module later still requires coordinated releases and consumer upgrades.
+
+## More Information
+
+Note (2026-10-28): `cmd/docs` was renamed to `cmd/corestack-docs`; read references to `cmd/docs` above as `cmd/corestack-docs`. The decision is unchanged.

docs/adr/20261028T210148136Z-run-native-urfave-commands-inside-selected-lifecycle-modules.md

@@ -0,0 +1,104 @@
+---
+title: "Run native urfave/cli commands inside selected lifecycle modules"
+date: 2026-10-28
+status: accepted
+implementation: implemented
+summary: Use native urfave/cli commands and flags with thin lifecycle action adapters and an explicit exit boundary.
+tags:
+  - lifecycle
+  - cli
+supersedes: []
+superseded_by: []
+related:
+  - /docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md
+  - /docs/adr/20261027T184038082Z-supervise-module-lifecycle-and-managed-workers-within-one-shutdown-budget.md
+tracking:
+  - https://gitea.auvem.com/corestack/go/issues/8
+implemented_by:
+  - https://gitea.auvem.com/corestack/go/pulls/16
+---
+
+# Run native urfave/cli commands inside selected lifecycle modules
+
+## Context and Problem Statement
+
+[Issue 8](https://gitea.auvem.com/corestack/go/issues/8) needs command-specific resource setup, signal-aware work, cleanup on completion, automatic help and distinct usage failures. The owner selected `github.com/urfave/cli/v3` v3.14.0 for every command, subcommand, flag and help surface; callers declare native flags. One-offs skip module services; serve runs them. The root-module boundary and lifecycle ordering, cancellation and shared shutdown budget already stand. This clean-room implementation uses no go-toolkit/appcli source.
+
+The owner accepted the three-function API, adapter-owned signal subscription, private invocation App boundary, native validation limitations and generated-help diagnostic/exit exceptions after independent review. The corrected decision was verified at [commit 1b756511](https://gitea.auvem.com/corestack/go/commit/1b7565113c20757c8a049fe44e9a035cf72fd4b7), with R1–R3 addressed and no blocking or major findings; the implementation dispatch explicitly records owner acceptance. Implementation is published in [PR 16](https://gitea.auvem.com/corestack/go/pulls/16) after independent standard and fresh high implementation reviews with no outstanding findings.
+
+## Considered Options
+
+* Native urfave/cli command tree with action adapters: shares native flags/help and existing lifecycle coordination; adds only selection, signal ownership and exit classification.
+* A new command/flag schema wrapping urfave/cli: could centralize declarations, but duplicates its API and increases conversion and maintenance obligations without a requested capability.
+* Standard-library flag parsing: smaller dependency graph, but would require our own subcommands/help and contradict the owner's dependency choice.
+* Per-binary urfave/cli and lifecycle wiring: no library API to maintain, but repeats signal cleanup, one-off service suppression and exit policy in each consumer.
+
+## Decision Outcome
+
+Choose the first option in root package `go.auvem.com/corestack/lifecycle/cli`, with no lifecycle core change. Import urfave/cli as `urfavecli` to distinguish its native types from this package. The entire new public surface is:
+
+```go
+// Run executes a caller-owned native tree and returns its process code and error.
+// It prints diagnostics but never exits the process; args includes argv[0].
+func Run(ctx context.Context, cliRoot *urfavecli.Command, args []string) (int, error)
+
+// Serve returns an action running exactly these modules, including their services.
+func Serve(config lifecycle.Config, modules []lifecycle.Module) urfavecli.ActionFunc
+
+// Action returns a one-off action using exactly these modules, without services.
+func Action(config lifecycle.Config, modules []lifecycle.Module,
+    fn urfavecli.ActionFunc) urfavecli.ActionFunc
+```
+
+The functions capture module declarations in their supplied order; callers list every needed module explicitly. There is no registry, name lookup, implicit dependency expansion or DAG. Callbacks close over caller-owned resource handles populated by Setup; the one-off receives the selected native command for parsed flag access. There is no public App, worker method, configuration framework or flag/environment facade. Empty module lists are valid. Nil one-off functions, nil Run context/root, invalid lifecycle config and invalid selected modules are runtime errors before resource acquisition; validate every selected declaration before starting setup. Bindings do not start work until invoked. A command tree and its mutable resources have one execution owner; construct fresh trees for independent runs and do not mutate captured declarations concurrently.
+
+`Serve` constructs a fresh lifecycle App, registers selected modules and calls its Run. `Action` copies selected modules with Run cleared, then registers an internal final module with no-op Setup/Teardown and the command function as Run. Choose its nonempty name by checking all selected names and varying a private suffix until unused; no public module name is reserved. All selected setups precede work; returning from the one-off leaves no selected services to keep the App alive. Lifecycle closes admission, cancels the callback context and performs reverse cleanup. No success sentinel, cancellation-error filtering, parent-context cancellation or second shutdown timer is added. Action failures are lifecycle failures and preserve their chains. Core setup failure/partial cleanup, parent cancellation, second signal, abandonment and joined-error behavior remain authoritative. Selected module services cannot run during one-offs. The invocation App is private: modules or callbacks that need its App.Go cannot obtain it through these adapters and are incompatible with this narrow API. Capturing another App does not confer this invocation's supervision. Supported modules manage resources and optional services without that access; raw goroutines remain caller-owned and outside managed-worker completion. Exposing worker access would require a separate owner decision.
+
+Each invoked adapter subscribes to SIGINT/SIGTERM using a private channel buffered for two signals when Config.Signals is nil, and defers signal.Stop. With a supplied channel, subscription, filtering and cleanup remain caller-owned as in lifecycle; a closed supplied channel disables signals. The adapter never closes either channel. No subscription or relay goroutine is needed during parsing/help. Lifecycle alone consumes/counts signals and cancels command work; do not also use signal.NotifyContext, which would turn graceful Ctrl-C into parent cancellation. After adapter return, subscription cleanup restores the prior process signal behavior; the caller owns process exit and abandoned resources.
+
+Run owns the tree's ExitErrHandler, OnUsageError and CommandNotFound hooks, rejecting conflicting caller hooks as runtime configuration errors rather than silently overriding them. It installs a non-exiting root handler and usage/not-found handling on the caller-declared tree before urfave/cli runs; no urfave/cli package globals are changed. CommandNotFound returns void, so its callback records a local usage cause for this invocation; Run combines that cause with the native result even when urfave/cli returns nil, retaining any simultaneous runtime error. Native actions, Before/After, ArgValidator, flags, arguments and help templates remain caller declarations. Hooks outside the lifecycle action are outside its signal/shutdown/resource guarantee: use them for prompt validation, and put resource work inside selected modules or the adapted action. Leave group Actions unset for native group help/unknown-command handling; positional arguments on actionable leaves follow native urfave/cli declarations and validators.
+
+The exit mapping is:
+
+| Result | Code |
+| --- | --- |
+| No returned or locally recorded error, including valid help, empty group help, normal completion or graceful first signal with successful cleanup | 0 |
+| Lifecycle setup/action/service/teardown error, parent cancellation, budget/second-signal abandonment, or other unclassified native error | 1 |
+| Native OnUsageError path on caller-declared commands (invalid/missing flag value, required flag/argument, mutually exclusive flags, native argument parsing), or locally recorded unknown command/help topic | 2 |
+| Parse failure in a urfave/cli-generated help command, including its aliases | 1 |
+| Explicit `urfavecli.Exit(err, 2)` from pre-lifecycle caller validation | 2 |
+
+A lifecycle failure always remains code 1, including action-returned ExitCoder values and joins containing cleanup failures; do not infer success by matching context.Canceled. Non-2 ExitCoder values outside lifecycle normalize to 1; an error never becomes success through ExitCode 0. Use private provenance wrappers for usage and lifecycle failures. Native After hooks may aggregate failures in urfavecli.MultiError, whose Errors() children are invisible to standard traversal. A small private bridge traverses both standard Unwrap forms and native MultiError.Errors(), recursively exposing children through Unwrap() []error while also retaining each original error/wrapper as a traversal child. It delegates Error() to the original rather than duplicating its text. Do not flatten or replace native wrappers: errors.Is must still match their identity and errors.As must still find their types, alongside nested causes and private markers.
+
+Classify every semantic branch, carrying its usage/lifecycle provenance through wrappers and aggregates; aggregate containers are not extra unclassified failures. Any lifecycle branch or unclassified runtime branch dominates usage branches, including an Exit(err, 2) action plus failing After, usage plus runtime After, and nested parent/leaf After failures. Looking up only the first ExitCoder or marker is insufficient. Run returns the traversable error after cleanup and emits at most one adapter-owned final diagnostic to cliRoot.ErrWriter. This is not a single total diagnostic guarantee: native help parse handling and caller hooks may also print. Usage hooks request relevant native help through urfave/cli's Show*Help functions. Native help goes to cliRoot.Writer and diagnostics to cliRoot.ErrWriter, defaulting to stdout/stderr; callers may supply writers there. No logger/writer registry or logging policy is added. Rendering retains urfave/cli's own writer-error behavior, without promising stronger delivery guarantees.
+
+Accepted owner exception: urfave/cli creates generated help nodes lazily after the pre-run hook walk; their parse failures bypass OnUsageError. Accept code 1 with native diagnostics for malformed generated help invocations (root, nested and aliases); Run's final diagnostic may repeat the native error. Valid help remains code 0, and unknown help topics remain code 2 through the recorded CommandNotFound cause. Uniform code 2 and one total diagnostic would require separate feasibility evidence and owner approval. Do not initialize by reparsing, copy native parser/help code, or detect diagnostics through error strings.
+
+urfave/cli v3.14.0 does not expose all validation errors through OnUsageError: invalid environment values in Flag.PostParse bypass it, as do ArgValidator and flag-action errors. Unclassified errors from those paths are code 1. Callers needing code 2 from custom validators return `urfavecli.Exit(err, 2)` before lifecycle entry; native environment-source failures remain code 1 unless the caller validates explicitly. Do not inspect error strings, reparse arguments, wrap every flag type or promise universal parse/runtime discrimination.
+
+A schematic consumer uses ordinary Go wiring; the implementation Example must be executable and show both modes:
+
+```go
+cfg := lifecycle.Config{Logger: logger}
+cliRoot := &urfavecli.Command{Name: "app", Commands: []*urfavecli.Command{
+    {Name: "serve", Action: cli.Serve(cfg, []lifecycle.Module{database, server})},
+    {Name: "inspect", Flags: []urfavecli.Flag{&urfavecli.BoolFlag{Name: "verbose"}},
+        Action: cli.Action(cfg, []lifecycle.Module{database},
+            func(ctx context.Context, cmd *urfavecli.Command) error {
+                return inspect(ctx, db, cmd.Bool("verbose"))
+            })},
+}}
+code, err := cli.Run(context.Background(), cliRoot, os.Args)
+_ = err // already diagnosed; available for inspection by an embedding caller
+os.Exit(code) // caller-owned process boundary, after all adapter cleanup
+```
+
+The dependency belongs in root go.mod/go.sum under the accepted boundary ADR. At v3.14.0 `go list -deps` reports no nonstandard production package except urfave/cli itself; its [module requirements](https://github.com/urfave/cli/blob/v3.14.0/go.mod) are for tests, with YAML already present here. This is a small CLI dependency, not a reason to introduce a nested module. The native exported types deliberately couple consumers to urfave/cli v3; we own integration tests when upgrading it.
+
+### Consequences
+
+* Scope is one PR, approximately 200–350 production lines plus focused tests and docs: new lifecycle/cli/cli.go (package/public comments and adapters), cli_test.go, example_test.go, root go.mod/go.sum and this ADR. No existing callers, fixtures, lifecycle core, migration package, release/config framework or GUI changes are anticipated. The reusable migration command belongs exclusively to issue 9.
+* There are no persistence writers, migrations, remote services, new auth boundaries or persistent workers. Active work consists of lifecycle-owned callbacks, its existing shutdown deadline, and a temporary OS signal subscription only while an adapted action executes. Callers own command output, cooperative callbacks, partial setup cleanup and eventual process exit; importing the package starts nothing.
+* Tests must prove selected-only setup and registration/reverse order, no one-off services, teardown on success/failure, serve services, fixed code mapping with preserved typed causes and mixed cleanup errors, native flags/subcommands/help without module setup, invalid environment classification, injected first/second signals, parent cancellation and the shared deadline. Test with injected channels and explicitly release blocked goroutines; do not send real signals. Exercise native callbacks returning ExitCoder without process exit. Add focused action/lifecycle-plus-After, usage-plus-runtime-After and nested After tests asserting code 1, original wrapper identity/types and all child causes. Cover root/nested generated help parse errors and aliases (code 1/native diagnostics), valid help (code 0), unknown commands/help topics returning native nil (code 2), and synthetic-name collisions without reserving names.
+* Native [aggregation and parse handling](https://github.com/urfave/cli/blob/v3.14.0/command_run.go), [MultiError API](https://github.com/urfave/cli/blob/v3.14.0/errors.go) and [lazy help setup](https://github.com/urfave/cli/blob/v3.14.0/command_setup.go) establish integration obligations; they do not alone verify adapter behavior. Retain these cases in upgrade tests. The simpler alternative is narrower hook support; retaining native hooks with a small traversal bridge preserves the requested cause guarantees. Accepting the generated-help exception avoids a second parser/help subsystem.
+* Independent ADR review and owner acceptance are complete. The three adapters, focused tests, executable serve/inspect example and public documentation are implemented in [PR 16](https://gitea.auvem.com/corestack/go/pulls/16). Independent standard and fresh high implementation reviews of `e0673630d5876ece6f2419b4b63ce9f643d5a082` found no Blocking, Major or Minor issues; required local build, vet, race, lint, docs, TODO and formatting checks passed on the reviewed code. Local PostgreSQL integrations skipped without DSNs; final-head CI, PostgreSQL integration evidence and merge readiness are tracked in the PR. Publication is complete, and this record was reconciled against latest `origin/main` at `f0439000cbed0ffdccad0521748bcf1738af4a0c` plus the PR; this records delivery evidence, not CI success, merge or release.

docs/adr/20261028T215512402Z-separate-migration-authoring-tools-from-lifecycle-runtime-adapters.md

@@ -0,0 +1,107 @@
+---
+title: "Separate migration authoring tools from lifecycle runtime adapters"
+date: 2026-10-28
+status: accepted
+implementation: implemented
+summary: Keep startup and native migration commands in a thin lifecycle adapter and source creation and reconciliation in a standalone development tool.
+tags:
+  - migrations
+  - lifecycle
+  - cli
+supersedes: []
+superseded_by: []
+related:
+  - /docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md
+  - /docs/adr/20261027T184038082Z-supervise-module-lifecycle-and-managed-workers-within-one-shutdown-budget.md
+  - /docs/adr/20261028T210148136Z-run-native-urfave-commands-inside-selected-lifecycle-modules.md
+tracking:
+  - https://gitea.auvem.com/corestack/go/issues/9
+implemented_by:
+  - https://gitea.auvem.com/corestack/go/pulls/18
+---
+
+# Separate migration authoring tools from lifecycle runtime adapters
+
+## Context and Problem Statement
+
+[Issue 9](https://gitea.auvem.com/corestack/go/issues/9) needs caller-selected apply/require startup policy, reusable database-only migration commands, and SQL/Go creation and timestamp-to-sequential reconciliation without manually adapting registrations. The owner selected a standalone `cmd/corestack-goose` tool, available through go install/go run without tags, with authoring code absent from production applications. Existing `migrate.New` disables global registration; stock Goose Go output registers through init and cannot satisfy that contract.
+
+Preserve the accepted lifecycle ordering, reverse cleanup, caller-owned resources, native urfave/cli commands and shutdown budget. Keep migrate usable without lifecycle.
+
+## Considered Options
+
+* Application-specific runtime wiring and manually adapted Goose output: least library code, but misses reusable commands and unchanged generated-Go registration.
+* Application build tags for authoring: complicates consumer builds; declined in favor of a standalone tool.
+* Thin runtime adapter and standalone authoring tool with a generated registration aggregate: meets the artifact boundary with a bounded source convention.
+* Rewrite arbitrary Go registrations or infer them through globals/init: broader compatibility and parser/state cost than required; reject unsupported layouts instead.
+
+## Decision Outcome
+
+Choose the third option in the root module, with no new dependencies or lifecycle core changes. The owner accepted this decision, including `up-to` and single-step `down`, after independent ADR review. See [PR 18](https://gitea.auvem.com/corestack/go/pulls/18) for implementation and review evidence.
+
+Runtime lives in `go.auvem.com/corestack/migrate/lifecycle` (examples alias migratelifecycle), importing migrate's dependencies and `lifecycle/cli`; neither migrate nor lifecycle imports it. Authoring lives only in `cmd/corestack-goose` and its internal implementation, never imported by runtime packages or generated consumer code.
+
+The public runtime surface is:
+
+```go
+type Policy string
+const (
+    Apply Policy = "apply"
+    Require Policy = "require"
+)
+func Module(name string, policy Policy,
+    provider func(context.Context) (*goose.Provider, error)) (lifecycle.Module, error)
+func Commands(config lifecycle.Config, modules []lifecycle.Module,
+    provider func(context.Context) (*goose.Provider, error)) *urfavecli.Command
+```
+
+Module validates name, policy and nonnil resolver without resolving. Setup resolves a nonnil provider after earlier database setup, then calls Up for Apply or HasPending for Require. Pending migrations fail setup before later modules/services; errors retain contextual causes. Zero/unknown policy fails. The module has no Run and no-op Teardown: the database module owns partial acquisition cleanup and closing. Never call Provider.Close, which closes the supplied database in Goose v3.29.0.
+
+Ordinary closures bind resources: database Setup opens db; the resolver calls migrate.New with db, embedded files, dialect, logger and `migrations.GoMigrations()...`. Register database before migration and dependent services. Declaration starts nothing. Each resolution constructs fresh Go registrations, without a registry, stored context, global mutable state or init. Resolution acquires no independently owned resource; a resolver that does must clean up its failure locally.
+
+Commands returns a fresh native `migrate` group with these leaves:
+
+| Leaf | Goose provider method |
+| --- | --- |
+| `up` | Up |
+| `up-to <version>` | UpTo |
+| `down` | Down (one migration) |
+| `down-to <version>` | DownTo |
+| `status` | Status |
+
+Each uses `lifecycle/cli.Action` over exactly the supplied database modules, suppressing services and excluding the startup migration module and unrelated modules. After setup, resolve the provider and invoke Goose directly. Nil resolver/provider and construction failures are runtime errors. Existing adapter validation, cancellation, reverse cleanup, signals and exit classification apply. Use fresh trees/resource bindings for independent invocations; concurrent mutation/reuse is unsupported.
+
+Help and invalid arguments must not open the database. Native ArgValidator enforces no positional arguments for up/down/status and exactly one nonnegative decimal int64 for up-to/down-to; reject negative, overflow, missing and extra values with `urfavecli.Exit(err, 2)` before lifecycle entry. Zero behavior follows Goose, including DownTo(0) rolling back all migrations. Leave the group Action unset for native help/not-found behavior; existing generated-help exceptions apply. Status writes a version/state/source table to the selected command Writer and propagates write errors. Other leaves use configured Goose logging; no extra output/config schema is added.
+
+Require is a point-in-time check, not a startup transaction or deployment lock; HasPending takes no Goose session lock. Require and status can initialize the version table: neither runs migration bodies nor promises read-only database access. Apply and runtime writes retain migrate.New's PostgreSQL session lock and external serialization for other dialects. No new worker, retry or lock is introduced.
+
+Install the standalone tool with `go install go.auvem.com/corestack/cmd/corestack-goose@<release>` or use `go run go.auvem.com/corestack/cmd/corestack-goose ...` from the consumer module with its selected dependency version:
+
+```text
+corestack-goose create [--dir <dir>] <name> sql|go
+corestack-goose fix [--dir <dir>]
+```
+
+Both commands default to the current working directory; `--dir` overrides it. The directory must exist. Generated Go uses package migrations and names restricted to lowercase ASCII words separated by underscores; reject duplicate identifiers before writes. Create stages Goose CreateWithTemplate output using stock SQL/custom Go templates. SQL filenames stay unchanged; Go appends `_migration` to produce `<version>_<name>_migration.go`, preventing allowed names such as test, create_test, linux or windows from triggering build filtering. Factory identifiers derive from the logical name, excluding that suffix; create and fix agree. Authoring is offline with a fixed source format and no Goose global registration.
+
+Each generated Go file declares an unexported factory taking a version and returning a fresh `*goose.Migration` with editable transactional up/down bodies. Tool-owned `register.go` exports `GoMigrations() []*goose.Migration`, returning fresh Migration/GoFunc values and a new slice of factory calls with literal versions matching filename prefixes. Maintain this sole explicit registration-version surface even for SQL-only sets (empty slice). Consumer output imports only Goose and the standard library; applications pass registrations to migrate.New. The embedded-directory requirement applies to Go-only sets too.
+
+Fix scans SQL and house Go filenames together, preserves sequential IDs, sorts timestamp IDs numerically, and allocates after the highest sequential ID with at least five-digit padding. Use Goose's timestamp classification (valid UTC timestamp after Unix epoch); reject invalid/duplicate/overflowed IDs and numeric/lexical ordering disagreement. One mapping drives filename changes and aggregate literals; factory names remain version-independent. Preserve migration bytes and bodies. Validate factory identity/signature and package agreement. Replace register.go only with its owned marker and canonical agreement with current filenames/factories. Reject handwritten/drifted layouts with actionable diagnostics.
+
+Create and fix preflight the complete planned set: regular files/directories rather than symlink paths, names, version mappings, identifiers, aggregate agreement, destination collisions and output syntax. Open new destinations exclusively, including renamed copies. Replace existing register.go only when tool-owned and unchanged since preflight. Require a single authoring process and no concurrent editor mutation; this provides no isolation against racing writers.
+
+There is no atomic multi-file guarantee. Stage first, fully publish each destination before removing its source, and stop on the first write/remove failure, reporting completed/outstanding paths. Interruption may leave duplicates, aggregate mismatches or temporary files; no automatic retry or rollback. Before fix, commit or separately back up the complete source set, including untracked migrations and tracked edits; ordinary restore cannot recover untracked files or unsaved changes. On failure inspect reported paths and restore from that commit/backup before retrying; preflight rejects inconsistent sets. This manual recovery needs no persistent journal. Fix changes source IDs, never database history: use it before IDs reach a shared database; preserve deployed IDs and add migrations afterward. The tool cannot prove deployment history.
+
+### Consequences
+
+* Goose retains runtime schema/version history. Development-only source writers create files, copy/remove reconciled sources and replace the owned aggregate. Imports start nothing; no persistent worker or new auth boundary is introduced.
+* The fixed source convention avoids arbitrary Go rewriting and automated crash recovery, at the cost of rejecting unsupported layouts and requiring manual source restoration after failures. Consumer guidance lives in [migrate/README.md](/migrate/README.md).
+* Delivery checks cover Apply/Require startup ordering; all five leaves against SQLite; lifecycle, context, error and Writer failures; help/usage without database setup; version validation and Goose zero-target behavior.
+* Build and test the standalone tool and runtime-only production fixture separately. Production dependencies and binary symbols must exclude this project's authoring package and file-writing entry points; upstream Goose authoring source may remain in the dependency.
+* The generated-consumer flow creates SQL/Go, fixes IDs, compiles unedited registrations (including build-sensitive names), applies to SQLite and verifies versions, pending state and provider isolation. Safety tests cover collisions, unsupported/drifted aggregates, duplicate/mixed IDs, repeated fix and injected partial-write failure followed by source restoration.
+
+## More Information
+
+Pinned Goose v3.29.0 [CreateWithTemplate](https://github.com/pressly/goose/blob/v3.29.0/create.go) supplies templates and exclusive creation but can leave partial output, motivating staging. Its [Fix](https://github.com/pressly/goose/blob/v3.29.0/fix.go) lacks aggregate maintenance and no-overwrite guarantees, so only creation is reused. [NewGoMigration](https://github.com/pressly/goose/blob/v3.29.0/migration.go) and [provider options](https://github.com/pressly/goose/blob/v3.29.0/provider_options.go) support fresh provider-local registration. [Provider operations](https://github.com/pressly/goose/blob/v3.29.0/provider.go) and [initialization](https://github.com/pressly/goose/blob/v3.29.0/provider_run.go) establish ownership and version-table behavior. Native [argument validation](https://github.com/urfave/cli/blob/v3.14.0/command_run.go) precedes Action.
+
+Reconciled against `origin/main` at `0034a561ba5eade4ee6fb29436c76e4e34fa3a56` plus [PR 18](https://gitea.auvem.com/corestack/go/pulls/18). The PR records independent reviews, passing local build/vet/race/pinned-lint/docs/TODO/format checks, standalone install/run, generated-consumer SQLite flow and production artifact checks. PostgreSQL integrations were skipped locally without DSNs; CI, merge and release status remain in the PR.

docs/adr/README.md

@@ -26,4 +26,4 @@ Use `write-adr` and `review-adr` when available: they guide reasoning while defe
 
 ## Reconcile before final review and merge
 
-Compare the latest target branch plus the PR with the affected decisions and plans, not just the working branch's previous metadata. Update ADR implementation state and `implemented_by` with the real PR URL when delivery evidence supports it. Close finished plans with completion evidence and an Outcome; keep work active when scope remains. Never invent PR links, completed checks, owner acceptance, or delivery evidence. Run `docs check` using the pinned documentation command in the root AGENTS.md after reconciliation.
+Compare the latest target branch plus the PR with the affected decisions and plans, not just the working branch's previous metadata. Update ADR implementation state and `implemented_by` with the real PR URL when delivery evidence supports it. Close finished plans with completion evidence and an Outcome; keep work active when scope remains. Never invent PR links, completed checks, owner acceptance, or delivery evidence. Run `corestack-docs check` using the pinned documentation command in the root AGENTS.md after reconciliation.

docs/docs-format.md

@@ -1,6 +1,6 @@
 # Docs format
 
-This is the complete specification for architecture decision records (ADRs) and implementation plans checked by `docs check`. It is standalone: a file that follows this document is valid without running the tool. The words MUST, MUST NOT and MAY are used in their RFC 2119 sense.
+This is the complete specification for architecture decision records (ADRs) and implementation plans checked by `corestack-docs check`. It is standalone: a file that follows this document is valid without running the tool. The words MUST, MUST NOT and MAY are used in their RFC 2119 sense.
 
 The ADR body uses the [MADR 4](https://adr.github.io/madr/) layout; `Consequences` is mandatory. The frontmatter, naming and cross-reference rules are specific to this format.
 
@@ -135,7 +135,7 @@ Heading text is the raw source after the `#` markers, trimmed, with any closing
 
 ### 6.3 Placeholders
 
-A record is invalid if it still contains the exact marker `{{docs:todo}}` anywhere outside code, including inside a frontmatter string value or list item (write it quoted there: `summary: "{{docs:todo}}"`). A list item equal to the marker reports only the marker error, not the format error for its key. `docs new` writes this marker into each field and section it leaves for you to fill; replace it with content. No other text is treated as a placeholder, so words like TODO or TBD are fine. To mention the marker itself, put it in inline or fenced code.
+A record is invalid if it still contains the exact marker `{{docs:todo}}` anywhere outside code, including inside a frontmatter string value or list item (write it quoted there: `summary: "{{docs:todo}}"`). A list item equal to the marker reports only the marker error, not the format error for its key. `corestack-docs new` writes this marker into each field and section it leaves for you to fill; replace it with content. No other text is treated as a placeholder, so words like TODO or TBD are fine. To mention the marker itself, put it in inline or fenced code.
 
 ## 7. References and links
 
@@ -156,9 +156,9 @@ URL:
 
 Always allowed in body prose only: in-page anchors (`#section`) and `mailto:` links. Any other scheme is rejected.
 
-## 8. What `docs check` reports
+## 8. What `corestack-docs check` reports
 
-`docs check [--root DIR]` checks every record under `DIR` (default: the working directory) and prints one line per problem:
+`corestack-docs check [--root DIR]` checks every record under `DIR` (default: the working directory) and prints one line per problem:
 
 ```
 path:line: message

go.mod

@@ -9,6 +9,7 @@ require (
 	github.com/pressly/goose/v3 v3.29.0
 	github.com/stephenafamo/bob v0.50.0
 	github.com/stephenafamo/scan v0.9.0
+	github.com/urfave/cli/v3 v3.14.0
 	github.com/yuin/goldmark v1.8.6
 	go.yaml.in/yaml/v3 v3.0.5
 	modernc.org/sqlite v1.60.1

go.sum

@@ -141,6 +141,8 @@ github.com/tklauser/go-sysconf v0.3.12 h1:0QaGUFOdQaIVdPgfITYzaTegZvdCjmYO52cSFA
 github.com/tklauser/go-sysconf v0.3.12/go.mod h1:Ho14jnntGE1fpdOqQEEaiKRpvIavV0hSfmBq8nJbHYI=
 github.com/tklauser/numcpus v0.6.1 h1:ng9scYS7az0Bk4OZLvrNXNSAO2Pxr1XXRAPyjhIx+Fk=
 github.com/tklauser/numcpus v0.6.1/go.mod h1:1XfjsgE2zo8GVw7POkMbHENHzVg3GzmoZ9fESEdAacY=
+github.com/urfave/cli/v3 v3.14.0 h1:a8414NQlHJs0c/iBsulKLzlES0n/lEAskbL2LKpU4/s=
+github.com/urfave/cli/v3 v3.14.0/go.mod h1:vXn6HxPNccJSzQr2QvwVncOKrgYGIHU0HY5h8B2nQj4=
 github.com/wasilibs/go-pgquery v0.0.0-20250409022910-10ac41983c07 h1:mJdDDPblDfPe7z7go8Dvv1AJQDI3eQ/5xith3q2mFlo=
 github.com/wasilibs/go-pgquery v0.0.0-20250409022910-10ac41983c07/go.mod h1:Ak17IJ037caFp4jpCw/iQQ7/W74Sqpb1YuKJU6HTKfM=
 github.com/wasilibs/wazero-helpers v0.0.0-20240620070341-3dff1577cd52 h1:OvLBa8SqJnZ6P+mjlzc2K7PM22rRUPE1x32G9DTPrC4=

lifecycle/cli/cli.go

@@ -0,0 +1,230 @@
+// Package cli runs caller-owned urfave/cli trees inside selected lifecycle modules.
+// It owns temporary signal subscriptions and exit classification, not process exit,
+// configuration, resource handles or unsupervised goroutines.
+package cli
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/signal"
+	"slices"
+	"syscall"
+
+	urfavecli "github.com/urfave/cli/v3"
+	"go.auvem.com/corestack/lifecycle"
+)
+
+// Run executes cliRoot with args including argv[0], returning 0 for success/help,
+// 2 for usage, and 1 for runtime failures. Lifecycle failures always take priority.
+// It prints a final diagnostic to cliRoot.ErrWriter and never exits the process.
+// Run reserves ExitErrHandler, OnUsageError and CommandNotFound throughout the
+// declared tree. Construct fresh trees for independent runs; do not mutate them
+// concurrently. Native generated-help parse and environment validation failures
+// may return 1 and print native diagnostics in addition to the final diagnostic.
+func Run(ctx context.Context, cliRoot *urfavecli.Command, args []string) (int, error) {
+	var err error
+	if ctx == nil || cliRoot == nil {
+		err = errors.New("cli: context and root command are required")
+	} else {
+		err = validateTree(cliRoot)
+	}
+	if err == nil {
+		var missing error
+		installHooks(cliRoot, &missing)
+		err = cliRoot.Run(ctx, args)
+		if missing != nil {
+			if err == nil {
+				err = missing
+			} else {
+				err = errors.Join(err, missing)
+			}
+		}
+	}
+	if err == nil {
+		return 0, nil
+	}
+	code := classify(err, 0)
+	err = expose(err)
+	if cliRoot != nil && cliRoot.ErrWriter != nil {
+		fmt.Fprintln(cliRoot.ErrWriter, err)
+	} else {
+		fmt.Fprintln(os.Stderr, err)
+	}
+	return code, err
+}
+
+func validateTree(cmd *urfavecli.Command) error {
+	if cmd == nil {
+		return errors.New("cli: nil command")
+	}
+	if cmd.ExitErrHandler != nil || cmd.OnUsageError != nil || cmd.CommandNotFound != nil {
+		return fmt.Errorf("cli: command %q sets a reserved error hook", cmd.Name)
+	}
+	for _, child := range cmd.Commands {
+		if err := validateTree(child); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func installHooks(cmd *urfavecli.Command, missing *error) {
+	cmd.ExitErrHandler = func(context.Context, *urfavecli.Command, error) {}
+	cmd.OnUsageError = func(_ context.Context, selected *urfavecli.Command, err error, _ bool) error {
+		_ = urfavecli.ShowSubcommandHelp(selected)
+		return &failure{err, 2}
+	}
+	cmd.CommandNotFound = func(_ context.Context, selected *urfavecli.Command, name string) {
+		*missing = errors.Join(*missing, &failure{fmt.Errorf("unknown command or help topic %q", name), 2})
+		_ = urfavecli.ShowSubcommandHelp(selected)
+	}
+	for _, child := range cmd.Commands {
+		installHooks(child, missing)
+	}
+}
+
+// Serve returns a native action running exactly modules, including their services,
+// in registration order with reverse cleanup. Bindings capture declarations without
+// starting work; resources and declarations must not be mutated concurrently.
+// Nil config.Signals subscribes to SIGINT/SIGTERM for the invocation, buffered for
+// two signals; an injected channel and its subscription remain caller-owned.
+// The private invocation App is unavailable for managed-worker admission.
+func Serve(config lifecycle.Config, modules []lifecycle.Module) urfavecli.ActionFunc {
+	return bind(config, modules, nil, false)
+}
+
+// Action returns a native one-off action using exactly modules with their Run
+// callbacks suppressed. All setups precede fn; completion triggers reverse cleanup.
+// fn receives lifecycle's signal-aware context and the selected native command.
+// Nil fn is a runtime configuration error. Signal and ownership rules match Serve;
+// hooks outside this action are outside the lifecycle shutdown guarantee.
+func Action(config lifecycle.Config, modules []lifecycle.Module, fn urfavecli.ActionFunc) urfavecli.ActionFunc {
+	return bind(config, modules, fn, true)
+}
+
+func bind(config lifecycle.Config, modules []lifecycle.Module, fn urfavecli.ActionFunc, oneOff bool) urfavecli.ActionFunc {
+	modules = slices.Clone(modules)
+	return func(ctx context.Context, cmd *urfavecli.Command) error {
+		err := execute(ctx, cmd, config, modules, fn, oneOff)
+		if err != nil {
+			return &failure{err, 1}
+		}
+		return nil
+	}
+}
+
+func execute(ctx context.Context, cmd *urfavecli.Command, config lifecycle.Config, modules []lifecycle.Module, fn urfavecli.ActionFunc, oneOff bool) error {
+	if oneOff && fn == nil {
+		return errors.New("cli: one-off function is required")
+	}
+	var signals chan os.Signal
+	if config.Signals == nil {
+		signals = make(chan os.Signal, 2)
+		config.Signals = signals
+	}
+	app, err := lifecycle.New(config)
+	if err != nil {
+		return err
+	}
+	names := make(map[string]bool, len(modules))
+	for _, module := range modules {
+		names[module.Name] = true
+		if oneOff {
+			module.Run = nil
+		}
+		if err := app.Register(module); err != nil {
+			return err
+		}
+	}
+	if oneOff {
+		name := "cli-action"
+		for names[name] {
+			name += "-"
+		}
+		noop := func(context.Context) error { return nil }
+		if err := app.Register(lifecycle.Module{Name: name, Setup: noop, Teardown: noop,
+			Run: func(ctx context.Context) error { return fn(ctx, cmd) }}); err != nil {
+			return err
+		}
+	}
+	if signals != nil {
+		signal.Notify(signals, syscall.SIGINT, syscall.SIGTERM)
+		defer signal.Stop(signals)
+	}
+	return app.Run(ctx)
+}
+
+type failure struct {
+	error
+	code int
+}
+
+func (e *failure) Unwrap() error { return e.error }
+
+func children(err error) []error {
+	switch e := err.(type) {
+	case interface{ Unwrap() []error }:
+		return e.Unwrap()
+	case interface{ Unwrap() error }:
+		if child := e.Unwrap(); child != nil {
+			return []error{child}
+		}
+	case urfavecli.MultiError:
+		return e.Errors()
+	}
+	return nil
+}
+
+// invariant: runtime branches dominate usage; aggregate containers add no failure.
+func classify(err error, inherited int) int {
+	if e, ok := err.(*failure); ok {
+		if e.code == 1 {
+			return 1
+		}
+		inherited = e.code
+	} else if e, ok := err.(urfavecli.ExitCoder); ok && inherited == 0 {
+		inherited = 1
+		if e.ExitCode() == 2 {
+			inherited = 2
+		}
+	}
+	code := 0
+	for _, child := range children(err) {
+		if child == nil {
+			continue
+		}
+		next := classify(child, inherited)
+		if next == 1 {
+			return 1
+		}
+		code = next
+	}
+	if code != 0 {
+		return code
+	}
+	if inherited != 0 {
+		return inherited
+	}
+	return 1
+}
+
+// exposed retains native identity and formatting while making opaque MultiError
+// descendants reachable through standard errors.Is and errors.As traversal.
+type exposed struct {
+	error
+	causes []error
+}
+
+func (e *exposed) Unwrap() []error { return e.causes }
+
+func expose(err error) error {
+	causes := []error{err}
+	for _, child := range children(err) {
+		if child != nil {
+			causes = append(causes, expose(child))
+		}
+	}
+	return &exposed{err, causes}
+}

lifecycle/cli/cli_test.go

@@ -0,0 +1,428 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"reflect"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+
+	urfavecli "github.com/urfave/cli/v3"
+	"go.auvem.com/corestack/lifecycle"
+)
+
+func config() lifecycle.Config {
+	return lifecycle.Config{Logger: slog.New(slog.NewTextHandler(io.Discard, nil)), Signals: make(chan os.Signal, 2), ShutdownTimeout: time.Second}
+}
+
+func command(action urfavecli.ActionFunc) *urfavecli.Command {
+	return &urfavecli.Command{Name: "app", Writer: io.Discard, ErrWriter: io.Discard, Commands: []*urfavecli.Command{{Name: "inspect", Action: action, Flags: []urfavecli.Flag{&urfavecli.BoolFlag{Name: "verbose"}}}}}
+}
+
+func TestNativeLifecycleFlow(t *testing.T) {
+	for _, fail := range []bool{false, true} {
+		t.Run(fmt.Sprint(fail), func(t *testing.T) {
+			var order []string
+			boom := &os.PathError{Op: "inspect", Path: "db", Err: io.ErrUnexpectedEOF}
+			var selected []lifecycle.Module
+			for _, name := range []string{"cli-action", "cli-action-", "database"} {
+				selected = append(selected, lifecycle.Module{Name: name,
+					Setup:    func(context.Context) error { order = append(order, "setup "+name); return nil },
+					Run:      func(context.Context) error { t.Error("one-off service started"); return nil },
+					Teardown: func(context.Context) error { order = append(order, "close "+name); return nil }})
+			}
+			cliRoot := command(Action(config(), selected, func(_ context.Context, cmd *urfavecli.Command) error {
+				if !cmd.Bool("verbose") {
+					t.Error("native flag missing")
+				}
+				order = append(order, "inspect")
+				if fail {
+					return boom
+				}
+				return nil
+			}))
+			cliRoot.Commands = append(cliRoot.Commands, &urfavecli.Command{Name: "unused", Action: Serve(config(), []lifecycle.Module{{Name: "unused", Setup: func(context.Context) error { t.Error("unselected setup"); return nil }, Teardown: func(context.Context) error { return nil }}})})
+			code, err := Run(context.Background(), cliRoot, []string{"app", "inspect", "--verbose"})
+			if fail && (code != 1 || !errors.Is(err, boom)) || !fail && (code != 0 || err != nil) {
+				t.Fatalf("Run = %d, %v", code, err)
+			}
+			want := []string{"setup cli-action", "setup cli-action-", "setup database", "inspect", "close database", "close cli-action-", "close cli-action"}
+			if !reflect.DeepEqual(order, want) {
+				t.Fatalf("order %v", order)
+			}
+		})
+	}
+}
+
+func TestNativeUsageAndHelp(t *testing.T) {
+	for _, tc := range []struct {
+		args string
+		code int
+	}{
+		{"", 0}, {"--help", 0}, {"inspect --help", 0}, {"help inspect", 0}, {"group", 0}, {"group --help", 0},
+		{"missing", 2}, {"help missing", 2}, {"group missing", 2}, {"group help missing", 2},
+		{"--bad", 2}, {"inspect --bad", 2}, {"inspect --count", 2}, {"inspect --count nope", 2}, {"inspect", 2},
+		{"help --bad", 1}, {"h --bad", 1}, {"group help --bad", 1}, {"group h --bad", 1},
+	} {
+		t.Run(tc.args, func(t *testing.T) {
+			cliRoot := command(Action(config(), []lifecycle.Module{{Name: "db", Setup: func(context.Context) error { t.Error("setup during usage/help"); return nil }, Teardown: func(context.Context) error { return nil }}}, func(context.Context, *urfavecli.Command) error { t.Error("action during usage/help"); return nil }))
+			cliRoot.Commands[0].Flags = append(cliRoot.Commands[0].Flags, &urfavecli.IntFlag{Name: "count", Required: true})
+			cliRoot.Commands = append(cliRoot.Commands, &urfavecli.Command{Name: "group", Commands: []*urfavecli.Command{{Name: "child"}}})
+			var output, diagnostic bytes.Buffer
+			cliRoot.Writer = &output
+			cliRoot.ErrWriter = &diagnostic
+			code, err := Run(context.Background(), cliRoot, append([]string{"app"}, strings.Fields(tc.args)...))
+			if code != tc.code || (err != nil) != (tc.code != 0) {
+				t.Fatalf("Run=%d,%v; want %d", code, err, tc.code)
+			}
+			if output.Len() == 0 && tc.code != 1 {
+				t.Error("missing native help")
+			}
+			if (diagnostic.Len() > 0) != (tc.code != 0) {
+				t.Fatalf("diagnostic %q", diagnostic.String())
+			}
+		})
+	}
+}
+
+func TestNativeValidation(t *testing.T) {
+	for _, kind := range []string{"environment", "validator", "validator-exit", "flag-action", "required-argument", "argument-parse", "exclusive"} {
+		t.Run(kind, func(t *testing.T) {
+			cliRoot := command(func(context.Context, *urfavecli.Command) error {
+				t.Error("invalid invocation reached action")
+				return nil
+			})
+			cmd := cliRoot.Commands[0]
+			args := []string{"app", "inspect"}
+			want := 1
+			switch kind {
+			case "environment":
+				t.Setenv("CORESTACK_CLI_COUNT", "oops")
+				cmd.Flags = []urfavecli.Flag{&urfavecli.IntFlag{Name: "count", Sources: urfavecli.EnvVars("CORESTACK_CLI_COUNT")}}
+			case "validator", "validator-exit":
+				cmd.ArgValidator = func(context.Context, *urfavecli.Command) error {
+					if kind == "validator-exit" {
+						return urfavecli.Exit("invalid", 2)
+					}
+					return errors.New("invalid")
+				}
+				if kind == "validator-exit" {
+					want = 2
+				}
+			case "flag-action":
+				cmd.Flags = []urfavecli.Flag{&urfavecli.BoolFlag{Name: "bad", Action: func(context.Context, *urfavecli.Command, bool) error { return errors.New("invalid") }}}
+				args = append(args, "--bad")
+			case "required-argument":
+				cmd.Arguments = []urfavecli.Argument{&urfavecli.StringArg{Name: "target", Required: true}}
+				want = 2
+			case "argument-parse":
+				cmd.Arguments = []urfavecli.Argument{&urfavecli.IntArg{Name: "count"}}
+				args = append(args, "oops")
+				want = 2
+			case "exclusive":
+				cmd.MutuallyExclusiveFlags = []urfavecli.MutuallyExclusiveFlags{{Flags: [][]urfavecli.Flag{{&urfavecli.BoolFlag{Name: "a"}}, {&urfavecli.BoolFlag{Name: "b"}}}}}
+				args = append(args, "--a", "--b")
+				want = 2
+			}
+			code, err := Run(context.Background(), cliRoot, args)
+			if code != want || err == nil {
+				t.Fatalf("Run=%d,%v; want %d", code, err, want)
+			}
+		})
+	}
+}
+
+func TestFailureCategoriesAndCauses(t *testing.T) {
+	for _, kind := range []string{"native-exit2", "native-after", "native-exit0", "native-exit9", "action-exit2", "teardown", "setup", "action-after", "usage-after", "nested-after", "unknown-after"} {
+		t.Run(kind, func(t *testing.T) {
+			cause := &os.PathError{Op: "read", Path: "db", Err: io.ErrUnexpectedEOF}
+			after := errors.New("after")
+			parent := errors.New("parent after")
+			original := urfavecli.Exit(cause, 2)
+			cfg := config()
+			modules := []lifecycle.Module{{Name: "db", Setup: func(context.Context) error { return nil }, Teardown: func(context.Context) error { return nil }}}
+			action := func(context.Context, *urfavecli.Command) error { return original }
+			want := 1
+			args := []string{"app", "inspect"}
+			switch kind {
+			case "native-exit2":
+				want = 2
+			case "native-exit0":
+				original = urfavecli.Exit(cause, 0)
+			case "native-exit9":
+				original = urfavecli.Exit(cause, 9)
+			case "setup":
+				modules[0].Setup = func(context.Context) error { return cause }
+			case "teardown":
+				modules[0].Teardown = func(context.Context) error { return after }
+			}
+			cliRoot := command(action)
+			if !strings.HasPrefix(kind, "native-") {
+				cliRoot.Commands[0].Action = Action(cfg, modules, action)
+			}
+			if kind == "native-after" || kind == "action-after" || kind == "nested-after" || kind == "usage-after" {
+				cliRoot.Commands[0].After = func(context.Context, *urfavecli.Command) error { return after }
+			}
+			if kind == "nested-after" {
+				cliRoot.After = func(context.Context, *urfavecli.Command) error { return parent }
+			}
+			if kind == "usage-after" {
+				cliRoot.Commands[0].Flags = append(cliRoot.Commands[0].Flags, &urfavecli.StringFlag{Name: "needed", Required: true})
+			}
+			if kind == "unknown-after" {
+				args = []string{"app", "help", "missing"}
+				cliRoot.After = func(context.Context, *urfavecli.Command) error { return after }
+			}
+			code, err := Run(context.Background(), cliRoot, args)
+			if code != want || err == nil {
+				t.Fatalf("Run=%d,%v", code, err)
+			}
+			if kind != "usage-after" && kind != "unknown-after" {
+				var path *os.PathError
+				if !errors.Is(err, cause) || !errors.As(err, &path) || path != cause || !errors.Is(err, io.ErrUnexpectedEOF) {
+					t.Fatalf("cause lost: %v", err)
+				}
+				if kind != "setup" && !errors.Is(err, original) {
+					t.Fatalf("original identity lost: %v", err)
+				}
+			}
+			if kind == "teardown" || strings.HasSuffix(kind, "-after") {
+				if !errors.Is(err, after) {
+					t.Fatalf("After/cleanup lost: %v", err)
+				}
+			}
+			if kind == "nested-after" && !errors.Is(err, parent) {
+				t.Fatal("parent cause lost")
+			}
+			if kind == "native-after" || kind == "action-after" || kind == "nested-after" || kind == "usage-after" {
+				var multi urfavecli.MultiError
+				if !errors.As(err, &multi) || !errors.Is(err, multi) {
+					t.Fatalf("native aggregate lost: %v", err)
+				}
+				if err.Error() != multi.Error() {
+					t.Fatalf("duplicated formatting: %v", err)
+				}
+			}
+		})
+	}
+}
+
+func TestValidationBeforeSetup(t *testing.T) {
+	for _, kind := range []string{"nil-context", "nil-root", "nil-function", "nil-logger", "negative-timeout", "invalid-module", "duplicate-module", "nil-child", "exit-hook", "usage-hook", "not-found-hook"} {
+		t.Run(kind, func(t *testing.T) {
+			cfg := config()
+			noop := func(context.Context) error { return nil }
+			modules := []lifecycle.Module{{Name: "db", Setup: func(context.Context) error { t.Error("setup before validation"); return nil }, Teardown: noop}}
+			var ctx context.Context = context.Background()
+			fn := urfavecli.ActionFunc(func(context.Context, *urfavecli.Command) error { t.Error("action before validation"); return nil })
+			switch kind {
+			case "nil-context":
+				ctx = nil
+			case "nil-function":
+				fn = nil
+			case "nil-logger":
+				cfg.Logger = nil
+			case "negative-timeout":
+				cfg.ShutdownTimeout = -1
+			case "invalid-module":
+				modules = append(modules, lifecycle.Module{Name: "invalid"})
+			case "duplicate-module":
+				modules = append(modules, modules[0])
+			}
+			cliRoot := command(Action(cfg, modules, fn))
+			switch kind {
+			case "nil-root":
+				cliRoot = nil
+			case "nil-child":
+				cliRoot.Commands = append(cliRoot.Commands, nil)
+			case "exit-hook":
+				cliRoot.Commands[0].ExitErrHandler = func(context.Context, *urfavecli.Command, error) {}
+			case "usage-hook":
+				cliRoot.Commands[0].OnUsageError = func(context.Context, *urfavecli.Command, error, bool) error { return nil }
+			case "not-found-hook":
+				cliRoot.Commands[0].CommandNotFound = func(context.Context, *urfavecli.Command, string) {}
+			}
+			code, err := Run(ctx, cliRoot, []string{"app", "inspect"})
+			if code != 1 || err == nil {
+				t.Fatalf("Run=%d,%v", code, err)
+			}
+		})
+	}
+}
+func await[T any](t *testing.T, ch <-chan T) T {
+	t.Helper()
+	select {
+	case value := <-ch:
+		return value
+	case <-time.After(3 * time.Second):
+		t.Fatal("callback blocked")
+		var zero T
+		return zero
+	}
+}
+
+func TestSignalsAndParent(t *testing.T) {
+	for _, mode := range []string{"first", "second", "parent", "serve"} {
+		t.Run(mode, func(t *testing.T) {
+			signals := make(chan os.Signal, 2)
+			cfg := config()
+			cfg.Signals = signals
+			ctx, cancel := context.WithCancel(context.Background())
+			defer cancel()
+			ready := make(chan struct{})
+			canceled := make(chan struct{})
+			exited := make(chan struct{})
+			cleanup := make(chan struct{})
+			release := make(chan struct{})
+			defer func() { close(release); await(t, exited) }()
+			callback := func(ctx context.Context) error {
+				close(ready)
+				defer close(exited)
+				<-ctx.Done()
+				close(canceled)
+				if mode == "second" {
+					<-release
+				}
+				return ctx.Err()
+			}
+			modules := []lifecycle.Module{{Name: "db", Setup: func(context.Context) error { return nil }, Teardown: func(context.Context) error { close(cleanup); return nil }, Run: callback}}
+			action := Action(cfg, modules, func(ctx context.Context, _ *urfavecli.Command) error { return callback(ctx) })
+			if mode == "serve" {
+				action = Serve(cfg, modules)
+			}
+			done := make(chan struct {
+				code int
+				err  error
+			}, 1)
+			go func() {
+				code, err := Run(ctx, command(action), []string{"app", "inspect"})
+				done <- struct {
+					code int
+					err  error
+				}{code, err}
+			}()
+			await(t, ready)
+			if mode == "parent" {
+				cancel()
+			} else {
+				signals <- syscall.SIGINT
+			}
+			await(t, canceled)
+			await(t, cleanup)
+			if mode == "second" {
+				signals <- syscall.SIGTERM
+			}
+			result := await(t, done)
+			want := 0
+			if mode == "second" || mode == "parent" {
+				want = 1
+			}
+			if result.code != want || (result.err != nil) != (want != 0) {
+				t.Fatalf("Run=%d,%v", result.code, result.err)
+			}
+			if want == 1 && !errors.Is(result.err, context.Canceled) {
+				t.Fatalf("cancellation lost: %v", result.err)
+			}
+			// The adapter must leave the injected channel open and reusable.
+			signals <- syscall.SIGTERM
+		})
+	}
+}
+
+func TestSharedShutdownDeadline(t *testing.T) {
+	cfg := config()
+	cfg.ShutdownTimeout = 100 * time.Millisecond
+	ready := make(chan struct{})
+	shutdown := make(chan time.Time, 1)
+	exited := make(chan struct{})
+	release := make(chan struct{})
+	defer func() { close(release); await(t, exited) }()
+	var first time.Time
+	noop := func(context.Context) error { return nil }
+	modules := []lifecycle.Module{
+		{Name: "blocked", Setup: noop, Teardown: func(ctx context.Context) error {
+			defer close(exited)
+			deadline, _ := ctx.Deadline()
+			shutdown <- deadline
+			<-release
+			return nil
+		}},
+		{Name: "first", Setup: noop, Teardown: func(ctx context.Context) error {
+			first, _ = ctx.Deadline()
+			time.Sleep(20 * time.Millisecond)
+			return nil
+		}},
+	}
+	done := make(chan error, 1)
+	go func() {
+		_, err := Run(context.Background(), command(Action(cfg, modules, func(context.Context, *urfavecli.Command) error { close(ready); return nil })), []string{"app", "inspect"})
+		done <- err
+	}()
+	await(t, ready)
+	deadline := await(t, shutdown)
+	if !first.Equal(deadline) {
+		t.Fatal("shutdown deadline reset between hooks")
+	}
+	if err := await(t, done); !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("deadline lost: %v", err)
+	}
+}
+
+func TestEmptySelectionsAndOwnedSignals(t *testing.T) {
+	for _, oneOff := range []bool{false, true} {
+		cfg := config()
+		cfg.Signals = nil
+		action := Serve(cfg, nil)
+		if oneOff {
+			action = Action(cfg, nil, func(context.Context, *urfavecli.Command) error { return nil })
+		}
+		if code, err := Run(context.Background(), command(action), []string{"app", "inspect"}); code != 0 || err != nil {
+			t.Fatalf("Run=%d,%v", code, err)
+		}
+	}
+	cfg := config()
+	signals := make(chan os.Signal)
+	close(signals)
+	cfg.Signals = signals
+	if code, err := Run(context.Background(), command(Serve(cfg, nil)), []string{"app", "inspect"}); code != 0 || err != nil {
+		t.Fatalf("closed signals: %d,%v", code, err)
+	}
+}
+func TestPartialSetupAndMixedCleanup(t *testing.T) {
+	for _, setupFailure := range []bool{false, true} {
+		t.Run(fmt.Sprint(setupFailure), func(t *testing.T) {
+			initiating := urfavecli.Exit(io.ErrUnexpectedEOF, 2)
+			cleanup := errors.New("cleanup")
+			var order []string
+			modules := []lifecycle.Module{
+				{Name: "first", Setup: func(context.Context) error { order = append(order, "first setup"); return nil }, Teardown: func(context.Context) error { order = append(order, "first cleanup"); return cleanup }},
+				{Name: "second", Setup: func(context.Context) error {
+					order = append(order, "second setup")
+					if setupFailure {
+						return initiating
+					}
+					return nil
+				}, Teardown: func(context.Context) error { order = append(order, "second cleanup"); return nil }},
+			}
+			cliRoot := command(Action(config(), modules, func(context.Context, *urfavecli.Command) error { order = append(order, "action"); return initiating }))
+			code, err := Run(context.Background(), cliRoot, []string{"app", "inspect"})
+			if code != 1 || !errors.Is(err, initiating) || !errors.Is(err, cleanup) || !errors.Is(err, io.ErrUnexpectedEOF) {
+				t.Fatalf("Run=%d,%v", code, err)
+			}
+			want := []string{"first setup", "second setup", "first cleanup"}
+			if !setupFailure {
+				want = []string{"first setup", "second setup", "action", "second cleanup", "first cleanup"}
+			}
+			if !reflect.DeepEqual(order, want) {
+				t.Fatalf("order %v", order)
+			}
+		})
+	}
+}

lifecycle/cli/example_test.go

@@ -0,0 +1,51 @@
+package cli_test
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"log/slog"
+
+	urfavecli "github.com/urfave/cli/v3"
+	"go.auvem.com/corestack/lifecycle"
+	"go.auvem.com/corestack/lifecycle/cli"
+)
+
+func Example() {
+	cfg := lifecycle.Config{Logger: slog.New(slog.NewTextHandler(io.Discard, nil))}
+	for _, args := range [][]string{{"app", "serve"}, {"app", "inspect", "--verbose"}} {
+		var database string
+		db := lifecycle.Module{Name: "database",
+			Setup:    func(context.Context) error { database = "connected"; fmt.Println("open database"); return nil },
+			Teardown: func(context.Context) error { fmt.Println("close database"); database = ""; return nil },
+		}
+		server := lifecycle.Module{Name: "server",
+			Setup: func(context.Context) error { fmt.Println("open server"); return nil },
+			// A real server blocks until cancellation; this finite service keeps the example executable.
+			Run:      func(context.Context) error { fmt.Println("serve:", database); return nil },
+			Teardown: func(context.Context) error { fmt.Println("close server"); return nil },
+		}
+		cliRoot := &urfavecli.Command{Name: "app", Commands: []*urfavecli.Command{
+			{Name: "serve", Action: cli.Serve(cfg, []lifecycle.Module{db, server})},
+			{Name: "inspect", Flags: []urfavecli.Flag{&urfavecli.BoolFlag{Name: "verbose"}},
+				Action: cli.Action(cfg, []lifecycle.Module{db}, func(_ context.Context, cmd *urfavecli.Command) error {
+					fmt.Println("inspect:", database, "verbose:", cmd.Bool("verbose"))
+					return nil
+				})},
+		}}
+		code, err := cli.Run(context.Background(), cliRoot, args)
+		fmt.Println("exit:", code, err)
+		// main may call os.Exit(code) here, after adapter cleanup.
+	}
+	// Output:
+	// open database
+	// open server
+	// serve: connected
+	// close server
+	// close database
+	// exit: 0 <nil>
+	// open database
+	// inspect: connected verbose: true
+	// close database
+	// exit: 0 <nil>
+}

migrate/README.md

@@ -5,6 +5,61 @@
 It returns `*goose.Provider` directly: Goose owns execution, version tracking,
 status, and errors. There is no lifecycle dependency or background work.
 
+Use the standalone `corestack-goose` development tool for SQL and Go creation
+and timestamp-to-sequential reconciliation. Its generated Go migrations work
+unchanged with this package's provider-local registration:
+
+```sh
+go install go.auvem.com/corestack/cmd/corestack-goose@<release>
+mkdir -p migrations
+cd migrations
+corestack-goose create create_events sql
+corestack-goose fix
+corestack-goose create populate_events go
+corestack-goose fix
+# Or use the version selected by your consumer module:
+go run go.auvem.com/corestack/cmd/corestack-goose create add_index sql
+```
+
+Both commands default to the current working directory; use `--dir <dir>` to
+select another existing directory. Paths must have no symlink components (on
+macOS use `/private/tmp`, rather than `/tmp`), and migration files must be regular.
+Names are lowercase ASCII words separated by underscores. Templates are stock
+Goose SQL or transactional Go. The Go suffix `<version>_<name>_migration.go`
+keeps names such as `test`, `create_test` and `windows` buildable on every platform.
+Edit up/down bodies; leave factories and generated `register.go` intact.
+Its `GoMigrations()` returns fresh registrations, even for SQL-only sets.
+
+Versions must be unique across SQL and Go. Goose timestamps have second
+resolution: fix each new migration before creating another in the same second,
+or wait for a distinct timestamp. `fix` preserves sequential IDs and migration
+bodies, allocates timestamps after the highest sequential ID with at least
+five-digit padding, and updates filenames and registration literals together.
+Preflight rejects unsafe paths, collisions, unsupported Go layouts, edited
+aggregates, duplicate versions/factories, overflow and lexical/numeric order
+disagreement. Stock Goose Go output uses an incompatible global `init` registry.
+For concepts, see Goose's [hybrid versioning](https://github.com/pressly/goose#hybrid-versioning)
+and [SQL annotations](https://pressly.github.io/goose/documentation/annotations/).
+
+Before `fix`, commit or separately back up the **complete source set**, including
+untracked migrations and tracked edits. Use one authoring process without concurrent
+editor changes. New destinations are exclusive; staged destinations are fully
+published before old sources are removed. This is **not an atomic multi-file
+operation**: interruption can leave duplicates, aggregate drift or staging files,
+with no automatic rollback or journal. On failure inspect the reported completed,
+partial/current and outstanding paths, then restore the complete source set and
+aggregate from backup before retrying. Ordinary Git restore cannot recover
+untracked files or unsaved edits.
+
+Source reconciliation never rewrites database history. Use it before those IDs
+reach a shared database; preserve deployed IDs and add migrations afterward. The
+tool cannot determine deployment history.
+
+The standalone tool needs no database or build tags. Production imports `migrate`
+and optionally `migrate/lifecycle`; neither imports authoring code. Generated
+migrations import only Goose and the standard library. Artifact tests verify the
+runtime dependency and executable boundary for the tested build.
+
 Embed migrations in the application's binary and run them before serving traffic:
 
 ```go
@@ -40,65 +95,69 @@ not defer it when sharing the pool with the application. Use `"."` for SQL files
 at the embedded root. Files in the selected directory are discovered directly,
 without recursively searching subdirectories.
 
-Use unique positive versions and Goose's migration creator naming convention:
-zero-padded sequential names such as `00007_users.sql` and `00010_events.sql`, or
-fixed-width timestamps such as `20261027114500_create_users.sql`. Filenames must
-sort lexically in numeric version order, including when mixing naming schemes;
-choose padding wide enough for the complete history. Goose v3.29.0 preserves
-lexical source order for SQL-only providers, so arbitrary unpadded names such as
-`7_users.sql` and `10_events.sql` are unsupported by this house convention: they
-can produce incorrect latest versions and source/status ordering. This package
-does not rename or normalize migration files.
+Preserve the tool's creator/fix filenames and ship the complete migration history.
+The pinned Goose SQL-only provider relies on lexical filename order matching
+numeric version order. Timestamp versions and gaps are supported; never derive
+versions from file counts. For operations and errors, use the
+[Provider API](https://pkg.go.dev/github.com/pressly/goose/v3#Provider).
 
-Never derive a version from a file count or add one to the current version.
-Keep applied migrations immutable and ship the complete history. Goose rejects
-newly introduced migrations below the current version by default.
+For generated Go functions, import the consumer's migration package and pass
+`migrations.GoMigrations()...` as the trailing arguments to `migrate.New`.
+Embed the complete directory with `//go:embed migrations` (and use a different
+variable name, such as `migrationFiles`, from the imported package). The directory
+must exist even for Go-only sets. Global registration is disabled; never share
+mutable registration objects across providers. See Goose's
+[provider-local registration](https://pressly.github.io/goose/documentation/provider/#withgomigrations).
 
-```sql
--- +goose Up
-CREATE TABLE users (id BIGINT PRIMARY KEY);
+## Lifecycle startup and native commands
 
--- +goose Down
-DROP TABLE users;
+`go.auvem.com/corestack/migrate/lifecycle` is a thin adapter; `migrate` itself has
+no lifecycle dependency. Alias it `migratelifecycle` to distinguish the core
+lifecycle package. Its resolver runs after the caller's database setup and should
+construct a fresh provider with fresh registrations:
+
+```go
+resolve := func(ctx context.Context) (*goose.Provider, error) {
+    return migrate.New(db, goose.DialectPostgres, migrationFiles,
+        "migrations", logger, migrations.GoMigrations()...)
+}
+startup, err := migratelifecycle.Module("migrations", migratelifecycle.Require, resolve)
+if err != nil {
+    return err
+}
+root := &urfavecli.Command{Name: "app", Commands: []*urfavecli.Command{
+    {Name: "serve", Action: cli.Serve(cfg, []lifecycle.Module{database, startup, server})},
+    migratelifecycle.Commands(cfg, []lifecycle.Module{database}, resolve),
+}}
+code, err := cli.Run(ctx, root, args) // args includes argv[0]; caller owns process exit.
 ```
 
-Goose runs each migration in a transaction by default. Its annotations support
-statement blocks and explicit `NO TRANSACTION` where required; such migrations
-and nontransactional database DDL can leave partial effects on failure. Down
-migrations execute application-authored SQL and may delete data.
+Here `database.Setup` opens `db` and cleans up its partial acquisition on failure;
+`database.Teardown` closes it. Construct the tree and captured resource bindings
+fresh for independent invocations. Declaration does no work. Select `Apply` to run
+Up during setup, or `Require` to fail before later setup/services when migrations
+are pending. Require is a point-in-time check without a deployment lock. It and
+status may initialize Goose's version table; neither promises read-only DB access.
+The migration module never closes the provider or shared database.
 
-| Operation | Provider method |
-| --- | --- |
-| Apply all pending migrations | `Up(ctx)` |
-| Apply pending versions through a target, inclusive | `UpTo(ctx, version)` |
-| Roll back versions above a target; zero removes all | `DownTo(ctx, version)` |
-| Inspect each migration's state | `Status(ctx)` |
-| Current database version | `GetDBVersion(ctx)` |
-| Current and latest available versions | `GetVersions(ctx)` |
-| Detect pending migrations | `HasPending(ctx)` |
-
-Targets are numeric version bounds, so gaps and timestamps work without special
-handling. Up on a fully migrated database succeeds with no results. Operations
-may create Goose's `goose_db_version` table even when only inspecting state.
-Execution errors retain Goose's details; use `errors.As` with
-`*goose.PartialError` to inspect applied and failed migrations. Transactional
-failure leaves the database at the last committed migration version. Operation
-logs use the injected slog logger; callers handle and log returned errors.
-
-For Go functions, pass migrations created with `goose.NewGoMigration(version,
-up, down)` as the trailing arguments to `migrate.New`. Use `goose.GoFunc.RunTx`
-for transactional work or `RunDB` for work requiring its own connections. Each
-provider should receive its own migration instances. Versions must be unique
-across SQL and Go migrations. Global registration is disabled; no `init` or
-`goose.AddMigration` calls are needed.
+The native group supplies `migrate up`, `up-to <version>` (inclusive), `down`
+(one migration), `down-to <version>` and `status` (version/state/source table).
+Pass exactly the database modules, excluding the startup migration module and
+unrelated modules. Services are suppressed; the existing `lifecycle/cli.Action`
+owns signals, cancellation, errors and reverse cleanup. Help and invalid arguments
+never run setup. Target versions must be nonnegative decimal int64 values, with
+no extra arguments; malformed usage returns exit 2 through `cli.Run`. Zero follows
+Goose: `down-to 0` rolls everything back; `up-to 0` succeeds if nothing is pending,
+but returns a runtime error when pending work reaches Goose's version validation.
+Resolver/Goose/cleanup and status Writer failures return runtime errors (exit 1).
+Supply the native command Writer and configured Goose logger for output.
 
 Postgres providers automatically use Goose's default session advisory locker.
 Concurrent startup calls from separate providers/processes serialize migration
 execution and recheck applied versions under the lock. The default lock ID
 serializes Goose migrations throughout the same database, including different
-schemas; lock acquisition retries for about five minutes and unlock retries for
-about one minute, subject to the operation context. Use a direct connection or
-a session-pooling proxy: transaction pooling cannot preserve session locks.
+schemas. Use a direct connection or a session-pooling proxy: transaction pooling
+cannot preserve session locks.
 `RunDB` Go migrations need spare pool connections while the locked session is
 held; avoid a one-connection pool for them.
 

migrate/lifecycle/lifecycle.go

@@ -0,0 +1,146 @@
+// Package lifecycle adapts Goose providers to startup policy and native commands.
+// Callers own database modules and supply fresh, late-bound providers.
+package lifecycle
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+	"text/tabwriter"
+
+	"github.com/pressly/goose/v3"
+	urfavecli "github.com/urfave/cli/v3"
+	"go.auvem.com/corestack/lifecycle"
+	"go.auvem.com/corestack/lifecycle/cli"
+)
+
+// Policy selects migration behavior during module setup.
+type Policy string
+
+const (
+	// Apply runs pending migrations before later modules start.
+	Apply Policy = "apply"
+	// Require fails setup when migrations are pending. This is a point-in-time
+	// check, not a deployment lock; Goose may initialize its version table.
+	Require Policy = "require"
+)
+
+// Module declares startup migration work without resolving provider yet.
+// Register it after the database module and before dependent modules. The
+// resolver must return fresh registrations and clean up any partial acquisition.
+// Teardown never closes the provider: the database module owns its database.
+func Module(name string, policy Policy, provider func(context.Context) (*goose.Provider, error)) (lifecycle.Module, error) {
+	if name == "" || (policy != Apply && policy != Require) || provider == nil {
+		return lifecycle.Module{}, errors.New("migrate: name, apply/require policy and provider resolver are required")
+	}
+	return lifecycle.Module{Name: name, Teardown: func(context.Context) error { return nil }, Setup: func(ctx context.Context) error {
+		p, err := resolve(ctx, provider)
+		if err != nil {
+			return err
+		}
+		if policy == Apply {
+			_, err = p.Up(ctx)
+		} else {
+			var pending bool
+			pending, err = p.HasPending(ctx)
+			if err == nil && pending {
+				return errors.New("migrate: pending migrations; run migrate up before startup")
+			}
+		}
+		if err != nil {
+			return fmt.Errorf("migrate: %s: %w", policy, err)
+		}
+		return nil
+	}}, nil
+}
+
+func resolve(ctx context.Context, provider func(context.Context) (*goose.Provider, error)) (*goose.Provider, error) {
+	if provider == nil {
+		return nil, errors.New("migrate: provider resolver is required")
+	}
+	p, err := provider(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("migrate: resolve provider: %w", err)
+	}
+	if p == nil {
+		return nil, errors.New("migrate: resolver returned nil provider")
+	}
+	return p, nil
+}
+
+// Commands returns a fresh native migrate group using exactly modules, with
+// services suppressed. Supply database modules only, excluding startup policy.
+// Resolvers run after setup. Help/usage starts nothing; Action owns signals and
+// reverse cleanup. Use fresh trees and bindings for independent invocations.
+// Status may initialize the version table; it does not run migration bodies.
+func Commands(config lifecycle.Config, modules []lifecycle.Module, provider func(context.Context) (*goose.Provider, error)) *urfavecli.Command {
+	group := &urfavecli.Command{Name: "migrate", Usage: "Manage database migrations"}
+	for _, name := range []string{"up", "up-to", "down", "down-to", "status"} {
+		targeted := strings.HasSuffix(name, "-to")
+		leaf := &urfavecli.Command{Name: name, ArgValidator: func(_ context.Context, cmd *urfavecli.Command) error {
+			if targeted {
+				if cmd.NArg() == 1 {
+					if _, err := version(cmd.Args().First()); err == nil {
+						return nil
+					}
+				}
+				return urfavecli.Exit("expected one nonnegative decimal int64 version", 2)
+			}
+			if cmd.NArg() != 0 {
+				return urfavecli.Exit("unexpected positional arguments", 2)
+			}
+			return nil
+		}}
+		if targeted {
+			leaf.ArgsUsage = "<version>"
+		}
+		leaf.Action = cli.Action(config, modules, func(ctx context.Context, cmd *urfavecli.Command) error {
+			p, err := resolve(ctx, provider)
+			if err != nil {
+				return err
+			}
+			target, _ := version(cmd.Args().First()) // ArgValidator checked targeted leaves before setup.
+			switch name {
+			case "up":
+				_, err = p.Up(ctx)
+			case "up-to":
+				_, err = p.UpTo(ctx, target)
+			case "down":
+				_, err = p.Down(ctx)
+			case "down-to":
+				_, err = p.DownTo(ctx, target)
+			case "status":
+				var statuses []*goose.MigrationStatus
+				statuses, err = p.Status(ctx)
+				if err == nil {
+					writer := tabwriter.NewWriter(cmd.Writer, 0, 4, 2, ' ', 0)
+					if _, err = fmt.Fprintln(writer, "VERSION\tSTATE\tSOURCE"); err == nil {
+						for _, status := range statuses {
+							if _, err = fmt.Fprintf(writer, "%d\t%s\t%s\n", status.Source.Version, status.State, status.Source.Path); err != nil {
+								break
+							}
+						}
+					}
+					if err == nil {
+						err = writer.Flush()
+					}
+				}
+			}
+			if err != nil {
+				return fmt.Errorf("migrate %s: %w", name, err)
+			}
+			return nil
+		})
+		group.Commands = append(group.Commands, leaf)
+	}
+	return group
+}
+
+func version(raw string) (int64, error) {
+	if raw == "" || strings.IndexFunc(raw, func(r rune) bool { return r < '0' || r > '9' }) >= 0 {
+		return 0, errors.New("invalid version")
+	}
+	return strconv.ParseInt(raw, 10, 64)
+}

migrate/lifecycle/lifecycle_test.go

@@ -0,0 +1,289 @@
+package lifecycle_test
+
+import (
+	"bytes"
+	"context"
+	"database/sql"
+	"embed"
+	"errors"
+	"io"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/pressly/goose/v3"
+	urfavecli "github.com/urfave/cli/v3"
+	"go.auvem.com/corestack/lifecycle"
+	"go.auvem.com/corestack/lifecycle/cli"
+	"go.auvem.com/corestack/migrate"
+	adapter "go.auvem.com/corestack/migrate/lifecycle"
+	_ "modernc.org/sqlite"
+)
+
+//go:embed testdata
+var files embed.FS
+
+func config() lifecycle.Config {
+	return lifecycle.Config{Logger: slog.New(slog.NewTextHandler(io.Discard, nil))}
+}
+
+func database(t *testing.T) *sql.DB {
+	t.Helper()
+	db, err := sql.Open("sqlite", filepath.Join(t.TempDir(), "test.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := db.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	return db
+}
+func provider(t *testing.T, db *sql.DB) *goose.Provider {
+	t.Helper()
+	p, err := migrate.New(db, goose.DialectSQLite3, files, "testdata/migrations", config().Logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+func TestStartupPolicies(t *testing.T) {
+	for _, policy := range []adapter.Policy{adapter.Apply, adapter.Require} {
+		for _, applied := range []bool{false, true} {
+			t.Run(string(policy)+"/applied="+stringBool(applied), func(t *testing.T) {
+				db := database(t)
+				p := provider(t, db)
+				if applied {
+					if _, err := p.Up(t.Context()); err != nil {
+						t.Fatal(err)
+					}
+				}
+				var calls []string
+				var setupCtx context.Context
+				dbModule := lifecycle.Module{Name: "db", Setup: func(ctx context.Context) error { setupCtx = ctx; calls = append(calls, "db"); return nil }, Teardown: func(ctx context.Context) error {
+					if ctx.Err() != nil {
+						t.Error(ctx.Err())
+					}
+					calls = append(calls, "close")
+					return nil
+				}}
+				module, err := adapter.Module("migrations", policy, func(ctx context.Context) (*goose.Provider, error) {
+					if ctx != setupCtx {
+						t.Error("setup context changed")
+					}
+					calls = append(calls, "resolve")
+					return provider(t, db), nil
+				})
+				if err != nil {
+					t.Fatal(err)
+				}
+				if len(calls) != 0 || module.Run != nil {
+					t.Fatal("declaration started work")
+				}
+				app, err := lifecycle.New(config())
+				if err != nil {
+					t.Fatal(err)
+				}
+				later := lifecycle.Module{Name: "later", Setup: func(context.Context) error { calls = append(calls, "later"); return nil }, Run: func(context.Context) error { calls = append(calls, "service"); return nil }, Teardown: func(context.Context) error { calls = append(calls, "later-close"); return nil }}
+				for _, m := range []lifecycle.Module{dbModule, module, later} {
+					if err := app.Register(m); err != nil {
+						t.Fatal(err)
+					}
+				}
+				err = app.Run(t.Context())
+				if policy == adapter.Require && !applied {
+					if err == nil || !strings.Contains(err.Error(), "pending") {
+						t.Fatalf("pending Require: %v", err)
+					}
+					if !reflect.DeepEqual(calls, []string{"db", "resolve", "close"}) {
+						t.Fatal(calls)
+					}
+				} else {
+					if err != nil {
+						t.Fatal(err)
+					}
+					if !reflect.DeepEqual(calls, []string{"db", "resolve", "later", "service", "later-close", "close"}) {
+						t.Fatal(calls)
+					}
+					pending, err := p.HasPending(t.Context())
+					if err != nil || pending {
+						t.Fatalf("pending=%v err=%v", pending, err)
+					}
+				}
+				if err := db.PingContext(t.Context()); err != nil {
+					t.Fatalf("adapter closed caller DB: %v", err)
+				}
+			})
+		}
+	}
+}
+func stringBool(v bool) string {
+	if v {
+		return "true"
+	}
+	return "false"
+}
+
+func TestModuleValidationAndErrors(t *testing.T) {
+	sentinel := errors.New("resolve failure")
+	for _, tc := range []struct {
+		name     string
+		policy   adapter.Policy
+		resolver func(context.Context) (*goose.Provider, error)
+	}{{"", adapter.Apply, func(context.Context) (*goose.Provider, error) { return nil, nil }}, {"m", "", func(context.Context) (*goose.Provider, error) { return nil, nil }}, {"m", "invalid", func(context.Context) (*goose.Provider, error) { return nil, nil }}, {"m", adapter.Apply, nil}} {
+		if _, err := adapter.Module(tc.name, tc.policy, tc.resolver); err == nil {
+			t.Fatal("accepted invalid module")
+		}
+	}
+	for _, policy := range []adapter.Policy{adapter.Apply, adapter.Require} {
+		for _, resolver := range []func(context.Context) (*goose.Provider, error){func(context.Context) (*goose.Provider, error) { return nil, nil }, func(context.Context) (*goose.Provider, error) { return nil, sentinel }, func(context.Context) (*goose.Provider, error) {
+			db := database(t)
+			p := provider(t, db)
+			if err := db.Close(); err != nil {
+				t.Fatal(err)
+			}
+			return p, nil
+		}} {
+			m, err := adapter.Module("m", policy, resolver)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if err := m.Setup(t.Context()); err == nil {
+				t.Fatal("accepted resolver/DB failure")
+			}
+		}
+	}
+	m, err := adapter.Module("m", adapter.Apply, func(context.Context) (*goose.Provider, error) { return nil, sentinel })
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := m.Setup(t.Context()); !errors.Is(err, sentinel) {
+		t.Fatal(err)
+	}
+}
+
+func run(t *testing.T, args []string, modules []lifecycle.Module, resolver func(context.Context) (*goose.Provider, error), writer io.Writer) (int, error) {
+	t.Helper()
+	root := &urfavecli.Command{Name: "app", Writer: writer, ErrWriter: io.Discard, Commands: []*urfavecli.Command{adapter.Commands(config(), modules, resolver)}}
+	return cli.Run(t.Context(), root, append([]string{"app", "migrate"}, args...))
+}
+func TestCommandsSQLite(t *testing.T) {
+	db := database(t)
+	var out bytes.Buffer
+	var calls []string
+	module := lifecycle.Module{Name: "db", Setup: func(context.Context) error { calls = append(calls, "setup"); return nil }, Run: func(context.Context) error { t.Error("one-off ran service"); return nil }, Teardown: func(context.Context) error { calls = append(calls, "cleanup"); return nil }}
+	resolver := func(context.Context) (*goose.Provider, error) {
+		calls = append(calls, "resolve")
+		return provider(t, db), nil
+	}
+	for _, step := range []struct {
+		args    []string
+		version int64
+	}{{[]string{"up-to", "1"}, 1}, {[]string{"up"}, 2}, {[]string{"status"}, 2}, {[]string{"down"}, 1}, {[]string{"up-to", "2"}, 2}, {[]string{"down-to", "0"}, 0}} {
+		calls = nil
+		code, err := run(t, step.args, []lifecycle.Module{module}, resolver, &out)
+		if code != 0 || err != nil {
+			t.Fatalf("%v code=%d err=%v", step.args, code, err)
+		}
+		version, err := provider(t, db).GetDBVersion(t.Context())
+		if err != nil || version != step.version {
+			t.Fatalf("%v version=%d err=%v", step.args, version, err)
+		}
+		if !reflect.DeepEqual(calls, []string{"setup", "resolve", "cleanup"}) {
+			t.Fatal(calls)
+		}
+	}
+	// Zero is valid syntax; Goose UpTo rejects it after setup when migrations are pending.
+	code, err := run(t, []string{"up-to", "0"}, []lifecycle.Module{module}, resolver, &out)
+	if code != 1 || err == nil || !strings.Contains(err.Error(), "greater than 0") {
+		t.Fatalf("zero UpTo: code=%d err=%v", code, err)
+	}
+	if !strings.Contains(out.String(), "VERSION") || !strings.Contains(out.String(), "applied") || !strings.Contains(out.String(), "00002_second.sql") {
+		t.Fatal(out.String())
+	}
+}
+func TestHelpAndUsageWithoutSetup(t *testing.T) {
+	for _, leaf := range []string{"up", "up-to", "down", "down-to", "status"} {
+		code, err := run(t, []string{leaf, "--help"}, nil, nil, io.Discard)
+		if code != 0 || err != nil {
+			t.Fatalf("%s help: %d %v", leaf, code, err)
+		}
+	}
+
+	module := lifecycle.Module{Name: "db", Setup: func(context.Context) error { t.Error("usage opened DB"); return nil }, Teardown: func(context.Context) error { return nil }}
+	for _, tc := range []struct {
+		args []string
+		code int
+	}{{nil, 0}, {[]string{"--help"}, 0}, {[]string{"help", "up-to"}, 0}, {[]string{"missing"}, 2}, {[]string{"up", "extra"}, 2}, {[]string{"down", "extra"}, 2}, {[]string{"status", "extra"}, 2}, {[]string{"up-to"}, 2}, {[]string{"down-to"}, 2}, {[]string{"up-to", "1", "2"}, 2}, {[]string{"down-to", "--", "-1"}, 2}, {[]string{"up-to", "+1"}, 2}, {[]string{"up-to", "9223372036854775808"}, 2}, {[]string{"down-to", "1x"}, 2}, {[]string{"up-to", "１"}, 2}} {
+		code, err := run(t, tc.args, []lifecycle.Module{module}, nil, io.Discard)
+		if code != tc.code || (code == 0 && err != nil) || (code != 0 && err == nil) {
+			t.Fatalf("args=%v code=%d err=%v", tc.args, code, err)
+		}
+	}
+}
+
+type brokenWriter struct{ err error }
+
+func (w brokenWriter) Write([]byte) (int, error) { return 0, w.err }
+func TestCommandFailureCleanup(t *testing.T) {
+	db := database(t)
+	writeErr := errors.New("write failed")
+	resolveErr := errors.New("resolve failed")
+	cleanupErr := errors.New("cleanup failed")
+	for _, tc := range []struct {
+		name     string
+		resolver func(context.Context) (*goose.Provider, error)
+		writer   io.Writer
+		want     error
+	}{{"writer", func(context.Context) (*goose.Provider, error) { return provider(t, db), nil }, brokenWriter{writeErr}, writeErr}, {"resolver", func(context.Context) (*goose.Provider, error) { return nil, resolveErr }, io.Discard, resolveErr}, {"nil", nil, io.Discard, nil}, {"nil-provider", func(context.Context) (*goose.Provider, error) { return nil, nil }, io.Discard, nil}} {
+		t.Run(tc.name, func(t *testing.T) {
+			cleaned := false
+			module := lifecycle.Module{Name: "db", Setup: func(context.Context) error { return nil }, Teardown: func(context.Context) error { cleaned = true; return cleanupErr }}
+			code, err := run(t, []string{"status"}, []lifecycle.Module{module}, tc.resolver, tc.writer)
+			if code != 1 || err == nil || !cleaned || !errors.Is(err, cleanupErr) || (tc.want != nil && !errors.Is(err, tc.want)) {
+				t.Fatalf("code=%d err=%v cleaned=%v", code, err, cleaned)
+			}
+		})
+	}
+}
+func TestCommandSignalContext(t *testing.T) {
+	signals := make(chan os.Signal, 2)
+	cfg := config()
+	cfg.Signals = signals
+	entered := make(chan struct{})
+	done := make(chan error, 1)
+	cleaned := false
+	module := lifecycle.Module{Name: "db", Setup: func(context.Context) error { return nil }, Teardown: func(ctx context.Context) error {
+		if ctx.Err() != nil {
+			t.Error(ctx.Err())
+		}
+		cleaned = true
+		return nil
+	}}
+	root := &urfavecli.Command{Name: "app", Writer: io.Discard, ErrWriter: io.Discard, Commands: []*urfavecli.Command{adapter.Commands(cfg, []lifecycle.Module{module}, func(ctx context.Context) (*goose.Provider, error) {
+		close(entered)
+		<-ctx.Done()
+		return nil, ctx.Err()
+	})}}
+	go func() { _, err := cli.Run(t.Context(), root, []string{"app", "migrate", "up"}); done <- err }()
+	select {
+	case <-entered:
+	case <-time.After(5 * time.Second):
+		t.Fatal("resolver did not start")
+	}
+	signals <- syscall.SIGTERM
+	select {
+	case err := <-done:
+		if err != nil || !cleaned {
+			t.Fatalf("err=%v cleaned=%v", err, cleaned)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("signal did not cancel resolver")
+	}
+}

migrate/lifecycle/testdata/migrations/00001_first.sql

@@ -0,0 +1,4 @@
+-- +goose Up
+CREATE TABLE events (id INTEGER PRIMARY KEY);
+-- +goose Down
+DROP TABLE events;

migrate/lifecycle/testdata/migrations/00002_second.sql

@@ -0,0 +1,4 @@
+-- +goose Up
+INSERT INTO events VALUES (2);
+-- +goose Down
+DELETE FROM events WHERE id = 2;

migrate/migrate.go

@@ -23,10 +23,13 @@ import (
 // across providers/processes. PostgreSQL connections must preserve session
 // affinity (transaction-pooling proxies cannot safely hold session locks).
 //
-// Use the returned Provider's Up, UpTo, DownTo, Status, GetDBVersion, GetVersions,
-// and HasPending methods directly. Filenames must sort lexically in numeric
-// version order: use zero-padded sequential or fixed-width timestamp prefixes,
-// as produced by Goose's migration creator. Global Go registration is ignored.
+// Use the returned Provider's Up, UpTo, Down, DownTo, Status, GetDBVersion, GetVersions,
+// and HasPending methods directly. Create and reconcile sources with the standalone
+// corestack-goose tool (go run go.auvem.com/corestack/cmd/corestack-goose).
+// Pass migrations.GoMigrations()... from its generated package; stock Goose Go
+// output uses an incompatible global init registry. Lexical filename order must
+// match numeric version order. Each provider needs fresh Go registrations;
+// global Go registration is ignored.
 func New(db *sql.DB, dialect goose.Dialect, files embed.FS, dir string, logger *slog.Logger, migrations ...*goose.Migration) (*goose.Provider, error) {
 	for i, migration := range migrations {
 		if migration == nil {