pi-soly 1.16.2 → 1.16.4

package/nudge.ts

@@ -169,7 +169,31 @@ export function buildNudgeSection(
       - \`soly verify\`                         — self-review loop until clean
       - \`soly status\`                         — current position + progress (no LLM round-trip)
 
-   **You may scaffold a new plan yourself** when the user asks for a new piece of work and the scope is clear (or the user just confirmed). Propose the slug AND the full branch name first via ask_pro — offer the default \`${prefix ? prefix + "/" : ""}<slug>\` plus the alternatives \`fix/<slug>\`, \`chore/<slug>\`, or just \`<slug>\` (no prefix). Pick whatever fits the work, then type \`soly new …\` in your next output. Don't ask for trivial one-liners or when the user already said "go". Skip only for a genuine one-off that doesn't deserve a plan branch.`
+   **You may scaffold a new plan yourself** when the user asks for a new piece of work and the scope is clear (or the user just confirmed). Propose the slug AND the full branch name first via ask_pro — offer the default \`${prefix ? prefix + "/" : ""}<slug>\` plus the alternatives \`fix/<slug>\`, \`chore/<slug>\`, or just \`<slug>\` (no prefix). Pick whatever fits the work, then type \`soly new …\` in your next output. Don't ask for trivial one-liners or when the user already said "go". Skip only for a genuine one-off that doesn't deserve a plan branch.
+
+   **STUDY THE REPO before scaffolding or fleshing out a plan.** Before you write or edit any plan, use the available tools to understand the area you're about to touch:
+   - \`soly_snippet(path, offset, limit)\` and \`soly_doc_search(query)\` for bounded reads of the relevant files (don't \`read\` the whole tree — that's why these tools exist).
+   - The \`## project layout\` section in this system prompt for a directory overview.
+   - \`.agents/docs/\` (intent) for *why* the project is the way it is.
+   - \`git log --oneline -20\` for recent context (existing patterns, prior decisions).
+
+   What to extract: where similar features live, the naming/file-layout conventions, how errors are handled, how tests are written, and any constraints you missed in the prompt. Surface ambiguities as \`ask_pro\` questions BEFORE writing the plan — a plan that knows "the tests go in __tests__/" beats a plan that picks an arbitrary location and rewrites.
+
+   **Corporate reviewer — gap-hunt the plan before coding.** Even when PLAN.md already exists and looks approved, BEFORE you touch any code (a phase, a task, or an arbitrary edit):
+      1. Re-read the entire PLAN.md end-to-end. Read adjacent code (one similar feature) with \`soly_snippet\`.
+      2. List concrete gaps the plan doesn't address, in priority order. Examples to look for:
+         - **Placement** — which file(s) does the new code live in? If the plan names them, read them; if not, decide and ask.
+         - **Naming** — function/class/variable names that match existing conventions? (camelCase vs snake_case, verb vs noun, get/set prefix)
+         - **Boundary cases** — empty inputs, large inputs, concurrent access, missing files, malformed data. Did the plan mention any? Will the implementation handle them?
+         - **Errors** — what does this code do when X fails? Does the plan say? Does the codebase have an existing error pattern to follow?
+         - **Existing instances** — if the pattern already exists in the codebase (e.g. another route, another component, another handler), what happens to them? Migration? Coexistence?
+         - **Tests** — does the plan name the test file? The fixture data? The assertion style?
+         - **Rollout / risk** — is this safe to merge? Does anything need a feature flag, a config gate, or a deprecation window?
+      3. If you find ANY material gap, ask the user via \`ask_pro\` BEFORE writing a single line of code. Phrase each question with a recommended default + 2-3 alternatives. Don't pick for the user.
+      4. If the plan is genuinely complete and you find no gaps, say so explicitly ("No gaps found in PLAN.md, proceeding") and proceed.
+      5. This is independent of \`confirmBeforeCode\` (\`scope\` / \`ask\` / \`off\`). The reviewer runs even when the user said "go" — it's the last filter, not the first.
+
+   Why this exists: plans that look complete often aren't. Asking 4 sharp questions with defaults saves a 40-minute rebuild when an assumption turns out to be wrong. Don't rush.`
 			: "";
 
 	// Confirm-before-coding gate: for non-trivial implementation, pull the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "1.16.2",
+  "version": "1.16.4",
   "description": "Project management + workflow framework for pi-coding-agent. Plans, state, MANDATORY rules, self-review, multi-question picker, native footer + welcome chrome — one npm install, zero config. The LLM drives execution and delegates to a worker subagent when available.",
   "type": "module",
   "main": "index.ts",

package/workflows/execute.ts

@@ -181,6 +181,8 @@ The worker reads this file first — it contains intent, STATE, ROADMAP (n/a for
 
 **0-POINT CHECK.** Worker must re-read .agents/docs/ (intent) and .agents/features/${task.feature}/README.md before implementing.
 
+**STUDY THE REPO.** The worker MUST use \`soly_snippet(path, offset, limit)\`, \`soly_doc_search(query)\`, and \`## project layout\` from the system prompt to understand the area before changing any file. Read at least: the module being modified, one similar feature for the pattern, and the corresponding test file. Do NOT change code based on assumptions about how the existing code works.
+
 Launch a single subagent for this work. Do NOT do the work inline.
 
 subagent({
@@ -326,6 +328,10 @@ ${planBody.slice(0, 4000)}${planBody.length > 4000 ? "\n…(truncated)" : ""}
 
 **0-POINT CHECK.** Worker must re-read .agents/docs/ (intent) before implementing.
 
+**STUDY THE REPO.** Worker MUST use \`soly_snippet(path, offset, limit)\`, \`soly_doc_search(query)\`, and \`## project layout\` from the system prompt to map the area before editing. Read at least: the module(s) the plan touches, one adjacent feature for the convention, and any test files in the same area. Do NOT edit code on assumptions about how existing code is structured.
+
+**Corporate reviewer — gap-hunt the plan first.** Re-read the entire PLAN.md end-to-end. Identify concrete gaps (file paths not named, error handling missing, boundary cases unmentioned, no test file cited, no migration plan for existing instances, etc.). If you find ANY material gap, use \`ask_pro\` to surface it to the user BEFORE editing a single file — phrase each question with a recommended default + 2-3 alternatives. Only after gaps are resolved (or explicitly accepted by the user) may implementation begin.
+
 Launch a single subagent to execute the plan. Do NOT do the work inline.
 
 subagent({

package/workflows/planning.ts

@@ -118,6 +118,8 @@ ${planBody.slice(0, 4000)}${planBody.length > 4000 ? "\n…(truncated)" : ""}
 
 **0-POINT CHECK.** Re-read .agents/docs/ (intent) before fleshing out the plan.
 
+**STUDY THE REPO.** Before writing PLAN.md, use \`soly_snippet(path, offset, limit)\` and \`soly_doc_search(query)\` to understand the area this plan will touch. Look at how similar features are implemented in this codebase (naming, file layout, error handling, test convention), and check \`## project layout\` from the system prompt for orientation. Extract enough context that the plan names concrete files and conventions, not abstractions. Surface ambiguities as \`ask_pro\` questions BEFORE writing PLAN.md.
+
 If ask_pro is available, use it ONCE to gather goal / steps / acceptance criteria (freeText questions, batched). Then write PLAN.md with the answers. If ask_pro is NOT available, write a sensible stub plan and tell the user to refine it via \`soly plan ${target.raw}\` again.
 
 Hard rules:
@@ -543,6 +545,8 @@ ${planBody.slice(0, 4000)}${planBody.length > 4000 ? "\n…(truncated)" : ""}
 
 **0-POINT CHECK.** Re-read .agents/docs/ (intent) before discussing.
 
+**STUDY THE REPO.** Use \`soly_snippet(path, offset, limit)\`, \`soly_doc_search(query)\`, and \`## project layout\` from the system prompt to understand the area the plan touches. The discussion should resolve real ambiguities in the existing code, not invent new ones. If the plan body mentions files you haven't read, read them first.
+
 Use \`soly_finish_discuss\` to capture the discussion outcome. The flow:
 1. Read the plan above.
 2. Identify ambiguities / open questions / scope clarifications.