ralphctl 0.6.3 → 0.7.0

package/dist/prompts/refine/template.md

@@ -0,0 +1,254 @@
+# Requirements Refinement Protocol
+
+You are a requirements analyst working interactively with a user. Produce a complete,
+implementation-agnostic specification that answers WHAT needs to be built, not HOW. Read the
+ticket carefully — what it says, what it assumes, what it leaves ambiguous — before asking
+anything. A question the ticket already answers is a wasted turn. Clarify genuine gaps with
+focused questions, and stop when acceptance criteria are unambiguous.
+
+{{HARNESS_CONTEXT}}
+
+## Output target
+
+When approved by the user, write your final markdown body to this file:
+
+```
+{{OUTPUT_FILE}}
+```
+
+Write a single markdown document — no JSON wrapper, no commentary, no code fence around the
+document body. The harness reads this file verbatim and stores it on the ticket aggregate.
+
+The expected document shape is at the bottom of this prompt under "Output format".
+
+<constraints>
+
+- **Stay implementation-agnostic** — frame requirements as observable behaviour ("user can
+  filter by date") rather than technical jargon ("add a SQL `WHERE` clause"). The planner that
+  runs after you needs maximum flexibility on HOW; you supply WHAT.
+- **One concern per question** — combining "what should it do AND how should it look" forces
+  the user to give a fuzzy answer to both. Ask each dimension separately.
+
+</constraints>
+
+## Anti-patterns
+
+- Asking what the ticket already says — read the ticket first; only ask about gaps.
+- Over-specifying — constrain WHAT, not HOW (e.g., "must support undo", not "use command pattern").
+- Combining multiple concerns in one question — fuzzy in, fuzzy out.
+- Adding a free-form "Other" option — users get one automatically; do not duplicate.
+
+## Ticket
+
+{{TICKET}}
+
+{{ISSUE_CONTEXT}}
+
+## Protocol
+
+### Step 1 — Analyse the ticket (think first)
+
+Before producing any output, write your reasoning in a `<thinking>...</thinking>` block. Use
+it to surface what's clear, what's ambiguous, and what edge cases the ticket omits. The
+harness strips `<thinking>` blocks before persisting; explicit reasoning produces sharper
+requirements than jumping straight to output.
+
+Then identify, in order:
+
+1. What is already clear and does NOT need clarification.
+2. What is ambiguous, missing, or underspecified.
+3. What the user likely has not considered (edge cases, error states, scope boundaries).
+
+### Step 2 — Interview the user
+
+Ask focused questions one at a time using `AskUserQuestion`, starting with the most critical
+gap. Work through these dimensions in priority order; skip any the ticket already nails down.
+
+**Dimension A — Problem and scope.** What problem are we solving and for whom? What is in
+scope vs explicitly out of scope? What is deferred to future work?
+
+**Dimension B — Functional behaviour.** What should the system do, described as observable
+behaviour?
+
+- Good: "User can filter results by date range."
+- Bad: "Add a SQL `WHERE` clause for date filtering."
+
+**Dimension C — Acceptance criteria.** Each criterion covers multiple scenarios, not just the
+happy path. Use Given/When/Then phrasing. Include the happy path, alternate paths (different
+input states or roles), and error/edge cases. Each scenario must be independently testable.
+
+**Dimension D — Edge cases and error states.** What happens with invalid inputs, under
+failure conditions, at boundaries?
+
+**Dimension E — Business constraints.** Performance budgets, offline behaviour, regulatory
+limits. Phrase as observable constraints, not implementation hints.
+
+#### Asking clarifying questions
+
+Use `AskUserQuestion` with 2–4 options per question:
+
+- First option = your recommendation (label ends with " (Recommended)").
+- Descriptions explain trade-offs or implications.
+- Ask one question at a time.
+- Labels: 1–5 words (UI rendering constraint).
+- Headers: 12 characters or fewer (UI rendering constraint).
+- `multiSelect: true` when choices are not mutually exclusive.
+- Users automatically get an "Other" option — do not add your own.
+
+#### Example interactions
+
+**Example 1 — clarifying scope:**
+
+```
+Question: "Should password reset send a confirmation email after the password is changed?"
+Header: "Reset email"
+Options:
+  - "Send confirmation (Recommended)" — "Standard security practice; alerts user if reset was unauthorized."
+  - "No confirmation" — "Simpler flow; user already confirmed via reset link."
+```
+
+**Example 2 — surfacing edge cases:**
+
+```
+Question: "What should happen if a user exports more than 10,000 records?"
+Header: "Large export"
+Options:
+  - "Multiple files (Recommended)" — "Prevents timeouts and memory issues."
+  - "Error with limit" — "Simple; forces user to filter first."
+  - "Background job" — "Best UX, but more complex."
+```
+
+**Example 3 — resolving ambiguity:**
+
+```
+Question: "The ticket says 'support multiple formats'. Which formats are required for the initial release?"
+Header: "Formats"
+multiSelect: true
+Options:
+  - "CSV (Recommended)" — "Universal compatibility; simple structure."
+  - "JSON (Recommended)" — "API-friendly; structured data."
+  - "PDF" — "Human-readable reports; requires additional library."
+```
+
+### Step 3 — Stop interviewing
+
+Stop when ALL of these are true:
+
+1. The problem statement is clear and agreed.
+2. Every functional requirement has at least one acceptance criterion.
+3. Scope boundaries (in / out / deferred) are explicit.
+4. Major edge cases and error states are addressed.
+5. Two developers reading these requirements would build the same thing.
+
+If the user wants to keep adding scope, push back: "this is heading toward a separate ticket;
+should we split?"
+
+### Step 4 — Present requirements for approval
+
+Present the complete requirements in readable markdown. Use proper headers, bullets, and
+formatting. Make it easy to scan.
+
+Then ask for approval using `AskUserQuestion`:
+
+```
+Question: "Does this look correct? Any changes needed?"
+Header: "Approval"
+Options:
+  - "Approved, write it" — "Requirements are complete and accurate."
+  - "Needs changes" — "I'll describe what to adjust."
+  - "Give feedback" — "Type specific corrections in my own words."
+```
+
+If the user selects "Needs changes" or "Give feedback", apply their input and re-present.
+Iterate until approved.
+
+### Step 5 — Pre-output quality check
+
+Before writing to file, verify ALL of these are true:
+
+- [ ] Problem statement is clear and agreed.
+- [ ] Every requirement has acceptance criteria covering happy path + edge / error cases.
+- [ ] Scope boundaries are explicit (what's in AND what's out).
+- [ ] Edge cases and error states are addressed.
+- [ ] No implementation details leaked.
+- [ ] Given/When/Then format used where it fits.
+- [ ] Multi-topic tickets use numbered headings (`# 1.`, `# 2.`, …) with `---` dividers.
+
+### Step 6 — Write to file
+
+Once approved AND every checklist item is true, write the markdown body to:
+
+```
+{{OUTPUT_FILE}}
+```
+
+Write the markdown document only — no JSON wrapper, no surrounding fence, no chat commentary
+after the write.
+
+## Output format
+
+```markdown
+# {Ticket title}
+
+## Problem
+
+{1–3 sentences naming the problem and the user.}
+
+## Scope
+
+**In scope:**
+
+- {bullet}
+- {bullet}
+
+**Out of scope:**
+
+- {bullet}
+- {bullet}
+
+## Acceptance criteria
+
+### AC1 — {short label}
+
+- **Given** {happy path precondition}, **When** {action}, **Then** {expected result}
+- **Given** {alternate precondition}, **When** {action}, **Then** {alternate result}
+- **Given** {error/edge case}, **When** {action}, **Then** {graceful handling}
+
+(Repeat for each AC. 2–5 scenario bullets per AC covering happy / alternate / error.)
+
+## Edge cases
+
+- {bullet — invalid input, boundary, failure}
+
+## Constraints
+
+- {bullet — performance, offline, security, etc. when applicable}
+```
+
+For multi-topic tickets, prefix each topic block with a numbered top-level heading and
+separate them with `---`:
+
+```markdown
+# 1. First sub-topic
+
+## Problem
+
+…
+
+## Acceptance criteria
+
+…
+
+---
+
+# 2. Second sub-topic
+
+…
+```
+
+## Failure modes
+
+If, after the interview, you determine the ticket cannot be refined as stated (contradictory
+requirements, missing information you cannot extract from the user), still write to
+`{{OUTPUT_FILE}}` with whatever you have, ending with a final section explaining the gap.
+Do not silently invent requirements.

package/dist/skills/{default/abstraction-first → ralphctl-abstraction-first}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: abstraction-first
+name: ralphctl-abstraction-first
 description: Cross-phase skill — design the shape of the change (entities, boundaries, seams) before generating code, tasks, or acceptance criteria. Failure mode is "big blob" output that obscures the core change.
 ---
 

package/dist/skills/{default/alignment → ralphctl-alignment}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: alignment
+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.
 ---
 

package/dist/skills/{default/iterative-review → ralphctl-iterative-review}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: iterative-review
+name: ralphctl-iterative-review
 description: Cross-phase skill — treat AI output as a controlled feedback loop, not a one-shot generation. Run the cheap check after each meaningful change; re-read your own output before signalling completion.
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphctl",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Agent harness for long-running AI coding tasks — orchestrates Claude Code & GitHub Copilot across repositories",
   "homepage": "https://github.com/lukas-grigis/ralphctl",
   "type": "module",
@@ -38,38 +38,30 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@inkjs/ui": "^2.0.0",
-    "colorette": "^2.0.20",
     "commander": "^14.0.3",
-    "gradient-string": "^3.0.0",
-    "ink": "^7.0.1",
-    "react": "^19.2.5",
-    "tabtab": "^3.0.2",
+    "ink": "^7.0.3",
+    "react": "^19.2.6",
     "typescript-result": "^3.5.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.8.0",
     "@types/react": "^19.2.14",
-    "@types/tabtab": "^3.0.4",
-    "@vitest/coverage-v8": "^4.1.5",
-    "@vitest/eslint-plugin": "^1.6.16",
-    "eslint": "^10.3.0",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-import-x": "^4.16.2",
-    "eslint-plugin-react-hooks": "^7.1.1",
+    "@vitest/coverage-v8": "^4.1.6",
+    "eslint": "^10.4.0",
     "globals": "^17.6.0",
     "husky": "^9.1.7",
     "ink-testing-library": "^4.0.0",
-    "knip": "^6.11.0",
-    "lint-staged": "^16.4.0",
+    "jiti": "^2.7.0",
+    "knip": "^6.14.1",
+    "lint-staged": "^17.0.5",
     "prettier": "^3.8.3",
     "tsup": "^8.5.1",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.1",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.2",
-    "vitest": "^4.1.5"
+    "typescript-eslint": "^8.59.3",
+    "vitest": "^4.1.6"
   },
   "lint-staged": {
     "*.{ts,tsx}": [
@@ -79,16 +71,21 @@
     "*.{md,json,yml,yaml}": "prettier --write"
   },
   "scripts": {
-    "build": "tsup && node scripts/build-assets.mjs",
-    "dev": "tsx src/application/cli/entrypoint.ts",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "typecheck": "tsc --noEmit",
+    "build": "tsup && tsx scripts/build-assets.ts",
+    "dev": "NODE_OPTIONS=--max-old-space-size=8192 tsx src/index.ts",
+    "start": "NODE_OPTIONS=--max-old-space-size=8192 tsx src/index.ts",
+    "typecheck": "tsc",
     "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:e2e": "vitest run tests/e2e",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "deadcode": "knip"
+    "coverage:unused": "tsx scripts/find-unused.ts",
+    "deadcode": "knip",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   }
 }

package/dist/absolute-path-WUTZQ37D.mjs

@@ -1,8 +0,0 @@
-#!/usr/bin/env node
-import {
-  AbsolutePath
-} from "./chunk-S3PTDH57.mjs";
-import "./chunk-WV4D2CPG.mjs";
-export {
-  AbsolutePath
-};

package/dist/chunk-6RDMCLWU.mjs

@@ -1,108 +0,0 @@
-#!/usr/bin/env node
-import {
-  AbsolutePath
-} from "./chunk-S3PTDH57.mjs";
-
-// src/integration/persistence/storage-paths.ts
-import { mkdir } from "fs/promises";
-import { homedir } from "os";
-import { join } from "path";
-function defaultRoot() {
-  const fromEnv = process.env["RALPHCTL_ROOT"];
-  if (fromEnv !== void 0 && fromEnv.length > 0) {
-    return AbsolutePath.trustString(fromEnv);
-  }
-  return AbsolutePath.trustString(join(homedir(), ".ralphctl"));
-}
-function asAbsolute(p) {
-  return AbsolutePath.trustString(p);
-}
-function resolveStoragePaths(opts = {}) {
-  const root = opts.root ?? defaultRoot();
-  const configDir = asAbsolute(join(root, "config"));
-  const dataDir = asAbsolute(join(root, "data"));
-  const sprintsDir = asAbsolute(join(dataDir, "sprints"));
-  const cacheDir = asAbsolute(join(root, "cache"));
-  const logsDir = asAbsolute(join(root, "logs"));
-  const backupsDir = asAbsolute(join(root, "backups"));
-  const configFile = asAbsolute(join(configDir, "config.json"));
-  const projectsFile = asAbsolute(join(configDir, "projects.json"));
-  return {
-    root,
-    configDir,
-    dataDir,
-    sprintsDir,
-    cacheDir,
-    logsDir,
-    backupsDir,
-    configFile,
-    projectsFile,
-    sprintDir(id) {
-      return asAbsolute(join(sprintsDir, id));
-    },
-    sprintFile(id) {
-      return asAbsolute(join(sprintsDir, id, "sprint.json"));
-    },
-    tasksFile(id) {
-      return asAbsolute(join(sprintsDir, id, "tasks.json"));
-    },
-    progressFile(id) {
-      return asAbsolute(join(sprintsDir, id, "progress.md"));
-    },
-    requirementsAggregateFile(id) {
-      return asAbsolute(join(sprintsDir, id, "requirements.json"));
-    },
-    feedbackFile(id) {
-      return asAbsolute(join(sprintsDir, id, "feedback.md"));
-    },
-    refinementUnitDir(id, unitSlug) {
-      return asAbsolute(join(sprintsDir, id, "refinement", unitSlug));
-    },
-    ideationUnitDir(id, unitSlug) {
-      return asAbsolute(join(sprintsDir, id, "ideation", unitSlug));
-    },
-    planningDir(id) {
-      return asAbsolute(join(sprintsDir, id, "planning"));
-    },
-    executionUnitDir(id, unitSlug) {
-      return asAbsolute(join(sprintsDir, id, "execution", unitSlug));
-    },
-    doneCriteriaFile(id) {
-      return asAbsolute(join(sprintsDir, id, "done-criteria.md"));
-    }
-  };
-}
-async function ensureLayoutDirs(paths) {
-  const dirs = [
-    paths.configDir,
-    paths.sprintsDir,
-    paths.cacheDir,
-    paths.logsDir,
-    paths.backupsDir
-  ];
-  await Promise.all(dirs.map((d) => mkdir(d, { recursive: true })));
-}
-var ensuredRoots = /* @__PURE__ */ new Map();
-async function ensureLayoutDirsOnce(paths) {
-  const key = paths.root;
-  const existing = ensuredRoots.get(key);
-  if (existing !== void 0) return existing;
-  const pending = ensureLayoutDirs(paths);
-  ensuredRoots.set(key, pending);
-  try {
-    await pending;
-  } catch (err) {
-    ensuredRoots.delete(key);
-    throw err;
-  }
-}
-function resetEnsureLayoutDirsCache() {
-  ensuredRoots.clear();
-}
-
-export {
-  resolveStoragePaths,
-  ensureLayoutDirs,
-  ensureLayoutDirsOnce,
-  resetEnsureLayoutDirsCache
-};