@bongos/core 1.20.22 → 1.20.24

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.20.22",
-  "core_contract": "1.20.22",
-  "source_commit": "d79f16096f873c36c2bd963c04d552fa8300497f",
+  "core_version": "1.20.24",
+  "core_contract": "1.20.24",
+  "source_commit": "64e82c9e53ba033fa0a010b81ce5a1530730df4f",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T16:20:55.212Z",
+  "built_at": "2026-09-30T18:38:12.477Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 558,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2641,
+    "functional_verbatim": 2643,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3225,
-  "tree_sha256": "63917bb4f51c192d66139655bbfebd61e0f04299a9f09e5073420a970ee9e39a",
+  "file_count": 3227,
+  "tree_sha256": "d2625091be4e2f62dd4ef689d1ae4db2c14ae9fd89b7491059734525b36b140a",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2257,7 +2257,7 @@
     {
       "path": "docs/architecture.md",
       "mode": "0000644",
-      "sha256": "682588d5c6f8dc16bfd25c23b441d333691678ac49f55500e6745fedf7c7851d"
+      "sha256": "4149011e96acb427e32a55b0e48026ad0aa5a5ac2d3fa5054da9e5ef0e4f9a3f"
     },
     {
       "path": "docs/branding-contract.md",
@@ -2782,7 +2782,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "f721721d1ba698925f1aa8133bb3b5d6ab6c048be0183212c0a89b1ca1d132a0"
+      "sha256": "76bebe410cae7c9eeda4bcc19c45a31595de4d7a45cb1f125cd742be9d0ea97b"
     },
     {
       "path": "docs/modules-contract.md",
@@ -3959,6 +3959,11 @@
       "mode": "0000644",
       "sha256": "2f578b536ed624b204fc201c0a5e8033a2417c189c9caaa8f2148408f76ae481"
     },
+    {
+      "path": "migrations/core_265_module_assessments.sql",
+      "mode": "0000644",
+      "sha256": "ea887c7bcd2863e69121bfcfa36cc62fedc77c5bd5a052e5868e2f7c99cbc103"
+    },
     {
       "path": "modules/agents/CLAUDE.md",
       "mode": "0000644",
@@ -8907,12 +8912,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "a4c779e1257097ccfca882fff19eb4475df55ddcec186db467d2efa021e2f32d"
+      "sha256": "cc2bd4f2449af9d3c504aa278de3c2cb3601b64d23fd2156b38764b726395217"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "90060e42b238486c38227cafbb5d7026e8d4283a3b96508f1617d69f524cdefe"
+      "sha256": "f57e0105f2c5994b176ded81625dbf0dc0e6f9a4b5ca26cf4e2eba6a9215af23"
     },
     {
       "path": "public-docs/index.html",
@@ -8932,7 +8937,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "f92a265951d8ff9531bca0803411c8f1a156d3a034c3125a080cf9c65c66c3c5"
+      "sha256": "0ff22595a15543713edcced44a6c4cf66150bcedfdc4b242b6e83d9c45418dfa"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -11047,7 +11052,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "8d944dcbb15babff01a10b3805ccc2fbe79ff903067af22afde12a8a1447b580"
+      "sha256": "3482788e77daee0cd538f507f349ab0ac522566ea19600c3d3163101bc7c1abb"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13984,6 +13989,11 @@
       "mode": "0000644",
       "sha256": "9183d78e4d195428afbee8c71746e12db2455f8529ac1223d690a7b8f7ded538"
     },
+    {
+      "path": "tests/module_assessments_migration.mjs",
+      "mode": "0000644",
+      "sha256": "bb71efed35265acaf82f475cbe5221c63eda8a0af452fe4154dfe05fcb7c920a"
+    },
     {
       "path": "tests/module_asset_subdomain.mjs",
       "mode": "0000644",

package/docs/architecture.md

@@ -258,6 +258,20 @@ module_entitlements(id, module_key, holder_kind IN (builder|instance), holder_re
               -- keeping the row.
 ```
 
+Module assessments (migration `core_265`, task 1003814 — [ADR 0343](adr/0343-a-module-score-is-a-security-gate-then-an-average-of-visible-parts.md) + [ADR 0347](adr/0347-every-store-module-ships-a-how-to.md) D5; per module VERSION, append-only history, the current row is the newest; never reads price):
+
+```
+module_assessment_signals(id, version_id → store_module_versions, part IN (security|tests|
+              install|reliability|tester_feedback|docs), outcome IN (scored|passed|failed|
+              no_data|pending|not_scored), score 0-100 iff scored, sample_size, reason,
+              detail jsonb, measured_at)  -- security is pass/fail only (the D2 gate);
+              -- "no data yet" is an outcome, never a zero (D3/D5)
+module_assessment_scores(id, version_id, kind IN (computed|override), overall 0-100 | NULL,
+              security_passed, is_new (D5 "New" label), formula, signal_ids bigint[],
+              override_by, override_reason, computed_at)  -- an override names who + why
+              -- and is a new row on the computed history, never an edit (D6)
+```
+
 Code: `src/bongos/module-entitlements.js` (`grantEntitlement`, `recordAcquired`, `revokeEntitlement`, `checkEntitlement`, `listEntitlements`). Read routes (own-scoped, `requireBuilder`): `GET /store/entitlements`, `GET /store/modules/:key/entitlement`. Install (task 1003785) grants a free module through `POST /store/modules/:key/acquire`; the buy action (area 8) will grant a paid one.
 
 Bongos views: `claimable_tasks` (rebuilt in 006 to use SELECT t.*; rebuilt again in 014 so the new `discipline` column flows through), `version_progress` (rebuilt in 006 to count only leaf tasks for forward-compat with task hierarchy), `tasks_session_fit` (new in 006: derives `fits_session_modes[]` and `credits_per_minute`; rebuilt in 014 for the same SELECT t.* refresh), `task_grades_with_context` (new in 016: joins task_grades × tasks × builders × cost_log so the V4 optimizer has quality-per-dollar in one read).

package/docs/module-api-changelog.md

@@ -2701,5 +2701,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.20.20 with no explicit bump. run 36735857856. (task 1002620)
   1.20.22 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.20.21 with no explicit bump. run 36743446010. (task 1002620)
+  1.20.23 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.22 with no explicit bump. run 36747567551. (task 1002620)
+  1.20.24 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.23 with no explicit bump. run 36759918201. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/migrations/core_265_module_assessments.sql

@@ -0,0 +1,97 @@
+-- core_265_module_assessments.sql — what the module assessment produces: each
+-- part's result, the composed overall score, and the history of both.
+--
+-- task 1003814 (goal 1000091, working area 5). ADR 0343 settled the score: a
+-- Security gate, then the plain average of the other parts that have data;
+-- ADR 0347 D5 adds a Docs part that is shown but never averaged in. These two
+-- tables are the storage only — the signals that fill them (tasks 1003791-3,
+-- 1003806, 1004367), the composition (1003794) and the Metic+ override route
+-- (1003796) are their own tasks and write here.
+--
+-- Everything is scoped per module VERSION (store_module_versions.id), not per
+-- module: a new version is a new thing to judge, which is what lets assessment
+-- re-run on publish.
+--
+--   module_assessment_signals  one row per measurement of one part of one
+--                          version. APPEND-ONLY: a re-run adds a row, never
+--                          UPDATEs one, so a part's score can be seen to move.
+--                          The CURRENT result of a part is the newest row per
+--                          (version, part). `outcome` keeps "no data yet"
+--                          distinct from a low score (ADR 0343 D3/D5 — a missing
+--                          part is never a zero):
+--                            scored      a 0-100 score (Tests, Install,
+--                                        Reliability, Tester feedback, Docs)
+--                            passed /    the Security gate (D2) — pass/fail,
+--                            failed      never a number, never averaged
+--                            no_data     nothing to measure yet (no installs, no
+--                                        testers, a module that declares no tests
+--                                        — task 1003791 says that is not a fail)
+--                            pending     measurement under way ("Docs: pending")
+--                            not_scored  the measurement could not run
+--                          `sample_size` is how many installs / testers / test
+--                          cases the number rests on, so two friendly testers
+--                          cannot outweigh two hundred real ones (task 1003806).
+--   module_assessment_scores  one row per composition of a version's overall
+--                          score. APPEND-ONLY history; the CURRENT score is the
+--                          newest row per version. `overall` is NULL when no
+--                          averaged part has data. `security_passed` NULL means
+--                          the gate has not run. `is_new` is ADR 0343 D5's label
+--                          (no Install or Reliability data yet). `signal_ids`
+--                          names the exact signal rows the number was composed
+--                          from, so "why did I score 71?" is answerable from the
+--                          row. `kind = 'override'` is a Metic+ correction
+--                          (ADR 0343 D6, task 1003796): it must say who and why,
+--                          and it is a new row on top of the computed history,
+--                          never an edit of it.
+--
+-- Nothing here reads price: free and paid are assessed identically (D6).
+-- Additive only (new tables), so forward-safe. Idempotent: safe to re-run.
+
+CREATE TABLE IF NOT EXISTS module_assessment_signals (
+  id              bigserial PRIMARY KEY,
+  version_id      bigint NOT NULL REFERENCES store_module_versions(id),
+  part            text NOT NULL
+                    CHECK (part IN ('security', 'tests', 'install', 'reliability',
+                                    'tester_feedback', 'docs')),
+  outcome         text NOT NULL
+                    CHECK (outcome IN ('scored', 'passed', 'failed', 'no_data',
+                                       'pending', 'not_scored')),
+  score           smallint CHECK (score BETWEEN 0 AND 100),
+  sample_size     integer CHECK (sample_size >= 0),
+  reason          text,
+  detail          jsonb NOT NULL DEFAULT '{}'::jsonb,
+  measured_at     timestamptz NOT NULL DEFAULT now(),
+  -- a number exactly when the outcome is 'scored'
+  CHECK ((outcome = 'scored') = (score IS NOT NULL)),
+  -- Security is a gate (ADR 0343 D2): pass/fail only; no other part passes or fails
+  CHECK ((part = 'security') = (outcome IN ('passed', 'failed'))
+         OR outcome IN ('no_data', 'pending', 'not_scored'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_module_assessment_signals_current
+  ON module_assessment_signals (version_id, part, measured_at DESC, id DESC);
+
+CREATE TABLE IF NOT EXISTS module_assessment_scores (
+  id               bigserial PRIMARY KEY,
+  version_id       bigint NOT NULL REFERENCES store_module_versions(id),
+  kind             text NOT NULL DEFAULT 'computed'
+                     CHECK (kind IN ('computed', 'override')),
+  overall          smallint CHECK (overall BETWEEN 0 AND 100),
+  security_passed  boolean,
+  is_new           boolean NOT NULL,
+  formula          text NOT NULL,
+  signal_ids       bigint[] NOT NULL DEFAULT '{}',
+  override_by      bigint REFERENCES builders(id),
+  override_reason  text,
+  computed_at      timestamptz NOT NULL DEFAULT now(),
+  -- an override names who made it and why; a computed row names neither
+  CHECK ((kind = 'override') = (override_by IS NOT NULL)),
+  CHECK ((kind = 'computed' AND override_reason IS NULL)
+         OR (kind = 'override' AND length(btrim(coalesce(override_reason, ''))) > 0))
+);
+
+CREATE INDEX IF NOT EXISTS idx_module_assessment_scores_current
+  ON module_assessment_scores (version_id, computed_at DESC, id DESC);
+
+INSERT INTO schema_migrations (version) VALUES ('core_265_module_assessments')
+  ON CONFLICT (version) DO NOTHING;

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.22",
+  "version": "1.20.24",
   "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/release-notes.json

@@ -8188,5 +8188,17 @@
       "id": "1002818",
       "text": "When a project invites someone, that person now sees the invitation on their Cloud Bongos projects page, and signing in to the project is what accepts it. Taking an invite back removes it there too. Inviting from the platform'"
     }
+  ],
+  "1.20.23": [
+    {
+      "id": "1003814",
+      "text": "Module scores now have a place to live: each quality check's result per module version, the overall score, and its full history, with 'no data yet' never counted as zero."
+    }
+  ],
+  "1.20.24": [
+    {
+      "id": "1004428",
+      "text": "The plan for the new project-startup experience is agreed and written down. New projects begin with a demo-or-create choice and seven planet questions, and each project picks its own colours and logo. While a project is being"
+    }
   ]
 }

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.22'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.24'; // 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('discord'); log.info('mounted');

package/tests/module_assessments_migration.mjs

@@ -0,0 +1,96 @@
+// tests/module_assessments_migration.mjs — the module assessment tables (task
+// 1003814, ADR 0343 + ADR 0347 D5). DB-free: the unit gate has no Postgres, so
+// this pins the rules the owner decided directly in the migration text, where a
+// later edit that loosened one would otherwise land silently. The live apply
+// runs in the PG lane (scripts/verify-gds-only-schema.sh) and at deploy.
+//
+// Run:  node tests/module_assessments_migration.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const FILE = 'core_265_module_assessments.sql';
+const SQL = readFileSync(path.join(ROOT, 'migrations', FILE), 'utf8');
+// Comments stripped so an assertion can only be satisfied by real DDL.
+const DDL = SQL.replace(/--.*$/gm, '');
+
+// The body of one CREATE TABLE, up to its closing ");".
+function table(name) {
+  const m = new RegExp(`CREATE TABLE IF NOT EXISTS ${name} \\(([\\s\\S]*?)\\n\\);`).exec(DDL);
+  assert.ok(m, `${name} is created`);
+  return m[1];
+}
+
+test('both tables exist, idempotently', () => {
+  table('module_assessment_signals');
+  table('module_assessment_scores');
+  assert.doesNotMatch(DDL, /CREATE TABLE (?!IF NOT EXISTS)/, 'every CREATE TABLE is IF NOT EXISTS');
+  assert.doesNotMatch(DDL, /CREATE INDEX (?!IF NOT EXISTS)/, 'every CREATE INDEX is IF NOT EXISTS');
+  assert.match(DDL, /INSERT INTO schema_migrations \(version\) VALUES \('core_265_module_assessments'\)\s+ON CONFLICT \(version\) DO NOTHING;/);
+});
+
+test('assessment is per module VERSION, not per module', () => {
+  for (const t of ['module_assessment_signals', 'module_assessment_scores']) {
+    assert.match(table(t), /version_id\s+bigint NOT NULL REFERENCES store_module_versions\(id\)/, t);
+    assert.doesNotMatch(table(t), /module_key/, `${t} is not keyed by module`);
+  }
+});
+
+test('the parts are exactly ADR 0343 D1 plus the ADR 0347 Docs part', () => {
+  assert.match(table('module_assessment_signals'),
+    /CHECK \(part IN \('security', 'tests', 'install', 'reliability',\s+'tester_feedback', 'docs'\)\)/);
+});
+
+test('"no data yet" is an outcome, never a zero (ADR 0343 D3/D5)', () => {
+  const t = table('module_assessment_signals');
+  assert.match(t, /'no_data'/);
+  assert.match(t, /'pending'/);
+  assert.match(t, /'not_scored'/);
+  assert.match(t, /score\s+smallint CHECK \(score BETWEEN 0 AND 100\)/);
+  assert.match(t, /CHECK \(\(outcome = 'scored'\) = \(score IS NOT NULL\)\)/, 'a number only when scored');
+  assert.doesNotMatch(t, /score\s+smallint[^,\n]*NOT NULL/, 'score must be nullable');
+  assert.doesNotMatch(t, /score[^,\n]*DEFAULT 0/, 'no default-to-zero');
+});
+
+test('security is a pass/fail gate, and nothing else passes or fails (ADR 0343 D2)', () => {
+  assert.match(table('module_assessment_signals'),
+    /CHECK \(\(part = 'security'\) = \(outcome IN \('passed', 'failed'\)\)\s+OR outcome IN \('no_data', 'pending', 'not_scored'\)\)/);
+});
+
+test('history is kept: no uniqueness that would force an overwrite, nothing cascades', () => {
+  assert.doesNotMatch(DDL, /UNIQUE/, 'a re-run adds a row rather than replacing one');
+  assert.doesNotMatch(DDL, /ON DELETE CASCADE/);
+  assert.match(DDL, /ON module_assessment_signals \(version_id, part, measured_at DESC, id DESC\)/);
+  assert.match(DDL, /ON module_assessment_scores \(version_id, computed_at DESC, id DESC\)/);
+});
+
+test('an override names who and why; a computed row names neither (ADR 0343 D6)', () => {
+  const t = table('module_assessment_scores');
+  assert.match(t, /CHECK \(kind IN \('computed', 'override'\)\)/);
+  assert.match(t, /CHECK \(\(kind = 'override'\) = \(override_by IS NOT NULL\)\)/);
+  assert.match(t, /kind = 'override' AND length\(btrim\(coalesce\(override_reason, ''\)\)\) > 0/);
+  assert.match(t, /kind = 'computed' AND override_reason IS NULL/);
+});
+
+test('a score records what it was composed from, and the New label (ADR 0343 D5)', () => {
+  const t = table('module_assessment_scores');
+  assert.match(t, /signal_ids\s+bigint\[\] NOT NULL/);
+  assert.match(t, /formula\s+text NOT NULL/);
+  assert.match(t, /is_new\s+boolean NOT NULL/);
+  assert.match(t, /overall\s+smallint CHECK \(overall BETWEEN 0 AND 100\)/);
+});
+
+test('price is never an input (ADR 0343 D6)', () => {
+  assert.doesNotMatch(DDL, /price|credits|cents/i);
+});
+
+test('the migration is forward-safe under the lint gate', () => {
+  const lint = require('../scripts/gds/lint-migrations.js');
+  assert.deepEqual(lint.scanMigrationSql(SQL).unsafe || [], []);
+});