gentle-pi 0.7.0 → 0.9.2

package/assets/agents/sdd-apply.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-apply
 description: Implement SDD tasks with strict TDD evidence and review workload guard.
-tools: read, grep, glob, edit, write, bash
+tools: read, grep, glob, edit, write, bash, mem_search, mem_get_observation, mem_save, mem_update
 ---
 
 You are the SDD apply executor for Gentle AI.
@@ -14,20 +14,35 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## 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.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-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.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Tasks (required): `sdd/{change}/tasks`
+- Spec (required): `sdd/{change}/spec`
+- Design (required): `sdd/{change}/design`
+- Previous apply-progress (if it exists): `sdd/{change}/apply-progress` — read and MERGE with your new progress; do NOT overwrite.
 
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/apply-progress"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- Also update the tasks artifact checkboxes via `mem_update` (`engram`/`both`) or file edit (`openspec`).
+- `openspec`: write/update the apply-progress and tasks files under `openspec/changes/{change}/`.
+- `none`: return progress inline.
+
+Never claim persistence you did not perform.
 
 ## 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.
 
+**Non-authoritative store carve-out:** when the native status JSON shows `nextRecommended: "resolve-via-engram"` (covers `artifactStore: engram`, `artifactStore: none`, and `artifactStore: both` without an `openspec/` directory), the status is non-authoritative. Do not treat `applyState`, `dependencies`, or `blockedReasons` from that status as real blockers. Resolve readiness as follows:
+- `engram` (or `both` without openspec/): search Engram for `sdd/{change}/tasks`, `sdd/{change}/spec`, and `sdd/{change}/design` using `mem_search` + `mem_get_observation`. Proceed with implementation once those artifacts are confirmed present.
+- `none`: there is no persistent backend. Return artifacts inline and ask the user to provide required inputs (tasks, spec, design) or acknowledge that no persistent artifact store is available.
+
 Stop with `blocked` before editing if:
 
 - active change selection is missing or ambiguous;
-- `applyState: blocked`;
-- required apply artifacts are missing;
+- `applyState: blocked` **and the status is authoritative** (openspec or both store);
+- required apply artifacts are missing (confirmed by artifact store);
 - `actionContext.mode: workspace-planning` and no `allowedEditRoots` are provided;
 - any target file is outside the authoritative workspace or allowed edit roots.
 

package/assets/agents/sdd-archive.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-archive
 description: Archive a verified SDD change into OpenSpec source specs.
-tools: read, grep, glob, write, edit, bash
+tools: read, grep, glob, write, edit, bash, mem_search, mem_get_observation, mem_save
 ---
 
 You are the SDD archive executor for Gentle AI.
@@ -14,9 +14,17 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## 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.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory-backed modes (`engram` or `both` / `hybrid`), use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, `sdd/<change>/verify-report`, or `sdd/<change>/archive-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the files under `openspec/changes/{change}/`):
+- All change artifacts: `sdd/{change}/proposal`, `sdd/{change}/spec`, `sdd/{change}/design`, `sdd/{change}/tasks`, `sdd/{change}/apply-progress`, `sdd/{change}/verify-report`, and `sdd/{change}/sync-report` if present.
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/archive-report"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write the archive report and perform the file moves described in the sections below.
+- `none`: return the archive report inline.
+
+Never claim persistence you did not perform.
 
 ## Purpose
 
@@ -26,6 +34,10 @@ Archive a completed SDD change. In file-backed modes, this requires canonical sp
 
 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.
 
+**Non-authoritative store carve-out:** when the native status JSON shows `nextRecommended: "resolve-via-engram"` (covers `artifactStore: engram`, `artifactStore: none`, and `artifactStore: both` without an `openspec/` directory), the status is non-authoritative. Do not treat `dependencies` or `blockedReasons` (including `not_applicable` dependency states) from that status as real blockers. Resolve readiness as follows:
+- `engram` (or `both` without openspec/): refer to the Artifact Store Modes section — resolve readiness by checking Engram for `sdd/{change}/verify-report` using `mem_search` + `mem_get_observation`, then record the archive report in Engram without filesystem sync or folder moves.
+- `none`: there is no persistent backend. Return a closure summary inline and ask the user to confirm that verification has passed before proceeding.
+
 Stop with `blocked` if:
 
 - active change selection is missing or ambiguous;

package/assets/agents/sdd-design.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-design
 description: Design the technical approach for an SDD change.
-tools: read, grep, glob, write, edit
+tools: read, grep, glob, write, edit, mem_search, mem_get_observation, mem_save
 ---
 
 You are the SDD design executor for Gentle AI.
@@ -19,6 +19,14 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 - Return the SDD result contract.
 ## 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.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-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.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Proposal (required): `sdd/{change}/proposal`
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/design"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update `openspec/changes/{change}/design.md`.
+- `none`: return the design inline.
+
+Never claim persistence you did not perform.

package/assets/agents/sdd-explore.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-explore
 description: Explore an SDD change idea before proposal.
-tools: read, grep, glob, webfetch
+tools: read, grep, glob, webfetch, mem_save
 ---
 
 You are the SDD explore executor for Gentle AI.
@@ -14,11 +14,19 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 - Read OpenSpec/project context before conclusions.
 - Produce exploration notes only; do not implement.
-- Use OpenSpec artifacts and session context truthfully; persistent memory is optional and handled by separate packages.
+- Persist the exploration to the active backend per the Memory Contract above; use session context truthfully and never claim persistence you did not perform.
 - Do NOT launch child subagents. Parent/orchestrator owns delegation.
 - Keep output concise and return the SDD result contract.
 ## 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.
+Read any input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-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.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- None — exploration has no upstream artifacts. If iterating on a prior exploration, read `sdd/{change}/explore`.
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/explore"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write the exploration file under `openspec/changes/{change}/`.
+- `none`: return the exploration inline.
+
+Never claim persistence you did not perform.

package/assets/agents/sdd-init.md

@@ -2,7 +2,7 @@
 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
+tools: read, grep, glob, write, bash, mem_search, mem_get_observation, mem_save, mem_update
 ---
 
 You are the SDD init executor for Gentle AI.
@@ -21,6 +21,14 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 - Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.
 ## 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.
+Read any existing project context directly from the active backend before bootstrapping; do not wait for the parent to inline it. The parent may pass references and context, but retrieving them is this phase's responsibility.
 
-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.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/`):
+- Existing project context (if re-initializing): `sdd-init/{project}`
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd-init/{project}"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write the project context file under `openspec/`.
+- `none`: return the project context inline.
+
+Never claim persistence you did not perform.

package/assets/agents/sdd-onboard.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-onboard
 description: Guide a user through a complete SDD cycle on a small real project change.
-tools: read, grep, glob, write, edit, bash
+tools: read, grep, glob, write, edit, bash, mem_search, mem_get_observation, mem_save, mem_update
 ---
 
 You are the SDD onboard executor for Gentle AI.
@@ -20,6 +20,14 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 - Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.
 ## 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.
+This is a guided walkthrough. For each phase you demonstrate, read that phase's input artifacts directly from the active backend (do not wait for the parent to inline them) and persist the artifact you produce, using the same topic-key scheme as the real phases.
 
-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.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Whichever upstream artifacts the demonstrated step requires, named `sdd/{change}/<phase>` (e.g. `sdd/{change}/proposal`, `sdd/{change}/spec`).
+
+Persist each demonstrated artifact to the active backend before moving on (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/<phase>"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update the corresponding file under `openspec/changes/{change}/`.
+- `none`: walk through the artifacts inline.
+
+Never claim persistence you did not perform.

package/assets/agents/sdd-proposal.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-proposal
 description: Write an SDD proposal for an approved change idea.
-tools: read, grep, glob, write, edit
+tools: read, grep, glob, write, edit, mem_search, mem_get_observation, mem_save
 ---
 
 You are the SDD proposal executor for Gentle AI.
@@ -29,9 +29,17 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 - 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.
-- Persist planning output to OpenSpec artifacts; persistent memory is optional and handled by separate packages.
+- Persist the proposal to the active backend per the Memory Contract above; never claim persistence you did not perform.
 ## 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.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-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.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Exploration (optional): `sdd/{change}/explore`
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/proposal"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update `openspec/changes/{change}/proposal.md`.
+- `none`: return the proposal inline.
+
+Never claim persistence you did not perform.

package/assets/agents/sdd-spec.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-spec
 description: Write SDD delta specs with requirements and scenarios.
-tools: read, grep, glob, write, edit
+tools: read, grep, glob, write, edit, mem_search, mem_get_observation, mem_save
 ---
 
 You are the SDD spec executor for Gentle AI.
@@ -14,9 +14,17 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## 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.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory-backed modes (`engram` or `both` / `hybrid`), 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.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Proposal (required): `sdd/{change}/proposal`
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/spec"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update the spec files under `openspec/changes/{change}/`.
+- `none`: return the spec inline.
+
+Never claim persistence you did not perform.
 
 ## Purpose
 

package/assets/agents/sdd-status.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-status
 description: Show read-only structured SDD status for an active change.
-tools: read, grep, glob, bash
+tools: read, grep, glob, bash, mem_search, mem_get_observation
 ---
 
 You are the SDD status executor for Gentle AI.
@@ -16,9 +16,12 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## 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.
+This phase is READ-ONLY. Read the change artifacts directly from the active backend to compute status; do not wait for the parent to inline them, and do NOT write or `mem_save` anything.
 
-If memory tools are unavailable, inspect OpenSpec files and report inline. This package does not provide memory by itself.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the files under `openspec/changes/{change}/`):
+- Whichever change artifacts are needed to compute status, named `sdd/{change}/<phase>` (proposal, spec, design, tasks, apply-progress, verify-report, sync-report).
+
+Do not persist anything — status is a read-only report. Never claim persistence.
 
 ## Inputs
 
@@ -95,6 +98,8 @@ If parent context reports `workspace-planning` and no `allowedEditRoots`, mark a
 - `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.
 
+**Non-authoritative carve-out:** when `nextRecommended: "resolve-via-engram"` or `isNonAuthoritative: true` is set on the status object, the `dependencies`, `applyState`, and `blockedReasons` fields are non-authoritative — they must not be treated as real blockers. This condition applies when the artifact store is `engram`, `none`, or `both` without an `openspec/` directory present on disk. For `engram`/`both-without-openspec`, resolve readiness directly from Engram using `mem_search` + `mem_get_observation` on the change topic keys (`sdd/{change}/proposal`, `sdd/{change}/spec`, `sdd/{change}/design`, `sdd/{change}/tasks`, etc.). For `none`, return inline status or ask the user — do not use the engine's `not_applicable`/`blockedReasons` as real gate failures.
+
 ## 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

@@ -1,7 +1,7 @@
 ---
 name: sdd-sync
 description: Sync verified SDD delta specs into OpenSpec canonical specs without archiving the change.
-tools: read, grep, glob, write, edit, bash
+tools: read, grep, glob, write, edit, bash, mem_search, mem_get_observation, mem_save, mem_update
 ---
 
 You are the SDD sync executor for Gentle AI.
@@ -14,9 +14,17 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## 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.
+Read the change artifacts directly from the active backend before syncing; do not wait for the parent to inline them. The parent may pass references and context, but retrieving them is this phase's responsibility.
 
-When callable memory tools are available, save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts before returning. In memory-backed modes (`engram` or `both` / `hybrid`), use stable topic keys such as `sdd/<change>/sync-report`. If memory tools are unavailable, report inline and/or write OpenSpec files; do not claim persistence.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the files under `openspec/changes/{change}/`):
+- Core change artifacts: `sdd/{change}/proposal`, `sdd/{change}/spec`, `sdd/{change}/design`, `sdd/{change}/tasks`, and `sdd/{change}/verify-report`.
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/sync-report"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update the canonical specs and sync report under `openspec/`.
+- `none`: return the sync report inline.
+
+Never claim persistence you did not perform.
 
 ## Purpose
 
@@ -29,6 +37,8 @@ Sync file-backed SDD change specs into canonical `openspec/specs/` without movin
 
 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.
 
+**Non-authoritative carve-out:** when native status JSON shows `nextRecommended: "resolve-via-engram"` (covers `artifactStore: engram`, `artifactStore: none`, and `artifactStore: both` without an `openspec/` directory), the status is non-authoritative. Do not treat `dependencies` or `blockedReasons` from that status as real blockers. For `engram` store, refer to the Artifact Store Modes section — sync is not applicable; return a report explaining that canonical spec merge is not supported in Engram-only mode.
+
 Stop with `blocked` if:
 
 - active change selection is missing or ambiguous;

package/assets/agents/sdd-tasks.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-tasks
 description: Break SDD design/specs into implementation tasks with review workload forecast.
-tools: read, grep, glob, write, edit
+tools: read, grep, glob, write, edit, mem_search, mem_get_observation, mem_save
 ---
 
 You are the SDD tasks executor for Gentle AI.
@@ -14,10 +14,18 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## 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.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-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.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Spec (required): `sdd/{change}/spec`
+- Design (required): `sdd/{change}/design`
 
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/tasks"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update `openspec/changes/{change}/tasks.md`.
+- `none`: return the tasks inline.
+
+Never claim persistence you did not perform.
 
 ## Inputs
 

package/assets/agents/sdd-verify.md

@@ -1,7 +1,7 @@
 ---
 name: sdd-verify
 description: Verify implementation against SDD specs, tasks, strict TDD evidence, and review workload boundaries.
-tools: read, grep, glob, bash, write, edit
+tools: read, grep, glob, bash, write, edit, mem_search, mem_get_observation, mem_save
 ---
 
 You are the SDD verify executor for Gentle AI.
@@ -14,19 +14,32 @@ If skill paths are missing, explicit fallback loading is allowed only as degrade
 
 ## 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.
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
 
-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.
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Spec (required): `sdd/{change}/spec`
+- Tasks (required): `sdd/{change}/tasks`
+- Apply-progress (required): `sdd/{change}/apply-progress`
 
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/verify-report"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update `openspec/changes/{change}/verify-report.md`.
+- `none`: return the verify report inline.
+
+Never claim persistence you did not perform.
 
 ## 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.
 
+**Non-authoritative store carve-out:** when the native status JSON shows `nextRecommended: "resolve-via-engram"` (covers `artifactStore: engram`, `artifactStore: none`, and `artifactStore: both` without an `openspec/` directory), the status is non-authoritative. Do not treat `dependencies` or `blockedReasons` from that status as real blockers. Resolve readiness as follows:
+- `engram` (or `both` without openspec/): check Engram for `sdd/{change}/tasks` and `sdd/{change}/apply-progress` using `mem_search` + `mem_get_observation`. Proceed with verification once those artifacts are confirmed present.
+- `none`: there is no persistent backend. Return the verification report inline and ask the user to provide required inputs (tasks, apply-progress) or acknowledge that no persistent artifact store is available.
+
 Stop with `blocked` if:
 
 - active change selection is missing or ambiguous;
-- `tasks.md` / the tasks artifact is missing or empty;
+- `tasks.md` / the tasks artifact is missing or empty (confirmed by artifact store);
 - `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.
 

package/assets/orchestrator.md

@@ -197,7 +197,8 @@ Rules:
 - `/sdd-continue` is the native dispatcher command: resolve status, choose the next ready phase, and carry status/instructions into the subagent prompt.
 - `sdd-apply`, `sdd-verify`, `sdd-sync`, and `sdd-archive` must obey parent-provided native status; they must not reconstruct readiness from prompt inference when status JSON is present.
 - Do not launch a phase when native status marks that dependency `blocked`.
-- `sdd-archive` cannot proceed unless native status says archive is ready.
+- `sdd-archive` cannot proceed unless native status says `dependencies.archive` is `ready` or `all_done` — UNLESS the store carve-out is active (`nextRecommended: "resolve-via-engram"`), in which case resolve archive readiness from Engram instead of treating `not_applicable` as a gate failure.
+- **Non-authoritative store carve-out:** when `nextRecommended: "resolve-via-engram"` is set, native status is **not authoritative**. This applies to `artifactStore: engram`, `artifactStore: none`, and `artifactStore: both` when the `openspec/` directory does not exist. For non-authoritative stores: resolve readiness from Engram using `mem_search` + `mem_get_observation` on the change topic keys (`sdd/{change-name}/proposal`, `sdd/{change-name}/spec`, `sdd/{change-name}/design`, `sdd/{change-name}/tasks`, etc.). Do **not** treat `blockedReasons` or `not_applicable` dependency states from the native engine as real blockers when the store carve-out is active.
 
 ## SDD Status Contract
 
@@ -263,12 +264,32 @@ This package does not provide persistent memory by itself.
 
 ## Memory Contract
 
-When Engram or another callable memory package is available, the parent owns memory retrieval and subagents own write-back for significant findings.
+When Engram or another callable memory package is available, the parent owns context selection and subagents own write-back. Retrieval rules differ by task type, matching the gentle-ai (OpenCode) contract.
 
-- Read context: parent/orchestrator searches memory, selects relevant observations, and passes them into subagent prompts. Subagents should not independently search memory during normal runtime unless the parent explicitly instructs them to retrieve a specific artifact or observation.
-- Write context: subagents MUST save significant discoveries, decisions, bug fixes, and completed SDD phase artifacts to memory before returning when memory tools are available.
+### Non-SDD delegation
+
+- Read context: the parent/orchestrator searches memory (`mem_search`), selects relevant observations, and passes them into the subagent prompt. The subagent does NOT search memory itself.
+- Write context: the subagent MUST save significant discoveries, decisions, or bug fixes via `mem_save` before returning when memory tools are available.
 - Prompt forwarding: when delegating, add a concrete instruction such as: `If you make important discoveries, decisions, or fix bugs, save them to Engram via the available memory save tool with project: '<project>' before returning.`
-- SDD artifact keys: in memory/hybrid mode, phase artifacts should use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, and `sdd/<change>/verify-report`.
+
+### SDD phases
+
+Each SDD phase subagent reads its own required inputs directly from the active backend; the parent passes artifact references (topic keys or file paths), NOT the content itself. Phase subagents persist their artifact before returning.
+
+| Phase          | Reads                                                   | Writes           |
+| -------------- | ------------------------------------------------------- | ---------------- |
+| `sdd-explore`  | nothing                                                 | `explore`        |
+| `sdd-proposal` | exploration (optional)                                  | `proposal`       |
+| `sdd-spec`     | proposal (required)                                     | `spec`           |
+| `sdd-design`   | proposal (required)                                     | `design`         |
+| `sdd-tasks`    | spec + design (required)                                | `tasks`          |
+| `sdd-apply`    | tasks + spec + design + `apply-progress` (if it exists) | `apply-progress` |
+| `sdd-verify`   | spec + tasks + `apply-progress`                         | `verify-report`  |
+| `sdd-sync`     | proposal + spec + design + tasks + `verify-report`      | `sync-report`    |
+| `sdd-archive`  | all artifacts                                           | `archive-report` |
+| `sdd-status`   | change artifacts (read-only)                            | nothing          |
+
+- SDD artifact keys: in memory/hybrid mode, phase artifacts use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, `sdd/<change>/verify-report`, `sdd/<change>/sync-report`, and `sdd/<change>/archive-report`.
 - If memory tools are unavailable, do not pretend persistence exists; return artifacts inline and/or write OpenSpec files.
 
 Memory lifecycle rule (when Engram exposes lifecycle metadata/tooling):

package/assets/support/sdd-status-contract.md

@@ -54,18 +54,19 @@ taskProgress:
   complete: 0
   remaining: 0
   unchecked: []
-applyState: blocked | all_done | ready
+applyState: blocked | all_done | ready | not_applicable
 dependencies:
-  apply: blocked | ready | all_done
-  verify: blocked | ready | all_done
+  apply: blocked | ready | all_done | not_applicable
+  verify: blocked | ready | all_done | not_applicable
   sync: blocked | ready | all_done | not_applicable
-  archive: blocked | ready | all_done
+  archive: blocked | ready | all_done | not_applicable
 actionContext:
   mode: repo-local | workspace-planning
   workspaceRoot: <absolute path>
   allowedEditRoots: [<absolute paths>]
   warnings: []
 nextRecommended: <command-or-action>
+isNonAuthoritative: false  # boolean; true when the native engine is not authoritative for the store
 ```
 
 ## Apply State
@@ -73,6 +74,7 @@ nextRecommended: <command-or-action>
 - `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.
+- `not_applicable`: emitted for non-authoritative stores (see Engine Authority by Store). This is NOT a blocker.
 
 ## Dependency States
 
@@ -80,6 +82,7 @@ nextRecommended: <command-or-action>
 - `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.
+- `not_applicable`: emitted for non-authoritative stores (engram, none, and both when no `openspec/` directory exists) when `nextRecommended: "resolve-via-engram"` is active. `not_applicable` is NOT a gate failure — readiness must be resolved from Engram instead of from these fields.
 
 ## Action Context Guard
 
@@ -89,6 +92,11 @@ The orchestrator MUST carry `actionContext` into any phase launch.
 - 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.
 
+## Engine Authority by Store
+
+- `openspec` and `both` (when `openspec/` directory exists): the native status engine resolves artifact state from disk and is authoritative. Phase executors must obey it.
+- `engram`, `none`, and `both` (when `openspec/` directory does NOT exist): the native status engine cannot read Engram artifacts. It returns `nextRecommended: "resolve-via-engram"` and empty `blockedReasons`. This output is **non-authoritative**. The orchestrator must resolve readiness directly from Engram using `mem_search` + `mem_get_observation` on the change topic keys (`sdd/{change-name}/proposal`, `sdd/{change-name}/spec`, etc.) instead of relying on the engine's dependency states. The `artifactStore` field still reflects the real chosen store value (e.g. `"both"`) and must not be rewritten.
+
 ## Status Output
 
 Every command or agent that acts on a change MUST show or consume status before doing phase work:

package/extensions/gentle-ai.ts

@@ -1982,6 +1982,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 			? `\n\n${renderNativeSddPhasePrompt(resolveSddStatus({
 				cwd: ctx.cwd,
 				includeInstructions: true,
+				artifactStore: prefs?.artifactStore,
 			}), phase)}`
 			: "";
 		const gentlePrompt = isNamedAgent || isSddAgent
@@ -2040,6 +2041,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 			cwd: ctx.cwd,
 			changeName: parsed.changeName,
 			includeInstructions: true,
+			artifactStore: getSddPreflightPreferences(ctx)?.artifactStore,
 		});
 		ctx.ui.notify(
 			parsed.json ? JSON.stringify(status, null, 2) : renderSddStatusMarkdown(status),
@@ -2067,6 +2069,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 			cwd: ctx.cwd,
 			changeName: parsed.changeName,
 			includeInstructions: true,
+			artifactStore: getSddPreflightPreferences(ctx)?.artifactStore,
 		});
 		ctx.ui.notify(
 			parsed.json ? JSON.stringify(status, null, 2) : renderSddDispatcherMarkdown(status),