@bongos/core 1.19.492 → 1.19.494

package/modules/copy-desk/tests/copy_no_cms.mjs

@@ -1,5 +1,6 @@
 // modules/copy-desk/tests/copy_no_cms.mjs — the goal's hard NON-GOAL, made
-// testable (task 1003113 / R02 of goal 1000074).
+// testable (task 1003113 / R02, brought to its full version by task 1003114 /
+// R03 of goal 1000074).
 //
 // Goal 1000074, verbatim: "NO LIVE CMS. Every copy change is a claimed, graded,
 // shipped GDS task (the methodology's hard rule). The registry is an inventory
@@ -10,16 +11,25 @@
 // this one erodes is not a dramatic "add a CMS" commit — it is one plausible
 // column ("just store the suggested wording so the artist doesn't lose it"),
 // then one plausible read of that column, and the ledger rule is dead with
-// nobody having decided to kill it. So the shape is pinned here:
+// nobody having decided to kill it.
 //
-//   * the write surface is EXACTLY the two verbs R02 defines,
-//   * no column on copy_desk_flags could hold replacement text, and
-//   * nothing in this module ever hands a renderer a string as authoritative copy.
+// R02 pinned the shape while the module could not edit anything at all. R03 is
+// the harder case and the reason this file exists: the module now DOES carry an
+// editing affordance, so "no CMS" has to survive contact with a feature whose
+// whole job is proposing new words. It survives because of where the words go.
+// A proposal becomes a TASK — the ledger every change already passes through,
+// which no renderer reads — and the wording reaches a person only after somebody
+// claims that task and ships the diff. So the four things pinned here are:
 //
-// R03 (task 1003114) builds the editing affordance, and its own done-when asks
-// for the full version of this test. This is the R02-scoped seed of it: when R03
-// adds a proposal path, the expected route list below changes DELIBERATELY, in a
-// diff a reviewer can see, rather than drifting.
+//   * the write surface is EXACTLY the three verbs the module defines,
+//   * no column on copy_desk_flags could hold replacement text,
+//   * nothing in this module writes a file, and
+//   * the ONLY thing that writes a surface file is the applier, it lives outside
+//     the request path, and it cannot write outside a registry surface.
+//
+// R02's version of this file said: "when R03 adds a proposal path, the expected
+// route list below changes DELIBERATELY, in a diff a reviewer can see, rather
+// than drifting." This is that diff.
 
 import { strict as assert } from 'node:assert';
 import fs from 'node:fs';
@@ -28,6 +38,7 @@ import url from 'node:url';
 
 const HERE = path.dirname(url.fileURLToPath(import.meta.url));
 const MODULE_DIR = path.join(HERE, '..');
+const REPO_ROOT = path.join(MODULE_DIR, '..', '..');
 
 let passed = 0;
 let failed = 0;
@@ -37,6 +48,7 @@ async function test(name, fn) {
 }
 
 const read = (rel) => fs.readFileSync(path.join(MODULE_DIR, rel), 'utf8');
+const readRepo = (rel) => fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8');
 
 // Strip comments so the prose ABOUT the rule (which necessarily names the
 // forbidden things — the migration header says in so many words that a flag
@@ -49,7 +61,7 @@ const stripComments = (src) => src
 
 console.log('copy-desk: NO LIVE CMS');
 
-await test('the write surface is exactly the two verbs R02 defines', () => {
+await test('the write surface is exactly the three verbs the module defines', () => {
   const src = stripComments(read('routes/copy-desk.js'));
   const found = [...src.matchAll(/router\.(post|put|patch|delete)\(\s*'([^']+)'/g)]
     .map((m) => `${m[1].toUpperCase()} ${m[2]}`)
@@ -57,6 +69,7 @@ await test('the write surface is exactly the two verbs R02 defines', () => {
   assert.deepEqual(found, [
     'POST /copy-desk/flags',
     'POST /copy-desk/flags/:id/close',
+    'POST /copy-desk/proposals',
   ], 'a new write route on this module must be a deliberate, reviewed change to this list');
 });
 
@@ -69,6 +82,16 @@ await test('no column on copy_desk_flags could hold replacement text', () => {
     `copy_desk_flags must carry a judgement and a pointer, never replacement copy (found "${hit && hit[0]}")`);
 });
 
+await test('R03 added no migration — a proposal is a task, not a row here', () => {
+  // The load-bearing one. R03's obvious-but-wrong implementation is a
+  // `copy_desk_proposals` table, which is the forbidden column with extra steps:
+  // once the wording lives in this module's schema, one plausible read of it
+  // turns the module into the copy source. The proposal lives on the TASK.
+  const migrations = fs.readdirSync(path.join(MODULE_DIR, 'migrations')).sort();
+  assert.deepEqual(migrations, ['copy_desk_001_flags.sql'],
+    'a second migration in this module needs a hard look at whether it stores copy');
+});
+
 await test('the only text column is the historical snapshot, and it is never the live source', () => {
   const sql = stripComments(read('migrations/copy_desk_001_flags.sql'));
   const textish = [...sql.matchAll(/^\s{2}(\w+)\s+text\b/gm)].map((m) => m[1]);
@@ -87,17 +110,72 @@ await test('this module never writes to the surfaces it inventories', () => {
   // The registry is generated by R01 and committed. If this module ever gained a
   // write to docs/copy-registry.json — or to any surface file — the inventory
   // would stop describing the tree and start describing itself.
-  for (const rel of ['registry.js', 'flags.js', 'routes/copy-desk.js']) {
+  for (const rel of ['registry.js', 'flags.js', 'proposals.js', 'routes/copy-desk.js']) {
     const src = stripComments(read(rel));
     assert.equal(/fs\.(writeFile|writeFileSync|appendFile|appendFileSync|rm|unlink|mkdir)/.test(src), false,
       `${rel} performs a filesystem WRITE — this module reads the registry and never writes it`);
   }
 });
 
+await test('the proposal domain holds no path to a renderer — it composes text and parses it back', () => {
+  // proposals.js is the file that handles replacement wording, so it is the file
+  // most able to become a copy source by accident. It must be PURE: no fs, no
+  // DB, no network. Its output goes into a task description and nowhere else.
+  const src = stripComments(read('proposals.js'));
+  for (const forbidden of ['require(', 'fs.', 'pool', 'fetch(']) {
+    assert.equal(src.includes(forbidden), false,
+      `proposals.js must stay pure — it must not reach for ${forbidden}`);
+  }
+});
+
+await test('the proposal route creates a TASK and does not write a string anywhere', () => {
+  const src = stripComments(read('routes/copy-desk.js'));
+  const route = src.slice(src.indexOf("router.post('/copy-desk/proposals'"));
+  assert.ok(/lifecycle\.createTask\(/.test(route),
+    'the proposal path must land in the ledger via lifecycle.createTask');
+  // No INSERT/UPDATE of this module's own tables on the proposal path — the
+  // wording must not come to rest in copy_desk_*.
+  assert.equal(/insertFlag|closeFlag|INSERT INTO|UPDATE /i.test(route), false,
+    'the proposal path must not write a row in this module — the task IS the record');
+});
+
 await test('the module manifest declares no seam another module could write copy through', () => {
   const manifest = JSON.parse(read('module.json'));
   assert.deepEqual(manifest.provides, [], 'a provided port here would be a copy write path for every other module');
-  assert.deepEqual(manifest.consumes, []);
+  // R03 consumes `lifecycle` to create the proposal task. That direction is the
+  // safe one and the point: this module can put a work request INTO the ledger,
+  // and nothing can pull copy OUT of this module.
+  assert.deepEqual(manifest.consumes, ['lifecycle']);
+});
+
+await test('the applier is the only writer, it lives outside the request path, and it is path-guarded', () => {
+  // The one thing in this feature that does write a surface file. Three
+  // properties make that safe, and all three are pinned here.
+  const applier = readRepo('scripts/gds/copy-apply.js');
+  const stripped = stripComments(applier);
+
+  // 1. It is a COMMAND, not a route: nothing in the module's request path
+  //    IMPORTS it, so no HTTP call can cause a file write. Naming it is fine and
+  //    in fact required — the task a proposal creates tells its claimer the
+  //    exact line to run, and that instruction is the whole handoff. What must
+  //    not exist is a require/import edge, which would put a file write one
+  //    function call away from a request handler.
+  for (const rel of ['registry.js', 'flags.js', 'proposals.js', 'routes/copy-desk.js']) {
+    const src = stripComments(read(rel));
+    assert.equal(/(?:require|import)\s*\(?\s*['"][^'"]*copy-apply/.test(src), false,
+      `${rel} must not IMPORT the applier — it runs under a claim, not under a request`);
+  }
+
+  // 2. It writes only inside a surface the REGISTRY defines, and the guard is
+  //    derived from R01's own SURFACES table rather than a second list.
+  assert.ok(/path_outside_surface/.test(stripped), 'the applier must refuse a path outside its surface');
+  assert.ok(/ci\.SURFACES/.test(stripped), 'the path guard must derive from the inventory, not a hardcoded root');
+
+  // 3. It verifies its own work against a freshly regenerated registry, so an
+  //    edit that lands somewhere the inventory does not read as copy is
+  //    reported rather than committed quietly.
+  assert.ok(/regenerated registry does not contain the new wording/.test(applier),
+    'the applier must check that what it wrote is what the inventory now reads');
 });
 
 console.log(`\n${passed} passed, ${failed} failed`);

package/modules/copy-desk/tests/copy_proposals.mjs

@@ -0,0 +1,279 @@
+// modules/copy-desk/tests/copy_proposals.mjs — the proposal, end to end as far
+// as a DB-free test can take it (task 1003114 / R03 of goal 1000074).
+//
+// copy_no_cms.mjs pins what this feature must NEVER do. This file pins what it
+// must DO, and the interesting half is the applier: an artist's wording has to
+// land on exactly the characters that string occupies and on nothing else. A
+// copy change that lands on the wrong bytes is worse than one that never lands,
+// so most of what follows is the refusals.
+//
+// The two halves are tested against each other deliberately — `composeProposal
+// Block` writes what `parseProposalBlock` reads, and the applier consumes the
+// parse — because a format with one writer and one reader is exactly the kind
+// that drifts silently until a real file gets edited wrong.
+//
+// DB-free and fs-free: the applier's pure layer takes a source STRING, so every
+// case below is a hand-written file that never touches the tree.
+
+import { strict as assert } from 'node:assert';
+import path from 'node:path';
+import url from 'node:url';
+import { createRequire } from 'node:module';
+
+const HERE = path.dirname(url.fileURLToPath(import.meta.url));
+const require_ = createRequire(import.meta.url);
+const proposals = require_(path.join(HERE, '..', 'proposals.js'));
+const applier = require_(path.join(HERE, '..', '..', '..', 'scripts', 'gds', 'copy-apply.js'));
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+// A registry entry, the shape registry.occurrencesOf hands back.
+const entry = (over = {}) => ({
+  id: 'abc123abc123',
+  surface: 'builders-hall',
+  file: 'modules/hall-ui/public/copy-desk.js',
+  line: 42,
+  origin: 'js-markup',
+  text: 'Loading the copy desk…',
+  ...over,
+});
+
+const HALL = 'modules/hall-ui/public/t.js';
+const HALL_HTML = 'modules/hall-ui/public/t.html';
+
+console.log('copy-desk: proposals');
+
+// ---------------------------------------------------------------------------
+// The judgement floor. Same argument as a flag's reason (ADR 0178 §2): a
+// proposal with no case for it costs a reviewer more than no proposal.
+// ---------------------------------------------------------------------------
+
+await test('a proposal needs a reason a reviewer can decide on', () => {
+  const r = proposals.normalizeProposalPayload({
+    body: { proposed_text: 'Opening the copy desk…', why: 'better' },
+    entry: entry(),
+  });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'why_too_thin');
+  assert.ok(r.detail.what_this_means.length > 0, 'the refusal has to tell the person what to do');
+});
+
+await test('a proposal that changes nothing is refused rather than filed', () => {
+  const r = proposals.normalizeProposalPayload({
+    body: { proposed_text: 'Loading the copy desk…', why: 'This wording reads as machine-written to me.' },
+    entry: entry(),
+  });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'proposed_text_unchanged');
+});
+
+await test('the target facts are taken from the registry, never from the body', () => {
+  const r = proposals.normalizeProposalPayload({
+    // A caller trying to describe a different target than the one they named.
+    body: {
+      proposed_text: 'Opening the copy desk…',
+      why: 'The current line describes the machine, not the person waiting.',
+      file: 'migrations/core_001_secrets.sql',
+      line: 1,
+      current: 'something else entirely',
+      surface: 'not-a-surface',
+    },
+    entry: entry(),
+    builderId: 7,
+  });
+  assert.equal(r.ok, true);
+  assert.equal(r.patch.file, 'modules/hall-ui/public/copy-desk.js', 'file must come from the registry entry');
+  assert.equal(r.patch.surface, 'builders-hall');
+  assert.equal(r.patch.line, 42);
+  assert.equal(r.patch.current, 'Loading the copy desk…', 'the current wording is a server-side fact');
+});
+
+await test('the placeholder count must hold, and the refusal explains why', () => {
+  const bad = proposals.normalizeProposalPayload({
+    body: { proposed_text: 'Welcome back to the hall.', why: 'Shorter and warmer than the current line.' },
+    entry: entry({ text: 'Hello {…}, welcome back to the hall.' }),
+  });
+  assert.equal(bad.ok, false);
+  assert.equal(bad.code, 'placeholder_mismatch');
+  assert.equal(bad.detail.expected, 1);
+  assert.equal(bad.detail.got, 0);
+
+  const good = proposals.normalizeProposalPayload({
+    body: { proposed_text: 'Good to see you, {…} — welcome back.', why: 'Shorter and warmer than the current line.' },
+    entry: entry({ text: 'Hello {…}, welcome back to the hall.' }),
+  });
+  assert.equal(good.ok, true, 'keeping the hole, even in a new position, is allowed');
+});
+
+// ---------------------------------------------------------------------------
+// The patch format. One writer, one reader, tested against each other.
+// ---------------------------------------------------------------------------
+
+await test('a composed proposal block parses back to the same patch', () => {
+  const { patch } = proposals.normalizeProposalPayload({
+    body: { proposed_text: 'Opening the copy desk…', why: 'The current line describes the machine, not the person waiting.' },
+    entry: entry(),
+  });
+  const body = proposals.proposalTaskBody(patch);
+  const parsed = proposals.parseProposalBlock(body);
+  assert.equal(parsed.ok, true);
+  for (const field of ['string_id', 'surface', 'file', 'line', 'origin', 'current', 'proposed']) {
+    assert.deepEqual(parsed.patch[field], patch[field], `${field} must survive the round trip`);
+  }
+  // RUNNABLE AS WRITTEN. The task cannot know its own id while its description is
+  // being composed, so the command takes none and acts on the claim you hold —
+  // a placeholder here would be a step for the claimer to get wrong.
+  assert.match(body, /```bash\nnode scripts\/gds\/copy-apply\.js\n```/,
+    'the task must tell its claimer the exact line that lands it, with nothing to substitute');
+  assert.ok(!/<this task id>|--task <|\$\{/.test(body), 'and no placeholder survives into the instructions');
+});
+
+await test('a description with two proposals is refused, not silently halved', () => {
+  const { patch } = proposals.normalizeProposalPayload({
+    body: { proposed_text: 'Opening the copy desk…', why: 'The current line describes the machine, not the person.' },
+    entry: entry(),
+  });
+  const two = `${proposals.composeProposalBlock(patch)}\n\n${proposals.composeProposalBlock(patch)}`;
+  const parsed = proposals.parseProposalBlock(two);
+  assert.equal(parsed.ok, false);
+  assert.equal(parsed.code, 'multiple_proposal_blocks');
+});
+
+await test('a patch from an unknown schema is refused rather than half-understood', () => {
+  const parsed = proposals.parseProposalBlock('```copy-proposal\n{"schema":99,"string_id":"x"}\n```');
+  assert.equal(parsed.ok, false);
+  assert.equal(parsed.code, 'proposal_schema_unknown');
+});
+
+await test('a task with no proposal in it is a named refusal', () => {
+  const parsed = proposals.parseProposalBlock('An ordinary task about something else.');
+  assert.equal(parsed.ok, false);
+  assert.equal(parsed.code, 'no_proposal_block');
+});
+
+// ---------------------------------------------------------------------------
+// The applier. This is where wrong is expensive.
+// ---------------------------------------------------------------------------
+
+const patchFor = (over = {}) => ({
+  schema: 1,
+  string_id: 'abc123abc123',
+  surface: 'builders-hall',
+  file: HALL,
+  line: 1,
+  origin: 'js-markup',
+  current: 'Loading the copy desk…',
+  proposed: 'Opening the copy desk…',
+  ...over,
+});
+
+await test('it replaces exactly the string, and leaves the markup around it alone', () => {
+  const src = 'const h = `<p class="lede">Loading the copy desk…</p>`;';
+  const r = applier.applyPatchToSource(src, HALL, patchFor());
+  assert.equal(r.ok, true);
+  assert.equal(r.source, 'const h = `<p class="lede">Opening the copy desk…</p>`;');
+});
+
+await test('it puts the source’s own interpolations back, in the order the new sentence needs', () => {
+  const src = 'const h = `<p>Hello ${builder.name}, welcome back to the hall.</p>`;';
+  const r = applier.applyPatchToSource(src, HALL, patchFor({
+    current: 'Hello {…}, welcome back to the hall.',
+    proposed: 'Good to see you, {…} — welcome back.',
+  }));
+  assert.equal(r.ok, true);
+  assert.equal(r.source, 'const h = `<p>Good to see you, ${builder.name} — welcome back.</p>`;',
+    'the expression must survive verbatim, at its new position in the sentence');
+});
+
+await test('an html attribute is replaced inside its quotes and nowhere else', () => {
+  const src = '<button title="Flag this copy" aria-label="Flag this copy">Flag</button>';
+  const r = applier.applyPatchToSource(src, HALL_HTML, patchFor({
+    origin: 'html-attr:title',
+    current: 'Flag this copy',
+    proposed: 'Mark this wording for review',
+  }));
+  assert.equal(r.ok, true);
+  assert.equal(r.source, '<button title="Mark this wording for review" aria-label="Flag this copy">Flag</button>',
+    'only the attribute the patch named may change');
+});
+
+await test('a string that has already been reworded is refused, and nothing is written', () => {
+  const src = 'const h = `<p>Opening the copy desk…</p>`;';
+  const r = applier.applyPatchToSource(src, HALL, patchFor());
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'target_gone');
+  assert.ok(r.detail.what_this_means.includes('Nothing was changed'));
+});
+
+await test('a string that appears twice in one file is refused unless the line disambiguates', () => {
+  const src = [
+    'const a = `<p>Could not save.</p>`;',
+    'const b = `<p>Could not save.</p>`;',
+  ].join('\n');
+  const ambiguous = applier.applyPatchToSource(src, HALL, patchFor({
+    current: 'Could not save.', proposed: 'That did not save.', line: 9,
+  }));
+  assert.equal(ambiguous.ok, false);
+  assert.equal(ambiguous.code, 'ambiguous_target');
+  assert.deepEqual(ambiguous.detail.lines, [1, 2]);
+
+  const picked = applier.applyPatchToSource(src, HALL, patchFor({
+    current: 'Could not save.', proposed: 'That did not save.', line: 2,
+  }));
+  assert.equal(picked.ok, true);
+  assert.equal(picked.source, [
+    'const a = `<p>Could not save.</p>`;',
+    'const b = `<p>That did not save.</p>`;',
+  ].join('\n'), 'only the named line may change');
+});
+
+await test('a string whose literal is escaped has no exact span, and is refused by name', () => {
+  // The inventory unescapes a quoted literal before reading it, which shifts
+  // every character after the backslash — so no exact span exists and the
+  // applier must not guess at one.
+  const src = "const h = '<p>She said \\'no\\' to the wording, twice.</p>';";
+  const r = applier.applyPatchToSource(src, HALL, patchFor({
+    current: "She said 'no' to the wording, twice.",
+    proposed: 'She turned the wording down, twice.',
+  }));
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'no_exact_span');
+});
+
+await test('the path guard refuses anything outside the surface the registry defines', () => {
+  for (const file of ['../../../etc/passwd', 'migrations/core_001.sql', 'config/branding.json', 'modules/hall-ui/public/../../../server.js']) {
+    const r = applier.checkPatchPath(patchFor({ file }));
+    assert.equal(r.ok, false, `${file} must be refused`);
+    assert.equal(r.code, 'path_outside_surface');
+  }
+  const ok = applier.checkPatchPath(patchFor({ file: 'modules/hall-ui/public/copy-desk.js' }));
+  assert.equal(ok.ok, true);
+});
+
+await test('an unknown surface is refused before any file is read', () => {
+  const r = applier.checkPatchPath(patchFor({ surface: 'somewhere-else' }));
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'unknown_surface');
+  assert.ok(Array.isArray(r.detail.known) && r.detail.known.length > 0, 'the refusal names the surfaces that do exist');
+});
+
+await test('the applier re-checks the placeholder arithmetic against the real source', () => {
+  // The proposal path already checked it, but the source is what is about to be
+  // written and may have changed since. Belt and braces, on the one rule where
+  // being wrong corrupts a file rather than annoying a person.
+  const src = 'const h = `<p>Hello ${name} and ${other}, welcome.</p>`;';
+  const r = applier.applyPatchToSource(src, HALL, patchFor({
+    current: 'Hello {…} and {…}, welcome.',
+    proposed: 'Welcome, {…}.',
+  }));
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'placeholder_mismatch');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -286,6 +286,8 @@ function createClient(opts = {}) {
       postCopyDeskFlags: (args) => request("POST", "/copy-desk/flags", { hasBody: true }, args),
       // POST /copy-desk/flags/{id}/close — rank: any-builder — POST /copy-desk/flags/:id/close
       postCopyDeskFlagsIdClose: (args) => request("POST", "/copy-desk/flags/{id}/close", { hasBody: true }, args),
+      // POST /copy-desk/proposals — rank: any-builder — POST /copy-desk/proposals
+      postCopyDeskProposals: (args) => request("POST", "/copy-desk/proposals", { hasBody: true }, args),
       // GET /copy-desk/queue — rank: any-builder — GET /copy-desk/queue
       getCopyDeskQueue: (args) => request("GET", "/copy-desk/queue", { hasBody: false }, args),
       // GET /copy-desk/strings — rank: any-builder — GET /copy-desk/strings

package/modules/hall-ui/public/copy-desk.css

@@ -67,7 +67,7 @@
 .cd-find .filter input[type="search"] { width: 100%; }
 .cd-search-count { margin: 0 0 14px; }
 
-/* The two dialogs are the family modal on a native <dialog>: bg-card, one rule
+/* The three dialogs are the family modal on a native <dialog>: bg-card, one rule
    hairline, no shadow. The backdrop is the one literal this sheet keeps — pure
    black with alpha as a SCRIM is the exception the Fifteen Rule names, and a
    backdrop cannot take a ground token: it has to darken whatever is behind it
@@ -77,3 +77,11 @@
 .cd-dialog .ov-form { margin: 14px 0 0; }
 .cd-dialog textarea { resize: vertical; line-height: 1.5; }
 .ov-modal .cd-dialog__err { min-height: 18px; margin: 8px 0 0; font-size: 13px; line-height: 1.45; color: var(--danger); }
+
+/* The placeholder rule, shown only for a sentence that has holes in it (task
+   1003114 / R03). It is a CONSTRAINT, not a footnote — losing a hole is the one
+   edit the applier refuses outright — so it is the note voice raised one ink
+   step, and nothing more. No band, no tint: this family marks state with a pill
+   and never with a bar, and a rule the reader must obey is not an exception to
+   that, it is the reason to keep it. */
+.cd-holes { color: var(--ink-soft); }

package/modules/hall-ui/public/copy-desk.html

@@ -142,6 +142,39 @@
   </form>
 </dialog>
 
+<!-- Proposing new wording (task 1003114 / R03). A third dialog rather than a mode
+     on the flag composer, because the two acts are different: a flag says this is
+     wrong, a proposal says this is what it should say instead, and one of them
+     creates work on the board. The textarea opens PREFILLED with the current
+     wording — an artist edits a sentence, they do not retype it from memory. -->
+<dialog id="cd-propose-dialog" class="ov-modal cd-dialog">
+  <form method="dialog" id="cd-propose-form">
+    <h3 class="scroll__h">Propose new wording</h3>
+    <p class="cd-dialog__target" id="cd-propose-target"></p>
+    <div class="ov-form">
+      <div class="ov-field ov-field--wide">
+        <label class="ov-field__l" for="cd-propose-text">What should it say?</label>
+        <textarea id="cd-propose-text" rows="3" required></textarea>
+      </div>
+      <!-- Shown only when the sentence has holes in it. The arithmetic is a real
+           rule, not a formality: the applier puts the source's own values back
+           into these, so losing one is a code change and gets refused. -->
+      <p class="ov-form__why cd-holes" id="cd-propose-holes" hidden></p>
+      <div class="ov-field ov-field--wide">
+        <label class="ov-field__l" for="cd-propose-why">Why is this better?</label>
+        <textarea id="cd-propose-why" rows="4" minlength="10" required
+                  placeholder="What the current wording gets wrong, and what yours does about it."></textarea>
+      </div>
+      <p class="ov-form__why">Nothing changes yet. This files a task carrying your wording; whoever claims it lands the diff, and it ships graded like every other change.</p>
+    </div>
+    <p class="cd-dialog__err" id="cd-propose-err" role="alert"></p>
+    <div class="ov-modal__actions">
+      <button type="button" class="btn-ghost" id="cd-propose-cancel">Cancel</button>
+      <button type="button" class="btn-accent" id="cd-propose-submit">File the change</button>
+    </div>
+  </form>
+</dialog>
+
 <div id="toast" class="toast" role="status" aria-live="polite" data-visible="0"></div>
 
 <script src="/builders/shell.js?v=2026-07-02-shell1"></script>