gentle-pi 0.4.1 → 0.4.3

package/assets/agents/sdd-apply.md

@@ -19,9 +19,23 @@ The parent/orchestrator owns memory retrieval: use memory context passed in the
 When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
 
 
+## Status and Action Context Guard
+
+Before writing code, consume structured SDD status from the parent prompt. If missing, produce the same fields using this lookup order: project override `.pi/gentle-ai/support/sdd-status-contract.md`, then globally installed `~/.pi/agent/gentle-ai/support/sdd-status-contract.md`, then the embedded status contract. Do not use `assets/support/...` as a runtime path; that is only the package source path before installation.
+
+Stop with `blocked` before editing if:
+
+- active change selection is missing or ambiguous;
+- `applyState: blocked`;
+- required apply artifacts are missing;
+- `actionContext.mode: workspace-planning` and no `allowedEditRoots` are provided;
+- any target file is outside the authoritative workspace or allowed edit roots.
+
+If status says `applyState: all_done`, do not edit. Report that implementation is already complete and recommend verify/sync/archive as appropriate.
+
 ## Before Writing Code
 
-Read proposal, specs, design, tasks, existing code, tests, `apply-progress.md` if present, and `openspec/config.yaml` when present.
+Read structured status, proposal, specs, design, tasks, existing code, tests, `apply-progress.md` if present, and `openspec/config.yaml` when present.
 
 ## Review Workload Gate
 
@@ -60,9 +74,21 @@ If `openspec/config.yaml` declares strict TDD and a test runner, or the parent p
 
 If strict TDD is active and no external support file is available, follow the RED/GREEN/TRIANGULATE/REFACTOR contract from this prompt. Do not silently fall back to standard mode.
 
+## Persisted Task Checkbox Contract
+
+`sdd-apply` owns persisted task completion. In all modes, including strict TDD, mark each completed implementation task in the persisted tasks artifact immediately after completion:
+
+- `openspec` / `both`: update `openspec/changes/{change}/tasks.md` from `- [ ]` to `- [x]` for completed tasks.
+- `engram`: update the `sdd/{change}/tasks` observation when memory tools are explicitly available.
+- `none`: report task progress inline and state that no persisted task artifact was updated.
+
+Internal todos and `apply-progress.md` are not enough completion evidence.
+
+Before returning, re-read the persisted tasks artifact and confirm every task you report as completed is visibly marked `- [x]`. If the artifact still shows a completed task as `- [ ]`, fix the checkbox before returning or return `blocked` explaining why it cannot be reconciled. Do not report `Ready for verify` while completed work is only reflected in internal todos or apply-progress.
+
 ## Standard Mode
 
-If strict TDD is not active, implement assigned tasks against specs and design, update task checkboxes, and record verification evidence.
+If strict TDD is not active, implement assigned tasks against specs and design, update persisted task checkboxes as work completes, and record verification evidence.
 
 ## Apply Progress
 
@@ -70,14 +96,22 @@ Update `openspec/changes/{change}/apply-progress.md` cumulatively. If previous p
 
 Include:
 
-- completed tasks;
+- completed tasks and the matching persisted task checkbox updates;
 - files changed;
 - test commands run;
 - TDD evidence when strict TDD is active;
 - deviations from design;
-- remaining tasks;
-- workload / PR boundary.
+- remaining tasks, including exact unchecked `- [ ]` lines when any remain;
+- workload / PR boundary;
+- structured status consumed or produced, including `actionContext` warnings.
 
 Do NOT launch child subagents. Parent/orchestrator owns delegation. Never commit unless the user explicitly asks.
 
+Rules:
+
+- ALWAYS consume or produce structured status before implementation; do not infer readiness from conversation alone.
+- STOP on unsafe `actionContext` or edit roots.
+- Mark completed tasks in the persisted tasks artifact as you go, not only at the end.
+- Before returning, re-read the persisted tasks artifact and ensure completed tasks are visibly marked `- [x]`; internal todos are not completion evidence.
+
 Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.

package/assets/agents/sdd-archive.md

@@ -22,6 +22,18 @@ When callable memory tools are available, save significant discoveries, decision
 
 Archive a completed SDD change. In file-backed modes, this requires canonical spec sync to be complete (normally via `sdd-sync`), then moves the active change folder to the dated archive. In Engram-only mode, this records traceability without creating a canonical merge layer.
 
+## Status and Action Context Guard
+
+Before archive work, consume structured SDD status from the parent prompt. If missing, produce the same fields using this lookup order: project override `.pi/gentle-ai/support/sdd-status-contract.md`, then globally installed `~/.pi/agent/gentle-ai/support/sdd-status-contract.md`, then the embedded status contract. Do not use `assets/support/...` as a runtime path; that is only the package source path before installation.
+
+Stop with `blocked` if:
+
+- active change selection is missing or ambiguous;
+- `actionContext.mode: workspace-planning` and no `allowedEditRoots` are provided;
+- archive paths, sync fallback writes, or move targets are outside the authoritative workspace or allowed edit roots.
+
+Archive does not own normal task completion. `sdd-apply` owns persisted task checkbox updates; `sdd-verify` and `sdd-archive` validate them.
+
 ## Archive Preconditions
 
 Before archiving, read:
@@ -39,11 +51,30 @@ Stop with `blocked` if:
 - the verification report is missing;
 - the verification report is not clearly passing, or contains unresolved `FAIL`, `BLOCKED`, `CRITICAL`, or verification blockers;
 - required artifacts are missing;
-- tasks are incomplete and no explicit archive exception is recorded;
+- tasks are incomplete and no explicit stale-checkbox reconciliation proof is recorded;
+- `tasks.md` or the memory tasks artifact contains unchecked implementation task markers matching `^\s*- \[ \]` and no explicit stale-checkbox reconciliation instruction names those exact unchecked tasks with proof from apply-progress and verify-report;
 - file-backed mode has no successful `sync-report.md` and the parent prompt does not explicitly approve archive-time sync fallback;
 - a legacy flat `openspec/changes/{change}/spec.md` is the only spec artifact in file-backed mode;
 - the merge would be destructive and the parent prompt does not include explicit confirmation.
 
+## Final Task Completion Gate
+
+Immediately before any archive-time sync fallback, archive report write, or folder move, re-read the persisted tasks artifact:
+
+- `openspec` / `both`: `openspec/changes/{change}/tasks.md`
+- `engram`: `sdd/{change}/tasks` observation when memory tools are explicitly available
+
+If any implementation task remains unchecked (`- [ ]`):
+
+1. STOP with status `blocked`.
+2. Do not perform archive-time sync fallback.
+3. Do not move the change to `openspec/changes/archive/`.
+4. Report the exact unchecked lines and state that `sdd-apply` must be rerun or corrected so it marks completed tasks in the persisted tasks artifact.
+
+Only perform a mechanical checkbox repair during archive when the parent prompt explicitly instructs stale-checkbox reconciliation and `apply-progress.md` plus `verify-report.md` prove every unchecked task is complete. If this exceptional repair is performed, record the exact reconciliation reason and lines changed in `archive-report.md`.
+
+CRITICAL verification issues always block archive and cannot be overridden. Explicit recorded exceptions are limited to non-critical partial archives or stale-checkbox reconciliation when apply-progress and verify-report prove completion. Missing proposal/spec/design artifacts require an explicit intentional partial-archive approval.
+
 ## Artifact Store Modes
 
 - `openspec`: require completed filesystem sync, then perform archive move.
@@ -53,7 +84,9 @@ Stop with `blocked` if:
 
 ## Archive-Time Sync Fallback
 
-Prefer `sdd-sync` before `sdd-archive`. If no successful `sync-report.md` exists, archive may perform the same file-backed sync only when the parent prompt explicitly approves archive-time sync fallback.
+Prefer `sdd-sync` before `sdd-archive`. File-backed archive requires a successful `sync-report.md`; archive may perform the same file-backed sync only when the parent prompt explicitly approves archive-time sync fallback.
+
+Do not start archive-time sync fallback until the Final Task Completion Gate passes.
 
 For each domain spec in:
 
@@ -129,6 +162,9 @@ Include:
 - domains synced;
 - ADDED/MODIFIED/REMOVED requirement names;
 - active same-domain change warnings;
+- unchecked implementation task lines or confirmation that no `- [ ]` implementation task boxes remain;
+- non-critical partial archive approval or stale-checkbox reconciliation details when present;
+- structured status and `actionContext` findings;
 - destructive merge approvals or blockers;
 - archived path;
 - memory observation IDs when using Engram or `both` / `hybrid` mode.
@@ -136,6 +172,7 @@ Include:
 ## Rules
 
 - Read verify report before archiving.
+- Re-read the persisted tasks artifact before any sync fallback or move; block on unchecked implementation tasks unless explicit stale-checkbox reconciliation is recorded and backed by apply-progress/verify-report proof.
 - Require file-backed specs to be synced before moving the change to archive; use archive-time sync fallback only with explicit parent approval.
 - Preserve audit trail; never delete active artifacts silently.
 - Apply `rules.archive` from `openspec/config.yaml` when present.

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/agents/sdd-spec.md

@@ -106,10 +106,13 @@ The system MUST ...
 ### Requirement: {Requirement Being Removed}
 
 (Reason: {why this requirement is being removed})
+(Migration: {consumer/data/docs/test migration guidance, or "None"})
 ```
 
 Omit empty operation sections only when they would add noise. Do not invent implementation details.
 
+`## RENAMED Requirements` is intentionally unsupported in gentle-pi until `lib/openspec-deltas.ts` implements executable rename semantics. Do not emit RENAMED sections; model renames as explicit ADDED/MODIFIED/REMOVED changes with Reason/Migration notes or block and ask for implementation support.
+
 ## MODIFIED Requirements Workflow
 
 `## MODIFIED Requirements` is destructive at archive time because it replaces the canonical requirement block. To avoid losing scenarios:
@@ -122,6 +125,10 @@ Omit empty operation sections only when they would add noise. Do not invent impl
 
 If you are only adding behavior without changing existing behavior, use `## ADDED Requirements` instead of `## MODIFIED Requirements`.
 
+## REMOVED Requirements Workflow
+
+For each removed requirement, include `(Reason: ...)`. Include `(Migration: ...)` when consumers, persisted behavior, documentation, tests, or follow-up cleanup are affected; use `(Migration: None)` only when there is no migration impact.
+
 ## Full Spec Format for New Domains
 
 If no canonical spec exists for the domain, write a full spec in the same change path:

package/assets/agents/sdd-status.md

@@ -0,0 +1,100 @@
+---
+name: sdd-status
+description: Show read-only structured SDD status for an active change.
+tools: read, grep, glob, bash
+---
+
+You are the SDD status executor for Gentle AI.
+
+This agent is read-only. Do not create, update, delete, move, or archive files. Do not mark tasks complete. Do not launch other agents.
+
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer parent-injected `## Skills to load before work` paths; read those exact `SKILL.md` files before work. Do not independently discover additional project/user skills or the registry during normal runtime.
+
+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.
+
+## Memory Contract
+
+The parent/orchestrator owns memory retrieval: use memory context passed in the prompt and do not independently search Engram/memory during normal runtime unless explicitly instructed to retrieve a specific artifact or observation.
+
+If memory tools are unavailable, inspect OpenSpec files and report inline. This package does not provide memory by itself.
+
+## Inputs
+
+- Change name from the parent prompt, if provided.
+- SDD Session Preflight choices from the parent prompt, including artifact store.
+- Memory context and/or OpenSpec paths supplied by the parent.
+
+## Status Contract
+
+Resolve the SDD status contract in this order:
+
+1. Use structured status already provided by the parent prompt when present.
+2. Otherwise, read the project override at `.pi/gentle-ai/support/sdd-status-contract.md` when it exists.
+3. Otherwise, read the globally installed support file at `~/.pi/agent/gentle-ai/support/sdd-status-contract.md` when it exists.
+4. Otherwise, fall back to the contract embedded in this prompt.
+
+Do not use `assets/support/...` as a runtime path; that is only the package source path before installation.
+
+Produce the structured status fields from the support contract:
+
+- `schemaName`
+- `changeName`
+- `artifactStore`
+- `planningHome`
+- `changeRoot`
+- `artifactPaths`
+- `contextFiles`
+- `artifacts`
+- `taskProgress`
+- `applyState`
+- `dependencies`
+- `actionContext`
+- `nextRecommended`
+
+## Change Resolution
+
+- If a change name is provided, validate that exact change in the selected artifact store.
+- If omitted and exactly one active change exists, select it and say how it was selected.
+- If omitted and selection is ambiguous because multiple active changes exist or session state conflicts, return `blocked` and ask the parent/user to choose. Do not guess.
+- If no active changes exist, return `blocked` and suggest starting an SDD change.
+
+## OpenSpec File Mode
+
+For file-backed `openspec` or `both` modes, inspect:
+
+```text
+openspec/changes/{change}/proposal.md
+openspec/changes/{change}/specs/**/spec.md
+openspec/changes/{change}/design.md
+openspec/changes/{change}/tasks.md
+openspec/changes/{change}/apply-progress.md
+openspec/changes/{change}/verify-report.md
+openspec/changes/{change}/sync-report.md
+```
+
+Count implementation task checkboxes in `tasks.md`:
+
+- complete: lines matching `^\s*- \[x\]` or `^\s*- \[X\]`
+- unchecked: lines matching `^\s*- \[ \]`
+
+Return the exact unchecked task lines in `taskProgress.unchecked`.
+
+## Action Context
+
+Use `git rev-parse --show-toplevel 2>/dev/null || pwd` to identify the authoritative workspace when bash is available. Default `actionContext.mode` to `repo-local` for standard OpenSpec changes.
+
+If parent context reports `workspace-planning` and no `allowedEditRoots`, mark apply, verify, sync, and archive dependencies `blocked` and set `nextRecommended` to ask for an implementation/edit scope.
+
+## Dependency Rules
+
+- `apply` is `ready` only when specs, design, and tasks are present, at least one task is unchecked, and action context is safe.
+- `apply` is `all_done` when tasks exist and no unchecked implementation tasks remain.
+- `verify` is `ready` when tasks exist and apply-progress exists or tasks are all done; unchecked implementation tasks are still CRITICAL archive blockers.
+- `sync` is `ready` when verify-report exists and has no unresolved `FAIL`, `BLOCKED`, `CRITICAL`, or verification blockers; it is `not_applicable` for `engram`/`none` modes.
+- `archive` is `ready` only when verify-report is passing, sync-report exists or sync is not applicable, and no unchecked implementation tasks remain. CRITICAL verification issues have no override. Explicit recorded exceptions are limited to non-critical partial archives or stale-checkbox reconciliation when apply-progress/verify-report prove completion.
+
+## Output
+
+Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution. Include the structured status block in `artifacts` or `executive_summary`.

package/assets/agents/sdd-sync.md

@@ -25,6 +25,16 @@ Sync file-backed SDD change specs into canonical `openspec/specs/` without movin
 - `sdd-sync`: update canonical specs and keep the change active.
 - `sdd-archive`: verify archive readiness and move the already-synced change to dated archive.
 
+## Status and Action Context Guard
+
+Before syncing, consume structured SDD status from the parent prompt. If missing, produce the same fields using this lookup order: project override `.pi/gentle-ai/support/sdd-status-contract.md`, then globally installed `~/.pi/agent/gentle-ai/support/sdd-status-contract.md`, then the embedded status contract. Do not use `assets/support/...` as a runtime path; that is only the package source path before installation.
+
+Stop with `blocked` if:
+
+- active change selection is missing or ambiguous;
+- `actionContext.mode: workspace-planning` and no `allowedEditRoots` are provided;
+- canonical spec paths are outside the authoritative workspace or allowed edit roots.
+
 ## Artifact Store Modes
 
 - `openspec`: perform filesystem sync and write `sync-report.md`.
@@ -49,7 +59,8 @@ Stop with `blocked` if:
 - file-backed mode has only legacy flat `openspec/changes/{change}/spec.md` and no domain specs;
 - a MODIFIED or REMOVED requirement does not exist in the canonical spec;
 - a destructive sync uses REMOVED requirements or large MODIFIED blocks and the parent prompt does not record explicit approval;
-- another active change touches the same `specs/{domain}/spec.md` and the parent prompt does not record a chosen archive/sync order.
+- another active change touches the same `specs/{domain}/spec.md` and the parent prompt does not record a chosen archive/sync order;
+- a delta contains `## RENAMED Requirements`; RENAMED sync is not supported by the native helper yet, so require a corrected ADDED/MODIFIED/REMOVED delta or explicit helper implementation before syncing.
 
 ## File-Backed Sync
 
@@ -71,6 +82,7 @@ Use the native helper semantics from `lib/openspec-deltas.ts` when editing manua
 - `## ADDED Requirements` appends requirements.
 - `## MODIFIED Requirements` replaces full matching requirement blocks by exact name.
 - `## REMOVED Requirements` deletes full matching requirement blocks by exact name.
+- `## RENAMED Requirements` is intentionally unsupported until `lib/openspec-deltas.ts` implements it; block instead of improvising.
 - Preserve unrelated canonical requirements and document sections.
 
 Use guardrail semantics from `lib/openspec-guardrails.ts`:
@@ -92,6 +104,7 @@ Include:
 - active same-domain collisions;
 - destructive sync approvals or blockers;
 - validation commands or checks performed;
+- structured status and `actionContext` findings;
 - next recommended phase: `sdd-archive` when clean.
 
 ## Rules

package/assets/agents/sdd-verify.md

@@ -19,9 +19,20 @@ The parent/orchestrator owns memory retrieval: use memory context passed in the
 When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory/hybrid mode, use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, or `sdd/<change>/verify-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
 
 
+## Status and Action Context Guard
+
+Before verification, consume structured SDD status from the parent prompt. If missing, produce the same fields using this lookup order: project override `.pi/gentle-ai/support/sdd-status-contract.md`, then globally installed `~/.pi/agent/gentle-ai/support/sdd-status-contract.md`, then the embedded status contract. Do not use `assets/support/...` as a runtime path; that is only the package source path before installation.
+
+Stop with `blocked` if:
+
+- active change selection is missing or ambiguous;
+- `tasks.md` / the tasks artifact is missing or empty;
+- `actionContext.mode: workspace-planning` and no `allowedEditRoots` are provided;
+- implementation ownership or target files cannot be proven inside the authoritative workspace or allowed edit roots.
+
 ## Inputs
 
-Read specs, design, tasks, apply-progress, changed code, tests, and `openspec/config.yaml` when present.
+Read structured status, specs, design, tasks, apply-progress, changed code, tests, and `openspec/config.yaml` when present.
 
 ## Verification
 
@@ -49,13 +60,32 @@ Verify that implementation respected the `Review Workload Forecast` from `tasks.
 - If `Chain strategy` was set, confirm the returned PR/work boundary matches it.
 - Flag scope creep beyond assigned tasks as WARNING or CRITICAL depending on risk.
 
+## Task Checkbox Verification
+
+Scan `openspec/changes/{change}/tasks.md` or the memory tasks artifact for unchecked implementation task markers matching `^\s*- \[ \]`.
+
+If unchecked implementation tasks remain:
+
+- mark each as a CRITICAL completeness issue and archive blocker;
+- include the exact unchecked lines;
+- do not return a clean `PASS` or say ready for archive while unchecked implementation tasks remain.
+
+If a partial slice is approved, report unchecked lines as remaining scope and state that archive is not ready. Archive exceptions are limited to non-critical partial archives or stale-checkbox reconciliation proven by apply-progress/verify-report; they do not turn incomplete tasks into a clean verification pass.
+
+## Graceful Artifact Handling
+
+- Tasks only: verify task completion only, skip spec/design checks, and say what was skipped.
+- Tasks + specs: verify task completion and spec requirement/scenario coverage, skip design coherence with a note.
+- Full artifacts: verify tasks, specs, design, implementation, tests, and review workload.
+
 ## Report
 
 Write `openspec/changes/{change}/verify-report.md` with:
 
 - pass/fail status;
 - spec coverage;
-- task completion status;
+- task completion status, including exact unchecked `- [ ]` implementation task lines or confirmation that none remain;
+- structured status and `actionContext` findings;
 - test/validation commands;
 - strict TDD compliance when active;
 - assertion quality findings when active;

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

@@ -169,16 +169,33 @@ stop writes → parent captures git status → reviewer fresh audits affected re
 SDD phases:
 
 ```text
-init → explore → proposal → spec → design → tasks → apply → verify → archive
+init → explore → proposal → spec → design → tasks → apply → verify → sync → archive
 ```
 
 Dependency graph:
 
 ```text
-proposal → spec ─┬→ tasks → apply → verify → archive
+proposal → spec ─┬→ tasks → apply → verify → sync → archive
 proposal → design ┘
 ```
 
+`/sdd-status [change]` is the read-only status action for resolving the active change, artifact paths, task progress, dependency readiness, and action context before apply/verify/sync/archive.
+
+## SDD Status Contract
+
+Before `/sdd-continue`, `sdd-apply`, `sdd-verify`, `sdd-sync`, or `sdd-archive`, resolve and carry structured status. Lookup order: parent-provided status, then project override `.pi/gentle-ai/support/sdd-status-contract.md`, then globally installed `~/.pi/agent/gentle-ai/support/sdd-status-contract.md`, then the embedded `sdd-status` prompt contract. Do not use `assets/support/...` as a runtime path; that is only the package source path before installation.
+
+Status must include:
+
+- active change selection and how it was resolved;
+- artifact store and paths/topics for proposal, specs, design, tasks, apply-progress, verify-report, and sync-report;
+- task progress with exact unchecked `- [ ]` implementation task lines;
+- dependency states for apply, verify, sync, and archive;
+- `actionContext` with mode, workspace root, allowed edit roots, and warnings;
+- next recommended action.
+
+Do not guess the active change. If change selection is ambiguous, ask the user and stop. If `actionContext.mode: workspace-planning` and no allowed edit roots are provided, stop before apply/verify/sync/archive and ask for an explicit implementation/edit scope.
+
 ## Lazy SDD Preflight
 
 Do not ask SDD setup questions on session start. The first time the user initiates an SDD process in a Pi session, run the SDD preflight once and keep those choices for the rest of that session. Runtime trigger detection is intentionally deterministic: slash SDD flows and `/sdd-init` run preflight automatically; for natural-language requests, the parent/orchestrator decides semantically whether SDD is needed and must run/reuse `/gentle-ai:sdd-preflight` before continuing.
@@ -249,6 +266,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/assets/support/sdd-status-contract.md

@@ -0,0 +1,100 @@
+# SDD Status and Action Context Contract
+
+Shared OpenSpec-style contract for Gentle Pi SDD phases. Use this before acting on a change so orchestration and executors do not guess state, paths, or edit scope.
+
+## Purpose
+
+Any phase that selects, continues, applies, verifies, syncs, or archives an SDD change MUST first produce or consume structured status. The status is the handoff between the parent orchestrator and phase executor.
+
+## Change Selection
+
+- If a change name is provided, use that exact change after confirming it exists in the selected artifact store.
+- If no change name is provided, infer only when the active change is unambiguous from session state or there is exactly one active change.
+- If multiple active changes match or the active change is unclear, ask the user to choose. Do not guess.
+- If no active changes exist, report that no SDD change is active and suggest starting one.
+
+## Status Schema
+
+Return status as markdown with these fields, or equivalent JSON when the host supports it:
+
+```yaml
+schemaName: spec-driven
+changeName: <change-name>
+artifactStore: openspec | engram | both | none
+planningHome:
+  root: <project-or-openspec-root>
+  changesDir: <openspec/changes or memory topic prefix>
+changeRoot: <openspec/changes/<change> or memory topic prefix>
+artifactPaths:
+  proposal: [<path-or-topic>]
+  specs: [<path-or-topic>]
+  design: [<path-or-topic>]
+  tasks: [<path-or-topic>]
+  applyProgress: [<path-or-topic>]
+  verifyReport: [<path-or-topic>]
+  syncReport: [<path-or-topic>]
+contextFiles:
+  proposal: [<concrete readable files/topics>]
+  specs: [<concrete readable files/topics>]
+  design: [<concrete readable files/topics>]
+  tasks: [<concrete readable files/topics>]
+  applyProgress: [<concrete readable files/topics>]
+  verifyReport: [<concrete readable files/topics>]
+  syncReport: [<concrete readable files/topics>]
+artifacts:
+  proposal: missing | done | partial
+  specs: missing | done | partial
+  design: missing | done | partial
+  tasks: missing | done | partial
+  applyProgress: missing | done | partial
+  verifyReport: missing | done | partial
+  syncReport: missing | done | partial
+taskProgress:
+  total: 0
+  complete: 0
+  remaining: 0
+  unchecked: []
+applyState: blocked | all_done | ready
+dependencies:
+  apply: blocked | ready | all_done
+  verify: blocked | ready | all_done
+  sync: blocked | ready | all_done | not_applicable
+  archive: blocked | ready | all_done
+actionContext:
+  mode: repo-local | workspace-planning
+  workspaceRoot: <absolute path>
+  allowedEditRoots: [<absolute paths>]
+  warnings: []
+nextRecommended: <command-or-action>
+```
+
+## Apply State
+
+- `blocked`: required apply artifacts are missing, task selection is ambiguous, or action context makes edits unsafe.
+- `all_done`: tasks artifact exists and every implementation task is checked `[x]`.
+- `ready`: tasks artifact exists, at least one implementation task remains unchecked, and edit scope is safe.
+
+## Dependency States
+
+- `apply` is `ready` only when specs, design, and tasks are available and task progress is not all done.
+- `verify` is `ready` when tasks exist and either apply-progress exists or the tasks artifact shows all intended implementation work complete. Unchecked implementation tasks remain CRITICAL blockers for full archive readiness.
+- `sync` is `ready` only when verify-report exists and has no unresolved `FAIL`, `BLOCKED`, `CRITICAL`, or verification blockers. `engram`/`none` modes may mark sync `not_applicable`.
+- `archive` is `ready` only when verify-report exists, sync is complete or not applicable, and tasks are complete. CRITICAL verification issues have no override. Explicit recorded exceptions are limited to non-critical partial archives or stale-checkbox reconciliation when apply-progress/verify-report prove completion.
+
+## Action Context Guard
+
+The orchestrator MUST carry `actionContext` into any phase launch.
+
+- If `mode: workspace-planning` and `allowedEditRoots` is empty, stop before editing, verifying implementation ownership, syncing specs, or archiving. Treat linked repos and folders as read-only planning context.
+- If `allowedEditRoots` is present, only edit or move files within those roots.
+- If a phase cannot prove a file is inside the authoritative workspace or allowed edit roots, stop and ask for clarification.
+
+## Status Output
+
+Every command or agent that acts on a change MUST show or consume status before doing phase work:
+
+- active change selection and how it was resolved;
+- artifact statuses and paths/topics used as context;
+- task progress and unchecked task list when tasks exist;
+- next recommended action;
+- any `actionContext` or edit-root warnings.

package/extensions/gentle-ai.ts

@@ -42,6 +42,7 @@ function sddGlobalAssetDriftCount(): number {
 	for (const [assetSubdir, installedSubdir] of [
 		["agents", "agents"],
 		["chains", "chains"],
+		["support", join("gentle-ai", "support")],
 	] as const) {
 		const assetDir = join(ASSETS_DIR, assetSubdir);
 		if (!existsSync(assetDir)) continue;
@@ -79,6 +80,7 @@ function sddLocalOverrideDriftCount(cwd: string): number {
 	for (const [assetSubdir, installedSubdir] of [
 		["agents", join(".pi", "agents")],
 		["chains", join(".pi", "chains")],
+		["support", join(".pi", "gentle-ai", "support")],
 	] as const) {
 		const assetDir = join(ASSETS_DIR, assetSubdir);
 		const installedDir = join(cwd, installedSubdir);
@@ -216,6 +218,7 @@ const SDD_AGENT_NAMES = [
 	"sdd-spec",
 	"sdd-design",
 	"sdd-tasks",
+	"sdd-status",
 	"sdd-apply",
 	"sdd-verify",
 	"sdd-sync",

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.3",
   "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/scripts/verify-package-files.mjs

@@ -15,12 +15,14 @@ const requiredPaths = [
   "assets/agents/sdd-onboard.md",
   "assets/agents/sdd-proposal.md",
   "assets/agents/sdd-spec.md",
+  "assets/agents/sdd-status.md",
   "assets/agents/sdd-sync.md",
   "assets/agents/sdd-tasks.md",
   "assets/agents/sdd-verify.md",
   "assets/chains/sdd-full.chain.md",
   "assets/chains/sdd-plan.chain.md",
   "assets/chains/sdd-verify.chain.md",
+  "assets/support/sdd-status-contract.md",
   "assets/support/strict-tdd.md",
   "assets/support/strict-tdd-verify.md",
   "extensions/gentle-ai.ts",

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"))),

package/tests/runtime-harness.mjs

@@ -311,8 +311,10 @@ async function run() {
 		);
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-apply.md")), true);
 		assert.equal(existsSync(join(globalAgentHome, "chains", "sdd-full.chain.md")), true);
+		assert.equal(existsSync(join(globalAgentHome, "gentle-ai", "support", "sdd-status-contract.md")), true);
 		await writeFile(join(globalAgentHome, "agents", "sdd-apply.md"), "stale global apply\n");
 		await writeFile(join(globalAgentHome, "chains", "sdd-full.chain.md"), "stale global chain\n");
+		await writeFile(join(globalAgentHome, "gentle-ai", "support", "sdd-status-contract.md"), "stale global status contract\n");
 		await mkdir(join(noUiCwd, ".pi", "agents"), { recursive: true });
 		await writeFile(join(noUiCwd, ".pi", "agents", "sdd-apply.md"), "project override must stay\n");
 		for (const handler of hooks.get("session_start")) {
@@ -328,6 +330,11 @@ async function run() {
 			"stale global chain\n",
 			"session_start must refresh stale global SDD chains",
 		);
+		assert.notEqual(
+			await readFile(join(globalAgentHome, "gentle-ai", "support", "sdd-status-contract.md"), "utf8"),
+			"stale global status contract\n",
+			"session_start must refresh stale global SDD support files",
+		);
 		assert.equal(
 			await readFile(join(noUiCwd, ".pi", "agents", "sdd-apply.md"), "utf8"),
 			"project override must stay\n",
@@ -402,7 +409,9 @@ async function run() {
 		assert.equal(existsSync(join(lazySddCwd, ".pi", "agents", "sdd-apply.md")), false);
 		assert.equal(existsSync(join(lazySddCwd, ".pi", "chains", "sdd-full.chain.md")), false);
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-apply.md")), true);
+		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-status.md")), true);
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-sync.md")), true);
+		assert.equal(existsSync(join(globalAgentHome, "gentle-ai", "support", "sdd-status-contract.md")), true);
 		assert.equal(existsSync(join(globalAgentHome, "chains", "sdd-full.chain.md")), true);
 		assert.equal(ctx.ui.selections.length, 3);
 		assert.equal(ctx.ui.selections[0].label, "SDD execution mode");
@@ -436,7 +445,9 @@ async function run() {
 		assert.equal(existsSync(join(lazySddCwd, ".pi", "agents", "sdd-apply.md")), false);
 		assert.equal(existsSync(join(lazySddCwd, ".pi", "chains", "sdd-full.chain.md")), false);
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-apply.md")), true);
+		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-status.md")), true);
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-sync.md")), true);
+		assert.equal(existsSync(join(globalAgentHome, "gentle-ai", "support", "sdd-status-contract.md")), true);
 		assert.equal(existsSync(join(globalAgentHome, "chains", "sdd-full.chain.md")), true);
 		const globalSddApply = await readFile(
 			join(globalAgentHome, "agents", "sdd-apply.md"),
@@ -605,6 +616,8 @@ async function run() {
 		assert.match(ctx.ui.notifications.at(-1).message, /Global Gentle AI SDD assets installed/);
 		assert.equal(existsSync(join(installCwd, ".pi", "agents", "sdd-apply.md")), false);
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-apply.md")), true);
+		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-status.md")), true);
+		assert.equal(existsSync(join(globalAgentHome, "gentle-ai", "support", "sdd-status-contract.md")), true);
 	} finally {
 		await rm(installCwd, { recursive: true, force: true });
 	}
@@ -613,9 +626,11 @@ async function run() {
 	try {
 		await mkdir(join(staleAssetsCwd, ".pi", "agents"), { recursive: true });
 		await mkdir(join(staleAssetsCwd, ".pi", "chains"), { recursive: true });
+		await mkdir(join(staleAssetsCwd, ".pi", "gentle-ai", "support"), { recursive: true });
 		await writeFile(join(staleAssetsCwd, ".pi", "agents", "sdd-apply.md"), "stale apply\n");
 		await writeFile(join(staleAssetsCwd, ".pi", "agents", "sdd-spec.md"), "stale spec\n");
 		await writeFile(join(staleAssetsCwd, ".pi", "chains", "sdd-full.chain.md"), "stale chain\n");
+		await writeFile(join(staleAssetsCwd, ".pi", "gentle-ai", "support", "sdd-status-contract.md"), "stale status contract\n");
 		const ctx = createCtx(staleAssetsCwd, true);
 		await commands.get("gentle-ai:status").handler("", ctx);
 		assert.match(ctx.ui.notifications.at(-1).message, /Project-local SDD override drift: \d+ file\(s\)/);
@@ -638,7 +653,9 @@ async function run() {
 		assert.equal(existsSync(join(sddCwd, ".pi", "agents", "sdd-apply.md")), false);
 		assert.equal(existsSync(join(sddCwd, ".pi", "chains", "sdd-full.chain.md")), false);
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-apply.md")), true);
+		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-status.md")), true);
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-sync.md")), true);
+		assert.equal(existsSync(join(globalAgentHome, "gentle-ai", "support", "sdd-status-contract.md")), true);
 		assert.equal(existsSync(join(globalAgentHome, "chains", "sdd-full.chain.md")), true);
 		assert.equal(ctx.ui.selections.length, 3);
 		assert.match(ctx.ui.notifications[0].message, /SDD preflight complete/);