gentle-pi 0.4.1 → 0.4.2

package/assets/agents/sdd-proposal.md

@@ -13,6 +13,19 @@ Use your assigned executor/phase skill for this SDD phase. For project/user skil
 If skill paths are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `paths-injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should pass indexed paths next time.
 
 - Read exploration and project standards before writing.
+- In interactive SDD mode, do not make the agent decide silently whether the proposal is "clear enough". Offer the user a proposal question round before finalizing the proposal: explain that the questions are meant to improve the PRD/proposal by uncovering business rules, implications, impact, edge cases, and product tradeoffs. Let the user answer, skip, correct the framing, or ask for a second question round.
+- Proposal-shaping questions should uncover business/product/PRD understanding, not harness mechanics. Cover the smallest useful subset of:
+  1. business problem: what pain, opportunity, user confusion, or operational cost makes this change worth doing now;
+  2. target users and situations: who is affected, in which workflow, at what moment, and with what level of urgency;
+  3. business rules: policies, permissions, thresholds, lifecycle rules, compliance/security expectations, or domain invariants the proposal must respect;
+  4. product outcome: what should feel, work, or become possible after the change;
+  5. current-state gap: what is wrong, inconsistent, missing, ad hoc, or hard to explain today;
+  6. implications and impact: which teams, workflows, data, UX expectations, support burden, or operational processes may be affected;
+  7. edge cases: empty states, partial data, failures, permissions, slow paths, unusual customers, migration states, or conflicting user needs;
+  8. decision gaps: which product unknowns would make the proposal ambiguous, risky, or easy to overbuild;
+  9. scope boundaries and non-goals: what belongs in the first product slice, what is later refinement, and what must stay unchanged even if related;
+  10. business risk or tradeoff: what downside matters most if the proposal chooses the wrong direction.
+- Prefer 3–5 concrete product questions per round. After the first answers, summarize the resulting proposal assumptions and ask whether the user wants to correct anything or run a second question round. Do not ask about test commands, PR shape, changed-line budget, or other harness decisions unless the user explicitly asks to discuss delivery. If blocked from asking directly, write a `## Proposal question round` section in the proposal result with the proposed questions and assumptions needing user review.
 - Write `openspec/changes/{change}/proposal.md`.
 - Include intent, scope, affected areas, risks, rollback, and success criteria.
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.

package/assets/chains/sdd-full.chain.md

@@ -1,8 +1,12 @@
 ---
 name: sdd-full
-description: Run the full SDD lifecycle for a change when explicitly approved.
+description: Run the full SDD lifecycle for a change in auto mode or explicit full-lifecycle approval.
 ---
 
+## Interactive mode guard
+
+This chain is a continuous lifecycle pipeline. Use it only in auto mode or explicit full-lifecycle approval. In interactive mode the parent/orchestrator must stop at each phase boundary, present the current artifact, and ask the user before continuing. Approval to start SDD is not approval of the generated proposal, specs, design, tasks, apply, verify, sync, or archive phases.
+
 ## sdd-init
 
 output: init.md
@@ -27,7 +31,7 @@ output: proposal.md
 outputMode: file-only
 progress: true
 
-Create or update the OpenSpec proposal for {task} using the exploration notes and the previous step output.
+Create or update the OpenSpec proposal for {task} using the exploration notes and the previous step output. If this is an interactive SDD run and the parent has not already supplied proposal-shaping answers, surface the missing questions in the result so the parent can ask before treating the proposal as approved.
 
 ## sdd-spec
 
@@ -36,7 +40,7 @@ output: spec.md
 outputMode: file-only
 progress: true
 
-Write delta specs for {task} from the approved proposal. Preserve RFC 2119 requirements and Given/When/Then scenarios.
+Write delta specs for {task} from the parent-approved proposal. Preserve RFC 2119 requirements and Given/When/Then scenarios. In interactive mode, do not treat chain execution alone as proposal approval.
 
 ## sdd-design
 

package/assets/chains/sdd-plan.chain.md

@@ -1,8 +1,12 @@
 ---
 name: sdd-plan
-description: Plan an SDD change through proposal, spec, design, and tasks.
+description: Plan an SDD change through proposal, spec, design, and tasks; safe for auto mode or explicit all-planning approval.
 ---
 
+## Interactive mode guard
+
+This chain is a continuous planning pipeline. Use it only in auto mode or explicit all-planning approval. In interactive mode the parent/orchestrator must stop after sdd-proposal, present the proposal, and ask the user before continuing to sdd-spec, sdd-design, and sdd-tasks.
+
 ## sdd-init
 
 output: init.md
@@ -18,7 +22,7 @@ output: proposal.md
 outputMode: file-only
 progress: true
 
-Create or update the OpenSpec proposal for {task}. Use prior exploration if it is available in the project artifacts.
+Create or update the OpenSpec proposal for {task}. Use prior exploration if it is available in the project artifacts. If this is an interactive SDD run and the parent has not already supplied proposal-shaping answers, surface the missing questions in the result so the parent can ask before treating the proposal as approved.
 
 ## sdd-spec
 

package/assets/orchestrator.md

@@ -249,6 +249,10 @@ In interactive mode, between phases:
 2. state next phase;
 3. ask whether to continue or adjust.
 
+Interactive approval is phase-scoped. A user response such as "continue", "dale", or "go on" approves only the immediate next phase, not the rest of the SDD pipeline. Do not treat a generated artifact as approved until the user has had a chance to review or explicitly delegate that review.
+
+Before `sdd-proposal` in interactive mode, offer the user a proposal question round instead of silently deciding whether the proposal is clear enough. Explain that the questions are meant to improve the PRD/proposal by uncovering business understanding, business rules, implications, impact, edge cases, and product tradeoffs. Prefer 3–5 concrete product questions per round, then summarize the resulting assumptions and ask whether the user wants to correct anything or run a second question round. Cover business/product/PRD decisions: business problem, target users and situations, business rules, product outcome, current-state gap, implications and impact, edge cases, decision gaps, first-slice scope boundaries, non-goals, product constraints, and business tradeoffs. Do not ask about test commands, PR shape, changed-line budget, or other harness mechanics at proposal time unless the user explicitly asks to discuss delivery.
+
 ## Result Contract
 
 Every phase result should include:

package/lib/sdd-preflight.ts

@@ -235,6 +235,16 @@ export function renderSddPreflightPrompt(prefs: SddPreflightPreferences): string
 	const sourceLine = prefs.prompted
 		? "The user already chose these SDD preferences for this Pi session. Reuse them unless the user explicitly changes them."
 		: "No interactive UI was available for SDD preflight, so these default preferences were applied for this Pi session. Ask the user before making delivery decisions that depend on them.";
+	const interactiveRules =
+		prefs.executionMode === "interactive"
+			? [
+					"- Interactive phase gate: complete only the current SDD phase. Do not start the next SDD phase unless the current user turn explicitly approves that next phase.",
+					"- In interactive mode, words like `continue`, `dale`, or `go on` approve only the immediate next phase, not all remaining phases.",
+					"- Before writing an SDD proposal in interactive mode, offer the user a proposal question round to improve the PRD/proposal by uncovering business rules, implications, impact, edge cases, product tradeoffs, and decision gaps. Prefer 3–5 concrete product questions per round, then summarize assumptions and ask whether the user wants corrections or a second question round. Do not ask about test commands, PR shape, changed-line budget, or other harness mechanics at proposal time unless the user explicitly asks to discuss delivery.",
+				]
+			: [
+					"- Auto mode: phases may run back-to-back only because the user chose speed and trusts the flow.",
+				];
 	return [
 		"## SDD Session Preflight",
 		sourceLine,
@@ -242,6 +252,7 @@ export function renderSddPreflightPrompt(prefs: SddPreflightPreferences): string
 		`- Artifact store: ${prefs.artifactStore}${prefs.engramAvailable ? "" : " (Engram unavailable in this session)"}`,
 		`- Chained PR strategy: ${prefs.chainedPrStrategy}`,
 		`- Review budget: ${prefs.reviewBudgetLines} changed lines`,
+		...interactiveRules,
 		"- If task/workload forecasts conflict with these preferences, pause before sdd-apply and ask the user for a delivery decision.",
 	].join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",

package/tests/artifact-language.test.ts

@@ -73,11 +73,51 @@ test("rendered SDD preflight prompt is English artifact copy", () => {
 
 	assert.match(prompt, /The user already chose these SDD preferences/);
 	assert.match(prompt, /Review budget: 400 changed lines/);
+	assert.match(prompt, /complete only the current SDD phase/i);
+	assert.match(prompt, /Do not start the next SDD phase/i);
+	assert.match(prompt, /approve only the immediate next phase/i);
+	assert.match(prompt, /offer the user a proposal question round/i);
+	assert.match(prompt, /business rules, implications, impact, edge cases/i);
+	assert.match(prompt, /second question round/i);
 	for (const pattern of SPANISH_PREFLIGHT_COPY) {
 		assert.doesNotMatch(prompt, pattern);
 	}
 });
 
+test("SDD proposal questions focus on business and PRD gaps", async () => {
+	const proposalAgent = await readFile(join(ROOT, "assets/agents/sdd-proposal.md"), "utf8");
+
+	assert.match(proposalAgent, /offer the user a proposal question round/i);
+	assert.match(proposalAgent, /second question round/i);
+	assert.match(proposalAgent, /business problem/i);
+	assert.match(proposalAgent, /business rules/i);
+	assert.match(proposalAgent, /implications and impact/i);
+	assert.match(proposalAgent, /edge cases/i);
+	assert.match(proposalAgent, /target users/i);
+	assert.match(proposalAgent, /product outcome/i);
+	assert.match(proposalAgent, /decision gaps/i);
+	// Proposal-shaping questions must stay on business/product ground: the agent is
+	// explicitly told to keep harness mechanics out of the proposal question round
+	// unless the user opts into discussing delivery. Removing this guard is the most
+	// likely way harness mechanics would leak back into proposal questions.
+	assert.match(
+		proposalAgent,
+		/Do not ask about test commands, PR shape, changed-line budget, or other harness decisions unless the user explicitly asks to discuss delivery/i,
+	);
+});
+
+test("SDD chain assets distinguish interactive gates from auto execution", async () => {
+	const planChain = await readFile(join(ROOT, "assets/chains/sdd-plan.chain.md"), "utf8");
+	const fullChain = await readFile(join(ROOT, "assets/chains/sdd-full.chain.md"), "utf8");
+
+	assert.match(planChain, /auto mode or explicit all-planning approval/i);
+	assert.match(planChain, /interactive mode/i);
+	assert.match(planChain, /must stop after sdd-proposal/i);
+	assert.match(fullChain, /auto mode or explicit full-lifecycle approval/i);
+	assert.match(fullChain, /interactive mode/i);
+	assert.match(fullChain, /must stop at each phase boundary/i);
+});
+
 test("persistent harness prompt assets do not hardcode Spanish SDD artifact copy", async () => {
 	const files = [
 		...(await collectTextFiles(join(ROOT, "assets"))),