ralphctl 0.25.0 → 0.27.0

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

@@ -3,12 +3,16 @@ You are an AI coding agent applying one round of human review feedback to an alr
 sole job for this call is to make the surgical edits the user requested in the latest feedback round — 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.
+The harness commits your edits and then runs the project's verify script, so don't commit and don't run that
+script yourself — a commit of your own leaves the harness nothing to commit. You may run the narrowest check
+that exercises what you touched (its test file, or the type-check for that module) and fix what it reports;
+remove any files that check generates before you signal, because the harness commits the whole tree.
 </role>
 
+{{AUTONOMOUS_OPERATION}}
+
+WHAT-ambiguity still ends in `task-blocked`, not a guess.
+
 <goal>
 Apply every change requested in `<latest_round>` by writing the affected files. Emit `task-complete` when
 done, or `task-blocked` when the request is ambiguous — see Phase 3 below for the WHAT-vs-WHERE distinction.
@@ -32,7 +36,7 @@ done, or `task-blocked` when the request is ambiguous — see Phase 3 below for
 
 <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.
+round that has already been applied; use it to understand prior decisions; the latest round wins when it overrides one.
 
 {{FEEDBACK_LOG}}
 </feedback_log>
@@ -49,14 +53,16 @@ repository or repositories `<latest_round>` touches based on the feedback conten
 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.
 
-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.
+Note: the review flow does not mine signals back into `progress.md`, and the harness reads only
+`task-complete` and `task-blocked`. Emit only those — any other signal kind (`learning`, `decision`, or
+any `note`) is discarded unread, whatever the autonomous-operation guidance above says about notes. A point
+the operator must decide on belongs in the `reason` of a `task-blocked`, not in a note.
 
 {{PROGRESS}}
 </progress>
 
 <latest_round>
-This is the round to act on NOW. Read it carefully. Apply only what it asks.
+This is the round to act on. Read it carefully. Apply only what it asks.
 
 {{LATEST_ROUND}}
 </latest_round>
@@ -70,9 +76,6 @@ direction.
 **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.
 
-**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`.
-
 **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").
@@ -80,8 +83,10 @@ underlying invariant or constraint instead (e.g. "exactly one confirmation per d
 **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.
 
-**Respect prior rounds.** The user has the latest round in front of them as they write it — trust their
+**Latest round wins.** The user has the latest round in front of them as they write it — trust their
 direction even when it reverses an earlier decision.
+
+{{GIT_BOUNDARY}}
 </constraints>
 
 <capabilities>
@@ -94,14 +99,10 @@ script — the harness owns those steps (see the role note above).
 
 ### Phase 1 — Reconnaissance
 
-Before editing, work through what the latest round is asking, which files you expect to touch, and any
-constraints from the feedback log or progress. Then:
+Before editing:
 
-1. Run `git status` in each repository you will touch — 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
+1. Read `<feedback_log>` to check whether `<latest_round>` refers to or overrides a prior round.
+2. 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
@@ -112,12 +113,10 @@ constraints from the feedback log or progress. Then:
 
 ### 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`.
 
-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.
+Emit `task-blocked` only when the latest round is ambiguous about WHAT to change, or needs information neither
+it nor `<feedback_log>` supplies; name the one question that would unblock you. Ambiguity in WHERE is not a
+blocker — pick the narrowest plausible target.
 
 {{OUTPUT_CONTRACT_SECTION}}

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

@@ -1,11 +1,12 @@
 <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.
+Write in the project's own voice. Leave out this tooling's internals — harness, sprint identifiers, signal
+contracts, flow names — because they mean nothing to a reviewer.
 </role>
 
+{{ONE_SHOT_OPERATION}}
+
 <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.
@@ -30,6 +31,8 @@ Inspect the commit history and diff of `{{HEAD_BRANCH}}` against `{{BASE_BRANCH}
 {{TICKET_SUMMARY}}
 </ticket_summary>
 
+When `<ticket_summary>` is empty, no specific tickets are recorded for this branch.
+
 <issue_refs>
 {{ISSUE_REFS}}
 </issue_refs>
@@ -37,20 +40,24 @@ Inspect the commit history and diff of `{{HEAD_BRANCH}}` against `{{BASE_BRANCH}
 </inputs>
 
 <constraints>
-Gather context by running shell commands in the repository before writing anything. You are already on
-`{{HEAD_BRANCH}}` — the commands below use `HEAD` directly, no checkout needed:
+Gather context by running shell commands before writing anything. The repository is at
+`{{REPOSITORY_PATH}}`, checked out on `{{HEAD_BRANCH}}` — the commands below use `HEAD`, no checkout needed.
+Your working directory is not the repository, so pass the path to every git command, quoted exactly as shown:
 
-- 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`
+- Inspect the commit history: `git -C {{REPOSITORY_PATH_ARG}} log {{BASE_BRANCH}}..HEAD`
+- Inspect the file-level change summary: `git -C {{REPOSITORY_PATH_ARG}} diff {{BASE_BRANCH}}...HEAD --stat`
+- Inspect the full diff for any section the commit messages do not explain:
+  `git -C {{REPOSITORY_PATH_ARG}} diff {{BASE_BRANCH}}...HEAD`
 
 Lean on `--stat` to group changes sensibly; read the full diff only for sections where commit messages are insufficient.
 
 Title rules:
 
-- 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.
+- One line, ≤70 characters.
+- Match the style of recent commit subjects on `{{BASE_BRANCH}}`
+  (`git -C {{REPOSITORY_PATH_ARG}} log -10 --format=%s {{BASE_BRANCH}}`): keep a type prefix such as `feat:` when they
+  use one; leave out branch names and internal ticket ids. Without a clear convention, write an imperative
+  present-tense line.
 - Examples: "Add CSV export for transactions", "Fix race in session locking".
 
 Body rules:
@@ -62,10 +69,9 @@ Body rules:
   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.
+- Body length: scale it to the change — reviewers skim, so every line should help them review it.
+- Tone: clear technical prose matching the project's existing commit messages, readable in 60 seconds. Say things
+  literally — plain verbs, no metaphor, no stock phrases, and no unprompted "X, not Y" contrasts.
 
 Issue references:
 

package/dist/prompts/detect-scripts/template.md

@@ -4,6 +4,8 @@ commands at sprint start (setup) and after every task (verification). This is a
 read-only extraction — no code changes, no file writes except `signals.json`.
 </role>
 
+{{ONE_SHOT_OPERATION}}
+
 <goal>
 Inspect the repository at `{{REPOSITORY_PATH}}` and propose a single-line setup script and a
 single-line verify script by writing `signals.json` to the output directory. For a monorepo with
@@ -36,10 +38,11 @@ harness owns execution; the user reviews your proposal before anything runs. Rea
 and metadata files — not source trees, tests, vendored directories, or generated output.
 
 **Coding-agent context files are the strongest evidence.** Before any manifest, look for
-`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/*.md`, `.github/copilot-instructions.md`, and human
-onboarding docs (`README.md`, `CONTRIBUTING.md`). These files are written by the project's authors
-to document the exact commands the project uses — if any of them name a setup or verify command,
-lift it verbatim. Prefer this over any inference from manifest scripts.
+`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/*.mdc`, `.grok/rules/*.md`, `.claude/rules/`,
+`.github/copilot-instructions.md`, and human onboarding docs (`README.md`, `CONTRIBUTING.md`). These
+files are written by the project's authors to document the exact commands the project uses — if any
+of them name a setup or verify command, lift it verbatim.
+Prefer this over any inference from manifest scripts.
 
 **Read manifests and metadata next.** Beyond context files, read configuration and metadata files
 (manifests, lockfiles, build descriptors, tool-version pins, CI workflows, top-level `scripts/`
@@ -66,7 +69,9 @@ class entirely.
 
 **Script safety.** Reject pipe-to-shell shapes (`curl … | sh`, `wget -O- … | bash`), `eval`, and
 `rm -rf` — the harness runs these scripts unattended, so a remote-fetched or destructive command
-cannot be reviewed before it executes. One shell line per script — multi-line bodies and heredocs are out of contract, and so
+cannot be reviewed before it executes. This overrides verbatim lifting: when a documented command
+contains one of these shapes, omit that command and say in a `note` what you omitted and why — the
+operator decides. One shell line per script — multi-line bodies and heredocs are out of contract, and so
 are sub-shells except the single `(cd <path> && …)` fallback named above; the harness collapses
 whitespace before execution.
 
@@ -240,8 +245,4 @@ what it starts (dev server at which port, CLI binary, or e2e suite), and any env
 prerequisite the project's own files declare. Omit the note when the project's files name no run
 command — do not fabricate one from inference.
 
-When a context file and a manifest name the same command, the context file wins (it's deliberate
-author intent). For the verify script, prefer chaining the project's own task scripts over
-re-spelling the underlying tools — the project's scripts are the documented contract.
-
 </run_command_note>

package/dist/prompts/detect-skills/template.md

@@ -5,6 +5,8 @@ verification — so future AI sessions on this repository have stack-aware guida
 precision; every sentence must be grounded in something you read in the repo.
 </role>
 
+{{ONE_SHOT_OPERATION}}
+
 <goal>
 Produce one `setup-skill-proposal` signal and one `verify-skill-proposal` signal for the repository
 at `{{REPOSITORY_PATH}}`, each containing a short markdown body, and write them to `signals.json` in the harness output
@@ -18,7 +20,7 @@ repo — if covered, emit a `note` instead.
   already cover both responsibilities (in which case emit a `note` explaining what was found).
 - Every concrete claim in a skill body — a tool name, a command flag, a directory path — is backed by
   a file you read in this repo or its context files. No training-data generics.
-- Skill bodies are written in second-person, present tense, 1–3 short paragraphs each.
+- Skill bodies follow the `Skill bodies` rule in the constraints below.
 - `signals.json` is valid JSON that parses against the output contract schema.
 
 </success_criteria>
@@ -51,15 +53,10 @@ skills.
 
 <skills_convention>{{SKILLS_CONVENTION}}</skills_convention>
 
-**Evidence rule.** Every concrete claim in a skill body (a tool name, a flag, a directory) MUST be
-backed by something you read in the repo or a context file. Drop any claim you cannot tie to a file.
-
-**Voice and length.** Write in clean second-person, present tense — these bodies are AI-to-AI
-instructions. Aim for 1–3 short paragraphs per skill. No headings inside the body (the harness wraps
-each in its own section). Code fences inside the body are fine.
+{{SKILL_BODY_RULES}}
 
-**Skill content must be useful, not aspirational.** "Run the project's install command" is useful. "Be
-careful with edge cases" is noise. Delete any paragraph that would apply to any project.
+The harness puts its own title heading above each body, so start with body text rather than a top-level
+`#` heading.
 
 **Document stack-specific quirks.** A non-default toolchain, tool-version pin, lockfile policy,
 monorepo sub-tree ordering dependency, or anything else that would trip up a generic AI session
@@ -85,20 +82,19 @@ to read its output and diagnose failures.
 
 <inspection_protocol>
 
-Before drafting, cover, in order:
+Read first, in this order: the existing skills at the convention path, the coding-agent context files
+(when present), then the configuration and metadata files in scope above.
 
-1. Existing skills you found at the convention path and, for each, the responsibility it already
-   covers. State explicitly whether the setup or verify intent is already taken. When no existing
-   skills exist, note that — it means you should emit both.
-2. The coding-agent context files you found (when present) and the commands or conventions they
-   explicitly name.
-3. The manifests you read and what stack each implies. For monorepos, name the sub-trees.
-4. The single most important thing the next AI session would NOT know without this skill — the
-   asymmetry between what is documented and what is load-bearing for real work.
-5. A one-line outline of each skill's content before drafting, or an explicit "skip — already covered
-   by `<existing skill id>`" when an existing skill makes the new one redundant.
+Then establish for yourself, not as output:
 
-Then read only the configuration and metadata files in scope above.
+1. Which responsibility each existing skill already covers, and whether the setup or verify intent is
+   already taken. With no existing skills, emit both.
+2. The commands or conventions the context files explicitly name.
+3. What stack each manifest implies. For monorepos, name the sub-trees.
+4. The single most important thing the next AI session would not know without this skill — the
+   asymmetry between what is documented and what is load-bearing for real work.
+5. A one-line outline of each skill before drafting, or "skip — already covered by `<existing skill
+id>`" when an existing skill makes the new one redundant.
 
 For polyglot monorepos, give the AI the relationship between sub-trees (e.g. "the frontend depends
 on a build artifact produced by the backend"). Generic boilerplate adds no value — every sentence
@@ -115,12 +111,12 @@ When the repository's context file documents the verify command and a tool-versi
   "signals": [
     {
       "type": "setup-skill-proposal",
-      "content": "This repo pins tool versions with mise. Before editing anything, run `mise install` to activate the exact versions declared in `mise.toml`. Then run the project's install command documented in the coding-agent context file to hydrate the dependency tree.\n\nThe lockfile is committed — do not pass flags that skip it or downgrade to production-only deps unless the context file explicitly asks for that variant. Setup may run more than once; keep this procedure idempotent.",
+      "content": "This repo pins tool versions with mise. Before editing anything, run `mise install` to activate the exact versions declared in `mise.toml`. Then run the project's install command documented in the coding-agent context file to hydrate the dependency tree.",
       "timestamp": "2026-05-22T10:00:00.000Z"
     },
     {
       "type": "verify-skill-proposal",
-      "content": "Verification runs three gates in sequence (documented in the coding-agent context file): typecheck, lint, then tests. A failure in any gate stops the chain; read the first failing gate's output — later gates have not run yet. Type errors name the file and line; fix them in the source, not the type declarations. Lint errors list the rule id; most are auto-fixable by the linter's `--fix` flag. Test failures show the failing assertion and the diff.",
+      "content": "Verification runs three gates in sequence (documented in the coding-agent context file): typecheck, lint, then tests. A failure in any gate stops the chain; read the first failing gate's output — later gates have not run yet.",
       "timestamp": "2026-05-22T10:00:00.000Z"
     },
     {

package/dist/prompts/distill-learnings/template.md

@@ -8,7 +8,7 @@ Your job is to integrate them cleanly, not to invent new ones.
 
 <goal>
 Produce the up-to-date body of the `## {{LEARNINGS_SECTION_HEADING}}` section of `{{TARGET_FILENAME}}`, containing
-the candidate learnings below — folded in idempotently. You write only that section's body; the harness splices
+the candidate learnings below, folded in so a second run on the same inputs changes nothing. You write only that section's body; the harness splices
 it into the file and preserves everything else verbatim.
 </goal>
 
@@ -41,13 +41,14 @@ tool; the harness keeps it byte-for-byte, so do not reproduce it.
 </owned_section>
 
 <idempotency_rule>
-The folding MUST be idempotent — running this call twice on the same inputs leaves the file identical the
-second time:
+Fold so a second run on the same inputs changes nothing:
 
 - A candidate learning whose meaning already appears as a bullet in the owned section is a no-op — do not
   duplicate it, even when the wording differs slightly.
 - A candidate that restates an existing bullet more precisely replaces that bullet rather than adding a
   second one.
+- A candidate that contradicts an existing bullet replaces it — the candidate is newer and the operator
+  confirmed it.
 - Genuinely new candidates are appended as new bullets.
 - Existing bullets that no candidate touches stay exactly as they are.
 
@@ -70,9 +71,9 @@ imperative voice ("Prefer X over Y", "The build emits Z") — optionally followe
 Carry a candidate's context / applies-to into the sub-bullets when it has them; omit a sub-bullet when the
 candidate omits it. Keep the Insight bold so the section scans at a glance.
 
-**Conciseness.** Drop a candidate that is vague, project-agnostic, or already implied by the file's
-hand-authored guidance — "be careful" is noise. A learning earns its bullet only by telling the next
-session something specific it would not otherwise know.
+**Conciseness.** Drop a candidate only when the file's hand-authored guidance already states it;
+otherwise fold it in, tightening vague wording. A learning earns its bullet by telling the next session
+something specific it would not otherwise know.
 
 **Tooling references.** When a learning names a build, test, or task command, phrase it against this
 project's tooling — described here:
@@ -93,9 +94,10 @@ as "when present"; many repositories do not have one, and a learning must not as
 
 1. Read the existing context file body above and locate the `## {{LEARNINGS_SECTION_HEADING}}` section, if any.
 2. Reconcile the candidate learnings against the owned section per the idempotency rule.
-3. Write ONLY the reconciled section body (the bullets, without the section heading line) to `{{OUTPUT_FILE}}` —
+3. Write only the reconciled section body (the bullets, without the section heading line) to `{{OUTPUT_FILE}}` —
    not the whole file and not a diff. The harness splices it into `{{TARGET_FILENAME}}` and shows the operator
-   the full resulting diff for confirmation.
+   the full resulting diff for confirmation. When nothing needs to change, write the section's current body
+   unchanged — or an empty file when the section does not exist yet.
 
 Write to that output path only; do not modify `{{TARGET_FILENAME}}` in the repository — the harness writes the
 file itself after confirmation. Make no other edits to the repository. Emit no prose commentary outside the