docs(cli): re-anchor the dead tracker citations in packages/cli/src to the commits that decided them, and the source-hashes header at its producer

.changeset/cli-provenance-anchors.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/cli': patch
+---
+
+Provenance comments in `@objectstack/cli` were re-anchored
+
+Comment and docblock lines under `src/` that cited tracker numbers which no
+longer resolve on GitHub now cite the commit in this repository's history that
+decided the matter, and say in their own words what was decided. Two strings
+move with them: the `os i18n extract --source-hashes` help text now says what
+the provenance companion records instead of citing a number, and the header
+that flag writes into each `<locale>.source-hashes.generated.ts` cites the
+commit that introduced the companion. No command, flag, exit code, error code,
+type, export or runtime behaviour changes.

packages/cli/src/commands/cloud/login.ts

@@ -12,7 +12,7 @@
  * ## `--json` here is NDJSON — a declared exception, same as `os login` (#6730)
  *
  * Everywhere else in this CLI `--json` means "stdout is exactly one JSON
- * document" (#6217). Both device-flow login commands are declared exceptions to
+ * document" (commit 2b641ddd4). Both device-flow login commands are declared exceptions to
  * that, and they are the SAME exception: one compact JSON document per line.
  *
  * ### What was broken

packages/cli/src/commands/compile.ts

@@ -228,7 +228,7 @@ export default class Compile extends Command {
       // one. See `printAuthoringAdvisories` for the measurement.
       printAuthoringAdvisories(ruleAdvisories);
     };
-    // [#12125] The ADR-0087 D2 conversion notices, hoisted for the SAME reason
+    // [commit 79cf692b0] The ADR-0087 D2 conversion notices, hoisted for the SAME reason
     // and under the SAME ruling as the four lists above — one field over. The
     // notices were computed at step 2 (below) and reached the terminal SUCCESS
     // payload alone, so all nine failure exits dropped a list already in hand.

packages/cli/src/commands/create.ts

@@ -38,7 +38,7 @@
  * ObjectStack is a developer tool, so a documented developer-facing command has
  * to work for the developer who follows the docs. This command is documented on
  * four public doc pages (`deployment/cli`, `plugins/index`, the two
- * `protocol/kernel` pages) and, until #14824, every one of those readers got a
+ * `protocol/kernel` pages) and, until commit cf6b67164, every one of those readers got a
  * project that CANNOT INSTALL:
  *
  *   - the emitted `package.json` declared `@objectstack/spec` and
@@ -81,7 +81,7 @@
  *
  * ## The emitted package NAME follows the placement too (#15530)
  *
- * The audience decides the name, and #14824 moved the audience without moving
+ * The audience decides the name, and commit cf6b67164 moved the audience without moving
  * the name: the standalone default kept stamping `@objectstack/plugin-<name>`
  * — a scope the developer it now scaffolds for cannot publish to — onto every
  * project, with the emitted README telling them to install it from there. The
@@ -321,9 +321,9 @@ function pluginDirName(name: string): string {
  * ## Why the standalone name is unscoped
  *
  * `@objectstack` is a scope the developer this command scaffolds FOR cannot
- * publish to. Until #14824 that was arguably fine, because the default output
+ * publish to. Until commit cf6b67164 that was arguably fine, because the default output
  * landed inside this monorepo, where every sibling really does carry the scope.
- * That ruling pointed the default at the developer's own directory and the name
+ * That commit pointed the default at the developer's own directory and the name
  * did not move with the audience — so the standalone emission stamped a scope
  * its owner does not own onto every project generated from it. ⚠️ Nothing in
  * this repository can see that: the name is never resolved from a registry

packages/cli/src/commands/database-driver-allowlist.pin.test.ts

@@ -36,10 +36,10 @@
  * `start.ts` and once in `dev.ts`, and that duplication is exactly how the two
  * can drift apart from each other as well as from the resolver.
  *
- * SCOPE (#6860 vs #6345): this pins the CANONICAL kinds — the `driverId` values
+ * SCOPE (#6860 vs commit e2798fab7): this pins the CANONICAL kinds — the `driverId` values
  * the resolver produces. The resolver also accepts aliases (`pg`, `mysql2`,
  * `libsql`, `mingo`, `wasm`, …) which the flag deliberately does not offer;
- * converging that vocabulary is #6345's job, and this pin is written so it does
+ * converging that vocabulary was commit e2798fab7's job, and this pin is written so it does
  * not prejudge it — an alias collapses to its canonical id and is not demanded
  * of the flag.
  */
@@ -101,7 +101,7 @@ function candidateTokens(): string[] {
  * is supplied so it resolves normally; the catch is kept so the derivation
  * survives another kind growing the same "recognized but unusable" shape.
  *
- * `err.recognized` is what keeps that catch honest (#6345). The resolver now
+ * `err.recognized` is what keeps that catch honest (commit e2798fab7). The resolver now
  * ALSO throws `UnsupportedDriverError` for a spelling nothing claims — the CLI
  * half of "both hosts refuse the same input", which replaced a silent fall-through
  * to the dev SQLite default. Reading `driverType` off that error would report the

packages/cli/src/commands/database-driver-flag-derivation.test.ts

@@ -24,7 +24,7 @@
  * Deriving the flag from the CONFIG-CONTRACT face (`DRIVER_ID_ALIASES` /
  * `resolveDriverId`) instead of the SELECTION face would offer `sqlite3`,
  * `better-sqlite3`, `mariadb` and `inmemory` — spellings neither boot host has
- * ever accepted as a selection (#6345 fixes the selection face as the union of
+ * ever accepted as a selection (commit e2798fab7 fixes the selection face as the union of
  * what the two hosts accepted the day the ruling was written). The last case here
  * drives oclif's real parser to prove they are still refused at parse time.
  */

packages/cli/src/commands/doctor-organizations-message-spelling.test.ts

@@ -6,9 +6,9 @@
  *
  * ── What this closes ─────────────────────────────────────────────────────
  *
- * PR #12463 (#12151) single-sourced every operator-facing occurrence in
+ * Commit 27b690272 (PR #12463) single-sourced every operator-facing occurrence in
  * `serve.ts` onto `Serve.ORGANIZATIONS_RUNTIME_PKG` and pinned what those
- * messages render. `doctor.ts` sat outside that card's file surface and kept
+ * messages render. `doctor.ts` sat outside that commit's file surface and kept
  * its own bare `@objectstack/organizations` literal inside
  * `TENANCY_POSTURE_FIX_HINTS`, under no check of any kind — so a roster-key
  * rename left `os doctor` printing a package name that boot no longer

packages/cli/src/commands/environments/environments.test.ts

@@ -77,7 +77,7 @@ describe('os environments commands', () => {
 });
 
 /**
- * Pin (#10967): every `examples` entry on EVERY CLI command source names a
+ * Pin (commit e4a71d418): every `examples` entry on EVERY CLI command source names a
  * command id THIS CLI ACTUALLY REGISTERS.
  *
  * ## The failure this exists to refuse
@@ -94,7 +94,7 @@ describe('os environments commands', () => {
  * exactly as before while any `examples` string spelling the OLD topic
  * silently stops being true — not a parse error, not a type error, nothing
  * a build catches. A user who copy-pastes the stale line hits `Error:
- * Command projects:bind not found.` (exit 2). That is the shape #10967
+ * Command projects:bind not found.` (exit 2). That is the shape commit e4a71d418
  * fixed under `environments/*.ts`; this pin targets the MECHANISM (an
  * example naming an id this CLI does not register), not the literal string
  * `os projects`, so it keeps working for a topic nobody has renamed yet —
@@ -123,7 +123,7 @@ describe('os environments commands', () => {
  * ## Population: EVERY command source, via AST — not via `import`
  *
  * The property is checked against every non-test file under
- * `packages/cli/src/commands/**`, not just the five #10967 touches — a
+ * `packages/cli/src/commands/**`, not just the five commit e4a71d418 touched — a
  * five-file population is exactly the set that is already correct, so it
  * cannot catch the defect class returning anywhere else (it did not catch
  * it in `register.ts`/`whoami.ts`/`logout.ts`, discovered by hand below).
@@ -157,23 +157,23 @@ describe('os environments commands', () => {
  * `examples` USED TO say `os auth register` / `os auth whoami` / `os auth
  * logout`, though no `auth` topic has ever existed for them (confirmed via
  * `--help`: `Error: Command auth:whoami not found.`) — the same defect
- * class as #10967, found by scanning the whole tree, but not #10967's to
- * fix (outside its dispatched file surface). Filed as #11221 and fixed
- * there, so `EXCLUDED` is now empty and all three are scanned by the main
+ * class commit e4a71d418 fixed, found by scanning the whole tree, but not that commit's to
+ * fix (outside its dispatched file surface). Fixed separately by commit e278a2970,
+ * so `EXCLUDED` is now empty and all three are scanned by the main
  * assertion like every other command source.
  *
  * The mechanism stays, because it is what made that handoff safe: a silent,
  * permanent exemption is its own defect — a file excluded here stops being
  * checked by this pin forever, even after the excluded condition no longer
  * holds. So a second `it.each` re-runs the SAME predicate over the excluded
  * files and asserts it still finds an unresolved entry. That is not
- * hypothetical here: when #11221's fix removed the last unresolved entry,
+ * hypothetical here: when commit e278a2970 removed the last unresolved entry,
  * this assertion went red on purpose for all three files, and its message
  * ("remove it from EXCLUDED above") is what retired them. The pattern
  * (map-of-reason + filtered main assertion + a "still needs its exclusion"
  * retiring assertion) matches
  * `packages/create-objectstack/src/starter-comments-self-contained.test.ts`'s
- * `EXCLUDED`, which has retired this same way before (#11022).
+ * `EXCLUDED`, which has retired this same way before (commit 21756b325).
  */
 describe('#10967 pin: examples resolve to a real command id', () => {
   const ENVIRONMENTS_DIR = fileURLToPath(new URL('.', import.meta.url));
@@ -293,7 +293,7 @@ describe('#10967 pin: examples resolve to a real command id', () => {
   /**
    * Nothing is excluded — every command source is scanned. `register.ts` /
    * `whoami.ts` / `logout.ts` each carried a self-retiring entry here while
-   * their `os auth …` examples were #11221's to fix; that fix landed, the
+   * their `os auth …` examples awaited commit e278a2970's fix; that fix landed, the
    * retiring assertion below went red exactly as designed, and the map goes
    * back to empty rather than staying around as a silent exemption over three
    * root-level commands. The assertion stays, so the next entry added here is

packages/cli/src/commands/explain.ts

@@ -218,7 +218,7 @@ export const SCHEMAS: Record<string, SchemaInfo> = {
       { name: 'description', type: 'string', description: 'App description' },
       { name: 'navigation', type: 'NavItem[]', description: 'Menu tree. Every item needs `id` (snake_case) + `label` + a discriminant `type`, plus that type\'s own target key: object -> `objectName`, dashboard -> `dashboardName`, page -> `pageName`, url -> `url`, report -> `reportName`.' },
       // `theme` here described a key that is only an alias of `branding`; the
-      // `themes` metadata surface itself was retired at #10485 (ADR-0049) —
+      // `themes` metadata surface itself was retired by commit 35ad101bc (ADR-0049) —
       // `app.branding` is the one colour surface. `logo` and `defaultRoute`
       // were the same class of row: neither is an AppSchema key, and both are
       // now rejected by name (`logo` -> `branding`).

packages/cli/src/commands/generate-builtin-id-column.pin.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * THE #15040 PIN: the `id` column both migration generators emit is the column
+ * THE commit 8644d1d33 PIN: the `id` column both migration generators emit is the column
  * `driver-sql` actually creates.
  *
  * ## The defect
@@ -46,7 +46,7 @@
  *
  * ## The audit-stamp columns: all three rows now ruled (#15521)
  *
- * #15040 measured a THIRD disagreement in the same pass and recorded it here
+ * Commit 8644d1d33 measured a THIRD disagreement in the same pass and recorded it here
  * without correcting it. #15521 split that record into rows and has now ruled
  * every one of them the same way — the generator follows the driver:
  *

packages/cli/src/commands/generate-declared-column-default.pin.test.ts

@@ -10,7 +10,7 @@
  * band into a generated table got NULL where the platform's own table supplies
  * the declared value. Driven on live PostgreSQL 16.13 — one object, three
  * schemas, one producer each, `information_schema.columns` read back per schema
- * (the card's own six-column probe, re-run against `generate.ts` as #16887 and
+ * (the card's own six-column probe, re-run against `generate.ts` as commit 9cdffbe36 and
  * #17208 leave it):
  *
  * ```
@@ -49,7 +49,7 @@
  *
  * 1. **`f_required` stays out of the repair.** A `required: true` field with no
  *    `storage.notNull` is nullable on all three producers — which is agreement,
- *    not divergence, because #16887 already took both generators off `required`.
+ *    not divergence, because commit 9cdffbe36 already took both generators off `required`.
  *    Whether a SCAFFOLD should nonetheless preserve the author's declaration is
  *    an open decision (#17218) and ⛔ is not settled here or by this file.
  * 2. **`NOW()` on a `date` / `time` column is a PostgreSQL claim**, like every