@bongos/core 1.19.535 → 1.19.536

package/modules/lifecycle/routes/project-settings.js

@@ -0,0 +1,263 @@
+'use strict';
+
+// modules/lifecycle/routes/project-settings.js — the five fundamentals of a project,
+// in one read, each carrying WHERE its value came from (task 1003280, goal 1000072,
+// criterion legibility-project-settings).
+//
+// WHY THIS ROUTE EXISTS. Goal 1000072's thesis is that this project is legible to
+// Claude and illegible to a human: the system knows everything and exposes almost
+// none of it in a shape a person can hold. The five values here — the rot timer, the
+// category set, how credits are calculated, whether equity is real, and what share of
+// upmarket revenue is paid on credits — were each answerable only by reading source.
+// This route is the TRANSLATION LAYER, not a new capability: it invents no value and
+// stores nothing of its own.
+//
+// THE ONE RULE THAT SHAPES EVERY ROW: a value is reported WITH ITS PROVENANCE. A
+// number with no provenance is what let a 6h and a 24h staleness answer coexist
+// unnoticed for months (ADR 0226), which is the exact failure this goal is named for.
+// So every row says whether it is a live knob or committed config, and names the file
+// (and ADR) it resolves from. A row the reader cannot type into must LOOK unwritable
+// and say why.
+//
+// AND THE ONE THAT KEEPS IT HONEST: a fundamental with no knob behind it is reported
+// as ABSENT, never as a plausible zero. `upmarket_percent` is that row today — the
+// task asked for it, and no such knob exists anywhere in this codebase. Rendering it
+// as "0%" would be a fabricated fact about the project's economics; saying "there is
+// no such setting yet, and here is where it would live" is the legible answer.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `../../../src/module-api`; `../goal-category` is an intra-module sibling.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const goalCategory = require('../goal-category');
+
+const log = api.logger('lifecycle');
+
+// --- the three rows that are READ, never written -----------------------------
+//
+// Each names the committed artefact it resolves from, because "you cannot edit this"
+// is only half an answer; the other half is "and here is the file that decides it".
+
+// The credit formula IN FORCE, asked of the economy module rather than restated here.
+// ADR 0146 put the reward policy inside economy precisely so display surfaces ask
+// instead of re-deriving it; a second copy of `round(cost × 1.20)` in a settings page
+// is the drift this goal exists to end. When economy is off there is no formula to
+// report, and saying so beats printing one that nothing applies.
+function creditRow() {
+  const reward = api.resolveOptional('reward');
+  if (!reward || typeof reward.rewardConfig !== 'function') {
+    return {
+      key: 'credit_calculation',
+      title: 'Credit calculation',
+      editable: false,
+      state: 'unavailable',
+      sentence: 'The economy module is not enabled on this instance, so no credit formula is in force.',
+      source: 'module `economy` (absent)',
+      reads: { file: 'modules/economy/credits.js', adr: 'ADR 0054' },
+    };
+  }
+  let policy;
+  try {
+    policy = reward.rewardConfig();
+  } catch (err) {
+    log.error(`project-settings: rewardConfig() failed: ${err && err.message}`);
+    return {
+      key: 'credit_calculation',
+      title: 'Credit calculation',
+      editable: false,
+      state: 'unavailable',
+      sentence: 'The credit formula could not be read just now.',
+      source: 'module `economy`',
+      reads: { file: 'modules/economy/credits.js', adr: 'ADR 0054' },
+    };
+  }
+  const mult = (1 + Number(policy.marginPct) / 100).toFixed(2);
+  const peg = Number(policy.usdPeg);
+  const pegNote = peg !== 1 ? ` × ${peg} peg` : '';
+  // The per-task estimate is ADVERTISED but never paid when the mode is cost-plus-only
+  // (ADR 0146). A page that showed the estimate without that sentence would be telling
+  // a builder they will earn a number this instance has decided not to pay.
+  const estimate = policy.perTaskCredit
+    ? 'A task’s own credit estimate is also paid, scaled by its kind.'
+    : 'A task’s credit estimate is an advertised guide only — this instance pays cost-plus and nothing else.';
+  return {
+    key: 'credit_calculation',
+    title: 'Credit calculation',
+    editable: false,
+    state: 'live',
+    value: { marginPct: policy.marginPct, usdPeg: policy.usdPeg, mode: policy.mode, perTaskCredit: policy.perTaskCredit },
+    sentence: `A shipped session pays round(true cost in USD × ${mult}${pegNote}). ${estimate}`,
+    source: 'branding pack → `reward`',
+    reads: { file: 'config/branding.json → reward', adr: 'ADR 0054, ADR 0146' },
+  };
+}
+
+// Equity. THE OWNER DECIDED THIS (2026-08-25) and the decision is that it is NOT REAL:
+// credits ARE the ownership stream today, and no legal equity is issued. The page says
+// that plainly rather than implying a cap table exists — an owner reading their own
+// settings page must not come away believing shares are being issued. If issuance ever
+// becomes real it gets its own decision record; the Board Room spec already parks
+// Howey / Subchapter T explicitly out of scope.
+function equityRow() {
+  return {
+    key: 'equity_calculation',
+    title: 'Equity calculation',
+    editable: false,
+    state: 'not-yet-real',
+    sentence: 'No legal equity is issued. Credits are the ownership stream this project actually runs — '
+      + 'the owner’s framing in ADR 0054 is that a credit IS a unit of ownership. There is no cap table, '
+      + 'no share class and no issuance behind this row.',
+    source: 'owner decision, 2026-08-25',
+    reads: { file: 'docs/adr/0054-drachmae-token-reward.md', adr: 'ADR 0054' },
+  };
+}
+
+// The share of upmarket revenue paid out on credits. NO SUCH KNOB EXISTS — searched
+// across code, config, migrations and docs on this task and found only prose in an
+// unrelated competitive-analysis file. So this row reports ABSENCE and names where the
+// setting would live if it became real, which is the actionable fact. A rendered "0%"
+// would be a fabricated economic claim; an omitted row would leave the owner to
+// rediscover the gap by grep.
+function upmarketRow() {
+  return {
+    key: 'upmarket_percent',
+    title: 'Percent of upmarket revenue paid on credits',
+    editable: false,
+    state: 'absent',
+    sentence: 'This project has no such setting yet — nothing in the code, config or database '
+      + 'defines it, so there is no number to show. It would belong beside the other reward '
+      + 'terms in the branding pack’s `reward` block, and paying against it would need its own '
+      + 'decision record first.',
+    source: 'not configured anywhere',
+    reads: { file: 'config/branding.json → reward (where it would live)', adr: null },
+  };
+}
+
+module.exports = function buildProjectSettingsRouter() {
+  const router = express.Router();
+
+  // GET /project-settings — all five rows in ONE read.
+  //
+  // rank: project.settings.manage (metic+, government_010), the SAME floor as the page
+  // it serves (requireGovernmentPage). The first cut gated this any-builder on the
+  // reasoning that it is "the project's own published terms" — but the payload also
+  // carries reward-policy internals (marginPct, usdPeg, mode), a raw rejected
+  // project_settings value, and internal file/migration paths, and a xenos who cannot
+  // even load the page could still curl those. Matching the read floor to the page's
+  // (task 1003280 grade, hacker lens) closes that asymmetry; the two WRITES already
+  // gate on this same atom, so the whole surface is now one floor.
+  //
+  // One read, not five: the page draws five rows, so it asks for five rows. Fetching
+  // per-row would put the hall's own settings page in the shape goal 1000072's
+  // criterion names (hall-ui/CLAUDE.md, "a card asks the server for the rows it draws").
+  router.get('/project-settings', api.requireBuilder, api.requirePermission('project.settings.manage'), async (req, res) => {
+    try {
+      const timer = await api.resolveRotDays();
+      // Inactive included: the set's SHAPE is what this page edits, and a deactivated
+      // category the owner cannot see is one they cannot bring back.
+      const categories = await goalCategory.listCategories({ includeInactive: true });
+
+      // A settings read is a configuration comparison — a cached one is wrong the
+      // moment somebody turns a knob (the rot.js precedent).
+      res.set('Cache-Control', 'no-store');
+      res.json({
+        rows: [
+          {
+            key: 'rot_timer',
+            title: 'Stale timer',
+            editable: true,
+            state: 'live',
+            value: { days: timer.days, min: api.projectSettings.MIN_ROT_DAYS, max: api.projectSettings.MAX_ROT_DAYS },
+            sentence: `Work nobody has touched for ${timer.days} day${timer.days === 1 ? '' : 's'} `
+              + 'is raised as a needs-attention item. Raising it only ever ASKS a person; nothing is '
+              + 'released or reassigned automatically.',
+            source: timer.source,
+            describe: api.projectSettings.describeRotTimer(timer),
+            // Surfaced ONLY when a configured value could not be used. It belongs on the
+            // screen of the person who can fix it — the reporting-degrades half of ADR
+            // 0226's asymmetric fail posture.
+            invalid: timer.invalid,
+            reads: { file: 'project_settings[\'attention.rot_days\'] (migration core_231)', adr: 'ADR 0226' },
+            // THE ROW THAT PREVENTS THIS PAGE FROM LYING. There are two timers, and the
+            // OTHER one — the claim sweep — enforces rather than reports, is measured in
+            // hours, and is NOT editable here. Naming it inline is what stops a reader
+            // concluding they have just reconfigured the sweep that auto-releases claims.
+            sibling: {
+              title: 'The claim sweep is a different timer',
+              sentence: 'A CLAIM that goes silent is handled separately, in hours, and the sweep '
+                + 'RELEASES it without asking. That timer is committed configuration, not a knob on '
+                + 'this page.',
+              reads: { file: 'src/stale-timer.js', adr: 'ADR 0226' },
+            },
+          },
+          {
+            key: 'work_categories',
+            title: 'Category set',
+            editable: true,
+            state: 'live',
+            value: { categories, active: categories.filter((c) => c.active).length, total: categories.length },
+            sentence: 'The human categories a goal can carry. They orient a reader and steer Claude — '
+              + 'they gate nothing, route nothing and authorise nothing.',
+            source: 'work_categories table',
+            reads: { file: 'work_categories (migration core_226)', adr: 'ADR 0192' },
+          },
+          creditRow(),
+          equityRow(),
+          upmarketRow(),
+        ],
+      });
+    } catch (err) {
+      log.error(`GET /project-settings: ${err && err.message}`);
+      res.fail('project_settings_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH /project-settings/rot-days — body { days }. The one number this page writes.
+  //
+  // rank: project.settings.manage (metic+, government_010).
+  //
+  // Validated HERE against the resolver's own parser rather than a re-typed range, so
+  // the page and the reader of the value can never disagree about what is acceptable —
+  // the second copy of "1..365" would be the drift this file exists to prevent.
+  // rank: project.settings.manage (metic+, granted by government_010).
+  //
+  // THE ATOM IS A STRING LITERAL, not a named constant, and that is load-bearing: the
+  // route-rank auditor (src/bongos/route-rank-check.js) reads this file statically and
+  // pulls the atom out of `requirePermission(...)` with a QUOTED-STRING match. A
+  // `requirePermission(SETTINGS_ATOM)` therefore resolves to an EMPTY gate — rank
+  // 'unknown' — which is a hard ADR 0016 build failure, and the generated OpenAPI would
+  // have carried no `x-permissions` either. This route was written with a constant
+  // first and fitness.js caught it; that is why every gated route in the tree spells
+  // its atom inline. (Wrapping the middleware list across lines is fine — the sibling
+  // PATCH /work-categories/:id does exactly that and still classifies metic+archon.)
+  router.patch('/project-settings/rot-days', api.requireBuilder, api.requirePermission('project.settings.manage'), async (req, res) => {
+      // STRICT schema first (ADR 0118): it declares the only field this handler reads,
+      // so an unknown key is refused through the ADR 0116 envelope instead of being
+      // silently dropped. It settles the TYPE; parseDays below settles the RANGE, using
+      // the resolver's own parser so the form and the reader cannot disagree.
+      if (api.validateOrRespond(req, res, { days: { required: true, type: 'number' } })) return;
+      const parsed = api.projectSettings.parseDays(req.body.days);
+      if (parsed.days == null) {
+        // parsed.reason already carries the bound ("out of range (1..365)"), so this
+        // does not re-type it — the drift the page's own rule forbids (task 1003280 grade).
+        return res.fail('bad_rot_days', {
+          status: 400,
+          message: `days: ${parsed.reason}`,
+        });
+      }
+      try {
+        await api.projectSettings.set(api.projectSettings.KEYS.ROT_DAYS, parsed.days, req.builder.id);
+        // Re-RESOLVE rather than echoing what was written: the receipt must describe the
+        // value the rest of the system will now read, through the same precedence every
+        // other caller goes through.
+        const timer = await api.resolveRotDays();
+        res.json({ ok: true, rot_days: timer.days, source: timer.source, describe: api.projectSettings.describeRotTimer(timer) });
+      } catch (err) {
+        log.error(`PATCH /project-settings/rot-days: ${err && err.message}`);
+        res.fail('project_settings_write_failed', { status: 500, message: 'internal error' });
+      }
+    });
+
+  return router;
+};

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.535",
+  "version": "1.19.536",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.535",
+      "version": "1.19.536",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.535",
+  "version": "1.19.536",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/bongos/serve-internal.js

@@ -829,6 +829,17 @@ function mountInternalSurfaces(app) {
   // data never leaked (the route gate held), but the page was the one item in the
   // group without a wall. Gated here so the group is uniform (task 1002710).
   const SESSIONS_PAGE_RE = /^\/builders\/sessions(?:\.html)?\/?$/;
+  // /project-settings — the five fundamentals of the project (task 1003280, goal
+  // 1000072). Government tier, beside /watch and /sessions: it is a STEERING surface,
+  // and ADR 0157 put that floor at metic. Both writes behind it gate independently on
+  // `project.settings.manage` (defence in depth unchanged), so this gate decides only
+  // who receives the shell.
+  //
+  // NB the assignment must stay `const NAME_RE = /…/;` with nothing between the `=`
+  // and the literal — tests/hall_page_gate_map.mjs rebuilds the URL→gate map by
+  // parsing this file statically, and a comment in that gap drops the regex out of
+  // the map. Prose goes above the const, as here.
+  const PROJECT_SETTINGS_PAGE_RE = /^\/builders\/project-settings(?:\.html)?\/?$/;
   // The /government ranks-and-permissions tab (BV1.R113) sits one floor higher:
   // the `government.manage` atom itself (archon), the same key its data routes
   // check — requireGovernmentManagePage, not the metic-floored gate above.
@@ -861,7 +872,7 @@ function mountInternalSurfaces(app) {
     if (!req.path.startsWith('/builders')) return next();
     const norm = path.posix.normalize(req.path);
     if (WATCH_PAGE_RE.test(norm) || HARBOR_PAGE_RE.test(norm) || GATE_PAGE_RE.test(norm)
-      || SESSIONS_PAGE_RE.test(norm)) {
+      || SESSIONS_PAGE_RE.test(norm) || PROJECT_SETTINGS_PAGE_RE.test(norm)) {
       return gdsAuth.requireGovernmentPage(req, res, next);
     }
     // R16 (goal 1000069) widened the government shell from the manage atom

package/src/module-api.js

@@ -28,6 +28,9 @@ const {
   getSetting: getProjectSetting,
   setSetting: setProjectSetting,
   describeRotTimer,
+  parseDays: parseRotDays,
+  MIN_ROT_DAYS,
+  MAX_ROT_DAYS,
 } = require('./bongos/project-settings');
 const seams = require('./module-seams');
 const { buildInfo } = require('./build-info');
@@ -46,7 +49,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.535'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.536'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');
@@ -288,6 +291,15 @@ module.exports = {
     get: getProjectSetting,
     set: setProjectSetting,
     describeRotTimer,
+    // The RANGE CHECK, shared rather than re-typed. The settings page validates a
+    // submitted timer with the very parser the resolver reads it back through, so the
+    // form and the reader can never disagree about what 1..365 means (task 1003280).
+    parseDays: parseRotDays,
+    // The bounds themselves, so a surface that must SHOW them (the settings page's rot
+    // row) reads the single source instead of re-typing 1/365 — the very drift the
+    // page's own anti-drift rule forbids, caught one layer up on task 1003280's grade.
+    MIN_ROT_DAYS,
+    MAX_ROT_DAYS,
   },
   readConfigFileSync: instanceConfig.readConfigFileSync,
   configHome: instanceConfig.configHome,

package/tests/hall_nav.mjs

@@ -170,7 +170,9 @@ test('sidebar groups read by audience, in order', () => {
   assert.deepEqual(nav[3].items.map((i) => i.id),
     ['primer', 'ranks', 'economy', 'diagrams', 'atlas', 'modules', 'apidocs'], 'Docs = reference material');
   // 'government' (the Permissions tab, BV1.R113) is the group's one archon-gated item.
-  assert.deepEqual(nav[4].items.map((i) => i.id), ['watch', 'harbor', 'gate', 'sessions', 'government']);
+  // 'project-settings' joins the Government group at the metic floor (task 1003280,
+  // goal 1000072) — it sits before 'government', which is the one archon-only item.
+  assert.deepEqual(nav[4].items.map((i) => i.id), ['watch', 'harbor', 'gate', 'sessions', 'project-settings', 'government']);
 });
 
 test('Economy lives in Docs and points at the reward-schedule page', () => {

package/tests/hall_page_gate_map.mjs

@@ -68,6 +68,10 @@ const ORACLE = {
   '/builders/harbor': 'requireGovernmentPage',
   '/builders/gate': 'requireGovernmentPage',
   '/builders/sessions': 'requireGovernmentPage',
+  // The five fundamentals of the project (task 1003280, goal 1000072). Same tier as
+  // its neighbours: a steering surface, metic+ per ADR 0157. Its two WRITES gate
+  // independently on `project.settings.manage`, so this row is only about the shell.
+  '/builders/project-settings': 'requireGovernmentPage',
 
   // Metic+ via the `project.curate` atom — the exact permission GET /scouting
   // checks, so the page can never drift wider than the API it fronts. Its