Merge commit 'a1934a1498ec91688b6245d5b05b1cdf66d5c98a' into gsta-96-preamble-hoist

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

docs/ADDING_A_HOST.md

@@ -459,6 +459,7 @@ Key fields:
 | `suppressedResolvers` | Resolver functions that return empty for this host |
 | `coAuthorTrailer` | Git co-author string for commits |
 | `boundaryInstruction` | Anti-prompt-injection warning for cross-model invocations |
+| `transcripts` | Optional `{ root, layout }`: where the host keeps its own chat transcripts on disk and how this workspace's files are told apart, rendered by `/context-restore`'s no-checkpoint fallback (`{{TRANSCRIPT_SOURCES}}`, `{{TRANSCRIPT_DISCOVERY}}`); a declared store also needs a discovery body in `scripts/resolvers/transcripts.ts`. Absent: the host declares no transcript store. |
 
 ## Validation
 

docs/CHANGELOG_STYLE.md

@@ -62,6 +62,9 @@ the user gets; the path to that system is invisible to them.
 **When to write the CHANGELOG entry:**
 - At `/ship` time (Step 13), not during development or mid-branch.
 - The entry covers ALL commits on this branch vs the base branch.
+- `/ship` lints the lines the branch added with `bin/gstack-prose-lint CHANGELOG.md --base origin/<base> --gate`,
+  and the Quality gate workflow gates the `## [Unreleased]` block the same way. Rewrite each `PROSE:` line
+  it names ([docs/troubleshooting.md](troubleshooting.md#prose-lint-found)).
 - Never fold new work into an existing CHANGELOG entry from a prior version that
   already landed on main. If main has v0.10.0.0 and your branch adds features,
   bump to v0.10.1.0 with a new entry — don't edit the v0.10.0.0 entry.

docs/PROJECT_STRUCTURE.md

@@ -97,7 +97,7 @@ gstack/
 ├── docs/designs/    # Design documents (incl. IMPECCABLE_INTEROP.md = the design detector / catalog / open DESIGN.md record, and fork-port-residual-2026-09/ evaluation evidence)
 ├── setup-deploy/    # /setup-deploy skill (one-time deploy config)
 ├── .github/         # CI workflows + shared composite actions (.github/actions/) + Docker image (claude CLI pinned)
-│   ├── workflows/   # evals.yml (E2E on Ubicloud), quality-gate.yml (secret scan), dependency-review.yml, osv-scanner.yml, skill-docs.yml, actionlint.yml, plus free-tests, Windows, periodic and marathon evals, CSO release, platform qualification and smaller gates
+│   ├── workflows/   # evals.yml (E2E on Ubicloud), quality-gate.yml (secret scan, CHANGELOG prose lint), dependency-review.yml, osv-scanner.yml, skill-docs.yml, actionlint.yml, plus free-tests, Windows, periodic and marathon evals, CSO release, platform qualification and smaller gates
 │   └── docker/      # Dockerfile.ci (pre-baked toolchain + Playwright/Chromium)
 ├── contrib/         # Contributor-only tools (never installed for users)
 │   └── add-host/    # /gstack-contrib-add-host skill
@@ -105,7 +105,7 @@ gstack/
 ├── SKILL.md         # Generated from SKILL.md.tmpl (don't edit directly)
 ├── SKILL.md.tmpl    # Template: edit this, run gen:skill-docs
 ├── ETHOS.md         # Builder philosophy (Boil the Ocean, Search Before Building)
-├── NOTICE.md        # Third-party notices: material derived from impeccable and the DESIGN.md spec (Apache-2.0), Elaya's design skills and hallmark's sloplint (MIT)
+├── NOTICE.md        # Third-party notices: material derived from impeccable and the DESIGN.md spec (Apache-2.0), Elaya's design skills and hallmark's sloplint (MIT), plus courtesy entries for tstack and pstack ideas and word lists (MIT; no license text carried)
 ├── licenses/        # Verbatim license texts for the notices above (Apache-2.0.txt, MIT-elaya.txt, MIT-hallmark.txt)
 └── package.json     # Build scripts for browse
 ```

docs/captain.md

@@ -165,7 +165,7 @@ a push included. The sequence that works unattended on Capy:
    to the current tree.
 6. Docs audit: snapshot the documentation candidates read-only and record the vetted
    section.
-7. Body and receipt: compose the PR body (What changed, Why, Approvals first on Capy),
+7. Body and receipt: compose the PR body (What changed, Why, Blast radius, Approvals first on Capy),
    write the ship receipt into it, post body and title.
 8. Terminal line: `gstack-ship-receipt result --pr <n>` prints
    `GSTACK_RESULT: skill=ship status=complete`.

docs/capy-install.md

@@ -490,7 +490,7 @@ thread asks its Captain, otherwise the person), plan approvals are rendered
 with `gstack-owner-brief render --captain`, answers are recorded with
 `gstack-approvals` (mirrored to the Captain's drive `approvals/` directory when the
 Captain created one, so the crew can read every lane's record), and /ship's PR body opens
-with before/after images (`gstack-pr-shots`), Why and Approvals. Every autoplan gate
+with before/after images (`gstack-pr-shots`), Why, Blast radius and Approvals. Every autoplan gate
 prints its cost (`GATE_SPEND:`, `GATE_REC_COST:`; `autoplan/DRIVER.md` says how to relay
 them). The guide is
 [`capy/skill/gstack/captain.md`](../capy/skill/gstack/captain.md);

docs/troubleshooting.md

@@ -4852,6 +4852,40 @@ every flag and code.
 
 **Fix.** Rerun once; if it repeats, report the printed frame to the gstack maintainers.
 
+## Prose lint (gstack-prose-lint)
+
+`bin/gstack-prose-lint` reads the prose /ship is about to publish, a CHANGELOG
+entry (Step 13) and the sections the author writes in the PR body (Step 19:
+`## Why`, `## Summary` and `## Blast radius`, through `--sections`; the
+`## What changed` captions and image text stay a report), and the quality-gate
+workflow runs it over `CHANGELOG.md`'s `[Unreleased]` block. It decides only
+what a regular expression can: autopilot vocabulary, "not just X, but Y",
+metaphor nouns, a colon used as a conjunction, a bold label that restates its
+line, an arrow or a dropped article standing in for a sentence, and a fence or
+HTML comment left open (`unclosed-block`), because nothing after it was read.
+Fenced code, inline code, URLs, HTML comments and quoted words are never read,
+so the problem quoted in `## Why` is the person's to phrase. Everywhere else (a
+template, a doc, this file) it is a report: run it, read it, keep your em dashes.
+
+<a id="prose-lint-found"></a>
+### `PROSE_LINT_FOUND`
+
+**Meaning.** A gated run (`--gate`) found at least one tell in the text it was
+given. Each `PROSE: <file>:<line> <rule> "<match>" (<hint>)` line above the
+trailer names the rule and what to write instead; `PROSE_LINT: found=<n>` counts
+them. With `--unreleased` only the `## [Unreleased]` block was read; with
+`--base <ref>` only the lines the working tree added since the merge base; with
+`--sections <a,b>` only the text under those `## ` headings (under `--gate`, a
+file with none of them is exit 2, not a pass: the draft lost a heading).
+
+**Fix.** Rewrite each named line in the draft the way its hint says (a measurement
+such as `1.6740 → 1.7010` and the `before → after` heading are not findings), then
+rerun the same command. The PR body's verbatim tool sections (the approvals
+table, issue links, review findings, the coverage diagram) are outside
+`--sections` and are never read, so a finding there means the compose block was
+edited: restore its `--sections` list. A rule that keeps flagging correct prose
+is a bug in `lib/prose-lint.ts`: file it with the sentence.
+
 ## Quick answers
 
 The short troubleshooting entries that used to live in the README. Each names the symptom and the fix; the sections above cover every gate message in depth.