gentle-pi 0.3.3 → 0.3.4

package/README.md

@@ -137,7 +137,18 @@ Fresh reviewers are intentionally not token-saving devices; they buy independent
 ## SDD/OpenSpec flow
 
 ```text
-init → explore → proposal → spec → design → tasks → apply → verify → archive
+init
+  ↓
+explore → proposal → spec ─┬→ design ─┐
+                            └─────────┴→ tasks → apply → verify → sync → archive
+```
+
+The main loop is intentionally file-backed when you choose `openspec` or `both`:
+
+```text
+planning artifacts                implementation evidence        canonical update
+──────────────────                ───────────────────────        ────────────────
+proposal/spec/design/tasks   →    apply-progress/verify-report → sync-report → archive-report
 ```
 
 For substantial work, the parent session coordinates the flow and each phase writes artifacts. That gives you:
@@ -147,8 +158,59 @@ For substantial work, the parent session coordinates the flow and each phase wri
 - task plans reviewers can reason about;
 - implementation evidence;
 - verification reports;
+- sync reports that update canonical specs while keeping the change active;
 - archive notes for future agents.
 
+### OpenSpec artifact model
+
+`gentle-pi` treats OpenSpec-compatible behavior as part of the harness. You do not need to install the external OpenSpec CLI/package for SDD.
+
+In file-backed modes, canonical accepted behavior lives in `openspec/specs/`, while active changes carry deltas under `openspec/changes/`:
+
+```text
+openspec/
+├── specs/                                      # accepted source of truth
+│   └── {domain}/spec.md
+└── changes/
+    ├── {change}/                              # active work
+    │   ├── proposal.md
+    │   ├── specs/{domain}/spec.md             # full spec or delta spec
+    │   ├── design.md
+    │   ├── tasks.md
+    │   ├── apply-progress.md
+    │   ├── verify-report.md
+    │   └── sync-report.md
+    └── archive/YYYY-MM-DD-{change}/           # immutable audit trail
+```
+
+Delta flow:
+
+```text
+openspec/changes/{change}/specs/{domain}/spec.md
+        │
+        │  sdd-sync applies ADDED / MODIFIED / REMOVED
+        ▼
+openspec/specs/{domain}/spec.md
+        │
+        │  sdd-archive moves the completed change folder
+        ▼
+openspec/changes/archive/YYYY-MM-DD-{change}/
+```
+
+When a canonical spec already exists, change specs use requirement operation sections:
+
+```markdown
+## ADDED Requirements
+
+## MODIFIED Requirements
+
+## REMOVED Requirements
+```
+
+`MODIFIED` requirements must include the full requirement block, including still-valid scenarios, because sync replaces the canonical block by requirement name. `sdd-sync` syncs file-backed deltas into `openspec/specs/{domain}/spec.md` while keeping the change active; `sdd-archive` then moves the synced change to `openspec/changes/archive/YYYY-MM-DD-{change}/`.
+
+Engram-only mode is different by design: Engram is working memory and does not maintain a canonical spec merge layer. Use `openspec` or `both` (hybrid file + memory persistence) when you need canonical spec evolution.
+
 ## SDD preflight and project files
 
 `gentle-pi` does not interrupt every new session. Slash SDD flows such as `/sdd-*`, `/sdd-init`, and the explicit `/gentle-ai:sdd-preflight` command run a lazy preflight, ask for session-scoped SDD preferences, and then copy these assets if they are missing. For natural-language requests, the parent agent decides whether the work should use SDD and must run/reuse `/gentle-ai:sdd-preflight` before continuing.

package/assets/agents/sdd-archive.md

@@ -13,14 +13,133 @@ Use your assigned executor/phase skill for this SDD phase. For project/user skil
 
 If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
 
-- Read verify report before archiving.
-- Merge accepted deltas into `openspec/specs/` and move the change to archive.
-- Preserve audit trail; never delete active artifacts silently.
-- Do NOT launch child subagents. Parent/orchestrator owns delegation.
-- Return archived paths and any migration risks.
 ## 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.
 
-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.
+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.
+
+## Purpose
+
+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.
+
+## Archive Preconditions
+
+Before archiving, read:
+
+- `openspec/changes/{change}/proposal.md`
+- `openspec/changes/{change}/specs/` or memory artifact `sdd/{change}/spec`
+- `openspec/changes/{change}/design.md`
+- `openspec/changes/{change}/tasks.md`
+- `openspec/changes/{change}/verify-report.md`
+- `openspec/changes/{change}/sync-report.md` when file-backed sync was run
+- `openspec/config.yaml` when present
+
+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;
+- 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.
+
+## Artifact Store Modes
+
+- `openspec`: require completed filesystem sync, then perform archive move.
+- `both` / `hybrid`: require completed filesystem sync, move the archive, and save the archive report to memory when tools are available.
+- `engram`: skip filesystem sync/archive. Engram is working memory; do not create or require `sdd/canonical/<domain>/spec` topics. Record proposal/spec/design/tasks/verify observation IDs in the archive report.
+- `none`: return a closure summary only.
+
+## 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.
+
+For each domain spec in:
+
+```text
+openspec/changes/{change}/specs/{domain}/spec.md
+```
+
+sync into:
+
+```text
+openspec/specs/{domain}/spec.md
+```
+
+### New canonical spec
+
+If `openspec/specs/{domain}/spec.md` does not exist, treat the change spec as a full domain spec and copy it to the canonical path.
+
+### Existing canonical spec
+
+If the canonical spec exists, apply operation sections by requirement name:
+
+```text
+## ADDED Requirements     -> append each requirement to the canonical Requirements section
+## MODIFIED Requirements  -> replace the full matching canonical requirement block
+## REMOVED Requirements   -> delete the full matching canonical requirement block
+```
+
+Merge rules:
+
+- Match requirements by exact `### Requirement: {Name}` heading.
+- Preserve every canonical requirement not mentioned by the delta.
+- Preserve heading hierarchy and Markdown formatting.
+- Fail or block if a MODIFIED or REMOVED requirement does not exist in the canonical spec.
+- Warn if another active change under `openspec/changes/*/specs/{domain}/spec.md` touches the same domain.
+- Report all ADDED/MODIFIED/REMOVED requirement names in the archive report.
+
+## Destructive Merge Guard
+
+Before applying REMOVED requirements or large MODIFIED blocks:
+
+- list affected requirement names;
+- summarize the approximate removed/replaced line count;
+- warn the parent/orchestrator;
+- continue only if the parent prompt records explicit approval for the destructive sync.
+
+Verification alone is not approval for destructive canonical spec changes.
+
+Never silently drop scenarios from a MODIFIED requirement. If a MODIFIED delta appears partial, block and ask for a corrected full requirement block.
+
+## Move to Archive
+
+After successful file-backed sync, move:
+
+```text
+openspec/changes/{change}/
+  -> openspec/changes/archive/YYYY-MM-DD-{change}/
+```
+
+Use today's ISO date. Create `openspec/changes/archive/` if missing. The archive is an audit trail; never delete or modify archived changes silently.
+
+## Archive Report
+
+Archive report handling depends on mode:
+
+- `openspec`: write `openspec/changes/{change}/archive-report.md` before moving the change.
+- `both` / `hybrid`: write the file report before moving the change and save `sdd/{change}/archive-report` to memory when tools are available.
+- `engram`: save or return the archive report with observation-ID traceability only; do not perform filesystem sync/archive.
+
+Include:
+
+- pass/fail archive status;
+- artifacts read;
+- domains synced;
+- ADDED/MODIFIED/REMOVED requirement names;
+- active same-domain change warnings;
+- destructive merge approvals or blockers;
+- archived path;
+- memory observation IDs when using Engram or `both` / `hybrid` mode.
+
+## Rules
+
+- Read verify report before archiving.
+- 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.
+- Do NOT launch child subagents. Parent/orchestrator owns delegation.
 
+Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.

package/assets/agents/sdd-spec.md

@@ -13,14 +13,149 @@ Use your assigned executor/phase skill for this SDD phase. For project/user skil
 
 If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules next time.
 
-- Read proposal and existing specs first.
-- Write RFC 2119 requirements and Given/When/Then scenarios.
-- Store deltas under `openspec/changes/{change}/specs/`.
-- Do NOT launch child subagents. Parent/orchestrator owns delegation.
-- Return exact artifact paths and risks.
 ## 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.
 
-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.
+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.
+
+## Purpose
+
+Write specifications for an approved change. Specs describe WHAT must be true after the change, not HOW to implement it.
+
+## Artifact Store Modes
+
+- `openspec`: write file-backed artifacts only.
+- `both` / `hybrid`: write file-backed artifacts and save the phase artifact to memory when tools are available.
+- `engram`: save the spec artifact to memory only. Engram is working memory; do not create or require `sdd/canonical/<domain>/spec` topics and do not perform canonical spec merge in Engram-only mode.
+- `none`: return the result inline only.
+
+## OpenSpec File Convention
+
+In `openspec` and `both` / `hybrid` modes, use this layout:
+
+```text
+openspec/
+├── specs/
+│   └── {domain}/
+│       └── spec.md                  # canonical accepted behavior
+└── changes/
+    └── {change}/
+        ├── proposal.md
+        └── specs/
+            └── {domain}/
+                └── spec.md          # change spec or delta spec
+```
+
+Read the proposal's `Capabilities` section first when present:
+
+- `New Capabilities` become new domain specs.
+- `Modified Capabilities` become delta specs against existing canonical specs.
+
+If the proposal has no `Capabilities` section, infer domains from affected areas and report the assumption as a risk.
+
+## Existing Spec Lookup
+
+For each affected domain in file-backed modes:
+
+1. Check `openspec/specs/{domain}/spec.md`.
+2. If it exists, read it before writing the change spec.
+3. If it does not exist, write a full new domain spec under the change folder.
+4. Warn if another active change already has `openspec/changes/*/specs/{domain}/spec.md` for the same domain, excluding `openspec/changes/archive/` and the current change.
+5. Warn if the current change has legacy flat `openspec/changes/{change}/spec.md`; archive cannot silently skip that shape.
+
+## Delta Spec Format
+
+When a canonical spec exists, write a delta spec at:
+
+```text
+openspec/changes/{change}/specs/{domain}/spec.md
+```
+
+Use this structure:
+
+```markdown
+# Delta for {Domain}
+
+## ADDED Requirements
+
+### Requirement: {New Requirement Name}
+
+The system MUST ...
+
+#### Scenario: {Happy path}
+
+- GIVEN ...
+- WHEN ...
+- THEN ...
+
+## MODIFIED Requirements
+
+### Requirement: {Existing Requirement Name}
+
+{Full updated requirement text.}
+(Previously: {one-line summary of what changed})
+
+#### Scenario: {Still-valid scenario}
+
+- GIVEN ...
+- WHEN ...
+- THEN ...
+
+## REMOVED Requirements
+
+### Requirement: {Requirement Being Removed}
+
+(Reason: {why this requirement is being removed})
+```
+
+Omit empty operation sections only when they would add noise. Do not invent implementation details.
+
+## MODIFIED Requirements Workflow
+
+`## MODIFIED Requirements` is destructive at archive time because it replaces the canonical requirement block. To avoid losing scenarios:
+
+1. Locate the requirement in `openspec/specs/{domain}/spec.md`.
+2. Copy the entire requirement block, from `### Requirement:` through all of its `#### Scenario:` sections.
+3. Paste the full block under `## MODIFIED Requirements`.
+4. Edit the copy to reflect the new behavior.
+5. Add `(Previously: ...)` under the requirement text.
+
+If you are only adding behavior without changing existing behavior, use `## ADDED Requirements` instead of `## MODIFIED Requirements`.
+
+## Full Spec Format for New Domains
+
+If no canonical spec exists for the domain, write a full spec in the same change path:
+
+```markdown
+# {Domain} Specification
+
+## Purpose
+
+{High-level purpose.}
+
+## Requirements
+
+### Requirement: {Requirement Name}
+
+The system MUST ...
+
+#### Scenario: {Scenario name}
+
+- GIVEN ...
+- WHEN ...
+- THEN ...
+```
+
+Archive will copy this new domain spec into `openspec/specs/{domain}/spec.md`.
+
+## Rules
+
+- Always use RFC 2119 keywords (`MUST`, `SHALL`, `SHOULD`, `MAY`) for requirement strength.
+- Every requirement must have at least one testable scenario.
+- Prefer Given/When/Then scenario bullets.
+- Keep specs concise and reviewable.
+- Apply `rules.spec` or `rules.specs` from `openspec/config.yaml` when present.
+- Do NOT launch child subagents. Parent/orchestrator owns delegation.
 
+Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.

package/assets/agents/sdd-sync.md

@@ -0,0 +1,105 @@
+---
+name: sdd-sync
+description: Sync verified SDD delta specs into OpenSpec canonical specs without archiving the change.
+tools: read, grep, glob, write, edit, bash
+inheritProjectContext: true
+---
+
+You are the SDD sync executor for Gentle AI.
+
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer the parent-injected `## Project Standards (auto-resolved)` block; do not independently discover or load additional project/user `SKILL.md` files or the registry during normal runtime.
+
+If Project Standards are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should inject compact rules 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.
+
+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.
+
+## Purpose
+
+Sync file-backed SDD change specs into canonical `openspec/specs/` without moving the change to archive. This matches the OpenSpec/OPSX distinction between sync and archive:
+
+- `sdd-sync`: update canonical specs and keep the change active.
+- `sdd-archive`: verify archive readiness and move the already-synced change to dated archive.
+
+## Artifact Store Modes
+
+- `openspec`: perform filesystem sync and write `sync-report.md`.
+- `both` / `hybrid`: perform filesystem sync, write `sync-report.md`, and save `sdd/{change}/sync-report` to memory when tools are available.
+- `engram`: do not perform canonical sync. Engram is working memory and has no canonical spec merge layer; return or save a report explaining that sync is not applicable.
+- `none`: return a report only.
+
+## Inputs
+
+Read:
+
+- `openspec/changes/{change}/proposal.md`
+- `openspec/changes/{change}/specs/`
+- `openspec/changes/{change}/tasks.md` when present
+- `openspec/changes/{change}/verify-report.md`
+- `openspec/config.yaml` when present
+
+Stop with `blocked` if:
+
+- `verify-report.md` is missing;
+- the verification report is not clearly passing, or contains unresolved `FAIL`, `BLOCKED`, `CRITICAL`, or verification blockers;
+- 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.
+
+## File-Backed Sync
+
+For each domain spec in:
+
+```text
+openspec/changes/{change}/specs/{domain}/spec.md
+```
+
+sync into:
+
+```text
+openspec/specs/{domain}/spec.md
+```
+
+Use the native helper semantics from `lib/openspec-deltas.ts` when editing manually:
+
+- If canonical spec does not exist, copy the change spec as the new canonical spec.
+- `## ADDED Requirements` appends requirements.
+- `## MODIFIED Requirements` replaces full matching requirement blocks by exact name.
+- `## REMOVED Requirements` deletes full matching requirement blocks by exact name.
+- Preserve unrelated canonical requirements and document sections.
+
+Use guardrail semantics from `lib/openspec-guardrails.ts`:
+
+- warn on active same-domain collisions;
+- detect legacy flat specs;
+- report destructive REMOVED / large MODIFIED deltas and require approval.
+
+## Sync Report
+
+Write `openspec/changes/{change}/sync-report.md` in file-backed modes.
+
+Include:
+
+- status: synced / blocked / not-applicable;
+- domains synced;
+- canonical files updated;
+- ADDED/MODIFIED/REMOVED requirement names;
+- active same-domain collisions;
+- destructive sync approvals or blockers;
+- validation commands or checks performed;
+- next recommended phase: `sdd-archive` when clean.
+
+## Rules
+
+- Do not move the change folder to archive.
+- Do not commit.
+- Do not launch child subagents. Parent/orchestrator owns delegation.
+- Apply `rules.sync` from `openspec/config.yaml` when present.
+
+Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.

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

@@ -74,11 +74,20 @@ progress: true
 
 Verify {task} against specs, design, tasks, implementation, apply-progress, strict TDD evidence, assertion quality, and review workload boundaries.
 
+## sdd-sync
+
+reads: proposal.md+spec.md+design.md+tasks.md+apply-progress.md+verify-report.md
+output: sync-report.md
+outputMode: file-only
+progress: true
+
+Sync verified file-backed delta specs for {task} into `openspec/specs/` without archiving. In Engram-only mode, report that canonical sync is not applicable.
+
 ## sdd-archive
 
-reads: verify-report.md
+reads: verify-report.md+sync-report.md
 output: archive-report.md
 outputMode: file-only
 progress: true
 
-Archive {task} only when the verification report passes; otherwise report that archive is blocked and preserve active artifacts.
+Archive {task} only when the verification report passes and file-backed sync is complete or not applicable; otherwise report that archive is blocked and preserve active artifacts.

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

@@ -29,11 +29,20 @@ progress: true
 
 Run focused and full verification for {task} using the apply-progress and project artifacts. Include review/judgment blockers.
 
+## sdd-sync
+
+reads: init.md+apply-progress.md+verify-report.md
+output: sync-report.md
+outputMode: file-only
+progress: true
+
+Sync verified file-backed delta specs for {task} into `openspec/specs/` without archiving. In Engram-only mode, report that canonical sync is not applicable.
+
 ## sdd-archive
 
-reads: verify-report.md
+reads: verify-report.md+sync-report.md
 output: archive-report.md
 outputMode: file-only
 progress: true
 
-Archive {task} only when verification succeeds. If verification fails, leave artifacts active and report the blocker.
+Archive {task} only when verification succeeds and file-backed sync is complete or not applicable. If verification or sync fails, leave artifacts active and report the blocker.

package/extensions/gentle-ai.ts

@@ -33,6 +33,36 @@ import {
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
 
+function sddAssetDriftCount(cwd: string): number {
+	let stale = 0;
+	for (const [assetSubdir, installedSubdir] of [
+		["agents", join(".pi", "agents")],
+		["chains", join(".pi", "chains")],
+	] as const) {
+		const assetDir = join(ASSETS_DIR, assetSubdir);
+		if (!existsSync(assetDir)) continue;
+		for (const entry of readdirSync(assetDir, { withFileTypes: true })) {
+			if (!entry.isFile()) continue;
+			const installedPath = join(cwd, installedSubdir, entry.name);
+			try {
+				if (!existsSync(installedPath)) {
+					stale += 1;
+					continue;
+				}
+				if (
+					readFileSync(join(assetDir, entry.name), "utf8") !==
+					readFileSync(installedPath, "utf8")
+				) {
+					stale += 1;
+				}
+			} catch {
+				stale += 1;
+			}
+		}
+	}
+	return stale;
+}
+
 let orchestratorPromptCache: string | null = null;
 function getOrchestratorPrompt(): string {
 	if (orchestratorPromptCache === null) {
@@ -128,6 +158,7 @@ const SDD_AGENT_NAMES = [
 	"sdd-tasks",
 	"sdd-apply",
 	"sdd-verify",
+	"sdd-sync",
 	"sdd-archive",
 ] as const;
 const SDD_AGENT_NAME_SET = new Set<string>(SDD_AGENT_NAMES);
@@ -1338,6 +1369,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 			const openspecConfigured = existsSync(
 				join(ctx.cwd, "openspec", "config.yaml"),
 			);
+			const staleSddAssets = sddAssetDriftCount(ctx.cwd);
 			const modelConfig = await readModelConfigAsync(ctx.cwd);
 			ctx.ui.notify(
 				[
@@ -1345,11 +1377,16 @@ export default function gentleAi(pi: ExtensionAPI): void {
 					`Persona: ${readPersonaMode(ctx.cwd)}`,
 					`SDD agents: ${agentsInstalled ? "installed" : "not installed"}`,
 					`SDD chains: ${chainsInstalled ? "installed" : "not installed"}`,
+					`SDD assets stale: ${staleSddAssets} file(s)${
+						staleSddAssets > 0
+							? " — run /gentle-ai:install-sdd --force to refresh intentionally"
+							: ""
+					}`,
 					`OpenSpec config: ${openspecConfigured ? "present" : "missing"}`,
 					`Global model config: ${existsSync(modelConfigPath(ctx.cwd)) ? "present" : "missing"}`,
 					...describeModelConfig(ctx.cwd, modelConfig),
 				].join("\n"),
-				"info",
+				staleSddAssets > 0 ? "warning" : "info",
 			);
 		},
 	});

package/lib/openspec-deltas.ts

@@ -0,0 +1,156 @@
+export interface RequirementBlock {
+	name: string;
+	content: string;
+	start: number;
+	end: number;
+}
+
+export interface DeltaSpec {
+	added: RequirementBlock[];
+	modified: RequirementBlock[];
+	removed: RequirementBlock[];
+}
+
+type DeltaOperation = keyof DeltaSpec;
+
+const REQUIREMENT_HEADING = /^### Requirement:\s*(.+?)\s*$/gm;
+const DELTA_SECTION_HEADING = /^##\s+(ADDED|MODIFIED|REMOVED)\s+Requirements\s*$/gim;
+
+function normalizeMarkdown(markdown: string): string {
+	return markdown.replace(/\r\n/g, "\n");
+}
+
+function nextTopLevelSection(markdown: string, from: number): number {
+	const match = /^##\s+/gm;
+	match.lastIndex = from;
+	const next = match.exec(markdown);
+	return next?.index ?? markdown.length;
+}
+
+function cleanRequirementContent(content: string): string {
+	return content.trimEnd().replace(/\n\s*---\s*$/m, "").trimEnd();
+}
+
+function operationKey(label: string): DeltaOperation {
+	switch (label.toUpperCase()) {
+		case "ADDED":
+			return "added";
+		case "MODIFIED":
+			return "modified";
+		case "REMOVED":
+			return "removed";
+		default:
+			throw new Error(`Unsupported delta operation: ${label}`);
+	}
+}
+
+export function parseRequirementBlocks(markdown: string): RequirementBlock[] {
+	const source = normalizeMarkdown(markdown);
+	const matches = [...source.matchAll(REQUIREMENT_HEADING)];
+	return matches.map((match, index) => {
+		const start = match.index ?? 0;
+		const end = matches[index + 1]?.index ?? nextTopLevelSection(source, start + match[0].length);
+		return {
+			name: match[1].trim(),
+			content: cleanRequirementContent(source.slice(start, end)),
+			start,
+			end,
+		};
+	});
+}
+
+export function parseDeltaSpec(markdown: string): DeltaSpec {
+	const source = normalizeMarkdown(markdown);
+	const sectionMatches = [...source.matchAll(DELTA_SECTION_HEADING)];
+	const delta: DeltaSpec = { added: [], modified: [], removed: [] };
+	const seen = new Map<string, string>();
+
+	for (const [index, match] of sectionMatches.entries()) {
+		const sectionStart = (match.index ?? 0) + match[0].length;
+		const sectionEnd = sectionMatches[index + 1]?.index ?? source.length;
+		const key = operationKey(match[1]);
+		const section = source.slice(sectionStart, sectionEnd);
+		const blocks = parseRequirementBlocks(section);
+		delta[key].push(...blocks);
+	}
+
+	for (const [operation, blocks] of Object.entries(delta) as [DeltaOperation, RequirementBlock[]][]) {
+		for (const block of blocks) {
+			const previous = seen.get(block.name);
+			if (previous) {
+				throw new Error(
+					`Duplicate delta operation for requirement "${block.name}" (${previous} and ${operation})`,
+				);
+			}
+			seen.set(block.name, operation);
+		}
+	}
+
+	return delta;
+}
+
+function requirementMap(blocks: RequirementBlock[]): Map<string, RequirementBlock> {
+	const out = new Map<string, RequirementBlock>();
+	for (const block of blocks) {
+		if (out.has(block.name)) throw new Error(`Duplicate canonical requirement "${block.name}"`);
+		out.set(block.name, block);
+	}
+	return out;
+}
+
+function requireCanonicalBlock(
+	canonical: Map<string, RequirementBlock>,
+	name: string,
+	operation: string,
+): RequirementBlock {
+	const block = canonical.get(name);
+	if (!block) throw new Error(`Missing canonical requirement "${name}" for ${operation}`);
+	return block;
+}
+
+function appendAddedRequirements(markdown: string, added: RequirementBlock[]): string {
+	if (added.length === 0) return markdown;
+	const addition = added.map((block) => block.content.trim()).join("\n\n---\n\n");
+	const requirementsHeading = /^## Requirements\s*$/m.exec(markdown);
+	if (!requirementsHeading) return `${markdown.trimEnd()}\n\n## Requirements\n\n${addition}\n`;
+
+	const sectionStart = requirementsHeading.index + requirementsHeading[0].length;
+	const sectionEnd = nextTopLevelSection(markdown, sectionStart);
+	const before = markdown.slice(0, sectionEnd).trimEnd();
+	const after = markdown.slice(sectionEnd).replace(/^\n+/, "");
+	return after
+		? `${before}\n\n---\n\n${addition}\n\n${after}`
+		: `${before}\n\n---\n\n${addition}\n`;
+}
+
+export function applyDeltaSpec(canonicalMarkdown: string, deltaMarkdown: string): string {
+	let result = normalizeMarkdown(canonicalMarkdown);
+	const delta = parseDeltaSpec(deltaMarkdown);
+	const canonical = requirementMap(parseRequirementBlocks(result));
+
+	for (const block of delta.added) {
+		if (canonical.has(block.name)) {
+			throw new Error(`Cannot add existing canonical requirement "${block.name}"`);
+		}
+	}
+
+	const replacements: Array<{ start: number; end: number; content: string }> = [];
+	for (const block of delta.modified) {
+		const target = requireCanonicalBlock(canonical, block.name, "MODIFIED");
+		replacements.push({ start: target.start, end: target.end, content: block.content.trimEnd() });
+	}
+	for (const block of delta.removed) {
+		const target = requireCanonicalBlock(canonical, block.name, "REMOVED");
+		replacements.push({ start: target.start, end: target.end, content: "" });
+	}
+
+	for (const replacement of replacements.sort((a, b) => b.start - a.start)) {
+		const prefix = result.slice(0, replacement.start).trimEnd();
+		const suffix = result.slice(replacement.end).replace(/^\n+/, "");
+		result = replacement.content
+			? `${prefix}\n\n${replacement.content}\n\n${suffix}`.trimEnd() + "\n"
+			: `${prefix}\n\n${suffix}`.trimEnd() + "\n";
+	}
+
+	return appendAddedRequirements(result, delta.added).trimEnd() + "\n";
+}

package/lib/openspec-guardrails.ts

@@ -0,0 +1,99 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parseDeltaSpec } from "./openspec-deltas.ts";
+
+export interface DomainCollision {
+	change: string;
+	path: string;
+}
+
+export interface LegacyFlatSpecWarning {
+	change: string;
+	path: string;
+	hasDomainSpecs: boolean;
+}
+
+export interface LargeModifiedRequirement {
+	name: string;
+	lineCount: number;
+}
+
+export interface DestructiveDeltaReport {
+	destructive: boolean;
+	removedRequirements: string[];
+	largeModifiedRequirements: LargeModifiedRequirement[];
+}
+
+export interface DestructiveDeltaOptions {
+	largeModifiedLineThreshold?: number;
+}
+
+function safeDirectories(path: string): string[] {
+	try {
+		return readdirSync(path).filter((entry) => {
+			try {
+				return statSync(join(path, entry)).isDirectory();
+			} catch {
+				return false;
+			}
+		});
+	} catch {
+		return [];
+	}
+}
+
+function hasAnyDomainSpec(specsDir: string): boolean {
+	for (const domain of safeDirectories(specsDir)) {
+		if (existsSync(join(specsDir, domain, "spec.md"))) return true;
+	}
+	return false;
+}
+
+export function detectActiveDomainCollisions(
+	cwd: string,
+	changeName: string,
+	domain: string,
+): DomainCollision[] {
+	const changesDir = join(cwd, "openspec", "changes");
+	const collisions: DomainCollision[] = [];
+	for (const change of safeDirectories(changesDir)) {
+		if (change === "archive" || change === changeName) continue;
+		const path = join(changesDir, change, "specs", domain, "spec.md");
+		if (existsSync(path)) collisions.push({ change, path });
+	}
+	return collisions;
+}
+
+export function detectLegacyFlatSpec(
+	cwd: string,
+	changeName: string,
+): LegacyFlatSpecWarning | undefined {
+	const changeDir = join(cwd, "openspec", "changes", changeName);
+	const path = join(changeDir, "spec.md");
+	if (!existsSync(path)) return undefined;
+	return {
+		change: changeName,
+		path,
+		hasDomainSpecs: hasAnyDomainSpec(join(changeDir, "specs")),
+	};
+}
+
+export function analyzeDeltaDestructiveness(
+	deltaMarkdown: string,
+	options: DestructiveDeltaOptions = {},
+): DestructiveDeltaReport {
+	const threshold = options.largeModifiedLineThreshold ?? 40;
+	const delta = parseDeltaSpec(deltaMarkdown);
+	const removedRequirements = delta.removed.map((block) => block.name);
+	const largeModifiedRequirements = delta.modified
+		.map((block) => ({
+			name: block.name,
+			lineCount: block.content.split("\n").length,
+		}))
+		.filter((block) => block.lineCount >= threshold);
+	return {
+		destructive: removedRequirements.length > 0 || largeModifiedRequirements.length > 0,
+		removedRequirements,
+		largeModifiedRequirements,
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "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

@@ -6,9 +6,21 @@ import { fileURLToPath } from "node:url";
 const root = join(fileURLToPath(new URL("..", import.meta.url)));
 
 const requiredPaths = [
+  "assets/agents/sdd-apply.md",
+  "assets/agents/sdd-archive.md",
+  "assets/agents/sdd-design.md",
+  "assets/agents/sdd-explore.md",
   "assets/agents/sdd-init.md",
+  "assets/agents/sdd-proposal.md",
+  "assets/agents/sdd-spec.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/strict-tdd.md",
+  "assets/support/strict-tdd-verify.md",
   "extensions/gentle-ai.ts",
   "extensions/sdd-init.ts",
   "extensions/skill-registry.ts",

package/tests/openspec-deltas.test.ts

@@ -0,0 +1,209 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+	applyDeltaSpec,
+	parseDeltaSpec,
+	parseRequirementBlocks,
+} from "../lib/openspec-deltas.ts";
+
+const canonicalSpec = `# Example Specification
+
+## Purpose
+
+Example domain.
+
+## Requirements
+
+### Requirement: Existing Behavior
+
+The system MUST keep existing behavior.
+
+#### Scenario: Happy path
+
+- GIVEN an existing condition
+- WHEN the action runs
+- THEN existing behavior is preserved
+
+---
+
+### Requirement: Deprecated Behavior
+
+The system MUST support old behavior.
+
+#### Scenario: Old path
+
+- GIVEN an old condition
+- WHEN the action runs
+- THEN old behavior is preserved
+`;
+
+const deltaSpec = `# Delta for Example
+
+## ADDED Requirements
+
+### Requirement: New Behavior
+
+The system MUST support new behavior.
+
+#### Scenario: New path
+
+- GIVEN a new condition
+- WHEN the action runs
+- THEN new behavior is available
+
+## MODIFIED Requirements
+
+### Requirement: Existing Behavior
+
+The system MUST keep existing behavior and report audit evidence.
+(Previously: existing behavior did not report audit evidence)
+
+#### Scenario: Happy path
+
+- GIVEN an existing condition
+- WHEN the action runs
+- THEN existing behavior is preserved
+- AND audit evidence is recorded
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Behavior
+
+(Reason: old behavior is no longer supported)
+`;
+
+test("parseRequirementBlocks extracts requirement blocks with names", () => {
+	const blocks = parseRequirementBlocks(canonicalSpec);
+
+	assert.deepEqual(
+		blocks.map((block) => block.name),
+		["Existing Behavior", "Deprecated Behavior"],
+	);
+	assert.match(blocks[0].content, /Scenario: Happy path/);
+	assert.match(blocks[1].content, /old behavior/i);
+});
+
+test("parseDeltaSpec extracts ADDED, MODIFIED, and REMOVED sections", () => {
+	const delta = parseDeltaSpec(deltaSpec);
+
+	assert.deepEqual(
+		delta.added.map((block) => block.name),
+		["New Behavior"],
+	);
+	assert.deepEqual(
+		delta.modified.map((block) => block.name),
+		["Existing Behavior"],
+	);
+	assert.deepEqual(
+		delta.removed.map((block) => block.name),
+		["Deprecated Behavior"],
+	);
+});
+
+test("applyDeltaSpec applies ADDED, MODIFIED, and REMOVED while preserving unrelated content", () => {
+	const result = applyDeltaSpec(canonicalSpec, deltaSpec);
+
+	assert.match(result, /### Requirement: New Behavior/);
+	assert.match(result, /audit evidence is recorded/);
+	assert.doesNotMatch(result, /### Requirement: Deprecated Behavior/);
+	assert.match(result, /# Example Specification/);
+	assert.match(result, /## Purpose/);
+	assert.match(result, /## Requirements/);
+});
+
+test("applyDeltaSpec preserves sections after Requirements when appending ADDED", () => {
+	const result = applyDeltaSpec(
+		`${canonicalSpec}\n## Notes\n\nKeep this section.\n`,
+		`# Delta
+
+## ADDED Requirements
+
+### Requirement: New Behavior
+
+The system MUST support new behavior.
+`,
+	);
+
+	assert.match(result, /### Requirement: New Behavior[\s\S]*\n\n## Notes\n\nKeep this section\./);
+	assert.doesNotMatch(result, /Behavior## Notes/);
+});
+
+test("applyDeltaSpec does not duplicate separators between multiple ADDED requirements", () => {
+	const result = applyDeltaSpec(
+		canonicalSpec,
+		`# Delta
+
+## ADDED Requirements
+
+### Requirement: First New Behavior
+
+The system MUST support the first behavior.
+
+---
+
+### Requirement: Second New Behavior
+
+The system MUST support the second behavior.
+`,
+	);
+
+	assert.match(result, /### Requirement: First New Behavior[\s\S]*---[\s\S]*### Requirement: Second New Behavior/);
+	assert.doesNotMatch(result, /---\n\n---/);
+});
+
+test("applyDeltaSpec rejects MODIFIED requirements that do not exist", () => {
+	assert.throws(
+		() =>
+			applyDeltaSpec(
+				canonicalSpec,
+				`# Delta
+
+## MODIFIED Requirements
+
+### Requirement: Missing Behavior
+
+The system MUST fail.
+`,
+			),
+		/missing canonical requirement.*Missing Behavior/i,
+	);
+});
+
+test("applyDeltaSpec rejects REMOVED requirements that do not exist", () => {
+	assert.throws(
+		() =>
+			applyDeltaSpec(
+				canonicalSpec,
+				`# Delta
+
+## REMOVED Requirements
+
+### Requirement: Missing Behavior
+
+(Reason: already absent)
+`,
+			),
+		/missing canonical requirement.*Missing Behavior/i,
+	);
+});
+
+test("applyDeltaSpec rejects duplicate operations for the same requirement", () => {
+	assert.throws(
+		() =>
+			parseDeltaSpec(`# Delta
+
+## ADDED Requirements
+
+### Requirement: Same Behavior
+
+The system MUST do one thing.
+
+## REMOVED Requirements
+
+### Requirement: Same Behavior
+
+(Reason: conflict)
+`),
+		/duplicate delta operation.*Same Behavior/i,
+	);
+});

package/tests/openspec-guardrails.test.ts

@@ -0,0 +1,71 @@
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import {
+	analyzeDeltaDestructiveness,
+	detectActiveDomainCollisions,
+	detectLegacyFlatSpec,
+} from "../lib/openspec-guardrails.ts";
+
+test("detectActiveDomainCollisions finds other active changes touching the same domain", async () => {
+	const cwd = await mkdtemp(join(tmpdir(), "gentle-pi-guardrails-"));
+	mkdirSync(join(cwd, "openspec/changes/current/specs/sdd-openspec"), { recursive: true });
+	mkdirSync(join(cwd, "openspec/changes/other/specs/sdd-openspec"), { recursive: true });
+	mkdirSync(join(cwd, "openspec/changes/archive/2026-01-01-old/specs/sdd-openspec"), { recursive: true });
+	writeFileSync(join(cwd, "openspec/changes/current/specs/sdd-openspec/spec.md"), "# Current\n");
+	writeFileSync(join(cwd, "openspec/changes/other/specs/sdd-openspec/spec.md"), "# Other\n");
+	writeFileSync(join(cwd, "openspec/changes/archive/2026-01-01-old/specs/sdd-openspec/spec.md"), "# Old\n");
+
+	const collisions = detectActiveDomainCollisions(cwd, "current", "sdd-openspec");
+
+	assert.deepEqual(collisions.map((collision) => collision.change), ["other"]);
+	assert.match(collisions[0].path, /openspec\/changes\/other\/specs\/sdd-openspec\/spec\.md$/);
+});
+
+test("detectLegacyFlatSpec warns when a flat change spec exists without domain specs", async () => {
+	const cwd = await mkdtemp(join(tmpdir(), "gentle-pi-legacy-flat-"));
+	mkdirSync(join(cwd, "openspec/changes/legacy-change"), { recursive: true });
+	writeFileSync(join(cwd, "openspec/changes/legacy-change/spec.md"), "# Legacy\n");
+
+	assert.deepEqual(detectLegacyFlatSpec(cwd, "legacy-change"), {
+		change: "legacy-change",
+		path: join(cwd, "openspec/changes/legacy-change/spec.md"),
+		hasDomainSpecs: false,
+	});
+});
+
+test("detectLegacyFlatSpec reports domain specs when both old and new layouts exist", async () => {
+	const cwd = await mkdtemp(join(tmpdir(), "gentle-pi-legacy-both-"));
+	mkdirSync(join(cwd, "openspec/changes/mixed/specs/domain"), { recursive: true });
+	writeFileSync(join(cwd, "openspec/changes/mixed/spec.md"), "# Legacy\n");
+	writeFileSync(join(cwd, "openspec/changes/mixed/specs/domain/spec.md"), "# Domain\n");
+
+	assert.equal(detectLegacyFlatSpec(cwd, "mixed")?.hasDomainSpecs, true);
+});
+
+test("analyzeDeltaDestructiveness reports removed and large modified requirements", () => {
+	const report = analyzeDeltaDestructiveness(
+		`# Delta
+
+## MODIFIED Requirements
+
+### Requirement: Big Replacement
+
+${Array.from({ length: 15 }, (_, index) => `Line ${index + 1}`).join("\n")}
+
+## REMOVED Requirements
+
+### Requirement: Removed Behavior
+
+(Reason: no longer supported)
+`,
+		{ largeModifiedLineThreshold: 10 },
+	);
+
+	assert.equal(report.destructive, true);
+	assert.deepEqual(report.removedRequirements, ["Removed Behavior"]);
+	assert.deepEqual(report.largeModifiedRequirements.map((item) => item.name), ["Big Replacement"]);
+});

package/tests/runtime-harness.mjs

@@ -288,6 +288,7 @@ async function run() {
 			{ action: "continue" },
 		);
 		assert.equal(existsSync(join(lazySddCwd, ".pi", "agents", "sdd-apply.md")), true);
+		assert.equal(existsSync(join(lazySddCwd, ".pi", "agents", "sdd-sync.md")), true);
 		assert.equal(existsSync(join(lazySddCwd, ".pi", "chains", "sdd-full.chain.md")), true);
 		const lazyAppliedAgent = await readFile(
 			join(lazySddCwd, ".pi", "agents", "sdd-apply.md"),
@@ -383,11 +384,27 @@ async function run() {
 		await rm(installCwd, { recursive: true, force: true });
 	}
 
+	const staleAssetsCwd = await tempWorkspace();
+	try {
+		await mkdir(join(staleAssetsCwd, ".pi", "agents"), { recursive: true });
+		await mkdir(join(staleAssetsCwd, ".pi", "chains"), { 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");
+		const ctx = createCtx(staleAssetsCwd, true);
+		await commands.get("gentle-ai:status").handler("", ctx);
+		assert.match(ctx.ui.notifications.at(-1).message, /SDD assets stale: \d+ file\(s\)/);
+		assert.match(ctx.ui.notifications.at(-1).message, /gentle-ai:install-sdd --force/);
+	} finally {
+		await rm(staleAssetsCwd, { recursive: true, force: true });
+	}
+
 	const sddCwd = await tempWorkspace();
 	try {
 		const ctx = createCtx(sddCwd, true);
 		await commands.get("sdd-init").handler("", ctx);
 		assert.equal(existsSync(join(sddCwd, ".pi", "agents", "sdd-apply.md")), true);
+		assert.equal(existsSync(join(sddCwd, ".pi", "agents", "sdd-sync.md")), true);
 		assert.equal(existsSync(join(sddCwd, ".pi", "chains", "sdd-full.chain.md")), true);
 		assert.equal(ctx.ui.selections.length, 3);
 		assert.match(ctx.ui.notifications[0].message, /SDD preflight complete/);