@bongos/core 1.19.1055 → 1.19.1056

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.1055",
-  "core_contract": "1.19.1055",
-  "source_commit": "dc38a2a4e86d707edd38427cf7df3c4437458758",
+  "core_version": "1.19.1056",
+  "core_contract": "1.19.1056",
+  "source_commit": "069ec293a36320e7bb8a9546282a2ef92bed10e4",
   "source_ref": "HEAD",
-  "built_at": "2026-09-28T05:05:07.855Z",
+  "built_at": "2026-09-28T05:31:55.050Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 542,
+    "docs_redacted": 543,
     "agent_docs_stubbed": 26,
     "functional_verbatim": 2511,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3080,
-  "tree_sha256": "b6c500e72b0b49f4521c50a3282616cfdf968b85b827eace71deb76fca3f55dd",
+  "file_count": 3081,
+  "tree_sha256": "8984ba3615dc3744fe218ef870fafffbf77518b4db628e054010ca8cb40ed041",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -1627,7 +1627,7 @@
     {
       "path": "docs/adr/0233-a-copy-proposal-is-a-task-carrying-a-patch.md",
       "mode": "0000644",
-      "sha256": "6c44b222db9e6e91e1dcf137c4c9ccac3113790b6b453c189949991aac72e861"
+      "sha256": "8b4cf87eeccb6b9018ae6ff72d976b1cad4d6c0fd38b78ae9ebc44b1ff2223f7"
     },
     {
       "path": "docs/adr/0234-idea-routing-capture-time-promotion-landing-matrix-homeless-inbox.md",
@@ -2164,10 +2164,15 @@
       "mode": "0000644",
       "sha256": "26bcf5464d93ebf3186831e3a2f9df0622b9e38dab9fd1daf9899c63a365c7a2"
     },
+    {
+      "path": "docs/adr/0341-the-page-is-the-unit-of-tweak-mode.md",
+      "mode": "0000644",
+      "sha256": "ab4cefdfbe2505dabe75298a1f2ac98adee1dcbb205c3879d91813d242bdf60f"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "117a17c71d5b811fca29ef77f0140c18aa0b8c699b57e0b8352d3938b3a79c91"
+      "sha256": "33c5508da42392b6ecc70ef3a0c1951714cb0a22551765c3e87213c1fc9bc253"
     },
     {
       "path": "docs/api-reference.md",
@@ -2737,7 +2742,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "5a093f82bbd86f7932a798a5e53f85609e08c7837ef64c2334a7a2b8efc401c1"
+      "sha256": "8c3a8c0069cd15d3b2ade2c2cc7c87a346c733cadd37ffc7c52a1f1ec22e3f6f"
     },
     {
       "path": "docs/modules-contract.md",
@@ -8462,12 +8467,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b60b03c560a09917e3383f0630839ff29ffade876f87f0079f1cb718dac762e6"
+      "sha256": "edc67014a2cb1e4b1b5d6e59d3da8cacb2b22c51c959bc28fc33e598b400e1c5"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "21389dd422886a6fcf8088ac5be8dd63f39e76f6c28fd063f3cd72e9eadefc2c"
+      "sha256": "7bf05c3c167f553ab3f5aa7f68adb070625e336e0ab8444d5f5ccd3609eff206"
     },
     {
       "path": "public-docs/index.html",
@@ -8487,7 +8492,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "3631f0c336ffb1fa2da262932c3158a4cb79c640c52ffc04e08a21b23c8f4534"
+      "sha256": "cf9eeae40e20a710b6342a6af31c2f29cd0044df79f221408a8f98c3531f1252"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -10567,7 +10572,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "22a1cf07ea07585df430c3a395af379d9a6bb81b20d5bf647128272568b57580"
+      "sha256": "8419fdb2f19beaccf903a5f9d341ba6b0bf76b75d6f8e14c574e65e341f6a83e"
     },
     {
       "path": "src/module-loader/catalog.js",

package/docs/adr/0233-a-copy-proposal-is-a-task-carrying-a-patch.md

@@ -5,6 +5,7 @@
 - **Tasks:** [#1003114](https://cloudbongos.com/builders#/task/1003114) (R03 of goal 1000074, the artist's loop) — builds on [#1003112](https://cloudbongos.com/builders#/task/1003112) (R01, the registry) and [#1003113](https://cloudbongos.com/builders#/task/1003113) (R02, the flag and the queue)
 - **Extends:** [ADR 0081](0081-tool-agnostic-design-layer.md) — the repo is the source of truth, with swappable tool adapters that land their output as a committed diff. This applies that contract to TEXT.
 - **Extends:** [ADR 0178](0178-the-copy-desk-flag-and-queue.md) — which pinned that `copy_desk_flags` may never hold replacement text, and named this task as the one that would have to keep that true while adding an editing affordance.
+- **Amended by:** [ADR 0341](0341-the-page-is-the-unit-of-tweak-mode.md) (task 1004332) — a proposal may also be a whole-page batch (the `page-tweak` blocks, D4); every rule below still holds for each of its lines.
 - **Related:** 0083 (module system, ports), 0086 (goals), 0016 (authority resolved server-side), 0158 §2 (a verdict is advisory, never self-executing), 0162 (review gates retired — no human approval in the land path), 0197 (the ui-design module)
 
 ## Context

package/docs/adr/0341-the-page-is-the-unit-of-tweak-mode.md

@@ -0,0 +1,211 @@
+# ADR 0341 — The page is the unit of Tweak Mode: one tweak task per page round, its status derived from the ledger
+
+- **Status:** Accepted (the owner's decisions written down; the builder's picks for the gaps are listed in "Decided by the builder, owner to confirm")
+- **Date:** 2026-09-27
+- **Task:** [task 1004332](https://cloudbongos.com/builders#/task/1004332) (BV2.TW03, goal 1000095, working area 6). Spec: [`docs/specs/<redacted>.md`](../specs/<redacted>.md). Master design: [`docs/design/mocks/tweak-mode/`](../design/mocks/tweak-mode/README.md).
+- **Deciders:** the owner, Masterqua (area owner), at the planning session of 2026-09-27 (meta task 1004312): the interview, then the prototype review. This ADR adds no decision the spec did not make, except the gaps listed at the end.
+- **Amends:** [ADR 0233](0233-a-copy-proposal-is-a-task-carrying-a-patch.md) — a proposal was one occurrence; a page batch is every line of one page (§4 below). 0233's rules all still hold.
+- **Replaces:** the `artist-review-on-ship` rule of [ADR 0242](0242-a-cascade-is-a-declaration-table-on-the-event-that-already-exists.md)'s cascade table (§9). The runner and the removal rule stay.
+- **Reconciles:** [ADR 0241](0241-the-artist-gate-is-a-per-project-deploy-gate-that-reads-a-state.md) and [ADR 0162](0162-review-gates-retired-rank-consistent-ci-only.md) — the approval hold on a page tweak (§7).
+- **Builds on:** the page inventory (task 1004314: `docs/page-inventory.json`, page id `<surface>:<page>`), [ADR 0178](0178-the-copy-desk-flag-and-queue.md) (the flag), [ADR 0172 per-craft compensation](0172-per-craft-compensation-ideator-credit-lane.md) (a craft's own credit lane), [ADR 0185](0185-spark-handoff-credit-split.md) (payees resolved server-side), [ADR 0096](0096-require-reward-before-workable.md) (a workable task carries a reward), [ADR 0120](0120-pay-on-land-and-builder-owned-rebase-gate.md) (pay on land).
+
+## Context
+
+An artist today reviews one ship at a time. The cascade files an "Artist review" task on every ship that touches copy or visuals. Of the 41 it filed, 34 were abandoned (33 with no note), 5 shipped and 2 sit in backlog. The owner's answer is Tweak Mode: the artist takes a whole page, rewrites every word of it as one document, submits, and a session applies it. The artist approves the rendered result before it ships, and every page carries a status, a count, a changelog and a changed-since marker.
+
+The spec records sixteen decisions. The tasks that build them (TW04 to TW16) each need the same model underneath: what a tweak task is, where the words rest while they are being written, what state a page is in, and who is paid. This ADR is that model, so no later task has to decide it again.
+
+## Decision
+
+### D1. The page is the unit, and its id comes from the page inventory
+
+Every Tweak Mode record keys on a **page id** from `docs/page-inventory.json` (`builders:studio`, `landing:index`, `status:explore`, …). The route layer validates a page id against the inventory and refuses an unknown one with `unknown_page`. Surfaces and their sizes (the M in "N of M") come from the same file.
+
+The server reads the inventory at runtime, so it must reach instances. **The task that first reads it on a server path (TW05) adds `docs/page-inventory.json`, and the page readings (D3), to the publish manifest**, the copy-registry precedent (ADR 0178).
+
+### D2. One tweak task per page round; the task is the record
+
+A **page tweak task** is an ordinary GDS task created by the claim route (D5):
+
+| Field | Value |
+|---|---|
+| `source` | `page-tweak` |
+| `source_ref` | `page-tweak/<page_id>/r<n>`, where n is one plus the number of earlier page-tweak tasks for that page, whatever their status. It never repeats, so `POST /tasks`'s source-ref dedupe cannot hand back an old round. |
+| `title` | `Tweak: <inventory title> (<page_id>)`, for example `Tweak: Home (landing:index)` |
+| `kind` / `discipline` | `feature` / `artist` |
+| `credits_reward` | `30`, the value every shipped artist review carried (§10). It also satisfies ADR 0096's reward gate. |
+| `requires_rank` | none. An artist is a craft, not a rank (ADR 0178 §4, ADR 0233 §7). |
+| version, goal | the version being built, and its catch-all goal (`allowCatchAll`), exactly as a copy proposal lands (`proposals.resolveTargetVersion`; `no_open_version` if nothing is being built) |
+| `touches` | the page's `files` from the inventory |
+
+**One open round per page.** A round is open until its task is `shipped` or `abandoned`. Finding or creating it and claiming it run in one transaction under `pg_advisory_xact_lock(hashtext('page-tweak/' || page_id))`, so two artists cannot both open a round.
+
+### D3. The page reading is a committed, generated artifact
+
+TW04's page reader writes **`docs/page-readings.json`**, generated and committed, the same family as the inventory and the copy registry. For each inventory page it lists the page's visible lines in page order, grouped by section (a page's default state; other states may add lines). Each line carries:
+
+- `key`: `L0001`, `L0002`, … in page order. It is stable only within one reading, and the reading's hash says which one.
+- `section`, `text` (with `{…}` holes, the registry's own convention);
+- `placement`: `placed` (with `file`, `line`, `string_id` from `docs/copy-registry.json`), `shared` (shared-shell text such as the top bar and footer: the planning session's meaning of "same UI element") or `unplaced` (a string the registry cannot place).
+
+Each page also carries `reading_hash`, over its non-shared lines, and `files_hash`, over the contents of its inventory `files`. Freshness is checked cheaply: a page whose `files_hash` no longer matches is stale, and ship-check names the command that re-reads it. **No browser is launched inside ship-check or fitness.** The re-read is the reader's own command.
+
+### D4. The draft and the batch live on the task (amends ADR 0233)
+
+ADR 0233 §2 stands: the words rest in a task description, never in a table, and nothing renders a task description as product copy. A page adds three fenced blocks. Each has one writer and one parser, in a pure file `modules/copy-desk/pages.js` (the `proposals.js` rules: no fs, no DB, no network):
+
+- **```` ```page-tweak-draft ```` — the draft, while the artist writes.** `{ schema: 1, page_id, reading_hash, saved_at, lines: [{ key, section, before, after, placement }] }`. Only changed lines are stored. Autosave replaces the block in place. Only the holder of the page's writing claim (D5) may save.
+- **```` ```page-tweak ```` — the batch, frozen at submit.** `{ schema: 1, page_id, reading_hash, submitted_at, lines: [{ key, section, before, after, placement, file, line, string_id }], unplaced_tasks: [task ids] }`. **Targets are resolved server-side from the current reading at submit, never from the request body** (0233 §7). A draft line whose `before` is no longer on the page is a named refusal, `target_gone`, on that line. Placeholder arithmetic (0233 §4) is checked per line at submit and again at apply.
+- **```` ```page-tweak-applied ```` — written by the applying session (TW11).** `{ schema: 1, page_id, applied_at, reading_hash_after, lines_after: [text…], refused: [{ key, code }] }`, read from the regenerated `docs/page-readings.json` on the applier's branch. `lines_after` is the baseline that drift is measured from (D8).
+- **```` ```page-tweak-sent-back ```` — one per send-back (D7).** `{ at, by, note }`, appended and never replaced.
+
+**Unplaced lines** (spec decision 7): a rewrite of an `unplaced` line is taken out of the batch at submit. It files its own engineer task (`source: page-tweak-unplaced`, `source_ref: page-tweak-unplaced/<tweak task id>/<key>`, `backlog`, `discipline: engineer`) carrying the page, the line and the wording, and the page does not wait for it.
+
+**Shared lines** are editable and travel in the batch like placed lines. They carry the margin note "changes this on every page" (TW10). A shared edit counts toward the page it was made on.
+
+`copy-apply.js --batch` (TW11) applies every line of a `page-tweak` block using 0233's own rules: it re-derives each span, puts the `${expr}` holes back, and refuses by name (`target_gone`, `ambiguous_target`, `no_exact_span`, `placeholder_mismatch`, `path_outside_surface`). A refused line is listed in `refused`, never skipped silently. The batch lands with the lines that applied, and a refused line is shown to the artist at approval.
+
+`modules/copy-desk/tests/copy_no_cms.mjs` **stays green by being amended in a reviewed diff**, which is what it exists for. Its write-verb list grows by exactly the routes in D11. Its migration list grows by `copy_desk_002_page_asks.sql` (D6). Its text-column list grows by `page_id`. `pages.js` joins `proposals.js` under the purity test. Nothing in the module's request path may require `copy-apply.js`.
+
+### D5. The claim: artists claim, anyone asks
+
+**Who may claim:** a builder whose craft includes artist (`builders.preferred_disciplines` contains `artist`, read server-side through the same reader `help-requests` uses, never from the request). Anyone else gets `not_an_artist` and is offered the ask.
+
+**The claim** (`POST /copy-desk/pages/:pageId/claim`) finds the page's open round or creates it (D2) and takes a **web claim** on it: `bind_session=false`, no worktree, the kind of claim that migration core_204 already allows to coexist. The task goes to `active`. If another builder holds the round, the claim is refused with `page_held` and names the holder. If the caller already holds it, the claim returns the round (that is Resume). If the round is an unheld draft (released without submitting), the claim takes it over and the draft stays.
+
+**"Take next"** is this same claim, on the page id the recommendation returned (D8), in one call.
+
+### D6. A page ask is a flag with a page scope
+
+A **page ask** (spec decision 9) is a row in the existing `copy_desk_flags` table, widened by `modules/copy-desk/migrations/copy_desk_002_page_asks.sql`. It is the copy-desk module's own table, so this is a module migration. `scope` gains `'page'`, a nullable `page_id text` is added, and the target check becomes: `string_id` is present exactly for `'string'` scope, and `page_id` exactly for `'page'` scope. The reason floor (`length(btrim(reason)) >= 10`) and the open, resolved and dismissed lifecycle are the flag's own. No column can hold replacement text (ADR 0178 §3 still holds).
+
+- **Anyone may ask, at any rank** (`POST /copy-desk/pages/:pageId/asks`). A second open ask by the same builder on the same page returns the first one.
+- An open ask is **resolved when the page's next tweak ships**, with `resolved_task_id` set to that tweak task. It is never auto-dismissed.
+- "N people asked for it" counts the distinct `flagged_by` values among open page asks.
+- Existing string and surface flags are kept and deleted by nothing. They do not count as asks.
+
+### D7. The round's states, and approve and send-back
+
+A round's state is **derived** from its task and never stored:
+
+| State | Derived from |
+|---|---|
+| `writing` | `active`, with a web claim held (by the artist) |
+| `draft` | `ready`, a `page-tweak-draft` block present and no `page-tweak` block: an unheld draft that any artist may resume |
+| `submitted` | `ready`, with a `page-tweak` block, and no `page-tweak-applied` block newer than the latest send-back: the `/tweak` queue |
+| `applying` | `active`, with a CLI claim held (a worktree). A failed grade stays here, and the applier recovers it the ordinary way. |
+| `waiting_for_artist` | `completed`, with the latest grade **passed** and the task a page tweak: the Approval queue |
+| `landing` | `confirmed` |
+| (closed) | `shipped` (the page's count goes up) or `abandoned` |
+
+**The hold.** When a page-tweak task's grade passes, `applyGrade` records the grade but **does not promote `completed` to `confirmed`**. The task waits at `completed`. `ship.js` publishes the branch and its PR on that held pass (a grade-parked ship otherwise never publishes, and a later confirm would strand at `no_branch_no_tip`). It then prints that the page is waiting for the artist and exits. Readers that treat `completed` as a failed grade (strand-watch, `/grade-recover`, the board) must tell the two apart by the passed grade.
+
+**Approve** (`POST /copy-desk/pages/:pageId/approve`, through the lifecycle port) performs the promotion the grade withheld: `completed` to `confirmed`, with `advanceToMerge`. The server then lands it exactly as it lands any confirmed task. Nothing ships without approval (spec decision 4).
+
+**Send back** (`POST /copy-desk/pages/:pageId/send-back`) requires a note of at least 10 characters. It appends a `page-tweak-sent-back` block, releases the applier's claim, closes the unmerged PR and returns the task to `ready`, so the round reads `submitted` again: "It comes back to the queue once it is re-applied" (the mock). The author may amend the draft while the round waits, and the next applier's claim freezes it again.
+
+Both are new transitions on the lifecycle port (`approveHeldTweak`, `sendBackHeldTweak`), owned by lifecycle because it owns the state machine. Copy-desk calls them through the port and never writes `tasks.status` itself.
+
+**Why this hold is admissible under ADRs 0162 and 0241.** It passes ADR 0241's admissibility test. It is evaluated from state (a passed grade on a page-tweak task). It is the same for every builder. It has a named escape hatch: the project owner may approve through the existing override-request path, recorded and audit-logged. And it holds only work whose substance is the artist's own words: the applier transcribed a page the artist wrote, and the artist confirms the transcription. It is not a gate on a builder's own work.
+
+### D8. Status, count, changelog, drift and the recommendation are all derived
+
+**No status table** (planning decision). Everything below is a read over page-tweak tasks, their fenced blocks, `docs/page-readings.json` and the inventory.
+
+- **Count per page:** the number of shipped page-tweak tasks for that page id. **Text count:** those whose batch changed text, which is every one while Tweak Mode is text only. **UI count:** those whose batch has `kind: 'ui'`. The field is reserved for visual tweaks, is absent today, and so reads 0.
+- **Status per page:** `Untweaked` (count 0), `Text tweaked`, `UI tweaked`, or `Both`, shown with the count ("Text tweaked 2x").
+- **Changelog:** one entry per shipped round: the artist (the payee, §10), `shipped_at`, the line count, and before and after per line, from the `page-tweak` block.
+- **Drift, "changed since last tweak"** (spec decision 8): the page's current non-shared reading lines, compared as a multiset of texts with `lines_after` of its latest shipped round. The lines that differ are the changed-since lines ("4 lines changed since your last pass"). The ships that changed them are the shipped tasks since that round whose `touches` meet the page's files. A tweaked page keeps its count while it drifts.
+- **Artist Review Status, per surface:** "N of M tweaked". N is the surface's pages with count ≥ 1, and M is its pages in the inventory. Drift does not lower N. Surfaces are listed landing, builders hall, status (the mock's order).
+- **The artist's tally:** credits is the sum of the artist's `tweak.page_approved:` credit rows (§10). Pages tweaked is the number of shipped rounds they authored. This week is those credits booked in the trailing seven days.
+- **The recommendation** (TW07): candidates are inventory pages with no open round held or in flight by someone else. A page the caller holds is Resume, not a recommendation. The tiers, in this order: **asked for** (by distinct askers, most first, then the oldest open ask), then **changed since the last tweak** (most changed lines first), then **untweaked** (surface order landing, builders, status, then inventory order). Tweaked pages with no drift come last. Each candidate carries its why ("2 people asked for it", "4 lines changed since your last pass", "untweaked"). The first is the recommendation, and the next few are "pick another".
+
+### D9. The artist-review cascade is replaced, not moved
+
+The `artist-review-on-ship` entry is **removed** from `CASCADES` in `modules/lifecycle/cascade.js` (TW14). The runner, the removal rule and the idea cascades stay. **A ship that changes a page's words then writes nothing.** Drift is derived (D8), so a changed page reads "changed since last tweak" and rises in the recommendation on its own. `hasCopyOrVisualWork` stays exported, because the grader's advisory reader lens is scoped by it (ADR 0298). The two artist review tasks already in backlog stay as ordinary work, and no data is deleted. Task 1004078 is merged into TW14, since with no review cards it has nothing left to fix.
+
+### D10. What the reviews paid, and what an approved page pays
+
+**What the reviews paid, from the ledger.** An artist review task was an ordinary task: `kind: unclassified` (×1.0 in `KIND_MULTIPLIERS`) and `credits_reward: 30` (all five shipped reviews carried 30, set at triage). It paid through the two ordinary streams (ADR 0054, ADR 0146):
+
+1. The **per-task estimate**, `credits_reward × kind multiplier` = 30, to the shipper on land (`awardLandingCredit`). This is **withheld under `cost-plus-only`, which is this instance's mode**, so all five shipped reviews show `credits_awarded: 0`.
+2. The **cost-plus session reward**, `round(true_cost_usd × 1.20)`, to whichever session shipped it.
+
+An artist working in the studio runs no session, so stream 2 can never reach them. Paying "what the reviews paid" literally on this instance would pay a studio artist nothing.
+
+**The rule.** An approved page pays its artist the review's priced value, **`credits_reward × KIND_MULTIPLIERS[kind]`, which is 30 credits for a `feature` round at 30**. It is booked on its own **artist credit lane** (the ADR 0172 per-craft precedent): a policy key `reward.artistCredit`, default true, not suppressed by `cost-plus-only`, just as the ideator lane is not.
+
+- **When:** at the land (the `shipped` transition), inside the lifecycle's ship transaction through the `reward` port (ADR 0120: pay on land).
+- **Payee, resolved server-side** (ADR 0185): the builder whose web claim on the task was released by the submit that froze the shipped batch, read from the `claims` table. Never the caller, and never a field in the description, which the task's editors could change.
+- **Reason key:** `tweak.page_approved:<task id>`, idempotent per (builder, reason).
+- **The applier keeps its normal build reward** (the cost-plus session reward, on land, unchanged). **The shipper's per-task estimate is not paid on a page-tweak task**, because the artist lane takes that stream, so the total is conserved in both reward modes.
+- **Self-applied** (the artist also ran `/tweak`): one artist row plus their own session reward. Nothing is doubled.
+- The tally (D8) reads these rows.
+
+### D11. The routes, in one place
+
+All are on the copy-desk module (it `consumes: ["lifecycle"]`; no new port is provided). Reads first, then writes:
+
+| Route | Task | What |
+|---|---|---|
+| `GET /copy-desk/pages` | TW05 | every page's status, count and drift, plus the per-surface rollup |
+| `GET /copy-desk/pages/:pageId` | TW05 | one page: status, changelog, changed-since lines, the open round and its state |
+| `GET /copy-desk/tally` | TW05 | the caller's tally |
+| `GET /copy-desk/next` | TW07 | the recommendation and the alternatives |
+| `GET /copy-desk/pages/:pageId/draft.docx` | TW09 | the download |
+| `POST /copy-desk/pages/:pageId/claim` | TW06 | claim, resume, take next |
+| `POST /copy-desk/pages/:pageId/asks` | TW06 | ask for a page |
+| `PUT /copy-desk/pages/:pageId/draft` | TW08 | autosave (the holder only) |
+| `POST /copy-desk/pages/:pageId/draft.docx` | TW09 | the upload, merged into the draft |
+| `POST /copy-desk/pages/:pageId/submit` | TW08 | freeze and queue |
+| `POST /copy-desk/pages/:pageId/approve` | TW12 | the held pass goes on to land |
+| `POST /copy-desk/pages/:pageId/send-back` | TW12 | back to the queue with a note |
+
+The lifecycle port gains what these need: `updateTaskDescription`, `webClaimTask`, `releaseClaim`, `approveHeldTweak` and `sendBackHeldTweak`. Each lands with the task that first calls it.
+
+### D12. The Word round trip
+
+**Download** renders the draft over the page reading as a `.docx` with **no new dependency**. A .docx is a zip, and a small writer and reader on `node:zlib` in `modules/copy-desk/docx.js` (pure over Buffers) is the cheapest viable option (spec: no paid service). The file holds:
+
+- the page title as the title, and each section as a Heading 2;
+- one paragraph per line, in page order, showing the draft's `after` (or the current text if the line is unchanged). Each paragraph is wrapped in a plain-text content control (`w:sdt`) tagged with the line's `key`;
+- `shared` and `unplaced` lines shown in their own paragraph style with a Word comment ("changes this on every page", "goes to an engineer");
+- custom document properties carrying `page_id` and `reading_hash`.
+
+**Upload** maps paragraphs back to lines **by tag**. If the editor stripped the tags, it maps by position, with the same section headings and the same number of lines per section. The changed texts merge into the draft (never straight to the site), and the merge is shown to the artist in the editor. The upload is refused, with the lines named, when:
+
+- `structure_changed`: lines were **added** (untagged or surplus paragraphs), **dropped** (a key missing) or **reordered** (the keys out of page order), or a section heading changed. The refusal lists each moved line by section and its first words;
+- `wrong_page`: the file's `page_id` is not the page;
+- `reading_moved`: the file's `reading_hash` is not the draft's, because the page changed since the download. The artist is asked to download again, so no stale line is merged by position.
+
+## Decided by the builder, owner to confirm
+
+The spec does not answer these. Each is the choice most faithful to it, and each is a small change here if the owner rules otherwise. (The TW03 task text said a gap should become a blocker. The owner's overnight rule for this chain says to pick and list, so they are listed rather than filed.)
+
+1. **The artist's pay on this instance** (D10): 30 credits per approved page on a new artist lane that `cost-plus-only` does not suppress. The literal reading, the reviews' stream as it actually paid here, is zero for a studio artist.
+2. **The hold sits on `completed` with a passed grade**, not on a new task status (D7). A new status would touch every reader of the state machine.
+3. **Who approves:** the author, or any other artist-craft builder (so an absent author does not strand a page), with the project owner's override as the escape hatch.
+4. **Send-back returns the round to the apply queue**, the mock's words, and the author may amend the draft while it waits. The applier's sent-back session is unpaid, because its ship never lands (pay on land).
+5. **Page asks widen `copy_desk_flags`** rather than adding a table (D6), and open string flags do not count as asks.
+6. **Shared-shell lines are editable in a page's batch** and count toward that page (D4).
+7. **Drift excludes shared lines**, so a shell change does not mark all 30 hall pages changed (D8).
+8. **Recommendation ties and order** (D8). The mock's sample list puts an untweaked page before a changed one. The spec's order (asked, changed, untweaked) wins, and the mock's list is sample data.
+9. **The Approval queue shows the renders `/tweak` attached**, images of the applied branch, never a DOM built from the batch. That keeps ADR 0233's "nothing renders a task description as product copy" true. The renders need named slots on task visuals (TW11). Today there is one image per task.
+10. **Round numbering and titles** (D2), the **one-open-round lock** (D2), and **no rank floor** on a tweak task.
+11. **The Word file's shape** (D12): content-control tags, and refusing on `reading_moved` rather than merging by position.
+12. **The readings ship with the core** and are refreshed by `files_hash`, with no browser in ship-check (D1, D3).
+
+## Consequences
+
+- TW04 to TW16 are cut against this ADR. Each task's description names the sections that govern it.
+- `copy_no_cms.mjs` changes in reviewed diffs (TW06, TW08, TW09, TW12), and each diff has to justify what it adds to the lists.
+- The artist gate (ADR 0241) holds nothing new. With the cascade gone, `strict` would hold a deploy only on the two review tasks still in backlog. The gate is `off` for now (spec decision 13). Task 1004107 stays open for when it returns.
+- Strand and recovery tools learn one new fact: `completed` with a passed grade on a page tweak is waiting for the artist, not a failure.
+
+## Rejected
+
+- **A page status table.** The planning session ruled it out. A table would be a second record of what the task ledger already says.
+- **A `copy_desk_drafts` table.** ADR 0178's forbidden column with extra steps (0233 §2).
+- **Keeping the per-ship review beside Tweak Mode.** Spec decision 10: it is replaced.
+- **Letting the artist's approval gate any ship other than a page tweak.** ADR 0241's reason still holds.
+- **A paid .docx service or a heavy library.** The format is a zip of XML, and node already reads zips.

package/docs/adr/README.md

@@ -432,3 +432,4 @@ This keeps the decision history honest and traceable.
 | 0338 | [**Modules travel through a Bongos-hosted store, and an acquired module keeps working forever** ([task 1003782](https://cloudbongos.com/builders#/task/1003782), goal 1000091 — working area 5, owner Will). A module had no transport of its own: it reached an instance only inside the core (ADR 0107 §6) or in the instance's repo. Weighed npm packages, a Bongos-hosted store and git refs against the four things area 5's criteria require — entitlement before install, a per-version score, a tester channel, and a delist that stops distribution. npm and git refs fail entitlement and delist by construction. **D1:** Cloud Bongos hosts the store; a module version is a tarball + hash manifest in the same format `package-core.js` already emits (same `isPublishable()` gate), registry rows on the control-plane DB, artifacts in the already-paid DO Spaces bucket, served by the control plane only after an entitlement + channel check; free modules take the same path at price zero; install/update verify hashes on arrival; modules' own npm deps still travel via npm (ADR 0138). No new fixed cost. **D2 (owner):** delisting, author withdrawal or deletion removes a module from the catalog and stops new acquisitions and updates, but **an acquired module keeps working forever** — the store never disables or removes an installed copy and a delist never revokes an entitlement; the holder is told no more updates will come. Security issues are not a special case; a remote kill switch would need a superseding ADR. Rejected: npm, git refs, remote disable on delist.](0338-modules-travel-through-a-bongos-hosted-store.md) | modules / distribution / economy |
 | 0339 | [**A project's owner upgrades it, and a hosted project hands off to the hub's door** ([task 1004174](https://cloudbongos.com/builders#/task/1004174), goal 1000090 — the owner's ruling of 2026-09-26 that only a project's owner upgrades it). Amends ADR 0293 D5. **D1:** the deploy door's preview and move routes admit the OWNER of a tenant row (`co-tenant`/`cloud-host`) for that row, asked first; every other caller meets the unmodified `core.pin.move` gate, so a non-owner's refusal is unchanged whether or not the id exists and the widening can only admit. **D2:** the platform's own row stays atom-only. **D3:** `GET /core-update` names `<hub>/deploy?project=<slug>` on a federated project, and the hosted hall's banner and rail hand off there (the dead local Deploy item is gone); the hub's `/deploy` shell admits a project owner through `alsoAdmits: 'isProjectOwner'`. **D4:** the intent's actor records the door (`api:owner:<id>` / `api:archon:<id>`), both attributed on the `core_upgrades` ledger. Rejected: a tenant-side API that performs the upgrade, granting the system atom to owners, owners moving the platform row. ADR 0328 Phase 1 (task 1004159) should fold this gate into `requireProjectOwner`.](0339-a-projects-owner-upgrades-it-and-a-hosted-project-hands-off-to-the-hub-door.md) | provisioning / deploy door / permissions |
 | 0340 | [**Every hall takes its update from Settings, and /deploy is the platform hall's page** ([task 1004296](https://cloudbongos.com/builders#/task/1004296), goal 1000090 — the owner's 2026-09-25 asks: a Settings version panel "just like iOS", and /deploy only in the Bongos hall). Amends ADR 0339 D3 and the reach of ADR 0293's page. **D1:** Settings → Software update in the core — the running core, the newest release the runner's own channel rule allows, and what each version in between carries from the newest package's release notes; every signed-in builder reads it, and "up to date" is said only from an answer. **D2:** its Update button leads to the door (local /deploy, the hub's /deploy?project=, or a `bongos upgrade` sentence), drawn only for holders of core.pin.move. **D3:** /deploy 302s to Settings on a hall without the provisioning module. **D4:** the banner links Settings everywhere but the platform; the rail is no longer re-pointed; /core-update drops deploy_url. **D5:** the registry reader moved into the core (module-api readPackageRegistry). Rejected: a second copy of the two-step door, gating the panel on the atom, a "moved" page.](0340-every-hall-takes-its-update-from-settings-and-deploy-is-the-platform-halls-page.md) | deploy door / settings / core update |
+| 0341 | [**The page is the unit of Tweak Mode: one tweak task per page round, its status derived from the ledger** ([task 1004332](https://cloudbongos.com/builders#/task/1004332), goal 1000095 — BV2.TW03, the owner's Tweak Mode decisions of 2026-09-27 written down). Amends ADR 0233 (a proposal becomes a page batch); replaces the artist-review-on-ship cascade rule. **D1-D3:** every record keys on a page id from docs/page-inventory.json; a round is a `page-tweak` task (`source_ref page-tweak/<page>/r<n>`, 30c, catch-all goal, one open round per page under an advisory lock); TW04 commits docs/page-readings.json (line keys, placed/shared/unplaced, reading and files hashes, no browser in ship-check). **D4:** the draft, the frozen batch, the apply record and each send-back are fenced blocks on the task, parsed by a pure pages.js; unplaced rewrites file their own engineer task; copy_no_cms.mjs grows in reviewed diffs. **D5-D6:** artist-craft builders claim with a web claim; anyone asks, and a page ask is a copy_desk_flags row with scope page. **D7:** round states are derived; a passed grade on a page tweak holds at completed until the artist approves (the confirm) or sends it back to the apply queue, with the owner override as the escape hatch. **D8:** count, status, changelog, drift (against the last round's lines_after), N of M per surface, the tally and the recommendation order are all reads. **D9:** the cascade rule is removed; hasCopyOrVisualWork stays for the reader lens. **D10:** the reviews paid 30c per task on the estimate stream (withheld under cost-plus-only) plus the session's cost-plus; an approved page pays its artist 30c on a new artist lane that cost-plus-only does not suppress, payee from the claims table, applier keeps its session reward. **D11-D12:** the route table; a dependency-free .docx with content-control line tags, refused as structure_changed, wrong_page or reading_moved. Twelve builder picks are listed for the owner to confirm.](0341-the-page-is-the-unit-of-tweak-mode.md) | copy desk / artist loop / economy |

package/docs/module-api-changelog.md

@@ -2597,5 +2597,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.1053 with no explicit bump. run 36378326588. (task 1002620)
   1.19.1055 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.1054 with no explicit bump. run 36380323033. (task 1002620)
+  1.19.1056 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1055 with no explicit bump. run 36382270561. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

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

@@ -7631,5 +7631,11 @@
       "id": "1004314",
       "text": "Every page the project serves now has a name that stays put. A new generated list names all 37 pages across the builders hall (30), the landing site (5) and the status site (2). Each entry gives the page a short id such as bui"
     }
+  ],
+  "1.19.1056": [
+    {
+      "id": "1004332",
+      "text": "Tweak Mode now has one written plan that every later step builds on. It says how a page is taken, where the artist's words rest while they write, how a page shows as tweaked or changed since, how the Word download and upload w"
+    }
   ]
 }

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.1055'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1056'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');