gentle-pi 0.3.3 → 0.3.5

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/lib/sdd-preflight.ts

@@ -1,4 +1,5 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -6,6 +7,10 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
 
+function gentlePiAgentHome(): string {
+	return process.env.GENTLE_PI_AGENT_HOME ?? join(homedir(), ".pi", "agent");
+}
+
 export type SddExecutionMode = "interactive" | "auto";
 export type SddArtifactStore = "openspec" | "engram" | "both";
 export type SddChainedPrStrategy =
@@ -89,22 +94,23 @@ function copyDirectoryFiles(
 }
 
 export function installSddAssets(
-	cwd: string,
+	_cwd: string,
 	force: boolean,
 ): { agents: number; chains: number; support: number; skipped: number } {
+	const agentHome = gentlePiAgentHome();
 	const agents = copyDirectoryFiles(
 		join(ASSETS_DIR, "agents"),
-		join(cwd, ".pi", "agents"),
+		join(agentHome, "agents"),
 		force,
 	);
 	const chains = copyDirectoryFiles(
 		join(ASSETS_DIR, "chains"),
-		join(cwd, ".pi", "chains"),
+		join(agentHome, "chains"),
 		force,
 	);
 	const support = copyDirectoryFiles(
 		join(ASSETS_DIR, "support"),
-		join(cwd, ".pi", "gentle-ai", "support"),
+		join(agentHome, "gentle-ai", "support"),
 		force,
 	);
 	return {
@@ -248,7 +254,7 @@ export async function ensureSddPreflight(
 					`Artifacts: ${prefs.artifactStore}`,
 					`PR chaining: ${prefs.chainedPrStrategy}`,
 					`Review budget: ${prefs.reviewBudgetLines} changed lines`,
-					`Assets installed: ${result.agents} agent(s), ${result.chains} chain(s), ${result.support} support file(s), ${result.skipped} skipped.`,
+					`Global SDD assets ready: ${result.agents} agent(s), ${result.chains} chain(s), ${result.support} support file(s), ${result.skipped} already present.`,
 					modelRoutingLine,
 				].join("\n"),
 				modelResult.invalidPath ? "warning" : "info",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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/skills/gentle-ai/SKILL.md

@@ -55,4 +55,4 @@ Hard delegation triggers:
 - **Incident rule**: after wrong cwd, accidental worktree/repo mutation, merge recovery, confusing test command, or environment workaround, run fresh audit.
 - **Long-session rule**: after roughly 20 tool calls, 5 exploratory reads, or 2 non-mechanical edits with no delegation and accumulating complexity, pause and choose a subagent or justify not doing so.
 
-The package auto-installs SDD agents and chains into the project when a Pi session starts. Use `/gentle-ai:install-sdd --force` only for recovery or intentional overwrite.
+The package ensures SDD agents and chains are available as global Pi runtime assets. Project-local SDD files are overrides/debug copies only. Use `/gentle-ai:install-sdd --force` only for recovery or intentional global refresh.

package/skills/judgment-day/SKILL.md

@@ -13,7 +13,7 @@ Load this skill only when the user explicitly asks for Judgment Day, dual/advers
 
 ## Hard Rules
 
-- Resolve project skills before launching agents: read skill registry, match compact rules by target files/task, and inject the same `Project Standards` block into both judge prompts and fix prompts.
+- Resolve project skills before launching agents: read skill registry, match indexed paths by target files/task, and pass the same `Skills to load before work` block into both judge prompts and fix prompts.
 - Launch **two blind judges in parallel** with identical target and criteria; never review the code yourself.
 - Wait for both judges before synthesis; never accept a partial verdict.
 - Classify warnings as `WARNING (real)` only if normal intended use can trigger them; otherwise downgrade to INFO as `WARNING (theoretical)`.

package/skills/judgment-day/references/prompts-and-formats.md

@@ -8,8 +8,8 @@ You are an adversarial code reviewer. Your ONLY job is to find problems.
 ## Target
 {files, feature, architecture, component}
 
-## Project Standards (auto-resolved)
-{matching compact rules, if available}
+## Skills to load before work
+{matching SKILL.md paths, if available}
 
 ## Review Criteria
 - Correctness: logical errors and behavior mismatches
@@ -33,7 +33,7 @@ WARNING rule: normal intended use can trigger it → `WARNING (real)`; contrived
 
 If clean: `VERDICT: CLEAN — No issues found.`
 
-Always end with: `Skill Resolution: {injected|fallback-registry|fallback-path|none} — {details}`.
+Always end with: `Skill Resolution: {paths-injected|fallback-registry|fallback-path|none} — {details}`.
 ```
 
 ## Fix Agent Prompt
@@ -44,8 +44,8 @@ You are a surgical fix agent. Apply ONLY the confirmed issues listed below.
 ## Confirmed Issues to Fix
 {confirmed findings table}
 
-## Project Standards (auto-resolved)
-{matching compact rules, if available}
+## Skills to load before work
+{matching SKILL.md paths, if available}
 
 ## Instructions
 - Fix only confirmed issues.
@@ -54,7 +54,7 @@ You are a surgical fix agent. Apply ONLY the confirmed issues listed below.
 - If fixing a repeated pattern in touched files, fix all occurrences of that same pattern.
 - Return changed file, line, and fix summary.
 
-End with: `Skill Resolution: {injected|fallback-registry|fallback-path|none} — {details}`.
+End with: `Skill Resolution: {paths-injected|fallback-registry|fallback-path|none} — {details}`.
 ```
 
 ## Verdict Table

package/skills/skill-registry/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: skill-registry
+description: "Trigger: update skills, skill registry, actualizar skills, after skill changes. Index available skills by trigger and path."
+license: MIT
+metadata:
+  author: gentleman-programming
+  version: "1.0"
+---
+
+## Activation Contract
+
+Use this skill after installing, removing, creating, moving, or renaming skills, or when a delegator needs a fresh skill index.
+
+## Hard Rules
+
+- The registry is an index, not a compiler or summary. `SKILL.md` remains the source of truth.
+- Do not generate or inject compact rules by default; preserve author intent by passing exact skill paths to subagents.
+- Always write `.atl/skill-registry.md` regardless of SDD persistence mode.
+- Save the registry to Engram as `topic_key: skill-registry` when available, with `capture_prompt: false`.
+- Skip `sdd-*`, `_shared`, and `skill-registry`; deduplicate by skill name, preferring project-level skills over user-level skills.
+- Add `.atl/` to `.gitignore` when possible unless explicitly disabled.
+
+## Decision Gates
+
+| Situation | Action |
+| --- | --- |
+| Same skill exists globally and in project | Keep the project-level skill |
+| Same skill exists in multiple global locations | Keep the first source in scan order |
+| No skills found | Write an empty registry so agents stop searching blindly |
+| Agent will delegate work | Select matching registry rows and pass their `SKILL.md` paths |
+
+## Execution Steps
+
+1. Scan all known user and project skill directories for `*/SKILL.md`.
+2. Read frontmatter only as needed to extract `name` and `description` trigger text.
+3. Render `.atl/skill-registry.md` with scanned sources, registry contract, skill name, trigger/description, scope, and exact path.
+4. Persist to Engram when available using `title: skill-registry`, `topic_key: skill-registry`, `type: config`, and `capture_prompt: false`.
+5. Return the registry path, skill count, cache status, and whether Engram was updated.
+
+## Output Contract
+
+Return:
+- Project name and `.atl/skill-registry.md` path.
+- Number of indexed skills.
+- Whether the cache was hit or regenerated.
+- Any skipped or duplicate skills when relevant.
+
+## References
+
+- `docs/skill-style-guide.md` — how skills should be authored before indexing.
+- `skills/_shared/skill-resolver.md` — how delegators use the index.

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"]);
+});