ralphctl 0.8.2 → 0.8.4

package/dist/manifest.json

@@ -1,10 +1,12 @@
 {
   "version": 1,
-  "generatedAt": "2026-05-26T13:05:48.855Z",
+  "generatedAt": "2026-05-28T21:15:32.467Z",
   "assets": [
+    "prompts/_partials/conventions-agents-md.md",
+    "prompts/_partials/conventions-claude-md.md",
+    "prompts/_partials/conventions-copilot-instructions.md",
     "prompts/_partials/decisions.md",
     "prompts/_partials/harness-context.md",
-    "prompts/_partials/signals-feedback.md",
     "prompts/_partials/validation-checklist.md",
     "prompts/apply-feedback/template.md",
     "prompts/create-pr/template.md",

package/dist/prompts/_partials/conventions-agents-md.md

@@ -0,0 +1,63 @@
+## AGENTS.md conventions
+
+`AGENTS.md` is the cross-tool agent context file — recognised by OpenAI Codex and increasingly by other
+agent runtimes. It is format-loose: no required heading schema, no hard line cap. Write it as clear
+prose or bullets, organised into named sections, so any agent runtime that loads it can navigate it
+without tool-specific knowledge.
+
+**Structure rules:**
+
+- Open with a brief one- or two-sentence project description (no formal H1 required, though a title
+  heading is fine).
+- Use H2 sections to group related rules — `## Build`, `## Testing`, `## Architecture`, etc.
+- Keep sections short and scannable; avoid walls of prose. Bullets work well.
+- No depth limit on headings, but rarely need more than `##`/`###`.
+- No hard line cap, but keep the file under ~150 lines — longer files dilute the signal-to-noise
+  ratio for models with a limited context window.
+
+**Tone and framing:**
+
+Write `AGENTS.md` as a plain, tool-agnostic specification. Avoid Claude-specific vocabulary
+(`<tool>`, `slash commands`, hooks, `CLAUDE.md` cross-references) and Copilot-specific vocabulary
+(Chat context, `@workspace`). The content should read equally well regardless of which agent runtime
+is consuming it.
+
+**Inclusion test** — include a rule only when an agent would get it wrong without being told. Skip
+anything derivable from the language, the manifest, or the directory structure. Skip generic
+engineering advice the model already follows by default.
+
+**Sample stub** (adapt; do not copy verbatim):
+
+```markdown
+# Project Name
+
+TypeScript monorepo. Use the workspace-aware install command; individual-package installs
+break the shared lockfile.
+
+## Build
+
+- `<build command>` — compiles all packages to `dist/`.
+- Environment: copy `.env.example` to `.env` and fill in required values before running.
+
+## Testing
+
+- `<test command>` — runs unit + integration tests.
+- Integration tests require a running database; start it with `<database start command>`.
+- Do not mock the database layer — use real fixtures from `tests/fixtures/`.
+
+## Architecture
+
+- Clean Architecture: `domain → business → integration → application`. No reverse imports.
+- No barrel files (`index.ts` re-exports) — every import names its symbol explicitly.
+
+## Conventions
+
+- Business operations return a `Result` type — do not throw for domain errors.
+- All file writes go through the atomic-write helper in `business/io/`; direct `fs.writeFile`
+  is banned from business code.
+
+## Security
+
+- Do not log authentication tokens or request bodies, even at debug level.
+- Never commit `.env` files — they contain real credentials for development services.
+```

package/dist/prompts/_partials/conventions-claude-md.md

@@ -0,0 +1,58 @@
+## CLAUDE.md conventions
+
+`CLAUDE.md` is Claude Code's native project context file — loaded automatically from the repository root
+at the start of every session. Write it as a compact reference document an agent re-reads on every
+invocation, not as a tutorial or README.
+
+**Structure rules:**
+
+- Exactly one H1 (`# Project Name`) as the opening line.
+- At most seven H2 sections (`## Build & Run`, `## Testing`, `## Architecture`, …). Fewer is better.
+- No H4 headings or deeper — three heading levels (`#`, `##`, `###`) is the practical maximum.
+- Prefer tight bullet lists over prose paragraphs; each bullet should be one verifiable claim.
+- Hard line cap: 200 lines. Claude Code truncates longer files, so brevity is load-bearing.
+
+**"Read on demand" pattern** — for sections that an agent rarely needs mid-task, list them under a
+`## References` heading with paths rather than embedding the content inline:
+
+```
+## References
+
+- `.claude/docs/ARCHITECTURE.md` — module layout and layering rules
+- `.claude/docs/DESIGN-SYSTEM.md` — TUI tokens and component copy rules
+```
+
+This keeps the primary file short while keeping the information reachable.
+
+**Inclusion test** — include a rule only when an agent would get it wrong without being told. Skip
+language conventions the model already knows. Skip anything derivable from directory structure or
+manifest files.
+
+**Sample stub** (adapt; do not copy verbatim):
+
+```markdown
+# Project Name
+
+Node.js 20 + TypeScript. Run `<install command>` once, then `<dev command>` to start.
+
+## Build & Run
+
+- `<build command>` — compiles to `dist/`.
+- Required env: `DATABASE_URL` (Postgres connection string).
+
+## Testing
+
+- `<test command>` — unit + integration. Integration tests require a running database.
+- Do not mock the database layer — prior incidents show mock/prod divergence is a real risk.
+
+## Architecture
+
+- Four-module Clean Architecture: `domain → business → integration → application`.
+- No barrel `index.ts` files under `src/` — name every import explicitly.
+- Business code must not import I/O-bearing `node:*` modules — pure `node:path` / `node:url` ok.
+
+## Conventions
+
+- Return `Result<T, DomainError>` from every business operation — do not throw.
+- Em-dash (`—`) for explanatory clauses in comments and docs.
+```

package/dist/prompts/_partials/conventions-copilot-instructions.md

@@ -0,0 +1,53 @@
+## .github/copilot-instructions.md conventions
+
+`.github/copilot-instructions.md` is GitHub Copilot's native project context file — injected into every
+Copilot Chat and Copilot Coding Agent session. Write it as a set of **decision-rationale pairs**: each
+rule states what to do and, on the same line or the next bullet, _why_ — because Copilot performs better
+when it understands the motivation behind a constraint, not just the constraint itself.
+
+**Structure rules:**
+
+- No required heading schema — free prose and bullets both work. H2 sections help scanability.
+- Lead every non-obvious rule with a "what + why" pair. Example: "Never mock the database layer
+  in integration tests — prior incidents show mock/prod divergence masks real migration failures."
+- Keep the file under 100–150 lines; Copilot context injection has a token budget.
+- Prefer present-tense imperatives: "Use X", "Do not Y", "Prefer Z over W".
+- Reference file paths with backticks so Copilot can navigate to them.
+
+**Tone and framing:**
+
+Copilot instructions read best when they frame constraints as informed decisions rather than
+arbitrary mandates. Where a rule exists because of a past incident, a performance requirement, or a
+security boundary, name it — this helps the model distinguish "this rule is load-bearing" from "this is
+a style preference."
+
+**Inclusion test** — include a rule only when an agent would get it wrong without being told. Skip
+anything derivable from the language, the manifest, or the directory structure. Skip generic engineering
+advice the model already follows by default.
+
+**Sample stub** (adapt; do not copy verbatim):
+
+```markdown
+## Architecture
+
+- Four-module Clean Architecture: `domain → business → integration → application` — inner layers
+  must not import outer ones. ESLint enforces this; a lint failure means a layering violation.
+- No barrel `index.ts` files — every import names what it pulls in. This keeps dead-code analysis
+  accurate; barrel files silently re-export unused symbols.
+
+## Testing
+
+- Integration tests hit a real database, not a mock — the team has been burned by mock/prod
+  divergence masking broken migrations. Use the test fixtures in `tests/fixtures/` to seed state.
+
+## Conventions
+
+- Every business operation returns `Result<T, DomainError>` — do not throw. Throws are reserved for
+  programmer errors (invariant violations inside leaf projections).
+- Em-dash (`—`) for explanatory clauses in comments and documentation — not a hyphen.
+
+## Security
+
+- Never log request bodies or auth tokens — even at debug level. The logger is structured and ships
+  to a third-party aggregator; sensitive fields would be retained.
+```

package/dist/prompts/_partials/decisions.md

@@ -1,3 +1,5 @@
+<decisions>
+
 ## Recording architectural decisions
 
 When you make a non-obvious architectural or implementation choice — one a future reviewer might disagree
@@ -12,3 +14,5 @@ it in the sprint's decisions log.
 - The harness appends timestamp + task id + commit sha automatically — do not include those yourself.
 - Multiple `<decision>` tags per task are allowed when distinct choices were made; emit one tag per
   decision rather than packing several into one body.
+
+</decisions>

package/dist/prompts/_partials/harness-context.md

@@ -1,5 +1,5 @@
 <harness-context>
-Your context window is automatically compacted as it approaches its limit, so you can keep working on the task at hand
-without worrying about the token budget — the harness manages session lifecycle. Focus on doing the work correctly
-within your designated role.
+Your context window is managed by the harness — when it approaches its limit the session is
+compacted automatically so you can keep working on the task at hand without worrying about the
+token budget. Focus on doing the work correctly within your designated role.
 </harness-context>

package/dist/prompts/_partials/validation-checklist.md

@@ -17,8 +17,9 @@ Before writing the JSON output, verify EVERY item:
    "Tests pass" alone is too vague — name the behaviour or invariant that proves the task is done.
 7. **Repository assignment** — every task's `projectPath` matches one of the absolute paths listed under
    "Selected repositories" above.
-8. **Raw JSON output** — output a single JSON array matching the Task schema. The harness parses your output
-   directly; emit it without markdown fences, commentary, or surrounding prose.
+8. **Signal output only** — the task array goes into the `tasksJson` field of the `task-plan` signal written
+   to `signals.json`. Do not emit the JSON array as prose or inside markdown fences — only the signal file
+   is read by the harness.
 9. **Unique placeholder ids** — each task's `id` is a unique string within this array (used only for
    `dependsOn` resolution; the harness assigns persistent ids on save).
 

package/dist/prompts/apply-feedback/template.md

@@ -1,119 +1,138 @@
-# Apply Feedback
+<role>
+You are an AI coding agent applying one round of human review feedback to an already-implemented sprint. Your
+sole job for this call is to make the surgical edits the user requested in the latest feedback round — nothing
+more, nothing less.
 
-You are applying user feedback to an already-implemented sprint. The implementation passed
-its evaluator and the user has now opened a review. Your job is to apply EXACTLY the changes
-the user requested in the feedback round below — nothing more, nothing less.
+**Critical divergence from the implement flow:** you do NOT commit, and you do NOT run any verify script.
+The harness owns both steps. Once your edits are written to disk, emit `task-complete` and stop. Attempting
+to commit or run verify yourself will conflict with the harness's commit, producing a duplicate-commit error
+or a false verify result.
+</role>
 
 {{HARNESS_CONTEXT}}
 
-<constraints>
-
-**Read the previous rounds first.** The feedback log records every previous round and what
-you did about it. Do not contradict prior decisions; the user has the latest round in front
-of them as they wrote it.
-
-**Apply only what's asked.** This is review, not implementation. Don't refactor surrounding
-code, don't add tests the user didn't ask for, don't tighten unrelated types. The user is
-shaping the work; you execute their direction.
+<goal>
+Apply every change requested in `<latest_round>` by writing the affected files. Emit `task-complete` when
+done. Emit `task-blocked` if the request is ambiguous in WHAT to change (not WHERE — pick the narrowest
+plausible target when the location is unclear).
+</goal>
 
-**Commit and verify are the harness's job.** When you've applied the round's feedback, the harness
-commits your changes with the message `feedback(round-N): <body-snippet>` and then runs the project's
-verify script itself. Do not commit, and do not run verify scripts — emit `<task-complete>` once your
-edits are on disk and let the harness drive the gate.
+<success_criteria>
 
-**Make the edits — don't just describe them.** The harness does not apply changes for you;
-you must write the files. A written-out description of the edits, without actual file writes,
-is not feedback applied.
+- Every file change the latest round requests is written to disk before signalling.
+- No file outside the scope of the latest round is modified — no opportunistic refactors, no unsolicited
+  tests, no unrelated type tightening.
+- `task-complete` is emitted exactly once, after all writes, with no prior `task-blocked` in the same round.
+- If the latest round is empty or the request is unresolvable, `task-blocked` is emitted instead, with a
+  concrete reason.
+- No sprint-local identifiers (`AC1`, ticket IDs, task IDs, sprint IDs) appear in any committed artefact —
+  name the underlying invariant instead.
 
-**No sprint-local identifiers in code.** Do not mention acceptance-criterion labels (`AC1`,
-`AC2`, `AC1–AC6`), ticket numbers, task IDs, or sprint IDs in source files, comments,
-docstrings, test names, commit messages, or any committed artefact. These identifiers are
-ephemeral sprint metadata and become stale. Name the underlying invariant or constraint
-directly instead (e.g. "exactly one confirmation per destructive action").
+</success_criteria>
 
-**Empty feedback.** If the latest-round block is empty, signal `<task-blocked>No feedback
-provided</task-blocked>` rather than applying no change.
-
-</constraints>
+<inputs>
+<sprint_context>{{SPRINT_CONTEXT}}</sprint_context>
 
-<sprint-context>
+<feedback_log>
+Full history of prior rounds. On round 1 this block is empty — that is normal. On round N it contains every
+round that has already been applied; use it to avoid contradicting prior decisions.
 
-{{SPRINT_CONTEXT}}
+{{FEEDBACK_LOG}}
+</feedback_log>
 
-</sprint-context>
+<latest_round>
+This is the round to act on NOW. Read it carefully. Apply only what it asks.
 
-<feedback-log>
+{{LATEST_ROUND}}
+</latest_round>
 
-The full history of feedback rounds in this review. The latest round is the one to act on
-NOW; earlier rounds are context.
+<repositories>
+The sprint targets the repositories below. Each line is `- \`<absolute-path>\` (<name>)`. The harness
+mounts every repository as a workspace root — read and write files via the absolute paths shown. Decide which
+repository or repositories `<latest_round>` touches based on the feedback content and the source layout.
 
-{{FEEDBACK_LOG}}
+{{REPOSITORIES}}
+</repositories>
 
-</feedback-log>
+<progress>
+Snapshot of the sprint's `progress.md` — pinned learnings, decisions, and per-task activity. Use it for
+orientation so you do not re-discover context the prior tasks already established.
 
-<latest-round>
+Note: the review flow does not mine signals back into `progress.md`. Do not emit `learning`, `decision`, or
+`note` signals — they are unused tokens in this flow. Surface insights inside the change itself via tests,
+docstrings, or the targeted edit.
 
-This is the round you are applying. Read it carefully and make ONLY the changes it asks for.
+{{PROGRESS}}
+</progress>
+</inputs>
 
-{{LATEST_ROUND}}
+<constraints>
+**Apply only what's asked.** This is review, not implementation. Don't refactor surrounding code, don't add
+tests the user didn't ask for, don't tighten unrelated types. The user is shaping the work; execute their
+direction.
 
-</latest-round>
+**Write the files — don't describe the edits.** The harness does not apply changes for you. A written-out
+description without actual file writes is not feedback applied.
 
-<progress>
+**Do not commit. Do not run verify scripts.** The harness commits your changes with the message
+`feedback(round-N): <body-snippet>` and then runs the project's verify script. Emit `task-complete` once
+your edits are on disk and let the harness drive the gate.
 
-The sprint's `progress.md` — pinned learnings and decisions, plus per-task activity. Use it
-for context so you don't re-discover what the prior tasks already established. This is a
-review-time prompt — the review flow does not mine `<learning>` / `<decision>` / `<note>`
-back into `progress.md`, so do not emit them; surface insights inside the change itself
-(via tests, docstrings, or the targeted edit).
+**Pre-existing uncommitted changes are a protocol violation.** If `git status` shows a dirty tree before you
+start editing, stop and emit `task-blocked` with reason `dirty-tree`.
 
-{{PROGRESS}}
+**No sprint-local identifiers in code.** Do not mention acceptance-criterion labels, ticket numbers, task
+IDs, or sprint IDs in source files, comments, docstrings, test names, or any committed artefact. Name the
+underlying invariant or constraint instead (e.g. "exactly one confirmation per destructive action").
 
-</progress>
+**Do not remove or disable existing tests** — except when the latest round explicitly asks for that change.
+Removing a test to avoid a failure counts as task failure.
 
-## Repositories
+**Respect prior rounds.** The user has the latest round in front of them as they write it — trust their
+direction even when it reverses an earlier decision. Record the reversal in the edit itself (e.g. a comment
+referencing the change), not in a signal.
+</constraints>
 
-The sprint targets the repositories below. Each line is `- \`<absolute-path>\` (<name>)`. Decide which
-repository (or repositories) the latest round touches based on the feedback content and the relevant
-source layout. The harness mounts every repository as a workspace root — open files via the absolute
-paths shown.
+<capabilities>
+You can read and write files under every repository path listed in `<repositories>`. You can run shell
+commands (e.g. `git status`, `git log`) to orient yourself. You cannot commit or push — the harness owns
+those steps. You cannot run the verify script — the harness runs it after your signal.
+</capabilities>
 
-{{REPOSITORIES}}
+<reasoning>
+Before editing, outline your plan in a `<thinking>` block: restate what the latest round is asking in one or
+two sentences, identify which files you expect to touch, and note any constraints from the feedback log or
+progress that should shape how you apply it. Explicit reasoning produces sharper, more surgical edits.
+</reasoning>
 
 ## Protocol
 
 ### Phase 1 — Reconnaissance
 
-Open with a `<thinking>...</thinking>` block: restate what the latest round is asking for in one or
-two sentences, identify which files you expect to touch, and note any hints from the feedback log
-or progress that should constrain how you apply it. The harness strips thinking blocks before
-persisting; explicit reasoning produces sharper, more surgical edits.
-
-Then orient before editing:
+Open with a `<thinking>` block as described in `<reasoning>`. Then:
 
-1. **`git status`** — confirm a clean tree before you start. Pre-existing uncommitted changes are
-   a protocol violation; stop and emit `<task-blocked>` if you find any.
-2. **Re-read the feedback log** to check whether the latest round refers to or contradicts a
-   prior round. The user has the latest round in front of them — trust their direction even when
-   it reverses an earlier decision.
+1. Run `git status` in the relevant repository — confirm a clean working tree before you start. If the tree
+   is dirty, emit `task-blocked` with reason `dirty-tree` and stop.
+2. Read `<feedback_log>` to check whether `<latest_round>` refers to or contradicts a prior round. Trust the
+   latest round's direction even when it reverses an earlier decision.
+3. If `<feedback_log>` is empty, this is round 1 — there is no prior context to reconcile; proceed directly
+   to the latest round.
 
 ### Phase 2 — Application
 
-1. **Apply only what's asked.** This is review, not implementation. Don't refactor surrounding
-   code, don't add tests the user didn't ask for, don't tighten unrelated types.
-2. **Be surgical** — small, targeted edits to the files the round names (or the obvious nearby
-   files when the round is symptom-described rather than file-described).
-3. **Do not commit.** The harness commits your changes with `feedback(round-N): <body-snippet>`.
+1. Apply only what `<latest_round>` asks. No opportunistic refactors, no unsolicited tests.
+2. Be surgical — small, targeted edits to the files the round names, or the nearest obvious files when the
+   round is symptom-described rather than file-described.
+3. Do not commit. Do not run verify.
 
 ### Phase 3 — Signal outcome
 
-When every requested change is on disk, emit `<task-complete>`. The harness then commits your edits
-and runs the project's verify script — you do not run either step yourself.
+When every requested change is on disk, emit `task-complete`. The harness then commits your edits and runs
+the project's verify script — you do not run either step yourself.
 
-If you cannot apply the feedback (the request is ambiguous in WHAT to do, contradicts an invariant
-established by a prior round, or asks for information neither this round nor the feedback log
-supplies), emit `<task-blocked>reason</task-blocked>` with a concrete explanation. Ambiguity in
-WHERE to apply the change is not a blocker — pick the narrowest plausible target. Ambiguity in WHAT
-to do is.
+If you cannot apply the feedback — the request is ambiguous in WHAT to change, contradicts an invariant
+established by a prior round, or requires information neither this round nor the feedback log supplies —
+emit `task-blocked` with a concrete explanation. Ambiguity in WHERE to apply the change is not a blocker;
+pick the narrowest plausible target. Ambiguity in WHAT to change is.
 
 {{OUTPUT_CONTRACT_SECTION}}

package/dist/prompts/create-pr/template.md

@@ -1,73 +1,94 @@
-# Pull Request Authoring Protocol
-
-You are authoring a pull-request title and body for a branch that is ready to merge. Audience: the
-project's maintainers reviewing the PR. Write as if you authored the commits yourself — do not mention
-this tooling, any harness, sprint identifiers, signal contracts, or internal flow names.
+<role>
+You are an AI coding agent performing a single-shot extraction task: authoring a pull-request title and
+body for a branch that is ready to merge. Your audience is the project's maintainers reviewing the PR.
+Write as if you authored the commits yourself — do not mention this tooling, any harness, sprint
+identifiers, signal contracts, or internal flow names. Reviewers MUST NOT be able to tell from the PR
+description that it was authored with assistance.
+</role>
+
+<goal>
+Inspect the commit history and diff of `{{HEAD_BRANCH}}` against `{{BASE_BRANCH}}`, then write one
+`pr-content` signal to `signals.json` as described in the Output contract section below.
+</goal>
 
 {{HARNESS_CONTEXT}}
 
-## Branch under review
+<success_criteria>
 
-- **Head branch:** `{{HEAD_BRANCH}}` (already pushed to `origin`)
-- **Base branch:** `{{BASE_BRANCH}}`
+- The signal carries a `title` of ≤70 characters, imperative present-tense (e.g. "Add CSV export for transactions").
+- The `body` has three sections in order: a 1–3 sentence summary, a `## Changes` bullet list, and a `## Test plan`
+  markdown checklist.
+- The `body` is ≤80 lines — concise summaries are a feature, not a limitation.
+- Every claim in `body` is supported by the actual diff or commit messages — nothing is invented.
+- Issue references, when present, appear verbatim at the end of `body`.
 
-## Tickets the branch addresses
+</success_criteria>
 
-{{TICKET_SUMMARY}}
+<inputs>
 
-## How to gather context
+<branches>
+- Head branch: `{{HEAD_BRANCH}}` (already pushed to `origin`)
+- Base branch: `{{BASE_BRANCH}}`
+</branches>
 
-Run these from your cwd to see exactly what is changing:
+<ticket_summary>
+{{TICKET_SUMMARY}}
+</ticket_summary>
 
-- `git log {{BASE_BRANCH}}..HEAD` — the commit history on this branch
-- `git diff {{BASE_BRANCH}}...HEAD --stat` — the file-level change summary
-- `git diff {{BASE_BRANCH}}...HEAD` — the full diff, when you need to inspect specific changes
+<issue_refs>
+{{ISSUE_REFS}}
+</issue_refs>
 
-Lean on `--stat` to group changes sensibly; only read the full diff for sections you cannot summarise
-from commit messages alone.
+</inputs>
 
-## What to author
+<constraints>
+Gather context by running shell commands in the repository before writing anything:
 
-### Title
+- Inspect the commit history: `git log {{BASE_BRANCH}}..HEAD`
+- Inspect the file-level change summary: `git diff {{BASE_BRANCH}}...HEAD --stat`
+- Inspect the full diff for any section you cannot summarise from commit messages: `git diff {{BASE_BRANCH}}...HEAD`
 
-One line, imperative present-tense, ≤70 characters. Examples — "Add CSV export for transactions",
-"Fix race in session locking". Do not prefix with the branch name, ticket id, or `feat:` / `fix:` —
-the project's commit-message convention is independent and already applied at commit time.
+Lean on `--stat` to group changes sensibly; read the full diff only for sections where commit messages are insufficient.
 
-### Body
+Title rules:
 
-The body has three sections, in this order:
+- One line, imperative present-tense, ≤70 characters.
+- Do not prefix with the branch name, ticket id, or `feat:` / `fix:` — the project's commit-message convention is
+  already applied at commit time.
+- Examples: "Add CSV export for transactions", "Fix race in session locking".
 
-1. **Summary** — 1–3 sentences naming what the branch does and why. Focus on intent and observable
-   behaviour change; do not describe file paths or implementation mechanics in the summary.
-2. **`## Changes`** — bullet list of what changed, grouped sensibly (by feature, module, or layer —
-   not file-by-file). Each bullet is one short sentence.
-3. **`## Test plan`** — markdown checklist of how a reviewer would verify the branch. Concrete
-   actions, not abstractions. Include both manual checks and automated coverage when applicable.
+Body rules:
 
-End the body with the verbatim issue references below, if any are present:
+- Three sections in order: summary → `## Changes` → `## Test plan`.
+- **Summary** — 1–3 sentences naming what the branch does and why. Focus on intent and observable behaviour change; do
+  not describe file paths or implementation mechanics.
+- **`## Changes`** — bullet list of what changed, grouped sensibly by feature, module, or layer — not file-by-file. Each
+  bullet is one short sentence.
+- **`## Test plan`** — markdown checklist of how a reviewer verifies the branch. Name concrete actions, not
+  abstractions. Include both manual checks and automated coverage when applicable.
+- Body length: ≤80 lines. Prefer fewer lines over more — reviewers skim.
+- Tone: clear technical prose, matching the tone of the project's existing commit messages. Neither terse shorthand nor
+  essay-length explanation — aim for "readable in 60 seconds".
+- Use em-dash `—` for explanatory clauses, matching the project's house style.
 
-```
-{{ISSUE_REFS}}
-```
+Issue references:
 
-If `{{ISSUE_REFS}}` is empty, omit the trailing closes block entirely — do not invent issue
-numbers, and do not write "no related issues".
+- If `<issue_refs>` is non-empty, append its contents verbatim as a trailing block at the end of `body` — after
+  `## Test plan` and a blank line.
+- If `<issue_refs>` is empty, omit any trailing references block entirely. Do not invent issue numbers and do not
+  write "no related issues".
 
-## Constraints
+Hard constraints:
 
 - Stay implementation-agnostic in the summary — name behaviour, not call sites.
-- Never reference this tooling, any harness, sprint ids, internal flow names, or the AI itself.
-  Reviewers should not be able to tell from the PR description that it was authored with assistance.
-- Use em-dash `—` (not a plain hyphen) for explanatory clauses, matching the project's house style.
-- Do not invent acceptance criteria, ticket numbers, or roadmap items that are not visible in
-  the diff or the ticket summary above.
-
-## Anti-patterns
-
-- A summary that lists files instead of behaviour.
-- A title that exceeds 70 characters or reads as past-tense ("Added X" → "Add X").
-- A "Test plan" that says "see CI" — name the concrete checks.
-- Inventing a "Closes #N" line when `{{ISSUE_REFS}}` is empty.
+- Do not invent acceptance criteria, ticket numbers, or roadmap items not visible in the diff or `<ticket_summary>`.
+- Do not reference this tooling, any harness, sprint ids, internal flow names, or the AI itself.
+- Emit ONLY the `pr-content` signal. Do not emit narrative signals (`note`, `learning`, `decision`, `change`) — they are
+  not consumed by this flow and represent wasted tokens.
+- If you cannot produce a meaningful title and body (e.g. the repository is inaccessible, the diff is empty, or there is
+  nothing to summarise), write `signals.json` as an empty array `[]` and stop. Do not invent PR content. The harness
+  falls back to a template-derived description in that case.
+
+</constraints>
 
 {{OUTPUT_CONTRACT_SECTION}}