@bongos/core 1.17.0

package/scripts/gds/newcomer-floor.js

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+// Newcomer task floor — deterministic copy-stamping replenisher.
+// Task 614 (original AI version) → task 1158 (deterministic rewrite) → task 1488
+// (multiple chores per discipline).
+//
+// THE GAP this closes: a freshly-onboarded builder (Xenos, or a brand-new Metic)
+// can only claim tasks flagged `newcomer_friendly`. The supply drains as builders
+// claim them. The original task-614 replenisher GENERATED fresh tasks via an Opus
+// subagent — but that spawns a headless `claude -p` that 401s outside an authed
+// session, so the floor silently drained to 0/0/0 and stayed there.
+//
+// WHAT THIS DOES NOW: each discipline defines a LIST of EVERGREEN chores in
+// `newcomer-floor.templates.json` (engineer = "add a unit test" + the constrained
+// docs-hygiene sweep; artist = generate an asset; ideator = file ideas). A chore's
+// definition never changes, yet running it is always valuable. Each chore keeps its
+// OWN standing pool to its OWN per-template `floor`; when a chore's ready copies drop
+// below that floor, this script stamps fresh IDENTICAL claimable COPIES of it. No AI,
+// no subprocess, no 401.
+//
+// THE MODEL (Kanban replenishment, now per-chore):
+//   - TEMPLATE  = one canonical chore (durable; never claimed, never ships).
+//   - COPY      = a disposable GDS task one newcomer claims + ships once.
+//   - FLOOR     = keep N ready copies PER CHORE; refill as they drain. `floor` lives
+//                 per-template in templates.json (the per-discipline value in
+//                 newcomer-floor.config.json is the fallback default).
+//
+// IDEMPOTENT, two ways:
+//   1. Per-chore deficit counts ready + backlog copies of THAT template. Once a chore
+//      is at floor, the next run is a no-op for it.
+//   2. Each copy carries a UNIQUE per-instance source_ref
+//      `tmpl:<discipline>:<template_id>:<seq>` where seq is monotonic across ALL
+//      statuses (open + shipped + abandoned), so a re-stamp never collides with an
+//      existing copy's ref — and identical-title copies do NOT dedup against each other.
+//
+// REVIEW GATE (config.auto_promote):
+//   true  (current) -> copies land status='ready' (live immediately). Safe: output is
+//                      deterministic and the templates are pre-approved.
+//   false           -> copies land status='backlog' for an Archon to promote.
+//
+// AUTH: POST /api/gds/tasks is archon-gated (creating work is scope-shaping —
+// ADR 0016). Run under an Archon session (on the droplet, the operator's).
+//
+// Usage:
+//   node scripts/gds/newcomer-floor.js                 # check floor; stamp copies to fill deficits
+//   node scripts/gds/newcomer-floor.js --check         # report floor + deficits only; no writes
+//   node scripts/gds/newcomer-floor.js --dry-run       # print what WOULD be stamped; create nothing
+//   node scripts/gds/newcomer-floor.js --auto-promote  # force status='ready' (overrides config)
+//   node scripts/gds/newcomer-floor.js --discipline artist   # only this discipline
+//   node scripts/gds/newcomer-floor.js --config <path> --json
+//
+// Exit codes: 0 ok (incl. no-op) · 1 api/network error · 2 bad invocation ·
+//             10 re-auth needed (cli-lib forces this on a 401).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { cliClient, requireSession } = require('./cli-lib');
+
+const DEFAULT_CONFIG_PATH = path.join(__dirname, 'newcomer-floor.config.json');
+const SOURCE_TAG = 'newcomer-template';
+const HARD_MAX_MINUTES = 60; // newcomer scope ceiling, never exceeded (task 614)
+const VALID_DISCIPLINES = new Set(['engineer', 'artist', 'ideator']);
+// Every status a copy's source_ref could occupy — scanned so `seq` is globally
+// monotonic and never recycles a ref already used by a shipped/abandoned copy.
+const ALL_STATUSES = ['backlog', 'ready', 'active', 'completed', 'confirmed', 'shipped', 'blocked', 'abandoned'];
+
+// ---------- pure helpers (exported for the co-located test) ----------
+
+function arg(name, args) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : null;
+}
+
+// Unique per-COPY anchor. Same template + different seq -> different ref, so a
+// pile of identical-title copies never dedups against itself.
+function instanceSourceRef(discipline, templateId, seq) {
+  return `tmpl:${discipline}:${templateId}:${seq}`;
+}
+
+// Parse the seq out of a tmpl: ref iff it matches this discipline+template.
+// Returns a positive integer, or null if the ref isn't ours / is malformed.
+function parseSeq(ref, discipline, templateId) {
+  const prefix = `tmpl:${discipline}:${templateId}:`;
+  if (typeof ref !== 'string' || !ref.startsWith(prefix)) return null;
+  const n = Number(ref.slice(prefix.length));
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+// Decompose any tmpl:<disc>:<template_id>:<seq> ref (template_ids are colon-free
+// kebab-case). Returns { discipline, templateId, seq } or null for a non-chore ref.
+function parseRef(ref) {
+  if (typeof ref !== 'string') return null;
+  const parts = ref.split(':');
+  if (parts.length !== 4 || parts[0] !== 'tmpl') return null;
+  const seq = Number(parts[3]);
+  if (!Number.isInteger(seq) || seq <= 0) return null;
+  return { discipline: parts[1], templateId: parts[2], seq };
+}
+
+// Next monotonic seq for a template = 1 + the max seq among all existing refs
+// (any status). `existingRefs` is an iterable of source_ref strings.
+function nextSeq(existingRefs, discipline, templateId) {
+  let max = 0;
+  for (const ref of existingRefs || []) {
+    const s = parseSeq(ref, discipline, templateId);
+    if (s !== null && s > max) max = s;
+  }
+  return max + 1;
+}
+
+// A chore's pool depth: its own `floor`, else the per-discipline default, else 0.
+function templateFloor(template, discipline, floorDefaults) {
+  const own = Number(template && template.floor);
+  if (Number.isFinite(own) && own >= 0) return own;
+  return (floorDefaults || {})[discipline] || 0;
+}
+
+// Per-CHORE deficits. Iterates the TEMPLATES (source of truth for what chores
+// exist) so a chore with zero supply still shows its full-floor deficit. `supply`
+// is keyed `${discipline}:${template_id}` -> {ready, backlog}. Returns a flat array
+// of { discipline, template_id, floor, ready, backlog, needed }.
+function computeTemplateDeficits(supply, templatesByDisc, floorDefaults, { only = null } = {}) {
+  const out = [];
+  for (const [disc, list] of Object.entries(templatesByDisc || {})) {
+    if (only && disc !== only) continue;
+    if (!VALID_DISCIPLINES.has(disc)) continue;
+    for (const t of list || []) {
+      const floor = templateFloor(t, disc, floorDefaults);
+      const c = (supply && supply[`${disc}:${t.template_id}`]) || { ready: 0, backlog: 0 };
+      const have = (Number(c.ready) || 0) + (Number(c.backlog) || 0);
+      out.push({
+        discipline: disc,
+        template_id: t.template_id,
+        floor,
+        ready: Number(c.ready) || 0,
+        backlog: Number(c.backlog) || 0,
+        needed: Math.max(0, floor - have),
+      });
+    }
+  }
+  return out;
+}
+
+// Assemble a copy's description: template body + explicit done-when block +
+// evergreen-newcomer footer.
+function buildDescription(proposal, discipline) {
+  const parts = [];
+  if (proposal.description) parts.push(proposal.description);
+  if (proposal.done_when && proposal.done_when.length) {
+    parts.push('**Done when:**\n' + proposal.done_when.map((d) => `- ${d}`).join('\n'));
+  }
+  parts.push(
+    `_Evergreen newcomer chore — a fixed first-builder task for this discipline. The definition never ` +
+    `changes, but running it is always valuable. Scoped as a low-stakes ${discipline} task ` +
+    `(<= ${proposal.est_minutes ?? HARD_MAX_MINUTES} min). If it turns out bigger than it looks, release it and an Archon will re-scope._`
+  );
+  return parts.join('\n\n').slice(0, 50000);
+}
+
+// Coerce + clamp a template into a createable copy proposal at the given seq.
+// est_minutes is clamped to (0, HARD_MAX_MINUTES]; touches normalized; done_when
+// folded to an array. Returns null if the template is missing a usable title.
+function buildProposalFromTemplate(template, seq, { discipline } = {}) {
+  if (!template || typeof template !== 'object') return null;
+  const disc = discipline || template.discipline;
+  const title = typeof template.title === 'string' ? template.title.trim().slice(0, 200) : '';
+  if (!title) return null;
+
+  let est = Math.round(Number(template.est_minutes));
+  if (!Number.isFinite(est) || est <= 0) est = HARD_MAX_MINUTES;
+  est = Math.min(est, HARD_MAX_MINUTES);
+
+  const touches = Array.isArray(template.touches)
+    ? template.touches.map((t) => String(t).trim()).filter(Boolean).slice(0, 20)
+    : [];
+
+  const doneWhen = Array.isArray(template.done_when)
+    ? template.done_when.map((d) => String(d).trim()).filter(Boolean)
+    : (typeof template.done_when === 'string' && template.done_when.trim() ? [template.done_when.trim()] : []);
+
+  const credits = Number.isFinite(Number(template.credits_reward)) ? Number(template.credits_reward) : 15;
+
+  return {
+    title,
+    description: typeof template.description === 'string' ? template.description.trim() : '',
+    done_when: doneWhen,
+    touches,
+    est_minutes: est,
+    credits_reward: credits,
+    kind: typeof template.kind === 'string' ? template.kind : 'feature',
+    version_id: template.version_id,
+    discipline: disc,
+    template_id: template.template_id,
+    source_ref: instanceSourceRef(disc, template.template_id, seq),
+    seq,
+  };
+}
+
+// ---------- plumbing (network side effects) ----------
+
+// Await a generated-client call ({status,ok,data}) and throw a uniform error on
+// a non-ok response. `label` is a human-readable "METHOD /path" tag for the msg.
+async function call(label, resultPromise) {
+  const r = await resultPromise;
+  if (!r.ok) {
+    const msg = r.data && (r.data.error || r.data.message) ? `${r.data.error || ''} ${r.data.message || ''}`.trim() : `HTTP ${r.status}`;
+    throw new Error(`${label} -> ${msg}`);
+  }
+  return r.data;
+}
+
+function loadConfig(configPath) {
+  const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  if (!cfg.disciplines || typeof cfg.disciplines !== 'object') {
+    throw new Error(`${configPath}: missing "disciplines" map`);
+  }
+  return cfg;
+}
+
+// Load + lightly validate the canonical templates. Each discipline maps to a LIST
+// of chores (a bare object is tolerated and wrapped for back-compat). Every entry
+// must carry a template_id, title and version_id. Returns { discipline: [templates] }.
+function loadTemplates(templatesPath) {
+  const raw = JSON.parse(fs.readFileSync(templatesPath, 'utf8'));
+  const out = {};
+  for (const disc of VALID_DISCIPLINES) {
+    if (!raw[disc]) continue; // a missing discipline is allowed (skipped at run time)
+    const list = Array.isArray(raw[disc]) ? raw[disc] : [raw[disc]];
+    for (const t of list) {
+      if (!t || !t.template_id || !t.title || !t.version_id) {
+        throw new Error(`${templatesPath}: a "${disc}" template is missing template_id/title/version_id`);
+      }
+    }
+    out[disc] = list;
+  }
+  return out;
+}
+
+// Scan every status once: collect all tmpl: refs (the monotonic-seq basis) AND tally
+// per-template supply (ready + backlog copies, keyed `${disc}:${template_id}`).
+//
+// Fail CLOSED: the seq-uniqueness invariant requires seeing EVERY existing tmpl: ref
+// (there is no DB unique index on source_ref). A transient scan failure must ABORT
+// (throw -> main exits 1), never proceed on an incomplete ref set and risk minting a
+// colliding seq. GET /tasks returns [] for an unknown status, so a throw here is a
+// genuine network/5xx error worth aborting on.
+async function scanTemplateInstances() {
+  const refs = new Set();
+  const supply = {};
+  const api = await cliClient();
+  for (const status of ALL_STATUSES) {
+    const data = await call(`GET /tasks?status=${status}`, api.tasks.getTasks({ query: { status } }));
+    for (const t of data.tasks || []) {
+      const r = t.source_ref;
+      if (typeof r !== 'string' || !r.startsWith('tmpl:')) continue;
+      refs.add(r);
+      if (status === 'ready' || status === 'backlog') {
+        const p = parseRef(r);
+        if (p) {
+          const key = `${p.discipline}:${p.templateId}`;
+          if (!supply[key]) supply[key] = { ready: 0, backlog: 0 };
+          supply[key][status] += 1;
+        }
+      }
+    }
+  }
+  return { refs, supply };
+}
+
+async function createCopy({ proposal, status }) {
+  const api = await cliClient();
+  const data = await call('POST /tasks', api.tasks.postTasks({
+    body: {
+      version_id: proposal.version_id,
+      title: proposal.title,
+      description: buildDescription(proposal, proposal.discipline),
+      kind: proposal.kind,
+      discipline: proposal.discipline,
+      status,
+      newcomer_friendly: true,
+      source: SOURCE_TAG,
+      source_ref: proposal.source_ref,
+      est_minutes: proposal.est_minutes,
+      credits_reward: proposal.credits_reward,
+      touches: proposal.touches,
+      priority: 4,
+      auto_detect_touches: false,
+    },
+  }));
+  return data.task || data;
+}
+
+// ---------- main ----------
+
+async function main() {
+  const args = process.argv.slice(2);
+  const FLAGS = {
+    check: args.includes('--check'),
+    dryRun: args.includes('--dry-run'),
+    json: args.includes('--json'),
+    autoPromote: args.includes('--auto-promote'),
+    discipline: arg('--discipline', args),
+    configPath: arg('--config', args) || DEFAULT_CONFIG_PATH,
+  };
+  if (FLAGS.discipline && !VALID_DISCIPLINES.has(FLAGS.discipline)) {
+    console.error(`bad --discipline "${FLAGS.discipline}"; valid: ${[...VALID_DISCIPLINES].join(', ')}`);
+    process.exit(2);
+  }
+
+  await requireSession();
+  const config = loadConfig(FLAGS.configPath);
+  const templatesPath = config.templates_path
+    ? path.resolve(path.dirname(FLAGS.configPath), config.templates_path)
+    : path.join(__dirname, 'newcomer-floor.templates.json');
+  const templates = loadTemplates(templatesPath);
+  const floorDefaults = {};
+  for (const [d, c] of Object.entries(config.disciplines || {})) floorDefaults[d] = Number(c && c.floor) || 0;
+  const autoPromote = FLAGS.autoPromote || config.auto_promote === true;
+  const status = autoPromote ? 'ready' : 'backlog';
+  const maxPerRun = Number(config.max_generate_per_run) || 8;
+
+  // 1. One scan -> existing refs (seq basis, mutated as we stamp) + per-chore supply.
+  const { refs: existingRefs, supply } = await scanTemplateInstances();
+
+  // 2. Per-chore deficits.
+  const deficits = computeTemplateDeficits(supply, templates, floorDefaults, { only: FLAGS.discipline });
+  const summary = { status, autoPromote, deficits, stamped: [] };
+
+  const need = deficits.filter((d) => d.needed > 0);
+  if (FLAGS.check || need.length === 0) {
+    summary.noop = need.length === 0;
+    return report(summary, FLAGS, { checkOnly: FLAGS.check });
+  }
+
+  // 3. Open-version guard: a copy can't be filed against a shipped/missing version.
+  const api = await cliClient();
+  const versions = (await call('GET /versions', api.versions.getVersions())).versions || [];
+  const versionStatus = new Map(versions.map((v) => [v.id, v.status]));
+
+  // 4. Stamp per deficient chore, honoring the per-run cap.
+  let budget = maxPerRun;
+  for (const d of need) {
+    if (budget <= 0) { summary.stamped.push({ ...d, skipped: 'per-run cap reached' }); continue; }
+    const template = (templates[d.discipline] || []).find((t) => t.template_id === d.template_id);
+    if (!template) { summary.stamped.push({ ...d, error: 'template vanished mid-run' }); continue; }
+    const vs = versionStatus.get(template.version_id);
+    if (!vs) { summary.stamped.push({ ...d, error: `template version "${template.version_id}" not found — fix templates.json` }); continue; }
+    if (vs === 'shipped') { summary.stamped.push({ ...d, error: `template version "${template.version_id}" has shipped — repoint templates.json at an open version` }); continue; }
+
+    const count = Math.min(d.needed, budget);
+    for (let i = 0; i < count; i++) {
+      const seq = nextSeq(existingRefs, d.discipline, template.template_id);
+      const proposal = buildProposalFromTemplate(template, seq, { discipline: d.discipline });
+      if (!proposal) { summary.stamped.push({ ...d, error: 'template produced no usable copy (missing title?)' }); break; }
+      existingRefs.add(proposal.source_ref); // keep seq monotonic within the run
+      if (FLAGS.dryRun) {
+        summary.stamped.push({ discipline: d.discipline, template_id: d.template_id, dryRun: true, title: proposal.title, source_ref: proposal.source_ref, version_id: proposal.version_id });
+      } else {
+        const task = await createCopy({ proposal, status });
+        summary.stamped.push({ discipline: d.discipline, template_id: d.template_id, task_id: task.id, title: task.title, status, source_ref: proposal.source_ref });
+      }
+      budget -= 1;
+      if (budget <= 0) break;
+    }
+  }
+
+  report(summary, FLAGS, { checkOnly: false });
+}
+
+function report(summary, FLAGS, { checkOnly }) {
+  if (FLAGS.json) { console.log(JSON.stringify(summary, null, 2)); return; }
+
+  console.log('Newcomer floor (per chore):');
+  for (const d of summary.deficits) {
+    const flag = d.needed > 0 ? `  ⚠ need ${d.needed}` : '  ✓';
+    console.log(`  ${d.discipline.padEnd(9)} ${d.template_id.padEnd(24)} ready=${d.ready} backlog=${d.backlog} floor=${d.floor}${flag}`);
+  }
+  if (checkOnly) { console.log('(--check: no stamping)'); return; }
+  if (summary.noop) { console.log('All chores at or above floor — nothing to stamp.'); return; }
+
+  console.log(`\nReview gate: ${summary.autoPromote ? "AUTO-PROMOTE (copies land status='ready', live now)" : "REVIEW (copies land status='backlog'; an Archon promotes to 'ready')"}${FLAGS.dryRun ? '  [DRY RUN — nothing created]' : ''}`);
+  for (const g of summary.stamped) {
+    const who = `${g.discipline}/${g.template_id}`;
+    if (g.error) console.log(`  ✗ ${who}: ${g.error}`);
+    else if (g.skipped) console.log(`  • ${who}: skipped — ${g.skipped}`);
+    else if (g.dryRun) console.log(`  ◌ ${who}: would stamp "${g.title}" (ref ${g.source_ref})`);
+    else console.log(`  ✓ ${who}: task #${g.task_id} [${g.status}] "${g.title}" (ref ${g.source_ref})`);
+  }
+  if (!summary.autoPromote && !FLAGS.dryRun && summary.stamped.some((g) => g.task_id)) {
+    console.log('\nNext: an Archon promotes the new backlog copies to ready:');
+    console.log('  node scripts/gds/api.js POST /api/gds/tasks/<id>/promote   (or the builders\' hall)');
+  }
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('[newcomer-floor]', err && err.message ? err.message : err);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  instanceSourceRef,
+  parseSeq,
+  parseRef,
+  nextSeq,
+  templateFloor,
+  computeTemplateDeficits,
+  buildDescription,
+  buildProposalFromTemplate,
+  loadTemplates,
+  loadConfig,
+  VALID_DISCIPLINES,
+  HARD_MAX_MINUTES,
+  SOURCE_TAG,
+};

package/scripts/gds/newcomer-floor.templates.json

@@ -0,0 +1,86 @@
+{
+  "_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 (src/bongos/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 (engineer=internal GDS-V4, artist+ideator=product V2); it MUST point at an open (non-shipped) version — update it at version close. 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. 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",
+      "version_id": "GDS-V4",
+      "discipline": "engineer",
+      "kind": "feature",
+      "est_minutes": 45,
+      "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. Good hunting grounds (look for an exported function with little or no matching `tests/` coverage):\n- `src/bongos/path-match.js` (`touchesOverlap`, `matchOne`), `src/bongos/llm-pricing.js` (`familyFor`, `canonicalizeModelId`), `src/bongos/task-classifier.js`, `src/bongos/render-prefs.js`, `src/bongos/wandering-prefs.js`.\n- pure parsing/format helpers exported from `scripts/gds/*.js`.\n\nCheck `tests/` first: if a helper already has a thorough test file, add a missing case to a DIFFERENT helper, or pick another module — don't duplicate existing coverage.\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.",
+      "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).",
+        "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."
+      ],
+      "touches": []
+    },
+    {
+      "template_id": "docs-hygiene-pass",
+      "version_id": "GDS-V4",
+      "discipline": "engineer",
+      "kind": "cleanup",
+      "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._",
+      "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.",
+        "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."
+      ],
+      "touches": [],
+      "floor": 1
+    }
+  ],
+  "artist": [
+    {
+      "template_id": "asset-generate-pass",
+      "version_id": "V2",
+      "discipline": "artist",
+      "kind": "feature",
+      "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\nAmazonprimea is a young ancient-Greek coastal world, and it 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>.amazonprimea.com`).\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."
+      ],
+      "touches": [],
+      "floor": 3
+    }
+  ],
+  "ideator": [
+    {
+      "template_id": "idea-seed-pass",
+      "version_id": "V2",
+      "discipline": "ideator",
+      "kind": "feature",
+      "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 world the size of Amazonprimea 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 https://amazonprimea.com/builders 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/gds/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.",
+      "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).",
+        "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, Amazonprimea, 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.",
+        "Before filing you ran `GET /api/gds/inbox` and confirmed your ideas are not near-duplicates of open ones.",
+        "You touched only the idea_inbox via capture.js — no code, no migrations, no infra, no permission/pipeline files; nothing committed to the repo."
+      ],
+      "touches": [],
+      "floor": 2
+    }
+  ]
+}