opencode-workflow-guard 1.4.0 → 1.5.0

package/README.md

@@ -25,12 +25,15 @@ Add to your project's `opencode.json` or global `~/.config/opencode/opencode.jso
 
 *Requires OpenCode >= 1.18.* See [docs/installation.md](docs/installation.md) for full setup options and TUI companion badge configuration.
 
+For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json` as well. Do not use `opencode-workflow-guard/ui`; npm parses that unscoped slash form as GitHub shorthand rather than a package export, which can trigger Git credential prompts. The package exposes OpenCode's native `./server` and `./tui` entrypoints so the package root is sufficient in both configs.
+
 ### 2. Verification
 
 ```bash
 npm run typecheck    # Strict TypeScript check (0 errors)
 npm test             # Run 415+ unit and adversarial tests
-npm run test:all     # Run full verification suite (typecheck + unit + live e2e)
+npm run test:all     # Typecheck + unit + install/load checks
+WORKFLOW_GUARD_LIVE_E2E=1 npm run test:install # Also run model-driven OpenCode policy probes
 ```
 
 ---
@@ -41,7 +44,7 @@ The plugin enforces **24 deterministic policy rules** across four main pillars:
 
 * **Branch & History Protection:** Enforces feature-branch workflows (blocks edits/commits on `main`/`master`), hard-blocks direct or forced pushes to protected branches, enforces mergeability pre-flight checks, and requires PR changelogs / changesets.
 * **Task & Verification Discipline:** Gates file mutations on active `todowrite` tasks with subagent inheritance, blocks silent task deletion, enforces fresh test verification evidence before task completion, and journals completion claims vs. verification mismatches.
-* **Secrets & Workspace Confinement:** Confines all edits, shell redirects, and git operations within the workspace root (symlink & `../` escape safe), scrubs sensitive environment variables in agent subshells, and redacts `.env` reads with safe schema masks.
+* **Secrets & Workspace Confinement:** Confines edit tools and recognized shell/git mutations within the workspace root (including symlink and `../` escape checks), scrubs sensitive environment variables in agent subshells, and redacts `.env` reads with safe schema masks. Arbitrary executables are not OS-sandboxed; use containers or filesystem isolation when hard confinement is required.
 * **Destructive CLI & Environment Safety:** Intercepts destructive cloud/database/infrastructure commands, stops script laundering and interpreter evasion, blocks TTY hangs (`vim`, `nano`, `sudo`), and guards against dangerous package manager flags.
 
 For complete policy specifications and override rules, see [docs/policies.md](docs/policies.md).
@@ -72,6 +75,27 @@ For complete policy specifications and override rules, see [docs/policies.md](do
 | `record_review` | Record a secondary reviewer subagent's verdict evaluated against the review rubric |
 | `guard_worktree_create` | Create an isolated git worktree directory for concurrent subagent execution |
 | `guard_worktree_cleanup` | Snapshot-commit remaining changes and remove an isolated worktree directory |
+| `learning_profile` | Inspect the evidence-based local learner profile (when learning mode is enabled) |
+| `learning_checkpoint` | Rank high-value Socratic opportunities while respecting the session intervention budget |
+| `learning_record` | Persist concise evidence observed during a real learning interaction |
+| `project_memory_search` | Search current durable project knowledge in the local index |
+| `project_memory_record` | Record a durable fact, decision, constraint, or lesson with provenance |
+| `project_memory_export` | Explicitly promote selected records to repo-local human-readable JSONL |
+| `project_memory_import` | Import promoted repo-local knowledge into the local index |
+
+### Experimental Socratic Learning
+
+Learning mode is opt-in and advisory: it never blocks tool calls or weakens deterministic guardrails. Enable it by setting `WORKFLOW_GUARD_LEARNING=1` in the user environment before OpenCode starts. Project configuration cannot enable learning or expose the global profile on its own. `maxLearningInterventions` defaults to 3 per session and can be set to `0` in `.opencode/workflow-guard.json[c]` to suppress checkpoints.
+
+The learner profile is global to the local user and follows the XDG data convention: `$XDG_DATA_HOME/opencode/workflow-guard/learner-profile.json`, or `~/.local/share/opencode/workflow-guard/learner-profile.json` when `XDG_DATA_HOME` is unset. It stores distilled concept evidence, session/project provenance, and progression (`exposed` through `critique`), not conversation transcripts or numeric grades. Unobserved concepts remain unknown rather than being labeled knowledge gaps. Back up or delete this file independently from project repositories as desired.
+
+### Project Memory
+
+Project memory keeps durable working knowledge between sessions without treating conversation history as project truth. Facts, decisions, constraints, and lessons are stored in a local SQLite/FTS5 index under `$XDG_DATA_HOME/opencode/workflow-guard/project-memory/`, or `~/.local/share/opencode/workflow-guard/project-memory/` when `XDG_DATA_HOME` is unset. Git repositories are identified from their common Git directory, so linked worktrees share the same local project index.
+
+The local index is private working memory. Nothing from it is committed automatically. `project_memory_export` promotes only the explicitly selected current record IDs to `.opencode/memory/project-memory.jsonl`, a human-readable portable representation that another clone can import. The plugin adds `.opencode/memory/` to the clone-local `.git/info/exclude` by default; teams that deliberately want to version promoted knowledge can remove that exclusion or force-add the JSONL file. SQLite databases themselves should not be committed.
+
+Memory is supporting context, not authority. Superseded records are excluded from normal retrieval, recording and plugin imports reject content recognized by Workflow Guard's secret detector, and compaction injects at most eight recent current local records. Portable repository records are never injected automatically; they are available through explicit memory search after import. A local record tied to repository paths and a Git commit is omitted from compaction when those paths have committed, staged, or unstaged changes after that commit. Always prefer current repository state when it conflicts with historical memory.
 
 ---
 

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "OpenCode plugin enforcing workflow discipline through deterministic tool.execute.before hooks",
   "license": "MIT",
   "type": "module",
   "main": "src/workflow-guard.ts",
   "exports": {
     ".": "./src/workflow-guard.ts",
-    "./ui": "./src/workflow-guard-ui.ts"
+    "./server": "./src/workflow-guard.ts",
+    "./tui": "./src/workflow-guard-ui.ts"
   },
   "publishConfig": {
     "access": "public"

package/src/lib/learning.ts

@@ -0,0 +1,104 @@
+import type {
+	LearnerProfile,
+	LearningEvidence,
+	LearningOpportunity,
+	LearningStage,
+} from "./types.ts";
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const STAGE_ORDER: LearningStage[] = ["exposed", "developing", "demonstrated", "independent", "critique"];
+const TYPE_WEIGHT = { design: 0.3, debugging: 0.3, "new-concept": 0.2 } as const;
+
+export function createLearnerProfile(): LearnerProfile {
+	return { version: 1, concepts: {} };
+}
+
+export function getLearnerProfilePath(): string {
+	const dataRoot = process.env.XDG_DATA_HOME || join(homedir(), ".local", "share");
+	return join(dataRoot, "opencode", "workflow-guard", "learner-profile.json");
+}
+
+export function loadLearnerProfile(path = getLearnerProfilePath()): LearnerProfile {
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<LearnerProfile>;
+		const validConcepts = parsed.concepts && typeof parsed.concepts === "object" && !Array.isArray(parsed.concepts) &&
+			Object.values(parsed.concepts).every((concept) =>
+				concept && typeof concept === "object" &&
+				STAGE_ORDER.includes(concept.stage) &&
+				typeof concept.lastObservedAt === "number" && Number.isFinite(concept.lastObservedAt) &&
+				Array.isArray(concept.evidence),
+			);
+		if (parsed.version === 1 && validConcepts) {
+			return parsed as LearnerProfile;
+		}
+	} catch {}
+	return createLearnerProfile();
+}
+
+export function saveLearnerProfile(profile: LearnerProfile, path = getLearnerProfilePath()): void {
+	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+	const temporary = `${path}.${process.pid}.tmp`;
+	writeFileSync(temporary, JSON.stringify(profile, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+	renameSync(temporary, path);
+}
+
+export function updateLearnerProfile(
+	update: (profile: LearnerProfile) => void,
+	path = getLearnerProfilePath(),
+): LearnerProfile {
+	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+	const lockPath = `${path}.lock`;
+	let lock: number;
+	try {
+		lock = openSync(lockPath, "wx", 0o600);
+	} catch {
+		throw new Error("Learner profile is busy; evidence was not recorded. Remove a stale .lock file before retrying if its owning process has terminated.");
+	}
+	try {
+		writeFileSync(lock, String(process.pid));
+		const profile = loadLearnerProfile(path);
+		update(profile);
+		saveLearnerProfile(profile, path);
+		return profile;
+	} finally {
+		closeSync(lock);
+		try { unlinkSync(lockPath); } catch {}
+	}
+}
+
+export function recordLearningEvidence(profile: LearnerProfile, evidence: LearningEvidence): void {
+	const current = profile.concepts[evidence.concept];
+	const evidenceStage = evidence.kind === "needs-reinforcement" ? undefined : evidence.kind;
+	const stage = evidenceStage ?? current?.stage ?? "exposed";
+	const nextStage = current && STAGE_ORDER.indexOf(current.stage) > STAGE_ORDER.indexOf(stage)
+		? current.stage
+		: stage;
+
+	profile.concepts[evidence.concept] = {
+		stage: nextStage,
+		lastObservedAt: evidence.timestamp,
+		evidence: [...(current?.evidence ?? []), evidence].slice(-20),
+	};
+}
+
+export function selectLearningOpportunity(
+	profile: LearnerProfile,
+	opportunities: LearningOpportunity[],
+	options: { interventionsThisSession?: number; maxInterventionsPerSession?: number } = {},
+): LearningOpportunity | undefined {
+	const used = options.interventionsThisSession ?? 0;
+	const budget = options.maxInterventionsPerSession ?? 3;
+	if (used >= budget) return undefined;
+
+	let best: { opportunity: LearningOpportunity; score: number } | undefined;
+	for (const opportunity of opportunities) {
+		const known = profile.concepts[opportunity.concept];
+		const needsReinforcement = known?.evidence.at(-1)?.kind === "needs-reinforcement";
+		const gap = needsReinforcement ? 1 : known ? 1 - (STAGE_ORDER.indexOf(known.stage) + 1) / STAGE_ORDER.length : 1;
+		const score = opportunity.relevance * 0.4 + opportunity.consequence * 0.3 + gap * 0.3 + TYPE_WEIGHT[opportunity.type];
+		if (!best || score > best.score) best = { opportunity, score };
+	}
+	return best && best.score >= 0.75 ? best.opportunity : undefined;
+}

package/src/lib/project-memory.ts

@@ -0,0 +1,157 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { DatabaseSync } from "node:sqlite";
+import type { ProjectMemoryInput, ProjectMemoryKind, ProjectMemoryRecord, ProjectMemorySource } from "./types.ts";
+
+const KINDS = new Set<ProjectMemoryKind>(["fact", "decision", "constraint", "lesson"]);
+const SOURCES = new Set<ProjectMemorySource>(["user", "file", "git", "tool", "agent", "portable"]);
+
+export interface ProjectMemoryStore {
+	db: DatabaseSync;
+	projectId: string;
+	close(): void;
+}
+
+export function getProjectMemoryDir(): string {
+	const base = process.env.XDG_DATA_HOME || join(process.env.HOME || process.cwd(), ".local", "share");
+	return join(base, "opencode", "workflow-guard", "project-memory");
+}
+
+export function getProjectMemoryIdentity(root: string): string {
+	const result = spawnSync("git", ["-C", root, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8" });
+	const identity = result.status === 0 && result.stdout.trim() ? resolve(result.stdout.trim()) : resolve(root);
+	return createHash("sha256").update(identity).digest("hex").slice(0, 24);
+}
+
+export function ensureProjectMemoryExcluded(root: string): boolean {
+	const result = spawnSync("git", ["-C", root, "rev-parse", "--git-path", "info/exclude"], { encoding: "utf8" });
+	if (result.status !== 0 || !result.stdout.trim()) return false;
+	const path = resolve(root, result.stdout.trim());
+	let current = "";
+	try { current = readFileSync(path, "utf8"); } catch {}
+	if (current.split("\n").some((line) => line.trim() === ".opencode/memory/")) return true;
+	appendFileSync(path, `${current && !current.endsWith("\n") ? "\n" : ""}.opencode/memory/\n`);
+	return true;
+}
+
+export function isProjectMemoryFresh(memory: ProjectMemoryRecord, root: string): boolean {
+	if (!memory.commit || memory.paths.length === 0) return true;
+	if (!/^[0-9a-f]{7,64}$/i.test(memory.commit)) return false;
+	const result = spawnSync("git", ["-C", root, "diff", "--quiet", memory.commit, "--", ...memory.paths], { encoding: "utf8" });
+	if (result.status !== 0) return false;
+	const untracked = spawnSync("git", ["-C", root, "ls-files", "--others", "--exclude-standard", "--", ...memory.paths], { encoding: "utf8" });
+	return untracked.status === 0 && !untracked.stdout.trim();
+}
+
+export function openProjectMemory(projectId: string, directory = getProjectMemoryDir()): ProjectMemoryStore {
+	if (!projectId || projectId.length > 200) throw new Error("Invalid project memory identity.");
+	mkdirSync(directory, { recursive: true, mode: 0o700 });
+	const db = new DatabaseSync(join(directory, `${projectId.replace(/[^a-zA-Z0-9._-]/g, "_")}.sqlite`));
+	db.exec(`
+		PRAGMA journal_mode = WAL;
+		PRAGMA busy_timeout = 2000;
+		CREATE TABLE IF NOT EXISTS memories (
+			id TEXT PRIMARY KEY, project_id TEXT NOT NULL, kind TEXT NOT NULL, content TEXT NOT NULL,
+			source TEXT NOT NULL, created_at INTEGER NOT NULL, session_id TEXT, commit_sha TEXT,
+			paths TEXT NOT NULL, supersedes TEXT, status TEXT NOT NULL DEFAULT 'current'
+		);
+		CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(id UNINDEXED, content);
+	`);
+	return { db, projectId, close: () => db.close() };
+}
+
+function validateInput(input: ProjectMemoryInput): void {
+	if (!KINDS.has(input.kind) || !SOURCES.has(input.source)) throw new Error("Invalid project memory kind or source.");
+	if (!input.content.trim() || input.content.length > 4000) throw new Error("Project memory content must be 1-4000 characters.");
+	if ((input.paths?.length ?? 0) > 20 || input.paths?.some((path) => !path || path.length > 500 || isAbsolute(path) || path.split(/[\\/]/).includes("..") || /[\0\r\n]/.test(path))) throw new Error("Invalid project memory paths.");
+	if (input.sessionID && input.sessionID.length > 200) throw new Error("Invalid project memory session ID.");
+	if (input.commit && !/^[0-9a-f]{7,64}$/i.test(input.commit)) throw new Error("Invalid project memory commit.");
+	if (input.supersedes && (input.supersedes.length > 200 || /[\0\r\n]/.test(input.supersedes))) throw new Error("Invalid superseded project memory ID.");
+}
+
+function rowToRecord(row: Record<string, unknown>): ProjectMemoryRecord {
+	return {
+		id: String(row.id), projectId: String(row.project_id), kind: String(row.kind) as ProjectMemoryKind,
+		content: String(row.content), source: String(row.source) as ProjectMemorySource, createdAt: Number(row.created_at),
+		sessionID: row.session_id ? String(row.session_id) : undefined, commit: row.commit_sha ? String(row.commit_sha) : undefined,
+		paths: JSON.parse(String(row.paths)) as string[], supersedes: row.supersedes ? String(row.supersedes) : undefined,
+		status: String(row.status) as "current" | "superseded",
+	};
+}
+
+export function recordProjectMemory(store: ProjectMemoryStore, input: ProjectMemoryInput, id: string = randomUUID()): ProjectMemoryRecord {
+	validateInput(input);
+	const createdAt = Date.now();
+	store.db.exec("BEGIN IMMEDIATE");
+	try {
+		if (input.supersedes) store.db.prepare("UPDATE memories SET status = 'superseded' WHERE id = ? AND project_id = ?").run(input.supersedes, store.projectId);
+		store.db.prepare("INSERT INTO memories VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'current')").run(
+			id, store.projectId, input.kind, input.content.trim(), input.source, createdAt,
+			input.sessionID ?? null, input.commit ?? null, JSON.stringify(input.paths ?? []), input.supersedes ?? null,
+		);
+		store.db.prepare("INSERT INTO memories_fts(id, content) VALUES (?, ?)").run(id, input.content.trim());
+		store.db.exec("COMMIT");
+	} catch (error) {
+		store.db.exec("ROLLBACK");
+		throw error;
+	}
+	return { id, projectId: store.projectId, ...input, content: input.content.trim(), paths: input.paths ?? [], createdAt, status: "current" };
+}
+
+export function searchProjectMemory(store: ProjectMemoryStore, query: string, limit = 8): ProjectMemoryRecord[] {
+	const terms = query.match(/[\p{L}\p{N}_-]+/gu)?.slice(0, 12) ?? [];
+	if (terms.length === 0) return [];
+	const ftsQuery = terms.map((term) => `"${term.replaceAll('"', '""')}"`).join(" OR ");
+	const rows = store.db.prepare(`
+		SELECT m.* FROM memories_fts f JOIN memories m ON m.id = f.id
+		WHERE memories_fts MATCH ? AND m.project_id = ? AND m.status = 'current'
+		ORDER BY bm25(memories_fts), m.created_at DESC LIMIT ?
+	`).all(ftsQuery, store.projectId, Math.max(1, Math.min(limit, 20))) as Record<string, unknown>[];
+	return rows.map(rowToRecord);
+}
+
+export function getRecentProjectMemory(store: ProjectMemoryStore, limit = 8): ProjectMemoryRecord[] {
+	const rows = store.db.prepare("SELECT * FROM memories WHERE project_id = ? AND status = 'current' ORDER BY created_at DESC LIMIT ?")
+		.all(store.projectId, Math.max(1, Math.min(limit, 20))) as Record<string, unknown>[];
+	return rows.map(rowToRecord);
+}
+
+export function exportProjectKnowledge(store: ProjectMemoryStore, ids: string[], path: string, rejectContent: (content: string) => boolean = () => false): number {
+	const selected = ids.slice(0, 100).flatMap((id) => {
+		const row = store.db.prepare("SELECT * FROM memories WHERE id = ? AND project_id = ? AND status = 'current'").get(id, store.projectId) as Record<string, unknown> | undefined;
+		if (!row) return [];
+		const record = rowToRecord(row);
+		return rejectContent(record.content) ? [] : [record];
+	});
+	mkdirSync(dirname(path), { recursive: true });
+	const temporary = `${path}.${process.pid}.tmp`;
+	writeFileSync(temporary, selected.map((record) => JSON.stringify(record)).join("\n") + (selected.length ? "\n" : ""), { mode: 0o600 });
+	renameSync(temporary, path);
+	return selected.length;
+}
+
+export function importProjectKnowledge(store: ProjectMemoryStore, path: string, rejectContent: (content: string) => boolean = () => false): number {
+	let text: string;
+	try {
+		if (statSync(path).size > 1_000_000) return 0;
+		text = readFileSync(path, "utf8");
+	} catch { return 0; }
+	let imported = 0;
+	for (const line of text.split("\n").filter(Boolean).slice(0, 1000)) {
+		try {
+			const parsed = JSON.parse(line) as Partial<ProjectMemoryRecord>;
+			if (!parsed.id || typeof parsed.id !== "string" || parsed.id.length > 200 || /[\0\r\n]/.test(parsed.id) || typeof parsed.content !== "string" || rejectContent(parsed.content) || !KINDS.has(parsed.kind as ProjectMemoryKind)) continue;
+			const exists = store.db.prepare("SELECT 1 FROM memories WHERE id = ? AND project_id = ?").get(parsed.id, store.projectId);
+			if (exists) continue;
+			const superseded = typeof parsed.supersedes === "string"
+				? store.db.prepare("SELECT source FROM memories WHERE id = ? AND project_id = ?").get(parsed.supersedes, store.projectId) as { source?: string } | undefined
+				: undefined;
+			const supersedes = superseded?.source === "portable" ? parsed.supersedes : undefined;
+			recordProjectMemory(store, { kind: parsed.kind as ProjectMemoryKind, content: parsed.content, source: "portable", paths: Array.isArray(parsed.paths) ? parsed.paths : [], commit: parsed.commit, supersedes }, parsed.id);
+			imported++;
+		} catch {}
+	}
+	return imported;
+}

package/src/lib/state.ts

@@ -2,7 +2,7 @@ import { realpathSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { persistVerifyCache } from "./audit.ts";
-import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary } from "./verify.ts";
+import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary, getGitWorktreeFingerprint } from "./verify.ts";
 import type {
 	TodoSdkClient,
 	ProjectConfig,
@@ -149,13 +149,17 @@ export function recordReviewResult(
 	targetSessionID?: string,
 	workspace?: string,
 ): void {
+	const root = resolve(workspace ?? getWorkspaceRoot());
 	lastReview = {
 		reviewer,
 		summary: summary.slice(-4000),
 		passed,
 		timestamp: Date.now(),
 		targetSessionID,
-		workspace,
+		workspace: root,
+		commitHash: getCurrentGitCommitHash(root),
+		gitStatus: getGitStatusSummary(root),
+		worktreeFingerprint: getGitWorktreeFingerprint(root),
 	};
 	if (targetSessionID) sessionReviews.set(targetSessionID, lastReview);
 }
@@ -287,3 +291,13 @@ export function getSubagentMutationBudget(root: string): number {
 	}
 	return 50;
 }
+
+export function isLearningEnabled(root: string): boolean {
+	return process.env.WORKFLOW_GUARD_LEARNING === "1";
+}
+
+export function getLearningInterventionBudget(root: string): number {
+	const configured = getProjectConfig(root).maxLearningInterventions;
+	if (typeof configured === "number" && configured >= 0) return Math.floor(configured);
+	return 3;
+}

package/src/lib/types.ts

@@ -22,6 +22,7 @@ export interface ProjectConfig {
 	requireReview?: boolean;
 	requireDocumentation?: boolean;
 	maxSubagentMutations?: number;
+	maxLearningInterventions?: number;
 }
 
 export interface VerifyResult {
@@ -42,6 +43,9 @@ export interface ReviewResult {
 	timestamp: number;
 	targetSessionID?: string;
 	workspace?: string;
+	commitHash?: string;
+	gitStatus?: string;
+	worktreeFingerprint?: string;
 }
 
 export interface AuditEntry {
@@ -74,3 +78,61 @@ export interface ShellMutation {
 	target?: string;
 	what: string;
 }
+
+export type LearningStage = "exposed" | "developing" | "demonstrated" | "independent" | "critique";
+export type LearningEvidenceKind = LearningStage | "needs-reinforcement";
+export type LearningOpportunityType = "design" | "debugging" | "new-concept";
+
+export interface LearningEvidence {
+	concept: string;
+	kind: LearningEvidenceKind;
+	summary: string;
+	timestamp: number;
+	sessionID?: string;
+	project?: string;
+}
+
+export interface LearnerConcept {
+	stage: LearningStage;
+	lastObservedAt: number;
+	evidence: LearningEvidence[];
+}
+
+export interface LearnerProfile {
+	version: 1;
+	concepts: Record<string, LearnerConcept>;
+}
+
+export interface LearningOpportunity {
+	type: LearningOpportunityType;
+	concept: string;
+	relevance: number;
+	consequence: number;
+}
+
+export type ProjectMemoryKind = "fact" | "decision" | "constraint" | "lesson";
+export type ProjectMemorySource = "user" | "file" | "git" | "tool" | "agent" | "portable";
+
+export interface ProjectMemoryRecord {
+	id: string;
+	projectId: string;
+	kind: ProjectMemoryKind;
+	content: string;
+	source: ProjectMemorySource;
+	createdAt: number;
+	sessionID?: string;
+	commit?: string;
+	paths: string[];
+	supersedes?: string;
+	status: "current" | "superseded";
+}
+
+export interface ProjectMemoryInput {
+	kind: ProjectMemoryKind;
+	content: string;
+	source: ProjectMemorySource;
+	sessionID?: string;
+	commit?: string;
+	paths?: string[];
+	supersedes?: string;
+}

package/src/lib/utils.ts

@@ -44,9 +44,42 @@ export function decodeShellEscapes(text: string): string {
 }
 
 export function shellWords(command: string): string[] {
-	return (command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? []).map((word) =>
-		word.replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/, "$1$2"),
-	);
+	const words: string[] = [];
+	let word = "";
+	let quote: "'" | '"' | undefined;
+	let escaped = false;
+	let started = false;
+	for (const char of command) {
+		if (escaped) {
+			word += char;
+			escaped = false;
+			started = true;
+			continue;
+		}
+		if (char === "\\" && quote !== "'") {
+			escaped = true;
+			started = true;
+			continue;
+		}
+		if (char === "'" || char === '"') {
+			if (!quote) quote = char;
+			else if (quote === char) quote = undefined;
+			else word += char;
+			started = true;
+			continue;
+		}
+		if (!quote && /\s/.test(char)) {
+			if (started) words.push(word);
+			word = "";
+			started = false;
+			continue;
+		}
+		word += char;
+		started = true;
+	}
+	if (escaped) word += "\\";
+	if (started) words.push(word);
+	return words;
 }
 
 export function splitShellSegments(command: string): string[] {

package/src/lib/verify.ts

@@ -1,4 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { getCleanEnv, normalize } from "./utils.ts";
@@ -116,6 +117,43 @@ export function getGitStatusSummary(root: string): string | undefined {
 	return undefined;
 }
 
+export function getGitWorktreeFingerprint(root: string): string | undefined {
+	try {
+		// Index listing captures the exact staged/tracked content (blob hashes);
+		// a worktree-vs-index diff captures unstaged edits; untracked file
+		// contents cover files git does not yet track. Together these bind the
+		// fingerprint to file contents regardless of whether HEAD exists, so
+		// freshly initialized (commitless) repositories are covered too.
+		const staged = spawnSync("git", ["ls-files", "--stage", "-z"], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		const unstaged = spawnSync("git", ["diff", "--no-ext-diff", "--"], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		const untracked = spawnSync("git", ["ls-files", "--others", "--exclude-standard", "-z"], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (staged.status !== 0 || unstaged.status !== 0 || untracked.status !== 0) return undefined;
+		const hash = createHash("sha256").update(staged.stdout).update(unstaged.stdout);
+		for (const file of untracked.stdout.split("\0").filter(Boolean).sort()) {
+			hash.update("\0" + file + "\0");
+			try {
+				hash.update(readFileSync(join(root, file)));
+			} catch {
+				return undefined;
+			}
+		}
+		return hash.digest("hex");
+	} catch {}
+	return undefined;
+}
+
 export async function runVerify(
 	command: string,
 	root: string,