stitch-flow git:20261008.18e5cf3C

Immutable. This exact content never changes and is served at /api/v1/blob/0e5a5825ed941330.

<!-- Copyright (c) 2026 Petar Djukic. All rights reserved. SPDX-License-Identifier: MIT -->
---
name: stitch-flow
description: >-
  Repair discourse flow across paragraph boundaries after say-per-paragraph
  drafting: locate joints where a paragraph opens with a freestanding thesis
  instead of taking a handoff from the previous paragraph's close, then
  rewrite openings only — theme of the opener drawn from the rheme of the
  paragraph before, duplicate definitions merged, rhythm varied — leaving
  claims, citations, anchors, and rst markers untouched. Ships openers.py,
  which prints each section's joint chain with weak-joint and
  duplicate-definition flags. Triggers: stitch the flow, the paragraphs
  don't flow, written paragraph by paragraph, doesn't read as one piece,
  weak joints, paragraph openers, given-new.
argument-hint: '<chapter.md> [...] (detection); then the stitch pass by hand'
---

# Stitch Flow (discourse joints between paragraphs)

## The failure this fixes

SRD-first drafting writes one say per paragraph, and each say is written to
be complete in itself. The result reads correct and does not flow: nearly
every paragraph opens with a freestanding thesis sentence ("An agent is a
generic runtime." / "A role is a specification." / "Switching roles costs
no release."), takes no handoff from the paragraph before it, and could be
shuffled without breaking the text. Secondary symptoms of the same cause:
uniform paragraph rhythm (definition, elaboration, consequence, three to
five sentences, every time), section cross-references doing the work
transitions should ("the previous section's sense"), and the same thing
defined twice because each paragraph re-establishes its own context.

The failure has shipped twice (agent-dsl; autogenic-systems
roles-and-teams) because every existing gate reads one paragraph at a
time. reverse-outline checks that each satellite serves its section's
nucleus — logical coherence, not flow. tighten-style TS-10/TS-11 govern
the spine inside a paragraph, and its rewriter refuses to add transitions
by contract. Critic panels see passages. And match-structure's
paragraph_cohesion metric — tf-idf overlap between consecutive
paragraphs — scores the disease higher than the cure: the roles-and-teams
article measured 0.16 against 0.08-0.12 for its venue exemplars, because
re-establishing the same nouns in every paragraph is exactly what the
metric rewards. Do not gate this skill on that number.

## Detection

```bash
python3 scripts/openers.py chapter1.md chapter2.md ...
```

Per section, the script prints the joint chain — the last sentence of
paragraph N over the first sentence of paragraph N+1 — and flags:

- **WEAK**: the opener neither shares a content word with the previous
  paragraph's closing two sentences nor starts with a connective,
  demonstrative, or pronoun. A paragraph after an exhibit (table, figure,
  list) starts a fresh chain and is never flagged.
- **DUP**: two definitional sentences ("X is ...") whose content words
  overlap enough to be the same definition stated twice.
- The paragraph word-count spread, as a rhythm check.

The script locates; the reader decides. A hard cut at a genuine turn is
legitimate, and a section's first paragraph owes nothing to the heading.
Read the flagged joints in the full section before touching any of them.

For a judgment layer beyond your own read, run **critic-panel** with
`--roster williams`: the Flow Test persona (Joseph Williams,
cohesion-coherence) verdicts each flagged joint and the section's topic
strings, from a fresh context, before you touch the text.

## The stitch pass

Work one section at a time, with the whole section in view. For each weak
joint the reading confirms:

1. **Rewrite the opening only** — the first sentence, usually its first
   clause. Make the opener's theme the previous paragraph's rheme: the
   thing the last sentence left the reader holding is the thing the next
   sentence picks up. The claim the paragraph states does not change; the
   SRD say constrains content, not openings.
2. **Merge duplicates**: keep the definition at the anchor that governs
   it, and turn the other occurrence into a reference that carries new
   information instead of restating.
3. **Vary the rhythm** where two adjacent paragraphs share the same
   shape: fold a two-sentence satellite into its neighbor, or let one
   paragraph run long where the content carries it.
4. **No adverbial glue.** "Moreover", "Additionally", "In addition" are
   mechanical transitions filter-tells rightly flags; the handoff is
   thematic, not adverbial. If the only available link is an adverb, the
   paragraphs are in the wrong order — consider that before writing.

Never change: claims, numbers, quotations, citations, exhibit content,
anchor comments, rst markers, lock spans. If an opener rewrite makes an
anchor's one-line summary stale, update the anchor with it, in the same
commit.

## Gates after the pass

In order, all required where the repository has them:

1. `rst_markers.py check` per changed file, then the reverse-outline
   re-check of each paragraph against its marker — an opener rewrite must
   not change what the paragraph does for the argument.
2. **cold-review** screen, baseline vs candidate: a stitch pass is a
   rewrite pass, and entailment damage (inverted claims, reattached
   numbers) is exactly what it risks.
3. **filter-tells** on the changed files — the pass adds connective
   openers, which is where mechanical-transition tells would enter.
4. The repository's own build, census, and audit targets.

Re-run openers.py last and expect the weak count to fall, not to zero —
the residue should be the deliberate cuts.

## Boundaries

| Skill | Owns | Does not own |
|---|---|---|
| stitch-flow | the joints between paragraphs; duplicate definitions; rhythm | anything inside a paragraph's body |
| tighten-style | TS-10/TS-11 spine inside a paragraph | transitions (its rewriter refuses them) |
| reverse-outline | nuclearity: what each paragraph does for the argument | whether N+1 picks up where N left off |
| match-voice / humanize | register and diction per passage | discourse structure |
| cold-review | entailment between baseline and candidate | authoring any prose |
| critic-panel (Williams) | verdicts on joints and topic strings | applying anything |

match-structure's paragraph_cohesion cannot gate or measure this skill;
see above. The only trustworthy detector is openers.py plus a human read
of the flagged joints.