Disabling and Uninstalling LumenFlow

LumenFlow is designed to be easy to remove. Adoption trust depends on a credible opt-out. Two first-class commands handle it:

• pnpm lumenflow:disable / pnpm lumenflow:enable — reversible enforcement opt-out
• pnpm lumenflow:uninstall — destructive eject with dry-run default

Note

lumenflow:disable and lumenflow:uninstall share the same generated-file manifest with each other. pnpm lumenflow:integrate is a deprecated no-op (WU-3543) — it no longer generates or tracks any files, so it isn’t part of this shared manifest.

Reversible Opt-Out

Use lumenflow:disable when you want to temporarily turn certification off without removing your own hook or CI content. It publishes one micro-worktree commit that first makes workspace.yaml non-certifying, then removes only LumenFlow-owned blocks from the generic pre-commit, pre-push, and CI delegators and removes their integrity manifest. A failed write or push leaves the main checkout unchanged.

1. Disable

   pnpm lumenflow:disable

2. Re-enable later

   pnpm lumenflow:enable

   This atomically restores the generic delegators, digest-bound manifest, and the required .gitignore exceptions, then enables certification last. It preserves bytes outside LumenFlow markers. If the LumenFlow CI path contains marker-free content, repair stops rather than adopting or overwriting that project-owned file.

Both commands are idempotent after the requested state is already published. lumenflow:enable is also the remediation for missing, stale, or tampered lifecycle evidence reported by lumenflow:doctor.

Full Uninstall

lumenflow:uninstall removes LumenFlow-generated files from your project. It defaults to dry-run — you must pass --confirm to actually delete.

Dry-run (default)

pnpm lumenflow:uninstall

Prints the planned deletions without modifying disk. Run this first to inspect scope.

Apply

pnpm lumenflow:uninstall --confirm

Actually removes files. Prints a restore hint (git checkout -- or git revert).

Uninstall Flags

Flag	Effect
--confirm	Actually delete (without this, dry-run).
--keep-history	Preserve docs/operations/tasks/wu/ and .lumenflow/state/packs/software-delivery/stamps/.
--keep-config	Preserve workspace.yaml and .lumenflow/constraints.md.
--client <name>	Deprecated compatibility tombstone; no longer narrows scope and does not enable host-specific behavior.
--json	Emit machine-readable JSON output.

What Gets Removed

LumenFlow classifies files into these categories, and uninstall acts accordingly:

Category	Example	Action
hook	.husky/pre-commit	Delete
ci	.github/workflows/lumenflow-ci.yml	Delete
state	.lumenflow/state/packs/software-delivery/ (and legacy .lumenflow/state/)	Delete
stamp	.lumenflow/state/packs/software-delivery/stamps/ (and legacy .lumenflow/stamps/)	Delete (unless --keep-history)
config	workspace.yaml, .lumenflow/constraints.md	Delete (unless --keep-config)
docs	docs/operations/tasks/wu/	Delete (unless --keep-history)

Caution

Project-owned agent instruction, skill, hook, and MCP configuration files are never touched by uninstall. LumenFlow neither generates, deletes, nor surgically edits them.

Removing the npm Packages

Uninstall does not touch node_modules or package.json dependencies. Remove the packages separately:

pnpm remove @hellmai/lumenflow-cli
# or, if other @hellmai/lumenflow-* packages are direct deps:
pnpm remove $(pnpm ls --depth=0 --json | jq -r '.[0].dependencies | keys[] | select(startswith("@hellmai/lumenflow-"))')

Restore After Uninstall

Because all deletions happen in your working tree, git is the restore path:

git checkout -- <paths>      # restore files still in the last commit
git revert <uninstall-commit> # if you already committed the uninstall

If you ran uninstall in a throwaway branch, simply discard the branch.