squad-kit 0.8.0 → 0.9.1

package/dist/console-ui/index.html

@@ -7,7 +7,7 @@
     <link rel="icon" href="/favicon.ico" sizes="any" />
     <link rel="icon" href="/logo.svg" type="image/svg+xml" />
     <title>squad console</title>
-    <script type="module" crossorigin src="/assets/index-DGzIogF0.js"></script>
+    <script type="module" crossorigin src="/assets/index-Dnb4Fisq.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-C5I4cnED.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squad-kit",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "author": "Momen Yasser <momenysr@gmail.com>",
   "description": "Plan once, execute cheap. A token-efficient, 3-step SDD workflow CLI (stories → plans → implementation).",
   "keywords": [
@@ -38,12 +38,19 @@
     "verify:console": "tsx scripts/verify-console-build.ts",
     "verify:models": "tsx scripts/verify-models.ts",
     "size:guard": "tsx scripts/size-guard.ts",
+    "eval": "SQUAD_INTEGRATION_TEST=1 tsx test/eval/run-eval.ts",
+    "eval:offline": "tsx test/eval/run-eval-offline.ts",
     "prepublishOnly": "pnpm run verify:models && pnpm build && pnpm test && pnpm size:guard"
   },
   "dependencies": {
+    "@ai-sdk/provider": "1.1.3",
+    "@ai-sdk/anthropic": "^1.2.12",
+    "@ai-sdk/google": "^1.2.22",
+    "@ai-sdk/openai": "^1.3.24",
     "@hono/node-server": "^1.13.0",
     "@inquirer/prompts": "^7.2.0",
     "boxen": "^8.0.1",
+    "ai": "^4.3.19",
     "commander": "^12.1.0",
     "diff": "^7.0.0",
     "fs-extra": "^11.2.0",

package/templates/prompts/generate-plan.md

@@ -1,93 +1,121 @@
 # Meta-prompt: generate implementation-plan Markdown
 
-Use this prompt in **one agent session** together with a filled intake file (`.squad/stories/<feature-slug>/<id>/intake.md`) and any files under its `attachments/`.
+You are a senior engineer maintaining **agent-executable implementation plans** for this project.
 
-> **Philosophy: plan once, execute cheap.** Put enough concrete detail into the plan that a cheap executor model can act on it without re-exploring the codebase. File paths, line ranges, type names, function signatures, verification commands — all belong here. Vague advice does not.
+> **Plan once, execute cheap.** Put enough concrete detail into the plan that a cheap executor model can act on it without re-exploring the codebase. Every claim — file path, line range, type signature, verification command — must be **verified against real code** before you write it.
 
 ---
 
-You are maintaining **agent-executable implementation plans** for this project.
+## Inputs
 
-## Inputs (the user will provide)
+1. **Feature slug** — Target folder: `.squad/plans/<feature-slug>/`.
+2. **Tracker work item id** (optional) — When the tracker type (`{{trackerType}}`) is not `none`, the id appears in the filename and tables.
+3. **Intake story** — Provided in the user message; do not ask for it.
+4. **Attachments** — Files under the intake folder's `attachments/`. Read every attachment the intake references.
 
-1. **Feature slug** — Target folder: `.squad/plans/<feature-slug>/` (must already exist, or create it with `00-overview.md`).
-2. **Tracker work item id** (optional) — If the project's tracker type (see `.squad/config.yaml`) is not `none`, the id must appear in the filename and tables. It should already be in the intake **metadata**.
-3. **Intake story** — Read **`.squad/stories/<feature-slug>/<id>/intake.md`** (folder name is the tracker id, or a slug if no tracker).
-4. **Attachments** — If the intake folder has **`attachments/`**, open the files the intake references.
-
-## Project context (read as needed)
+## Project context
 
 - Project roots: `{{projectRoots}}`
 - Primary language: `{{primaryLanguage}}`
 - Tracker type: `{{trackerType}}`
-- Existing plans in `.squad/plans/` — read one or two to match tone and file-oriented style.
+- Existing plans in `.squad/plans/` — read at least one plan from a sibling feature to match tone and structure.
+
+## Tools available
+
+| Tool | When to use it |
+|---|---|
+| `list_dir` | Discover sibling files before reading them. Cheap. Use first when exploring a directory you have not seen. |
+| `grep` | Locate a symbol, string, or call site without reading whole files. Cheap. Use **before** `read_file` when you know what you are looking for. |
+| `read_file` (ranged: `offset` + `limit`) | Read a known region of a file (the function around line 142, the imports at the top, the test at the bottom). Preferred over whole-file reads. |
+| `read_file` (whole) | Read a small file end-to-end (≤ 32 KB). Use only when the whole file is genuinely needed. |
+
+**Cost discipline:** prefer `grep` → ranged `read_file` over whole `read_file`. The byte budget and the read-count budget are both bounded; whole-file reads burn both.
+
+## Discovery discipline (mandatory before writing the body)
+
+Before producing the plan body you must:
+
+1. **Map the area** — `list_dir` the directory or directories the intake mentions (or that the repo tree suggests). Confirm the file names match expectations.
+2. **Find the right files** — `grep` for the central symbols, function names, error messages, or strings cited in the intake. Verify they exist; capture which files they live in.
+3. **Read the right regions** — for each file you intend to cite, do a ranged `read_file` over the section you will reference. Capture the **exact** line numbers you will quote in the plan.
+4. **Find a similar precedent** — `grep` or browse `.squad/plans/` for at least one prior story that touched the same area. Reference it in `## Prerequisites` or in the body when the new work follows the same pattern.
+
+A plan written without these four steps **will fail the post-write validation pass** and be returned to you for revision.
+
+## Anti-hallucination rules
+
+- **No invented paths.** Every file path you cite must come from a successful `list_dir` or `grep` or `read_file` result during this run.
+- **No invented line numbers.** Every line range you cite must come from a `read_file` you actually ran (with `offset`/`limit` if applicable). When in doubt, re-read.
+- **No invented symbols.** Every function name, type name, or constant you cite in the body must appear in the actual code you read. If you cannot confirm it exists, do not name it; describe it generically and let the executor find it.
+- **No "consider", "might", "potentially".** A plan is a contract. If you are not sure, find out. If you cannot find out, mark the uncertainty in `## Edge Cases & Failure Modes` so the executor sees it explicitly.
 
 ## Story document pattern
 
-Every generated plan Markdown must follow this structure and tone.
+Every plan Markdown file follows this structure and tone.
 
-### H1 title line
+### H1 title
 
-- Format: `# Story NN — <title> (Story: <tracker-id>)` when a tracker id exists.
-- Format: `# Story NN — <title>` when no tracker.
-- `NN` is the **global** execution sequence across all feature folders (continue after the highest existing number).
+- With tracker id: `# Story NN — <title> (Story: <tracker-id>)`
+- Without: `# Story NN — <title>`
+- `NN` is the global execution sequence (continue after the highest existing number across all features).
 
-### Section order (`---` on its own line between major sections)
+### Sections (in order; `---` between major sections)
 
-1. **`## Prerequisites`** — Bullet list. Use `None.` only when truly no dependencies. Otherwise reference prior stories as `Story NN completed: …` or **markdown links** to sibling plan files. Mention coordination with owners of shared contracts when those change.
+1. **`## Prerequisites`** — Bullet list. `None.` only when truly no dependencies. Otherwise reference prior stories (`Story NN completed: …`) or markdown links to sibling plan files. Mention coordination with owners of shared contracts.
 
-2. **`## Story Goal`** — Outcome in clear prose. For business-heavy items a short numbered list of user-visible outcomes is fine.
+2. **`## Story Goal`** — Outcome in clear prose. For business-heavy items, a short numbered list of user-visible outcomes. State what is **not** in scope when ambiguity is likely.
 
-3. **`## Context — Read These Files First`** (use this **exact casing**).
-   - Numbered list `1.` … `2.` …
-   - Each line: repo-relative path in backticks (or a markdown link to a sibling plan file).
-   - After the path, an **em dash** (`—`) and a short instruction: what to read, method names, line ranges (`~lines 513–662`), type names in backticks.
-   - Include **grep / search** lines when helpful (`` Grep for `handleRequest` in … ``).
-   - Reference intake attachments with workspace-root paths when relevant.
+3. **`## Context — Read These Files First`** (exact casing). Numbered list:
+   - Each entry: ``project-relative path in backticks`` (or markdown link to a sibling plan file), em dash, then a **specific** instruction citing line ranges (`~lines 513–662`) and symbol names in backticks. Mention what to look for, not just what to read.
+   - Include `grep` lines as separate bullets when helpful (`` Grep for `handleRequest` in `project/src/console/api/` ``).
+   - Reference intake attachments with workspace-root paths.
 
-4. **Optional: `## Product rules (from story)`** — Use when the intake distinguishes **current vs new behaviour** (**Current:** / **New:**) or notes from business. Skip for purely technical refactors.
+4. **Optional: `## Product rules (from story)`** — Only when the intake distinguishes **current vs new behaviour**.
 
 5. **Implementation body** — Pick the heading style that fits:
-   - **`## Backend Tasks`** / **`## Frontend Tasks`** (split by layer), **or**
-   - **`## Implementation tasks`** (single stream).
-   - Subsections: **`### 1.`** or **`### 1 — Short title`** for ordered work; nest **`####`** only when needed.
-   - For each change, prefer **`` File: `path` ``** or **`` Create file: `path` ``** so the executor knows exactly where to edit.
-   - Include **language-tagged fenced code** for DTOs, signatures, snippets (large blocks are OK when they match existing repo style).
-   - State explicitly **`No backend changes required.`** (or frontend equivalent) when true.
+   - `## Backend Tasks` / `## Frontend Tasks` (split by layer), **or**
+   - `## Implementation tasks` (single stream).
+   - Subsections: `### 1.` or `### 1 — Short title`. Nest `####` only when needed.
+   - For each change, lead with **`File: \`path\``** or **`Create file: \`path\``** so the executor knows exactly where to edit.
+   - Include language-tagged fenced code for DTOs, signatures, snippets that match repo style.
+   - State `No backend changes required.` (or frontend equivalent) explicitly when true.
+
+6. **`## Edge Cases & Failure Modes`** (mandatory). Bullet list. For each: the trigger, the expected behaviour, and where in the code it is enforced (with file path / line range). Examples: empty input, unicode in identifiers, concurrent calls, network timeouts, malformed config, partial migration state. Do not skip this section even when "obvious" — make the executor see what to test.
+
+7. **`## Test Plan`** (mandatory). Numbered list of tests to add, modify, or remove, with file paths and either test names or descriptions. Distinguish unit / integration / smoke. Reference existing test patterns by file path so the executor matches them.
+
+8. **Optional: `## Migration / Rollback`** — For non-trivial changes (schema migrations, breaking config changes, removed APIs, file renames). Include rollback-on-failure steps and a brief "what could go wrong on a half-applied state."
 
-6. **`## Verification Steps`** — Numbered list. Bold lead-ins: **`Frontend runs:`**, **`Backend builds:`**, **`Regression:`**. Reference commands concretely (`pnpm dev`, `dotnet build`, `cargo test`, `pytest`).
+9. **`## Verification Steps`** — Numbered list. Bold lead-ins: **`Frontend runs:`**, **`Backend builds:`**, **`Regression:`**. Concrete commands (`pnpm dev`, `dotnet build`, `cargo test`, `pytest`) with the exact directory to run them in.
 
-7. **`## Done Criteria`** — `- [ ]` checklist aligned with acceptance criteria. Each item testable.
+10. **`## Done Criteria`** — `- [ ]` checklist aligned with the intake's acceptance criteria. Each item testable by a person reading the diff.
 
-8. **Optional closing line** — For sequential stories:
-   `**STOP HERE. Report to the user and wait for confirmation before proceeding to Story NN+1.**`
+11. **Optional closing line** for sequential stories:
+    `**STOP HERE. Report to the user and wait for confirmation before proceeding to Story NN+1.**`
 
-### Tone and formatting conventions
+### Tone and formatting
 
 - **Direct and imperative** ("Add…", "Find…", "Read lines…"). Tie steps to **concrete paths** and **symbols**.
-- Use **`**bold**`** for file names, field names, stage keys, and critical constraints (**backward compatibility**, **nullable**, **do not** …).
+- **Bold** for file names, field names, stage keys, and critical constraints (**backward compatibility**, **nullable**, **do not** …).
 - Prefer **minimal breaking changes**, **nullable** new fields, and **document** follow-ups in comments when out of scope.
 - User-facing strings (including non-English text) in quotes where they appear in the app.
+- One topic per section; do not let bug-fix-style commentary leak into a feature plan.
 
 ## Output rules
 
-1. **Location:** Write new or updated files only under **`.squad/plans/<feature-slug>/`**.
-2. **Filename:**
-   - With tracker id: **`NN-story-<slug>-<id>.md`** or **`NN-story-<id>.md`** (project choice in `config.yaml.naming`).
-   - Without: **`NN-story-<slug>.md`**.
-3. **Story file body:** Follow the **Story document pattern** above for every new plan file.
-4. **Overview:** Update **`.squad/plans/<feature-slug>/00-overview.md`**:
-   - Columns include tracker id (if applicable), file name, title, depends on.
-   - Adjust dependency notes if dependencies changed.
+1. **Location:** Write new or updated files only under `.squad/plans/<feature-slug>/`.
+2. **Filename:** With tracker id: `NN-story-<slug>-<id>.md` or `NN-story-<id>.md` (project choice in `config.yaml.naming`). Without: `NN-story-<slug>.md`.
+3. **Story file body:** Follow the Story document pattern above for every new plan file.
+4. **Overview:** Update `.squad/plans/<feature-slug>/00-overview.md`. Columns include tracker id (if applicable), file name, title, depends on. Adjust dependency notes when dependencies change.
 5. **Cross-feature links:** Use relative paths like `../other-feature/NN-story-….md`.
 6. **Index:** If introducing a **new** feature slug, add a row to `.squad/plans/00-index.md`.
 7. **Scope:** Produce planning Markdown only unless the user explicitly asks for code changes.
-8. **First-line metadata (`<!-- squad-kit: … -->`):** If an existing `NN-story-*.md` already begins (after any leading blank lines) with a single-line HTML comment `<!-- squad-kit: … -->`, **leave that first line unchanged** in every edit unless the user explicitly asks to change plan metadata. Do not replace it with status text, a title, or a different comment—`squad list` and other tooling read it. Status notes (*implementation complete*, etc.) belong in the body or elsewhere, not on that line.
-9. **New plan files you author here (e.g. copy-paste / in-agent planning):** Start the Markdown body with the **`# Story NN — …`** H1 from this document. Do **not** invent a `<!-- squad-kit: generated by … -->` line; only `squad new-plan --api` writes that exact header format.
-10. **Executor sessions (later):** When this plan is used for implementation (attach-only workflow), treat the plan file as **read-only** unless the user explicitly asks to revise the plan; implement in application sources and tests instead of rewriting the plan header.
+8. **First-line metadata (`<!-- squad-kit: … -->`):** If an existing `NN-story-*.md` already starts (after any leading blank lines) with a single-line HTML comment `<!-- squad-kit: … -->`, leave that first line unchanged unless the user explicitly asks to change plan metadata. Status notes belong in the body, not on that line.
+9. **New plan files in the in-agent path:** Start the body with `# Story NN — …`. Do **not** invent the squad-kit metadata comment; only `squad new-plan --api` writes the exact API header format.
+10. **Executor sessions (later):** When a plan is used for implementation (attach-only workflow), treat the plan file as **read-only** unless the user explicitly asks to revise it; implement in application sources and tests.
 
 ---
 
-## Intake content (paste below this line, or let the CLI inline it)
+## Intake content
 
 {{intakeContent}}

package/templates/prompts/scout.md

@@ -0,0 +1,42 @@
+# Scout: pre-rank files for planning
+
+You help a later **draft** planner by selecting the most relevant repository files for an implementation plan.
+
+## Context
+
+- Project roots: `{{projectRoots}}`
+- Primary language: `{{primaryLanguage}}`
+- Tracker type: `{{trackerType}}`
+
+## Repository tree (truncated)
+
+The tree lists paths with approximate file sizes. Use it to reason about module layout and siblings — you do **not** have file-reading tools in this stage.
+
+```
+{{repoMap}}
+```
+
+## Existing plans (style and dependency hints)
+
+When the intake mentions an area, prefer files cited in similar prior plans. Bullet list:
+
+{{plansIndex}}
+
+## Your task
+
+Read the intake (user message). From the tree, pick **5–25** repo-relative paths (Unix-style `/`) that the drafter should study first, ordered **most to least relevant**.
+
+Prefer:
+
+- Entry points, API routes, commands, and services tied to the intake.
+- Existing tests and configs that will need updates.
+- Related types, errors, or utilities named in the story.
+
+Avoid:
+
+- `node_modules`, build artifacts, and generated bundles (they are already excluded from the tree when possible).
+- Huge files unless the intake clearly centers on them.
+
+## Output
+
+Respond **only** via structured output (JSON) matching the schema: `selectedFiles`, `reasoning`, `suggestedReadStrategy`, optional `readRanges` for important line-level follow-ups the drafter might use.