@bongos/core 1.21.175 → 1.21.176

package/scripts/{gds → bongos}/newcomer-floor.templates.json

@@ -1,5 +1,5 @@
 {
-  "_doc": "The evergreen newcomer chores, grouped BY DISCIPLINE. Each discipline maps to a LIST of chore templates (was a single object before task 1488 — a discipline can now offer several first-builder chores so newcomers are not funnelled into one). The deterministic replenisher (scripts/gds/newcomer-floor.js) and the on-claim restock (modules/onboarding/newcomer-restock.js) stamp disposable claimable COPIES from each template; the TEMPLATE is never claimed and never ships. Each copy's source_ref is tmpl:<discipline>:<template_id>:<seq> (monotonic), so identical-title copies never collide with the dedup. Per-template `floor` sets that chore’s standing pool depth; if a template omits it, the discipline default in newcomer-floor.config.json applies. credits_reward, est_minutes and floor all live here (per chore). version_id is per-template so each chore lands on the correct track; it MUST point at an open (non-shipped) version — update it at version close, or the replenisher's open-version guard refuses to stamp and the floor silently stops refilling (task 1002958: the engineer pins still read the long-shipped GDS-V4 and artist+ideator read V2, a version this ladder never had, so NO discipline could restock). touches[] is intentionally empty so multiple same-discipline newcomers can claim copies concurrently; git-merge is the real collision detector. To ADD a chore: append an entry to the discipline's array. To CHANGE one: edit it here — no code change needed. UI offers two browser-free chores (a token-drift fix measured by validate-design.js, and an accessible-name fix) so a newcomer whose only craft is ui is never starved for work on a machine with no Chrome/Edge for the kit — task 1003487. Engineer offers a SAFE coding chore (add a unit test — touches only tests/, which auto-ships) and the docs-hygiene sweep (constrained to non-protected docs so a sub-Metic ship does not stall on the authority core).",
+  "_doc": "The evergreen newcomer chores, grouped BY DISCIPLINE. Each discipline maps to a LIST of chore templates (was a single object before task 1488 — a discipline can now offer several first-builder chores so newcomers are not funnelled into one). The deterministic replenisher (scripts/bongos/newcomer-floor.js) and the on-claim restock (modules/onboarding/newcomer-restock.js) stamp disposable claimable COPIES from each template; the TEMPLATE is never claimed and never ships. Each copy's source_ref is tmpl:<discipline>:<template_id>:<seq> (monotonic), so identical-title copies never collide with the dedup. Per-template `floor` sets that chore’s standing pool depth; if a template omits it, the discipline default in newcomer-floor.config.json applies. credits_reward, est_minutes and floor all live here (per chore). version_id is per-template so each chore lands on the correct track; it MUST point at an open (non-shipped) version — update it at version close, or the replenisher's open-version guard refuses to stamp and the floor silently stops refilling (task 1002958: the engineer pins still read the long-shipped GDS-V4 and artist+ideator read V2, a version this ladder never had, so NO discipline could restock). touches[] is intentionally empty so multiple same-discipline newcomers can claim copies concurrently; git-merge is the real collision detector. To ADD a chore: append an entry to the discipline's array. To CHANGE one: edit it here — no code change needed. UI offers two browser-free chores (a token-drift fix measured by validate-design.js, and an accessible-name fix) so a newcomer whose only craft is ui is never starved for work on a machine with no Chrome/Edge for the kit — task 1003487. Engineer offers a SAFE coding chore (add a unit test — touches only tests/, which auto-ships) and the docs-hygiene sweep (constrained to non-protected docs so a sub-Metic ship does not stall on the authority core).",
   "engineer": [
     {
       "template_id": "unit-test-pass",
@@ -10,11 +10,11 @@
       "credits_reward": 15,
       "floor": 2,
       "title": "Add a unit test for an untested pure exported helper (assert its real behaviour)",
-      "description": "## What you're doing\n\nThe repo's safety net is its **unit suite** — every `tests/*.mjs` file, run by `scripts/gds/run-unit-tests.js` in CI on every PR. New pure tests are **auto-discovered** (there is no allowlist to edit), so the moment you add one it joins the gate. Your first ship as an engineer: pick ONE exported helper that has thin or no test coverage and add a focused, DB-free unit test for it.\n\nIt is identical for every newcomer and **always valuable** — coverage is never \"done\", the codebase has hundreds of small pure helpers, and a good test both guards behaviour and teaches you how a corner of the system works. It is also **safe to auto-ship**: you add ONE file under `tests/`, which is not a protected surface, so a clean test merges on green with no owner approval.\n\n## How to pick a target (a PURE helper)\n\nPick a **pure** function — deterministic, with no database, network, filesystem, or live-server dependency — so the test runs standalone. Do not hunt by hand: run the finder, which reads the live tree every time (so this task never goes stale the way a written list does):\n\n```\nnode scripts/gds/find-untested.js\n```\n\nIt lists modules that **no test file names**, best candidates first — ones no test reaches at all, then ones that look pure, then the smallest. Its purity column is a heuristic: open the module and confirm the helper you pick really needs no database, network or files. If the list is empty, run it with `--all` and pick a module that still exports a helper you can test DB-free.\n\n## How to write it (mirror an existing test — there is no framework)\n\nThese tests are plain Node scripts using `node:assert`; there is no test runner. Open a small existing one as your model — for example `tests/criterion_ref_parse.mjs` or `tests/task_classifier_vocab.mjs` — and copy the shape:\n1. `import` / `require` the helper from its module.\n2. Assert **several** cases, including at least one **edge / boundary** case (empty input, null, a tricky value).\n3. Print a one-line success message at the end (an assert that throws exits non-zero, which is how the gate sees a failure).\n\nName the file `tests/<helper-or-module>.mjs`.\n\n## Verify + ship\n\nRun BOTH and confirm both are green:\n- `node tests/<your-file>.mjs` — your test alone, exits 0.\n- `node scripts/gds/run-unit-tests.js` — the whole gate, with your test auto-included.\n\nThen `/builder-ship`. The ship notes must name the helper and file you tested.\n\n## Stay safe (off-limits)\n\nAdd exactly ONE new file under `tests/`. Do NOT edit `scripts/gds/run-unit-tests.js` (it auto-discovers your test, and it is a protected file you may not touch), and do NOT change the helper you are testing. Your test must be **DB-free**: anything needing Postgres, the network, or a live server belongs in the integration gate and will fail standalone here. Touch no permission, pipeline, migration, or infra file.",
+      "description": "## What you're doing\n\nThe repo's safety net is its **unit suite** — every `tests/*.mjs` file, run by `scripts/bongos/run-unit-tests.js` in CI on every PR. New pure tests are **auto-discovered** (there is no allowlist to edit), so the moment you add one it joins the gate. Your first ship as an engineer: pick ONE exported helper that has thin or no test coverage and add a focused, DB-free unit test for it.\n\nIt is identical for every newcomer and **always valuable** — coverage is never \"done\", the codebase has hundreds of small pure helpers, and a good test both guards behaviour and teaches you how a corner of the system works. It is also **safe to auto-ship**: you add ONE file under `tests/`, which is not a protected surface, so a clean test merges on green with no owner approval.\n\n## How to pick a target (a PURE helper)\n\nPick a **pure** function — deterministic, with no database, network, filesystem, or live-server dependency — so the test runs standalone. Do not hunt by hand: run the finder, which reads the live tree every time (so this task never goes stale the way a written list does):\n\n```\nnode scripts/bongos/find-untested.js\n```\n\nIt lists modules that **no test file names**, best candidates first — ones no test reaches at all, then ones that look pure, then the smallest. Its purity column is a heuristic: open the module and confirm the helper you pick really needs no database, network or files. If the list is empty, run it with `--all` and pick a module that still exports a helper you can test DB-free.\n\n## How to write it (mirror an existing test — there is no framework)\n\nThese tests are plain Node scripts using `node:assert`; there is no test runner. Open a small existing one as your model — for example `tests/criterion_ref_parse.mjs` or `tests/task_classifier_vocab.mjs` — and copy the shape:\n1. `import` / `require` the helper from its module.\n2. Assert **several** cases, including at least one **edge / boundary** case (empty input, null, a tricky value).\n3. Print a one-line success message at the end (an assert that throws exits non-zero, which is how the gate sees a failure).\n\nName the file `tests/<helper-or-module>.mjs`.\n\n## Verify + ship\n\nRun BOTH and confirm both are green:\n- `node tests/<your-file>.mjs` — your test alone, exits 0.\n- `node scripts/bongos/run-unit-tests.js` — the whole gate, with your test auto-included.\n\nThen `/builder-ship`. The ship notes must name the helper and file you tested.\n\n## Stay safe (off-limits)\n\nAdd exactly ONE new file under `tests/`. Do NOT edit `scripts/bongos/run-unit-tests.js` (it auto-discovers your test, and it is a protected file you may not touch), and do NOT change the helper you are testing. Your test must be **DB-free**: anything needing Postgres, the network, or a live server belongs in the integration gate and will fail standalone here. Touch no permission, pipeline, migration, or infra file.",
       "done_when": [
         "A NEW tests/<name>.mjs file was added (it did not exist before) that unit-tests a PURE exported helper — no Postgres, network, filesystem, or live server.",
         "`node tests/<name>.mjs` exits 0 and the test makes real assertions about the helper's behaviour — at least two cases including one edge/boundary case — not a trivial always-true assertion.",
-        "`node scripts/gds/run-unit-tests.js` passes with the new test auto-included, so it must be DB-free and currently green (it must NOT need adding to any exclusion set).",
+        "`node scripts/bongos/run-unit-tests.js` passes with the new test auto-included, so it must be DB-free and currently green (it must NOT need adding to any exclusion set).",
         "Only the one new tests/ file was added — run-unit-tests.js was NOT edited, the helper under test was NOT changed, and no permission/pipeline/migration/infra path was touched.",
         "The ship notes name the helper and the test file."
       ],
@@ -28,10 +28,10 @@
       "est_minutes": 40,
       "credits_reward": 15,
       "title": "Docs-hygiene sweep: fix one piece of real drift (broken link, dead anchor, or bare #NNN ref) in a Markdown doc",
-      "description": "## What you're doing\n\nThe project's docs drift constantly — links break when files are renamed, heading anchors go dead, formatting breaks, and bare `#NNN` refs creep back (a bare `#123` autolinks to GitHub's issue space and 404s — see CLAUDE.md §8). Your job: find **one** genuine piece of drift in **one** SAFE doc and ship the fix.\n\n## First — do NOT open these (they will stall your ship)\n\nA newcomer (Xenos / Thetes, sub-Metic) may not modify the authority / pipeline core. Picking one of these as your target will **fail your grade or block your ship**, so don't even go looking for drift in them: `CLAUDE.md`, `docs/canonical-permissions.md`, the authority ADRs (`docs/adr/0016-*`, `docs/adr/0043-*`), and anything under `migrations/`, `infra/`, `.github/`, `.husky/`, `.claude/hooks/`, plus `package.json` and the ship / grade / deploy scripts. (The authoritative list is the glob set in `src/bongos/permission-path-check.js`.) The most *visible* drift often lives in `CLAUDE.md` itself — resist it; it is off-limits to you.\n\n## Pick from the SAFE docs only\n\nAll fair game: a recipe under `docs/recipes/`, a session log under `docs/session-logs/`, `docs/architecture.md`, `docs/file-map.md`, `docs/TRACKS.md`, a **non-authority** ADR, `README.md`, or `art/README.md`.\n\n## How to find a real target (don't ship a no-op)\n\n1. **Bare `#NNN` refs (easiest):** run `node scripts/gds/linkify-refs.js` (read-only) — it lists docs with upgradeable refs. Pick one from the SAFE list above and fix it with `node scripts/gds/linkify-refs.js --apply <safe-file.md>`.\n2. **Broken / renamed links:** open a safe doc and check its `](path)` links resolve to a real file (cross-check `docs/file-map.md`).\n3. **Dead anchors:** `](#heading)` where that heading no longer exists in the target doc.\n4. **Formatting drift:** a broken list nest, an unclosed code fence, a mangled table.\n\n## Verify + ship\n\nRun `node scripts/gds/linkify-refs.js --check <your-file.md>` (scoped to YOUR one safe file — exit 0) and confirm any link you touched resolves, then `/builder-ship`. The ship notes must name the specific drift you fixed and the one file.\n\n_Prefer writing code to prose? Claim the \"add a unit test\" engineer chore instead — it's the other first-builder engineer task._",
+      "description": "## What you're doing\n\nThe project's docs drift constantly — links break when files are renamed, heading anchors go dead, formatting breaks, and bare `#NNN` refs creep back (a bare `#123` autolinks to GitHub's issue space and 404s — see CLAUDE.md §8). Your job: find **one** genuine piece of drift in **one** SAFE doc and ship the fix.\n\n## First — do NOT open these (they will stall your ship)\n\nA newcomer (Xenos / Thetes, sub-Metic) may not modify the authority / pipeline core. Picking one of these as your target will **fail your grade or block your ship**, so don't even go looking for drift in them: `CLAUDE.md`, `docs/canonical-permissions.md`, the authority ADRs (`docs/adr/0016-*`, `docs/adr/0043-*`), and anything under `migrations/`, `infra/`, `.github/`, `.husky/`, `.claude/hooks/`, plus `package.json` and the ship / grade / deploy scripts. (The authoritative list is the glob set in `src/bongos/permission-path-check.js`.) The most *visible* drift often lives in `CLAUDE.md` itself — resist it; it is off-limits to you.\n\n## Pick from the SAFE docs only\n\nAll fair game: a recipe under `docs/recipes/`, a session log under `docs/session-logs/`, `docs/architecture.md`, `docs/file-map.md`, `docs/TRACKS.md`, a **non-authority** ADR, `README.md`, or `art/README.md`.\n\n## How to find a real target (don't ship a no-op)\n\n1. **Bare `#NNN` refs (easiest):** run `node scripts/bongos/linkify-refs.js` (read-only) — it lists docs with upgradeable refs. Pick one from the SAFE list above and fix it with `node scripts/bongos/linkify-refs.js --apply <safe-file.md>`.\n2. **Broken / renamed links:** open a safe doc and check its `](path)` links resolve to a real file (cross-check `docs/file-map.md`).\n3. **Dead anchors:** `](#heading)` where that heading no longer exists in the target doc.\n4. **Formatting drift:** a broken list nest, an unclosed code fence, a mangled table.\n\n## Verify + ship\n\nRun `node scripts/bongos/linkify-refs.js --check <your-file.md>` (scoped to YOUR one safe file — exit 0) and confirm any link you touched resolves, then `/builder-ship`. The ship notes must name the specific drift you fixed and the one file.\n\n_Prefer writing code to prose? Claim the \"add a unit test\" engineer chore instead — it's the other first-builder engineer task._",
       "done_when": [
         "Exactly one non-protected Markdown file was changed (NOT CLAUDE.md, canonical-permissions.md, an authority ADR, or anything under migrations/ infra/ .github/ .husky/ .claude/hooks/ — see src/bongos/permission-path-check.js), and the change is a genuine hygiene fix (a broken/renamed link path, a dead heading anchor, a bare `#NNN` ref linkified, or formatting drift) — not a content/meaning edit and not a cosmetic no-op.",
-        "`node scripts/gds/linkify-refs.js --check <your-file.md>` (scoped to the one file you changed) exits 0.",
+        "`node scripts/bongos/linkify-refs.js --check <your-file.md>` (scoped to the one file you changed) exits 0.",
         "Any link the fix points to actually resolves: an internal file link points at a path that exists (cross-checked against docs/file-map.md); an anchor link points at a heading that exists.",
         "No protected path was modified.",
         "The ship notes name the specific drift fixed and the one file touched."
@@ -49,13 +49,13 @@
       "est_minutes": 55,
       "credits_reward": 15,
       "title": "Generate one new in-world art asset of your choice (a prop, plant, animal, or accessory) via the pixel-art pipeline",
-      "description": "## What you're doing\n\nThis instance's world always needs more to look at. Your first ship as an artist is to **generate ONE new in-world asset of your own choosing** and add it to the world. You pick the subject — that's the fun part. Good candidates, all in-world (Mediterranean coast just south of Athens, mythic 'discovered secret' tone):\n- **Props**: amphora, fishing net, basket, crate, urn, torch, market awning, oar, clay pot.\n- **Plants**: olive tree, cypress, reeds, grapevine, shrub, wild herbs.\n- **Animals**: goat, chicken, duck, donkey, fish, gull, lizard.\n- **Accessories**: a sandal, a sun hat, a length of rope, a string of beads.\n\nIt is identical for every newcomer and **always valuable**, because a growing world has effectively unbounded demand for new props, flora, fauna, and detail — every newcomer picks a different subject, so two runs never collide.\n\n## How to find your way in\n\n1. Read `art/README.md` and `docs/recipes/pixel-art-pipeline.md`, plus `modules/art-pipeline/template/style_guide.md`, `modules/art-pipeline/template/rubric.json`, and `modules/art-pipeline/template/palette.json` — that's the look you must hit: 16-bit pixel art, early-Pokémon (FireRed) touchstone, top-down, 32×32, locked 64-colour Mediterranean palette (olive greens, warm tans, turquoise sea, weathered marble — NOT spring green, NOT navy, NOT pine).\n2. **Pick ONE subject.** Keep it to a SINGLE 32×32 tile/sprite — not a whole spritesheet or family (that's a bigger task).\n3. **Check the budget first**: `python3 modules/art-pipeline/pipeline/cost_ledger.py status` (the pipeline hard-stops at $80; one asset is ~$0.05–0.45).\n4. **Generate via the pipeline — do not hand-draw or freelance.** Use the `/otb-tile-generate` skill: it appends your new entry to `modules/art-pipeline/template/vocabulary.json`, runs the generate → post-process-to-32×32 → score-against-rubric → retry orchestrator, saves the final PNG to `modules/art-pipeline/generated/tiles/<id>.png`, and logs cost. (This needs the art pipeline's `GOOGLE_AI_STUDIO_KEY`, which resolves from `~/.config/otb/env`; most builder setups have it. If yours doesn't, claim the engineer or ideator newcomer chore instead, or ask an Archon to enable it.)\n5. **Confirm it PASSED** the rubric (`modules/art-pipeline/iterations/run_summary.json` shows `status: \"pass\"`). If it only reached best-effort, regenerate with the fix_hint — never paper over a fail.\n6. **See it in-game**: `node scripts/gds/art-stage.js` rebuilds the atlas and surfaces it on your sandbox preview (`sandbox-<login>.<instance-apex>`).\n7. Ship via `/builder-ship`; the ship notes name your asset and its rubric score.\n\n## Stay clear of (READ-ONLY)\n\nNever modify the locked palette (`modules/art-pipeline/template/palette.json`) or the rubric (`modules/art-pipeline/template/rubric.json`) — those are theme-defining and changing them needs an ADR (out of scope for a first ship). Touch only art assets/vocabulary under `art/` (and, only if your asset is a genuinely new base-tile TYPE, the `public/game/world/tilePalette.js` mapping). Do not touch any permission/pipeline-core/migration/infra file.",
+      "description": "## What you're doing\n\nThis instance's world always needs more to look at. Your first ship as an artist is to **generate ONE new in-world asset of your own choosing** and add it to the world. You pick the subject — that's the fun part. Good candidates, all in-world (Mediterranean coast just south of Athens, mythic 'discovered secret' tone):\n- **Props**: amphora, fishing net, basket, crate, urn, torch, market awning, oar, clay pot.\n- **Plants**: olive tree, cypress, reeds, grapevine, shrub, wild herbs.\n- **Animals**: goat, chicken, duck, donkey, fish, gull, lizard.\n- **Accessories**: a sandal, a sun hat, a length of rope, a string of beads.\n\nIt is identical for every newcomer and **always valuable**, because a growing world has effectively unbounded demand for new props, flora, fauna, and detail — every newcomer picks a different subject, so two runs never collide.\n\n## How to find your way in\n\n1. Read `art/README.md` and `docs/recipes/pixel-art-pipeline.md`, plus `modules/art-pipeline/template/style_guide.md`, `modules/art-pipeline/template/rubric.json`, and `modules/art-pipeline/template/palette.json` — that's the look you must hit: 16-bit pixel art, early-Pokémon (FireRed) touchstone, top-down, 32×32, locked 64-colour Mediterranean palette (olive greens, warm tans, turquoise sea, weathered marble — NOT spring green, NOT navy, NOT pine).\n2. **Pick ONE subject.** Keep it to a SINGLE 32×32 tile/sprite — not a whole spritesheet or family (that's a bigger task).\n3. **Check the budget first**: `python3 modules/art-pipeline/pipeline/cost_ledger.py status` (the pipeline hard-stops at $80; one asset is ~$0.05–0.45).\n4. **Generate via the pipeline — do not hand-draw or freelance.** Use the `/otb-tile-generate` skill: it appends your new entry to `modules/art-pipeline/template/vocabulary.json`, runs the generate → post-process-to-32×32 → score-against-rubric → retry orchestrator, saves the final PNG to `modules/art-pipeline/generated/tiles/<id>.png`, and logs cost. (This needs the art pipeline's `GOOGLE_AI_STUDIO_KEY`, which resolves from `~/.config/otb/env`; most builder setups have it. If yours doesn't, claim the engineer or ideator newcomer chore instead, or ask an Archon to enable it.)\n5. **Confirm it PASSED** the rubric (`modules/art-pipeline/iterations/run_summary.json` shows `status: \"pass\"`). If it only reached best-effort, regenerate with the fix_hint — never paper over a fail.\n6. **See it in-game**: `node scripts/bongos/art-stage.js` rebuilds the atlas and surfaces it on your sandbox preview (`sandbox-<login>.<instance-apex>`).\n7. Ship via `/builder-ship`; the ship notes name your asset and its rubric score.\n\n## Stay clear of (READ-ONLY)\n\nNever modify the locked palette (`modules/art-pipeline/template/palette.json`) or the rubric (`modules/art-pipeline/template/rubric.json`) — those are theme-defining and changing them needs an ADR (out of scope for a first ship). Touch only art assets/vocabulary under `art/` (and, only if your asset is a genuinely new base-tile TYPE, the `public/game/world/tilePalette.js` mapping). Do not touch any permission/pipeline-core/migration/infra file.",
       "done_when": [
         "Exactly one NEW in-world asset (your chosen subject) was generated via the pixel-art pipeline (`/otb-tile-generate` / orchestrator.py); the final PNG exists at modules/art-pipeline/generated/tiles/<id>.png.",
         "It PASSED the rubric (modules/art-pipeline/iterations/run_summary.json status 'pass', or /otb-design-review numbers reported at/above the bar) and every pixel is on the locked palette (modules/art-pipeline/template/palette.json).",
         "A vocabulary.json entry was added for the new asset; the locked palette.json and rubric.json were NOT modified.",
         "Only art/ files changed (plus, at most, the public/game/world/tilePalette.js wiring for a genuinely new base-tile type) — no permission, pipeline-core, migration, or infra file.",
-        "You staged it (`node scripts/gds/art-stage.js`) and the ship notes name the asset id and its rubric score."
+        "You staged it (`node scripts/bongos/art-stage.js`) and the ship notes name the asset id and its rubric score."
       ],
       "touches": [],
       "floor": 3
@@ -70,9 +70,9 @@
       "est_minutes": 45,
       "credits_reward": 12,
       "title": "Idea-seed pass: file 5-8 fresh in-world ideas (names, lore, or builder-UX) into the idea inbox",
-      "description": "## What you'll do\n\nThe seed of almost everything built here is the **idea_inbox** — a queue anyone can drop ideas into, which trusted builders later triage into real tasks. Your first ship as an ideator is simple and concrete: **add a small batch of fresh ideas to that inbox.** You write no code, touch no game, change no system — you think, write a few short well-shaped ideas, and file them with one command each.\n\nIt is identical for every newcomer and **always valuable**: the inbox is never \"done\" — every triage pass consumes ideas (promote/discard/merge), so it is permanently hungry for fresh input, and a growing world always wants more names, more lore, more texture. Your batch is brand-new content, so it can never duplicate \"the work\" — the supply IS the work.\n\n## Pick ONE branch\n\n- **Branch A — PRODUCT flavour (default).** Ideas that grow the world players see: **names + one line of lore** for a character, structure, landmark, district, ship, or festival; or a world-background snippet (a custom, a superstition, a line a named NPC says). Tone: mythic, mysterious, a \"discovered secret\"; Mediterranean ancient-Greek coast (just south of Athens); NOT modern, NOT tongue-in-cheek-modern. Ground it in CLAUDE.md §3/§6/§7.\n- **Branch B — INTERNAL / builder-UX.** Small user-experience improvement ideas for the GDS / builders' hall (the surfaces builders use, not the game): a clearer label, a confusing onboarding message, a quality-of-life tweak to a status page or a slash-command's output. See `docs/TRACKS.md` for product vs internal.\n\n## How to find your way in\n\n1. (Branch A) Read CLAUDE.md §3/§6/§7 for tone. (Branch B) Skim `docs/TRACKS.md` and click around your instance's /builders hall for the rough edge you'll write up.\n2. See what's already filed so you don't repeat it: `node scripts/gds/api.js GET /api/bongos/inbox`.\n3. File each idea with `node scripts/gds/capture.js \"<title>\" --body-file <path>` (filing an idea is the open-to-all path — a Xenos/Thetes session is allowed to do it; you just can't triage them). Put one line of detail + a `track: product` or `track: internal` line in each body file.",
+      "description": "## What you'll do\n\nThe seed of almost everything built here is the **idea_inbox** — a queue anyone can drop ideas into, which trusted builders later triage into real tasks. Your first ship as an ideator is simple and concrete: **add a small batch of fresh ideas to that inbox.** You write no code, touch no game, change no system — you think, write a few short well-shaped ideas, and file them with one command each.\n\nIt is identical for every newcomer and **always valuable**: the inbox is never \"done\" — every triage pass consumes ideas (promote/discard/merge), so it is permanently hungry for fresh input, and a growing world always wants more names, more lore, more texture. Your batch is brand-new content, so it can never duplicate \"the work\" — the supply IS the work.\n\n## Pick ONE branch\n\n- **Branch A — PRODUCT flavour (default).** Ideas that grow the world players see: **names + one line of lore** for a character, structure, landmark, district, ship, or festival; or a world-background snippet (a custom, a superstition, a line a named NPC says). Tone: mythic, mysterious, a \"discovered secret\"; Mediterranean ancient-Greek coast (just south of Athens); NOT modern, NOT tongue-in-cheek-modern. Ground it in CLAUDE.md §3/§6/§7.\n- **Branch B — INTERNAL / builder-UX.** Small user-experience improvement ideas for the GDS / builders' hall (the surfaces builders use, not the game): a clearer label, a confusing onboarding message, a quality-of-life tweak to a status page or a slash-command's output. See `docs/TRACKS.md` for product vs internal.\n\n## How to find your way in\n\n1. (Branch A) Read CLAUDE.md §3/§6/§7 for tone. (Branch B) Skim `docs/TRACKS.md` and click around your instance's /builders hall for the rough edge you'll write up.\n2. See what's already filed so you don't repeat it: `node scripts/bongos/api.js GET /api/bongos/inbox`.\n3. File each idea with `node scripts/bongos/capture.js \"<title>\" --body-file <path>` (filing an idea is the open-to-all path — a Xenos/Thetes session is allowed to do it; you just can't triage them). Put one line of detail + a `track: product` or `track: internal` line in each body file.",
       "done_when": [
-        "You filed 5–8 fresh ideas into the idea_inbox via `node scripts/gds/capture.js` (each prints a `Captured idea #N` confirmation), all in ONE branch (A product, or B internal/UX).",
+        "You filed 5–8 fresh ideas into the idea_inbox via `node scripts/bongos/capture.js` (each prints a `Captured idea #N` confirmation), all in ONE branch (A product, or B internal/UX).",
         "Each idea has a clear title and a body with at least one sentence of detail — for Branch A, one line of in-world lore (who/what it is); for Branch B, what the rough edge is and what 'better' looks like.",
         "Branch A ideas are in the world's voice and consistent with CLAUDE.md §3/§6/§7 (ancient-Greek coast, Example, mythic 'discovered secret' tone — not modern/anachronistic).",
         "Each idea body declares its track on a `track: product` or `track: internal` line so triage can route it.",
@@ -93,12 +93,12 @@
       "credits_reward": 15,
       "floor": 2,
       "title": "Token-drift pass: replace one hardcoded colour in a platform stylesheet with the branding token it should have used",
-      "description": "## What you're doing\n\nEvery colour on a platform surface must come from the instance's branding pack — **the Fifteen Rule**: thirteen colours plus two font stacks in `theme.ui`, reached as a `var()` or a `color-mix()` of them. The only legal literal is pure black or white with alpha, used as a scrim, mask or halo. Drift happens anyway: someone types `#3b82f6` in a hurry and the surface stops following the instance's world. Your first ship as a UI builder: find **one** real hardcoded colour in **one** stylesheet and replace it with the right token.\n\nIt is identical for every newcomer and **always valuable** — the sheets are large, drift is continuous, and every literal you convert is one more thing that follows the pack when an instance changes its look. It is also **safe**: you change one declaration in one CSS file, which is not a protected surface.\n\n## Learn the fifteen first (five minutes, and the whole job depends on it)\n\n1. Open `config/branding.json` (falling back to `config/branding.neutral.json`) and read `theme.ui` — those thirteen colours and two font stacks are your entire palette.\n2. Open the root `DESIGN.md` — it names the derived tiers and which token means what (surface, ink, accent, hairline, danger…). If it names a rule, it wins.\n3. Skim `docs/recipes/ui-look-before-you-ship.md` for how the floors are measured.\n\n## Find a real target\n\nGrep a platform stylesheet for a raw colour and pick ONE that is genuinely wrong:\n\n```\ngrep -rnE '#[0-9a-fA-F]{3,8}\\b|rgba?\\(' modules/hall-ui/public/ modules/status-ui/public/ --include=*.css\n```\n\nGood targets: a hex or `rgb()` that duplicates a token's value, or one that is close to a token but slightly off (the worst kind — it looks fine until the pack changes).\n\n**Not a target, leave these alone:** `#000` / `#fff` / `rgba(0,0,0,…)` / `rgba(255,255,255,…)` used as a scrim, shadow, mask or halo — those are explicitly legal. A colour inside a vendored or generated file. Anything under `config/` (changing the pack itself is the owner's decision and an ADR, never a first ship).\n\n## Make the change\n\nReplace the literal with the token that carries the same MEANING, not merely the nearest number — `var(--ui-accent)` because the thing is an accent, not because the hex was blue-ish. If no token means what the literal meant, you have found a design question rather than drift: pick a different target and, if you like, file the question with `node scripts/gds/capture.js`.\n\n**Both modes.** If the rule you touch has a dark twin, the twin changes too and stays byte-identical — `:root[data-mode=\"dark\"]` and `@media (prefers-color-scheme: dark) { :root:not([data-mode=\"light\"]) }`. Never fix one and leave the other.\n\n## Verify + ship\n\n- `node scripts/gds/validate-design.js --strict` — exits 0.\n- `node scripts/gds/run-unit-tests.js` — still green.\n- Say in the ship notes which literal you replaced, with which token, and why that token is the right MEANING.\n\nHave a browser (Edge or Chrome) on the machine? Then also run `node modules/ui-design/kit/render.js --page <the page>` and look at the before/after — the work is judged by looking at it. Not required for this chore.\n\n## Stay clear of\n\nDo not edit `config/branding.json`, `config/branding.neutral.json`, `config/design-tokens*.json`, or the root `DESIGN.md` — the world is the owner's, and changing it needs an ADR. Do not add a sixteenth token. Do not restyle the component while you are in there: one literal, one meaning, one commit. Touch no permission, pipeline, migration or infra file.",
+      "description": "## What you're doing\n\nEvery colour on a platform surface must come from the instance's branding pack — **the Fifteen Rule**: thirteen colours plus two font stacks in `theme.ui`, reached as a `var()` or a `color-mix()` of them. The only legal literal is pure black or white with alpha, used as a scrim, mask or halo. Drift happens anyway: someone types `#3b82f6` in a hurry and the surface stops following the instance's world. Your first ship as a UI builder: find **one** real hardcoded colour in **one** stylesheet and replace it with the right token.\n\nIt is identical for every newcomer and **always valuable** — the sheets are large, drift is continuous, and every literal you convert is one more thing that follows the pack when an instance changes its look. It is also **safe**: you change one declaration in one CSS file, which is not a protected surface.\n\n## Learn the fifteen first (five minutes, and the whole job depends on it)\n\n1. Open `config/branding.json` (falling back to `config/branding.neutral.json`) and read `theme.ui` — those thirteen colours and two font stacks are your entire palette.\n2. Open the root `DESIGN.md` — it names the derived tiers and which token means what (surface, ink, accent, hairline, danger…). If it names a rule, it wins.\n3. Skim `docs/recipes/ui-look-before-you-ship.md` for how the floors are measured.\n\n## Find a real target\n\nGrep a platform stylesheet for a raw colour and pick ONE that is genuinely wrong:\n\n```\ngrep -rnE '#[0-9a-fA-F]{3,8}\\b|rgba?\\(' modules/hall-ui/public/ modules/status-ui/public/ --include=*.css\n```\n\nGood targets: a hex or `rgb()` that duplicates a token's value, or one that is close to a token but slightly off (the worst kind — it looks fine until the pack changes).\n\n**Not a target, leave these alone:** `#000` / `#fff` / `rgba(0,0,0,…)` / `rgba(255,255,255,…)` used as a scrim, shadow, mask or halo — those are explicitly legal. A colour inside a vendored or generated file. Anything under `config/` (changing the pack itself is the owner's decision and an ADR, never a first ship).\n\n## Make the change\n\nReplace the literal with the token that carries the same MEANING, not merely the nearest number — `var(--ui-accent)` because the thing is an accent, not because the hex was blue-ish. If no token means what the literal meant, you have found a design question rather than drift: pick a different target and, if you like, file the question with `node scripts/bongos/capture.js`.\n\n**Both modes.** If the rule you touch has a dark twin, the twin changes too and stays byte-identical — `:root[data-mode=\"dark\"]` and `@media (prefers-color-scheme: dark) { :root:not([data-mode=\"light\"]) }`. Never fix one and leave the other.\n\n## Verify + ship\n\n- `node scripts/bongos/validate-design.js --strict` — exits 0.\n- `node scripts/bongos/run-unit-tests.js` — still green.\n- Say in the ship notes which literal you replaced, with which token, and why that token is the right MEANING.\n\nHave a browser (Edge or Chrome) on the machine? Then also run `node modules/ui-design/kit/render.js --page <the page>` and look at the before/after — the work is judged by looking at it. Not required for this chore.\n\n## Stay clear of\n\nDo not edit `config/branding.json`, `config/branding.neutral.json`, `config/design-tokens*.json`, or the root `DESIGN.md` — the world is the owner's, and changing it needs an ADR. Do not add a sixteenth token. Do not restyle the component while you are in there: one literal, one meaning, one commit. Touch no permission, pipeline, migration or infra file.",
       "done_when": [
         "Exactly one hardcoded colour literal in ONE non-protected stylesheet was replaced with a branding token (a var() or a color-mix() of theme.ui) — a real literal, not a legal black/white scrim, shadow, mask or halo, and not a cosmetic no-op.",
         "The token chosen matches the MEANING of what was styled (the ship notes say which token and why), and no sixteenth token was invented.",
         "If the rule had a dark twin, the twin was changed too and the two remain byte-identical.",
-        "`node scripts/gds/validate-design.js --strict` exits 0 and `node scripts/gds/run-unit-tests.js` is green.",
+        "`node scripts/bongos/validate-design.js --strict` exits 0 and `node scripts/bongos/run-unit-tests.js` is green.",
         "config/branding*.json, config/design-tokens*.json and the root DESIGN.md were NOT modified, and no permission, pipeline, migration or infra path was touched.",
         "The ship notes name the file, the literal removed and the token that replaced it."
       ],
@@ -113,12 +113,12 @@
       "credits_reward": 15,
       "floor": 1,
       "title": "Accessibility pass: give one unlabelled control or image on a platform page a real accessible name",
-      "description": "## What you're doing\n\nA control a screen reader cannot name is a control some people cannot use. Icon-only buttons are the usual offenders — a `<button>` whose entire content is an `<i class=\"ti ti-x\">` announces as \"button\" and nothing else. Your first ship as a UI builder: find **one** genuinely unlabelled control or image on a platform page and give it a real accessible name.\n\nIt is identical for every newcomer and **always valuable** — the hall and status surfaces carry many icon buttons, new ones arrive constantly, and each label you add is permanent.\n\n## Find a real target\n\nLook in `modules/hall-ui/public/*.html` and `*.js`, and `modules/status-ui/public/`:\n\n```\ngrep -rnE '<button[^>]*>\\s*<i class=\"ti' modules/hall-ui/public/ modules/status-ui/public/\ngrep -rn '<img' modules/hall-ui/public/ modules/status-ui/public/ | grep -v 'alt='\n```\n\nA target is genuine when it has **no** `aria-label`, **no** `title`, **no** visible text inside it, and **no** `aria-labelledby`. Check before you \"fix\" it — many already have one.\n\n## Make the change\n\n- Icon-only button → add `aria-label=\"<what it does>\"`. Name the ACTION, not the icon: `aria-label=\"Close the dialog\"`, never `aria-label=\"x icon\"`.\n- Decorative icon sitting beside text that already says it → the right fix is `aria-hidden=\"true\"`, so it is not announced twice.\n- `<img>` → a real `alt` describing what it conveys; `alt=\"\"` only when it is purely decorative.\n- Text built by JavaScript goes through the same `escapeHtml` the surrounding code uses — match the file's existing idiom.\n\nOne control. Do not restyle it, do not rename its class, do not refactor the component.\n\n## Verify + ship\n\n- `node scripts/gds/run-unit-tests.js` — green.\n- Read the label back to yourself with the screen off: does it say what pressing this does? If not, rewrite it.\n- The ship notes name the file, the control, and the label you gave it.\n\n## Stay clear of\n\nDo not \"fix\" a control that already has an accessible name — that is a no-op ship. Do not touch the branding pack, `DESIGN.md`, or any permission, pipeline, migration or infra file.",
+      "description": "## What you're doing\n\nA control a screen reader cannot name is a control some people cannot use. Icon-only buttons are the usual offenders — a `<button>` whose entire content is an `<i class=\"ti ti-x\">` announces as \"button\" and nothing else. Your first ship as a UI builder: find **one** genuinely unlabelled control or image on a platform page and give it a real accessible name.\n\nIt is identical for every newcomer and **always valuable** — the hall and status surfaces carry many icon buttons, new ones arrive constantly, and each label you add is permanent.\n\n## Find a real target\n\nLook in `modules/hall-ui/public/*.html` and `*.js`, and `modules/status-ui/public/`:\n\n```\ngrep -rnE '<button[^>]*>\\s*<i class=\"ti' modules/hall-ui/public/ modules/status-ui/public/\ngrep -rn '<img' modules/hall-ui/public/ modules/status-ui/public/ | grep -v 'alt='\n```\n\nA target is genuine when it has **no** `aria-label`, **no** `title`, **no** visible text inside it, and **no** `aria-labelledby`. Check before you \"fix\" it — many already have one.\n\n## Make the change\n\n- Icon-only button → add `aria-label=\"<what it does>\"`. Name the ACTION, not the icon: `aria-label=\"Close the dialog\"`, never `aria-label=\"x icon\"`.\n- Decorative icon sitting beside text that already says it → the right fix is `aria-hidden=\"true\"`, so it is not announced twice.\n- `<img>` → a real `alt` describing what it conveys; `alt=\"\"` only when it is purely decorative.\n- Text built by JavaScript goes through the same `escapeHtml` the surrounding code uses — match the file's existing idiom.\n\nOne control. Do not restyle it, do not rename its class, do not refactor the component.\n\n## Verify + ship\n\n- `node scripts/bongos/run-unit-tests.js` — green.\n- Read the label back to yourself with the screen off: does it say what pressing this does? If not, rewrite it.\n- The ship notes name the file, the control, and the label you gave it.\n\n## Stay clear of\n\nDo not \"fix\" a control that already has an accessible name — that is a no-op ship. Do not touch the branding pack, `DESIGN.md`, or any permission, pipeline, migration or infra file.",
       "done_when": [
         "Exactly one control or image that genuinely had NO accessible name (no aria-label, no title, no visible text, no aria-labelledby, no alt) was given one, in one non-protected file.",
         "The name describes the ACTION or the MEANING, not the icon ('Close the dialog', not 'x icon'); a purely decorative icon beside existing text was marked aria-hidden=\"true\" instead.",
         "Nothing else about the control changed — no restyle, no class rename, no component refactor — and any generated text uses the file's existing escaping idiom.",
-        "`node scripts/gds/run-unit-tests.js` is green.",
+        "`node scripts/bongos/run-unit-tests.js` is green.",
         "The branding pack, DESIGN.md, and every permission/pipeline/migration/infra path were untouched.",
         "The ship notes name the file, the control and the accessible name added."
       ],

package/scripts/bongos/newcomer-floor.test.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+// Pure-helper tests for the deterministic newcomer floor replenisher
+// (task 1158; multi-chore-per-discipline since task 1488).
+//
+// Co-located with the script rather than in tests/*.mjs. The repo's
+// run-unit-tests.js gate only scans tests/, so tests/newcomer_floor.mjs is a thin
+// shim that require()s THIS file so it runs in the gate. Covers the pure logic
+// (per-chore deficit math, per-template floor resolution, monotonic per-instance
+// source_ref seq, ref decomposition, template->copy building + scope-clamp,
+// description assembly) and the integrity of the real templates.json. Runnable:
+//
+//   node scripts/bongos/newcomer-floor.test.js
+//
+// Exits non-zero on first failure.
+
+const assert = require('node:assert');
+const path = require('node:path');
+const nf = require('./newcomer-floor');
+
+let passed = 0;
+function test(name, fn) {
+  try { fn(); passed += 1; }
+  catch (err) { console.error(`✗ ${name}\n  ${err.message}`); process.exit(1); }
+}
+
+// per-discipline DEFAULT floors (the fallback when a template omits its own).
+const FLOOR_DEFAULTS = { engineer: 2, artist: 3, ideator: 2 };
+
+// templates-by-discipline fixture (each discipline -> LIST of chores).
+const TEMPLATES = {
+  engineer: [
+    { template_id: 'unit-test-pass', version_id: 'GDS-V4', discipline: 'engineer', floor: 2, title: 'Add a unit test', done_when: ['a', 'b'], est_minutes: 45 },
+    { template_id: 'docs-hygiene-pass', version_id: 'GDS-V4', discipline: 'engineer', floor: 1, title: 'Docs sweep', done_when: ['a', 'b'], est_minutes: 40 },
+  ],
+  artist: [
+    { template_id: 'asset-generate-pass', version_id: 'V2', discipline: 'artist', title: 'Asset', done_when: ['a', 'b'], est_minutes: 55 }, // no own floor -> default
+  ],
+};
+
+// ---- templateFloor ----
+
+test('templateFloor: own floor wins over the discipline default', () => {
+  assert.strictEqual(nf.templateFloor({ floor: 5 }, 'engineer', FLOOR_DEFAULTS), 5);
+});
+
+test('templateFloor: falls back to the discipline default when omitted', () => {
+  assert.strictEqual(nf.templateFloor({}, 'artist', FLOOR_DEFAULTS), 3);
+});
+
+test('templateFloor: 0 is a valid explicit floor (not treated as missing)', () => {
+  assert.strictEqual(nf.templateFloor({ floor: 0 }, 'engineer', FLOOR_DEFAULTS), 0);
+});
+
+test('templateFloor: unknown discipline with no default -> 0', () => {
+  assert.strictEqual(nf.templateFloor({}, 'nope', FLOOR_DEFAULTS), 0);
+});
+
+// ---- computeTemplateDeficits ----
+
+function deficitFor(rows, templateId) {
+  return rows.find((r) => r.template_id === templateId);
+}
+
+test('computeTemplateDeficits: empty supply -> each chore needs its full floor', () => {
+  const rows = nf.computeTemplateDeficits({}, TEMPLATES, FLOOR_DEFAULTS);
+  assert.strictEqual(deficitFor(rows, 'unit-test-pass').needed, 2);
+  assert.strictEqual(deficitFor(rows, 'docs-hygiene-pass').needed, 1);
+  assert.strictEqual(deficitFor(rows, 'asset-generate-pass').needed, 3, 'artist uses the default floor');
+});
+
+test('computeTemplateDeficits: ready + backlog both count as supply (idempotency)', () => {
+  const supply = { 'engineer:unit-test-pass': { ready: 1, backlog: 1 } }; // fills floor 2
+  const rows = nf.computeTemplateDeficits(supply, TEMPLATES, FLOOR_DEFAULTS);
+  assert.strictEqual(deficitFor(rows, 'unit-test-pass').needed, 0);
+  assert.strictEqual(deficitFor(rows, 'docs-hygiene-pass').needed, 1, 'sibling chore is independent');
+});
+
+test('computeTemplateDeficits: supply is per-template, not shared across a discipline', () => {
+  // over-supplying one engineer chore must NOT satisfy the other.
+  const supply = { 'engineer:unit-test-pass': { ready: 9, backlog: 0 } };
+  const rows = nf.computeTemplateDeficits(supply, TEMPLATES, FLOOR_DEFAULTS);
+  assert.strictEqual(deficitFor(rows, 'unit-test-pass').needed, 0);
+  assert.strictEqual(deficitFor(rows, 'docs-hygiene-pass').needed, 1);
+});
+
+test('computeTemplateDeficits: over-supply never goes negative', () => {
+  const supply = { 'artist:asset-generate-pass': { ready: 10, backlog: 0 } };
+  const rows = nf.computeTemplateDeficits(supply, TEMPLATES, FLOOR_DEFAULTS);
+  assert.strictEqual(deficitFor(rows, 'asset-generate-pass').needed, 0);
+});
+
+test('computeTemplateDeficits: only-filter narrows to one discipline', () => {
+  const rows = nf.computeTemplateDeficits({}, TEMPLATES, FLOOR_DEFAULTS, { only: 'artist' });
+  assert.deepStrictEqual([...new Set(rows.map((r) => r.discipline))], ['artist']);
+});
+
+test('computeTemplateDeficits: ignores non-floor disciplines', () => {
+  const rows = nf.computeTemplateDeficits({}, { unclassified: [{ template_id: 'x', floor: 9 }] }, { unclassified: 9 });
+  assert.deepStrictEqual(rows, []);
+});
+
+// ---- instanceSourceRef + parseSeq + parseRef ----
+
+test('instanceSourceRef: tmpl:<disc>:<template_id>:<seq>', () => {
+  assert.strictEqual(nf.instanceSourceRef('engineer', 'unit-test-pass', 7), 'tmpl:engineer:unit-test-pass:7');
+});
+
+test('parseSeq: returns seq only for the matching discipline+template', () => {
+  assert.strictEqual(nf.parseSeq('tmpl:engineer:unit-test-pass:4', 'engineer', 'unit-test-pass'), 4);
+  assert.strictEqual(nf.parseSeq('tmpl:engineer:unit-test-pass:4', 'artist', 'unit-test-pass'), null, 'wrong discipline');
+  assert.strictEqual(nf.parseSeq('tmpl:engineer:other:4', 'engineer', 'unit-test-pass'), null, 'wrong template');
+  assert.strictEqual(nf.parseSeq('manual:engineer:some-title', 'engineer', 'unit-test-pass'), null, 'foreign ref');
+  assert.strictEqual(nf.parseSeq('tmpl:engineer:unit-test-pass:abc', 'engineer', 'unit-test-pass'), null, 'malformed seq');
+});
+
+test('parseRef: decomposes a chore ref into discipline/template/seq', () => {
+  assert.deepStrictEqual(nf.parseRef('tmpl:engineer:unit-test-pass:7'), { discipline: 'engineer', templateId: 'unit-test-pass', seq: 7 });
+  assert.strictEqual(nf.parseRef('manual:engineer:x'), null, 'not a chore ref');
+  assert.strictEqual(nf.parseRef('tmpl:engineer:unit-test-pass:0'), null, 'seq must be positive');
+  assert.strictEqual(nf.parseRef('tmpl:engineer:unit-test-pass'), null, 'too few parts');
+  assert.strictEqual(nf.parseRef('tmpl:a:b:c:d'), null, 'too many parts');
+});
+
+// ---- nextSeq (monotonic across all refs) ----
+
+test('nextSeq: empty set -> 1', () => {
+  assert.strictEqual(nf.nextSeq(new Set(), 'engineer', 'unit-test-pass'), 1);
+});
+
+test('nextSeq: 1 + max matching seq, ignoring other templates/disciplines', () => {
+  const refs = new Set([
+    'tmpl:engineer:unit-test-pass:1',
+    'tmpl:engineer:unit-test-pass:3', // gap is fine; max is 3
+    'tmpl:engineer:unit-test-pass:2',
+    'tmpl:engineer:docs-hygiene-pass:9', // sibling chore — ignored
+    'tmpl:artist:asset-generate-pass:5', // different discipline — ignored
+    'manual:engineer:something',         // foreign — ignored
+  ]);
+  assert.strictEqual(nf.nextSeq(refs, 'engineer', 'unit-test-pass'), 4);
+  assert.strictEqual(nf.nextSeq(refs, 'engineer', 'docs-hygiene-pass'), 10, 'sibling seq is independent');
+  assert.strictEqual(nf.nextSeq(refs, 'ideator', 'idea-seed-pass'), 1);
+});
+
+test('nextSeq: never recycles a shipped/abandoned seq (max over ALL statuses)', () => {
+  const refs = new Set(['tmpl:ideator:idea-seed-pass:1', 'tmpl:ideator:idea-seed-pass:2']);
+  assert.strictEqual(nf.nextSeq(refs, 'ideator', 'idea-seed-pass'), 3);
+});
+
+// ---- buildProposalFromTemplate ----
+
+const SAMPLE_TEMPLATE = {
+  template_id: 'docs-hygiene-pass',
+  version_id: 'GDS-V4',
+  discipline: 'engineer',
+  kind: 'cleanup',
+  est_minutes: 40,
+  credits_reward: 15,
+  floor: 1,
+  title: '  Docs-hygiene sweep  ',
+  description: 'Body.',
+  done_when: ['a', 'b'],
+  touches: ['docs/', 42, ''],
+};
+
+test('buildProposalFromTemplate: carries fields, normalizes touches, sets seq ref', () => {
+  const p = nf.buildProposalFromTemplate(SAMPLE_TEMPLATE, 5, { discipline: 'engineer' });
+  assert.strictEqual(p.title, 'Docs-hygiene sweep', 'trimmed');
+  assert.strictEqual(p.version_id, 'GDS-V4');
+  assert.strictEqual(p.kind, 'cleanup');
+  assert.strictEqual(p.credits_reward, 15);
+  assert.strictEqual(p.est_minutes, 40);
+  assert.deepStrictEqual(p.touches, ['docs/', '42'], 'empties dropped, coerced to strings');
+  assert.strictEqual(p.source_ref, 'tmpl:engineer:docs-hygiene-pass:5');
+  assert.deepStrictEqual(p.done_when, ['a', 'b']);
+});
+
+test('buildProposalFromTemplate: clamps est_minutes to the 60-min hard cap', () => {
+  const over = nf.buildProposalFromTemplate({ ...SAMPLE_TEMPLATE, est_minutes: 120 }, 1);
+  assert.strictEqual(over.est_minutes, nf.HARD_MAX_MINUTES, '120 clamps to 60');
+  const bad = nf.buildProposalFromTemplate({ ...SAMPLE_TEMPLATE, est_minutes: -3 }, 1);
+  assert.strictEqual(bad.est_minutes, nf.HARD_MAX_MINUTES, 'non-positive -> ceiling');
+});
+
+test('buildProposalFromTemplate: null on a titleless template', () => {
+  assert.strictEqual(nf.buildProposalFromTemplate({ ...SAMPLE_TEMPLATE, title: '   ' }, 1), null);
+  assert.strictEqual(nf.buildProposalFromTemplate(null, 1), null);
+});
+
+// ---- buildDescription ----
+
+test('buildDescription: folds done-when + evergreen footer', () => {
+  const desc = nf.buildDescription(
+    { title: 't', description: 'Body text.', done_when: ['x', 'y'], est_minutes: 30 },
+    'engineer'
+  );
+  assert.ok(desc.includes('Body text.'));
+  assert.ok(desc.includes('**Done when:**'));
+  assert.ok(desc.includes('- x') && desc.includes('- y'));
+  assert.ok(desc.includes('Evergreen newcomer chore'), 'footer present');
+  assert.ok(desc.includes('engineer'), 'discipline in footer');
+});
+
+// ---- loadTemplates: the REAL templates.json is well-formed (multi-chore shape) ----
+
+test('loadTemplates: real templates.json is a valid per-discipline list', () => {
+  const templates = nf.loadTemplates(path.join(__dirname, 'newcomer-floor.templates.json'));
+  for (const disc of ['engineer', 'artist', 'ideator']) {
+    const list = templates[disc];
+    assert.ok(Array.isArray(list) && list.length >= 1, `${disc} is a non-empty list`);
+    for (const t of list) {
+      assert.strictEqual(t.discipline, disc, `${disc} chore discipline matches its key`);
+      assert.ok(t.template_id && t.title && t.version_id, `${disc} chore has template_id/title/version_id`);
+      assert.ok(Array.isArray(t.done_when) && t.done_when.length >= 2, `${disc}/${t.template_id} has done-when bullets`);
+      assert.ok(t.est_minutes <= nf.HARD_MAX_MINUTES, `${disc}/${t.template_id} within the 60-min cap`);
+      assert.ok(Number.isFinite(Number(t.floor)) && t.floor >= 0, `${disc}/${t.template_id} has a numeric floor`);
+      const p = nf.buildProposalFromTemplate(t, 1, { discipline: disc });
+      assert.ok(p && p.source_ref === `tmpl:${disc}:${t.template_id}:1`, `${disc}/${t.template_id} stamps a clean copy`);
+    }
+  }
+});
+
+test('loadTemplates: engineer now offers BOTH the unit-test chore and the docs sweep', () => {
+  const templates = nf.loadTemplates(path.join(__dirname, 'newcomer-floor.templates.json'));
+  const ids = templates.engineer.map((t) => t.template_id);
+  assert.ok(ids.includes('unit-test-pass'), 'the safe coding chore is present');
+  assert.ok(ids.includes('docs-hygiene-pass'), 'the docs sweep is retained');
+  // every engineer chore touches only safe (non-protected) surfaces by design:
+  // touches[] is empty (git-merge is the collision detector), so this asserts the
+  // contract that engineer chores carry no protected-path touches.
+  for (const t of templates.engineer) {
+    assert.deepStrictEqual(t.touches || [], [], `${t.template_id} declares no touches[]`);
+  }
+});
+
+console.log(`✓ all ${passed} newcomer-floor pure-helper tests passed`);

package/scripts/bongos/next-number.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// next-number.js — deterministic next-free ADR + migration numbers (V4.R26 / #964).
+//
+// WHY: ADR + migration numbers collided across parallel sessions. ADRs collided
+// because each session scanned its OWN (possibly stale) local tree and picked the
+// same "next" — the triple ADR-0044 collision (sessions 1660/1629) and the
+// ADR-0024 collision (idea 122). Migrations collided/drifted because the
+// claim-time DB counter is not reconciled against reality — it once handed out
+// 079 when 079 was already applied on prod, and today it sits ahead of the
+// committed files (counter ~099 while migrations/ tops out at 093), so the
+// "reserved" number is neither the next free one nor collision-proof.
+//
+// This helper computes the next free number from the AUTHORITATIVE union of:
+//   - files committed on origin/main  (git — the real "taken" set, shared by all
+//     parallel sessions, so everyone agrees on the baseline)
+//   - the local working tree          (so a file you added THIS session counts,
+//     even before it is committed)
+// next = max(union) + 1.
+//
+// FAIL-OPEN (V4 ethos: sessions stop fighting the machine room): if origin/main
+// is unreachable (offline, fresh clone, credential-less box) it falls back to the
+// local HEAD tree + working tree and flags the result `degraded` — it never throws
+// and never blocks a claim.
+//
+// Usage:
+//   node scripts/bongos/next-number.js           # human-readable
+//   node scripts/bongos/next-number.js --json     # {"adr":58,"migration":94,...}
+//
+// Pure helpers (parseNumbers, nextFree, computeNextNumbers) + the sync facade
+// (nextNumbers) are exported for unit tests (tests/next_number.mjs).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { migrationNumberOf, CORE_NS } = require('./migration-namespace');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const ADR_DIR = 'docs/adr';
+const MIGRATIONS_DIR = 'migrations';
+
+// ADRs are NNNN-slug.md (4-digit). Migration numbers are parsed via migration-namespace's
+// migrationNumberOf so BOTH the legacy bare form (NNN_slug.sql) AND the namespaced form
+// (core_NNN_slug.sql / <key>_NNN_slug.sql, ADR 0108 §5) count toward the next-free number —
+// otherwise the first core_-prefixed file would be undercounted and its number reused.
+const ADR_RE = /^(\d{4})-.*\.md$/;
+
+// Extract the numeric prefixes matching `re` from a list of basenames → Set<int>.
+function parseNumbers(basenames, re) {
+  const out = new Set();
+  for (const name of basenames || []) {
+    const m = re.exec(name);
+    if (m) out.add(parseInt(m[1], 10));
+  }
+  return out;
+}
+
+// next free = max + 1; an empty set starts the sequence at `start`.
+function nextFree(numberSet, start = 1) {
+  let max = -Infinity;
+  for (const n of numberSet) if (n > max) max = n;
+  return max === -Infinity ? start : max + 1;
+}
+
+// PURE core: given two lists of repo-relative paths (committed + local), compute
+// the next free ADR + migration number. `start*` let callers pin the sequence
+// floor; defaults match the real repo (ADRs from 1, migrations from 1).
+function computeNextNumbers({ committedPaths = [], localPaths = [], startAdr = 1, startMigration = 1 } = {}) {
+  const baseName = (p) => p.split('/').pop();
+  const inDir = (p, dir) => p.startsWith(dir + '/');
+  const allPaths = [...committedPaths, ...localPaths];
+
+  const adrNames = allPaths.filter((p) => inDir(p, ADR_DIR)).map(baseName);
+  const migNames = allPaths.filter((p) => inDir(p, MIGRATIONS_DIR)).map(baseName);
+
+  const adrSet = parseNumbers(adrNames, ADR_RE);
+  // Count bare AND namespaced migration files (ADR 0108 §5): migrationNumberOf(...) parses
+  // both `NNN_x.sql` and `core_NNN_x.sql`/`<key>_NNN_x.sql`, so a prefixed file is never
+  // undercounted (which would hand its number out again).
+  const migSet = new Set(migNames.map(migrationNumberOf).filter((n) => n != null));
+
+  return {
+    adr: nextFree(adrSet, startAdr),
+    migration: nextFree(migSet, startMigration),
+    highestAdr: adrSet.size ? Math.max(...adrSet) : null,
+    highestMigration: migSet.size ? Math.max(...migSet) : null,
+  };
+}
+
+// ---- I/O facade (injectable for tests) -------------------------------------
+
+// List repo-relative paths under `dirs` committed on `ref`, via git. Returns []
+// (not throw) if the ref/repo is unavailable — the caller decides degraded-ness.
+function gitTreePaths(ref, dirs, runGit) {
+  try {
+    const out = runGit(['ls-tree', '-r', '--name-only', ref, '--', ...dirs]);
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+  } catch {
+    return null; // signal: ref unreachable
+  }
+}
+
+// List repo-relative paths under `dir` in the local working tree.
+function localDirPaths(dir, readDir) {
+  try {
+    return readDir(path.join(REPO_ROOT, dir)).map((name) => `${dir}/${name}`);
+  } catch {
+    return [];
+  }
+}
+
+const defaultRunGit = (args) =>
+  execFileSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+const defaultReadDir = (p) => fs.readdirSync(p);
+
+// SYNC facade used by claim.js + the CLI. Pulls the committed set from
+// origin/main (fail-open to HEAD, then to local-only) and unions the working
+// tree. Returns the numbers plus which source answered (for an honest print).
+function nextNumbers({ runGit = defaultRunGit, readDir = defaultReadDir } = {}) {
+  const dirs = [ADR_DIR, MIGRATIONS_DIR];
+  let committedPaths = gitTreePaths('origin/main', dirs, runGit);
+  let source = 'origin/main';
+  let degraded = false;
+  if (committedPaths === null) {
+    committedPaths = gitTreePaths('HEAD', dirs, runGit);
+    source = 'HEAD';
+    degraded = true;
+  }
+  if (committedPaths === null) {
+    committedPaths = [];
+    source = 'local-only';
+    degraded = true;
+  }
+  const localPaths = [...localDirPaths(ADR_DIR, readDir), ...localDirPaths(MIGRATIONS_DIR, readDir)];
+  const nums = computeNextNumbers({ committedPaths, localPaths });
+  return { ...nums, source, degraded };
+}
+
+const padAdr = (n) => String(n).padStart(4, '0');
+const padMig = (n) => String(n).padStart(3, '0');
+
+function main() {
+  const json = process.argv.includes('--json');
+  const r = nextNumbers();
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      adr: r.adr, migration: r.migration,
+      adr_padded: padAdr(r.adr), migration_padded: padMig(r.migration),
+      source: r.source, degraded: r.degraded,
+    }) + '\n');
+    return;
+  }
+  console.log(`Next free ADR:        ${padAdr(r.adr)}   →  docs/adr/${padAdr(r.adr)}-<slug>.md`);
+  // New CORE migrations are namespaced ${CORE_NS}_ (ADR 0108 §5) so their stem can't collide
+  // with an instance/module migration across repos. Instance seeds stay bare in
+  // migrations/instance/; a module migration is <key>_${padMig(r.migration)}_… in its own dir.
+  console.log(`Next free migration:  ${padMig(r.migration)}   →  migrations/${CORE_NS}_${padMig(r.migration)}_<slug>.sql   (core; instance seeds stay bare → migrations/instance/${padMig(r.migration)}_<slug>.sql)`);
+  console.log(`(from ${r.source} ∪ local working tree)${r.degraded ? '  ⚠ origin/main unreachable — verify before committing' : ''}`);
+}
+
+if (require.main === module) main();
+
+module.exports = { parseNumbers, nextFree, computeNextNumbers, nextNumbers, gitTreePaths, padAdr, padMig };