ralphctl 0.8.5 → 0.9.0

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-05-29T08:41:52.856Z",
+  "generatedAt": "2026-06-01T11:52:30.706Z",
   "assets": [
     "prompts/_partials/conventions-agents-md.md",
     "prompts/_partials/conventions-claude-md.md",
@@ -12,6 +12,7 @@
     "prompts/create-pr/template.md",
     "prompts/detect-scripts/template.md",
     "prompts/detect-skills/template.md",
+    "prompts/distill-learnings/template.md",
     "prompts/evaluate/template.md",
     "prompts/ideate/template.md",
     "prompts/implement/template.md",

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

@@ -0,0 +1,98 @@
+<role>
+You are an AI coding agent performing a single-shot documentation edit. Your sole job for this call is to
+fold a set of curated, machine-collected learnings into this project's existing context file —
+`{{TARGET_FILENAME}}` — so that future AI sessions on this repository inherit what earlier sessions
+discovered. You are an editor, not a researcher; every learning has already been produced and reviewed.
+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 (ralphctl)` section containing
+the candidate learnings below — folded in idempotently, preserving everything else in the file verbatim.
+</goal>
+
+<inputs>
+<target_filename>{{TARGET_FILENAME}}</target_filename>
+
+<existing_context_file>
+{{EXISTING_CONTEXT_FILE}}
+</existing_context_file>
+
+<candidate_learnings>
+{{CANDIDATE_LEARNINGS}}
+</candidate_learnings>
+</inputs>
+
+{{HARNESS_CONTEXT}}
+
+<owned_section>
+You own exactly one section of `{{TARGET_FILENAME}}` — the one headed `## Learnings (ralphctl)`. 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.
+
+- When the file already contains a `## Learnings (ralphctl)` 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.
+- Never create a second `## Learnings (ralphctl)` section — there must be exactly one.
+  </owned_section>
+
+<idempotency_rule>
+The folding MUST be idempotent — running this call twice on the same inputs leaves the file identical the
+second time:
+
+- 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.
+- Genuinely new candidates are appended as new bullets.
+- Existing bullets that no candidate touches stay exactly as they are.
+  </idempotency_rule>
+
+<curation_rules>
+
+**Faithfulness.** Each candidate is a learning a prior session recorded — fold its substance in, lightly
+edited for clarity and tense, but do not change its claim. Do not add learnings that are not in the
+candidate list.
+
+**Format.** Each learning is a bold Insight bullet — a single sentence, present tense, second-person or
+imperative voice ("Prefer X over Y", "The build emits Z") — optionally followed by indented `Context:` and
+`Applies to:` sub-bullets when the candidate supplies them:
+
+- **The build emits ESM only; no CJS entrypoint.**
+  - Context: wiring a downstream require()
+  - Applies to: packaging
+
+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.
+
+**Tooling references.** When a learning names a build, test, or task command, phrase it against this
+project's tooling — described here:
+
+<project_tooling>
+{{PROJECT_TOOLING}}
+</project_tooling>
+
+Reference the actual commands that section names; do not substitute commands from another ecosystem. When
+the section is empty, describe the action in prose rather than guessing a command.
+
+**Repository conventions.** Reference repository convention directories — such as a `.claude/` directory —
+as "when present"; many repositories do not have one, and a learning must not assume it exists.
+
+</curation_rules>
+
+<output_contract>
+
+1. Read the existing context file body above and locate the `## Learnings (ralphctl)` 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.
+
+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.
+
+</output_contract>

package/dist/prompts/implement/template.md

@@ -89,7 +89,9 @@ sprint.
   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.
+  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).
 - **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

package/dist/skills/ralphctl-abstraction-first/SKILL.md

@@ -6,6 +6,7 @@ description: Cross-phase skill — design the shape of the change (entities, bou
 # Abstraction-First
 
 > Concept
+>
 > from [Martin Fowler — "Abstraction-First"](https://martinfowler.com/articles/structured-prompt-driven/abstraction-first.html).
 > Adapted for ralphctl's three phases.
 

package/dist/skills/ralphctl-iterative-review/SKILL.md

@@ -6,6 +6,7 @@ description: Cross-phase skill — treat AI output as a controlled feedback loop
 # Iterative Review
 
 > Concept
+>
 > from [Martin Fowler — "Iterative Review"](https://martinfowler.com/articles/structured-prompt-driven/iterative-review.html).
 > Adapted for ralphctl's three phases.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphctl",
-  "version": "0.8.5",
+  "version": "0.9.0",
   "description": "Agent harness for long-running AI coding tasks — orchestrates Claude Code, GitHub Copilot, and OpenAI Codex across repositories",
   "homepage": "https://github.com/lukas-grigis/ralphctl",
   "type": "module",
@@ -38,15 +38,19 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "commander": "^14.0.3",
+    "commander": "^15.0.0",
+    "cross-spawn": "^7.0.6",
     "ink": "^7.0.3",
+    "proper-lockfile": "^4.1.2",
     "react": "^19.2.6",
     "typescript-result": "^3.5.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@types/cross-spawn": "^6.0.6",
     "@types/node": "^25.8.0",
+    "@types/proper-lockfile": "^4.1.4",
     "@types/react": "^19.2.14",
     "@vitest/coverage-v8": "^4.1.6",
     "eslint": "^10.4.0",