@bongos/core 1.17.0

package/scripts/gds/seed-governance-tasks.js

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+// Seed the 25 net-new BONGOS-V1 Governance tasks (BV1.R90-R114) defined in the
+// 2026-07-03 Governance planning session.
+//
+// Companion migration 186_bongos_v1_governance_planning_seed.sql seeds the six
+// done-when criteria (gov-perms-atom, gov-gates-permissioned, gov-full-model,
+// gov-core-project-split, gov-archon-tab, gov-boundary-proof) under goal_id=30.
+// RUN THIS SCRIPT AFTER THAT MIGRATION DEPLOYS so the criterion_id slugs resolve.
+//
+// Idempotent: skips tasks whose source_ref already exists; dependency + criterion
+// links are inserted at create (criterion_ids) and after all tasks exist (deps),
+// both idempotent server-side.
+//
+// Ranking: priority 1-5 (CHECK). Fine-grained order lives in the BV1.R## title
+// prefix (zero-padded). requires_rank auto-derives to metic on protected paths;
+// passed explicitly only to RAISE the crown-jewel tasks to archon (ADR 0084).
+//
+// Usage:  node scripts/gds/seed-governance-tasks.js [--dry-run]
+
+const { cliClient, requireSession } = require('./cli-lib');
+
+const DRY = process.argv.includes('--dry-run');
+const VERSION = 'BONGOS-V1';
+const GOAL_ID = 30;
+
+// C-slug shorthands
+const C1 = 'gov-perms-atom';
+const C2 = 'gov-gates-permissioned';
+const C3 = 'gov-full-model';
+const C4 = 'gov-core-project-split';
+const C5 = 'gov-archon-tab';
+const C6 = 'gov-boundary-proof';
+
+// Each entry: { ref, title, description, kind, priority, est_minutes,
+//   manual_degree, credits_reward, criterion_ids:[slug], depends_on_refs:[R##],
+//   touches?, requires_rank? }.  discipline is 'engineer' for all.
+const TASKS = [
+  // --- Foundation -----------------------------------------------------------
+  {
+    ref: 'R90', kind: 'spike', priority: 5, est_minutes: 240, manual_degree: 3, credits_reward: 70,
+    requires_rank: 'archon', criterion_ids: [C1], depends_on_refs: [],
+    title: 'Governance architecture — ADR + finalized permission catalog',
+    description: `**Why:** the whole goal anchors on the model. Settle it in an ADR before building.
+
+**Done when:** an ADR records the decision — permissions-as-atom, ranks become seeded roles, first-class principals + session-scopes + ownership-scoped permissions, and a protected-surface registry with "policy owns / substrate enforces"; the compatibility-seed strategy is specified; and the FULL permission catalog is enumerated (every key + \`system\` flag), grounded in the 2026-07-03 authority sweep. Output feeds R93/R94 and refines downstream sub-tasks.
+
+**Cross-refs:** builds on ADR 0016 (trust boundary), ADR 0043 (git/ssh boundary), ADR 0062 (core/host split), ADR 0083 (modules). Gates most of the goal.`,
+  },
+  {
+    ref: 'R91', kind: 'refactor', priority: 5, est_minutes: 45, manual_degree: 2, credits_reward: 25,
+    requires_rank: 'archon', criterion_ids: [C1], depends_on_refs: [],
+    touches: ['src/bongos/module-scope-map.js'],
+    title: "Add 'governance' module key + widen the Governance goal scope",
+    description: `**Why:** the module dir modules/governance/ needs a scope-map key before goal members can author tasks touching it (planning-session prep rule).
+
+**Done when:** \`module-scope-map.js\` MODULE_GLOBS gains a \`governance\` key covering modules/governance/** + config/governance*.json (protected, since it overlaps the authz core); and goal 30's scope is widened to include it (\`POST /goals/30/scope\`). Kernel-scoped → Archon.`,
+  },
+  {
+    ref: 'R92', kind: 'bug', priority: 2, est_minutes: 40, manual_degree: 1, credits_reward: 20,
+    criterion_ids: [C6], depends_on_refs: [],
+    touches: ['docs/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md', 'docs/canonical-permissions.md'],
+    title: 'Fix stale branch-protection docs (ADR 0043 + canonical-permissions)',
+    description: `**Why:** ADR 0043 and canonical-permissions.md still say the repo is a free private repo with no GitHub branch protection, so main-audit.js is the only net. That is now FALSE — main has live branch protection (required checks unit + trufflehog + gate-review, code-owner review, direct push blocked). Surfaced by the 2026-07-03 authority sweep.
+
+**Done when:** both docs describe the live state (branch protection on; main-audit.js is defense-in-depth, not the sole net). Independent of the rest of the goal — can land anytime.`,
+  },
+
+  // --- C1: permissions as atom + resolver + seed ----------------------------
+  {
+    ref: 'R93', kind: 'feature', priority: 5, est_minutes: 150, manual_degree: 2, credits_reward: 55,
+    requires_rank: 'archon', criterion_ids: [C1], depends_on_refs: ['R90', 'R91'],
+    title: 'governance_* tables + seed the four rank-roles + backfill assignments',
+    description: `**Why:** the DB home for live roles/grants/assignments and the compatibility seed that makes day one behavior-identical.
+
+**Done when:** module-owned additive migrations create \`governance_roles\`, \`governance_role_permissions\`, \`governance_builder_roles\` (all governance_*-namespaced); the four rank-roles (xenos/thetes/metic/archon) are seeded with grants matching today's thresholds (from R90's catalog); and every existing builder is backfilled a role assignment matching their current rank. Depends on R90 (catalog) + R91 (module key).`,
+  },
+  {
+    ref: 'R94', kind: 'feature', priority: 5, est_minutes: 120, manual_degree: 2, credits_reward: 45,
+    requires_rank: 'archon', criterion_ids: [C1], depends_on_refs: ['R90', 'R91'],
+    title: 'Permission catalog (code constants + system flags) in modules/governance/',
+    description: `**Why:** permissions map to real routes, so the catalog is code, not UI-invented data.
+
+**Done when:** modules/governance/ defines the full permission catalog as code constants, each flagged \`system\` (trust-boundary, non-grantable) or operational; the catalog is the single source the resolver, gates, and tab all read. Transcribes R90's enumerated catalog.`,
+  },
+  {
+    ref: 'R95', kind: 'feature', priority: 5, est_minutes: 150, manual_degree: 2, credits_reward: 55,
+    requires_rank: 'archon', criterion_ids: [C1], depends_on_refs: ['R93', 'R94'],
+    title: 'Permission resolver + kernel port (per-request, uncached)',
+    description: `**Why:** the heart of the system — turns a builder's roles into their effective permission set, preserving ADR 0016.
+
+**Done when:** \`resolveBuilderPermissions(builderId)\` returns the union of the builder's roles' permissions, resolved fresh per request with NO caching; it is exposed via a kernel port so core/auth resolves it without importing the module. Depends on R93 (data) + R94 (catalog).`,
+  },
+  {
+    ref: 'R97', kind: 'feature', priority: 5, est_minutes: 120, manual_degree: 2, credits_reward: 50,
+    requires_rank: 'archon', criterion_ids: [C1], depends_on_refs: ['R95'],
+    title: 'requirePermission() gate in auth (requireRank kept working via seed)',
+    description: `**Why:** the new gate primitive every route will use.
+
+**Done when:** \`requirePermission(...perms)\` middleware exists in auth, backed by the resolver (fail-closed, 403 on missing); \`requireRank\` keeps working unchanged (the seeded rank-roles make the two equivalent during migration). Depends on R95.`,
+  },
+  {
+    ref: 'R103', kind: 'verify', priority: 4, est_minutes: 90, manual_degree: 2, credits_reward: 40,
+    criterion_ids: [C1], depends_on_refs: ['R97'],
+    title: 'PROOF (C1): parity test — every builder resolves to today\'s exact powers',
+    description: `**Why:** the behavior-identical guarantee is the whole promise of the compat seed.
+
+**Done when:** a test enumerates every current builder + rank and asserts their resolved permission set grants exactly the routes/actions their rank allows today — no more, no less. Red if the seed drifts from the rank thresholds. Depends on R97.`,
+  },
+
+  // --- C2: migrate gates to permissions -------------------------------------
+  {
+    ref: 'R104', kind: 'refactor', priority: 4, est_minutes: 150, manual_degree: 2, credits_reward: 50,
+    requires_rank: 'archon', criterion_ids: [C2], depends_on_refs: ['R97'],
+    title: 'Migrate core src/bongos/routes/ gates requireRank -> requirePermission',
+    description: `**Why:** rank stops being special in core routes.
+
+**Done when:** every rank-gated route under src/bongos/routes/ uses \`requirePermission\` with the catalog key mapping to its capability; behavior unchanged (verified against R103's parity intent). Depends on R97.`,
+  },
+  {
+    ref: 'R105', kind: 'refactor', priority: 4, est_minutes: 180, manual_degree: 2, credits_reward: 55,
+    criterion_ids: [C2], depends_on_refs: ['R97'],
+    title: 'Migrate all modules/*/routes gates -> requirePermission',
+    description: `**Why:** the bulk of the ~60 gates live in feature modules (lifecycle, ideas, dev-box, security, ...).
+
+**Done when:** every rank-gated module write route uses \`requirePermission\`; behavior unchanged. Depends on R97.`,
+  },
+  {
+    ref: 'R106', kind: 'refactor', priority: 4, est_minutes: 120, manual_degree: 3, credits_reward: 50,
+    requires_rank: 'archon', criterion_ids: [C2], depends_on_refs: ['R97'],
+    title: 'Re-express claim eligibility as permissions',
+    description: `**Why:** claim-time authority (xenosClaimAllowed / rankAllowsTask / per-task requires_rank) is rank-driven today; it should read permissions too.
+
+**Done when:** claim eligibility resolves against permissions (e.g. task.claim.newcomer / task.claim.any) rather than the rank ladder directly; per-task floor still honored; abuse cases (a low-trust builder claiming out of scope) still blocked. Trust-sensitive → Archon. Depends on R97.`,
+  },
+  {
+    ref: 'R107', kind: 'refactor', priority: 4, est_minutes: 100, manual_degree: 2, credits_reward: 40,
+    criterion_ids: [C2], depends_on_refs: ['R97'],
+    title: 'Re-express page gates + wandering clamp as permissions',
+    description: `**Why:** the HTML page gates (requireArchonPage/requireNonXenosPage/requireBuilderPage) and the wandering-prefs rank-derived clamp are the remaining rank-keyed surfaces.
+
+**Done when:** page gates resolve via permissions; the wandering clamp's rank-default/ceiling is expressed via role metadata/permissions. Depends on R97.`,
+  },
+  {
+    ref: 'R108', kind: 'refactor', priority: 3, est_minutes: 90, manual_degree: 2, credits_reward: 40,
+    criterion_ids: [C2], depends_on_refs: ['R104', 'R105', 'R106', 'R107'],
+    title: 'Collapse the ~6 duplicated numeric rank-tier maps into the resolver',
+    description: `**Why:** RANK_TIER / REQUIRES_RANK_TIER / RANK_ORDER / RANK_DEFAULT are hand-copied in ~6 places (a known drift risk). Once gates read permissions, they collapse.
+
+**Done when:** the duplicated tier maps are removed/centralized behind the resolver; a test/fitness guard prevents reintroducing a parallel map. Depends on R104-R107.`,
+  },
+  {
+    ref: 'R109', kind: 'infra', priority: 4, est_minutes: 90, manual_degree: 2, credits_reward: 40,
+    requires_rank: 'archon', criterion_ids: [C2], depends_on_refs: ['R104', 'R105'],
+    title: 'Update route-rank-check fitness to assert permission gates',
+    description: `**Why:** the fitness gate that catches ungated/downgraded write routes must understand \`requirePermission\`, not just \`requireRank\`.
+
+**Done when:** route-rank-check recognizes permission gates, its EXPECTED pins are re-expressed in permission terms, and an ungated/under-gated write route still hard-fails the build. Depends on R104/R105.`,
+  },
+
+  // --- C3: the complete authority model -------------------------------------
+  {
+    ref: 'R98', kind: 'feature', priority: 4, est_minutes: 120, manual_degree: 2, credits_reward: 45,
+    criterion_ids: [C3], depends_on_refs: ['R95'],
+    title: 'First-class principals (machine identities) in the model',
+    description: `**Why:** BFG + Discord bot are gated on exact system_role, not rank — a governance axis roles don't cover.
+
+**Done when:** the model represents principals as a first-class type (provisioned out-of-band, never UI-grantable), the resolver/gates treat a principal's capability distinctly from a builder's roles, and the governance tab shows (but cannot grant) them. Depends on R95.`,
+  },
+  {
+    ref: 'R99', kind: 'feature', priority: 4, est_minutes: 100, manual_degree: 2, credits_reward: 40,
+    criterion_ids: [C3], depends_on_refs: ['R95'],
+    title: 'First-class session-scopes (box-scoped tokens)',
+    description: `**Why:** a box-scoped session is limited even when its builder isn't — capability attached to the session, orthogonal to roles.
+
+**Done when:** session-scope is a first-class capability the resolver honors (a box session's effective permissions are the deny-by-default allow-list, regardless of the builder's roles); modeled explicitly rather than as the current ad-hoc allowBoxScope flag. Depends on R95.`,
+  },
+  {
+    ref: 'R100', kind: 'feature', priority: 4, est_minutes: 90, manual_degree: 2, credits_reward: 40,
+    criterion_ids: [C3], depends_on_refs: ['R95'],
+    title: 'Ownership-scoped permissions ("act on own X")',
+    description: `**Why:** own-box / own-memory / own-credential / own-claim are "may act on OWN X" — a parameterized permission, not a global grant.
+
+**Done when:** the catalog + resolver express ownership-scoped permissions so a route can require "manage own X" distinctly from "manage any X"; existing own-scoped routes migrate to it. Depends on R95.`,
+  },
+  {
+    ref: 'R101', kind: 'feature', priority: 4, est_minutes: 180, manual_degree: 3, credits_reward: 60,
+    requires_rank: 'archon', criterion_ids: [C3], depends_on_refs: ['R95'],
+    title: 'Protected-surface registry (governance-owned data; substrate enforces)',
+    description: `**Why:** the biggest single task. PROTECTED_GLOBS / EXPECTED_RANKS are today's rank->surface map baked in code; governance should OWN them as data while the out-of-band substrate stays the enforcer.
+
+**Done when:** the protected-surface registry is governance-owned data; the substrate (pre-push hook, grader pre-pass, main-audit, gate-review, goal-scope-check) reads the registry rather than a hardcoded list; the Metic floor + system-permission mapping flow from it; and "policy owns / substrate enforces" is provable (the tab can re-map the floor but cannot move enforcement into the app). Depends on R95. See R90's ADR.`,
+  },
+
+  // --- C4: core / project split ---------------------------------------------
+  {
+    ref: 'R96', kind: 'feature', priority: 4, est_minutes: 100, manual_degree: 2, credits_reward: 40,
+    criterion_ids: [C4], depends_on_refs: ['R93', 'R94'],
+    title: 'config/governance.json + neutral + resolve-over-neutral',
+    description: `**Why:** role templates/defaults are per-instance config (the branding pattern); live data is DB.
+
+**Done when:** \`config/governance.json\` (instance) resolves over \`config/governance.neutral.json\` (neutral) with env override on top, mirroring src/branding.js precedence; it seeds the starting role templates a fresh instance inherits; live assignments stay in the DB (R93). Depends on R93/R94.`,
+  },
+  {
+    ref: 'R102', kind: 'verify', priority: 3, est_minutes: 70, manual_degree: 2, credits_reward: 35,
+    criterion_ids: [C4], depends_on_refs: ['R96'],
+    title: 'PROOF (C4): vanilla-boot check — neutral defaults, no OTB identity',
+    description: `**Why:** the core/host split only holds if a fresh instance boots clean.
+
+**Done when:** a test/fitness boots governance with only the neutral config and asserts sane default roles, no OTB-specific identity, and the trust boundary intact. Depends on R96.`,
+  },
+
+  // --- C5: the Archon Governance tab ----------------------------------------
+  {
+    ref: 'R110', kind: 'feature', priority: 4, est_minutes: 150, manual_degree: 2, credits_reward: 55,
+    requires_rank: 'archon', criterion_ids: [C5], depends_on_refs: ['R97', 'R109'],
+    title: 'Governance API routes (roles/perms/assignments CRUD)',
+    description: `**Why:** the tab's server surface.
+
+**Done when:** routes list roles/permissions/assignments, create a role, toggle an operational permission on a role, and assign a role to a builder — all gated \`governance.manage\` (Archon), system permissions rejected as non-grantable server-side, and pinned in route-rank-check. Depends on R97 + R109.`,
+  },
+  {
+    ref: 'R111', kind: 'feature', priority: 3, est_minutes: 180, manual_degree: 2, credits_reward: 55,
+    criterion_ids: [C5], depends_on_refs: ['R110'],
+    title: 'Governance hall page (role list, permission grid, assign)',
+    description: `**Why:** the thing you can see — Discord-style.
+
+**Done when:** modules/hall-ui/public/governance.{html,js} renders the role list, a per-role permission grid (toggle operational perms), and assign-role-to-builder; \`system\` permissions render LOCKED (visible, not togglable); uses existing style.css tokens (theme-aware). Copies the gate.js Archon-page pattern. Depends on R110.`,
+  },
+  {
+    ref: 'R113', kind: 'feature', priority: 3, est_minutes: 45, manual_degree: 1, credits_reward: 25,
+    criterion_ids: [C5], depends_on_refs: ['R111'],
+    touches: ['modules/hall-ui/public/shell.js', 'src/bongos/serve-internal.js'],
+    title: 'Governance nav entry + page gate',
+    description: `**Why:** wire the page into the hall, Archon-only, defense-in-depth.
+
+**Done when:** shell.js NAV gains a \`governance\` item in the Archon group (gate: 'archon'); serve-internal adds a GOVERNANCE_PAGE_RE to the requireArchonPage block. Depends on R111.`,
+  },
+
+  // --- C6: proof + docs -----------------------------------------------------
+  {
+    ref: 'R112', kind: 'verify', priority: 3, est_minutes: 120, manual_degree: 3, credits_reward: 50,
+    criterion_ids: [C6], depends_on_refs: ['R101', 'R110'],
+    title: 'Abuse-matrix test — no config can grant deploy/protected-path access',
+    description: `**Why:** the safety guarantee must be mechanically proven, not asserted.
+
+**Done when:** a test enumerates the abuse matrix — every attempt to grant a \`system\` permission (deploy, protected-path) to a custom role / low-trust builder is rejected server-side, and the substrate still blocks the action even if a grant were forced. The wall holds. Depends on R101 + R110.`,
+  },
+  {
+    ref: 'R114', kind: 'verify', priority: 2, est_minutes: 90, manual_degree: 3, credits_reward: 45,
+    criterion_ids: [C6], depends_on_refs: ['R111', 'R112'],
+    title: 'PROOF (C6): live demo — custom role works, system permission holds',
+    description: `**Why:** the end-to-end live demonstration that closes the goal.
+
+**Done when:** on the sandbox/staging, an Archon creates a custom role granting an operational permission, assigns it to a builder, and that builder can perform the operational action — WHILE a \`system\` permission the role also "has" stays enforced by substrate (the deploy/protected-path attempt is still blocked). Depends on R111 (tab) + R112 (matrix).`,
+  },
+];
+
+async function main() {
+  await requireSession();
+  const api = await cliClient();
+
+  const list = await api.tasks.getTasks({ query: { version: VERSION } });
+  const bySourceRef = {};
+  for (const t of list.data?.tasks || []) {
+    if (t.source_ref) bySourceRef[t.source_ref] = t;
+  }
+
+  const refToId = {}; // R## -> task id (existing or newly created)
+  let created = 0, skipped = 0, errors = 0;
+
+  // Pass 1: create tasks (with criterion_ids at create).
+  for (const def of TASKS) {
+    const source_ref = `bongos-v1-gov-${def.ref.toLowerCase()}`;
+    if (bySourceRef[source_ref]) {
+      refToId[def.ref] = bySourceRef[source_ref].id;
+      console.log(`SKIP  ${def.ref} (exists: id=${bySourceRef[source_ref].id})`);
+      skipped++;
+      continue;
+    }
+    const body = {
+      version_id: VERSION,
+      goal_id: GOAL_ID,
+      title: `BV1.${def.ref} — ${def.title}`,
+      description: def.description,
+      kind: def.kind,
+      discipline: 'engineer',
+      status: 'backlog',
+      priority: def.priority,
+      est_minutes: def.est_minutes,
+      manual_degree: def.manual_degree,
+      credits_reward: def.credits_reward,
+      touches: def.touches || [],
+      criterion_ids: def.criterion_ids,
+      source: 'planning-session',
+      source_ref,
+    };
+    if (def.requires_rank) body.requires_rank = def.requires_rank;
+    if (DRY) {
+      console.log(`DRY   ${def.ref}  P${def.priority}  ${def.kind}  ${def.est_minutes}m  ->[${def.criterion_ids.join(',')}] deps[${def.depends_on_refs.join(',')}]`);
+      continue;
+    }
+    const res = await api.tasks.postTasks({ body });
+    if (res.status !== 201) {
+      console.error(`FAIL  ${def.ref}: status=${res.status} ${JSON.stringify(res.data).slice(0, 240)}`);
+      errors++;
+      continue;
+    }
+    refToId[def.ref] = res.data.task.id;
+    console.log(`OK    ${def.ref} -> id=${res.data.task.id}  [${def.criterion_ids.join(',')}]`);
+    created++;
+  }
+
+  if (DRY) { console.log('\nDRY run — no deps posted.'); return; }
+
+  // Pass 2: wire dependencies (idempotent server-side).
+  let depEdges = 0, depErrors = 0;
+  for (const def of TASKS) {
+    if (!def.depends_on_refs.length) continue;
+    const id = refToId[def.ref];
+    if (!id) { console.error(`DEP-SKIP ${def.ref}: no id`); continue; }
+    const depIds = def.depends_on_refs.map((r) => refToId[r]).filter(Boolean).map(Number);
+    if (depIds.length !== def.depends_on_refs.length) {
+      console.error(`DEP-WARN ${def.ref}: unresolved refs ${JSON.stringify(def.depends_on_refs)}`);
+    }
+    if (!depIds.length) continue;
+    const res = await api.tasks.postTasksIdDependencies({ id, body: { depends_on_task_ids: depIds } });
+    if (res.status !== 200) {
+      console.error(`DEP-FAIL ${def.ref}: status=${res.status} ${JSON.stringify(res.data).slice(0, 200)}`);
+      depErrors++;
+      continue;
+    }
+    depEdges += depIds.length;
+    console.log(`DEP   ${def.ref} <- [${def.depends_on_refs.join(',')}]`);
+  }
+
+  console.log(`\nDONE  created=${created} skipped=${skipped} errors=${errors} dep_edges=${depEdges} dep_errors=${depErrors}  (manifest: ${TASKS.length})`);
+  process.exit(errors === 0 && depErrors === 0 ? 0 : 1);
+}
+
+main().catch((err) => { console.error('FATAL', err); process.exit(1); });