ralphctl 0.22.0 → 0.24.0

package/dist/cli.mjs

@@ -2,5 +2,5 @@
 
 // src/index.ts
 process.env.NODE_ENV ??= "production";
-var { runCli } = await import("./cli-LJZZGXAY.mjs");
+var { runCli } = await import("./cli-FHPDHGP5.mjs");
 await runCli(process.argv);

package/dist/manifest.json

@@ -1,17 +1,18 @@
 {
   "schemaVersion": 1,
-  "packageVersion": "0.22.0",
-  "generatedAt": "2026-09-17T11:08:05.426Z",
+  "packageVersion": "0.24.0",
+  "generatedAt": "2026-09-30T06:53:55.509Z",
   "assets": [
     "agent-definitions/ralphctl-evaluator.md",
     "agent-definitions/ralphctl-generator.md",
+    "prompts/_partials/approval-gate.md",
     "prompts/_partials/autonomous-operation.md",
     "prompts/_partials/conventions-agents-md.md",
     "prompts/_partials/conventions-claude-md.md",
     "prompts/_partials/conventions-copilot-instructions.md",
     "prompts/_partials/decisions.md",
-    "prompts/_partials/evaluation-checkpoint.md",
     "prompts/_partials/evaluator-failure-modes.md",
+    "prompts/_partials/evaluator-grading-rules.md",
     "prompts/_partials/evidence-bound.md",
     "prompts/_partials/harness-context.md",
     "prompts/_partials/parallel-tool-calls.md",

package/dist/prompts/_partials/approval-gate.md

@@ -0,0 +1,19 @@
+<approval-gate>
+Approval works on exactly what the operator sees: what you show them is what goes into `signals.json`,
+so the operator can only approve what is fully on screen.
+
+1. Run this prompt's pre-output checklist before you present anything, so the document you show already
+   passes it. The checklist may appear later in these instructions, and for requirements the interview's
+   stop criteria are the applicable checks; either way, check first and present second.
+2. Show the complete document you will write, verbatim — for requirements, every section; for a task
+   plan, every task with all its fields (name, repository, ticket, description, `blockedBy`, every step,
+   and every verification criterion with its check type and command), followed by the dependency order.
+   Print it as its own message, not as a lead-in to the question.
+3. Do this on every approval round, including after each revision. Never substitute a summary, a diff,
+   "unchanged sections omitted", or a pointer to an earlier message — an operator who has to scroll back
+   and reassemble the document is approving something they have not read.
+4. Ask the approval question last, as one line. When the runtime has no structured question tool, ask
+   the same question as a numbered list and wait for the answer.
+5. If anything changes after approval — including a change made to satisfy the checklist — present the
+full document again and ask again. An approval covers only the version that was shown.
+</approval-gate>

package/dist/prompts/_partials/evaluator-grading-rules.md

@@ -0,0 +1,25 @@
+<grading_rules>
+These rules apply every round, identically on a first evaluation and on a re-evaluation.
+
+- **Verify script scope.** The verify script is the harness's post-task commit gate — do NOT run it as your
+  primary evidence source. Run each `auto` criterion's command directly instead. Exception: when the task
+  defines no `auto` criteria, run the verify script once as the fallback evidence source and record its
+  output. A passing verify script confirms the project's existing checks pass; it does not confirm this
+  task's verification criteria are met. Grade criteria independently of whether the verify script exits 0.
+- **UNVERIFIED criteria.** A criterion whose behaviour IS runnable but which you were blocked from executing
+  here (missing credentials, no network, an environment gap) is graded `passed: false` with evidence
+  beginning "UNVERIFIED:" plus what blocked you, as opposed to observing a violation, so downstream
+  consumers can tell unverifiable apart from broken. A criterion that is not runnable by nature is never
+  UNVERIFIED — grade it on cited `path:line` or equivalent behavioural evidence.
+- **Verification-tampering audit.** Check whether the changes touch test files, fixtures, or verification
+  tooling themselves. A criterion satisfied by weakening or deleting a test, adding a skip, or hardcoding an
+  expected value is a Correctness FAIL, not a PASS — cite the specific diff hunk, even if you flagged the
+  same file in an earlier round. When `<reproduction>` is non-empty, this check extends to it: re-run its
+  command yourself — the task cannot pass Correctness while that command still fails — and treat an
+  unexplained edit to the reproduction test the same as any other tampering.
+- **Critique format.** Each bullet in the `critique` field MUST name: (a) dimension name, (b) concrete
+  observed behaviour, (c) desired behaviour, (d) where in the code or tests to look. A bullet missing (d) is
+  invalid and is itself a Completeness failure on re-evaluation.
+- **Evidence over suspicion.** A FAIL needs a concrete observation, just as a PASS does. When you cannot
+  verify a criterion, grade it UNVERIFIED as above — do not fail on speculation, and do not pass on hope.
+  </grading_rules>

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

@@ -1,11 +1,4 @@
 <harness-context>
-Your context window is managed by the harness — as it approaches its limit the session is
-compacted or reset automatically. Treat the durable record of your work as the state you write
-through the harness — your signals and the files your role produces, and (where present) the
-progress journal and git history — not the conversation in your context window, which may be
-compacted away. Keep that external state current and accurate as you go, so a fresh session can
-resume from it cleanly.
-
-Do not wrap up early, cut scope, or rush a verdict because you sense the context filling — the
-harness handles compaction; carry the work through to completion within your designated role.
+Your context window is managed by the harness — it is compacted or reset automatically as it fills, so keep the durable record of your work in the state you write through the harness (your signals, the files your role produces, and where present the progress journal and git history), not in the conversation.
+Do not wrap up early, cut scope, or rush a verdict because you sense the context filling — carry the work through to completion within your designated role.
 </harness-context>

package/dist/prompts/_partials/task-fields.md

@@ -7,7 +7,7 @@ Each task entry uses these fields:
   ambiguity.
 - **`projectPath`** — absolute path matching exactly one of the repositories listed under
   `<repositories>`.
-- **`steps`** — concrete, ordered implementation steps. Do NOT end steps with "run the
+- **`steps`** — concrete, ordered implementation steps. Don't end steps with "run the
   verification commands" or "run all the checks" — verification belongs in `verificationCriteria`;
   the harness and the evaluator execute it. A final step that re-runs the full suite only
   duplicates the post-task gate and inflates generator cost. Exception: a step MAY run a specific
@@ -18,7 +18,7 @@ Each task entry uses these fields:
   - `assertion` — human-readable check.
   - `check` — `"auto"` (evaluator runs `command`) or `"manual"` (evaluator inspects code or
     behaviour and cites a specific location).
-  - `command` — REQUIRED when `check === "auto"`; MUST be omitted when `check === "manual"`. Use
+  - `command` — required when `check === "auto"`; omit it when `check === "manual"`. Use
     the project's own commands — never hardcode a package-manager binary; read the project's
     manifest or context file for the actual command.
   - Include at least one `auto` criterion when the repository exposes a check command (test,
@@ -27,9 +27,9 @@ Each task entry uses these fields:
     on `manual` criteria alone.
 - **`blockedBy`** — array of `id` strings that must complete before this task starts.
 - **`extraDimensions`** — optional kebab-case evaluator dimensions beyond the five floor dimensions
-  (correctness, completeness, safety, consistency, robustness). Attach an extra dimension ONLY when
+  (correctness, completeness, safety, consistency, robustness). Attach an extra dimension only when
   an acceptance criterion explicitly demands a measurable property that no floor dimension covers
-  AND no manual criterion already encodes it. When in doubt, omit — the floor dimensions are almost
+  and no manual criterion already encodes it. When in doubt, omit — the floor dimensions are almost
   always sufficient. Example of a justified attachment: `migration-safety` when the task requires a
   zero-downtime schema change that the five floor dimensions cannot score on their own. Cap: 2–3 per
   task; hard max 6.

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

@@ -2,7 +2,7 @@
 
 ## Pre-Output Validation
 
-Before writing the JSON output, verify EVERY item:
+Before writing the JSON output, verify every item:
 
 1. **Requirements understood** — every requirement in scope is reflected in at least one task; nothing in scope is dropped.
 2. **Exclusive file ownership** — each file is owned by exactly one task. When two tasks must edit the same file,
@@ -16,9 +16,8 @@ Before writing the JSON output, verify EVERY item:
 6. **Verification criteria** — each task has 2–4 `verificationCriteria` that are testable and unambiguous.
    "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 repository paths provided above.
-8. **Signal output only** — the task array goes into the output signal named in your output contract below.
-   Do not emit the JSON array as prose or inside markdown fences — only the signal file is read by the
-   harness.
+8. **Signal output only** — the task array goes into the output signal named in your output contract below as JSON.
+   In chat you present it as the readable plan; 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
    `blockedBy` resolution; the harness assigns persistent ids on save).
 10. **Deterministic checks preferred** — each task includes at least one `auto` criterion when the

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

@@ -9,8 +9,6 @@ to commit or run verify yourself will conflict with the harness's commit, produc
 or a false verify result.
 </role>
 
-{{HARNESS_CONTEXT}}
-
 <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.
@@ -39,12 +37,6 @@ round that has already been applied; use it to avoid contradicting prior decisio
 {{FEEDBACK_LOG}}
 </feedback_log>
 
-<latest_round>
-This is the round to act on NOW. Read it carefully. Apply only what it asks.
-
-{{LATEST_ROUND}}
-</latest_round>
-
 <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
@@ -58,11 +50,16 @@ Snapshot of the sprint's `progress.md` — pinned learnings, decisions, and per-
 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. Surface insights inside the change itself via tests,
-docstrings, or the targeted edit.
+`note` signals — they are unused tokens in this flow.
 
 {{PROGRESS}}
 </progress>
+
+<latest_round>
+This is the round to act on NOW. Read it carefully. Apply only what it asks.
+
+{{LATEST_ROUND}}
+</latest_round>
 </inputs>
 
 <constraints>
@@ -84,8 +81,7 @@ underlying invariant or constraint instead (e.g. "exactly one confirmation per d
 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
-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.
+direction even when it reverses an earlier decision.
 </constraints>
 
 <capabilities>

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

@@ -11,8 +11,6 @@ Inspect the commit history and diff of `{{HEAD_BRANCH}}` against `{{BASE_BRANCH}
 `pr-content` signal to `signals.json` as described in the Output contract section below.
 </goal>
 
-{{HARNESS_CONTEXT}}
-
 <success_criteria>
 
 - The `title` and `body` follow the format and length rules in the Constraints section below.
@@ -80,9 +78,6 @@ Hard constraints:
 
 - Stay implementation-agnostic in the summary — name behaviour, not call sites.
 - 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 `{"schemaVersion": 1, "signals": []}` and stop. Do not invent PR
   content. The harness falls back to a template-derived description in that case.

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

@@ -4,12 +4,10 @@ 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>
 
-{{HARNESS_CONTEXT}}
-
 <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
-clearly separable module roots, ALSO propose structured per-module verify gates — one gate per
+clearly separable module roots, also propose structured per-module verify gates — one gate per
 module — so the harness can scope verification to the part of the tree a task actually touched.
 </goal>
 
@@ -22,7 +20,7 @@ module — so the harness can scope verification to the part of the tree a task
 - Per-module verify gates appear only when the repository has distinct module roots — a
   single-module repository proposes the verify script alone and no gates.
 - When the project's documented contract names a run command, a `note` signal describes it — see
-  the Protocol's Phase 1 step 5 and Phase 2 below for what counts and what the note must contain.
+  `<run_command_note>` below for what counts and what the note must contain.
 
 </success_criteria>
 
@@ -32,8 +30,10 @@ module — so the harness can scope verification to the part of the tree a task
 
 <constraints>
 
-**This invocation is read-only.** Do not modify the working tree, do not create files, do not run
-commands. The harness owns execution; the user reviews your proposal before anything runs.
+**This invocation is read-only — except for writing `signals.json`.** Do not modify the working tree,
+create other files, or run commands; read documentation instead of running a tool's `--help`. The
+harness owns execution; the user reviews your proposal before anything runs. Read only configuration
+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
@@ -49,7 +49,7 @@ confirm the stack, then propose root-level commands that build/verify the whole
 **Non-interactive flags for tools that colourise by default.** The harness captures the script's
 combined stdout/stderr to a plain-text log file. When the ecosystem's own build or test tool emits
 ANSI colour codes or interactive prompts by default, append that tool's own non-interactive /
-plain-console flag (check its own docs or `--help` for the exact name) unless the project's own docs
+plain-console flag (read its docs or config for the exact name) unless the project's own docs
 prescribe a different invocation. Modern Node / Python / Rust tooling respects `NO_COLOR` which the
 harness sets automatically, so no per-tool flag is needed there.
 
@@ -65,7 +65,8 @@ what the project documented. Omit a signal only when the project's own files are
 class entirely.
 
 **Script safety.** Reject pipe-to-shell shapes (`curl … | sh`, `wget -O- … | bash`), `eval`, and
-`rm -rf`. One shell line per script — multi-line bodies and heredocs are out of contract, and so
+`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
 are sub-shells except the single `(cd <path> && …)` fallback named above; the harness collapses
 whitespace before execution.
 
@@ -78,7 +79,7 @@ across a sprint.
 experienced contributor would run them locally. Use `&&` not `;`. Include test commands when the
 project's docs name them as part of the verification gate.
 
-**Per-module verify gates — monorepos only.** Emit the `verify-gates` signal ONLY when the
+**Per-module verify gates — monorepos only.** Emit the `verify-gates` signal only when the
 repository has clearly separable module roots: distinct build manifests living in their own
 subdirectories, each verifiable on its own. A single-module repository — one manifest at the root,
 or a workspace whose members are never checked independently — gets the verify script alone; never
@@ -92,11 +93,11 @@ emit gates for it. When gates apply:
   entry point as discovered from its manifest or the project's docs, never a command invented for
   it. Prefer the quiet / batch / non-interactive flag the ecosystem provides so the captured log
   stays clean, exactly as the verify script does.
-- The `verify-gates` signal is ADDITIVE — emit it alongside the `verify-script` signal, never
+- The `verify-gates` signal is additive — emit it alongside the `verify-script` signal, never
   instead of it. The script remains the whole-tree fallback the operator sees and the harness runs
   when a change touches no gated module; the gates scope verification when a change is confined to
   one module.
-- Add a catch-all gate with an empty-string `pathPrefix` ONLY when the repository defines a
+- Add a catch-all gate with an empty-string `pathPrefix` only when the repository defines a
   genuine cross-module integration check (e.g. a root-level end-to-end suite that exercises the
   modules together). Omit the catch-all when no such whole-tree check exists — the verify script
   already covers the unscoped case.
@@ -128,18 +129,15 @@ test`" and the manifest declares those scripts:
   "signals": [
     {
       "type": "setup-script",
-      "command": "<tool> install",
-      "timestamp": "..."
+      "command": "<tool> install"
     },
     {
       "type": "verify-script",
-      "command": "<tool> typecheck && <tool> lint && <tool> test",
-      "timestamp": "..."
+      "command": "<tool> typecheck && <tool> lint && <tool> test"
     },
     {
       "type": "note",
-      "text": "Commands lifted verbatim from the project's coding-agent context file.",
-      "timestamp": "..."
+      "text": "Commands lifted verbatim from the project's coding-agent context file."
     }
   ]
 }
@@ -153,18 +151,15 @@ When only a manifest exists with install + test scripts and no context file:
   "signals": [
     {
       "type": "setup-script",
-      "command": "<tool> install",
-      "timestamp": "..."
+      "command": "<tool> install"
     },
     {
       "type": "verify-script",
-      "command": "<tool> test",
-      "timestamp": "..."
+      "command": "<tool> test"
     },
     {
       "type": "note",
-      "text": "No context file found; commands inferred from manifest scripts.",
-      "timestamp": "..."
+      "text": "No context file found; commands inferred from manifest scripts."
     }
   ]
 }
@@ -179,18 +174,15 @@ names install + verify steps:
   "signals": [
     {
       "type": "setup-script",
-      "command": "<tool> install <tool's non-interactive flag>",
-      "timestamp": "..."
+      "command": "<tool> install <tool's non-interactive flag>"
     },
     {
       "type": "verify-script",
-      "command": "<tool> verify <tool's non-interactive flag>",
-      "timestamp": "..."
+      "command": "<tool> verify <tool's non-interactive flag>"
     },
     {
       "type": "note",
-      "text": "Commands lifted from the project's coding-agent context file; <tool's non-interactive flag> disables interactive prompts and ANSI colour for clean persisted logs.",
-      "timestamp": "..."
+      "text": "Commands lifted from the project's coding-agent context file; <tool's non-interactive flag> disables interactive prompts and ANSI colour for clean persisted logs."
     }
   ]
 }
@@ -207,13 +199,11 @@ point:
   "signals": [
     {
       "type": "setup-script",
-      "command": "<tool> install",
-      "timestamp": "..."
+      "command": "<tool> install"
     },
     {
       "type": "verify-script",
-      "command": "<tool> verify",
-      "timestamp": "..."
+      "command": "<tool> verify"
     },
     {
       "type": "verify-gates",
@@ -226,13 +216,11 @@ point:
           "pathPrefix": "services/web/",
           "command": "<tool> --filter web verify"
         }
-      ],
-      "timestamp": "..."
+      ]
     },
     {
       "type": "note",
-      "text": "Two independently-verifiable modules under services/; each gate runs that module's own check, the verify script remains the whole-tree fallback.",
-      "timestamp": "..."
+      "text": "Two independently-verifiable modules under services/; each gate runs that module's own check, the verify script remains the whole-tree fallback."
     }
   ]
 }
@@ -240,41 +228,20 @@ point:
 
 </example>
 
-## Protocol
-
-### Phase 1 — Inspection
-
-Before writing any output, cover, in order:
-
-1. The coding-agent context files you found and the commands they explicitly name. These are your
-   primary evidence source — list them before anything else.
-2. The manifest(s) you read, the package manager / language toolchain each implies, and the
-   `scripts` / task aliases it exposes.
-3. The shape of the repo: single-stack, single-language monorepo, or polyglot monorepo. For
-   polyglot layouts, name each sub-tree's path and toolchain.
-4. The candidate setup / verify commands, each with the file that documents it.
-5. The candidate run command — the command that starts the product in a running state for
-   interactive or end-to-end use (for example, a dev-server start script, an application
-   entry point, or an integration / smoke test runner). A run command is distinct from the
-   verify script: the verify script confirms correctness after a change; a run command starts
-   the live product so it can be exercised as a real user would. List the command and the file
-   that documents it.
-
-Then read only the configuration and metadata files in scope above. Do NOT read source trees,
-tests, vendored directories, or generated output.
-
-### Phase 2 — Drafting
+<run_command_note>
 
-For each candidate command, confirm the file that documents it. When a context file and a manifest
-both 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.
+A run command starts the product in a running state for interactive or end-to-end use (for example,
+a dev-server start script, an application entry point, or an integration / smoke test runner). It is
+distinct from the verify script: the verify script confirms correctness after a change; a run
+command starts the live product so it can be exercised as a real user would.
 
-When a run command was found in Phase 1 step 5, document it in a `note` signal: include the exact
-invocation, what it starts (dev server at which port, CLI binary, or e2e suite), and any
-environment 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 the project's files name one, document it in a `note` signal: include the exact invocation,
+what it starts (dev server at which port, CLI binary, or e2e suite), and any environment
+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.
 
-### Phase 3 — Output
+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.
 
-Write `signals.json` to the output directory as described in `<output_contract>` above.
+</run_command_note>

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

@@ -7,9 +7,9 @@ precision; every sentence must be grounded in something you read in the repo.
 
 <goal>
 Produce one `setup-skill-proposal` signal and one `verify-skill-proposal` signal for the repository
-at `{{REPOSITORY_PATH}}`, each containing a multi-paragraph markdown body, and write them to
-`signals.json` in the harness output directory. Omit a signal only when an existing skill already
-covers that responsibility for this repo.
+at `{{REPOSITORY_PATH}}`, each containing a short markdown body, and write them to `signals.json` in the harness output
+directory. Emit each signal unless an existing skill already covers that responsibility for this
+repo — if covered, emit a `note` instead.
 </goal>
 
 <success_criteria>
@@ -18,18 +18,15 @@ covers that responsibility for this repo.
   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, 4–10 short paragraphs each.
+- Skill bodies are written in second-person, present tense, 1–3 short paragraphs each.
 - `signals.json` is valid JSON that parses against the output contract schema.
 
 </success_criteria>
 
 <inputs>
 <repository_path>{{REPOSITORY_PATH}}</repository_path>
-<skills_convention_pointer>See the full skills convention in the constraints section below.</skills_convention_pointer>
 </inputs>
 
-{{HARNESS_CONTEXT}}
-
 <capabilities>
 You can read files anywhere in the repository at `{{REPOSITORY_PATH}}`. You cannot run shell commands,
 modify files, or create files — this invocation is read-only — except the single `signals.json` write
@@ -44,13 +41,13 @@ before anything lands.
 (`Makefile`, `justfile`, `Taskfile.yml`). These are the authoritative source. Beyond them, read only
 configuration and metadata files: manifests, lockfiles, build descriptors, tool-version pins, CI
 workflows, top-level `scripts/` entries. For monorepos, inspect the root and one or two representative
-sub-modules. Do NOT read source trees, tests, or vendored directories.
+sub-modules. Do not read source trees, tests, or vendored directories.
 
 **Check existing skills before drafting.** Use the convention below to list and inspect existing
 per-repo skills. If a skill already covers the sprint-setup or post-task-verification responsibility
-for this repo — even partially — omit the relevant signal and note it in a `note` signal so the
-operator can decide. Most repos will not have existing skills; their absence is the reason to emit,
-not a reason to omit.
+for this repo, omit the relevant signal and note it in a `note` signal so the operator can decide.
+Otherwise emit — partial or tangential coverage does not count, and most repos have no existing
+skills.
 
 <skills_convention>{{SKILLS_CONVENTION}}</skills_convention>
 
@@ -58,15 +55,15 @@ not a reason to omit.
 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 4–10 short paragraphs per skill. No headings inside the body (the harness wraps
+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 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.
 
-**Emit when there is any stack-specific quirk.** If the repo has a non-default toolchain, a
-tool-version pin, a lockfile policy, a monorepo sub-tree ordering dependency, or anything else that
-would trip up a generic AI session — emit the skill and document it.
+**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
+belongs in the skill body.
 
 </constraints>
 
@@ -101,8 +98,7 @@ Before drafting, cover, in order:
 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 read only the configuration and metadata files in scope above. Do NOT read source trees, tests,
-vendored directories, or generated output.
+Then read only the configuration and metadata files in scope above.
 
 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
@@ -113,8 +109,7 @@ should earn its place by being specific to this repo.
 <example>
 When the repository's context file documents the verify command and a tool-version pin file is present:
 
-```
-signals.json
+```json
 {
   "schemaVersion": 1,
   "signals": [

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

@@ -7,8 +7,9 @@ Your job is to integrate them cleanly, not to invent new ones.
 </role>
 
 <goal>
-Update `{{TARGET_FILENAME}}` so that it carries an up-to-date `## {{LEARNINGS_SECTION_HEADING}}` section containing
-the candidate learnings below — folded in idempotently, preserving everything else in the file verbatim.
+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
+it into the file and preserves everything else verbatim.
 </goal>
 
 <inputs>
@@ -17,26 +18,25 @@ the candidate learnings below — folded in idempotently, preserving everything
 <existing_context_file>
 {{EXISTING_CONTEXT_FILE}}
 </existing_context_file>
+An empty `<existing_context_file>` means the file does not exist yet — the harness will create it from your
+section body.
 
 <candidate_learnings>
 {{CANDIDATE_LEARNINGS}}
 </candidate_learnings>
 </inputs>
 
-{{HARNESS_CONTEXT}}
-
 <owned_section>
 You own exactly one section of `{{TARGET_FILENAME}}` — the one headed `## {{LEARNINGS_SECTION_HEADING}}`. This is
-the only part of the file you may add, reorder, or rewrite. Everything outside that section is
-hand-authored or owned by another tool — preserve it byte-for-byte.
+the only part of the file you produce. Everything outside that section is hand-authored or owned by another
+tool; the harness keeps it byte-for-byte, so do not reproduce it.
 
 - When the file already contains a `## {{LEARNINGS_SECTION_HEADING}}` section, treat its current bullets as the
-  prior state and reconcile the candidates against them (see the idempotency rule below).
-- When the file has no such section yet, append one at the end of the file — after the last existing
-  section, separated by a single blank line.
-- When `{{TARGET_FILENAME}}` does not exist yet, create it (and any missing parent directory) containing
-  only the owned section.
-- Never create a second `## {{LEARNINGS_SECTION_HEADING}}` section — there must be exactly one.
+  prior state and reconcile the candidates against them (see the idempotency rule below); your output replaces
+  that section's body.
+- When the file has no such section yet, your output becomes a new section appended at the end by the harness.
+- Output only the section body — no `## {{LEARNINGS_SECTION_HEADING}}` heading line, and no other headings of
+  level 1 or 2 (the harness rejects the proposal otherwise).
 
 </owned_section>
 
@@ -93,10 +93,12 @@ 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 the COMPLETE, updated `{{TARGET_FILENAME}}` back to disk at its original path — the full file, not
-   a diff and not only the section. Everything outside the owned section must be unchanged.
+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.
 
-Make no other edits to the repository. Emit no prose commentary outside the file you write — the harness
-reads the file from disk, not your message.
+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
+file you write — the harness reads that file, not your message.
 
 </output_contract>