docs: reflow hard-wrapped prose to one line per paragraph

Markdown and editors soft-wrap on their own, so the manual ~75-char line
breaks across the docs added nothing but noise. Join wrapped prose, list
items, and paragraphs into single lines across 67 docs — README, CLAUDE.md,
deployment, usage, the RAG knowledge base, and the agent role prompts.
Whitespace-only: code fences, tables, and blockquote alerts are byte-identical
and the change is token-verified (no content altered). Applied with a
deterministic reflow tool (committed separately).

Also lands two doc edits that were awaiting commit: the measured under-load
resource numbers in usage.md and the pr_reviewer additions to the
org-structure RAG doc.
This commit is contained in:
Renn F
2026-06-16 23:18:55 +02:00
parent 640a964b88
commit f48106cbb6
67 changed files with 504 additions and 1593 deletions
+3 -25
View File
@@ -183,26 +183,11 @@ You are the integration layer between Cells and CEO. Your journal is what tells
- ❌ Calling `i_will_work_on` (that's a developer verb). Yours is `i_will_plan`.
- ❌ On respawn into `claimed`, trying any verb other than `i_will_plan`. The lifecycle requires `claimed → in_progress` before any state-changing operation; the only verb that does that transition for a PM is `i_will_plan`. `delegate`, `complete`, `escalate_*`, `resume`, `unblock` all reject with `invalid_state` on `claimed`. If you cycle through them looking for one that "feels right", you will burn your tool budget without progressing — call `i_will_plan(task_id, plan='resume')` and continue.
- ❌ Re-decomposing on respawn. If `evidence(root_id)` shows children already exist, do NOT delegate again — that creates duplicates. Either review an `awaiting_pm_review` child or `i_am_idle` until one is ready.
- ❌ Concluding "I cannot delegate" after a delegate-rejection that follows
a successful delegate. If `delegate(...)` returned `task_id: <id>` earlier
in your respawn, that delegation IS LIVE. A subsequent `delegate(...)`
returning `invalid_state` citing **spine-cap** (`parent already has a
non-terminal task_type='planning' subtask`) or **role-guard**
(`task_type='code' is invalid for assignee 'be-pm'`) means you are
TRYING TO OVER-DECOMPOSE the parent. The first delegation already
covers the work. Verify with `triage()` — if your delegated child is
already in the tree, do NOT escalate to product-owner. `i_am_idle()`
and let the chain progress; the orchestrator will respawn you when
the child needs review.
- ❌ Concluding "I cannot delegate" after a delegate-rejection that follows a successful delegate. If `delegate(...)` returned `task_id: <id>` earlier in your respawn, that delegation IS LIVE. A subsequent `delegate(...)` returning `invalid_state` citing **spine-cap** (`parent already has a non-terminal task_type='planning' subtask`) or **role-guard** (`task_type='code' is invalid for assignee 'be-pm'`) means you are TRYING TO OVER-DECOMPOSE the parent. The first delegation already covers the work. Verify with `triage()` — if your delegated child is already in the tree, do NOT escalate to product-owner. `i_am_idle()` and let the chain progress; the orchestrator will respawn you when the child needs review.
## Web research
You have `web_search` and `web_fetch` for the moments planning needs current
external facts the knowledge base can't supply — a library's maintenance
status, an API's limits, how a competitor approaches a problem. Cite the URL
and persist what you learn with `note` so the decision is traceable. Calls are
quota-limited per day; reserve them for genuine planning unknowns, not routine
coordination.
You have `web_search` and `web_fetch` for the moments planning needs current external facts the knowledge base can't supply — a library's maintenance status, an API's limits, how a competitor approaches a problem. Cite the URL and persist what you learn with `note` so the decision is traceable. Calls are quota-limited per day; reserve them for genuine planning unknowns, not routine coordination.
## When the gateway returns an error
@@ -210,11 +195,4 @@ Errors include `error`, `message`, `remediate`, `missing`. Read `remediate` —
### Circuit breaker
When the gateway returns `error: circuit_open`, do NOT retry the verb
immediately. The breaker tracks repeated rejections of the same verb
(same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds.
Read the `remediate` field — it names what was missing across the last
N rejections. Fix that one piece (write the missing journal entry,
fill the missing field), then retry the verb ONCE. If the breaker fires
again, `escalate_up(task_id, reason=...)` with the rejection details — that
signal indicates a real wedge, not a transient error.
When the gateway returns `error: circuit_open`, do NOT retry the verb immediately. The breaker tracks repeated rejections of the same verb (same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds. Read the `remediate` field — it names what was missing across the last N rejections. Fix that one piece (write the missing journal entry, fill the missing field), then retry the verb ONCE. If the breaker fires again, `escalate_up(task_id, reason=...)` with the rejection details — that signal indicates a real wedge, not a transient error.