ralphctl 0.14.1 → 0.15.0

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-07-01T15:36:24.783Z",
+  "generatedAt": "2026-07-03T20:19:33.217Z",
   "assets": [
     "prompts/_partials/conventions-agents-md.md",
     "prompts/_partials/conventions-claude-md.md",
@@ -23,10 +23,15 @@
     "prompts/refine/template.md",
     "skills/ralphctl-abstraction-first/SKILL.md",
     "skills/ralphctl-alignment/SKILL.md",
+    "skills/ralphctl-cherny-workflow/SKILL.md",
     "skills/ralphctl-code-review-and-quality/SKILL.md",
     "skills/ralphctl-debugging-and-error-recovery/SKILL.md",
+    "skills/ralphctl-domain-driven-design/SKILL.md",
+    "skills/ralphctl-idea-refinement/SKILL.md",
     "skills/ralphctl-iterative-review/SKILL.md",
+    "skills/ralphctl-karpathy-guidelines/SKILL.md",
     "skills/ralphctl-minimal-scaffolding/SKILL.md",
+    "skills/ralphctl-ponytail/SKILL.md",
     "skills/ralphctl-surgical-simplicity/SKILL.md",
     "skills/ralphctl-test-driven-development/SKILL.md"
   ]

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

@@ -10,7 +10,8 @@ invocation, not as a tutorial or README.
 - 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.
+- Hard line cap: 200 lines. Instruction adherence measurably degrades on longer context 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:

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

@@ -22,5 +22,9 @@ Before writing the JSON output, verify EVERY item:
    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
+    repository exposes a check command (test, typecheck, lint, or build). A task that relies solely on
+    `manual` criteria is acceptable only when it is pure documentation or investigation work with no
+    code change to check.
 
 </validation-checklist>

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

@@ -118,8 +118,8 @@ single `note` signal with a brief explanation and stop — do not invent command
 </output_contract>
 
 <example>
-When `CLAUDE.md` (or equivalent) contains "Verification: `<tool> typecheck && <tool> lint &&
-`<tool> test`" and the manifest declares those scripts:
+When `CLAUDE.md` (or equivalent) contains "Verification: `<tool> typecheck && <tool> lint && <tool>
+test`" and the manifest declares those scripts:
 
 ```json
 {

package/dist/prompts/evaluate/template.md

@@ -8,15 +8,7 @@ render a verdict.
 
 **Grading rubric (pinned here — applies every round regardless of context):**
 
-Every evaluation grades four floor dimensions. Each dimension is independent; a FAIL on any one forces
-`status: "failed"` on the signal regardless of how other dimensions score.
-
-| Dimension    | PASS when                                                                                                                | FAIL when                                                                             |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
-| Correctness  | Every verification criterion in `<task_specification>` is met, with evidence                                             | Any criterion unmet, or evidence is missing for a PASS claim                          |
-| Completeness | All declared steps present; all criteria addressed; no criterion silently skipped                                        | A step or criterion has no evidence in the findings                                   |
-| Safety       | No error paths that crash, swallow, or silently corrupt; no unvalidated inputs at trust boundaries; no leaked resources  | A concrete safety defect is observable in the diff                                    |
-| Consistency  | Change follows the project's existing patterns — naming, file organisation, error handling, test structure, import style | A sibling file or function shows a materially different pattern the generator ignored |
+{{FLOOR_RUBRIC_SECTION}}
 
 Additional dimensions appended by the planner (when present) are evaluated with the same binary pass/fail
 logic. The rubric from `<task_specification>` is the authority — grade against it, not against your own
@@ -51,9 +43,9 @@ forcing a `passed` you cannot support — a false `passed` ships a bug; a `malfo
 Conversely, do not reach for `malformed` to dodge a clear `failed`: if you can name a concrete failing
 criterion, the verdict is `failed` with a critique, never `malformed`.
 
-A terminal `passed` or `failed` verdict MUST grade all four floor dimensions (correctness, completeness,
-safety, consistency), each with a finding — a verdict missing a floor dimension is rejected by the harness and
-re-requested. `malformed` is exempt from that coverage requirement.
+A terminal `passed` or `failed` verdict MUST grade all five floor dimensions (correctness, completeness,
+safety, consistency, robustness), each with a finding — a verdict missing a floor dimension is rejected by the
+harness and re-requested. `malformed` is exempt from that coverage requirement.
 </role>
 
 {{HARNESS_CONTEXT}}
@@ -94,6 +86,12 @@ The block below mirrors that file for in-context reference.
 {{TASK_STEPS_SECTION}}
 {{VERIFICATION_CRITERIA_SECTION}}
 
+<prior_criteria_verdicts>{{PRIOR_CRITERIA_VERDICTS}}</prior_criteria_verdicts>
+
+The `<prior_criteria_verdicts>` block above — when non-empty — records the verdicts earlier rounds
+reached on this checklist. Treat it as context, not evidence: re-verify every criterion yourself this
+round and never carry a prior PASS forward without your own observation.
+
 </task_specification>
 
 <evaluation_discipline>
@@ -143,7 +141,7 @@ may write is `signals.json` under the harness output directory.
 
 ### Phase 0 — Checkpoint write (do this first, before any verification)
 
-Write `signals.json` now with placeholder verdicts — `status: "failed"`, all four floor dimensions
+Write `signals.json` now with placeholder verdicts — `status: "failed"`, all five floor dimensions
 present, each set to `passed: false` with `finding: "assessment in progress"`. Use the schema and
 path shown in the output contract section at the bottom of this prompt.
 
@@ -164,7 +162,8 @@ rather than restarting from scratch.
         { "dimension": "correctness", "passed": false, "finding": "assessment in progress" },
         { "dimension": "completeness", "passed": false, "finding": "assessment in progress" },
         { "dimension": "safety", "passed": false, "finding": "assessment in progress" },
-        { "dimension": "consistency", "passed": false, "finding": "assessment in progress" }
+        { "dimension": "consistency", "passed": false, "finding": "assessment in progress" },
+        { "dimension": "robustness", "passed": false, "applicable": false, "finding": "assessment in progress" }
       ],
       "timestamp": "<ISO-8601 timestamp>"
     }
@@ -172,6 +171,10 @@ rather than restarting from scratch.
 }
 ```
 
+Robustness carries the optional `applicable` field shown above — leave it as a placeholder here and
+set it to `false` only if Phase 4 determines the change touches no error/failure path (with the real
+reason in `finding`), or omit it (default `true`) once you grade an actual pass/fail.
+
 Write this file, then proceed to Phase 1.
 
 ### Phase 1 — Computational verification
@@ -246,8 +249,10 @@ observation — file path, line number, function name, tool output, or quoted sn
 
 ### Phase 4 — Dimension assessment
 
-Evaluate across the four floor dimensions. Write per-dimension findings as one PASS/FAIL verdict and 1–3
-specific observations each.
+Evaluate across the five floor dimensions rendered in the grading rubric pinned at the top of this
+prompt. Write per-dimension
+findings as one PASS/FAIL verdict (or `applicable: false` for robustness, when justified) and 1–3 specific
+observations each, anchored to the acceptance criteria and check/verify output you gathered in Phases 1–3.
 
 1. **Correctness** — does the implementation do what the specification says, across every verification
    criterion? Cite the criterion and the code that satisfies (or fails to satisfy) it.
@@ -258,6 +263,10 @@ specific observations each.
 4. **Consistency** — does the change follow the project's existing patterns and conventions (naming, file
    organisation, error handling, test structure, import style)? Cite a specific sibling file or function
    when the comparison matters.
+5. **Robustness** — does the change handle error and failure paths gracefully — unhandled exceptions,
+   missing error propagation, ungraceful degradation, recovery from transient faults? When the change
+   touches no error/failure path, grade this dimension `applicable: false` and state the concrete reason in
+   `finding` rather than fabricating a pass or fail.
 
 {{EXTRA_DIMENSIONS_SECTION}}
 
@@ -285,7 +294,8 @@ Criteria:
 - [C1] (auto) run the project's test suite filtered to the export module — all tests pass.
 - [C2] (manual) — invalid `startDate` value returns 400 with the project's standard error body.
 
-Phase 1: verify script exits 0 — recorded verbatim in `executionEvidence` for the Correctness dimension.
+Phase 1: ran C1's test command directly — exit 0, 12 tests green, recorded verbatim in
+`executionEvidence` for the Correctness dimension.
 
 Phase 2:
 
@@ -303,6 +313,8 @@ Phase 4 dimensions:
   to this task's criteria.
 - Safety — PASS — input validated via shared Zod schema at `src/routes/exports.ts:12` before DB access.
 - Consistency — PASS — follows existing endpoint patterns in `src/routes/`; uses the shared error format.
+- Robustness — N/A — the change only adds input validation with a standard 400 response; it introduces no
+  error/failure-recovery path (retries, rollback, degradation) beyond what Correctness already covers.
 
 Verdict: `status: "passed"`, no critique.
 
@@ -336,6 +348,12 @@ Signals:
           "dimension": "consistency",
           "passed": true,
           "finding": "follows existing endpoint patterns in src/routes/; uses the shared error format from src/lib/errors.ts"
+        },
+        {
+          "dimension": "robustness",
+          "passed": false,
+          "applicable": false,
+          "finding": "input-validation change only; no error/failure-recovery path beyond the 400 response Correctness already covers"
         }
       ],
       "criteria": [
@@ -359,7 +377,8 @@ Criteria:
 - [C1] (auto) run the project's test suite filtered to the user-search module — all tests pass.
 - [C2] (manual) — invalid page number returns 400.
 
-Phase 1: verify script exits 0.
+Phase 1: ran C1's test command directly — exit 0, 8 tests green, recorded verbatim in
+`executionEvidence`.
 
 Phase 2:
 
@@ -379,6 +398,9 @@ Phase 4 dimensions:
 - Safety — FAIL — `src/repositories/users.ts:23`: SQL injection via unparameterised template literal.
   Sibling `src/repositories/posts.ts:15` shows the correct pattern.
 - Consistency — PASS — controller structure follows existing patterns; pagination helper used correctly.
+- Robustness — FAIL — `src/controllers/users.ts:47` lets the `NaN` from `parseInt(page)` propagate
+  uncaught into the query layer instead of degrading gracefully (e.g. rejecting with a 400 before the
+  query runs); the same defect that breaks Correctness also breaks graceful error handling here.
 
 Verdict: `status: "failed"`, critique:
 
@@ -388,6 +410,9 @@ Verdict: `status: "failed"`, critique:
 - "[Safety] (a) safety, (b) `WHERE name LIKE '%${query}%'` at `src/repositories/users.ts:23` interpolates
   user input into SQL, (c) use a parameterised query with `$1` placeholder, (d)
   `src/repositories/users.ts:23`."
+- "[Robustness] (a) robustness, (b) `src/controllers/users.ts:47` lets an invalid `page` value propagate
+  as an uncaught exception instead of a handled 400, (c) validate `page` before use and return a graceful
+  400 on failure, (d) `src/controllers/users.ts:47`."
 
 Signals:
 
@@ -419,6 +444,11 @@ Signals:
           "dimension": "consistency",
           "passed": true,
           "finding": "controller structure follows existing patterns; pagination helper used correctly"
+        },
+        {
+          "dimension": "robustness",
+          "passed": false,
+          "finding": "src/controllers/users.ts:47 lets an invalid page value propagate as an uncaught exception instead of a handled 400"
         }
       ],
       "criteria": [
@@ -429,7 +459,7 @@ Signals:
           "evidence": "src/controllers/users.ts:47 returns 500 on non-numeric page (expected 400)"
         }
       ],
-      "critique": "[Correctness · C2] (a) correctness, (b) parseInt(page) at src/controllers/users.ts:47 returns NaN for non-numeric input causing 500, (c) validate page before use so invalid input returns 400, (d) src/controllers/users.ts:47. [Safety] (a) safety, (b) WHERE name LIKE '%${query}%' at src/repositories/users.ts:23 interpolates user input into SQL, (c) use a parameterised query, (d) src/repositories/users.ts:23.",
+      "critique": "[Correctness · C2] (a) correctness, (b) parseInt(page) at src/controllers/users.ts:47 returns NaN for non-numeric input causing 500, (c) validate page before use so invalid input returns 400, (d) src/controllers/users.ts:47. [Safety] (a) safety, (b) WHERE name LIKE '%${query}%' at src/repositories/users.ts:23 interpolates user input into SQL, (c) use a parameterised query, (d) src/repositories/users.ts:23. [Robustness] (a) robustness, (b) src/controllers/users.ts:47 lets an invalid page value propagate as an uncaught exception, (c) validate page before use and return a graceful 400, (d) src/controllers/users.ts:47.",
       "timestamp": "2026-01-01T00:00:00.000Z"
     }
   ]
@@ -448,7 +478,8 @@ Criteria:
 - [C2] (manual) — old session-cookie keys are no longer read anywhere in the codebase.
 - [C3] (manual) — session TTL is configurable via environment variable.
 
-Phase 1: verify script exits 0. Integration tests green.
+Phase 1: ran C1's test command directly — exit 0, 34 tests green, recorded verbatim in
+`executionEvidence`.
 
 Phase 2:
 
@@ -469,9 +500,12 @@ Phase 4 dimensions:
 - Safety — PASS — new session store uses the project's standard signing key from `src/config/secrets.ts`.
 - Consistency — PASS — middleware structure matches `src/middleware/csrf.ts`; config access follows the
   pattern in `src/middleware/rate-limit.ts`.
+- Robustness — PASS — `src/middleware/session.ts:31` catches store-lookup failures and falls back to
+  issuing a fresh anonymous session, matching the retry/fallback pattern already used in
+  `src/middleware/csrf.ts`.
 
-Note: the verify script passed. This round still fails because C3 is unimplemented. The verify suite does
-not test TTL configurability.
+Note: C1's test command passed. This round still fails because C3 is unimplemented — a passing test
+command does not confirm TTL configurability.
 
 Verdict: `status: "failed"`, critique:
 

package/dist/prompts/evaluate-continuation/template.md

@@ -11,12 +11,15 @@ fixed. Investigate the current working tree again.
 You do not write code. You do not fix bugs. You do not edit tests. You read, run verification
 tooling, and render a verdict.
 
-**Grading rubric (unchanged every round):** grade the four floor dimensions (correctness, completeness, safety, consistency)
-plus any task-specific dimensions the planner attached. Each dimension is independent; a FAIL on
-any one forces `status: "failed"`. Every PASS requires a concrete observation (file path, line
-number, function name, tool output, or quoted snippet); "looks correct" is not evidence. A terminal
-`passed` or `failed` verdict MUST grade all four floor dimensions, each with a finding — a verdict
-missing a floor dimension is rejected and re-requested.
+**Grading rubric (unchanged every round):**
+
+{{FLOOR_RUBRIC_SECTION}}
+
+Grade any task-specific dimensions the planner attached with the same binary pass/fail logic. Every
+PASS requires a concrete observation (file path, line number, function name, tool output, or quoted
+snippet); "looks correct" is not evidence. A terminal `passed` or `failed` verdict MUST grade all
+five floor dimensions, each with a finding — a verdict missing a floor dimension is rejected and
+re-requested.
 
 **Verdict values — `passed`, `failed`, `malformed`:** reach for `malformed` ONLY when a tooling or
 environment problem blocks you from reaching a terminal verdict this round — never to dodge a clear
@@ -74,7 +77,7 @@ end. The final `signals.json` is the only machine-readable output and must come
 **Checkpoint write — do this first, before re-grading**
 
 If you have not already written a checkpoint `signals.json` for this round, write an `evaluation`
-signal now before continuing. Use `status: "failed"`, all four floor dimensions present, each set
+signal now before continuing. Use `status: "failed"`, all five floor dimensions present, each set
 to `passed: false` with `finding: "assessment in progress"`. Use the path named in the output
 contract section at the bottom of this prompt. This placeholder is valid against the schema the
 harness validates — it ensures a recoverable file exists on disk if this session exhausts its
@@ -92,7 +95,8 @@ below.
         { "dimension": "correctness", "passed": false, "finding": "assessment in progress" },
         { "dimension": "completeness", "passed": false, "finding": "assessment in progress" },
         { "dimension": "safety", "passed": false, "finding": "assessment in progress" },
-        { "dimension": "consistency", "passed": false, "finding": "assessment in progress" }
+        { "dimension": "consistency", "passed": false, "finding": "assessment in progress" },
+        { "dimension": "robustness", "passed": false, "applicable": false, "finding": "assessment in progress" }
       ],
       "timestamp": "<ISO-8601 timestamp>"
     }
@@ -100,6 +104,10 @@ below.
 }
 ```
 
+Robustness carries the optional `applicable` field shown above — set it to `false` only if
+re-grading determines the change touches no error/failure path (with the real reason in
+`finding`), or omit it (default `true`) once you record an actual pass/fail.
+
 Re-grade this round the same way you graded the first:
 
 1. Re-run each `auto` criterion's command directly and record the verbatim output. Do NOT run the
@@ -121,4 +129,98 @@ Do not run `git stash`, `git add`, or `git commit` — those are write operation
 may write is the `signals.json` named in the output contract below.
 </protocol>
 
+<examples>
+
+<example id="1" label="FAIL — a criterion that passed in round 1 regresses in round 2">
+
+Task: "Add rate limiting to the public API"
+
+Criteria:
+
+- [C1] (auto) run the project's test suite filtered to the rate-limit module — all tests pass.
+- [C2] (manual) — requests over the limit return 429 with a `Retry-After` header.
+
+Round 1 (already in this conversation's history): `status: "failed"` — C1 passed, C2 failed because
+no `Retry-After` header was present.
+
+Round 2 (this call) — re-ran C1's test command directly: exit 1, one failure — `rate-limit.test.ts:34`
+now fails because the request counter increments twice per request. Verbatim output recorded in
+`executionEvidence`. Re-inspected the diff: `src/middleware/rate-limit.ts:52` calls `store.increment()`
+a second time while building the new header, on top of the existing increment in the limit check.
+
+Re-assessment: C1 regressed from PASS (round 1) to FAIL (round 2) — the header fix double-counts
+requests against the limit. C2 is now PASS — `src/middleware/rate-limit.ts:60` sets `Retry-After` from
+the store's TTL, matching the criterion. Correctness fails on the C1 regression; Completeness, Safety,
+and Consistency pass; Robustness is `applicable: false` — the change touches only a counter increment,
+no new error/failure-recovery path.
+
+Verdict: `status: "failed"`, critique:
+
+- "[Correctness · C1] (a) correctness, (b) `store.increment()` at `src/middleware/rate-limit.ts:52` now
+  runs twice per request — once for the limit check, once while building the `Retry-After` header —
+  doubling the effective rate-limit consumption and failing `rate-limit.test.ts:34` (this criterion
+  passed in round 1; the header fix introduced the regression), (c) compute `Retry-After` from the
+  existing counter value without incrementing again, (d) `src/middleware/rate-limit.ts:52`."
+
+Signals:
+
+```json
+{
+  "schemaVersion": 1,
+  "signals": [
+    {
+      "type": "evaluation",
+      "status": "failed",
+      "dimensions": [
+        {
+          "dimension": "correctness",
+          "passed": false,
+          "finding": "C1 regressed: store.increment() at src/middleware/rate-limit.ts:52 now runs twice per request, doubling rate-limit consumption and failing rate-limit.test.ts:34.",
+          "executionEvidence": "<test command output>"
+        },
+        {
+          "dimension": "completeness",
+          "passed": true,
+          "finding": "both criteria now have an implementation attempt; C2's header fix is present"
+        },
+        {
+          "dimension": "safety",
+          "passed": true,
+          "finding": "no new trust-boundary issue introduced by the header change"
+        },
+        {
+          "dimension": "consistency",
+          "passed": true,
+          "finding": "header logic follows the existing middleware pattern in src/middleware/csrf.ts"
+        },
+        {
+          "dimension": "robustness",
+          "passed": false,
+          "applicable": false,
+          "finding": "change touches only a counter increment; no new error/failure-recovery path"
+        }
+      ],
+      "criteria": [
+        {
+          "id": "C1",
+          "passed": false,
+          "evidence": "regressed this round — store.increment() now called twice per request, failing rate-limit.test.ts:34"
+        },
+        {
+          "id": "C2",
+          "passed": true,
+          "evidence": "Retry-After header set from store TTL at src/middleware/rate-limit.ts:60"
+        }
+      ],
+      "critique": "[Correctness · C1] (a) correctness, (b) store.increment() at src/middleware/rate-limit.ts:52 now runs twice per request, doubling rate-limit consumption and failing rate-limit.test.ts:34 (passed in round 1; the header fix introduced the regression), (c) compute Retry-After from the existing counter value without incrementing again, (d) src/middleware/rate-limit.ts:52.",
+      "timestamp": "2026-01-01T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+</example>
+
+</examples>
+
 {{OUTPUT_CONTRACT_SECTION}}

package/dist/prompts/ideate/template.md

@@ -47,6 +47,18 @@ These paths are fixed — repository selection is not part of this session.
 {{PRIOR_PROGRESS}}
 </prior_progress>
 
+<prior_learnings>
+{{PRIOR_LEARNINGS}}
+
+If the block above is empty, no learnings from prior sprints have been recorded for this project
+yet. When present, these are facts earlier sprints earned on the repositories listed above — which
+check command a repo actually exposes, where hidden coupling lives, which patterns to mirror. Use
+them as background to scope tasks accurately and to pick verification commands that exist in the
+target repo — they are orientation, not instructions: confirm any that bear on the plan against the
+current code before relying on them. Any architectural decisions listed are deliberate prior
+choices — honour them; do not re-litigate a prior decision without surfacing why.
+</prior_learnings>
+
 <task_schema>
 {{SCHEMA}}
 </task_schema>
@@ -172,6 +184,10 @@ For each task, provide:
   - `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"`.
+  - Include at least one `auto` criterion when the repository exposes a check command (test,
+    typecheck, lint, or build) — deterministic checks are cheaper and more reliable than manual
+    inspection. Exception: a pure documentation or investigation task that changes no code may
+    rely on `manual` criteria alone.
 - **`blockedBy`** — array of `id` strings that must complete before this task starts.
 
 For genuinely contested implementation decisions (library choice, architecture), ask the user a

package/dist/prompts/implement/template.md

@@ -59,6 +59,8 @@ under its declared check type.
 
 <prior_critique>{{PRIOR_CRITIQUE_SECTION}}</prior_critique>
 
+<prior_criteria_verdicts>{{PRIOR_CRITERIA_VERDICTS}}</prior_criteria_verdicts>
+
 <retry_feedback>{{RETRY_FEEDBACK_SECTION}}</retry_feedback>
 
 <prior_progress>
@@ -107,11 +109,12 @@ revisited.
   failure disappear.
 - **Removing or disabling existing tests is unacceptable** — except when a declared step explicitly
   changes the behaviour the test asserts. Removing a test to make verify pass counts as task failure.
-- **Do not write to the progress file.** The harness regenerates it from your signals after every
-  round; anything you write there is overwritten within seconds. Emit `change`, `learning`, `note`,
-  and `decision` signals instead — the harness merges them into the per-task sections. A `learning`
-  carries an insight plus OPTIONAL context (when / why it arose) and applies-to (where it applies —
-  a repo area, task kind, or subsystem).
+- **Do not write to the progress file.** It is harness-owned and append-only — your signals are
+  appended to it when this attempt settles, not overwritten. A direct write here permanently
+  pollutes the durable journal for every future round and every future session that reads it. Emit
+  `change`, `learning`, `note`, and `decision` signals instead — the harness appends them into the
+  per-task sections. A `learning` carries an insight plus OPTIONAL context (when / why it arose) and
+  applies-to (where it applies — a repo area, task kind, or subsystem).
 - **No sprint-local identifiers in committed artefacts.** Do not mention acceptance-criterion labels
   (`AC1`, `AC2`), ticket numbers, task IDs, or sprint IDs in source files, comments, docstrings, test
   names, commit messages, or any other committed artefact. These identifiers are ephemeral sprint
@@ -242,7 +245,11 @@ In order:
    The harness commits after this turn using your wording verbatim. The fallback when you omit the
    signal is just the task name and description paragraph — thin context. Emit it on every task that
    touched any file. Omit only when the task was a pure investigation that wrote nothing.
-6. **Signal completion** — emit `task-complete` ONLY after all the above steps pass.
+6. **Signal completion** — emit `task-complete` ONLY after all the above steps pass. Then, as the
+   very LAST action of this turn, write exactly ONE file — `signals.json` — to the absolute path
+   named in the Output contract section below. That file is the ONLY channel the harness reads:
+   your code changes and your messages are invisible to it, so a turn that skips this write is
+   treated as producing no work at all, no matter how much you did.
 
 ## Failure modes
 

package/dist/prompts/plan/template.md

@@ -51,7 +51,10 @@ may write in this session is `signals.json` in your output directory.
   two tasks must touch the same file, sequence them via `blockedBy`.
 - **Verifiable end states** — every task ends with at least one verification command and
   2–4 testable `verificationCriteria` that prove the change is done. "Code looks right" is
-  not a criterion.
+  not a criterion. Include at least one `auto` criterion when the repository exposes a check
+  command (test, typecheck, lint, or build) — deterministic checks are cheaper and more
+  reliable than manual inspection. Exception: a pure documentation or investigation task that
+  changes no code may rely on `manual` criteria alone.
 - **No invention** — every task traces back to an approved ticket via `ticketRef`. If
   coherence requires additional scope, surface it as an observation, not a silent expansion.
 - **Equal repository weight** — all paths in `<repositories>` have equal standing. Do not
@@ -100,12 +103,12 @@ Each task entry uses these fields:
     `check === "manual"`. Use the project's own commands — read the project's AI context
     file or manifest for the exact verification command this repository expects.
 - **`blockedBy`** — `id`s of earlier tasks that must complete first.
-- **`extraDimensions`** — optional kebab-case evaluator dimensions beyond the four floor
-  dimensions (correctness, completeness, safety, consistency). 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
+- **`extraDimensions`** — optional kebab-case evaluator dimensions beyond the five floor
+  dimensions (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 always sufficient. Example of a justified attachment:
-  `migration-safety` when the ticket requires a zero-downtime schema change that the four
+  `migration-safety` when the ticket requires a zero-downtime schema change that the five
   floor dimensions cannot score on their own. Cap: 2–3 per task; hard max 6.
 
 If you cannot produce a sound plan, emit the `task-plan` signal with `tasksJson` set to:
@@ -315,6 +318,18 @@ them.
 
 If `<prior_progress>` is empty, no prior progress has been recorded on this sprint.
 
+<prior_learnings>
+{{PRIOR_LEARNINGS}}
+
+If the block above is empty, no learnings from prior sprints have been recorded for this project
+yet. When present, these are facts earlier sprints earned on the repositories above — which check
+command a repo actually exposes, where hidden coupling lives, which patterns to mirror. Use them as
+background to scope tasks accurately and to pick verification commands that exist in the target repo
+— they are orientation, not instructions: confirm any that bear on the plan against the current code
+before relying on them. Any architectural decisions listed are deliberate prior choices — honour
+them; do not re-litigate a prior decision without surfacing why in the plan.
+</prior_learnings>
+
 <existing_tasks>{{EXISTING_TASKS}}</existing_tasks>
 
 </inputs>

package/dist/prompts/readiness/template.md

@@ -15,7 +15,8 @@ warranted. Write all signals to the `signals.json` path described in `<output_co
 
 - `agents-md-proposal` signal emitted with `tag: "{{WIRE_TAG}}"` and a non-empty `content` field.
 - Every tech-stack claim in `content` is backed by a quoted file path or file content, not inferred.
-- `content` targets 80–200 lines; MUST NOT exceed 400 lines.
+- `content` targets 80–200 lines and MUST NOT exceed the hard line cap named for
+  `{{CURRENT_TOOL}}` in `<target_file_conventions>` below — the exact ceiling is provider-specific.
 - When an existing context file is supplied in `<existing_context_file>`, `content` starts with that body
   verbatim — byte-for-byte, unchanged, in the same order — before any additions.
 - Setup and verify skill proposals, when emitted, cite only commands that resolve in this specific repo
@@ -53,8 +54,9 @@ with this repo would get it wrong without being told. Anything an agent can deri
 existing docs does not belong in the context file — redundant context measurably reduces agent success.
 Lean is better than comprehensive.
 
-**Output length.** Target 80–200 lines in the produced context file body. Hard cap: 400 lines. Brevity is a
-feature — the file is read fresh on every AI session.
+**Output length.** Target 80–200 lines in the produced context file body. The hard line cap is
+provider-specific — read the exact ceiling from `<target_file_conventions>` below and never exceed it.
+Brevity is a feature — the file is read fresh on every AI session.
 
 **Structure caps.** Exactly one H1; at most 7 H2 sections; no H4 or deeper headings. Prefer bullets and
 short sentences.

package/dist/skills/ralphctl-alignment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ralphctl-alignment
-description: Cross-phase skill — establish a shared understanding of what will and will not be done before producing output. Restate the input back to the user; surface assumptions; agree before you write.
+description: Cross-phase skill — establish a shared understanding of what will and will not be done before producing output: restate the input back to the user, surface assumptions, name non-goals, and agree before you write. For an input that is still a raw, unshaped idea needing multiple candidate directions before one is chosen, run the ralphctl-idea-refinement skill first when it is installed in this session; alignment then confirms whichever direction comes out of it.
 ---
 
 # Alignment

package/dist/skills/ralphctl-cherny-workflow/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: ralphctl-cherny-workflow
+description: Session-discipline skill — settle the plan before touching code, work in small verified increments with a feedback loop that proves each change works, and record corrections so the same mistake is not repeated. Use when executing multi-step coding tasks where batching unverified work would compound risk; bundles plan-first sequencing and learning capture on top of the narrower per-change habits in ralphctl-iterative-review and (when installed) ralphctl-karpathy-guidelines.
+---
+
+# Cherny Workflow
+
+> Distilled from Boris Cherny's (creator of Claude Code) publicly shared workflow practices —
+> his January 2026 ["How I use Claude Code" thread](https://x.com/bcherny/status/2007179832300581177).
+> Clean-room — concepts only, not copied text; interactive-only tips (parallel terminals,
+> permission tuning, editor integration) are deliberately omitted.
+
+Two habits carry most of the value of this workflow: separate planning from execution, and give
+every change a way to prove itself. Cherny's strongest claim is about the second — a working
+verification loop multiplies the quality of the final result, because each increment is either
+demonstrated or rolled back while it is still small.
+
+## When this applies
+
+- **Execute** — the primary home: any task with more than one meaningful step, and any change where "did that actually work?" has a checkable answer.
+- **Create PR** — the summary step: the description writes itself when the work was a sequence of verified increments instead of one opaque batch.
+
+## Plan before code
+
+- Do not start editing until the plan is settled: which files change, in what order, and what proves each step worked. When the task arrives with a plan or acceptance criteria, restate them as your working plan; when it doesn't, write the plan as your first output.
+- Going back and forth on the plan is cheap; going back and forth on a half-applied diff is not. Revise the plan while it is still words.
+- Once the plan is settled, execution should be unremarkable — a step that surprises you is a signal to stop and re-plan, not to improvise forward.
+
+## The verification loop
+
+- Before each step, know its check: the test that should pass, the command that should exit cleanly, the behaviour that should be observable. A step without a check is not ready to execute.
+- Run the check immediately after the step — never accumulate several unverified steps, because a late failure then points at all of them at once.
+- Prefer the narrowest check that can falsify the step (one test file, one build target, one focused run) over broad suites; breadth comes at the end, and the harness owns the final post-task verify gate.
+- When no automated check exists for a step, create the smallest one that would fail if the step were wrong — or state explicitly in a `<note>` signal that the step is unverified and why.
+
+## Small verified increments
+
+- Shape the work so that after every increment the project is in a working state — each one a checkpoint the harness can capture, not a stretch of shared broken ground.
+- If an increment cannot be made safely small (a rename that touches everything, a schema change), isolate it as its own step with its own check, and keep unrelated edits out of it.
+- Re-read your own diff at each checkpoint: is everything in it intentional, and does anything in it belong to a different step?
+
+## Compounding corrections
+
+- When you discover a project-specific gotcha — a convention that contradicted your instinct, a command that behaves unexpectedly, a fix for a recurring failure — record it as a `<learning>` signal so it persists beyond this session.
+- The habit mirrors how Cherny's team maintains their agent-facing project docs: every observed mistake becomes a written correction, so the same steering is never needed twice.
+- Record the correction at the moment you learn it — deferred notes don't get written; the exception is mid-verification, where finishing the check comes first.
+
+## Anti-patterns
+
+- **Code-first sessions.** Editing before the plan exists, then discovering the approach was wrong three files in.
+- **Batch-then-pray.** Making five changes and running one big check at the end — the failure points everywhere and nowhere.
+- **Checkless steps.** "This one's trivial" is how unverified changes slip through; trivial steps have trivial checks.
+- **Silent re-learning.** Hitting the same project quirk twice because the first encounter was never recorded.
+- **Plan drift.** Quietly doing something other than the settled plan; when reality invalidates the plan, update it visibly first.
+
+## Self-check before finishing
+
+- [ ] The executed steps match the settled plan — or the plan was explicitly revised along the way.
+- [ ] Every step's check ran and passed at the time the step was made.
+- [ ] The final diff reads as a sequence of intentional increments, with nothing unexplained.
+- [ ] Any durable gotcha discovered this session was recorded as a `<learning>` signal.

package/dist/skills/ralphctl-debugging-and-error-recovery/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ralphctl-debugging-and-error-recovery
-description: Systematic root-cause debugging. Use when tests fail, builds break, or behaviour does not match expectations. Follow stop-the-line → reproduce → localize → reduce → root-cause → guard-with-regression-test → verify, not guessing.
+description: Systematic root-cause debugging. Use when tests fail, builds break, or behaviour does not match expectations. Follow stop-the-line → reproduce → localize → reduce → root-cause → guard-with-regression-test → verify, not guessing; the reproduction and regression steps follow the same red-green discipline as ralphctl-test-driven-development.
 license: MIT
 ---