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

migrate/README.md

@@ -5,21 +5,60 @@
 It returns `*goose.Provider` directly: Goose owns execution, version tracking,
 status, and errors. There is no lifecycle dependency or background work.
 
-Create SQL migration files with Goose's
-[`create` command](https://pressly.github.io/goose/documentation/cli-commands/#create).
-For timestamp-to-sequential reconciliation before deployment, use its
-[`fix` command](https://pressly.github.io/goose/documentation/cli-commands/#fix)
-as described in [hybrid versioning](https://github.com/pressly/goose#hybrid-versioning).
-These commands edit source files before embedding; `fix` does not update database
-history. Never renumber migrations already applied to shared databases.
+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:
 
-**Goose's default Go template is not compatible unchanged with this package.**
-It registers migrations globally from `init`, while this package uses explicit
-provider-local registration. Until the compatible authoring CLI planned in
-[#9](https://gitea.auvem.com/corestack/go/issues/9) is available, Go migrations
-require the adaptation described below; do not treat stock `goose create ... go`
-output as ready to use. That follow-up must supply and document the supported
-creation/reconciliation workflow before it is complete.
+```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:
 
@@ -56,21 +95,62 @@ 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.
 
-Preserve Goose's creator/fix filenames and ship the complete migration history.
+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, errors, and SQL annotations, use the
-[Provider API](https://pkg.go.dev/github.com/pressly/goose/v3#Provider) and
-[SQL migration docs](https://pressly.github.io/goose/documentation/annotations/).
+versions from file counts. For operations and errors, use the
+[Provider API](https://pkg.go.dev/github.com/pressly/goose/v3#Provider).
 
-For Go functions, use Goose's
-[provider-local registration](https://pressly.github.io/goose/documentation/provider/#withgomigrations):
-pass fresh `goose.NewGoMigration` values as the trailing arguments to `migrate.New`.
-The creator's default Go template instead calls `goose.AddMigrationContext` from
-`init`; replace that registration with provider-local construction. Global
-registration is disabled to keep each provider's migration set isolated and avoid
-import side effects. If `fix` renames Go migrations, update their explicit
-registration versions to match. Versions must be unique across SQL and Go files.
+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).
+
+## Lifecycle startup and native commands
+
+`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.
+```
+
+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.
+
+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