@bongos/core 1.19.888 → 1.19.890

package/modules/grading/grader-workers/reader.js

@@ -0,0 +1,218 @@
+// The Reader — the advisory copy lens (task 1003977, ADR 0298).
+//
+// Specialty: the SENTENCES. Is a line a person reads true, clear, in the
+// project's voice, and worth their attention? The other four workers read
+// completion (Narc), code quality (Quality), security (Hacker) and runtime cost
+// (Efficiency); not one of them reads a sentence. Task 1003937 established that
+// across four consecutive artist reviews, all of which found the same wall and
+// all of whose graded ships deservedly passed on the axes that WERE measured.
+//
+// ADVISORY, FULL STOP — and that is structural here, not a filter elsewhere.
+// This worker's computeVerdict cannot return 'fail' or 'concerns'; it returns
+// the single verdict 'advisory' on every path, including its own errors. The
+// panel then excludes it from the gate (NON_GATING_WORKERS in index.js, and the
+// partition in grader.js aggregatePanel). Two independent mechanisms, because
+// the owner's term (2026-09-17) is absolute: ADR 0241 put the artist's judgement
+// on the DEPLOY and off the ship path, after ADR 0162 retired review gates for
+// stranding graded-PASS work. A reader that could fail a ship puts that back.
+//
+// NOTE THIS IS STRONGER THAN ADVISORY_WORKERS. The Narc is "advisory" in the
+// sense that a Narc-only fail DOWNGRADES to concerns (manual-confirm). The
+// Reader cannot reach concerns either. There is deliberately NO blocker escape
+// hatch of the kind narc/hacker carry ("advisory ONLY if it carries no
+// blocker"): a copy lens finding something that genuinely blocks a ship is a
+// finding in another lens's territory, and the escape hatch would be the exact
+// hole the owner's term closes.
+//
+// THE STANDARD IS WRITTEN DOWN. docs/voice.md (task 1003976) is the rubric, and
+// its own rule is that a finding citing no rule id is not a finding. The guide
+// splits HARD rules (V1-V5, checkable — a lens may assert a break) from
+// JUDGEMENT rules (V6-V11, recognisable but not provable — a lens may only FLAG
+// a candidate and must quote the line). That split is reproduced in the prompt
+// below, because it is what keeps an advisory lens from recording taste as fact.
+
+const { buildWorkerPrompt, LLM_PROJECT } = require('./worker-prompt');
+const { parseCommon } = require('./worker-verdict');
+const { extractJson } = require('./extract-json');
+
+const KIND = 'reader';
+const NAME = 'Reader';
+const SPECIALTY = 'user-facing copy: truth, clarity, voice (docs/voice.md), against the written guide';
+
+// The ONE verdict this worker emits. Not 'pass': a pass is a claim the gate may
+// read, and an errored Reader claiming 'pass' would be a false one. Registered
+// in grader-score.js WORKER_VERDICTS so hasPanelEvidence still recognises a
+// panel that carries a Reader row.
+const ADVISORY_VERDICT = 'advisory';
+
+const PROMPT_HEADER = `You are the **Reader** — the copy lens for the ${LLM_PROJECT} project. You read the SENTENCES a person will see.
+
+You are ADVISORY. Nothing you report can block this ship, and you should not write as though it could. Your output is coaching for the artist who reviews this work afterwards, and a record of where the grade was otherwise blind.
+
+Your ONLY job is user-facing copy. You do NOT score whether the description was implemented (Narc), whether the code is well-written (Quality), whether it is secure (Hacker), or what it costs to run (Efficiency). If you notice something in those territories, say so in \`notes_md\` and move on — do not file it as an issue.
+
+## The standard is written down, and you must cite it
+
+\`docs/voice.md\` is the voice guide. **Read it first** — it is the rubric for this grade, and its rules carry ids (V1, V2, …).
+
+**A finding that cites no rule id is not a finding.** If a line is bad and no rule in the guide reaches it, say that in \`notes_md\` as a gap in the guide. Do not invent a rule at grade time. This is the guide's own instruction and it is what separates a lens from a second model's taste.
+
+The guide splits its rules in two, and the split governs what you may say:
+
+- **Hard rules (V1-V5)** can be checked. A line either breaks one or it does not. You MAY assert a break.
+- **Judgement rules (V6-V11)** name a failure a person can recognise but a checker cannot prove. You may **flag a candidate** and must quote the line and the rule id. You may NEVER assert that the line is wrong. The artist decides.
+
+Set \`kind\` on every issue to \`"break"\` (hard rule, asserted) or \`"flag"\` (judgement rule, offered). A judgement-rule issue filed as a break is the single most damaging thing you can do here, because it records taste as fact.
+
+## What counts as user-facing copy
+
+What the guide governs: every string a person reads on the builders' hall, the status dashboard and the landing surface; server-side route failures and validation text; outbound broadcast text.
+
+What it does NOT govern, and you must not score: repository documentation, ADRs, session logs, code comments, commit messages, skill prose. Those are written for builders and agents in ordinary technical prose. A diff that changes ONLY those carries no copy for you to read — say so and score 10.
+
+## How you work
+
+1. Read \`docs/voice.md\`.
+2. Walk the diff for CHANGED or ADDED user-facing strings. Quote each line you judge.
+3. For each, name the rule id it breaks or that it is a candidate against.
+4. Score \`copy_score\` (0-10):
+   - 10 = no user-facing copy changed, or every changed line is clean against the guide.
+   - 8 = clean; one or two judgement-rule flags worth the artist's eye.
+   - 6 = at least one hard-rule break in a line a person will read.
+   - 4 = several hard-rule breaks, or one in a high-traffic surface.
+   - 2 = the copy actively misleads (a word that means something else here, a claim the code does not support).
+   - 0 = the copy is wrong in a way that would embarrass the project in front of a user.
+
+   The score is a RECORD, not a gate. Nothing happens to the ship at any value.
+
+5. Severities: \`major\` for a hard-rule break on a line a person reads; \`minor\` for a hard-rule break somewhere quiet; \`nit\` for a judgement-rule flag. Never \`blocker\` — you cannot block, and a blocker severity from this lens is a category error.
+
+## Read budget
+
+**5 Read calls.** Spend the first on \`docs/voice.md\`. Spend the rest confirming that a string you are judging really is user-facing — the surrounding render path tells you, and a string in a code comment is not copy.
+
+## Sanity checks
+
+- A diff with no user-facing string changes scores 10 with no issues. That is a normal, common outcome. Do not manufacture findings to look useful.
+- Every issue quotes the line and names a rule id.
+- No issue carries severity \`blocker\`.
+- Do not rewrite the copy for them unless the fix is obvious and one line; the artist owns the remake.
+
+## Return ONLY JSON
+
+No prose, no markdown fences:
+
+\`\`\`
+{
+  "copy_score": <number 0-10>,
+  "confidence": <number 0-1>,
+  "reads_used": <integer 0-5>,
+  "strings_reviewed": [
+    { "where": "<file:line>", "line": "<the string, quoted>", "verdict": "ok"|"break"|"flag", "rule": "<V-id or null>" }
+  ],
+  "issues": [
+    { "severity": "major"|"minor"|"nit", "kind": "break"|"flag", "rule": "<V-id>", "file": "<path>", "summary": "<one line, quotes the copy and names the rule>" }
+  ],
+  "notes_md": "<short markdown — which surfaces carried copy, what you could not judge, and any gap in the guide you hit>"
+}
+\`\`\`
+
+You have a Read tool with a hard budget of 5 calls. Do not run tests, do not edit files, do not call the network.`;
+
+function buildPrompt({ task, valueSummary, diff, changedFiles, diffStats, priorRound, contextBundle }) {
+  return buildWorkerPrompt({
+    priorRound,
+    contextBundle,
+    header: PROMPT_HEADER,
+    task: task || {},
+    valueSummary,
+    diff,
+    changedFiles,
+    taskHeader: '## Task (context — you judge the copy, not the completion)',
+    descLabel: '**Description:**',
+    emptyFilesText: '(no files changed)',
+    readFilesHint: 'You can Read any of these files to see their post-merge state (5-call budget — spend the first on docs/voice.md).',
+    finalInstruction: 'Now read the copy. Cite a rule id on every finding, or do not file it. Output ONLY the JSON object.',
+  });
+}
+
+// The Reader's verdict is 'advisory' on EVERY path — a clean read, a bad read,
+// a crashed subagent, a timeout. There is no branch that returns anything else,
+// which is what makes "it cannot block" a property of this function rather than
+// a promise kept by its callers.
+//
+// An error still travels: `error` is set, the notes say so, and copy_score is
+// null rather than 0. A 0 would be a real score meaning "the copy is wrong in a
+// way that would embarrass the project", and an outage is not that. The same
+// distinction #943 draws for the panel — missing signal is not a bad signal.
+function computeVerdict(parsed, meta = {}) {
+  const advisory = (extra) => ({
+    verdict: ADVISORY_VERDICT,
+    scores: {},
+    issues: [],
+    confidence: null,
+    error: null,
+    ...extra,
+  });
+
+  if (meta.subprocess_error) {
+    return advisory({
+      notes_md: `Reader — ADVISORY, no signal: subagent error (${meta.subprocess_error}). The copy was not read; this does not affect the ship.`,
+      error: meta.subprocess_error,
+    });
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    return advisory({
+      notes_md: 'Reader — ADVISORY, no signal: could not parse subagent output as JSON. The copy was not read; this does not affect the ship.',
+      error: 'parse_error',
+    });
+  }
+
+  const { conf, issues: rawIssues, notesFromSubagent } = parseCommon(parsed);
+  const score = Number(parsed.copy_score);
+  const reviewed = Array.isArray(parsed.strings_reviewed) ? parsed.strings_reviewed : [];
+
+  // A blocker from this lens is a category error, not a blocking finding. It is
+  // FLOORED to major rather than dropped: the observation may be real and the
+  // artist should see it; what it may not be is a severity the gate reads as
+  // blocking. Dropping it would hide a finding; honouring it would hand this
+  // worker the veto the owner's term denies it.
+  const issues = rawIssues.map((i) => (
+    i && i.severity === 'blocker'
+      ? { ...i, severity: 'major', severity_floored_from: 'blocker' }
+      : i
+  ));
+
+  if (!Number.isFinite(score) || score < 0 || score > 10) {
+    return advisory({
+      issues,
+      notes_md: `Reader — ADVISORY, no score: copy_score was non-numeric or out of range (got ${parsed.copy_score}). Findings below still stand.`,
+      error: 'schema_error',
+      confidence: conf,
+    });
+  }
+
+  const s = Math.round(score * 10) / 10;
+  const breaks = issues.filter((i) => i.kind === 'break').length;
+  const flags = issues.filter((i) => i.kind === 'flag').length;
+  const prefix = `Reader — ADVISORY (copy=${s}/10, ${breaks} rule break${breaks === 1 ? '' : 's'}, ${flags} flag${flags === 1 ? '' : 's'}, ${reviewed.length} string${reviewed.length === 1 ? '' : 's'} reviewed, conf=${conf ?? '?'})`;
+
+  return advisory({
+    scores: { copy_score: s },
+    issues,
+    strings_reviewed: reviewed,
+    notes_md: `${prefix}\n${notesFromSubagent.trim()}`.trim(),
+    confidence: conf,
+  });
+}
+
+module.exports = {
+  KIND,
+  NAME,
+  SPECIALTY,
+  ADVISORY_VERDICT,
+  PROMPT_HEADER,
+  buildPrompt,
+  extractJson,
+  computeVerdict,
+};

package/modules/grading/grader.js

@@ -110,7 +110,27 @@ function describeOutage(gating) {
 }
 
 function aggregatePanel(workerResults, meta = {}) {
-  const N = workerResults.length;
+  // task 1003977 — THE NON-GATING PARTITION, before any gate arithmetic.
+  //
+  // A non-gating worker (today: the Reader, the advisory copy lens) contributes
+  // its scores and issues to the RECORD and nothing at all to the GATE. It is
+  // removed here, once, rather than special-cased in each of the counts below —
+  // pass/concerns/fail counts, the error and outage detection, the confidence
+  // median and every branch of the verdict all read `gateResults`.
+  //
+  // Removing it from the counts is why a Reader outage cannot reach #943's
+  // "every gating worker is missing signal" branch, and why a Reader cannot
+  // nudge the confidence median that drives the server-side gate. `N` stays the
+  // GATE's denominator so the verdict strings keep meaning what they said
+  // before ("2/4 gating worker(s) failed" counts the four that can fail).
+  //
+  // ADVISORY_WORKERS below is a DIFFERENT, weaker thing: narc is advisory in
+  // that a narc-only fail downgrades to manual-confirm. A non-gating worker
+  // never reaches even that.
+  const isNonGating = (w) => w && workers.isNonGatingKind(w.kind);
+  const nonGatingResults = workerResults.filter(isNonGating);
+  const gateResults = workerResults.filter((w) => !isNonGating(w));
+  const N = gateResults.length;
 
   // Score axes — median across workers that reported each. Reuses the
   // module-level median() helper (rounded to one decimal).
@@ -124,6 +144,12 @@ function aggregatePanel(workerResults, meta = {}) {
   // Phase 2.2 (#421): Efficiency Monger reports efficiency_score. Same
   // additive treatment as security_score.
   const efficiencyScore = median(workerResults.map((w) => w.scores?.efficiency_score));
+  // task 1003977: the Reader reports copy_score. Recorded like security_score
+  // and efficiency_score before it — additive, and read from the FULL result
+  // list rather than gateResults, because the whole point is that a non-gating
+  // worker's SIGNAL lands in the record even though its verdict never reaches
+  // the gate. Null whenever no Reader ran, which is every non-copy-bearing ship.
+  const copyScore = median(workerResults.map((w) => w.scores?.copy_score));
 
   const economyPenalty =
     economy != null ? Math.max(0, (THRESHOLD - economy) / 2) : 0;
@@ -131,8 +157,8 @@ function aggregatePanel(workerResults, meta = {}) {
   const blended = ff != null && cq != null ? r1((ff + cq) / 2) : 0;
 
   // Verdict counts.
-  const passCount = workerResults.filter((w) => w.verdict === 'pass').length;
-  const concernsCount = workerResults.filter((w) => w.verdict === 'concerns').length;
+  const passCount = gateResults.filter((w) => w.verdict === 'pass').length;
+  const concernsCount = gateResults.filter((w) => w.verdict === 'concerns').length;
   // A crashed worker sets verdict='fail' as a DEFAULT in its computeVerdict()
   // subprocess_error / parse_error / schema_error early returns (see each
   // worker module) — that is MISSING SIGNAL, not a substantive finding, and
@@ -149,12 +175,12 @@ function aggregatePanel(workerResults, meta = {}) {
   const hasSubstantiveIssue = (w) =>
     (w.issues || []).some((i) => i.severity === 'blocker' || i.severity === 'major');
   const isMissingSignal = (w) => !!w.error && !hasSubstantiveIssue(w);
-  const failCount = workerResults.filter((w) => w.verdict === 'fail' && !isMissingSignal(w)).length;
+  const failCount = gateResults.filter((w) => w.verdict === 'fail' && !isMissingSignal(w)).length;
   // NOTE (#473/#589): signals.error_count counts only isMissingSignal workers — i.e. a worker that
   // errored AND surfaced no blocking issue. A worker that errored but still raised a blocker/major
   // is a real finding, so it counts in fail_count (above), NOT here. This is a deliberate semantic
   // change from the old "all w.error" meaning; keep error_count = missing-signal-only.
-  const errorCount = workerResults.filter((w) => isMissingSignal(w)).length;
+  const errorCount = gateResults.filter((w) => isMissingSignal(w)).length;
 
   // V3.R85 (#481): the Narc (functional_fidelity) is ADVISORY in the gate —
   // Lars's call 2026-05-30 after #303, where over-literal acceptance-criteria
@@ -188,8 +214,8 @@ function aggregatePanel(workerResults, meta = {}) {
   // taken out by a grader outage, so it is not evidence either way about whether the
   // panel ran. Task 1003574.
   const isDeterministic = (w) => w && w.model === 'deterministic';
-  const nonAdvisory = workerResults.filter((w) => !isAdvisory(w));
-  const gating = nonAdvisory.length ? nonAdvisory : workerResults;
+  const nonAdvisory = gateResults.filter((w) => !isAdvisory(w));
+  const gating = nonAdvisory.length ? nonAdvisory : gateResults;
   const gatingFail = gating.filter((w) => w.verdict === 'fail' && !isMissingSignal(w)).length;
   const gatingError = gating.filter((w) => isMissingSignal(w)).length;
   const gatingConcerns = gating.filter((w) => w.verdict === 'concerns').length;
@@ -228,15 +254,15 @@ function aggregatePanel(workerResults, meta = {}) {
   const gatingErrorAll = subagentGating.length > 0 && subagentGating.every((w) => isMissingSignal(w));
   // Advisory-worker outcomes — never a hard block. Uses isAdvisory so a Narc
   // that DID raise a blocker is treated as gating (in `nonAdvisory`), not here.
-  const advisoryFail = workerResults.some((w) => isAdvisory(w) && w.verdict === 'fail' && !isMissingSignal(w));
-  const advisoryConcerns = workerResults.some((w) => isAdvisory(w) && w.verdict === 'concerns');
+  const advisoryFail = gateResults.some((w) => isAdvisory(w) && w.verdict === 'fail' && !isMissingSignal(w));
+  const advisoryConcerns = gateResults.some((w) => isAdvisory(w) && w.verdict === 'concerns');
 
   // Confidence — median for pass, fallthrough for concerns, 0 for fail.
   // (Drives the server-side gate; see file header.) Computed UNROUNDED —
   // confidence sits near the 0.4 gate cap so the module-level median()
   // helper (which rounds via r1()) would risk nudging a borderline value
   // across the boundary. Inlined for that one-decimal-precision reason.
-  const confVals = workerResults
+  const confVals = gateResults
     .map((w) => w.confidence)
     .filter((n) => Number.isFinite(n))
     .slice()
@@ -360,7 +386,12 @@ function aggregatePanel(workerResults, meta = {}) {
 
   // Build display notes.
   const lines = [];
-  lines.push(`Subagent grader ${VERSION} (panel of ${N}: ${workerResults.map((w) => w.kind).join(', ')}) — ${verdict}`);
+  // N counts the GATING workers; a non-gating one is named separately so the
+  // line cannot read as an off-by-one ("panel of 4: …five kinds…").
+  const advisoryKinds = nonGatingResults.map((w) => w.kind);
+  lines.push(`Subagent grader ${VERSION} (panel of ${N}: ${gateResults.map((w) => w.kind).join(', ')}`
+    + (advisoryKinds.length ? ` · advisory, non-gating: ${advisoryKinds.join(', ')}` : '')
+    + `) — ${verdict}`);
   if (ff != null) lines.push(`  functional_fidelity (Narc):  ${ff}/10`);
   if (cq != null) lines.push(`  code_quality (Quality):      ${cq}/10`);
   if (economy != null) lines.push(`  economy (Quality, adv.):     ${economy}/10`);
@@ -421,6 +452,7 @@ function aggregatePanel(workerResults, meta = {}) {
       code_quality_effective: cqEffective,
       security_score: security,
       efficiency_score: efficiencyScore,
+      copy_score: copyScore,
     },
     signals: {
       grader_kind: 'subagent-panel',
@@ -470,6 +502,10 @@ function graderUnavailableResult({ reason, note, meta = {} } = {}) {
       code_quality_effective: null,
       security_score: null,
       efficiency_score: null,
+      // task 1003977: nulled with the rest so an outage grade's rubric_scores
+      // has the SAME SHAPE as a normal one. A key that is absent here and
+      // present there is a difference a consumer has to know about.
+      copy_score: null,
     },
     signals: {
       grader_kind: 'subagent-panel',

package/modules/lifecycle/cascade.js

@@ -135,23 +135,33 @@ function hasCopyOrVisualWork(task) {
 // STEP 2 remakes the copy/visuals with both routes explicitly offered — R04's
 // brief, verbatim in intent.
 //
-// STEP 1 used to say "coach the grader", and for as long as that was the wording
-// it asked for something no artist could do (task 1003937, ADR 0298). The panel's
-// four lenses — narc, quality, hacker, efficiency — read completion, code quality,
-// security and runtime cost; not one of them reads a sentence, so there was no
-// counterpart to coach and four consecutive reviews found the same wall. The
-// ADR's decision is a fifth ADVISORY 'reader' lens, scoped to copy-bearing diffs
-// by this file's own hasCopyOrVisualWork, built only after the instance writes a
-// voice guide to judge against. Until it exists the step asks for the RECORD
-// instead of the coaching: followable today, and it is the corpus both the guide
-// and the lens will be written from. When the reader lands, this reverts to
-// coaching a lens that is actually listening — and the wording is the signal for
-// which of those two worlds we are in, so do not restore the old sentence early.
+// STEP 1 ASKS FOR COACHING AGAIN, because there is now a lens listening.
+//
+// The history, because the wording is load-bearing: STEP 1 originally said
+// "coach the grader", which asked for something no artist could do (task
+// 1003937, ADR 0298) — the panel's four lenses read completion, code quality,
+// security and runtime cost, and not one read a sentence, so four consecutive
+// reviews found the same wall. The step was rewritten to ask for the RECORD
+// instead, and that version carried an explicit instruction not to restore the
+// coaching wording early, because the wording is the signal for which world we
+// are in.
+//
+// Task 1003977 shipped the fifth lens: an ADVISORY 'reader', scoped to
+// copy-bearing diffs by THIS FILE'S hasCopyOrVisualWork — the same predicate
+// that fires this cascade, so an artist review and the copy lens cover exactly
+// the same set by construction, and widening one widens both. The voice guide
+// it waited on is docs/voice.md (task 1003976). So there is a counterpart to
+// coach, it has a written standard to be coached against, and the record the
+// interim wording collected is what both were built from.
+//
+// What has NOT changed: the reader is non-gating and cannot hold a ship (ADR
+// 0241 keeps the artist's judgement on the deploy), so this review is still a
+// request triage may dismiss.
 function artistReviewBody(task) {
   return [
     `This is an ARTIST REVIEW, generated automatically because task ${task.id} put copy or visuals in front of a person. It is a REQUEST, not a gate — it blocks nothing that shipped, and triage may dismiss it.`,
     '',
-    `STEP 1 — READ THE GRADE, AND WRITE DOWN WHAT IT COULD NOT SEE. Pull how the grader judged task ${task.id} (GET /tasks/${task.id}?include=grade), then record what an artist would have caught and no lens did: slop, an off-voice line, a claim that does not land, a visual that reads as generated. Do not expect to find a copy verdict to argue with — the panel's four lenses read completion, code quality, security and runtime cost, and none of them reads a sentence (ADR 0298). Your record IS the compounding part: it is the evidence the advisory 'reader' lens is being built from, and the corpus the voice guide it waits on will be written against.`,
+    `STEP 1 — COACH THE READER. Pull how the grader judged task ${task.id} (GET /tasks/${task.id}?include=grade) and find the 'reader' row in signals.workers, with its copy_score in rubric_scores. That lens read the changed copy against docs/voice.md and cited rule ids. Say where it was RIGHT, where it was WRONG, and — the valuable one — what it did not see at all. A finding it filed that you disagree with is worth as much as one it missed: both are corrections to a lens that is listening, which is what this step could not ask for before task 1003977 shipped it (ADR 0298). If the miss is because no rule in docs/voice.md reaches it, that is a gap in the GUIDE — file it against the guide rather than expecting the lens to invent a rule at grade time. Two cases where there will be no reader row and that is not a fault: a ship that took the trivial-diff path (a single generalist shot, no panel), and one where the lens errored — it is advisory, so an outage is recorded and nothing is blocked.`,
     '',
     'STEP 2 — REMAKE OR TWEAK the copy/visuals if they need it. Your choice of route, both offered on purpose: OUTSIDE the AI chat (edit the surface directly and land it through the copy desk or the normal pipeline), or WITH it (draft in chat, then land). Either way it lands as a claimed, graded, shipped task like everything else — there is no live CMS (goal 1000074\'s hard rule).',
     '',

package/modules/lifecycle/tests/cascade.mjs

@@ -213,15 +213,24 @@ await test('a copy/visual ship generates the two-step artist review', () => {
   assert.match(spec.title, /7001/);
   // Both steps, and both routes of step 2, are in the body.
   //
-  // STEP 1's label tracks ADR 0298 (task 1003937). It used to read
-  // "REVIEW THE GRADER … coach it", which asked for something no artist could
-  // do: the panel's four lenses read completion, code quality, security and
-  // runtime cost, so there was no copy verdict to coach. Until the advisory
-  // reader worker ships (task 1003977, itself gated on the voice guide in
-  // task 1003976) the step asks for the RECORD instead — hence the pin on the
-  // new label AND on the ADR reference, which is what stops a well-meaning
-  // copy-edit from restoring the unfollowable version without reading why.
-  assert.match(spec.description, /STEP 1 — READ THE GRADE, AND WRITE DOWN WHAT IT COULD NOT SEE/);
+  // STEP 1's label tracks ADR 0298 (task 1003937), and it has now turned twice.
+  // It first read "REVIEW THE GRADER … coach it", which asked for something no
+  // artist could do: the panel's four lenses read completion, code quality,
+  // security and runtime cost, so there was no copy verdict to coach. It was
+  // rewritten to ask for the RECORD instead, as an explicitly INTERIM wording,
+  // pinned here so a well-meaning copy-edit could not restore the unfollowable
+  // version without reading why.
+  //
+  // Task 1003977 shipped the advisory reader lens and the voice guide it waited
+  // on (task 1003976), so the step is coaching again — and this pin moves with
+  // it. The two must turn TOGETHER: the wording is the signal for which world
+  // we are in, so a body that still said "no lens reads a sentence" after the
+  // lens landed would send every artist looking for a counterpart that is
+  // sitting right there in the grade record.
+  assert.match(spec.description, /STEP 1 — COACH THE READER/);
+  assert.match(spec.description, /docs\/voice\.md/, 'and names the written standard to coach against');
+  assert.doesNotMatch(spec.description, /none of them reads a sentence/,
+    'the interim claim is gone — it stopped being true when the reader shipped');
   assert.match(spec.description, /ADR 0298/, 'the step names the decision that shaped it');
   assert.match(spec.description, /STEP 2 — REMAKE OR TWEAK/);
   assert.match(spec.description, /OUTSIDE the AI chat/);

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.888",
+  "version": "1.19.890",
   "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/scripts/gds/db-backup-offsite.sh

@@ -17,6 +17,36 @@
 # ADR 0022. The systemd unit injects them via EnvironmentFile; a manual run
 # sources the same file. Required vars:
 #   SPACES_KEY SPACES_SECRET SPACES_BUCKET SPACES_REGION SPACES_ENDPOINT
+#   GDS_OFFSITE_AGE_RECIPIENT
+#
+# ENCRYPTION IS MANDATORY (task 1003372, audit ref A1). Until that task this
+# script uploaded the raw pg_dump to the Space. A database dump is not "a backup"
+# from a security standpoint — it is every secret the platform holds, in one
+# file, on someone else's disk: OAuth credentials, the GitHub App private key,
+# and (before core_249) every builder's live session bearer in plaintext. A
+# breach of the Space, a mis-set bucket ACL, or a leaked read-only S3 key was a
+# total compromise of the instance with no trace in any log the platform keeps.
+#
+# The dump is encrypted to a PUBLIC key (`age`), so this box can produce backups
+# it cannot itself read. That asymmetry is the point: an attacker who owns the
+# droplet gets the live database anyway, but they do not also get the archive of
+# every previous state, and they cannot decrypt what is already in the Space.
+# Keep the private key OFF this machine.
+#
+# One-time setup, on a machine that is NOT the server:
+#   age-keygen -o bongos-backup.key      # store this somewhere safe and offline
+#   # it prints:  Public key: age1xxxxxxxx...
+# Then on the server, add to $ENV_FILE:
+#   GDS_OFFSITE_AGE_RECIPIENT=age1xxxxxxxx...
+#
+# To restore:
+#   age -d -i bongos-backup.key <dump>.sql.gz.age | gunzip | psql <db>
+#
+# WITHOUT A RECIPIENT THIS SCRIPT REFUSES TO RUN. It does not fall back to a
+# plaintext upload: that fallback is the vulnerability, and a silent one, since
+# a backup that "worked" looks identical either way. A failing timer is visible
+# in `systemctl status gds-db-offsite.timer`; an unencrypted dump in a bucket is
+# visible to nobody until it matters.
 #
 # Manual one-shot:
 #   <instance-root>/scripts/gds/db-backup-offsite.sh
@@ -72,13 +102,17 @@ ENV_FILE="${GDS_SPACES_ENV:-${CONFIG_DIR_NAME:+/etc/$CONFIG_DIR_NAME/spaces.env}
 # extract only the five expected KEY=VALUE lines. `read -r k v` with IFS='='
 # splits on the FIRST '=' only, so base64 secrets containing '/', '+' or '='
 # survive intact.
-if [ -z "${SPACES_KEY:-}" ] && [ -f "$ENV_FILE" ]; then
+# Read the file when EITHER the credentials or the encryption recipient is still
+# unset. Keying this on SPACES_KEY alone would skip the file on a box where
+# systemd injects the S3 vars but the recipient was added to the file later —
+# and the script would then refuse to run while the key it needs sat right there.
+if { [ -z "${SPACES_KEY:-}" ] || [ -z "${GDS_OFFSITE_AGE_RECIPIENT:-}" ]; } && [ -f "$ENV_FILE" ]; then
   while IFS='=' read -r _k _v; do
     case "$_k" in
-      SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT)
+      SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT|GDS_OFFSITE_AGE_RECIPIENT)
         export "$_k=$_v" ;;
     esac
-  done < <(grep -E '^(SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT)=' "$ENV_FILE" || true)
+  done < <(grep -E '^(SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT|GDS_OFFSITE_AGE_RECIPIENT)=' "$ENV_FILE" || true)
 fi
 
 missing=()
@@ -91,8 +125,30 @@ if [ "${#missing[@]}" -gt 0 ]; then
   exit 2
 fi
 
+# The encryption recipient is as required as the credentials — a dump this box
+# can upload but nobody can decrypt is useless, and a dump it uploads in the
+# clear is the finding this refusal exists to close (task 1003372, audit A1).
+if [ -z "${GDS_OFFSITE_AGE_RECIPIENT:-}" ]; then
+  echo "ERROR: GDS_OFFSITE_AGE_RECIPIENT is not set — refusing to ship an unencrypted database dump offsite." >&2
+  echo "       A dump is every secret this platform holds, in one file, on storage the platform does not own." >&2
+  echo "" >&2
+  echo "       Fix, on a machine that is NOT this server:" >&2
+  echo "         age-keygen -o bongos-backup.key     # keep this file safe and OFFLINE — it is the only way back" >&2
+  echo "       then add the age1... public key it prints to $ENV_FILE:" >&2
+  echo "         GDS_OFFSITE_AGE_RECIPIENT=age1..." >&2
+  echo "" >&2
+  echo "       This is deliberately not optional: falling back to a plaintext upload would look identical in the logs." >&2
+  exit 2
+fi
+
+
 # ---- preconditions ----------------------------------------------------------
 
+if ! command -v age >/dev/null 2>&1; then
+  echo "ERROR: 'age' not on PATH — it is what encrypts the dump before it leaves this box." >&2
+  echo "       Install with: apt install age   (or fetch the static binary from https://github.com/FiloSottile/age/releases)" >&2
+  exit 2
+fi
 if ! command -v python3 >/dev/null 2>&1; then
   echo "ERROR: python3 not on PATH (needed for the boto3 S3 client)." >&2
   exit 2
@@ -113,14 +169,38 @@ if [ -z "$LATEST" ]; then
 fi
 
 BASENAME=$(basename "$LATEST")
-KEY="${PREFIX}${BASENAME}"
 BYTES=$(stat -c '%s' "$LATEST")
 
-echo "[$(date -u +%FT%TZ)] gds-db-offsite: archiving ${LATEST} (${BYTES} bytes) → s3://${SPACES_BUCKET}/${KEY}"
+# ---- encrypt before it leaves the box ---------------------------------------
+#
+# To a temp file under the backup dir (same filesystem, so no cross-device copy
+# of plaintext through /tmp) with a 0600 umask, and removed on every exit path
+# including failure — the cleartext dump already lives beside it, so the
+# ciphertext is not sensitive in itself, but leaving files behind on a failing
+# weekly timer fills a disk nobody is watching.
+umask 077
+ENC="$(mktemp "${BACKUP_DIR}/.${BASENAME}.age.XXXXXX")"
+trap 'rm -f "$ENC"' EXIT
+
+if ! age -r "$GDS_OFFSITE_AGE_RECIPIENT" -o "$ENC" "$LATEST"; then
+  echo "ERROR: age refused to encrypt — is GDS_OFFSITE_AGE_RECIPIENT a valid age1... public key?" >&2
+  exit 2
+fi
+
+# A zero-byte or missing ciphertext would upload happily and restore to nothing.
+# Checked here rather than trusted, because the failure is silent for a month.
+ENC_BYTES=$(stat -c '%s' "$ENC")
+if [ "$ENC_BYTES" -lt 1 ]; then
+  echo "ERROR: encryption produced an empty file — refusing to upload it as a backup." >&2
+  exit 2
+fi
+
+KEY="${PREFIX}${BASENAME}.age"
+echo "[$(date -u +%FT%TZ)] gds-db-offsite: archiving ${LATEST} (${BYTES} bytes → ${ENC_BYTES} encrypted) → s3://${SPACES_BUCKET}/${KEY}"
 
 # ---- upload + prune (single boto3 session) ----------------------------------
 
-GDS_OFFSITE_LOCAL="$LATEST" \
+GDS_OFFSITE_LOCAL="$ENC" \
 GDS_OFFSITE_KEY="$KEY" \
 GDS_OFFSITE_KEEP="$KEEP" \
 GDS_OFFSITE_PREFIX="$PREFIX" \
@@ -151,10 +231,25 @@ s3 = boto3.client(
 s3.upload_file(local, bucket, objkey)
 print(f"[gds-db-offsite] uploaded {objkey}")
 
-# Prune: keep the newest `keep` objects under our prefix, delete the rest.
 resp = s3.list_objects_v2(Bucket=bucket, Prefix=prefix)
+contents = resp.get("Contents", [])
+
+# PURGE THE PLAINTEXT ALREADY UP THERE (task 1003372, audit A1). Every `.sql.gz`
+# under this prefix was uploaded unencrypted by an earlier version of this
+# script, and each one is a live copy of every secret the platform held on the
+# day it was taken — including, before core_249, directly replayable session
+# bearers. Encrypting from now on does nothing about them. They are deleted
+# OUTSIDE the retention count, and unconditionally: retaining four of them
+# "for safety" would retain the finding. The local nightly dumps on the droplet
+# are untouched, so this removes copies, never the last copy.
+legacy = [o for o in contents if o["Key"].endswith(".sql.gz")]
+for obj in legacy:
+    s3.delete_object(Bucket=bucket, Key=obj["Key"])
+    print(f"[gds-db-offsite] PURGED unencrypted legacy dump {obj['Key']}")
+
+# Prune: keep the newest `keep` ENCRYPTED objects under our prefix.
 objects = sorted(
-    [o for o in resp.get("Contents", []) if o["Key"].endswith(".sql.gz")],
+    [o for o in contents if o["Key"].endswith(".sql.gz.age")],
     key=lambda o: o["LastModified"],
 )
 to_delete = objects[:-keep] if len(objects) > keep else []
@@ -163,7 +258,8 @@ for obj in to_delete:
     print(f"[gds-db-offsite] pruned {obj['Key']}")
 
 kept = min(len(objects), keep)
-print(f"[gds-db-offsite] ok · {kept} offsite dump(s) retained · pruned {len(to_delete)}")
+print(f"[gds-db-offsite] ok · {kept} offsite dump(s) retained · pruned {len(to_delete)}"
+      + (f" · purged {len(legacy)} unencrypted legacy dump(s)" if legacy else ""))
 PYEOF
 
 echo "[$(date -u +%FT%TZ)] gds-db-offsite: done"