Rename the specgen binary to umbra-shroud, and migrate both package managers so hosts actually move #295

New issue

Open

opened 2026-08-16 04:09:29 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-16 04:09:29 +00:00

Member

Filed by Darren (director seat) at Kai's direction, 2026-08-16. Her name choice, my inventory.

The name

specgen becomes umbra-shroud. The umbra- prefix makes the relationship discoverable without a footnote: this binary ships from umbra/cmd/, and nothing in the current name says so.

Two problems the current name has beyond that:

spec is overloaded four ways. spec (the swagger input), specgen (this binary), specverb (the lock and half the docs), and .specgen/ (the guardfile project root) all mean different things. Working out whether specverb.lock pinned the spec or the engine cost real time tonight. Any replacement keeping spec keeps that collision.
gen undersells it. The binary does gen, lock, skew, build and run. Drift detection is arguably its best feature and the name hides it.

This is a binary rename, not a repo rename

Worth stating up front because it changes the cost. Umbra keeps its name and its URL. There is no repo transfer, no redirect, and no mark to redraw, so this does not belong in coilysiren/inbox#351's blocked-on-renames list the way cli-guard and ward-mcp did.

Inventory, checked rather than estimated

umbra - cmd/specgen, six docs/specgen-*.md, README, FEATURES
coilyco-flight-deck/agentic-os - 26 files, the SPECGEN_BIN env, three ward verbs (aosguard-lock, aosguard-build, aosguard-run), and the .specgen/ directory name
coilyco-flight-deck/homebrew-tap - Formula/specgen.rb
coilyco-flight-deck/scoop-bucket - bucket/specgen.json
coilysiren/lore - 2 files

The part that will bite: it is shipped on two package managers

A formula rename with no migration path means brew upgrade moves nobody. Every host keeps a binary called specgen, stops receiving updates, and nothing says so. The standing rule is to wait for the release pipeline on every host, and a rename without migration quietly makes that rule unsatisfiable.

So the rename is not done when the code renames:

Homebrew needs the formula renamed plus an oldname or alias so an installed specgen migrates on upgrade rather than being orphaned.
Scoop needs the same treatment for bucket/specgen.json.
A host that had specgen should end up with umbra-shroud without a human uninstalling anything.

Fix the residue from the last rename in the same pass

specverb.lock currently carries:

"cliGuard": "v0.142.0"

That field holds the umbra version, under the name the project had two renames ago. cli-guard no longer exists as a repo. If this rename lands without touching that field, the lock misdescribes itself in two directions at once.

That is also the lesson this rename should learn from: the previous one moved the repo and left its old name in a schema, where it has been quietly wrong ever since. Renames here leave residue, so the inventory is part of the work rather than a follow-up.

Do

cmd/specgen to cmd/umbra-shroud, and the six docs/specgen-*.md pages with it.
Rename the field in specverb.lock from cliGuard to something naming umbra, with whatever compatibility the loader needs to read an existing lock.
Homebrew formula rename plus migration.
Scoop manifest rename plus migration.
agentic-os: the 26 references, SPECGEN_BIN, the three ward verbs, and a decision on whether .specgen/ moves too. It is a directory name in a tracked path, so moving it is a wider diff than the rest combined and might reasonably stay.
coilysiren/lore, 2 files.

Acceptance

umbra-shroud --version works on a host that previously had specgen, reached by an ordinary brew upgrade with no manual uninstall.
The same for scoop.
No tracked file in any listed repo refers to a specgen binary except a deliberate compatibility shim.
specverb.lock names umbra rather than cli-guard, and an existing lock still loads.
ward exec aosguard-lock, aosguard-build and aosguard-run all work unchanged from a caller's point of view.

Not decided here

Whether .specgen/ follows. It is the guardfile project root discovered by --project-root, so renaming it touches every path reference in agentic-os for a directory nobody types by hand. Worth a deliberate yes or no rather than sweeping it in.

**Filed by Darren (director seat) at Kai's direction, 2026-08-16.** Her name choice, my inventory. ## The name `specgen` becomes **`umbra-shroud`**. The `umbra-` prefix makes the relationship discoverable without a footnote: this binary ships from `umbra/cmd/`, and nothing in the current name says so. Two problems the current name has beyond that: * **`spec` is overloaded four ways.** `spec` (the swagger input), `specgen` (this binary), `specverb` (the lock and half the docs), and `.specgen/` (the guardfile project root) all mean different things. Working out whether `specverb.lock` pinned the spec or the engine cost real time tonight. Any replacement keeping `spec` keeps that collision. * **`gen` undersells it.** The binary does `gen`, `lock`, `skew`, `build` and `run`. Drift detection is arguably its best feature and the name hides it. ## This is a binary rename, not a repo rename Worth stating up front because it changes the cost. Umbra keeps its name and its URL. There is **no repo transfer, no redirect, and no mark to redraw**, so this does not belong in `coilysiren/inbox#351`'s blocked-on-renames list the way `cli-guard` and `ward-mcp` did. ## Inventory, checked rather than estimated * **umbra** - `cmd/specgen`, six `docs/specgen-*.md`, README, FEATURES * **coilyco-flight-deck/agentic-os** - 26 files, the `SPECGEN_BIN` env, three ward verbs (`aosguard-lock`, `aosguard-build`, `aosguard-run`), and the `.specgen/` directory name * **coilyco-flight-deck/homebrew-tap** - `Formula/specgen.rb` * **coilyco-flight-deck/scoop-bucket** - `bucket/specgen.json` * **coilysiren/lore** - 2 files ## The part that will bite: it is shipped on two package managers A formula rename with no migration path means **`brew upgrade` moves nobody.** Every host keeps a binary called `specgen`, stops receiving updates, and nothing says so. The standing rule is to wait for the release pipeline on every host, and a rename without migration quietly makes that rule unsatisfiable. So the rename is not done when the code renames: * Homebrew needs the formula renamed **plus** an `oldname` or alias so an installed `specgen` migrates on upgrade rather than being orphaned. * Scoop needs the same treatment for `bucket/specgen.json`. * A host that had `specgen` should end up with `umbra-shroud` without a human uninstalling anything. ## Fix the residue from the last rename in the same pass `specverb.lock` currently carries: ```json "cliGuard": "v0.142.0" ``` That field holds the **umbra** version, under the name the project had two renames ago. `cli-guard` no longer exists as a repo. If this rename lands without touching that field, the lock misdescribes itself in two directions at once. That is also the lesson this rename should learn from: the previous one moved the repo and left its old name in a schema, where it has been quietly wrong ever since. Renames here leave residue, so the inventory is part of the work rather than a follow-up. ## Do 1. `cmd/specgen` to `cmd/umbra-shroud`, and the six `docs/specgen-*.md` pages with it. 2. Rename the field in `specverb.lock` from `cliGuard` to something naming umbra, with whatever compatibility the loader needs to read an existing lock. 3. Homebrew formula rename plus migration. 4. Scoop manifest rename plus migration. 5. agentic-os: the 26 references, `SPECGEN_BIN`, the three ward verbs, and a decision on whether `.specgen/` moves too. It is a directory name in a tracked path, so moving it is a wider diff than the rest combined and might reasonably stay. 6. `coilysiren/lore`, 2 files. ## Acceptance * `umbra-shroud --version` works on a host that previously had `specgen`, reached by an ordinary `brew upgrade` with no manual uninstall. * The same for scoop. * No tracked file in any listed repo refers to a `specgen` binary except a deliberate compatibility shim. * `specverb.lock` names umbra rather than cli-guard, and an existing lock still loads. * `ward exec aosguard-lock`, `aosguard-build` and `aosguard-run` all work unchanged from a caller's point of view. ## Not decided here Whether `.specgen/` follows. It is the guardfile project root discovered by `--project-root`, so renaming it touches every path reference in agentic-os for a directory nobody types by hand. Worth a deliberate yes or no rather than sweeping it in.

coilyco-ops added the

labels

2026-08-16 04:09:38 +00:00

coilyco-ops added the

role/ops

label

2026-08-17 01:42:35 +00:00

coilyco-ops referenced this issue