diff --git a/.pi/agent/agents/sdd-apply.md b/.pi/agent/agents/sdd-apply.md index baddc86..86a2bb1 100644 --- a/.pi/agent/agents/sdd-apply.md +++ b/.pi/agent/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//proposal`, `sdd//spec`, `sdd//design`, `sdd//tasks`, `sdd//apply-progress`, or `sdd//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. diff --git a/.pi/agent/agents/sdd-archive.md b/.pi/agent/agents/sdd-archive.md index 53a7a74..267e540 100644 --- a/.pi/agent/agents/sdd-archive.md +++ b/.pi/agent/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. diff --git a/.pi/agent/agents/sdd-init.md b/.pi/agent/agents/sdd-init.md index d959157..527531a 100644 --- a/.pi/agent/agents/sdd-init.md +++ b/.pi/agent/agents/sdd-init.md @@ -1,7 +1,6 @@ --- name: sdd-init description: Initialize project SDD context, testing capabilities, and skill registry. -model: openai-codex/gpt-5.3-codex tools: read, grep, glob, write, bash --- diff --git a/.pi/agent/agents/sdd-proposal.md b/.pi/agent/agents/sdd-proposal.md index b56c110..df20db0 100644 --- a/.pi/agent/agents/sdd-proposal.md +++ b/.pi/agent/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. diff --git a/.pi/agent/agents/sdd-spec.md b/.pi/agent/agents/sdd-spec.md index 5d37dc4..c62e69c 100644 --- a/.pi/agent/agents/sdd-spec.md +++ b/.pi/agent/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: diff --git a/.pi/agent/agents/sdd-sync.md b/.pi/agent/agents/sdd-sync.md index c80062b..72aa747 100644 --- a/.pi/agent/agents/sdd-sync.md +++ b/.pi/agent/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 diff --git a/.pi/agent/agents/sdd-verify.md b/.pi/agent/agents/sdd-verify.md index 8f7c129..dcf3879 100644 --- a/.pi/agent/agents/sdd-verify.md +++ b/.pi/agent/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//proposal`, `sdd//spec`, `sdd//design`, `sdd//tasks`, `sdd//apply-progress`, or `sdd//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; diff --git a/.pi/agent/chains/sdd-full.chain.md b/.pi/agent/chains/sdd-full.chain.md index 0e2ceb3..958cdd3 100644 --- a/.pi/agent/chains/sdd-full.chain.md +++ b/.pi/agent/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 diff --git a/.pi/agent/chains/sdd-plan.chain.md b/.pi/agent/chains/sdd-plan.chain.md index 6aa1abe..ad0ad19 100644 --- a/.pi/agent/chains/sdd-plan.chain.md +++ b/.pi/agent/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 diff --git a/.pi/agent/settings.json b/.pi/agent/settings.json index afec809..272429b 100644 --- a/.pi/agent/settings.json +++ b/.pi/agent/settings.json @@ -1,7 +1,8 @@ { + "quietStartup": true, "lastChangelogVersion": "0.70.6", "defaultProvider": "kimi-coding", - "defaultModel": "kimi-for-coding", + "defaultModel": "k2p6", "defaultThinkingLevel": "high", "packages": [ "npm:pi-subagents", @@ -16,7 +17,11 @@ "npm:pi-intercom", "npm:gentle-engram", "npm:pi-lens", - "npm:@juicesharp/rpiv-todo" + "npm:@juicesharp/rpiv-todo", + "npm:@majorgilles/pi-grill-me", + "git:git.commumedia.org/alex/pi-map" ], - "powerline": "full" + "powerline": "full", + "hideThinkingBlock": false, + "prompts": ["prompts/english-default.md", "prompts/todo-hygiene.md"] }