@jimhoyd/urlcode 0.4.0-alpha.2 → 0.4.0-alpha.3

package/docs/archive/2026-09-19/SPIKE-MONOREPO.md

@@ -0,0 +1,776 @@
+# Spike: consolidating core, auth, admin and ui into one repo
+
+> **Closed 2026-09-19: the migration is done, and this document is history.**
+>
+> `urlcode-ui`, `urlcode-auth` and `urlcode-admin` are workspace packages under
+> `packages/`, and all three have been released from this repository:
+> `@jimhoyd/urlcode-ui@0.1.0-alpha.6`, `@jimhoyd/urlcode-auth@0.1.0-alpha.6`,
+> `@jimhoyd/urlcode-admin@0.1.0-alpha.4`, each on the `alpha` dist-tag with
+> `latest` deliberately held behind. Core's tags are unchanged. The three
+> source repositories are gone.
+>
+> **The operational runbook is now
+> [docs/DEVELOPMENT-PIPELINE.md](../../DEVELOPMENT-PIPELINE.md) and
+> [docs/RELEASE-SECURITY.md](../../RELEASE-SECURITY.md).** Read those, not this.
+> Nothing below is an instruction.
+>
+> ### What the plan got wrong, for the next migration
+>
+> 1. **Its strongest argument was overstated.** "What consolidation would newly
+>    enforce" assumed the enforcing checks would follow the code. They did not:
+>    `check-guidance-claims.ts` had a hardcoded target list that could never
+>    match `packages/`, and `check-trust-model-prose.ts` was root-anchored, so
+>    package source comments and each package's `llms.txt` stayed unscanned.
+>    Consolidation bought Markdown coverage until both scripts were taught to
+>    discover workspace packages.
+> 2. **The real wins were the ones it never claimed.** CodeQL had never run on
+>    any of the three repositories, despite each `GOVERNANCE.md` saying it did;
+>    the first scan produced a high-severity finding in auth (a false positive,
+>    HIBP k-anonymity rather than password storage). Windows had never run
+>    either, and produced four genuine latent bugs.
+> 3. **Layout A has a cost the comparison missed.** Core is the repository root
+>    rather than a workspace member, so npm resolved the packages' core peer
+>    **from the registry** until each declared `file:../..`. Everything passed
+>    while building against a published core.
+> 4. **Mechanics #1 did not survive.** The repository allows only squash
+>    merges, so the ~130 imported commits collapsed into one and `git blame` on
+>    `main` resolves to the merge. That made archiving the source repositories
+>    load-bearing — and they were deleted instead. Their history survives only
+>    as verified bundles beside the earlier retirements.
+> 5. **Nothing was mentioned about releases, which is where the work was.**
+>    Four distinct release-path defects surfaced only by releasing: `--prefix`
+>    not isolating from workspace links, Changesets narrowing a peer range,
+>    the prepare script not building what it typechecks against, and the
+>    coordinator racing npm's propagation.
+>
+> The three open questions at the end were answered by doing it: `peers.json`
+> was deleted outright, `git subtree` was used over `filter-repo`, and the
+> core/monorepo naming overlap was never a problem in practice.
+
+
+> Maintainer update: monorepo work is starting now. The older proposal-only
+> status and instruction to postpone repository changes below are superseded.
+> Retired short-link packages and the deleted docs repository are historical
+> entries, not migration scope.
+>
+> **Correction (2026-09-19, later the same day): middleware is no longer
+> migration scope either.** The instruction this note used to carry —
+> "middleware moves in as its own package with its existing behavior; folding
+> it into core comes afterward" — was overtaken by events.
+> `jimhoyd-com/urlcode-middleware` has been **deleted**, and
+> `@jimhoyd/urlcode-middleware` unpublished from npm at `0.1.0-alpha.2`. There
+> is no `packages/middleware` to create and nothing to fold into core
+> afterward: per-route middleware was already native to core all along
+> (`docs/MIDDLEWARE.md`), and the deleted package only ever offered the same
+> behavior through the extension seam. Every "five repositories" count below
+> is now **four**: core, `urlcode-auth`, `urlcode-admin`, `urlcode-ui`.
+
+Status: migration direction accepted and work starting; completion is not claimed.
+The updated analysis from main is retained below.
+
+**Precondition re-surveyed 2026-09-19, after the cleanup PRs landed.** An
+earlier revision of this header said the coordinated cleanup PRs were open
+across core, auth, admin, UI and middleware, and told the reader to settle them
+before each package moves. They have since settled — core merged `#175` and
+`#176`, and a fresh survey reports **zero open pull requests across all four**
+in-scope repositories. Core holds open issues; `auth`, `admin` and `ui` report
+zero. Mechanics #0 is therefore satisfied again and mechanics #7 is again a
+no-op. Treat that as perishable and re-run it per repository immediately before
+that repository moves, exactly as mechanics #0 says. Trust by default and
+explicit sandbox choices remain unchanged.
+
+> **Update (2026-09-19) — reviewed against the live repositories, npm and the
+> checks that have landed since. Four things changed; the recommendation did
+> not.**
+>
+> 1. **Scope is five repositories, not six.** `urlcode-dynamic-link` was
+>    deleted rather than migrated, along with `urlcode-short` and
+>    `urlcode-docs` — all three unpublished from npm and their GitHub
+>    repositories removed. In scope: core, `urlcode-auth`, `urlcode-admin`,
+>    `urlcode-ui`, `urlcode-middleware`. **Superseded later the same day —
+>    `urlcode-middleware` was deleted too, making it four. See the correction
+>    at the top.**
+> 2. **The hard precondition is currently met.** Zero open pull requests *and*
+>    zero open issues across all five (surveyed 2026-09-19), so mechanics #0 is
+>    satisfied and mechanics #7 is a no-op. This window closes on its own.
+>    **Re-surveyed after the cleanup PRs landed: still zero open PRs, now
+>    across four repositories; core has since accumulated open issues. See the
+>    top of this document.**
+> 3. **The drift this plan opened with has already recurred** — see "The
+>    problem this is answering" below. It is now an observation, not a forecast.
+> 4. **A second argument exists that this document does not make:** the
+>    enforcing trust-model check cannot reach the four downstream repositories.
+>    See "What consolidation would newly enforce".
+>
+> Sections below carry their own dated notes where the text they replace is
+> kept for the record. Anything not marked still reads as originally written.
+
+Treat this the same way as the other `SPIKE-*.md` documents in this
+directory: a recorded decision trail for the maintainer to accept, amend or
+reject. **Superseded in part — the maintainer has since accepted the
+direction (see the top), so the plan below is committed scope, not a
+proposal.**
+
+## What this is not
+
+> **Superseded, and now factually false.** The paragraph below is kept because
+> it describes the state the plan was drafted in. It said "no git history has
+> been merged"; that stopped being true when `urlcode-ui` was merged in as
+> `packages/ui`. See "What has landed" immediately below for the current
+> state.
+
+This is not a recommendation to touch any of `urlcode`, `urlcode-auth`,
+`urlcode-admin` or `urlcode-ui` tonight. No git history has been merged, no
+package has been moved, no CI has been reconfigured. Everything below is a
+sequenced plan to review, not a changelog of what happened.
+
+## What has landed
+
+> **Added 2026-09-19.** This section is a changelog, not a plan. Everything
+> above it that reads as a proposal should be checked against this first.
+
+**All three extensions are in: `packages/ui`, `packages/auth`,
+`packages/admin`.** Sequencing steps 1-5 are done -- step 5 being void, since
+the package it named was deleted rather than migrated. Step 6 and the
+npm re-registrations have not happened, and nothing outward-facing has been
+done at all. The precondition was re-verified immediately before each move and
+held every time: zero open PRs, zero open issues.
+
+Suite sizes after the move, all green against core's working tree: core
+512/514 (2 pre-existing skips), auth 204, admin 65, ui 57 with none skipped.
+Auth and admin each lost their `peers.test.ts` along with the file it tested.
+
+Specifically:
+
+**A cost of layout A that this document does not mention, found on auth's
+move.** Core is the repository root rather than a workspace member, so npm does
+not link it as a workspace sibling: it resolved auth's `@jimhoyd/urlcode` peer
+from the **registry** instead, at the published `0.4.0-alpha.2`, which is 24
+commits behind this tree. Auth would have been built and tested against a
+published core while sitting next to the real one -- the exact drift this
+consolidation exists to remove, reintroduced by the consolidation itself, and
+silently. The fix took two attempts, and the first one failed in a way worth recording.
+A root `"overrides": {"@jimhoyd/urlcode": "file:."}` produced the right symlink
+on disk but wrote a lockfile entry resolving it to `packages/auth`, so
+`npm ci` rejected the tree outright -- caught by CI, not locally, because
+`npm install` tolerates the drift that `npm ci` refuses. Each package now
+declares `"@jimhoyd/urlcode": "file:../.."` as a devDependency instead, which
+is unambiguous.
+
+Both failure modes are invisible to the test suites: in the first, everything
+passed against a published core. So
+[`scripts/check-workspace-links.ts`](../scripts/check-workspace-links.ts)
+asserts in `npm run check` that every package declaring core as a peer
+resolves it to this repository's own `package.json`. Layout B would not have
+had this problem at all; it is a real, if small, entry on layout A's side of
+the ledger that the original comparison missed.
+
+Auth's own numbers, for the record: 206 tests passed against core's working
+tree at HEAD, so the 24-commit pin gap was stale bookkeeping and nothing more.
+204 remain after `peers.test.ts` was deleted with the file it tested.
+
+- `git subtree add --prefix=packages/<name>` for each, with the precondition
+  re-verified immediately before every move (zero open PRs, zero open issues).
+  On the branch, authorship history was preserved and `git blame` resolved
+  through the move. **It does not survive the merge -- see below.**
+
+### The merge squashed, and mechanics #1 did not survive it
+
+> **Decided 2026-09-19.** `jimhoyd-com/urlcode` allows squash merges only:
+> merge commits and rebase are both disabled, and the `Protect main` ruleset
+> requires linear history, which is *why* they are disabled. A
+> history-preserving merge was therefore not available without suspending that
+> rule, and the maintainer chose to keep linear history and accept the loss.
+
+Mechanics #1 says to preserve history "so `git log`/`git blame` on
+`packages/auth/src/auth.ts` still resolves to the real authorship history."
+On `main`, **it does not.** The 142 commits on the branch -- including roughly
+130 imported from the three source repositories -- collapsed into one squash
+commit, so every migrated file blames to that single commit.
+
+Two consequences follow, and the second is the important one:
+
+1. `git subtree add` bought nothing that a file copy would not have, *for
+   `main`*. It was not wasted: the branch history is what made each move
+   reviewable, and it is why the imported commits exist anywhere at all.
+2. **Archiving the three source repositories rather than deleting them is now
+   load-bearing, not a preference.** They are the only remaining copy of the
+   authorship history for `packages/ui`, `packages/auth` and `packages/admin`.
+   Step 6 already said archive rather than delete; that instruction has
+   stopped being about inbound links and redirects and become the retention
+   policy for the history itself. Deleting them would destroy it outright, the
+   way the September retirements did for the packages they withdrew -- and
+   unlike those, this code is still shipping.
+- The root `package.json` declares `"workspaces": ["packages/*"]`, and the root
+  `verify` script now runs each workspace's own `verify` — without that, ui's
+  57 tests silently stop running the moment it becomes a workspace.
+- Changesets is configured in `.changeset/`, with `fixed` and `linked` empty so
+  independent versioning is preserved. Core is not covered by it, because under
+  layout A core is the repository root rather than a workspace member.
+- **Mechanics #3 is done for ui: `peers.json` is gone**, along with
+  `scripts/peer-revisions.mjs` and the workflow that read them. ui's
+  cross-repository test resolves core from the repository root instead, so it
+  runs by default rather than skipping. There is no pinned peer revision left
+  to go stale -- a workspace package and its sibling are the same commit by
+  construction. ui had no `peers.test.ts`; `auth` and `admin` do, and theirs
+  will need deleting with the file.
+- **Mechanics #4 and #5 are done for ui.** `packages/ui/.github/` has been
+  removed rather than left inert: GitHub reads workflows, `CODEOWNERS`,
+  `dependabot.yml` and issue templates only from the repository root, so every
+  file in it was dead where it sat. Verification moved to core's `ci.yml`,
+  which now covers ui through the root `verify` on a 3x3 OS/Node matrix --
+  wider than the ubuntu-only workflow ui had of its own. Releases moved to
+  [`.github/workflows/release-ui.yml`](../.github/workflows/release-ui.yml).
+  Root `CODEOWNERS` already matched ui's (`* @jimhoyd`) so nothing was lost,
+  and Dependabot's npm entry at `/` covers workspaces from the root. The
+  cross-repository links in ui's docs are now relative, including
+  `docs/SPIKE-UI.md`'s link to the extension model review, which had been a
+  404 since `98b5659` archived its target -- independent of this migration.
+  ui's `package.json` `repository`/`homepage`/`bugs` name this repository, with
+  `repository.directory` set to `packages/ui`, since those ship to npm.
+
+**`pack-sources.mjs` is decided and done.** The two near-identical copies in
+`packages/auth/scripts/` and `packages/admin/scripts/` are replaced by one
+[`scripts/pack-sources.mjs`](../scripts/pack-sources.mjs) at the root. Its four
+repository paths and its `peers.json`-derived core pin are replaced by a single
+required `--revision`. The guarantee an operator verifies got *shorter and
+stronger*: one commit identifies core, ui, auth and admin simultaneously, where
+before it took four revisions plus trust that the `peers.json` pins agreed. What
+is given up is building a mix of revisions across packages, which was the drift
+vector this consolidation exists to remove. The step that installed each freshly
+built tarball as the next package's peer is gone too: the workspace resolves
+every sibling to this tree by construction, which is a stronger guarantee than
+installing tarballs built from it moments earlier, and
+`scripts/check-workspace-links.ts` enforces it.
+
+**Not done, and outward-facing -- the maintainer's to do:**
+
+1. **Re-register the npm trusted publishers**, all three under
+   `jimhoyd-com/urlcode`: `@jimhoyd/urlcode-ui` against
+   `.github/workflows/release-ui.yml`, `@jimhoyd/urlcode-auth` against
+   `release-auth.yml`, `@jimhoyd/urlcode-admin` against `release-admin.yml`
+   (mechanics #6).
+   The entry is pinned to a repository *and a workflow filename*, and the
+   filename had to change because core already owns `release.yml`. Until this
+   is done the publish step fails closed, which is correct behavior rather
+   than a bug: **ui cannot be released from here yet.**
+2. **Archive `jimhoyd-com/urlcode-ui`, `-auth` and `-admin`** (step 6)
+   -- but only after a release
+   from the new location has actually worked. Archive, do not delete: unlike
+   the September retirements, this code continues to live at a new path, so
+   the clone-URL redirect is the entire point.
+3. **Retag.** `git subtree add` did not carry ui's four `v0.1.0-alpha.*` tags,
+   and they are not re-creatable under the scheme decided above anyway. They
+   remain in the source repository until it is archived.
+
+### Corrections this migration forced on the plan
+
+Four claims above did not survive contact, and one of them was the document's
+strongest argument.
+
+1. **"What consolidation would newly enforce" was substantially overstated, and
+   is now true only because the checks were changed to make it true.** As
+   written, `check-trust-model-prose.ts` matched `PROJECT_ROOTS` against
+   root-relative prefixes, so `packages/ui/src/*.ts` comments were **not**
+   scanned; its `EXTRA_FILES` was root-only, so `packages/ui/llms.txt` -- the
+   most agent-facing file the package ships -- was scanned by neither check;
+   and `check-guidance-claims.ts` used a hardcoded ten-path `TARGETS` list that
+   could never reach a package at all. Consolidation on its own would have
+   bought Markdown coverage and nothing else. Both scripts now discover
+   workspace packages from disk, which was verified by planting violations in
+   `packages/ui/src/kit.ts` and `packages/ui/llms.txt` and confirming a
+   non-zero exit. File counts went 417 -> 467 and targets 10 -> 12.
+2. **"21 commits behind" was 24** by the time the move happened, and would have
+   kept drifting. Figures in this document go stale within a day; re-measure
+   rather than cite.
+3. **`git log <new path>` does not show pre-move history**, contrary to
+   mechanics #1. `git blame` does, and nothing is lost, but `git log
+   packages/ui/src/kit.ts` returns only the subtree-add commit because the
+   original 47 commits record the path as `src/kit.ts`. Use
+   `git log <old-sha> -- src/kit.ts`.
+4. **Two day-one breakages the plan did not anticipate.** Core's `eslint .`
+   reaches `packages/` immediately, and ui had never been linted: 10 errors on
+   the merge commit, plus more from generated `dist/` output once built,
+   because the root eslint ignores were root-anchored rather than `**/`-
+   anchored. Separately, `scripts/build-styles.mjs` hardcoded a package-local
+   `node_modules` path that does not exist once npm hoists devDependencies to
+   the workspace root. Both are fixed. Expect the same class of breakage from
+   `auth` and `admin`, which have 41 and 7 lint errors respectively and have
+   also never been linted.
+
+**A collision this document does not mention at all -- now settled.** Core and
+every extension trigger releases on `tags: ['v*']`, and their alpha tags
+literally overlap: ui carries `v0.1.0-alpha.2` through `-alpha.5`, admin
+`v0.1.0-alpha.1` and `-alpha.3`, auth `v0.1.0-alpha.1` through `-alpha.3`. In
+one repository, pushing a bare `v*` tag fires more than one release workflow.
+
+Decided: workspace packages release on Changesets' `<package name>@<version>`
+form, core keeps `v*`, and the two cannot collide because a scoped name starts
+with `@`. See [open decisions, "Accepted: per-package release
+tags"](OPEN-DECISIONS.md) for the reasoning and
+[`scripts/check-release-tags.ts`](../scripts/check-release-tags.ts), which
+fails `npm run check` if a future package workflow breaks the scheme. `ui`'s
+workflow has been moved onto it already, including the tag-to-version parsing
+that depended on the old `v` prefix.
+
+`git subtree add` does not carry tags, so none of ui's four came across. They
+would not be re-creatable under the old scheme anyway.
+
+## The problem this is answering
+
+Four repos (`urlcode`, `urlcode-auth`, `urlcode-admin`, `urlcode-ui`) already
+coordinate tightly — `auth`/`admin`/`ui` each pin an exact core revision in
+their own `peers.json`, and `docs/FRAMEWORK.md` describes them as one
+composed product, not four independent ones. Concretely observed cost of that
+coordination happening across four repos, from an evening spent reading all
+four:
+
+- **Observed and since fixed, which is the point rather than a counterpoint.**
+  When core landed trusted-by-default execution (`b3bde4e`), `urlcode-auth`
+  and `urlcode-admin` were both still pinning core at `50790d3a`
+  (`0.4.0-alpha.1`), predating it, and `urlcode-auth/SECURITY.md` still
+  carried a sentence ("sandboxed guest code") that assumed the old model.
+  Both have since been corrected — both repos now pin `d5e86017`, and that
+  sentence is gone. Nothing was ever broken in production by either.
+  The cost this plan is describing is not "drift goes unnoticed forever"; it
+  is that catching and fixing it took a manual pass across three separate
+  repositories, with nothing structural to catch it automatically — no
+  mechanism flags a downstream repo's prose or pin as stale when an upstream
+  contract changes underneath it. That pass has to be repeated by hand on
+  every future contract change, for every downstream repo, indefinitely.
+  Consolidation removes the class of work, not just this instance of it.
+
+  > **Update (2026-09-19): it recurred, which settles the argument.** The
+  > correction recorded above held for roughly one day. `urlcode-auth`,
+  > `urlcode-admin` and `urlcode-ui` all still pin core at `d5e86017`
+  > (2026-09-18), now **21 commits behind core's `main`** — a span that
+  > includes the trusted-by-default propagation in `db375bf` and the
+  > retirements in `10c2439`. Nothing is broken in production again, and that
+  > is again beside the point: the manual pass this document described as
+  > repeating indefinitely repeated within twenty-four hours of being
+  > performed. This is no longer a predicted cost.
+- Two more repos, planned in `docs/SPIKE-CORE-LAYERING.md` and originally
+  drafted here as "not yet created," turned out to already exist by the time
+  this doc was reviewed: `urlcode-dynamic-link` (7 commits, Phase 2 already
+  implemented, `v0.1.0-alpha.1` released) and `urlcode-middleware` (5 commits,
+  implemented, `v0.1.0-alpha.1` released), each with its own real commit
+  history, release workflow and open issues. That raises the
+  actively-coordinated repo count from four to six today, not hypothetically
+  — before this plan even accounts for `urlcode-template`, `urlcode-short`,
+  `urlcode-docs`, `urlcode-cloud` and `homebrew-urlcode`. It also means
+  "create them directly in the monorepo" (this doc's original framing) is no
+  longer available for these two — they now need the same history-preserving
+  migration as `auth`/`admin`/`ui`, covered in "Migration mechanics" below.
+
+None of this is a defect in any one repo. It's the accumulating tax of
+coordinating tightly-coupled, independently-versioned packages across
+separate git histories, issue trackers and CI pipelines by hand.
+
+## Scope: what moves, what doesn't
+
+Decided (see conversation this spike is drafted from):
+
+**In scope — originally six existing repos, all with real history, folded
+into one repo as workspace packages. Two of the six were deleted instead of
+migrated, leaving four:**
+
+| Repo today | Becomes |
+|---|---|
+| `urlcode` (core) | `packages/core` (or repo root stays core-shaped, TBD in "Layout options" below) |
+| `urlcode-auth` | `packages/auth` |
+| `urlcode-admin` | `packages/admin` |
+| `urlcode-ui` | `packages/ui` |
+| ~~`urlcode-dynamic-link`~~ | **No longer applicable — repository deleted 2026-09-19, not migrated.** See the note below. |
+| ~~`urlcode-middleware`~~ | **No longer applicable — repository deleted 2026-09-19 at `0.1.0-alpha.2`, not migrated.** Per-route middleware is native to core; see the correction at the top. |
+
+> **Update (2026-09-19): five, not six.** `urlcode-dynamic-link` was created,
+> released `v0.1.0-alpha.1`, and deleted within days. Read as evidence rather
+> than as a lost migration target, it is the sharpest data point this document
+> has: standing up a repository per extension was costly enough that one of
+> them was unwound outright rather than maintained. The section "Why six, and
+> not four" below should be read as "why five, and not four"; its argument
+> about `middleware` having already paid the coordination cost was unaffected
+> at the time — though `middleware` was itself deleted later the same day, so
+> the pattern this note reads as a one-off turned out to repeat.
+
+**Explicitly out of scope — three live repositories, each for a distinct, real
+reason, not just "left for later":**
+
+> **Update (2026-09-19):** this list was four. Two of its entries no longer
+> exist: `urlcode-short` and `urlcode-docs` were both deleted, so neither is a
+> candidate for anything. The three that remain — `homebrew-urlcode`,
+> `urlcode-cloud`, `urlcode-template` — are unaffected, and their reasons hold
+> exactly as written.
+
+- **`homebrew-urlcode`** — cannot move. Homebrew tap conventions require a
+  repo literally named `homebrew-<name>`; this is an external platform
+  constraint, not a project choice.
+- **`urlcode-docs`** — `AGENTS.md` is explicit that public documentation is
+  "authored there directly," deliberately separate from code, "no longer
+  generated from this repository." Folding it in would reverse a stated,
+  recent decision, not follow one.
+
+  > **Update (2026-09-19): resolved — the repository is deleted.** The decision
+  > quoted above was reversed, and then `urlcode-docs` was unpublished and
+  > **removed from GitHub**, not merely archived. Documentation is authored in
+  > this repository's `docs/`, and `AGENTS.md` no longer sends pages anywhere
+  > else — see [open decisions, item 6](OPEN-DECISIONS.md). This entry is kept
+  > only so the reversal is legible; there is nothing left to include or
+  > exclude.
+- **`urlcode-cloud`** — a separately-lifecycled hosted product (private
+  repo); its release cadence and access model have no reason to match a
+  library monorepo's.
+- **`urlcode-template`** (and, when it existed, `urlcode-short`) — an
+  example/starter project, not a library package. Mixing "things you
+  `npm install`" with "things you `git clone` as a starting point" in one
+  workspace is a different kind of repo than what this spike is solving for.
+  `urlcode-short` was deleted on 2026-09-19; the reasoning survives it and
+  still governs `urlcode-template`, which remains out of scope.
+
+## Why five, and not four — resolved: it is four
+
+> **Update (2026-09-19):** written as "why six", then narrowed to five when
+> `dynamic-link` was deleted. `middleware` has since been deleted as well, so
+> the answer is **four**, and this section is now entirely historical. It is
+> kept because the reasoning is what the outcome refutes: the argument below
+> was that `link` and `middleware` had already paid the coordination cost and
+> should therefore be folded in rather than left outside the fix. Both were
+> instead withdrawn altogether. That is a third possible response to the
+> coordination cost this document is about — not "consolidate it" and not
+> "keep paying it", but "stop shipping the thing" — and it is the one that
+> actually happened, twice. Worth weighing before the next extension gets its
+> own repository.
+
+`link` and `middleware` were extracted *out* of core specifically so core
+stays "the smallest thing that is still a complete product on its own"
+(`docs/SPIKE-CORE-LAYERING.md`). Both are now real, shipped repos: they
+already paid the coordination cost this spike is trying to remove —
+`urlcode-dynamic-link`'s and `urlcode-middleware`'s own `peers.json`-style
+pins against core, their own CI, their own docs that can drift the same way
+`urlcode-auth/SECURITY.md` already did. Folding them into this consolidation
+alongside `auth`/`admin`/`ui` stops that from compounding further, rather
+than leaving two more repos outside the fix.
+
+## Layout: decided — option A
+
+**A. Root repo is core, extensions live under `packages/`.**
+```
+urlcode/
+  src/            # core, unchanged in place
+  packages/
+    auth/
+    admin/
+    ui/
+```
+Lowest-friction for core's own history (nothing moves), but makes "core" and
+"the monorepo" the same name, which may read as core absorbing the
+extensions rather than the extensions and core coexisting as peers — worth a
+naming discussion given `AGENTS.md`'s "Core never imports them" independence
+framing.
+
+**B. Everything moves under `packages/`, including core — considered, not
+chosen.** Would have been symmetric and avoided the naming overlap noted
+above, at real cost: core's own history would need to move too, and every
+external reference to `urlcode`'s current repo path (`docs/`, READMEs
+elsewhere, the `@jimhoyd/urlcode` package's repository field, CI badges,
+this evening's own `peer-camera`/`peer-eyes` citations) would need updating.
+Decided against for exactly that reason.
+
+**Decided: (A).** Core's repo and history stay exactly where they are; the
+extension packages move to it — three of them, `auth`, `admin` and `ui`,
+after the `dynamic-link` and `middleware` deletions. The one open item this
+still leaves,
+worth a short naming discussion rather than blocking anything: "core" and
+"the consolidated repo" now share a name, which could read as core absorbing
+the extensions rather than the two coexisting as independent packages
+(`AGENTS.md`'s "Core never imports them" framing still holds in code either
+way — this is a naming-perception question, not a contract question).
+
+## Migration mechanics, per repo
+
+For each of `urlcode-auth`, `urlcode-admin` and `urlcode-ui` — three repos
+with real history, joining core, which stays in place (as of 2026-09-19;
+drafted as five, before `urlcode-dynamic-link` and then `urlcode-middleware`
+were deleted):
+
+0. **Drain open pull requests first — a hard precondition, not a courtesy.**
+   Before a repo is migrated, it must have zero open PRs (and no unmerged
+   release branch). A PR open against the source repo at the moment its code
+   moves is stranded: its branch targets a `main` that no longer receives
+   code, its diff is written against paths (`src/…`) that no longer exist at
+   that location, and re-creating it against the consolidated repo means
+   rebasing onto a different repository and a new path prefix
+   (`packages/<name>/src/…`) by hand. GitHub cannot retarget a PR across
+   repositories. So for each repo, in order: stop merging new work, merge or
+   close what is open, confirm `gh pr list`/the API reports none, then
+   migrate. Any PR that cannot be merged in time should be closed with its
+   branch preserved and re-opened against the consolidated repo afterwards —
+   a deliberate choice recorded on the PR, not an accident discovered later.
+   This is also the real reason to pick a quiet window for the migration
+   rather than a busy one: the cost of this step scales with how much is
+   in flight.
+
+   > **Update (2026-09-19): this precondition is met right now.** Surveyed
+   > across all five in-scope repositories: `urlcode`, `urlcode-auth`,
+   > `urlcode-admin`, `urlcode-ui` and `urlcode-middleware` each report **zero
+   > open pull requests**, and all but core report zero open issues (core holds
+   > `#168` and `#58`, neither of which is a migration blocker). Nothing is in
+   > flight anywhere. This is the quiet window this step asks for, and it is not
+   > a stable state — it closes the moment work resumes on any of the five.
+   >
+   > **Re-surveyed later the same day, after the cleanup PRs opened and
+   > merged:** four in-scope repositories now (`urlcode-middleware` is
+   > deleted), still **zero open pull requests across all four**. `auth`,
+   > `admin` and `ui` report zero open issues; core's open-issue count has
+   > grown past the two named above and none of them block migration either.
+   > The window described as closing on its own has so far reopened each time
+   > — which is an argument for re-running the survey, not for trusting any
+   > recorded figure in this document.
+1. **Preserve history with `git subtree add` or `git filter-repo` +
+   merge**, not a fresh copy — so `git log`/`git blame` on
+   `packages/auth/src/auth.ts` still resolves to the real authorship history
+   from `urlcode-auth`, and so a future "actually, let's give this its own
+   repo back" is a clean `git filter-repo` extraction, not archaeology.
+   `git subtree` is the lower-risk default (reversible, no force-push
+   required on the source repos); `git filter-repo` gives cleaner resulting
+   history at the cost of being a one-way rewrite of the joining repo's
+   local copy (the original `urlcode-auth` GitHub repo is untouched either
+   way — this only rewrites what gets pulled in).
+2. **npm workspace restructuring**: `package.json` at the monorepo root gets
+   `"workspaces": ["packages/*"]` (the same shape `peer-camera` already
+   uses); each `packages/<name>/package.json` keeps its own name/version,
+   independently publishable — this is what preserves "independently
+   versioned packages" as a property, not something this migration gives up.
+   **Decided: [Changesets](https://github.com/changesets/changesets) for the
+   release flow, not Nx or Turborepo.** A changeset is a small, bounded,
+   git-diffable markdown file (package name + semver bump + description) —
+   cheap and low-risk for an agent or a human to generate correctly, easy
+   for CI to verify mechanically ("does every touched package have one"),
+   and it's the deliberate checkpoint that stops local workspace-linked
+   development (testing against a sibling package's unreleased state, which
+   is now the default once auth/admin/ui sit next to
+   core) from silently becoming a real release. Nx/Turborepo were considered
+   and set aside: both add a much larger, more inference-heavy configuration
+   surface (task graphs, remote caching semantics) that's a bigger, more
+   opaque thing to get wrong than this repo's four packages currently need —
+   plain `npm test -w packages/auth`-style workspace scoping already covers
+   what this size of repo actually requires. Revisit only if the package
+   count grows enough that rebuild/retest time becomes a real problem.
+3. **`peers.json` becomes unnecessary for the three that moved** — a
+   workspace package can depend on a sibling workspace package directly
+   (`"@jimhoyd/urlcode": "workspace:*"` or npm's equivalent), which is
+   inherently always in sync, no separate pin file, no drift possible by
+   construction. `peers.json`-the-mechanism might still matter if any
+   *external* consumer needs a reviewed-revision pin story — worth deciding
+   explicitly rather than silently dropping the safeguard.
+4. **CI consolidation**: one `verify.yml` (or similar) with
+   path-filtered jobs per package, replacing four separate workflow files.
+   `CODEOWNERS` can still express per-package ownership within one repo
+   (path-scoped rules), so "who reviews auth changes" doesn't have to
+   become "everyone reviews everything."
+5. **Docs cross-references**: every `EXTENSIONS.md` links into another repository-
+   style cross-repo link in `auth`/`admin`/`ui`'s current docs becomes a
+   same-repo relative link once consolidated — this is a real cleanup
+   opportunity, not just migration overhead, since it directly targets the
+   "docs silently drifted apart" problem this spike opened with.
+6. **Re-register npm Trusted Publishing per package.** Every repo's
+   release workflow publishes via OIDC trusted publishing, no long-lived npm
+   token (`docs/SPIKE-CORE-LAYERING.md`'s governance section, confirmed by
+   `urlcode-middleware`'s own "Add trusted-publishing release workflow"
+   commit). That trust is registered on npmjs.com per package, pinned to an
+   exact GitHub repo + workflow filename (+ optional environment) — it does
+   not follow the code when the repo path changes. Each of
+   `@jimhoyd/urlcode-auth`, `-admin` and `-ui` needs its
+   npmjs.com trusted-publisher entry updated to the new repo and new workflow
+   path *before* that package's first release from the consolidated location,
+   or the publish step fails closed (correctly — not a security gap, just an
+   ordering dependency this plan needs to carry explicitly rather than
+   discover at release time).
+7. **Issue migration — decided: recreate open issues in the consolidated
+   repo, not leave-and-link.** GitHub doesn't move issues across repos
+   natively, so this means bulk-recreating each open issue at the new
+   location with a back-link to the original (closed with a pointer) rather
+   than leaving it where it is.
+
+   > **Update (2026-09-19): currently a no-op — there is nothing to
+   > recreate.** `urlcode-auth`, `urlcode-admin` and `urlcode-ui` all report
+   > **zero open issues**. Middleware's two, which this step was written
+   > around, were both closed before its repository was deleted (`#1`,
+   > `sandbox: true` unsupported, and `#3`, the vendored core tarball), along
+   > with a later `#4`. Those issue links no longer resolve — the deletion
+   > took the tracker with it — but the issue bodies were captured to
+   > `urlcode-middleware-issues.json` alongside the code bundle, so the
+   > content survives even though the URLs do not. `urlcode-dynamic-link`'s
+   > tally is equally moot: that repository is gone too. The decision above
+   > stands as policy for whatever is open at migration time; the concrete
+   > scope it enumerated has emptied out. Re-survey immediately before
+   > migrating rather than trusting this line.
+
+   The original scope, for the record:
+
+   > `auth`, `admin` and `ui`'s own open-issue counts weren't re-audited here,
+   > but `urlcode-dynamic-link` and `urlcode-middleware` were, since they're
+   > the two repos whose "does this even apply" status changed mid-conversation:
+   > `urlcode-dynamic-link` had 0 open issues — nothing to migrate.
+   > `urlcode-middleware` had 2 open issues to recreate, `#1`
+   > ("`sandbox: true` is not supported — needs its own QuickJS/WASM worker
+   > pool") and `#3` ("Remove vendored core tarball once `@jimhoyd/urlcode`
+   > 0.4.0-alpha.2+ is published to npm"). Both were to move to the
+   > consolidated repo's tracker when the merge actually happened, each closed
+   > in its original location with a link to the new issue.
+
+## What consolidation would newly enforce
+
+> **Added 2026-09-19.** This section did not exist when the spike was drafted,
+> because the checks it describes did not exist either. It is the strongest
+> argument in the document.
+
+Since this plan was written, two checks landed in `npm run check`, and both
+**fail CI** rather than reporting:
+
+- [`scripts/check-trust-model-prose.ts`](../scripts/check-trust-model-prose.ts)
+  rejects prose describing the pre-`0.4.0-alpha.2` trust model as current.
+  Since `db375bf` it reaches well past Markdown: comments in `src/`,
+  `scripts/`, `examples/`, `starters/`, `recipes/` and `benchmarks/`, plus
+  `llms.txt`/`llms-full.txt`, and it cross-checks that a project whose prose
+  claims isolation actually declares `sandbox: true` somewhere in its YAML.
+- [`scripts/check-guidance-claims.ts`](../scripts/check-guidance-claims.ts)
+  rejects agent-facing guidance that contradicts
+  `schemas/urlcode.schema.json` — including the inverse case, guidance calling
+  a field invented when the schema defines it
+  ([historical decisions, item 7](archive/2026-09-19/OPEN-DECISIONS.md)).
+
+**Both stop at this checkout.** The specific failure this document opens with —
+`urlcode-auth/SECURITY.md` asserting "sandboxed guest code" after core inverted
+the default — sits in a file that neither check can see, and cannot see while
+`auth` lives in its own repository. The same is true of `admin` and `ui`.
+It was also true of `middleware`, whose repository was deleted before the
+question could be settled either way.
+
+That reframes what consolidation buys. The original case was that it removes a
+class of manual coordination work. The stronger case, available only now, is
+that it places three packages' prose under an **existing, working, enforcing
+correctness gate** for the contract most likely to be misdescribed downstream —
+trusted-by-default execution, which is precisely where the observed drift
+happened. No other proposal on the table extends that check's reach; writing a
+cross-repository variant of it would mean building and maintaining a CI job that
+clones three repositories on every core change, which is the coordination cost
+again wearing a different hat.
+
+One related gap, unchanged: `npm run check:downstream-skills` is advisory and
+sits outside both `check` and `verify`, consistent with
+[historical decisions, item 9](archive/2026-09-19/OPEN-DECISIONS.md).
+The cleanup review has since adjudicated the template's skill drift and prepared
+aligned copies in its draft PR; the report itself remains advisory.
+
+## What this preserves, unchanged
+
+- **The trust/extension model itself.** `packages/auth` published from the
+  monorepo is exactly as separate a package, with exactly the same
+  `RuntimeExtension` contract, revision-pinning and operator-registration
+  requirements, as `urlcode-auth` published from its own repo today. This
+  spike changes where the source lives, not what the extension mechanism
+  guarantees.
+- **Independent versioning and release cadence per package** — a monorepo
+  with workspaces is not "one version number for everything."
+
+## What this gives up, honestly
+
+- **Per-repo maturity gating.** `docs/SPIKE-CORE-LAYERING.md` records that
+  `auth`/`admin`/`ui` used a "`private: true` until reviewed" pattern before
+  their first public release, and that the two new repos are deliberately
+  *not* following that pattern ("published public from the start"). A
+  monorepo can't easily make one folder private and another public — the
+  repo-level visibility setting is all-or-nothing on GitHub. Once
+  consolidated, "private until reviewed" stops being available as a pattern
+  for whatever the next extension after `middleware`/`dynamic-link` turns
+  out to be, unless it's built in yet another separate private repo first
+  and merged in later — which reintroduces a version of the coordination
+  cost this spike is trying to remove, just for pre-release work instead of
+  ongoing maintenance.
+- **"Fork just one piece" stops being a plain `git clone` — but scoped to a
+  narrow audience, not every auth user.** `SPIKE-AUTH.md` names forkability
+  as a deliberate design goal specifically for `auth`. It's important not to
+  overstate who this actually affects: a developer customizing auth's look
+  or copy (theme, relabeling, `extra.css`, a shadowed template) works
+  entirely inside *their own* project repo via the `ui` extension's layering
+  system (`ui/copy`, `ui/extra.css`, `ui/templates`) — they never clone or
+  fork `urlcode-auth` at all, install it from npm like any dependency, and
+  this migration changes nothing for them. The friction increase applies
+  only to the much narrower case of someone changing auth's actual *logic*
+  (a new sign-in method, different session semantics) — something the
+  layering system can't express because it's behavior, not presentation.
+  For that persona, forking just the auth package post-consolidation means a
+  `git filter-repo`-style history extraction instead of `git clone
+  jimhoyd-com/urlcode-auth` — solvable, but a real step up in friction, for
+  a small population, not the common path.
+- **Blast radius of a bad CI run.** One consolidated CI means a
+  misconfigured job can, in principle, block merges across all four
+  packages at once, where today a broken `urlcode-ui` pipeline can't stop an
+  unrelated `urlcode-auth` merge. Path-filtered jobs mitigate this but don't
+  eliminate it the way full repo separation does.
+
+## Sequencing, if this is accepted
+
+1. Decide layout (A vs. B above) and confirm the out-of-scope list.
+2. **Check open pull requests across all three joining repos before starting,
+   and again per repo immediately before its own migration** (mechanics #0). A
+   repo with anything open is not ready to move. Doing this as a survey first
+   also sizes the whole migration honestly: the number of in-flight PRs is the
+   real scheduling constraint, not the git mechanics.
+
+   > **Update (2026-09-19):** surveyed — zero open pull requests across all
+   > five repositories including core, and zero open issues outside core. The
+   > survey this step asks for has been done once and came back clean. Re-run
+   > it rather than relying on that, since it goes stale the moment work
+   > resumes. **It did go stale, twice over, within the same day:** the cleanup
+   > PRs opened and merged, and `urlcode-middleware` stopped existing. The
+   > current figure is zero open PRs across four repositories — see the top
+   > of this document, and re-run it again anyway.
+3. Migrate `urlcode-ui` first (fewest inbound dependents — `auth`/`admin`
+   both depend on it, nothing depends on them), proving the subtree +
+   workspace mechanics on the lowest-risk package. Re-register its npm
+   trusted publisher (mechanics #6) before cutting its first release from
+   the new location — treat this as part of "done," not a follow-up.
+4. Migrate `urlcode-auth`, then `urlcode-admin` — same re-registration step
+   each time.
+5. ~~Migrate `urlcode-middleware`.~~ **Void — nothing to migrate.**
+
+   > **Update (2026-09-19):** this step read "migrate `urlcode-dynamic-link`,
+   > then `urlcode-middleware`," and carried their issue tallies. Both halves
+   > are now void: each repository was deleted rather than migrated. The
+   > migration therefore ends at step 4, with `ui`, `auth` and `admin` moved
+   > and core in place. No `packages/middleware` is created, and no
+   > trusted-publisher entry is re-registered for `@jimhoyd/urlcode-middleware`
+   > — that package is unpublished.
+6. Retire (archive, don't delete — GitHub redirects an archived repo's clone
+   URL) the three now-empty source repos, with their READMEs pointing at the
+   new location.
+
+   > **Update (2026-09-19): "archive, don't delete" now has a counter-example
+   > in this project's own history, and it is worth weighing rather than
+   > restating.** `urlcode-dynamic-link`, `urlcode-short` and `urlcode-docs`
+   > were all **deleted outright**, so their clone URLs and every inbound link
+   > to them 404 with no redirect; the only surviving copies are verified
+   > `git bundle`s held locally (`fd9dc84`), which preserve the code but not
+   > the issues, the pull request history or any inbound URL. That was
+   > defensible for repositories whose code was being withdrawn entirely — and
+   > it still cost a citation: `urlcode-docs#17` is quoted as evidence in
+   > [historical decisions, item 7](archive/2026-09-19/OPEN-DECISIONS.md) and no longer resolves. It is a different case from a
+   > repository whose code continues to live at a new path, which is what this
+   > step covers and where the redirect is the entire point. Keep the
+   > archive-don't-delete rule here, and note explicitly that it diverges from
+   > what was done during the September 2026 retirements — the two situations
+   > are not the same and the precedent should not be read across.
+
+## Open questions for the maintainer, not answered here
+
+- Does `peers.json`'s reviewed-pin discipline need an equivalent for any
+  external (non-workspace) consumer, or does workspace-linking fully replace
+  its purpose?
+- `git subtree` vs. `git filter-repo` for history preservation — a real
+  tradeoff between migration safety and final history cleanliness, worth a
+  deliberate call rather than defaulting.
+- The naming-perception question from "Layout: decided — option A" above
+  (core's repo and the consolidated repo sharing a name) — worth a short
+  discussion, not blocking.