opencode-workflow-guard 1.4.1 → 1.5.0

package/README.md

@@ -32,7 +32,8 @@ For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json`
 ```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
 ```
 
 ---
@@ -74,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,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "OpenCode plugin enforcing workflow discipline through deterministic tool.execute.before hooks",
   "license": "MIT",
   "type": "module",

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

@@ -291,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 {
@@ -77,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/policies/boundary.ts

@@ -158,10 +158,11 @@ export function shellMutationIn(segment: string): ShellMutation | undefined {
 			what: `tee to '${teeTargets[0]!}'`,
 		};
 	}
-	const sedMatch = segment.match(/\bsed\s+(?:-(?:[a-zA-Z]*i[a-zA-Z]*|i\S*)\s+)+[^\s;&|]+/);
-	if (sedMatch) {
-		const tokens = sedMatch[0]!.split(/\s+/);
-		const target = tokens[tokens.length - 1];
+	const sedWords = shellWords(unwrapShellCommand(segment));
+	if (sedWords[0] === "sed" && sedWords.slice(1).some((word) => /^-(?:[a-zA-Z]*i|i\S*)$/.test(word) || /^--in-place(?:=.*)?$/.test(word))) {
+		const operands = sedWords.slice(1).filter((word) => !word.startsWith("-"));
+		const target = operands.at(-1);
+		if (!target) return undefined;
 		return { kind: "command", target, what: `sed -i on '${target}'` };
 	}
 	const transfer = filesystemTransferInfo(segment);
@@ -220,6 +221,34 @@ export function simpleFilesystemMutations(segment: string): ShellMutation[] {
 				};
 			});
 	}
+	if (command === "sed") {
+		let inPlace = false;
+		let scriptSupplied = false;
+		const targets: string[] = [];
+		for (let i = 1; i < words.length; i++) {
+			const word = words[i]!;
+			if (/^-(?:[a-zA-Z]*i|i\S*)$/.test(word) || /^--in-place(?:=.*)?$/.test(word)) {
+				inPlace = true;
+				continue;
+			}
+			if (word === "-e" || word === "--expression" || word === "-f" || word === "--file") {
+				scriptSupplied = true;
+				i++;
+				continue;
+			}
+			if (/^(?:-e|--expression=|-f|--file=)/.test(word) || word.startsWith("-")) {
+				if (/^(?:-e|--expression=)/.test(word)) scriptSupplied = true;
+				continue;
+			}
+			if (!scriptSupplied) {
+				scriptSupplied = true;
+				continue;
+			}
+			targets.push(word);
+		}
+		if (!inPlace) return [];
+		return targets.map((target) => ({ kind: "command" as const, target, what: `sed -i on '${target}'` }));
+	}
 	if (!SIMPLE_MUTATION_COMMANDS.has(command)) return [];
 	return words
 		.slice(1)

package/src/policies/destructive.ts

@@ -1,4 +1,4 @@
-import { asRecord } from "../lib/utils.ts";
+import { asRecord, shellWords, splitShellSegments } from "../lib/utils.ts";
 
 export interface LivePattern {
 	re: RegExp;
@@ -62,9 +62,48 @@ export const LIVE_MUTATION_PATTERNS: LivePattern[] = [
 	{ re: /\bmknod\s+\S+\s+p\b/, what: ["named FIFO pipe ", "creation (reverse shell backpipe)"].join("") },
 ];
 
+const KUBECTL_VALUE_GLOBALS = new Set([
+	"--as", "--as-group", "--as-uid", "--as-user-extra", "--cache-dir", "--certificate-authority", "--client-certificate", "--client-key",
+	"--cluster", "--context", "--kubeconfig", "--kuberc", "--namespace", "--password", "--profile", "--profile-output", "--request-timeout",
+	"--server", "--storage-driver-buffer-duration", "--storage-driver-db", "--storage-driver-host", "--storage-driver-password", "--storage-driver-table",
+	"--storage-driver-user", "--tls-server-name", "--token", "--user", "--username", "-n", "-s",
+]);
+const KUBECTL_BOOLEAN_GLOBALS = new Set(["--disable-compression", "--insecure-skip-tls-verify", "--match-server-version", "--storage-driver-secure", "--version", "--warnings-as-errors"]);
+
+function normalizedKubectlCommands(command: string): string {
+	const normalized: string[] = [];
+	for (const segment of splitShellSegments(command)) {
+		const words = shellWords(segment);
+		for (let i = 0; i < words.length; i++) {
+			if (words[i] !== "kubectl") continue;
+			let j = i + 1;
+			while (j < words.length) {
+				const option = words[j];
+				const name = option.split("=", 1)[0];
+				if (/^-[ns].+/.test(option) && !option.startsWith("--")) {
+					j++;
+					continue;
+				}
+				if (KUBECTL_VALUE_GLOBALS.has(name)) {
+					j += option.includes("=") ? 1 : 2;
+					continue;
+				}
+				if (KUBECTL_BOOLEAN_GLOBALS.has(name)) {
+					j++;
+					continue;
+				}
+				break;
+			}
+			if (j < words.length) normalized.push(`kubectl ${words.slice(j).join(" ")}`);
+		}
+	}
+	return normalized.join(" ; ");
+}
+
 export function liveMutationIn(command: string): string | undefined {
+	const optionNormalized = `${normalizedKubectlCommands(command)} ; ${command.replace(/\b(terraform|tofu)\s+(?:(?:-chdir(?:=\S+|\s+\S+)|-(?:no-color|version))\s+)*/g, "$1 ")}`;
 	for (const { re, what } of LIVE_MUTATION_PATTERNS) {
-		if (re.test(command)) {
+		if (re.test(command) || re.test(optionNormalized)) {
 			return what;
 		}
 	}

package/src/policies/git.ts

@@ -16,6 +16,22 @@ export const PROTECTED_BRANCHES = new Set(["main", "master"]);
 export const PUSH_TO_MAIN_RE =
 	/\bgit\s+push\b[^|;&]*(?:^|\s)\+?[\w./-]*:(?:main|master)(?![\w./-])|\bgit\s+push\b[^|;&]*(?:\s|\/)(?:main|master)(?![\w./-])/;
 
+export function hasUnsafeGitAlias(command: string): boolean {
+	return splitShellSegments(command).some((segment) => {
+		const words = unwrapShellWords(segment);
+		const gitIndex = words.findIndex((word, index) =>
+			word === "git" && words.slice(0, index).every((prefix) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(prefix)),
+		);
+		if (gitIndex < 0) return false;
+		const args = words.slice(gitIndex + 1);
+		return args.some((arg, index) =>
+			/^-calias\./i.test(arg) ||
+			/^--config-env=alias\./i.test(arg) ||
+			((arg === "-c" || arg === "--config-env") && /^alias\./i.test(args[index + 1] ?? "")),
+		);
+	});
+}
+
 export const GIT_BRANCH_CREATE_RE =
 	/\bgit\s+(?:checkout\s+-b|switch\s+(?:-c|--create))\b/;
 

package/src/policies/interpreter.ts

@@ -4,7 +4,7 @@ import { isPathOutsideWorkspace } from "./boundary.ts";
 export function extractInterpreterPayload(segment: string): string[] {
 	const payloads: string[] = [];
 	const inlineMatch = segment.match(
-		/\b(?:python3?|node|perl|ruby|osascript|bash|sh|zsh|dash|ksh)\s+(?:-[a-zA-Z]*[ce]\s+)(?:"([^"]*)"|'([^']*)')/i,
+		/\b(?:python3?|node|perl|ruby|osascript|bash|sh|zsh|dash|ksh)\s+(?:-[a-zA-Z]*[ce])\s*(?:"([^"]*)"|'([^']*)')/i,
 	);
 	if (inlineMatch?.[1] || inlineMatch?.[2]) {
 		payloads.push(inlineMatch[1] ?? inlineMatch[2] ?? "");
@@ -49,9 +49,14 @@ export function secretPathInPayload(payload: string): string | undefined {
 	return undefined;
 }
 
-const FUNCTION_TARGET_PATTERNS: RegExp[] = [
+const WRITE_TARGET_PATTERNS: RegExp[] = [
 	/\b(?:writeFileSync|writeFile|appendFile|appendFileSync|createWriteStream|unlink|unlinkSync|rmSync|rmdirSync|mkdirSync|renameSync|copyFileSync|cpSync|truncateSync)\s*\(\s*["']([^"']+)["']/g,
-	/\b(?:open|os\.remove|os\.unlink|os\.rmdir|os\.mkdir|os\.makedirs|os\.rename|shutil\.rmtree|shutil\.copy|shutil\.copy2|shutil\.move|Path)\s*\(\s*["']([^"']+)["']/g,
+	/\b(?:renameSync|copyFileSync|cpSync)\s*\(\s*["'][^"']+["']\s*,\s*["']([^"']+)["']/g,
+	/\b(?:os\.remove|os\.unlink|os\.rmdir|os\.mkdir|os\.makedirs|os\.rename|shutil\.rmtree|shutil\.copy|shutil\.copy2|shutil\.move)\s*\(\s*["']([^"']+)["']/g,
+	/\b(?:os\.rename|shutil\.copy|shutil\.copy2|shutil\.move)\s*\(\s*["'][^"']+["']\s*,\s*["']([^"']+)["']/g,
+	/\bopen\s*\(\s*["']([^"']+)["']\s*,\s*["'][^"']*[wax+][^"']*["']/g,
+	/\bPath\s*\(\s*["']([^"']+)["']\s*\)\s*\.\s*(?:write_text|write_bytes|unlink|mkdir|touch|rename|replace)\s*\(/g,
+	/\bPath\s*\(\s*["'][^"']+["']\s*\)\s*\.\s*(?:rename|replace)\s*\(\s*["']([^"']+)["']/g,
 	/[>]{1,2}\s*["']?([^\s;&"'|)]+)/g,
 ];
 
@@ -63,7 +68,7 @@ const FUNCTION_TARGET_PATTERNS: RegExp[] = [
 export function outsideWritePathInPayload(payload: string, root: string): string | undefined {
 	const candidates = new Set<string>();
 
-	for (const pattern of FUNCTION_TARGET_PATTERNS) {
+	for (const pattern of WRITE_TARGET_PATTERNS) {
 		const matches = payload.matchAll(pattern);
 		for (const m of matches) {
 			if (m[1]) candidates.add(m[1]);
@@ -78,3 +83,13 @@ export function outsideWritePathInPayload(payload: string, root: string): string
 	}
 	return undefined;
 }
+
+export function writePathsInPayload(payload: string): string[] {
+	const candidates = new Set<string>();
+	for (const pattern of WRITE_TARGET_PATTERNS) {
+		for (const match of payload.matchAll(pattern)) {
+			if (match[1]) candidates.add(match[1]);
+		}
+	}
+	return [...candidates];
+}

package/src/policies/secrets.ts

@@ -1,6 +1,7 @@
 import { realpathSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { getWorkspaceRoot } from "../lib/state.ts";
+import { shellWords, unwrapShellCommand } from "../lib/utils.ts";
 
 export const SAFE_ENV_FIXTURE_RE =
 	/\.env\.(example|sample|template|dist|schema)(\.[\w-]+)*$/i;
@@ -154,5 +155,16 @@ export function secretFileReadIn(segment: string): string | undefined {
 	}
 	const simpleMatch = segment.match(SIMPLE_FILE_READ_COMMAND_RE);
 	if (simpleMatch?.[1] && isSecretPath(simpleMatch[1])) return simpleMatch[1];
+	const words = shellWords(unwrapShellCommand(segment));
+	if (["cat", "head", "tail", "less", "more", "od", "hexdump", "strings", "base64", "xxd", "nl", "view", "nano", "vim"].includes(words[0] ?? "")) {
+		for (const operand of words.slice(1).filter((word) => !word.startsWith("-"))) {
+			if (isSecretPath(operand)) return operand;
+		}
+	}
+	if (words[0] === "dd") {
+		for (const word of words.slice(1)) {
+			if (word.startsWith("if=") && isSecretPath(word.slice(3))) return word.slice(3);
+		}
+	}
 	return undefined;
 }

package/src/workflow-guard.ts

@@ -9,9 +9,11 @@
  */
 
 import { tool, type Plugin, type PluginModule } from "@opencode-ai/plugin";
+import type { LearningEvidenceKind } from "./lib/types.ts";
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { join } from "node:path";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 export type {
@@ -23,6 +25,9 @@ export type {
 	AuditEntry,
 	GitInvocation,
 	ShellMutation,
+	LearnerProfile,
+	LearningEvidence,
+	LearningOpportunity,
 } from "./lib/types.ts";
 
 // ── State & runtime context ──────────────────────────────────────────────────
@@ -48,6 +53,8 @@ import {
 	isReviewRequired,
 	isDocumentationRequired,
 	getSubagentMutationBudget,
+	isLearningEnabled,
+	getLearningInterventionBudget,
 	recordReviewResult,
 	getLastReviewResult,
 	resetReviewState,
@@ -70,6 +77,8 @@ export {
 	isReviewRequired,
 	isDocumentationRequired,
 	getSubagentMutationBudget,
+	isLearningEnabled,
+	getLearningInterventionBudget,
 	recordReviewResult,
 	getLastReviewResult,
 	resetReviewState,
@@ -89,6 +98,48 @@ import {
 
 export { getCleanEnv };
 
+// ── Adaptive learning engine ─────────────────────────────────────────────────
+import {
+	loadLearnerProfile,
+	recordLearningEvidence,
+	selectLearningOpportunity,
+	updateLearnerProfile,
+} from "./lib/learning.ts";
+export {
+	createLearnerProfile,
+	getLearnerProfilePath,
+	loadLearnerProfile,
+	recordLearningEvidence,
+	saveLearnerProfile,
+	selectLearningOpportunity,
+	updateLearnerProfile,
+} from "./lib/learning.ts";
+
+// ── Project memory ───────────────────────────────────────────────────────────
+export {
+	getProjectMemoryDir,
+	getProjectMemoryIdentity,
+	ensureProjectMemoryExcluded,
+	isProjectMemoryFresh,
+	openProjectMemory,
+	recordProjectMemory,
+	searchProjectMemory,
+	getRecentProjectMemory,
+	exportProjectKnowledge,
+	importProjectKnowledge,
+} from "./lib/project-memory.ts";
+import {
+	exportProjectKnowledge,
+	ensureProjectMemoryExcluded,
+	getProjectMemoryIdentity,
+	getRecentProjectMemory,
+	importProjectKnowledge,
+	isProjectMemoryFresh,
+	openProjectMemory,
+	recordProjectMemory,
+	searchProjectMemory,
+} from "./lib/project-memory.ts";
+
 // ── Audit & durable verification cache ───────────────────────────────────────
 import {
 	getAuditFilePath,
@@ -170,6 +221,7 @@ import {
 	isBranchAlreadyMergedOrClosed,
 	checkMergeConflicts,
 	checkBranchBaseIsUpToDate,
+	hasUnsafeGitAlias,
 } from "./policies/git.ts";
 
 export {
@@ -215,6 +267,7 @@ import {
 	extractInterpreterPayload,
 	secretPathInPayload,
 	outsideWritePathInPayload,
+	writePathsInPayload,
 } from "./policies/interpreter.ts";
 export { extractInterpreterPayload, secretPathInPayload, outsideWritePathInPayload };
 
@@ -425,7 +478,7 @@ async function guardToolCallImpl(
 			logBlock(`[workflow-guard] blocked ${toolName}: protected path ${target}`);
 			return PROTECTED_PATH_REASON;
 		}
-		if (target && isSecretPath(target) && !allowLive) {
+		if (target && isSecretPath(target)) {
 			logBlock(`[workflow-guard] blocked ${toolName}: secret file path ${target}`);
 			return (
 				`Blocked: modifying secret file '${target}' directly is not permitted. ` +
@@ -442,7 +495,7 @@ async function guardToolCallImpl(
 					);
 					return PROTECTED_PATH_REASON;
 				}
-				if (isSecretPath(patchPath) && !allowLive) {
+				if (isSecretPath(patchPath)) {
 					logBlock(
 						`[workflow-guard] blocked apply_patch: secret file path ${patchPath}`,
 					);
@@ -502,14 +555,9 @@ async function guardToolCallImpl(
 					}
 				}
 			}
-			for (const content of extractEditContent(input)) {
-				if (isSettingsTamper(content)) {
-					logBlock(
-						`[workflow-guard] blocked ${toolName}: payload tampers with settings`,
-					);
-					return PROTECTED_PATH_REASON;
-				}
-			}
+		}
+		for (const content of extractEditContent(input)) {
+			if (isSettingsTamper(content)) return PROTECTED_PATH_REASON;
 		}
 
 		if (onProtectedBranch(currentRoot)) {
@@ -596,6 +644,9 @@ async function guardToolCallImpl(
 		}
 
 		const normalizedCommand = normalizeGitCommands(command);
+		if (hasUnsafeGitAlias(command)) {
+			return "Blocked: per-invocation Git aliases cannot be used because they can hide guarded Git operations.";
+		}
 		const gitInvocations = splitShellSegments(command)
 			.map((segment) => parseGitInvocation(segment.trim()))
 			.filter((invocation): invocation is NonNullable<ReturnType<typeof parseGitInvocation>> => invocation !== undefined);
@@ -646,8 +697,7 @@ async function guardToolCallImpl(
 		}
 
 		// ── Policy 17: secret file reads via shell ──
-		if (!allowLive) {
-			for (const segment of command.split(/[\n|;&]+/)) {
+		for (const segment of command.split(/[\n|;&]+/)) {
 				const secretFile = secretFileReadIn(segment.trim());
 				if (secretFile) {
 					logBlock(
@@ -658,7 +708,6 @@ async function guardToolCallImpl(
 						"Reference environment variables by name or inspect safe templates (e.g. .env.example) instead."
 					);
 				}
-			}
 		}
 
 		// ── Policy 18: interpreter inline evasion scanner ──
@@ -672,6 +721,21 @@ async function guardToolCallImpl(
 				);
 				return `Blocked: inline interpreter script targets file '${outsidePath}' outside workspace root (${currentRoot}). All changes must stay within the workspace.`;
 			}
+			const writePaths = writePathsInPayload(payload);
+			if (writePaths.length > 0) {
+				if (context?.agent && isReadOnlyRole(context.agent)) {
+					return `Blocked: subagent with read-only role '${context.agent}' cannot perform shell file mutations.`;
+				}
+				for (const path of writePaths) {
+					if (isProtectedPath(path)) return PROTECTED_PATH_REASON;
+				}
+				if (onProtectedBranch(currentRoot)) return branchGuardReason();
+				const todos = await effectiveTodos(context?.sessionID);
+				if (todos !== undefined && !hasActiveTodo(todos)) {
+					return "Blocked: inline interpreter file mutation with no active todo item.";
+				}
+				recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID));
+			}
 
 			if (!allowLive) {
 				const normPayload = normalizeGitCommands(normalize(payload));
@@ -682,23 +746,10 @@ async function guardToolCallImpl(
 					);
 					return `Blocked: inline interpreter script contains a ${liveCheck}. Interpreter payloads cannot smuggle live destructive commands past the guard.`;
 				}
-				if (isSettingsTamper(payload)) {
-					logBlock(
-						`[workflow-guard] blocked interpreter payload with settings tamper`,
-					);
-					return PROTECTED_PATH_REASON;
-				}
-				const secretPath = secretPathInPayload(payload);
-				if (secretPath) {
-					logBlock(
-						`[workflow-guard] blocked interpreter payload accessing secret file: ${secretPath}`,
-					);
-					return (
-						`Blocked: reading sensitive credential/secret file '${secretPath}' via inline interpreter script is not permitted. ` +
-						"Reference environment variables by name or inspect safe templates (e.g. .env.example) instead."
-					);
-				}
 			}
+			if (isSettingsTamper(payload)) return PROTECTED_PATH_REASON;
+			const secretPath = secretPathInPayload(payload);
+			if (secretPath) return `Blocked: reading sensitive credential/secret file '${secretPath}' via inline interpreter script is not permitted.`;
 		}
 
 		// ── Policies 1, 7 & 8: shell file mutations get the same gates as edits ──
@@ -784,12 +835,12 @@ async function guardToolCallImpl(
 			const isAz = /\baz\s+repos\s+pr\s+create\b/.test(normalizedCommand);
 			const prTool = isAz ? "az repos pr create" : "gh pr create";
 			const descFlag = isAz ? "--description" : "--body";
+			const preflightFailures: string[] = [];
 
 			// Policy 19: conflict-free mergeability gate before opening PR
 			const conflictCheck = checkMergeConflicts(currentRoot);
 			if (conflictCheck.hasConflicts) {
-				logBlock(`[workflow-guard] blocked ${prTool}: merge conflicts detected`);
-				return `Blocked: ${conflictCheck.reason}`;
+				preflightFailures.push(conflictCheck.reason ?? "Branch has merge conflicts with its base branch.");
 			}
 
 			// Policy 20: branch already merged/closed
@@ -797,10 +848,7 @@ async function guardToolCallImpl(
 			if (branch) {
 				const mergedStatus = isBranchAlreadyMergedOrClosed(currentRoot, branch);
 				if (mergedStatus.merged) {
-					logBlock(
-						`[workflow-guard] blocked ${prTool}: branch already merged/closed`,
-					);
-					return `Blocked: ${mergedStatus.reason}`;
+					preflightFailures.push(mergedStatus.reason ?? "Branch is already merged or closed.");
 				}
 			}
 
@@ -816,11 +864,7 @@ async function guardToolCallImpl(
 					review.gitStatus === getGitStatusSummary(currentRoot) &&
 					review.worktreeFingerprint === getGitWorktreeFingerprint(currentRoot);
 				if (!reviewMatchesContext) {
-					logBlock(`[workflow-guard] blocked ${prTool}: review approval required`);
-					return (
-						`Blocked: PR creation requires a passing review approval. ` +
-						"Invoke a secondary review subagent to record an approval using the record_review tool first."
-					);
+					preflightFailures.push("Passing secondary review approval is required; invoke a secondary review subagent and record approval with record_review.");
 				}
 			}
 
@@ -828,11 +872,7 @@ async function guardToolCallImpl(
 			if (isDocumentationRequired(currentRoot)) {
 				const hasDocChange = branchHasDocumentationChange(currentRoot);
 				if (!hasDocChange) {
-					logBlock(`[workflow-guard] blocked ${prTool}: documentation update required`);
-					return (
-						`Blocked: PR requires documentation updates (Policy 21). ` +
-						"Update README.md or relevant documentation in docs/ before opening a PR."
-					);
+					preflightFailures.push("Documentation update is required (Policy 21); update README.md or relevant documentation in docs/.");
 				}
 			}
 
@@ -843,19 +883,19 @@ async function guardToolCallImpl(
 				branchChangelog ||
 				prSegments.every((segment) => prBodyIncludesChangelog(segment));
 			if (!hasChangelog) {
-				logBlock(`[workflow-guard] blocked ${prTool}: no changelog found`);
-				return (
-					`Blocked: PR must include a changelog. Either update a ` +
-					`CHANGELOG file in this branch's diff, or include a ` +
-					`'Changelog:' section in the PR description (${descFlag}).`
-				);
+				preflightFailures.push(`Changelog is required; update a CHANGELOG file or include a 'Changelog:' section in the PR description (${descFlag}).`);
 			}
 
 			// Lockfile synchronization pre-flight gate
 			const lockCheck = checkLockfileSync(currentRoot);
 			if (lockCheck.isOutOfSync) {
-				logBlock(`[workflow-guard] blocked ${prTool}: ${lockCheck.reason}`);
-				return `Blocked: ${lockCheck.reason}`;
+				preflightFailures.push(lockCheck.reason ?? "Dependency lockfile is out of sync with its manifest.");
+			}
+
+			if (preflightFailures.length > 0) {
+				const reason = `Blocked: PR preflight failed:\n${preflightFailures.map((failure) => `- ${failure}`).join("\n")}`;
+				logBlock(`[workflow-guard] blocked ${prTool}: ${preflightFailures.length} preflight requirement(s) failed`);
+				return reason;
 			}
 		}
 
@@ -956,6 +996,18 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 	setWorkspaceRoot(effectiveRoot);
 	setSdkClient(ctx.client);
 	reloadProjectConfig(effectiveRoot);
+	const learningEnabled = isLearningEnabled(effectiveRoot);
+	const learningInterventions = new Map<string, number>();
+	const portableMemoryPath = join(effectiveRoot, ".opencode", "memory", "project-memory.jsonl");
+	let projectMemory: ReturnType<typeof openProjectMemory> | undefined;
+	try {
+		projectMemory = openProjectMemory(getProjectMemoryIdentity(effectiveRoot));
+		ensureProjectMemoryExcluded(effectiveRoot);
+		importProjectKnowledge(projectMemory, portableMemoryPath, (content) => secretIn(content) !== undefined);
+	} catch {
+		try { projectMemory?.close(); } catch {}
+		projectMemory = undefined;
+	}
 
 	try {
 		await (ctx.client as any)?.app?.log?.({
@@ -969,6 +1021,120 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 
 	return {
 		tool: {
+			project_memory_search: tool({
+				description: "Search current durable knowledge for this project. Returns concise typed records with provenance; superseded records are excluded.",
+				args: { query: tool.schema.string() },
+				execute: async (args) => projectMemory ? JSON.stringify(args.query.length <= 500 ? searchProjectMemory(projectMemory, args.query, 8) : [], null, 2) : "[workflow-guard] Project memory unavailable; core guard enforcement remains active.",
+			}),
+			project_memory_record: tool({
+				description: "Record a durable project fact, decision, constraint, or lesson when it will matter in future sessions. Do not record transient tool output, secrets, or speculative hypotheses.",
+				args: {
+					kind: tool.schema.string().describe("fact, decision, constraint, or lesson"),
+					content: tool.schema.string(),
+					paths: tool.schema.array(tool.schema.string()),
+					supersedes: tool.schema.string().optional(),
+				},
+				execute: async (args, toolContext) => {
+					if (!projectMemory) return "[workflow-guard] Project memory unavailable; core guard enforcement remains active.";
+					if (!(["fact", "decision", "constraint", "lesson"] as string[]).includes(args.kind)) return "[workflow-guard] Project memory rejected: invalid kind.";
+					const detectedSecret = secretIn(args.content);
+					if (detectedSecret) return `[workflow-guard] Project memory rejected: possible secret detected (${detectedSecret}).`;
+					const record = recordProjectMemory(projectMemory, {
+						kind: args.kind as "fact" | "decision" | "constraint" | "lesson",
+						content: args.content,
+						source: "agent",
+						sessionID: toolContext.sessionID,
+						commit: getCurrentGitCommitHash(effectiveRoot),
+						paths: args.paths,
+						supersedes: args.supersedes || undefined,
+					});
+					return JSON.stringify(record);
+				},
+			}),
+			project_memory_export: tool({
+				description: "Explicitly promote selected durable project-memory records to the human-readable repo-local .opencode/memory/project-memory.jsonl file. Nothing is exported automatically.",
+				args: { ids: tool.schema.array(tool.schema.string()) },
+				execute: async (args) => {
+					if (!projectMemory) return "[workflow-guard] Project memory unavailable; core guard enforcement remains active.";
+					if (args.ids.length > 100 || args.ids.some((id) => id.length > 200)) return "[workflow-guard] Project memory export rejected: invalid record IDs.";
+					const count = exportProjectKnowledge(projectMemory, args.ids, portableMemoryPath, (content) => secretIn(content) !== undefined);
+					return `[workflow-guard] Exported ${count} project-memory record(s) to .opencode/memory/project-memory.jsonl.`;
+				},
+			}),
+			project_memory_import: tool({
+				description: "Import the fixed repo-local .opencode/memory/project-memory.jsonl file into this project's local working-memory index.",
+				args: {},
+				execute: async () => projectMemory ? `[workflow-guard] Imported ${importProjectKnowledge(projectMemory, portableMemoryPath, (content) => secretIn(content) !== undefined)} new project-memory record(s).` : "[workflow-guard] Project memory unavailable; core guard enforcement remains active.",
+			}),
+			...(learningEnabled ? {
+				learning_profile: tool({
+					description: "Inspect the local evidence-based learner profile so teaching can build on demonstrated knowledge without assuming unobserved concepts are gaps.",
+					args: {},
+					execute: async () => JSON.stringify(loadLearnerProfile(), null, 2),
+				}),
+				learning_checkpoint: tool({
+					description: "At a high-value design decision, debugging moment, or important new concept, rank candidate Socratic learning opportunities. If one is selected, ask one concise question before continuing the work; do not turn routine syntax into a lesson.",
+					args: {
+						opportunities: tool.schema.array(tool.schema.object({
+							type: tool.schema.string().describe("design, debugging, or new-concept"),
+							concept: tool.schema.string().describe("Transferable engineering concept"),
+							relevance: tool.schema.number().describe("Current-task relevance from 0 to 1"),
+							consequence: tool.schema.number().describe("Decision consequence from 0 to 1"),
+						})),
+					},
+					execute: async (args, toolContext) => {
+						const valid = args.opportunities.slice(0, 20).filter((candidate): candidate is typeof candidate & { type: "design" | "debugging" | "new-concept" } =>
+							(candidate.type === "design" || candidate.type === "debugging" || candidate.type === "new-concept") &&
+							candidate.concept.length > 0 && candidate.concept.length <= 100 &&
+							candidate.relevance >= 0 && candidate.relevance <= 1 && candidate.consequence >= 0 && candidate.consequence <= 1,
+						);
+						const used = learningInterventions.get(toolContext.sessionID) ?? 0;
+						const selected = selectLearningOpportunity(loadLearnerProfile(), valid, {
+							interventionsThisSession: used,
+							maxInterventionsPerSession: getLearningInterventionBudget(effectiveRoot),
+						});
+						if (!selected) return JSON.stringify({ intervene: false, reason: "No opportunity selected or session learning budget reached." });
+						learningInterventions.set(toolContext.sessionID, used + 1);
+						return JSON.stringify({ intervene: true, opportunity: selected, guidance: "Ask one question, use the answer as task context, briefly reconcile if useful, then continue building." });
+					},
+				}),
+				learning_record: tool({
+					description: "Record concise evidence from a real Socratic interaction after observing the learner's reasoning. Record what was demonstrated, not a grade or an inferred deficit.",
+					args: {
+						concept: tool.schema.string(),
+						kind: tool.schema.string().describe("exposed, developing, demonstrated, independent, critique, or needs-reinforcement"),
+						summary: tool.schema.string().describe("Short factual description of observed reasoning"),
+					},
+					execute: async (args, toolContext) => {
+						const validKinds = new Set(["exposed", "developing", "demonstrated", "independent", "critique", "needs-reinforcement"]);
+						if (!validKinds.has(args.kind)) return "[workflow-guard] Learning evidence rejected: invalid evidence kind.";
+						if (args.concept.length < 1 || args.concept.length > 100 || args.summary.length < 1 || args.summary.length > 1000) {
+							return "[workflow-guard] Learning evidence rejected: concept must be 1-100 characters and summary 1-1000 characters.";
+						}
+						try {
+							updateLearnerProfile((profile) => {
+								if (!profile.concepts[args.concept] && Object.keys(profile.concepts).length >= 500) {
+									throw new Error("concept-limit");
+								}
+								recordLearningEvidence(profile, {
+									concept: args.concept,
+									kind: args.kind as LearningEvidenceKind,
+									summary: args.summary,
+									timestamp: Date.now(),
+									sessionID: toolContext.sessionID,
+									project: effectiveRoot,
+								});
+							});
+						} catch (error) {
+							if ((error as Error).message === "concept-limit") {
+								return "[workflow-guard] Learning evidence rejected: learner profile concept limit reached.";
+							}
+							throw error;
+						}
+						return `[workflow-guard] Learning evidence recorded for ${args.concept}.`;
+					},
+				}),
+			} : {}),
 			guard_status: tool({
 				description:
 					"Inspect active guardrails, current branch protection, and verification/review status.",
@@ -1289,6 +1455,13 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					);
 				}
 				contextBlocks.push(stateLines.join("\n"));
+				const projectKnowledge = (projectMemory ? getRecentProjectMemory(projectMemory, 20) : [])
+					.filter((memory) => memory.source !== "portable" && isProjectMemoryFresh(memory, effectiveRoot))
+					.slice(0, 8);
+				if (projectKnowledge.length > 0) {
+					const lines = projectKnowledge.map((memory) => `- [${memory.kind}:${memory.id.slice(0, 8)}] ${memory.content.slice(0, 300)}`);
+					contextBlocks.push(`## Project Memory\n${lines.join("\n")}\nTreat these as historical project knowledge; verify against current repository state when relevant files have changed.`);
+				}
 
 				if (Array.isArray(output?.context)) {
 					output.context.push(contextBlocks.join("\n\n"));
@@ -1366,15 +1539,15 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 			} catch {}
 		},
 
-		// Keep tool descriptions honest: todowrite's description reflects the
-		// finalization gates so the model is not surprised by verification blocks.
+		// Keep tool descriptions honest: todowrite's description reflects lifecycle
+		// and finalization gates so the model is not surprised by preventable blocks.
 		"tool.definition": async (input, output) => {
 			if (input.toolID !== "todowrite") return;
 			const description = typeof output.description === "string" ? output.description : "";
 			if (description.includes("verification evidence")) return;
 			output.description =
 				description +
-				"\n\nNote: marking every task completed triggers the workflow guard's finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply.";
+				"\n\nWorkflow Guard lifecycle: each todowrite call replaces the complete task list. Preserve every pending/in_progress task in subsequent updates until you explicitly mark it completed or cancelled; do not omit active tasks when adding new work. Marking every task completed triggers the finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply.";
 		},
 
 		event: async ({