@bongos/core 1.19.1063 → 1.19.1065

package/modules/lifecycle/page-tweak-hold.js

@@ -0,0 +1,74 @@
+// modules/lifecycle/page-tweak-hold.js — the ONE definition of "a page tweak
+// waiting for its artist" (task 1004322 / BV2.TW11, ADR 0341 D7).
+//
+// THE HOLD. A page tweak transcribes words an artist wrote, so its artist must
+// see the applied page before it ships (spec decision 4). When a page tweak's
+// grade PASSES, applyGrade records the grade but does not promote `completed`
+// to `confirmed`: the task waits at `completed` until the artist approves it
+// (TW12's approve route does the promotion the grade withheld) or sends it back.
+//
+// WHY ONE FILE. Five readers must agree on this one fact, and a second copy of
+// it is how they would drift: applyGrade (do not promote), the publish-branch
+// route (publish, but never arm auto-merge), the publish-status route (never
+// nudge the merge), ship.js (publish the branch and say the page is waiting)
+// and strand-watch / grade-recover (a held pass is not a failed grade). Every
+// one of them asks the questions below.
+//
+// PURE: no require, no fs, no DB. The scripts under scripts/gds/ require it
+// directly, so it must load without the module doorway.
+//
+// Every other task is untouched by construction: each predicate is false unless
+// the task's source is exactly 'page-tweak'.
+
+'use strict';
+
+// The task source the page claim writes (modules/copy-desk/pages.js SOURCE).
+// Restated, not required: copy-desk is another module, and this file requires
+// nothing so that the CLI can load it.
+const PAGE_TWEAK_SOURCE = 'page-tweak';
+
+// The derived round state this hold produces (ADR 0341 D7's table).
+const HOLD_STATE = 'waiting_for_artist';
+
+function isPageTweak(task) {
+  return !!task && task.source === PAGE_TWEAK_SOURCE;
+}
+
+// Is this task held for its artist? `gradePassed` is the task's grade row's
+// `passed` (task_grades keeps one row per task, the latest). Only a strict
+// `true` holds: a missing grade, or a failed one, is the ordinary `completed`
+// that /grade-recover handles.
+function isHeldForArtist(task, gradePassed) {
+  return isPageTweak(task) && task.status === 'completed' && gradePassed === true;
+}
+
+// What ship.js prints when it parks a held pass. One place, so the ship, the
+// re-grade and the resume all say the same thing.
+function heldLines(taskId, { prUrl = null } = {}) {
+  return [
+    '',
+    `Task #${taskId} passed its grade and is WAITING FOR THE ARTIST (ADR 0341 D7).`,
+    '  This is a page tweak: the artist approves the applied page before it ships.',
+    prUrl
+      ? `  The branch and its PR are published (${prUrl}); auto-merge is NOT armed.`
+      : '  The branch is published; auto-merge is NOT armed.',
+    '  The task stays at completed. Approve promotes it to land; send-back returns it to the /tweak queue.',
+    '  Nothing more to do here.',
+  ];
+}
+
+// The auto-merge result the publish route reports for a held pass, in the shape
+// enableAutoMergeDetailed returns, so the route's response carries its reason
+// on the field it already has (auto_merge_reason).
+const HELD_NOT_ARMED = Object.freeze({
+  ok: false,
+  reason: 'held for the artist (ADR 0341 D7): a page tweak lands only after its artist approves it',
+});
+
+module.exports = {
+  HELD_NOT_ARMED,
+  HOLD_STATE,
+  isPageTweak,
+  isHeldForArtist,
+  heldLines,
+};

package/modules/lifecycle/page-tweak-reads.js

@@ -12,6 +12,7 @@
 'use strict';
 
 const api = require('../../src/module-api');
+const hold = require('./page-tweak-hold');
 
 // Every page-tweak task, oldest first, with what the round state (D7) and the
 // changelog (D8) need beside the task itself:
@@ -93,4 +94,35 @@ async function shippedTasksTouchingSince({ files, since, limit = 50 } = {}) {
   return rows;
 }
 
-module.exports = { listPageTweakTasks, shippedTasksTouchingSince };
+// Is this task a page tweak held for its artist (ADR 0341 D7; task 1004322)?
+// The publish routes ask it before they arm or nudge a merge: a held pass is
+// published so the Approval queue can show the applied branch, but it must not
+// land until the artist approves. One row: the task's source and status, and its
+// grade (task_grades keeps one row per task). The verdict is the shared pure
+// predicate, so this read and applyGrade cannot disagree about what "held" means.
+async function readTweakHold(taskId) {
+  const { rows } = await api.pool.query(
+    `SELECT t.source, t.status, g.passed AS grade_passed
+       FROM tasks t
+       LEFT JOIN task_grades g ON g.task_id = t.id
+      WHERE t.id = $1`,
+    [taskId]
+  );
+  const row = rows[0] || null;
+  return { held: !!row && hold.isHeldForArtist(row, row.grade_passed), page_tweak: hold.isPageTweak(row) };
+}
+
+// The publish routes' form of the question, FAIL-CLOSED: a read that throws
+// answers "held", so the route neither arms auto-merge nor nudges the merge.
+// That is the safe direction for every task: an ordinary confirmed task whose
+// PR was left un-armed still lands, because the publish reconciler's sweep
+// merges green PRs of confirmed tasks on its own (task 1162).
+async function heldForArtistFailClosed(taskId, read = readTweakHold) {
+  try {
+    return (await read(taskId)).held;
+  } catch (_) {
+    return true;
+  }
+}
+
+module.exports = { listPageTweakTasks, shippedTasksTouchingSince, heldForArtistFailClosed };

package/modules/lifecycle/routes/gate-approvals.js

@@ -24,6 +24,11 @@ const express = require('express');
 const api = require('../../../src/module-api');
 const auth = api;
 const githubPush = require('../github-push');
+// The page-tweak hold (task 1004323 / BV2.TW12, ADR 0341 D7): the approve below
+// re-arms auto-merge on the reopened PR, and a page tweak held for its artist must
+// never be armed from here. Called through the module object so tests can stub it.
+const pageTweakReads = require('../page-tweak-reads');
+const { HELD_NOT_ARMED } = require('../page-tweak-hold');
 const { parseId } = api;
 // The SAME pure classifier the CI gate runs — reused (never duplicated) so the hall
 // shows identical verdict + reasons. Safe to require: gate-review.js guards its CLI
@@ -168,9 +173,16 @@ module.exports = function buildGateApprovalsRouter() {
 
       // 2. Re-trigger gate-review (close+reopen → `pull_request: reopened`) so the
       //    required check re-evaluates the new approval; re-arm auto-merge.
+      //    A PAGE TWEAK HELD FOR ITS ARTIST is reopened but NOT re-armed (task
+      //    1004323): clearing the gate check is the owner's act on the PR, and
+      //    approving the page is the artist's (ADR 0341 D7). Asked fail-closed: a
+      //    read that throws answers held, and an ordinary confirmed task left
+      //    un-armed still lands through the publish reconciler's sweep.
+      const prTask = taskIdFromPr(pr);
+      const held = prTask != null && await pageTweakReads.heldForArtistFailClosed(prTask);
       let recheck = { reopened: false, auto_merge: false };
       try {
-        recheck = await githubPush.recheckPullRequest({ number });
+        recheck = await githubPush.recheckPullRequest(held ? { number, arm: false, heldReason: HELD_NOT_ARMED.reason } : { number });
       } catch (e) {
         // The status IS set; if the re-trigger failed, the next push or a manual
         // re-run still clears it, and the publish reconciler sweep merges once green.
@@ -187,7 +199,10 @@ module.exports = function buildGateApprovalsRouter() {
         head_sha: pr.head_sha,
         status_set: true,
         recheck,
-        message: 'Approval recorded. Re-running the gate check — the PR merges once it goes green.',
+        held_for_artist: held,
+        message: held
+          ? 'Approval recorded. Re-running the gate check. This is a page tweak waiting for its artist, so it lands only once the artist approves it in the studio.'
+          : 'Approval recorded. Re-running the gate check — the PR merges once it goes green.',
       });
     } catch (err) {
       console.error('[gds] POST /gate-approvals/:pr/approve', err);

package/modules/lifecycle/routes/tasks.js

@@ -35,6 +35,7 @@ const { depRefusalRow } = require('../dead-deps.js');
 const { gradeQualityWhere } = require('../db-shared');
 const auth = api;
 const db = require('../db');
+const pageTweakReads = require('../page-tweak-reads'); const { HELD_NOT_ARMED } = require('../page-tweak-hold'); // ADR 0341 D7 (tests stub the read)
 const hierarchy = require('../hierarchy');
 const { suggestCriteria } = require('../criterion-suggest');
 // The orphan-task advisory (task 1002539) — pure, fail-open; see goal-advisory.js.
@@ -1184,7 +1185,8 @@ module.exports = function buildTasksRouter() {
       // task 1001431: ask WHY when arming fails. `auto_merge: false` on its own told the
       // builder nothing, and the commonest cause is a repo with allow_auto_merge OFF —
       // a permanent condition that reads exactly like a transient blip.
-      const autoMergeResult = await githubPush.enableAutoMergeDetailed({ nodeId: pr.node_id });
+      // task 1004322 (ADR 0341 D7): a page tweak held for its artist is PUBLISHED, never armed.
+      const autoMergeResult = (await pageTweakReads.heldForArtistFailClosed(id)) ? HELD_NOT_ARMED : await githubPush.enableAutoMergeDetailed({ nodeId: pr.node_id });
       const autoMerge = autoMergeResult.ok;
       // task 1139 (ADR 0058): attest the author's trust tier on the pushed sha so the
       // gate-review check can auto-approve a Metic+ author's gate-surface PR with no
@@ -1326,7 +1328,7 @@ module.exports = function buildTasksRouter() {
       // mirrors the reconcile-on-read precedent above (a GET that finishes the
       // land); best-effort so a merge-driver miss never turns the poll into a 502.
       let merge_driver = null;
-      if (!reconciled && !status.merged && status.pr_state === 'open') {
+      if (!reconciled && !status.merged && status.pr_state === 'open' && !(await pageTweakReads.heldForArtistFailClosed(id))) { // a held page tweak is never nudged (ADR 0341 D7)
         try {
           merge_driver = await githubPush.mergeIfGreen({ branch });
         } catch (e) {

package/modules/lifecycle/routes/visuals.js

@@ -14,6 +14,12 @@
 //   DELETE /tasks/:id/visual    take it back off       (claim holder | Archon)
 //   GET    /task-visuals/:name  serve one              (see the audience note)
 //
+// NAMED SLOTS (task 1004322 / BV2.TW11, lifecycle_013) — the same store, the same
+// gate, the same audience, one picture per name:
+//   POST   /tasks/:id/visuals/:slot   attach or replace a named one (claim holder | Archon)
+//   DELETE /tasks/:id/visuals/:slot   take it back off              (claim holder | Archon)
+//   GET    /tasks/:id/visuals         list them by name              (any builder)
+//
 // The twin of routes/bug-attachments.js, for the image a builder attaches to
 // their own shipped task instead of one the bot pulled out of #bugs. Storage +
 // screening live in ../task-visuals.js; all three routes live here rather than
@@ -191,6 +197,82 @@ module.exports = function buildTaskVisualsRouter() {
     }
   });
 
+  // ==========================================================================
+  // NAMED SLOTS (task 1004322 / BV2.TW11; ADR 0341 D7, builder pick 9)
+  // --------------------------------------------------------------------------
+  // A page tweak carries eight renders of the applied page (before and after,
+  // desktop and phone, light and dark), and the Approval queue shows them by
+  // name. Each slot is stored and screened exactly as the one visual is, and
+  // served by the same GET /task-visuals/:name, whose audience comes from the
+  // task. The slot name is validated before any byte is read.
+
+  // POST /tasks/:id/visuals/:slot — attach (or replace) one named visual.
+  router.post('/tasks/:id/visuals/:slot', auth.requireBuilder, visualUpload, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    const slot = req.params.slot;
+    if (!visuals.isSafeSlot(slot)) return res.fail('bad_slot', 400, { max_length: visuals.MAX_SLOT_LENGTH, example: visuals.TWEAK_RENDER_SLOTS[0] });
+    if (validateOrRespond(req, res, {
+      image_b64: { required: true, type: 'string', maxLength: VISUAL_B64_MAX, minLength: 1 },
+      content_type: { required: true, type: 'string', maxLength: 100, minLength: 1 },
+      alt: { type: 'string', maxLength: visuals.MAX_ALT_LENGTH },
+    })) return;
+    if (!(await gateTaskOwnership(req, res, id))) return;
+    const buf = Buffer.from(req.body.image_b64, 'base64');
+    const screened = visuals.screenImage(buf, req.body.content_type);
+    if (!screened.ok) {
+      return res.fail(`visual_${screened.reason}`, screened.reason === 'too_big' ? 413 : 400, {
+        max_bytes: visuals.MAX_BYTES,
+        accepted: Object.keys(visuals.EXT_BY_TYPE),
+      });
+    }
+    const task = await db.getTaskVisualAccess(id);
+    if (!task) return res.fail('task_not_found', 404);
+    try {
+      const stored = await visuals.persistImageBuffer(buf, { taskId: id, contentType: req.body.content_type });
+      if (!stored.ok) return res.fail(`visual_${stored.reason}`, 400);
+      const row = await db.setTaskVisualSlot({ taskId: id, slot, visualUrl: stored.url, visualAlt: visuals.normalizeAlt(req.body.alt) });
+      if (row && row.replaced_url && row.replaced_url !== stored.url) await visuals.deleteStored(row.replaced_url);
+      return res.status(201).json({ ok: true, slot, visual_url: row.visual_url, visual_alt: row.visual_alt, bytes: stored.bytes });
+    } catch (err) {
+      log.error({ taskId: id, slot, err: err && err.message }, 'task-visual slot upload failed');
+      return res.fail('visual_store_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // DELETE /tasks/:id/visuals/:slot — remove one named visual. Idempotent.
+  router.delete('/tasks/:id/visuals/:slot', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    const slot = req.params.slot;
+    if (!visuals.isSafeSlot(slot)) return res.fail('bad_slot', 400);
+    if (!(await gateTaskOwnership(req, res, id))) return;
+    try {
+      const url = await db.deleteTaskVisualSlot({ taskId: id, slot });
+      if (url) await visuals.deleteStored(url);
+      return res.json({ ok: true, slot, visual_url: null });
+    } catch (err) {
+      log.error({ taskId: id, slot, err: err && err.message }, 'task-visual slot delete failed');
+      return res.fail('visual_delete_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /tasks/:id/visuals — the task's named visuals. Any signed-in builder: it
+  // lists URLs only, and each image is still served under its own task's audience.
+  router.get('/tasks/:id/visuals', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    try {
+      const task = await db.getTaskVisualAccess(id);
+      if (!task) return res.fail('task_not_found', 404);
+      const rows = await db.listTaskVisualSlots(id);
+      return res.json({ ok: true, task_id: String(id), slots: rows.map((x) => ({ slot: x.slot, visual_url: x.visual_url, visual_alt: x.visual_alt, updated_at: x.updated_at })) });
+    } catch (err) {
+      log.error({ taskId: id, err: err && err.message }, 'task-visual slot list failed');
+      return res.fail('visual_list_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // DELETE /tasks/:id/visual — remove it again. The counterpart to "always
   // optional": a builder who attached the wrong screenshot must be able to take
   // it back, and an image is not prose (the write-once rule of task 1003102

package/modules/lifecycle/task-visual-db.js

@@ -43,4 +43,43 @@ async function getTaskVisualAccess(taskId) {
   return rows[0] ?? null;
 }
 
-module.exports = { setTaskVisual, getTaskVisualAccess };
+// NAMED SLOTS (task 1004322, lifecycle_013). Status-blind, like the two above:
+// the routes decide who may write and who may see.
+//
+// Upsert one slot. Returns the stored row and the URL it REPLACED (null when the
+// slot was empty), read in the same statement so the route can unlink exactly the
+// superseded file.
+async function setTaskVisualSlot({ taskId, slot, visualUrl, visualAlt = null }) {
+  const { rows } = await pool.query(
+    `WITH prev AS (
+       SELECT visual_url FROM lifecycle_task_visual_slots WHERE task_id = $1 AND slot = $2
+     )
+     INSERT INTO lifecycle_task_visual_slots (task_id, slot, visual_url, visual_alt, updated_at)
+     VALUES ($1, $2, $3, $4, now())
+     ON CONFLICT (task_id, slot) DO UPDATE
+       SET visual_url = EXCLUDED.visual_url, visual_alt = EXCLUDED.visual_alt, updated_at = now()
+     RETURNING slot, visual_url, visual_alt, (SELECT visual_url FROM prev) AS replaced_url`,
+    [taskId, slot, visualUrl, visualAlt]
+  );
+  return rows[0] ?? null;
+}
+
+// Remove one slot. Returns the URL it held, or null when it was already empty.
+async function deleteTaskVisualSlot({ taskId, slot }) {
+  const { rows } = await pool.query(
+    `DELETE FROM lifecycle_task_visual_slots WHERE task_id = $1 AND slot = $2 RETURNING visual_url`,
+    [taskId, slot]
+  );
+  return rows[0] ? rows[0].visual_url : null;
+}
+
+// Every slot a task carries, by name.
+async function listTaskVisualSlots(taskId) {
+  const { rows } = await pool.query(
+    `SELECT slot, visual_url, visual_alt, updated_at FROM lifecycle_task_visual_slots WHERE task_id = $1 ORDER BY slot`,
+    [taskId]
+  );
+  return rows;
+}
+
+module.exports = { setTaskVisual, getTaskVisualAccess, setTaskVisualSlot, deleteTaskVisualSlot, listTaskVisualSlots };

package/modules/lifecycle/task-visuals.js

@@ -55,6 +55,24 @@ const TYPE_BY_EXT = {
 };
 
 const MAX_BYTES = 4 * 1024 * 1024; // 4 MB — a screenshot, not an asset library.
+
+// NAMED SLOTS (task 1004322 / BV2.TW11, lifecycle_013). A task may carry named
+// visuals beside its one ship-time picture. The shape is the column's own CHECK,
+// restated so a bad name is refused before any byte is stored.
+const SLOT_RE = /^[a-z0-9]+(-[a-z0-9]+){0,5}$/;
+const MAX_SLOT_LENGTH = 48;
+function isSafeSlot(slot) {
+  return typeof slot === 'string' && slot.length <= MAX_SLOT_LENGTH && SLOT_RE.test(slot);
+}
+// The eight renders /tweak attaches to a page tweak (ADR 0341 D7, builder pick 9):
+// the applied page before and after, desktop (1440) and phone (390), light and
+// dark. Declared ONCE: the renderer names its files with it, the attach step
+// uploads by it, and the Approval queue (TW12) reads the same names.
+const TWEAK_RENDER_PHASES = Object.freeze(['before', 'after']);
+const TWEAK_RENDER_DEVICES = Object.freeze({ desktop: 1440, phone: 390 });
+const TWEAK_RENDER_MODES = Object.freeze(['light', 'dark']);
+const TWEAK_RENDER_SLOTS = Object.freeze(TWEAK_RENDER_PHASES.flatMap((phase) =>
+  Object.keys(TWEAK_RENDER_DEVICES).flatMap((device) => TWEAK_RENDER_MODES.map((mode) => `${phase}-${device}-${mode}`))));
 const MAX_ALT_LENGTH = 300;        // the caption/alt text stored beside it.
 
 // Stored filenames are SERVER-generated, never user-supplied: a fixed shape we
@@ -249,6 +267,12 @@ async function deleteStored(nameOrUrl, { dir = visualsDir() } = {}) {
 }
 
 module.exports = {
+  isSafeSlot,
+  MAX_SLOT_LENGTH,
+  TWEAK_RENDER_PHASES,
+  TWEAK_RENDER_DEVICES,
+  TWEAK_RENDER_MODES,
+  TWEAK_RENDER_SLOTS,
   EXT_BY_TYPE,
   TYPE_BY_EXT,
   MAX_BYTES,

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1063",
+  "version": "1.19.1065",
   "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

@@ -7679,5 +7679,17 @@
       "id": "1004321",
       "text": "Artists now have their own editor for a page. It shows every word of the page as one sheet of paper over the studio at night. You type over any line and it saves as you go. A changed line gets a small orange mark and shows wha"
     }
+  ],
+  "1.19.1064": [
+    {
+      "id": "1004322",
+      "text": "A session can now apply an artist's rewritten page. The new /tweak skill takes the next submitted page, applies every line in one pass, and photographs the page before and after, on a desktop and a phone, in light and dark, at"
+    }
+  ],
+  "1.19.1065": [
+    {
+      "id": "1004323",
+      "text": "An artist can now approve a tweaked page from the studio. A new Approval queue button opens a glass panel that shows the applied page as real pictures, before and after, on desktop and phone, in light and dark, with the change"
+    }
   ]
 }