@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/move-escalation.js

@@ -0,0 +1,141 @@
+'use strict';
+//
+// scripts/bongos/move-escalation.js — a core move nobody can heal reaches a person: one blocker
+// and one Discord notice per failed move, closed by itself when a later move lands (task
+// 1004449, goal 1000090 deploy self-heal).
+//
+// WHY. After task 1004448 a failed /deploy move ends one of three ways: it waits and retries
+// (transient), it is fixed and retried (known_wedge), or it is retired. A retired
+// needs_decision move is the owner's own rule refusing it, and the deploy page says so. But a
+// move retired as `unknown` — an unlisted failure, a fix that did not hold, and every
+// rollback that FAILED (the project may be down) — only wrote a line on the intent, which
+// nobody reads until they open the page. That is exactly the failure that needs a person.
+//
+// EDGE-TRIGGERED, WITHOUT NEW STATE. The blocker's (source, source_ref) is unique, and
+// source_ref names the INTENT: `core-move:<instance id>:<intent id>`. An intent retires once,
+// so a failed move files one blocker however many retries led up to it, and a re-run of the
+// same retire files nothing. The Discord notice is posted only when the insert actually
+// created the row, so it is exactly as edge-triggered as the blocker.
+//
+// CLOSED BY SUCCESS. A later core move on the same project that lands resolves every open
+// blocker this file filed for that project, with a note saying which move fixed it, and
+// posts one all-clear. A person can still resolve one by hand; this never reopens it.
+//
+// The Discord copy names a project only when it is public on the platform's map (the rule
+// liveness-notify.js keeps), and never carries upgrade output — that stays in the blocker,
+// inside the trust boundary. Writes go through the runner's own db handle (the hub
+// database, where the blockers table lives), not modules/ideas/blockers.js's shared pool,
+// which this CLI process never opens; the INSERT is that file's createBlocker, verbatim.
+
+const { execFile } = require('child_process');
+const { REPO_ROOT } = require('./provision-config.js');
+
+const BLOCKER_SOURCE = 'provisioning';
+const REF_PREFIX = 'core-move';
+const DETAIL_MAX = 1500;
+
+/** Does this retired move need a person? PURE. */
+function needsPerson({ intent, failure, terminal }) {
+  if (!intent || intent.action !== 'core-upgrade') return false;
+  return !!terminal || !!(failure && (failure.class === 'unknown' || failure.reason === 'rollback_failed'));
+}
+
+function sourceRef(inst, intent) { return `${REF_PREFIX}:${inst.id}:${intent.id}`; }
+
+function projectName(inst, provisioning) {
+  try { return provisioning.effectiveSettings(inst).visibility === 'public' ? inst.slug : null; } catch { return null; }
+}
+
+/** The blocker a failed move files. PURE. */
+function blockerFor({ inst, intent, failure, error }) {
+  const reason = (failure && failure.reason) || 'unknown';
+  const down = reason === 'rollback_failed';
+  const to = intent.target_version || '(no target)';
+  const detail = String(error || '').slice(0, DETAIL_MAX).replace(/```/g, "'''");
+  return {
+    title: down
+      ? `${inst.slug}: the core move to ${to} failed AND its rollback did not finish — the project may be down`
+      : `${inst.slug}: the core move to ${to} failed and the runner cannot fix it`,
+    bodyMd: [
+      `**Project:** ${inst.slug} (instance ${inst.id}) · **target:** ${to} · **reason:** \`${reason}\` · **move:** intent ${intent.id}`,
+      '',
+      down
+        ? 'The move changed the project, failed, and the automatic rollback also failed. It may be down or on a half-installed core. Check it before anything else.'
+        : 'The runner retired this move: it is not a known snag it can fix, or its one automatic fix did not work. Nothing is being retried.',
+      '',
+      'What the move reported:',
+      '```',
+      detail || '(nothing)',
+      '```',
+      '',
+      'This closes by itself when a later core move on this project succeeds.',
+    ].join('\n'),
+    source: BLOCKER_SOURCE,
+    sourceRef: sourceRef(inst, intent),
+  };
+}
+
+/** The owner-facing Discord line. `name` null → described, never identified. PURE. */
+function noticeText({ kind, name, to, down }) {
+  const who = name ? `**${name}**` : 'A private project';
+  if (kind === 'fixed') return `✅ ${who} took its core update${to ? ` to ${to}` : ''}; the earlier failed update is closed.`;
+  return down
+    ? `🚨 ${who}: a core update failed and could not be undone. The project may be down. A blocker is open with the details.`
+    : `⚠️ ${who}: a core update${to ? ` to ${to}` : ''} failed in a way the platform cannot fix by itself. A blocker is open with the details. Nothing is being retried.`;
+}
+
+// Fire-and-forget, the liveness-notify.js postNotice shape: CHAT_DRY_RUN=1 short-circuits and
+// a Discord hiccup never stalls the drain.
+function postNotice(text, { log = console.log } = {}) {
+  if (!text) return;
+  if (process.env.CHAT_DRY_RUN === '1') { log(`[core-move] [broadcast dry-run] would post: ${text}`); return; }
+  try {
+    execFile('node', ['scripts/discord/post.js', text], { cwd: REPO_ROOT, timeout: 10_000 }, (err) => {
+      if (err) log(`[core-move] notice broadcast failed (non-blocking): ${err.message}`);
+    });
+  } catch (e) { log(`[core-move] notice broadcast failed (non-blocking): ${(e && e.message) || e}`); }
+}
+
+/** After a move is retired: file its blocker and notice, once. Never throws. */
+async function afterRetire({ intent, inst, result, deps }) {
+  const failure = result && result.failure;
+  if (!deps.apply || !needsPerson({ intent, failure, terminal: result && result.terminal })) return { filed: false };
+  const b = blockerFor({ inst, intent, failure, error: result.error });
+  try {
+    const { rows } = await deps.db.query(
+      `INSERT INTO blockers (title, body_md, source, source_ref)
+       VALUES ($1, $2, $3, $4)
+       ON CONFLICT (source, source_ref) WHERE source IS NOT NULL AND source_ref IS NOT NULL
+         DO NOTHING
+       RETURNING id`, [b.title, b.bodyMd, b.source, b.sourceRef]);
+    if (!rows || !rows[0]) return { filed: false };
+    const down = (failure && failure.reason) === 'rollback_failed';
+    (deps.postNotice || postNotice)(noticeText({ kind: 'failed', name: projectName(inst, deps.provisioning), to: intent.target_version, down }), { log: deps.log });
+    (deps.log || (() => {}))(`  ⚑ filed blocker ${rows[0].id} for ${inst.slug}'s failed move to ${intent.target_version}`);
+    return { filed: true, blockerId: rows[0].id };
+  } catch (e) {
+    (deps.log || (() => {}))(`  ⚠ could not file a blocker for ${inst.slug}'s failed move: ${(e && e.message) || e}`);
+    return { filed: false };
+  }
+}
+
+/** After a move LANDS: close every open blocker this file filed for the project. Never throws. */
+async function afterSuccess({ intent, inst, result, deps }) {
+  if (!deps.apply || !intent || intent.action !== 'core-upgrade' || !result || result.ok === false || result.noop) return { closed: 0 };
+  const to = result.served || intent.target_version;
+  try {
+    const { rows } = await deps.db.query(
+      `UPDATE blockers SET status = 'resolved', resolved_at = now(), resolution_note = $3
+        WHERE status = 'open' AND source = $1 AND source_ref LIKE $2
+        RETURNING id`,
+      [BLOCKER_SOURCE, `${REF_PREFIX}:${inst.id}:%`, `closed automatically: a later core move to ${to} succeeded (intent ${intent.id})`]);
+    const n = (rows || []).length;
+    if (n) (deps.postNotice || postNotice)(noticeText({ kind: 'fixed', name: projectName(inst, deps.provisioning), to }), { log: deps.log });
+    return { closed: n };
+  } catch (e) {
+    (deps.log || (() => {}))(`  ⚠ could not close ${inst.slug}'s core-move blockers: ${(e && e.message) || e}`);
+    return { closed: 0 };
+  }
+}
+
+module.exports = { BLOCKER_SOURCE, REF_PREFIX, needsPerson, sourceRef, blockerFor, noticeText, postNotice, afterRetire, afterSuccess };

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

@@ -1,5 +1,5 @@
 {
-  "_doc": "Supply knob for the deterministic newcomer-task floor replenisher (scripts/gds/newcomer-floor.js) and the on-claim restock (src/bongos/newcomer-restock.js). As of task 1488 each discipline holds a LIST of chore templates, and each chore keeps its OWN standing pool to its OWN `floor` (declared per-template in newcomer-floor.templates.json). The `floor` in this disciplines map is now the DEFAULT applied to any template that omits its own — i.e. a fallback, not the primary knob. The pool is measured in READY copies of each template (source_ref tmpl:<discipline>:<template_id>:<seq>); when a chore's ready copies drop below its floor, fresh identical copies are stamped — deterministic, no AI subagent, no 401. The CHORE definitions (and their per-template floors) live in templates.json (edit there to add/change a chore or tune its pool depth).",
+  "_doc": "Supply knob for the deterministic newcomer-task floor replenisher (scripts/bongos/newcomer-floor.js) and the on-claim restock (src/bongos/newcomer-restock.js). As of task 1488 each discipline holds a LIST of chore templates, and each chore keeps its OWN standing pool to its OWN `floor` (declared per-template in newcomer-floor.templates.json). The `floor` in this disciplines map is now the DEFAULT applied to any template that omits its own — i.e. a fallback, not the primary knob. The pool is measured in READY copies of each template (source_ref tmpl:<discipline>:<template_id>:<seq>); when a chore's ready copies drop below its floor, fresh identical copies are stamped — deterministic, no AI subagent, no 401. The CHORE definitions (and their per-template floors) live in templates.json (edit there to add/change a chore or tune its pool depth).",
   "_review_gate": "`auto_promote` is the review toggle for the CLI seeder. true -> stamped copies land at status='ready' (claimable immediately). Safe here because output is deterministic and the templates are pre-approved (set true 2026-06-16, owner decision). false -> copies land at status='backlog' (NOT Xenos-claimable) for an Archon to promote via POST /api/bongos/tasks/:id/promote. (The on-claim restock always stamps 'ready' — it tops a just-claimed chore's pool back up so the shelf is never empty.)",
   "_floor_note": "Per-template `floor` lives in newcomer-floor.templates.json (next to each chore's credits_reward + est_minutes). The disciplines map below is only the per-discipline DEFAULT used when a template omits its own floor. credits_reward is never read from here.",
   "templates_path": "newcomer-floor.templates.json",

package/scripts/bongos/newcomer-floor.js

@@ -0,0 +1,421 @@
+#!/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/bongos/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/bongos/newcomer-floor.js                 # check floor; stamp copies to fill deficits
+//   node scripts/bongos/newcomer-floor.js --check         # report floor + deficits only; no writes
+//   node scripts/bongos/newcomer-floor.js --dry-run       # print what WOULD be stamped; create nothing
+//   node scripts/bongos/newcomer-floor.js --auto-promote  # force status='ready' (overrides config)
+//   node scripts/bongos/newcomer-floor.js --discipline artist   # only this discipline
+//   node scripts/bongos/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)
+// The crafts this seeder will stamp chores for. Deliberately a literal and NOT
+// enabledDisciplines(): this CLI seeds a REMOTE instance, whose enabled modules are
+// not this checkout's, so gating on the local module set would seed the wrong shelf.
+// It is the craft VOCABULARY, which is why 'unclassified' is absent. Keep in step
+// with the keys in newcomer-floor.templates.json ('ui' added by task 1003487); the
+// server-side restock reads the live offered set instead (newcomer-restock.js).
+const VALID_DISCIPLINES = new Set(['engineer', 'artist', 'ideator', 'ui']);
+// 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'; a Metic+ builder 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: a Metic+ builder promotes the new backlog copies to ready:');
+    console.log('  node scripts/bongos/api.js POST /api/bongos/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,
+};