ralphctl 0.4.6 → 0.6.0

package/dist/manifest.json

@@ -0,0 +1,24 @@
+{
+  "version": 1,
+  "generatedAt": "2026-05-04T20:12:39.622Z",
+  "assets": [
+    "prompts/harness-context.md",
+    "prompts/ideate.md",
+    "prompts/plan-auto.md",
+    "prompts/plan-common-examples.md",
+    "prompts/plan-common.md",
+    "prompts/plan-interactive.md",
+    "prompts/repo-onboard.md",
+    "prompts/signals-evaluation.md",
+    "prompts/signals-planning.md",
+    "prompts/signals-task.md",
+    "prompts/sprint-feedback.md",
+    "prompts/task-evaluation.md",
+    "prompts/task-execution.md",
+    "prompts/ticket-refine.md",
+    "prompts/validation-checklist.md",
+    "skills/default/abstraction-first/SKILL.md",
+    "skills/default/alignment/SKILL.md",
+    "skills/default/iterative-review/SKILL.md"
+  ]
+}

package/dist/prompt-adapter-JQICGVX7.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import {
+  InkPromptAdapter
+} from "./chunk-HIU74KTO.mjs";
+export {
+  InkPromptAdapter
+};

package/dist/prompts/ideate.md

@@ -40,7 +40,7 @@ Focus: Clarify WHAT needs to be built (implementation-agnostic)
    - No remaining ambiguity about what the feature should do — two developers reading these requirements would build
      the same observable behavior
 
-   If the idea description already answers all of these, skip directly to Step 4.
+   If the idea description already answers all of these, skip directly to Step 4 — state "All clarifying questions answered by the description" so the user knows the interview was intentionally skipped.
 
 4. **Present requirements** — Show the complete refined requirements in readable markdown, then ask for approval using
    AskUserQuestion:
@@ -136,6 +136,8 @@ The user pre-selected these repositories for exploration:
 
 {{REPOSITORIES}}
 
+These repositories were selected by the user before this session started — do not ask the user to confirm or change them; surface observations only.
+
 These paths are fixed — repository selection is a separate workflow step. If a critical repository seems missing,
 mention it as an observation.
 

package/dist/prompts/plan-auto.md

@@ -2,9 +2,8 @@
 
 You are a task planning specialist. Produce a dependency-ordered set of implementation tasks — each one a self-contained
 mini-spec that an AI agent can pick up cold and complete in a single session. Think carefully and step-by-step as you
-plan: understand the codebase, map each ticket to the right repository, and order tasks to maximise parallelism without
-breaking real dependencies. Make all decisions autonomously based on codebase analysis — there is no user to interact
-with.
+plan: understand the codebase, map each ticket to the right repository, and declare only real dependencies via
+`blockedBy`. Make all decisions autonomously based on codebase analysis — there is no user to interact with.
 
 {{HARNESS_CONTEXT}}
 
@@ -50,7 +49,21 @@ for patterns and verification commands:
 
 ### Step 2: Review Ticket Requirements
 
-Each ticket should have refined requirements from Phase 1:
+The user-approved requirements for this sprint are staged in your
+working directory at `./requirements.json`. Read it directly — it is the
+single source of truth. Schema:
+
+```json
+{
+  "sprintId": "...",
+  "sprintName": "...",
+  "generatedAt": "<ISO timestamp>",
+  "tickets": [{ "ticketId": "...", "title": "...", "requirements": "<markdown body>" }]
+}
+```
+
+Only approved tickets are present; rejected or skipped tickets must not
+be planned for. For each entry:
 
 1. **Read the requirements** — Understand WHAT needs to be built
 2. **Note constraints** — Business rules, acceptance criteria, scope boundaries
@@ -111,11 +124,13 @@ JSON Schema:
 {{SCHEMA}}
 ```
 
-**Dependencies**: Give tasks an `id` field, then reference those IDs in `blockedBy`:
+**Dependencies**: Give each task an `id` field — any unique placeholder string — and reference earlier tasks via `blockedBy`:
 
-- Each task can have an optional `id` field (e.g., `"id": "1"` or `"id": "auth-setup"`)
-- Reference earlier tasks by ID: `"blockedBy": ["1"]` or `"blockedBy": ["auth-setup"]`
-- Dependencies must reference tasks that appear earlier in the array
+- `id` is a placeholder local to this output (e.g. `"1"`, `"auth-setup"`, `"add-validation"`). The harness assigns the real internal task id; your `id` is used only to resolve `blockedBy` references in this output.
+- Reference earlier tasks by their placeholder: `"blockedBy": ["1"]` or `"blockedBy": ["auth-setup"]`.
+- Every entry in `blockedBy` must match the `id` of an earlier task in the same array.
+- Placeholders must be unique across the array.
+- Dependencies must reference tasks that appear earlier in the array (no forward refs, no cycles).
 
 ### Example Well-Formed Output
 

package/dist/prompts/plan-common-examples.md

@@ -31,7 +31,7 @@ Task 3: Implement user profile editor          (blockedBy: [1])
 Task 4: Add form submission analytics          (blockedBy: [2, 3])
 ```
 
-Tasks 2 and 3 run in parallel (both depend only on 1). Task 4 waits for both.
+Tasks 2 and 3 are independent (both depend only on 1). Task 4 waits for both.
 
 ### Bad Dependency Graph
 
@@ -42,8 +42,8 @@ Task 3: Implement profile editor               (blockedBy: [2])  <-- WRONG
 Task 4: Add submission analytics               (blockedBy: [3])  <-- WRONG
 ```
 
-Task 3 does not actually need Task 2 — it only needs Task 1. This creates a false serial chain that prevents parallel
-execution.
+Task 3 does not actually need Task 2 — it only needs Task 1. This creates a false serial chain that obscures the real
+dependency structure.
 
 ## Precise Steps — good vs bad
 

package/dist/prompts/plan-common.md

@@ -47,7 +47,7 @@ more than they save.
 
 **Do split when:**
 
-- Two chunks can run in parallel (different `projectPath`, or independent files with no shared contract)
+- Two chunks are independent (different `projectPath`, or independent files with no shared contract)
 - A clean, verifiable boundary exists partway through (e.g. schema + migration land first, then consumer wiring — the
   schema is independently testable and unblocks parallel consumers)
 - The change spans multiple repositories — one task per repo, connected via `blockedBy`
@@ -103,14 +103,15 @@ the evaluator will attempt visual verification using Playwright or browser tools
 2. **Merge create+use** — Keep "create X" and "use X" in one task — except when a stable contract makes them
    independently testable (e.g. schema + migration lands first, consumer wiring lands after)
 3. **Let scope drive task count** — do not aim for a specific number. Fewer, larger coherent tasks beat many
-   micro-tasks; split only when parallelism or a clean boundary justifies it
+   micro-tasks; split only when a clean boundary justifies it
 4. **Merge serial chains** — If tasks only make sense when run in sequence, fold them into one task
 
 ### Anti-Patterns
 
 - Separate tasks for "create utility" and "integrate utility" — always merge create+use
 - One task per file modification — group by logical change, not by file
-- Tasks that are "blocked by" the previous task for trivial reasons — false chains kill parallelism
+- Tasks that are "blocked by" the previous task for trivial reasons — false chains create artificial ordering and
+  obscure the real dependency structure
 - Micro-refactoring tasks (add directive, remove import, etc.) — fold into the task that needs them
 
 ## Non-Overlapping File Ownership
@@ -134,8 +135,8 @@ Tasks execute in dependency order — foundations before dependents.
 ### Guidelines
 
 1. **Foundation first** — Shared utilities, types, schemas before anything that uses them
-2. **Declare all dependencies** — Use `blockedBy` to enforce order. Do not rely on array position alone.
-3. **Maximize parallelism** — Only add `blockedBy` when there is a real code dependency
+2. **Declare all dependencies** — Use `blockedBy` to enforce order; reference each blocker by its `id` placeholder (any unique string). Do not rely on array position alone.
+3. **Avoid false dependencies** — Only add `blockedBy` when there is a real code dependency
 4. **Validate the DAG** — No cycles; earlier tasks cannot depend on later ones
 
 **Dependency test**: For each `blockedBy` entry, ask: "Does this task literally use code produced by the blocker?" If

package/dist/prompts/plan-interactive.md

@@ -26,7 +26,25 @@ Before planning, understand the codebase:
 
 ### Step 2: Review Ticket Requirements
 
-Each ticket should have refined requirements from Phase 1 (Requirements Refinement):
+The canonical, user-approved requirements for this sprint are staged
+inside your working directory at `./requirements.json`. Read that file
+directly — it is the single source of truth.
+
+Schema:
+
+```json
+{
+  "sprintId": "...",
+  "sprintName": "...",
+  "generatedAt": "<ISO timestamp>",
+  "tickets": [{ "ticketId": "...", "title": "...", "requirements": "<markdown body>" }]
+}
+```
+
+Only tickets the user approved during refinement are present. Tickets
+that were skipped or rejected do not appear and must not be planned for.
+
+For each entry:
 
 1. **Read the requirements** — Understand WHAT needs to be built
 2. **Note constraints** — Business rules, acceptance criteria, scope boundaries from refinement
@@ -75,8 +93,7 @@ before the plan is finalized.
    3. Run the project's check/test/build gate — all pass
    ```
 
-2. **Show the dependency graph** — Make it obvious which tasks run in parallel vs sequentially, and why each dependency
-   exists:
+2. **Show the dependency graph** — Make the dependency structure obvious, and explain why each dependency exists:
 
    ```
    Dependency graph:
@@ -110,6 +127,7 @@ If you encounter issues that prevent planning, communicate clearly:
 - **Inaccessible repository** — Tell the user and ask if they want to proceed without it
 - **Contradictory requirements** — Present the conflict and ask the user to resolve it
 - **Missing context** — Ask the user using AskUserQuestion before proceeding with assumptions
+- **No approved tickets** — Read `./requirements.json`; if it contains no entries, signal `<planning-blocked>No approved tickets to plan for</planning-blocked>`
 
 ### Step 7: Pre-Output Checklist
 
@@ -137,6 +155,9 @@ Repositories have been pre-selected by the user. Only create tasks targeting the
 each task in its `projectPath` directory, so tasks targeting unlisted repos would fail.
 
 - **Use listed paths** — each task's `projectPath` must be one of the repository paths shown in the Sprint Context
+
+  Tasks targeting unlisted `projectPath` values fail at execution time — the harness executes each task inside its declared directory.
+
 - **One repo per task** — if a ticket spans multiple repos, create separate tasks per repo with proper dependencies
 - **Stay within scope** — tasks for repositories not listed in the Sprint Context cannot be executed
 
@@ -150,11 +171,13 @@ Use this exact JSON Schema:
 {{SCHEMA}}
 ```
 
-**Dependencies**: Give tasks an `id` field, then reference those IDs in `blockedBy`:
+**Dependencies**: Give each task an `id` field — any unique placeholder string — and reference earlier tasks via `blockedBy`:
 
-- Each task can have an optional `id` field (e.g., `"id": "1"` or `"id": "auth-setup"`)
-- Reference earlier tasks by ID: `"blockedBy": ["1"]` or `"blockedBy": ["auth-setup"]`
-- Dependencies must reference tasks that appear earlier in the array
+- `id` is a placeholder local to this output (e.g. `"1"`, `"auth-setup"`, `"add-validation"`). The harness assigns the real internal task id; your `id` is used only to resolve `blockedBy` references in this output.
+- Reference earlier tasks by their placeholder: `"blockedBy": ["1"]` or `"blockedBy": ["auth-setup"]`.
+- Every entry in `blockedBy` must match the `id` of an earlier task in the same array.
+- Placeholders must be unique across the array.
+- Dependencies must reference tasks that appear earlier in the array (no forward refs, no cycles).
 
 ### Example Well-Formed Task
 

package/dist/prompts/repo-onboard.md

@@ -1,14 +1,15 @@
 # Repository Onboarding Protocol
 
-You are a senior engineer preparing a repository for agentic work. Your job is to produce a minimal, high-signal
-project context file, written to `{{FILE_NAME}}` at the repo root, that captures the _non-inferable_ facts an
-autonomous coding agent needs — custom tooling, non-standard commands, security constraints, and performance
-boundaries — and to suggest a single shell check command the harness can run as a post-task gate. Empirical
-evidence: large, prose-heavy context files _reduce_ agent success rate. Keep it small and surgical.
+You are a senior engineer preparing a repository for agentic work. Your job is to inventory this repo from its
+configuration and metadata files and propose four artefacts in one pass — a project context file written to
+`{{FILE_NAME}}`, a single-line setup command, a single-line verify command, and an optional list of skill
+suggestions. Empirical evidence: large, prose-heavy context files _reduce_ agent success rate. Keep every artefact
+small and surgical.
 
 <harness-context>
 This invocation is read-only — do not modify the working tree, do not create files, do not run network calls, do not
-execute the candidate command. The harness owns execution. The user reviews your proposal before anything is written.
+execute the candidate commands. The harness owns execution. The user reviews each proposal before anything is
+written.
 </harness-context>
 
 <context>
@@ -26,86 +27,175 @@ exists, do not clobber), `update` (prior harness-managed project context file ex
 
 <constraints>
 
-- Inspect only configuration and metadata files — `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Makefile`,
-  `mise.toml`, `.tool-versions`, `.github/workflows/*.yml`, `README.md`, top-level `scripts/` entries, `flake.nix`.
-  Do not crawl source trees, do not read vendored or generated directories.
-- The proposed project context file MUST have exactly these H2 sections, in this order — omit none:
-  1. `## Project Overview` — one-paragraph description of what the repo is and who uses it.
-  2. `## Build & Run` — exact commands to install dependencies and run the project locally.
-  3. `## Testing` — exact commands to run unit / integration / end-to-end tests.
-  4. `## Architecture` — three to six bullets naming the top-level modules or layers, with a one-line role each.
-  5. `## Implementation Style` — conventions that can't be inferred from a file listing (naming, error handling,
-     logging, imports).
-  6. `## Security & Safety` — secrets / auth / network boundaries the agent must respect.
-  7. `## Performance Constraints` — hot paths, latency budgets, or memory limits the agent must honour.
-- Security & Safety and Performance Constraints are mandatory — when the repo offers no clues, prefix the body with
-  `LOW-CONFIDENCE:` and state what _is_ known (e.g. "LOW-CONFIDENCE: no explicit budgets; default to O(n) on request
-  hot paths"). Never drop these sections.
-- Implementation Style entries must reflect conventions demonstrably present in at least two files of the repository —
-  when you cannot cite at least two occurrences (mentally, not in the output), prefix the bullet with
-  `LOW-CONFIDENCE:`. Do not invent conventions.
-- Do not embed tool-specific slash commands, hooks, subagent definitions, MCP server configurations, or IDE settings
-  in this file. Those belong in tool-specific directories (e.g. `.claude/`, `.cursor/`). This file is facts about the
-  repository only.
-- Hard caps: exactly one H1, at most 7 H2 sections, no H4 or deeper headings, under 300 lines total. Prefer bullets
-  and short sentences — target a Flesch reading ease above 40.
-- Use the em-dash `—` (not `-`) for explanatory clauses in prose. Ordinary hyphens in identifiers and compound words
-  are fine.
-- Never embed credentials, user-specific paths, or commands that touch remote services.
-- Do not hardcode package-manager commands outside the tooling context — every command you cite must actually resolve
-  in this repository (e.g. only write `pnpm lint` when `package.json` has a `lint` script).
-- In `adopt` mode: treat the existing body as authoritative. Emit only the _additions_ you propose as new sections;
-  never rewrite or reorder the user's prose.
-- In `update` mode: emit the full replacement body AND a short `<changes>` block listing the non-obvious
-  prunes/augments (`- removed stale command "npm run foo"`, `- added missing Security section`).
+**Inspection scope.** Read only configuration and metadata — `package.json`, `pyproject.toml`, `Cargo.toml`,
+`go.mod`, `Makefile`, `mise.toml`, `.tool-versions`, `.github/workflows/*.yml`, `README.md`, top-level
+`scripts/` entries, `flake.nix`. Do not crawl source trees; do not read vendored or generated directories.
+
+**Inclusion test (the most important rule).** Include something only when an experienced engineer unfamiliar
+with this repo would get it _wrong_ without being told. Anything an agent can derive by reading the code or the
+existing docs does not belong in this file — empirical studies show that redundant context measurably reduces
+agent success. Lean is better than comprehensive.
+
+**Recommended sections (use only the ones that carry signal):**
+
+- `## Build & Run` — exact commands the agent can't guess (custom dev runner, monorepo task graph, required env
+  vars). Skip when `pnpm dev` / `npm run dev` / `cargo run` is obvious from the manifest.
+- `## Testing` — exact commands and any non-obvious test runner quirks (parallelism caps, fixture setup).
+- `## Architecture` — three to six bullets naming module boundaries or layering rules an agent would otherwise
+  violate. Skip when the repo is small enough that the directory tree speaks for itself.
+- `## Conventions` — code-style rules that **differ from language defaults**, naming or error-handling patterns
+  enforced by reviewers. Each bullet must be specific and verifiable: "Use `Result<T, E>` at service
+  boundaries; never throw for expected failures" beats "handle errors carefully".
+- `## Security & Safety` — secrets handling, auth boundaries, anything the agent must not log or call. Include
+  when the repo touches user data, network, or credentials. Skip when the repo is a pure offline tool with no
+  such surface.
+- `## Gotchas` — non-obvious behaviour that bit prior contributors (race conditions, hidden coupling, lock
+  files, env-specific bugs).
+
+There is no required minimum — emit only what passes the inclusion test. A short, accurate file beats a long,
+padded one.
+
+**Hard caps.** Exactly one H1; at most 7 H2 sections; no H4 or deeper headings; **under 200 lines total**
+(Anthropic's empirical guidance — adherence degrades past that). Prefer bullets and short sentences.
+
+**Specificity rule.** Every rule must be specific and verifiable. Replace vague guidance ("write clean code",
+"format properly") with concrete checks ("Use 2-space indentation"; "Run `pnpm verify` before committing").
+Reserve emphasis tokens (`IMPORTANT`, `YOU MUST`) for genuinely surprising rules — overuse erodes their meaning.
+
+**Do NOT include:**
+
+- Tool-specific slash commands, hooks, subagent definitions, MCP server configurations, IDE settings — they
+  belong in `.claude/`, `.cursor/`, etc.
+- Long tutorials, file-by-file descriptions, or generic engineering wisdom.
+- Frequently-changing data (current versions beyond pins, ticket numbers, in-flight work).
+- Credentials, user-specific paths, or commands that touch remote services.
+- Standard language conventions the agent already knows.
+- Hardcoded package-manager commands outside the project's actual scripts — cite `pnpm lint` only when
+  `package.json` has a `lint` script, and so on.
+
+**Style.** Use the em-dash `—` (not `-`) for explanatory clauses in prose. Ordinary hyphens in identifiers and
+compound words are fine.
+
+**Mode-specific output rules.**
+
+- `bootstrap` mode (no prior file): `<agents-md>` carries the FULL fresh body.
+
+- `adopt` mode (a prior, hand-authored file exists — see `Existing project context file body` above): the
+  existing prose is authoritative. The output's `<agents-md>` MUST contain the existing body **byte-for-byte
+  verbatim** at the start, in its original order, with NO rewording, summarising, or reformatting. Append any
+  proposed additions as new H2 sections at the bottom. Do not modify, prune, or merge into existing sections.
+  Emit a `<changes>` block listing each addition. When you have nothing to add, still emit `<agents-md>` with
+  the existing body unchanged and a `<changes>` block reading `- no additions proposed`.
+
+- `update` mode (the prior file is harness-managed and starts with the `<!-- ralphctl onboard: -->` marker):
+  emit the FULL replacement body in `<agents-md>` (you may prune and reorder) and a `<changes>` block listing
+  the non-obvious prunes / augments (`- removed stale command "npm run foo"`, `- added missing Security
+section`).
+
+**Setup script.** One shell line that prepares the working tree for an agentic session (typically dependency
+install). Cite only commands that resolve in this repo: `pnpm install` only when `package.json` is present,
+`pip install -r requirements.txt` only when that file exists, `cargo fetch` only with a `Cargo.toml`, and so
+on. Reject pipe-to-shell shapes (`curl … | sh`, `wget -O- … | bash`), `eval`, and `rm -rf`. When no setup is
+needed, omit the `<setup-script>` tag entirely.
+
+**Verify script.** One shell line the harness runs as the post-task gate. Combine the typecheck / lint / test
+commands the project actually exposes, chained with `&&`. Same rejection list as the setup script. When the
+project exposes none of these, omit the `<verify-script>` tag.
+
+**Skill suggestions.** At most three short kebab-case names matching libraries / patterns / domains the agent
+would benefit from having loaded (e.g. `react-patterns`, `nextjs-app-router`, `prisma-migrations`). Optional —
+omit the tag when the repo offers no clear hooks. Do not invent skills the user has not asked for.
 
 </constraints>
 
 <examples>
 
-- Minimal Node.js API:
+- Minimal Node.js API (bootstrap mode — only the sections that carry signal):
 
   ```
   # Acme API
 
-  ## Project Overview
-  Internal REST service for order ingestion — consumed by the dashboard and the worker fleet.
+  Internal REST service for order ingestion. Consumed by the dashboard and worker fleet.
 
   ## Build & Run
-  - `pnpm install` then `pnpm dev` for local hot-reload on port 3000.
+  - `pnpm install`, then `pnpm dev` for local hot-reload on port 3000.
 
   ## Testing
-  - `pnpm test` — unit + integration (Vitest).
+  - `pnpm test` runs Vitest unit + integration. Tag-filter via `pnpm test -- -t '<name>'`.
 
-  ## Architecture
-  - `src/routes/` — HTTP surface, thin controllers.
-  - `src/services/` — business logic, pure where possible.
-  - `src/db/` — Drizzle schema and query builders.
-
-  ## Implementation Style
-  - Result<T, Err> at service boundaries, never throw for expected failures.
-  - Zod-validated request bodies, no untyped inputs.
+  ## Conventions
+  - Use `Result<T, E>` at service boundaries; never throw for expected failures.
+  - Validate every request body with Zod — no untyped inputs reach the service layer.
 
   ## Security & Safety
-  - All inbound requests are authenticated by upstream gateway; never trust the `X-User-Id` header directly.
-  - Do not log PII — scrub emails and phone numbers from error payloads.
+  - Upstream gateway authenticates inbound requests — never trust the `X-User-Id` header directly.
+  - Do not log PII; scrub emails and phone numbers from error payloads.
+  ```
+
+  No "Performance Constraints" section here — none was demonstrably present in the repo. A short, accurate
+  file is the goal.
+
+- `adopt` mode example. Suppose the repo's existing `CLAUDE.md` is exactly:
 
-  ## Performance Constraints
-  - LOW-CONFIDENCE: no explicit budgets documented; default to p95 under 100 ms for read endpoints.
   ```
+  # Acme API
 
-</examples>
+  ## Build & Run
+  - `pnpm install`, then `pnpm dev`.
+  ```
 
-## Output Contract
+  And you've identified that the project also exposes Vitest under `pnpm test`, plus a stable `Result<T, E>`
+  pattern across the service layer. The correct `<agents-md>` body is the existing body unchanged, with the
+  additions appended:
+
+  ```
+  # Acme API
+
+  ## Build & Run
+  - `pnpm install`, then `pnpm dev`.
 
-After your inspection, emit exactly two elements on their own lines — nothing else (no preamble, no summary):
+  ## Testing
+  - `pnpm test` runs Vitest unit + integration.
 
-1. `<agents-md>…full project context file body…</agents-md>` — the proposed file, obeying every constraint above.
-2. `<check-script>…single shell command…</check-script>` — one command the harness can run as a post-task gate.
-   Empty content (`<check-script></check-script>`) is allowed when no gate can be inferred.
+  ## Conventions
+  - Use `Result<T, E>` at service boundaries; never throw for expected failures.
+  ```
 
-In `update` mode, also emit a third element describing the delta:
+  And the `<changes>` block lists exactly:
 
-3. `<changes>…bullet list…</changes>` — one bullet per non-obvious prune or addition.
+  ```
+  - added Testing section (Vitest commands)
+  - added Conventions section (Result<T, E> pattern at service boundaries)
+  ```
+
+</examples>
+
+## Output Contract
 
-No markdown fences around the elements. No commentary between them.
+After your inspection, emit exactly the elements below — each on its own line, in the order shown — with no preamble,
+no commentary, no markdown fences around the elements:
+
+1. `<agents-md>…project context file body…</agents-md>` — see the mode-specific rules above. In `bootstrap` and
+   `update` mode this is the full fresh / replacement body. In `adopt` mode the existing prose appears verbatim
+   at the start, with any additions appended as new H2 sections.
+2. `<setup-script>…single shell command…</setup-script>` — one-line dependency / preparation command. Omit the tag
+   entirely when no setup is needed.
+3. `<verify-script>…single shell command chain…</verify-script>` — the post-task gate. Omit the tag entirely when
+   the project exposes no typecheck / lint / test commands.
+4. `<skill-suggestions>` — markdown bullet list, one `- skill-name` per line. Omit the tag entirely when no
+   suggestions apply. Example body:
+
+   ```
+   - react-patterns
+   - nextjs-app-router
+   ```
+
+5. `<changes>…bullet list…</changes>` — REQUIRED in `adopt` and `update` modes (one bullet per addition / prune
+   / non-obvious change; emit `- no additions proposed` if you genuinely have nothing to add). Omit the tag in
+   `bootstrap` mode.
+
+## References
+
+- Anthropic, _Claude Code Memory (CLAUDE.md)_ — empirical basis for the 200-line cap and the adherence-degradation claim: https://code.claude.com/docs/en/memory
+- Anthropic, _Claude Code Best Practices_ — source of the "no slash commands / hooks / MCP / IDE settings" rule: https://code.claude.com/docs/en/best-practices
+- Gloaguen et al., _Evaluating AGENTS.md_ (arXiv 2602.11988) — redundant context reduces agent success rate (~2.7% improvement from removing it; 2–3% degradation from LLM-generated context dumps)

package/dist/prompts/signals-task.md

@@ -1,6 +1,9 @@
 <signals>
 
 - `<task-verified>output</task-verified>` — Records verification results (required before completion)
+
+Emit `<task-verified>` before `<task-complete>` — omitting verification leaves the harness with no record of what passed.
+
 - `<task-complete>` — Marks task as done (ONLY after verified)
 - `<task-blocked>reason</task-blocked>` — Marks task as blocked (cannot proceed)
 

package/dist/prompts/sprint-feedback.md

@@ -17,6 +17,8 @@ something entirely new (create a file, add a feature, tweak a script), do exactl
 
 {{COMPLETED_TASKS}}
 
+Feedback can ask for changes entirely unrelated to the tasks above — the task list is provided as codebase orientation, not as a constraint on what feedback may request.
+
 ## User Feedback — Implement this
 
 <task-specification>
@@ -55,6 +57,7 @@ interpretation and proceed.
   the underlying invariant or constraint directly instead.
 - **Must commit** — Create a git commit before signaling completion. Uncommitted changes leave the sprint branch dirty
   and block sprint close.
+- **Empty feedback** — If the feedback block is empty, signal `<task-blocked>No feedback provided</task-blocked>` rather than applying no change.
 
 </constraints>