gsd-pi 2.8.0 → 2.8.2

package/src/resources/extensions/gsd/tests/run-uat.test.ts

@@ -226,7 +226,6 @@ async function main(): Promise<void> {
   const milestoneId = 'M001';
   const sliceId = 'S01';
   const uatPath = '.gsd/milestones/M001/slices/S01/S01-UAT.md';
-  const uatResultAbsPath = '/tmp/gsd-test/S01-UAT-RESULT.md';
   const uatResultPath = '.gsd/milestones/M001/slices/S01/S01-UAT-RESULT.md';
   const uatType = 'artifact-driven';
   const inlinedContext = '<!-- no context -->';
@@ -238,7 +237,6 @@ async function main(): Promise<void> {
       milestoneId,
       sliceId,
       uatPath,
-      uatResultAbsPath,
       uatResultPath,
       uatType,
       inlinedContext,
@@ -261,8 +259,8 @@ async function main(): Promise<void> {
     `prompt contains sliceId value "${sliceId}" after substitution`,
   );
   assert(
-    promptResult?.includes(uatResultAbsPath) ?? false,
-    `prompt contains uatResultAbsPath value after substitution`,
+    promptResult?.includes(uatResultPath) ?? false,
+    `prompt contains uatResultPath value after substitution`,
   );
   assert(
     !/\{\{[^}]+\}\}/.test(promptResult ?? ''),

package/src/resources/extensions/gsd/tests/write-gate.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Unit tests for the CONTEXT.md write-gate (D031 guard chain).
+ *
+ * Exercises shouldBlockContextWrite() — a pure function that implements:
+ *   (a) toolName !== "write" → pass
+ *   (b) milestoneId null → pass (not in discussion)
+ *   (c) path doesn't match /M\d+-CONTEXT\.md$/ → pass
+ *   (d) depthVerified → pass
+ *   (e) else → block with actionable reason
+ */
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { shouldBlockContextWrite } from '../index.ts';
+
+// ─── Scenario 1: Blocks CONTEXT.md write during discussion without depth verification (absolute path) ──
+
+test('write-gate: blocks CONTEXT.md write during discussion without depth verification (absolute path)', () => {
+  const result = shouldBlockContextWrite(
+    'write',
+    '/Users/dev/project/.gsd/milestones/M001/M001-CONTEXT.md',
+    'M001',
+    false,
+  );
+  assert.strictEqual(result.block, true, 'should block the write');
+  assert.ok(result.reason, 'should provide a reason');
+});
+
+// ─── Scenario 2: Blocks CONTEXT.md write during discussion without depth verification (relative path) ──
+
+test('write-gate: blocks CONTEXT.md write during discussion without depth verification (relative path)', () => {
+  const result = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M005/M005-CONTEXT.md',
+    'M005',
+    false,
+  );
+  assert.strictEqual(result.block, true, 'should block the write');
+  assert.ok(result.reason, 'should provide a reason');
+});
+
+// ─── Scenario 3: Allows CONTEXT.md write after depth verification ──
+
+test('write-gate: allows CONTEXT.md write after depth verification', () => {
+  const result = shouldBlockContextWrite(
+    'write',
+    '/Users/dev/project/.gsd/milestones/M001/M001-CONTEXT.md',
+    'M001',
+    true,
+  );
+  assert.strictEqual(result.block, false, 'should not block after depth verification');
+  assert.strictEqual(result.reason, undefined, 'should have no reason');
+});
+
+// ─── Scenario 4: Allows CONTEXT.md write outside discussion phase (milestoneId null) ──
+
+test('write-gate: allows CONTEXT.md write outside discussion phase', () => {
+  const result = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M001/M001-CONTEXT.md',
+    null,
+    false,
+  );
+  assert.strictEqual(result.block, false, 'should not block outside discussion phase');
+});
+
+// ─── Scenario 5: Allows non-CONTEXT.md writes during discussion ──
+
+test('write-gate: allows non-CONTEXT.md writes during discussion', () => {
+  // DISCUSSION.md
+  const r1 = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M001/M001-DISCUSSION.md',
+    'M001',
+    false,
+  );
+  assert.strictEqual(r1.block, false, 'DISCUSSION.md should pass');
+
+  // Slice file
+  const r2 = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M001/slices/S01/S01-PLAN.md',
+    'M001',
+    false,
+  );
+  assert.strictEqual(r2.block, false, 'slice plan should pass');
+
+  // Regular code file
+  const r3 = shouldBlockContextWrite(
+    'write',
+    'src/index.ts',
+    'M001',
+    false,
+  );
+  assert.strictEqual(r3.block, false, 'regular code file should pass');
+});
+
+// ─── Scenario 6: Regex specificity — doesn't match S01-CONTEXT.md ──
+
+test('write-gate: regex does not match slice context files (S01-CONTEXT.md)', () => {
+  const result = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M001/slices/S01/S01-CONTEXT.md',
+    'M001',
+    false,
+  );
+  assert.strictEqual(result.block, false, 'S01-CONTEXT.md should not be blocked');
+});
+
+// ─── Scenario 7: Error message contains actionable instruction ──
+
+test('write-gate: blocked reason contains depth_verification keyword', () => {
+  const result = shouldBlockContextWrite(
+    'write',
+    '.gsd/milestones/M999/M999-CONTEXT.md',
+    'M999',
+    false,
+  );
+  assert.strictEqual(result.block, true);
+  assert.ok(result.reason!.includes('depth_verification'), 'reason should mention depth_verification question id');
+  assert.ok(result.reason!.includes('ask_user_questions'), 'reason should mention ask_user_questions tool');
+});

package/src/resources/extensions/ttsr/index.ts

@@ -0,0 +1,163 @@
+/**
+ * TTSR Extension — Time Traveling Stream Rules
+ *
+ * Zero-context-cost guardrails that monitor streaming output against regex
+ * patterns. On match: abort stream, inject rule as system reminder, retry.
+ * Rules cost nothing until they fire.
+ *
+ * Hooks:
+ *   session_start  → load rules, populate manager
+ *   turn_start     → reset buffers
+ *   message_update → check delta against rules, abort on match
+ *   turn_end       → increment message count
+ *   agent_end      → if pending violation, inject rule via sendMessage
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
+import type { AssistantMessageEvent } from "@gsd/pi-ai";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { TtsrManager, type Rule, type TtsrMatchContext } from "./ttsr-manager.js";
+import { loadRules } from "./rule-loader.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+interface PendingViolation {
+	rules: Rule[];
+}
+
+function buildInterruptContent(rule: Rule): string {
+	const template = readFileSync(join(__dirname, "ttsr-interrupt.md"), "utf-8");
+	return template
+		.replace("{{name}}", rule.name)
+		.replace("{{path}}", rule.path)
+		.replace("{{content}}", rule.content);
+}
+
+/**
+ * Extract match context from an AssistantMessageEvent delta.
+ * Returns null for non-delta events.
+ */
+function extractDeltaContext(
+	event: AssistantMessageEvent,
+): { delta: string; context: TtsrMatchContext } | null {
+	if (event.type === "text_delta") {
+		return {
+			delta: event.delta,
+			context: { source: "text", streamKey: "text" },
+		};
+	}
+	if (event.type === "thinking_delta") {
+		return {
+			delta: event.delta,
+			context: { source: "thinking", streamKey: "thinking" },
+		};
+	}
+	if (event.type === "toolcall_delta") {
+		// Extract tool name and file paths from the partial message
+		const partial = event.partial;
+		const contentBlock = partial?.content?.[event.contentIndex];
+		const toolName = contentBlock && "name" in contentBlock ? (contentBlock as any).name : undefined;
+
+		// Try to extract file paths from partial JSON arguments
+		const filePaths: string[] = [];
+		if (contentBlock && "partialJson" in contentBlock) {
+			const json = (contentBlock as any).partialJson as string | undefined;
+			if (json) {
+				// Look for file_path or path in partial JSON
+				const pathMatch = json.match(/"(?:file_path|path)"\s*:\s*"([^"]+)"/);
+				if (pathMatch) filePaths.push(pathMatch[1]);
+			}
+		}
+
+		return {
+			delta: event.delta,
+			context: {
+				source: "tool",
+				toolName,
+				filePaths: filePaths.length > 0 ? filePaths : undefined,
+				streamKey: `toolcall:${event.contentIndex}`,
+			},
+		};
+	}
+	return null;
+}
+
+export default function (pi: ExtensionAPI) {
+	let manager: TtsrManager | null = null;
+	let pendingViolation: PendingViolation | null = null;
+
+	// ── session_start: load rules, populate manager ─────────────────────
+	pi.on("session_start", async (_event, ctx) => {
+		const rules = loadRules(ctx.cwd);
+		if (rules.length === 0) {
+			manager = null;
+			return;
+		}
+
+		manager = new TtsrManager();
+		let loaded = 0;
+		for (const rule of rules) {
+			if (manager.addRule(rule)) loaded++;
+		}
+
+		if (loaded === 0) {
+			manager = null;
+		}
+	});
+
+	// ── turn_start: reset buffers ───────────────────────────────────────
+	pi.on("turn_start", async () => {
+		if (!manager) return;
+		manager.resetBuffer();
+		pendingViolation = null;
+	});
+
+	// ── message_update: check delta against rules ───────────────────────
+	pi.on("message_update", async (event, ctx) => {
+		if (!manager || !manager.hasRules()) return;
+		if (pendingViolation) return; // Already matched, waiting for agent_end
+
+		const extracted = extractDeltaContext(event.assistantMessageEvent);
+		if (!extracted) return;
+
+		const { delta, context } = extracted;
+		const matches = manager.checkDelta(delta, context);
+		if (matches.length === 0) return;
+
+		// Match found — set pending violation and abort
+		pendingViolation = { rules: matches };
+		manager.markInjected(matches);
+		ctx.abort();
+	});
+
+	// ── turn_end: increment message count ───────────────────────────────
+	pi.on("turn_end", async () => {
+		if (!manager) return;
+		manager.incrementMessageCount();
+	});
+
+	// ── agent_end: inject violation if pending ──────────────────────────
+	pi.on("agent_end", async () => {
+		if (!manager || !pendingViolation) return;
+
+		const violation = pendingViolation;
+		pendingViolation = null;
+
+		// Build interrupt content for all matching rules
+		const interruptParts = violation.rules.map(buildInterruptContent);
+		const fullInterrupt = interruptParts.join("\n\n");
+
+		// Inject as a message that triggers a new turn
+		pi.sendMessage(
+			{
+				customType: "ttsr-violation",
+				content: fullInterrupt,
+				display: false,
+			},
+			{ triggerTurn: true },
+		);
+	});
+}

package/src/resources/extensions/ttsr/rule-loader.ts

@@ -0,0 +1,121 @@
+/**
+ * TTSR Rule Loader
+ *
+ * Scans global (~/.gsd/agent/rules/*.md) and project-local (.gsd/rules/*.md)
+ * rule files. Parses YAML frontmatter for condition, scope, globs.
+ * Project rules override global rules with the same name.
+ */
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import type { Rule } from "./ttsr-manager.js";
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+/** Minimal YAML parser for frontmatter (handles string arrays and scalars). */
+function parseFrontmatter(raw: string): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+	let currentKey: string | null = null;
+	let currentArray: string[] | null = null;
+
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trimEnd();
+
+		// Array item under current key
+		if (currentKey && /^\s+-\s+/.test(trimmed)) {
+			const value = trimmed.replace(/^\s+-\s+/, "").replace(/^["']|["']$/g, "");
+			currentArray!.push(value);
+			continue;
+		}
+
+		// Flush previous array
+		if (currentKey && currentArray) {
+			result[currentKey] = currentArray;
+			currentKey = null;
+			currentArray = null;
+		}
+
+		// Key-value or key-with-array
+		const kvMatch = trimmed.match(/^(\w[\w-]*):\s*(.*)$/);
+		if (kvMatch) {
+			const [, key, value] = kvMatch;
+			if (value.length === 0) {
+				// Expect array items below
+				currentKey = key;
+				currentArray = [];
+			} else {
+				result[key] = value.replace(/^["']|["']$/g, "");
+			}
+		}
+	}
+
+	// Flush trailing array
+	if (currentKey && currentArray) {
+		result[currentKey] = currentArray;
+	}
+
+	return result;
+}
+
+function parseRuleFile(filePath: string): Rule | null {
+	let content: string;
+	try {
+		content = readFileSync(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+
+	const match = FRONTMATTER_RE.exec(content);
+	if (!match) return null;
+
+	const [, frontmatterRaw, body] = match;
+	const meta = parseFrontmatter(frontmatterRaw);
+
+	const condition = meta.condition;
+	if (!Array.isArray(condition) || condition.length === 0) return null;
+
+	const name = basename(filePath, ".md");
+
+	return {
+		name,
+		path: filePath,
+		content: body.trim(),
+		condition: condition as string[],
+		scope: Array.isArray(meta.scope) ? (meta.scope as string[]) : undefined,
+		globs: Array.isArray(meta.globs) ? (meta.globs as string[]) : undefined,
+	};
+}
+
+function scanDir(dir: string): Rule[] {
+	if (!existsSync(dir)) return [];
+	const rules: Rule[] = [];
+	try {
+		const files = readdirSync(dir).filter((f) => f.endsWith(".md"));
+		for (const file of files) {
+			const rule = parseRuleFile(join(dir, file));
+			if (rule) rules.push(rule);
+		}
+	} catch {
+		// Directory unreadable — skip
+	}
+	return rules;
+}
+
+/**
+ * Load all TTSR rules from global and project-local directories.
+ * Project rules override global rules with the same name.
+ */
+export function loadRules(cwd: string): Rule[] {
+	const globalDir = join(homedir(), ".gsd", "agent", "rules");
+	const projectDir = join(cwd, ".gsd", "rules");
+
+	const globalRules = scanDir(globalDir);
+	const projectRules = scanDir(projectDir);
+
+	// Merge: project rules override global by name
+	const byName = new Map<string, Rule>();
+	for (const rule of globalRules) byName.set(rule.name, rule);
+	for (const rule of projectRules) byName.set(rule.name, rule);
+
+	return Array.from(byName.values());
+}

package/src/resources/extensions/ttsr/ttsr-interrupt.md

@@ -0,0 +1,6 @@
+<system-interrupt reason="rule_violation" rule="{{name}}" path="{{path}}">
+Your output was interrupted because it violated a project rule.
+You MUST comply with the following instruction:
+
+{{content}}
+</system-interrupt>