Skip to content

Harness engineering beginner tutorial, from 0 to 1

Add code links and project cross-links to all lectures and projects

sanbuphy9c024353fabb
diff --git a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts
new file mode 100644
index 0000000..311e665
--- /dev/null
+++ b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts
@@ -0,0 +1,170 @@
+/**
+ * failure-pattern-demo.ts
+ *
+ * Simulates the 4-step failure pattern that capable agents fall into:
+ * 1. Incomplete context
+ * 2. Locally reasonable changes
+ * 3. No global verification
+ * 4. Premature completion
+ *
+ * Run: npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface StepState {
+ step: number;
+ name: string;
+ contextAvailable: string[];
+ contextMissing: string[];
+ actionTaken: string;
+ localOutcome: string;
+ globalImpact: string;
+ completed: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Simulated "model" -- a simple decision function that bases its output
+// solely on whatever context it has been given.
+// ---------------------------------------------------------------------------
+
+function modelDecide(context: string[], task: string): string {
+ const has = (s: string) => context.some((c) => c.includes(s));
+
+ // The task is to "add a search endpoint to the API".
+ // Correct answer requires knowing about auth middleware and rate limiting.
+
+ if (!has("auth")) {
+ return "Created new route handler /search without authentication checks";
+ }
+ if (!has("rate-limit")) {
+ return "Added search route with auth but forgot rate limiting";
+ }
+ if (!has("test-standards")) {
+ return "Implemented search with auth and rate-limit, but no tests";
+ }
+ return "Fully implemented search endpoint with auth, rate-limit, and tests";
+}
+
+// ---------------------------------------------------------------------------
+// Failure simulation
+// ---------------------------------------------------------------------------
+
+function simulateFailurePattern(): StepState[] {
+ const steps: StepState[] = [];
+
+ // ---- Step 1: Incomplete Context ----
+ const step1Context = ["project structure", "route definitions"];
+ const step1Missing = ["auth middleware", "rate-limiting policy", "test standards"];
+ const step1Decision = modelDecide(step1Context, "add search endpoint");
+
+ steps.push({
+ step: 1,
+ name: "Incomplete Context",
+ contextAvailable: step1Context,
+ contextMissing: step1Missing,
+ actionTaken: step1Decision,
+ localOutcome: "Looks good -- route compiles, returns data",
+ globalImpact: "Missing auth means unauthenticated access to search",
+ completed: false,
+ });
+
+ // ---- Step 2: Locally Reasonable Changes ----
+ // The agent adds auth after a hint, but still lacks other context.
+ const step2Context = [...step1Context, "auth middleware"];
+ const step2Missing = ["rate-limiting policy", "test standards"];
+ const step2Decision = modelDecide(step2Context, "add search endpoint");
+
+ steps.push({
+ step: 2,
+ name: "Locally Reasonable Changes",
+ contextAvailable: step2Context,
+ contextMissing: step2Missing,
+ actionTaken: step2Decision,
+ localOutcome: "Route has auth -- looks complete locally",
+ globalImpact: "No rate limiting means the endpoint can be abused",
+ completed: false,
+ });
+
+ // ---- Step 3: No Global Verification ----
+ const step3Context = [...step2Context, "rate-limiting policy"];
+ const step3Missing = ["test standards"];
+ const step3Decision = modelDecide(step3Context, "add search endpoint");
+
+ steps.push({
+ step: 3,
+ name: "No Global Verification",
+ contextAvailable: step3Context,
+ contextMissing: step3Missing,
+ actionTaken: step3Decision,
+ localOutcome: "Feature appears fully implemented",
+ globalImpact: "No tests -- regression risk, violates project standards",
+ completed: false,
+ });
+
+ // ---- Step 4: Premature Completion ----
+ steps.push({
+ step: 4,
+ name: "Premature Completion",
+ contextAvailable: step3Context,
+ contextMissing: step3Missing,
+ actionTaken: 'Agent outputs: "Done. Added search endpoint."',
+ localOutcome: "Agent is satisfied, task marked complete",
+ globalImpact: "Task is incomplete -- missing tests, no E2E verification",
+ completed: true,
+ });
+
+ return steps;
+}
+
+// ---------------------------------------------------------------------------
+// Comparison table
+// ---------------------------------------------------------------------------
+
+function printComparisonTable(steps: StepState[]): void {
+ console.log("\n" + "=".repeat(90));
+ console.log(" FAILURE PATTERN DEMO -- 4 Steps to a Broken Deliverable");
+ console.log("=".repeat(90));
+
+ for (const s of steps) {
+ console.log(`\n Step ${s.step}: ${s.name}`);
+ console.log(" " + "-".repeat(60));
+ console.log(` Context available : ${s.contextAvailable.join(", ")}`);
+ console.log(` Context missing : ${s.contextMissing.join(", ") || "(none)"}`);
+ console.log(` Action taken : ${s.actionTaken}`);
+ console.log(` Local outcome : ${s.localOutcome}`);
+ console.log(` Global impact : ${s.globalImpact}`);
+ console.log(` Marked complete? : ${s.completed ? "YES (premature)" : "No"}`);
+ }
+
+ // Summary comparison
+ console.log("\n" + "=".repeat(90));
+ console.log(" COMPARISON: What the agent saw vs. what was actually needed");
+ console.log("=".repeat(90));
+
+ const totalRequired = ["project structure", "route definitions", "auth middleware", "rate-limiting policy", "test standards"];
+ const finalAvailable = steps[steps.length - 1].contextAvailable;
+
+ const header = "| Criterion | Available | Missing | Status |";
+ const sep = "|------------------------|-----------|---------|----------|";
+ console.log("\n" + header);
+ console.log(sep);
+
+ for (const item of totalRequired) {
+ const avail = finalAvailable.includes(item);
+ const row = `| ${item.padEnd(23)}| ${(avail ? "Yes" : "No").padEnd(10)}| ${(!avail ? "Yes" : "").padEnd(8)}| ${(avail ? "OK" : "GAP").padEnd(9)}|`;
+ console.log(row);
+ }
+
+ const gapCount = totalRequired.filter((i) => !finalAvailable.includes(i)).length;
+ console.log("\n Result: Agent completed with " + gapCount + " of " + totalRequired.length + " context items missing.");
+ console.log(" This is the core failure pattern: each step looked reasonable in isolation.\n");
+}
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+
+printComparisonTable(simulateFailurePattern());
diff --git a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md
new file mode 100644
index 0000000..fface47
--- /dev/null
+++ b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md
@@ -0,0 +1,10 @@
+# Failure Signals Checklist
+
+Use this checklist when reviewing a weak harness run.
+
+- Did the agent ask, or infer incorrectly, how to start the app?
+- Did it create directories or abstractions that do not match the intended
+ product?
+- Did it stop after making a visible UI shell without a complete workflow?
+- Did it leave notes or artifacts that help a future run continue?
+- Could a fresh session understand what happened in under five minutes?
diff --git a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/index.md b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/index.md
new file mode 100644
index 0000000..c9885ed
--- /dev/null
+++ b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/index.md
@@ -0,0 +1,7 @@
+# Code for Lecture 01
+
+Use this folder for small examples that show:
+
+- a strong model failing in a weak environment
+- underspecified repo setup
+- missing feedback loops
diff --git a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md
new file mode 100644
index 0000000..52fac65
--- /dev/null
+++ b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md
@@ -0,0 +1,18 @@
+# Underspecified Task Example
+
+Build a desktop knowledge base app with AI question answering.
+
+Constraints:
+
+- None specified
+- No startup command given
+- No folder structure guidance
+- No data model defined
+- No explicit completion criteria
+
+Typical outcomes from this kind of prompt:
+
+- the agent invents a structure ad hoc
+- the app may compile but not start consistently
+- the UI may appear before there is any usable ingest/query path
+- the agent often stops after cosmetic success
diff --git a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md
index 3bf8ed4..dddcf8f 100644
--- a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md
+++ b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/zh/lectures/lecture-01-why-capable-agents-still-fail/)
+> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/)
+> Practice project: [Project 01. Prompt-only vs. rules-first](./../../projects/project-01-baseline-vs-minimal-harness/index.md)
+
# Lecture 01. Strong Models Don't Mean Reliable Execution
## What Problem Does This Lecture Solve?
diff --git a/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md b/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md
new file mode 100644
index 0000000..8595b9b
--- /dev/null
+++ b/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md
@@ -0,0 +1,21 @@
+# Harness Components Example
+
+For a coding agent working in a local repository:
+
+- Model:
+ the LLM itself
+
+- Harness:
+ - system prompt
+ - AGENTS.md
+ - bash tool
+ - file read/write tools
+ - git access
+ - local filesystem
+ - startup scripts
+ - test commands
+ - stop hooks
+ - lint checks
+ - evaluator loop
+
+If you change any of the above harness pieces, you change the effective agent.
diff --git a/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts b/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts
new file mode 100644
index 0000000..d856ba3
--- /dev/null
+++ b/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts
@@ -0,0 +1,180 @@
+/**
+ * harness-vs-no-harness.ts
+ *
+ * Side-by-side comparison of the same task executor running with and without
+ * a harness. The harness version adds explicit rules, verification steps,
+ * and stop conditions.
+ *
+ * Run: npx tsx docs/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types & helpers
+// ---------------------------------------------------------------------------
+
+interface TaskResult {
+ name: string;
+ passed: boolean;
+ durationMs: number;
+ issues: string[];
+}
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+// ---------------------------------------------------------------------------
+// Simulated task executor
+// ---------------------------------------------------------------------------
+
+/** A simple task that can succeed or fail depending on rules. */
+type Task = {
+ name: string;
+ requiresAuth: boolean;
+ hasTests: boolean;
+ withinScope: boolean;
+};
+
+const tasks: Task[] = [
+ { name: "Add search endpoint", requiresAuth: true, hasTests: false, withinScope: true },
+ { name: "Add delete endpoint", requiresAuth: true, hasTests: true, withinScope: true },
+ { name: "Refactor auth middleware", requiresAuth: true, hasTests: true, withinScope: false },
+ { name: "Add health check", requiresAuth: false, hasTests: true, withinScope: true },
+ { name: "Add rate limiter", requiresAuth: true, hasTests: false, withinScope: true },
+];
+
+// ---------------------------------------------------------------------------
+// Run WITHOUT harness -- just execute every task, no checks
+// ---------------------------------------------------------------------------
+
+function runWithoutHarness(taskList: Task[]): TaskResult[] {
+ const results: TaskResult[] = [];
+
+ for (const t of taskList) {
+ const start = performance.now();
+ const issues: string[] = [];
+
+ // The "agent" does the work and calls it done.
+ let passed = true;
+
+ // Problems that go undetected without a harness
+ if (t.requiresAuth && !t.hasTests) {
+ issues.push("No tests for auth-protected endpoint");
+ // Agent doesn't notice -- marks as pass anyway
+ }
+ if (!t.withinScope) {
+ issues.push("Task is outside current scope");
+ // Agent doesn't notice
+ }
+
+ const duration = performance.now() - start;
+ results.push({ name: t.name, passed, durationMs: duration, issues });
+ }
+
+ return results;
+}
+
+// ---------------------------------------------------------------------------
+// Run WITH harness -- rules, verification, stop conditions
+// ---------------------------------------------------------------------------
+
+function runWithHarness(taskList: Task[]): TaskResult[] {
+ const rules = {
+ requireTestsForAuth: true,
+ enforceScope: true,
+ };
+
+ const results: TaskResult[] = [];
+
+ for (const t of taskList) {
+ const start = performance.now();
+ const issues: string[] = [];
+ let passed = true;
+
+ // Rule: auth endpoints must have tests
+ if (rules.requireTestsForAuth && t.requiresAuth && !t.hasTests) {
+ issues.push("BLOCKED: Auth-protected endpoint missing tests");
+ passed = false;
+ }
+
+ // Rule: stay in scope
+ if (rules.enforceScope && !t.withinScope) {
+ issues.push("BLOCKED: Task outside active scope -- skipped");
+ passed = false;
+ }
+
+ // Verification: re-check after execution
+ if (passed && !t.hasTests) {
+ issues.push("WARNING: No tests exist for this change");
+ }
+
+ const duration = performance.now() - start;
+ results.push({ name: t.name, passed, durationMs: duration, issues });
+ }
+
+ return results;
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function printComparison(
+ noHarness: TaskResult[],
+ withHarness: TaskResult[]
+): void {
+ console.log("\n" + "=".repeat(80));
+ console.log(" HARNESS vs NO-HARNESS COMPARISON");
+ console.log("=".repeat(80));
+
+ const header = `| ${pad("Task", 28)}| ${pad("No-Harness", 12)}| ${pad("Issues(NH)", 35)}| ${pad("Harness", 12)}| ${pad("Issues(H)", 35)}|`;
+ const sep = `|${"-".repeat(30)}|${"-".repeat(14)}|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(37)}|`;
+
+ console.log("\n" + header);
+ console.log(sep);
+
+ for (let i = 0; i < noHarness.length; i++) {
+ const nh = noHarness[i];
+ const wh = withHarness[i];
+ const nhPass = nh.passed ? "PASS" : "FAIL";
+ const whPass = wh.passed ? "PASS" : "FAIL";
+ const nhIssue = nh.issues[0] ?? "(none)";
+ const whIssue = wh.issues[0] ?? "(none)";
+
+ console.log(
+ `| ${pad(nh.name, 28)}| ${pad(nhPass, 12)}| ${pad(nhIssue, 35)}| ${pad(whPass, 12)}| ${pad(whIssue, 35)}|`
+ );
+ }
+
+ // Metrics
+ const nhPassed = noHarness.filter((r) => r.passed).length;
+ const whPassed = withHarness.filter((r) => r.passed).length;
+ const nhIssues = noHarness.reduce((sum, r) => sum + r.issues.length, 0);
+ const whIssues = withHarness.reduce((sum, r) => sum + r.issues.length, 0);
+
+ console.log("\n" + "=".repeat(80));
+ console.log(" SUMMARY METRICS");
+ console.log("=".repeat(80));
+
+ const metricsHeader = `| ${pad("Metric", 30)}| ${pad("No Harness", 15)}| ${pad("With Harness", 15)}|`;
+ const metricsSep = `|${"-".repeat(32)}|${"-".repeat(17)}|${"-".repeat(17)}|`;
+ console.log("\n" + metricsHeader);
+ console.log(metricsSep);
+ console.log(`| ${pad("Tasks passed", 30)}| ${pad(String(nhPassed) + "/" + noHarness.length, 15)}| ${pad(String(whPassed) + "/" + withHarness.length, 15)}|`);
+ console.log(`| ${pad("Issues detected", 30)}| ${pad(String(nhIssues), 15)}| ${pad(String(whIssues), 15)}|`);
+ console.log(`| ${pad("False positives (passed but flawed)", 30)}| ${pad(String(nhPassed - truePassCount(noHarness)), 15)}| ${pad(String(whPassed - truePassCount(withHarness)), 15)}|`);
+
+ console.log("\n The harness catches problems the no-harness run silently ignores.");
+ console.log(" Without a harness, every task 'passes' even when it shouldn't.\n");
+}
+
+/** Count tasks that actually pass (have tests and are in scope). */
+function truePassCount(results: TaskResult[]): number {
+ return results.filter((r) => r.passed && r.issues.length === 0).length;
+}
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+
+printComparison(runWithoutHarness(tasks), runWithHarness(tasks));
diff --git a/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/index.md b/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/index.md
new file mode 100644
index 0000000..b16cfa3
--- /dev/null
+++ b/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/index.md
@@ -0,0 +1,8 @@
+# Code for Lecture 02
+
+Use this folder for small examples that distinguish:
+
+- model behavior
+- harness behavior
+- prompt-only setups
+- environment-backed agent setups
diff --git a/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts b/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts
new file mode 100644
index 0000000..e56cddd
--- /dev/null
+++ b/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts
@@ -0,0 +1,36 @@
+type Message = {
+ role: "user" | "assistant";
+ content: string;
+};
+
+type ToolResult = {
+ ok: boolean;
+ output: string;
+};
+
+function runTool(name: string, input: string): ToolResult {
+ if (name === "read_file") {
+ return { ok: true, output: `contents of ${input}` };
+ }
+
+ return { ok: false, output: `unknown tool: ${name}` };
+}
+
+export function minimalHarness(messages: Message[]) {
+ const nextAction = {
+ tool: "read_file",
+ input: "README.md"
+ };
+
+ const result = runTool(nextAction.tool, nextAction.input);
+
+ return {
+ messages: [
+ ...messages,
+ {
+ role: "assistant",
+ content: `Tool ${nextAction.tool} returned: ${result.output}`
+ }
+ ]
+ };
+}
diff --git a/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md
index 4b3b5e9..9f6de41 100644
--- a/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md
+++ b/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/zh/lectures/lecture-02-what-a-harness-actually-is/)
+> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/)
+> Practice project: [Project 01. Prompt-only vs. rules-first](./../../projects/project-01-baseline-vs-minimal-harness/index.md)
+
# Lecture 02. What Harness Actually Means
## What Problem Does This Lecture Solve?
diff --git a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md
new file mode 100644
index 0000000..ead6a80
--- /dev/null
+++ b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md
@@ -0,0 +1,7 @@
+# Code for Lecture 03
+
+Use this folder for examples of:
+
+- agent-readable repo structures
+- docs as system of record
+- bad vs good knowledge placement
diff --git a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt
new file mode 100644
index 0000000..45315da
--- /dev/null
+++ b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt
@@ -0,0 +1,13 @@
+AGENTS.md
+docs/
+ ARCHITECTURE.md
+ PRODUCT.md
+ RELIABILITY.md
+ references/
+ electron.md
+ sqlite.md
+ plans/
+ active/
+ completed/
+src/
+scripts/
diff --git a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts
new file mode 100644
index 0000000..46f6a62
--- /dev/null
+++ b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts
@@ -0,0 +1,189 @@
+/**
+ * repo-reader.ts
+ *
+ * Reads a directory structure and scores it on discoverability.
+ * Checks for: AGENTS.md, docs/, architecture docs, feature tracking,
+ * handoff files, and other signals of a repository that serves as the
+ * system of record.
+ *
+ * Usage:
+ * npx tsx docs/lectures/lecture-03.../code/repo-reader.ts [path]
+ * (defaults to current working directory if no path given)
+ *
+ * Run: npx tsx docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Scoring criteria
+// ---------------------------------------------------------------------------
+
+interface Check {
+ name: string;
+ description: string;
+ maxPoints: number;
+ check: (dir: string) => { points: number; found: string[]; missing: string[] };
+}
+
+const checks: Check[] = [
+ {
+ name: "AGENTS.md / CLAUDE.md",
+ description: "Agent-readable instruction file at repo root",
+ maxPoints: 15,
+ check: (dir) => {
+ const candidates = ["AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"];
+ const found = candidates.filter((f) => fs.existsSync(path.join(dir, f)));
+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : candidates };
+ },
+ },
+ {
+ name: "Documentation directory",
+ description: "Dedicated docs/ or documentation/ directory",
+ maxPoints: 10,
+ check: (dir) => {
+ const candidates = ["docs", "documentation", "doc"];
+ const found = candidates.filter((f) => {
+ const p = path.join(dir, f);
+ return fs.existsSync(p) && fs.statSync(p).isDirectory();
+ });
+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["docs/"] };
+ },
+ },
+ {
+ name: "Architecture documentation",
+ description: "Files describing system architecture",
+ maxPoints: 15,
+ check: (dir) => {
+ const patterns = [
+ "architecture.md", "ARCHITECTURE.md", "docs/architecture.md",
+ "docs/architecture/", "design.md", "DESIGN.md",
+ ];
+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));
+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["architecture.md or docs/architecture/"] };
+ },
+ },
+ {
+ name: "Feature tracking",
+ description: "Feature list or task tracking file",
+ maxPoints: 15,
+ check: (dir) => {
+ const patterns = [
+ "feature_list.json", "features.md", "FEATURES.md",
+ "docs/features.md", "tasks.json", "TODO.md",
+ ];
+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));
+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["feature_list.json or features.md"] };
+ },
+ },
+ {
+ name: "Handoff / session continuity",
+ description: "Files for multi-session continuity",
+ maxPoints: 15,
+ check: (dir) => {
+ const patterns = [
+ "HANDOFF.md", "handoff.md", "SESSION_NOTES.md",
+ "docs/handoff.md", ".handoff", "PROGRESS.md",
+ ];
+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));
+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["HANDOFF.md or PROGRESS.md"] };
+ },
+ },
+ {
+ name: "Testing structure",
+ description: "Test directory or test configuration",
+ maxPoints: 10,
+ check: (dir) => {
+ const patterns = ["test", "tests", "__tests__", "spec"];
+ const found = patterns.filter((f) => {
+ const p = path.join(dir, f);
+ return fs.existsSync(p) && fs.statSync(p).isDirectory();
+ });
+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["test/ or tests/"] };
+ },
+ },
+ {
+ name: "Configuration files",
+ description: "Project config (package.json, tsconfig, etc.)",
+ maxPoints: 10,
+ check: (dir) => {
+ const patterns = ["package.json", "tsconfig.json", "pyproject.toml", "Cargo.toml", "go.mod"];
+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));
+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["package.json or equivalent"] };
+ },
+ },
+ {
+ name: "README",
+ description: "Root README file",
+ maxPoints: 10,
+ check: (dir) => {
+ const patterns = ["README.md", "README.rst", "README.txt", "README"];
+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));
+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["README.md"] };
+ },
+ },
+];
+
+// ---------------------------------------------------------------------------
+// Report generation
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function scoreRepo(targetDir: string): void {
+ const resolved = path.resolve(targetDir);
+
+ if (!fs.existsSync(resolved)) {
+ console.error(` Error: Directory not found: ${resolved}`);
+ process.exit(1);
+ }
+
+ console.log("\n" + "=".repeat(80));
+ console.log(" REPOSITORY DISCOVERABILITY SCORE");
+ console.log("=".repeat(80));
+ console.log(` Target: ${resolved}\n`);
+
+ const header = `| ${pad("Criterion", 30)}| ${pad("Points", 8)}| ${pad("Status", 10)}| Details`;
+ const sep = `|${"-".repeat(32)}|${"-".repeat(10)}|${"-".repeat(12)}|${"-".repeat(30)}`;
+ console.log(header);
+ console.log(sep);
+
+ let totalScore = 0;
+ let maxScore = 0;
+
+ for (const check of checks) {
+ const result = check.check(resolved);
+ totalScore += result.points;
+ maxScore += check.maxPoints;
+ const status = result.points > 0 ? "PASS" : "FAIL";
+ const detail = result.found.length > 0 ? result.found.join(", ") : result.missing[0];
+
+ console.log(`| ${pad(check.name, 30)}| ${pad(result.points + "/" + check.maxPoints, 8)}| ${pad(status, 10)}| ${detail}`);
+ }
+
+ // Final score
+ console.log("\n" + "-".repeat(80));
+ console.log(` TOTAL SCORE: ${totalScore} / ${maxScore} (${Math.round((totalScore / maxScore) * 100)}%)`);
+
+ // Grade
+ const pct = totalScore / maxScore;
+ let grade: string;
+ if (pct >= 0.9) grade = "A -- Repository is a strong system of record";
+ else if (pct >= 0.7) grade = "B -- Good foundation, minor gaps";
+ else if (pct >= 0.5) grade = "C -- Partial structure, significant gaps";
+ else if (pct >= 0.3) grade = "D -- Minimal structure, hard for agents to navigate";
+ else grade = "F -- Repository lacks discoverability signals";
+
+ console.log(` GRADE: ${grade}`);
+ console.log("=".repeat(80) + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const target = process.argv[2] || process.cwd();
+scoreRepo(target);
diff --git a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md
new file mode 100644
index 0000000..e0856c5
--- /dev/null
+++ b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md
@@ -0,0 +1,11 @@
+# System of Record Checklist
+
+Can a fresh agent discover the following from the repo alone?
+
+- What product is being built?
+- What the app should do for users?
+- How the codebase is organized?
+- How the app starts?
+- How health is checked?
+- What work is currently in progress?
+- What quality standards matter?
diff --git a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
index fab97ad..b5c265d 100644
--- a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
+++ b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)
+> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/)
+> Practice project: [Project 02. Agent-readable workspace](./../../projects/project-02-agent-readable-workspace/index.md)
+
# Lecture 03. Make the Repository Your Single Source of Truth
## What Problem Does This Lecture Solve?
diff --git a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md
new file mode 100644
index 0000000..cf0ae2d
--- /dev/null
+++ b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md
@@ -0,0 +1,15 @@
+# AGENTS.md
+
+## Start Here
+
+- Read `docs/ARCHITECTURE.md`
+- Read `docs/PRODUCT.md`
+- Use `npm run dev` to start the app
+- Use `npm run check` before marking work complete
+
+## Hard Rules
+
+- Do not change Electron main/preload/renderer boundaries without reading
+ `docs/ARCHITECTURE.md`
+- Do not mark a feature complete without verification
+- Leave a clean state for the next session
diff --git a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md
new file mode 100644
index 0000000..2fb84eb
--- /dev/null
+++ b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md
@@ -0,0 +1,7 @@
+# Instruction File Anti-Patterns
+
+- Putting all repository knowledge into one file
+- Repeating the same rule in multiple places
+- Encoding obsolete rules that nobody audits
+- Writing conditional instructions so specific that they rarely apply
+- Embedding long tool manuals into the startup context
diff --git a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md
new file mode 100644
index 0000000..756b500
--- /dev/null
+++ b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md
@@ -0,0 +1,7 @@
+# Code for Lecture 04
+
+Use this folder for examples of:
+
+- monolithic instruction files
+- short entrypoints
+- progressive disclosure patterns
diff --git a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts
new file mode 100644
index 0000000..59a9632
--- /dev/null
+++ b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts
@@ -0,0 +1,209 @@
+/**
+ * split-vs-monolithic.ts
+ *
+ * Creates a monolithic instruction file (~200 lines) and then shows how
+ * splitting into 4 focused files dramatically reduces the context needed
+ * for any single query. Simulates an "agent" searching for a specific rule
+ * and measures how many lines it must read in each approach.
+ *
+ * Run: npx tsx docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Simulated monolithic instruction file (200 lines of rules)
+// ---------------------------------------------------------------------------
+
+const monolithicInstructions: { lineNumber: number; section: string; content: string }[] = [];
+
+// Section 1: Project Overview (lines 1-50)
+for (let i = 1; i <= 50; i++) {
+ monolithicInstructions.push({
+ lineNumber: i,
+ section: "Project Overview",
+ content: i === 25 ? "This project uses React 18 with TypeScript strict mode." : `Overview detail line ${i}`,
+ });
+}
+
+// Section 2: Code Style Rules (lines 51-100)
+for (let i = 51; i <= 100; i++) {
+ monolithicInstructions.push({
+ lineNumber: i,
+ section: "Code Style",
+ content:
+ i === 72
+ ? "RULE: Always use explicit return types on exported functions."
+ : i === 78
+ ? "RULE: Use const assertions for immutable arrays."
+ : `Style rule detail line ${i}`,
+ });
+}
+
+// Section 3: Testing Standards (lines 101-150)
+for (let i = 101; i <= 150; i++) {
+ monolithicInstructions.push({
+ lineNumber: i,
+ section: "Testing",
+ content:
+ i === 120
+ ? "RULE: Every new endpoint must have integration tests."
+ : i === 135
+ ? "RULE: Test files must mirror the source file structure."
+ : `Testing detail line ${i}`,
+ });
+}
+
+// Section 4: Deployment Rules (lines 151-200)
+for (let i = 151; i <= 200; i++) {
+ monolithicInstructions.push({
+ lineNumber: i,
+ section: "Deployment",
+ content:
+ i === 175
+ ? "RULE: Never deploy on Fridays. Deploy window is Tue-Thu 10am-3pm."
+ : `Deployment detail line ${i}`,
+ });
+}
+
+// ---------------------------------------------------------------------------
+// Split instruction files (4 focused files)
+// ---------------------------------------------------------------------------
+
+const splitInstructions: Record<string, { lineNumber: number; section: string; content: string }[]> = {
+ "01-project-overview.md": monolithicInstructions.filter((l) => l.section === "Project Overview"),
+ "02-code-style.md": monolithicInstructions.filter((l) => l.section === "Code Style"),
+ "03-testing.md": monolithicInstructions.filter((l) => l.section === "Testing"),
+ "04-deployment.md": monolithicInstructions.filter((l) => l.section === "Deployment"),
+};
+
+// ---------------------------------------------------------------------------
+// Simulated queries -- the agent needs to find specific rules
+// ---------------------------------------------------------------------------
+
+interface Query {
+ description: string;
+ targetRule: string;
+ relevantSection: string;
+}
+
+const queries: Query[] = [
+ {
+ description: "Find the rule about return types",
+ targetRule: "explicit return types",
+ relevantSection: "Code Style",
+ },
+ {
+ description: "Find the deployment window rule",
+ targetRule: "deploy on Fridays",
+ relevantSection: "Deployment",
+ },
+ {
+ description: "Find the integration test rule",
+ targetRule: "integration tests",
+ relevantSection: "Testing",
+ },
+ {
+ description: "Find the test file structure rule",
+ targetRule: "mirror the source file",
+ relevantSection: "Testing",
+ },
+];
+
+// ---------------------------------------------------------------------------
+// Search simulation
+// ---------------------------------------------------------------------------
+
+function searchMonolithic(query: Query): { linesRead: number; found: boolean } {
+ // Agent must scan from the top, reading each line until it finds the rule.
+ // In the worst case it reads all lines.
+ let linesRead = 0;
+ let found = false;
+
+ for (const line of monolithicInstructions) {
+ linesRead++;
+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {
+ found = true;
+ break;
+ }
+ }
+
+ return { linesRead, found };
+}
+
+function searchSplit(query: Query): { linesRead: number; found: boolean; fileAccessed: string } {
+ // Agent knows which file to look in based on the section.
+ // It only reads lines from that one file.
+ const fileMap: Record<string, string> = {
+ "Project Overview": "01-project-overview.md",
+ "Code Style": "02-code-style.md",
+ Testing: "03-testing.md",
+ Deployment: "04-deployment.md",
+ };
+
+ const targetFile = fileMap[query.relevantSection];
+ const lines = splitInstructions[targetFile];
+ let linesRead = 0;
+ let found = false;
+
+ for (const line of lines) {
+ linesRead++;
+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {
+ found = true;
+ break;
+ }
+ }
+
+ return { linesRead, found, fileAccessed: targetFile };
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ console.log("\n" + "=".repeat(90));
+ console.log(" MONOLITHIC vs SPLIT INSTRUCTION FILES");
+ console.log("=".repeat(90));
+
+ console.log("\n Monolithic file: 1 file, " + monolithicInstructions.length + " lines total");
+ console.log(" Split files: 4 files, ~" + Math.round(monolithicInstructions.length / 4) + " lines each\n");
+
+ const header = `| ${pad("Query", 42)}| ${pad("Monolithic (lines)", 20)}| ${pad("Split (lines)", 15)}| ${pad("File Accessed", 22)}| Savings`;
+ const sep = `|${"-".repeat(44)}|${"-".repeat(22)}|${"-".repeat(17)}|${"-".repeat(24)}|${"-".repeat(10)}`;
+ console.log(header);
+ console.log(sep);
+
+ let totalMono = 0;
+ let totalSplit = 0;
+
+ for (const q of queries) {
+ const mono = searchMonolithic(q);
+ const split = searchSplit(q);
+ totalMono += mono.linesRead;
+ totalSplit += split.linesRead;
+
+ const savings = Math.round(((mono.linesRead - split.linesRead) / mono.linesRead) * 100);
+ console.log(
+ `| ${pad(q.description, 42)}| ${pad(String(mono.linesRead), 20)}| ${pad(String(split.linesRead), 15)}| ${pad(split.fileAccessed, 22)}| ${savings}%`
+ );
+ }
+
+ console.log(sep);
+ const avgMono = Math.round(totalMono / queries.length);
+ const avgSplit = Math.round(totalSplit / queries.length);
+ console.log(
+ `| ${pad("AVERAGE", 42)}| ${pad(String(avgMono), 20)}| ${pad(String(avgSplit), 15)}| ${pad("(targeted file)", 22)}| ${Math.round(((avgMono - avgSplit) / avgMono) * 100)}%`
+ );
+
+ console.log("\n" + "=".repeat(90));
+ console.log(" KEY INSIGHT");
+ console.log("=".repeat(90));
+ console.log(" With a monolithic file, the agent must scan up to " + monolithicInstructions.length + " lines for every query.");
+ console.log(" With split files, it reads only the relevant " + Math.round(monolithicInstructions.length / 4) + "-line file.");
+ console.log(" This means less context window usage, fewer hallucinations, and faster execution.\n");
+}
+
+run();
diff --git a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
index 49b28ba..35ef925 100644
--- a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
+++ b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/)
+> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/)
+> Practice project: [Project 02. Agent-readable workspace](./../../projects/project-02-agent-readable-workspace/index.md)
+
# Lecture 04. Split Instructions Across Files, Not One Giant File
## What Problem Does This Lecture Solve?
diff --git a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md
new file mode 100644
index 0000000..6040ea6
--- /dev/null
+++ b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md
@@ -0,0 +1,6 @@
+# Continuity Checklist
+
+- Can a fresh agent identify recent work in under five minutes?
+- Is the current stable startup path documented?
+- Is unfinished work clearly identified?
+- Is the next best task visible without reading old chat logs?
diff --git a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md
new file mode 100644
index 0000000..636e092
--- /dev/null
+++ b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md
@@ -0,0 +1,7 @@
+# Code for Lecture 05
+
+Use this folder for examples of:
+
+- broken multi-session tasks
+- missing continuity artifacts
+- continuity recovery patterns
diff --git a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md
new file mode 100644
index 0000000..09030a3
--- /dev/null
+++ b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md
@@ -0,0 +1,17 @@
+# Session Handoff Example
+
+## Completed
+
+- Added markdown import support
+- Added a basic document list in the renderer
+
+## Broken or Unverified
+
+- Import succeeds for `.md` but fails for large `.txt` files
+- The app starts, but the detail view has not been wired up
+
+## Next Best Step
+
+- Fix `.txt` import path
+- Verify import end-to-end
+- Then add the document detail panel
diff --git a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts
new file mode 100644
index 0000000..69f9c3e
--- /dev/null
+++ b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts
@@ -0,0 +1,162 @@
+/**
+ * session-simulator.ts
+ *
+ * Simulates two sessions working on a multi-step task.
+ * Run 1: No handoff file -- Session B starts from scratch and duplicates work.
+ * Run 2: With handoff file -- Session B picks up where Session A left off.
+ *
+ * Run: npx tsx docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface TaskStep {
+ id: number;
+ name: string;
+ durationMs: number;
+}
+
+interface SessionResult {
+ session: string;
+ stepsCompleted: number;
+ totalDurationMs: number;
+ duplicatedSteps: number;
+ output: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Task definition
+// ---------------------------------------------------------------------------
+
+const taskSteps: TaskStep[] = [
+ { id: 1, name: "Read project structure", durationMs: 50 },
+ { id: 2, name: "Understand existing auth module", durationMs: 80 },
+ { id: 3, name: "Design new search endpoint", durationMs: 60 },
+ { id: 4, name: "Implement search endpoint", durationMs: 100 },
+ { id: 5, name: "Write integration tests", durationMs: 70 },
+ { id: 6, name: "Update documentation", durationMs: 40 },
+];
+
+// ---------------------------------------------------------------------------
+// Simulated session executor
+// ---------------------------------------------------------------------------
+
+/** Simulate a session doing work. */
+function runSession(
+ sessionName: string,
+ startStep: number,
+ endStep: number
+): SessionResult {
+ const output: string[] = [];
+ let totalDuration = 0;
+
+ for (let i = startStep; i <= endStep; i++) {
+ const step = taskSteps.find((s) => s.id === i)!;
+ totalDuration += step.durationMs;
+ output.push(` [${sessionName}] Step ${step.id}: ${step.name} (${step.durationMs}ms)`);
+ }
+
+ return {
+ session: sessionName,
+ stepsCompleted: endStep - startStep + 1,
+ totalDurationMs: totalDuration,
+ duplicatedSteps: 0,
+ output,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Run 1: No handoff file
+// ---------------------------------------------------------------------------
+
+function simulateNoHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {
+ // Session A does steps 1-3 before timing out
+ const sessionA = runSession("Session A", 1, 3);
+
+ // Session B has no context, starts from scratch
+ const sessionB = runSession("Session B", 1, 6);
+ sessionB.duplicatedSteps = 3; // Redoes steps 1-3 that A already did
+
+ return { sessionA, sessionB };
+}
+
+// ---------------------------------------------------------------------------
+// Run 2: With handoff file
+// ---------------------------------------------------------------------------
+
+function simulateWithHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {
+ // Session A does steps 1-3 and writes a handoff file
+ const sessionA = runSession("Session A", 1, 3);
+
+ // Session B reads handoff, starts from step 4
+ const sessionB = runSession("Session B", 4, 6);
+ sessionB.duplicatedSteps = 0;
+
+ return { sessionA, sessionB };
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function printRun(title: string, result: { sessionA: SessionResult; sessionB: SessionResult }): void {
+ console.log("\n" + "=".repeat(80));
+ console.log(` ${title}`);
+ console.log("=".repeat(80));
+
+ console.log("\n Session A output:");
+ for (const line of result.sessionA.output) {
+ console.log(line);
+ }
+
+ console.log("\n Session B output:");
+ for (const line of result.sessionB.output) {
+ console.log(line);
+ }
+
+ console.log("\n Session B notes:");
+ if (result.sessionB.duplicatedSteps > 0) {
+ console.log(` - Redid ${result.sessionB.duplicatedSteps} steps that Session A already completed`);
+ console.log(` - Wasted ${result.sessionB.totalDurationMs - (taskSteps.slice(3).reduce((s, t) => s + t.durationMs, 0))}ms on duplicate work`);
+ } else {
+ console.log(" - Read handoff file, continued from step 4");
+ console.log(" - No duplicate work performed");
+ }
+}
+
+function printComparison(): void {
+ const noHandoff = simulateNoHandoff();
+ const withHandoff = simulateWithHandoff();
+
+ printRun("RUN 1: NO HANDOFF FILE", noHandoff);
+ printRun("RUN 2: WITH HANDOFF FILE", withHandoff);
+
+ // Comparison table
+ console.log("\n" + "=".repeat(80));
+ console.log(" COMPARISON TABLE");
+ console.log("=".repeat(80) + "\n");
+
+ const header = `| ${pad("Metric", 35)}| ${pad("No Handoff", 15)}| ${pad("With Handoff", 15)}|`;
+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(17)}|`;
+ console.log(header);
+ console.log(sep);
+
+ const noTotal = noHandoff.sessionA.totalDurationMs + noHandoff.sessionB.totalDurationMs;
+ const withTotal = withHandoff.sessionA.totalDurationMs + withHandoff.sessionB.totalDurationMs;
+
+ console.log(`| ${pad("Session A steps completed", 35)}| ${pad(String(noHandoff.sessionA.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionA.stepsCompleted), 15)}|`);
+ console.log(`| ${pad("Session B steps completed", 35)}| ${pad(String(noHandoff.sessionB.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionB.stepsCompleted), 15)}|`);
+ console.log(`| ${pad("Duplicated steps", 35)}| ${pad(String(noHandoff.sessionB.duplicatedSteps), 15)}| ${pad(String(withHandoff.sessionB.duplicatedSteps), 15)}|`);
+ console.log(`| ${pad("Total work (ms)", 35)}| ${pad(String(noTotal), 15)}| ${pad(String(withTotal), 15)}|`);
+ console.log(`| ${pad("Time saved by handoff", 35)}| ${pad("-", 15)}| ${pad(String(noTotal - withTotal) + "ms", 15)}|`);
+
+ console.log("\n A handoff file eliminates duplicate work and ensures continuity across sessions.\n");
+}
+
+printComparison();
diff --git a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index 1eeb33e..29fa1cb 100644
--- a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/)
+> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/)
+> Practice project: [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)
+
# Lecture 05. Keep Context Alive Across Sessions
## What Problem Does This Lecture Solve?
diff --git a/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md
new file mode 100644
index 0000000..fd65a7f
--- /dev/null
+++ b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md
@@ -0,0 +1,8 @@
+# Code for Lecture 06
+
+Use this folder for examples of:
+
+- initializer outputs
+- init scripts
+- progress files
+- first-run scaffolding
diff --git a/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts
new file mode 100644
index 0000000..52dcd98
--- /dev/null
+++ b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts
@@ -0,0 +1,296 @@
+/**
+ * init-check.ts
+ *
+ * Programmatically checks initialization prerequisites:
+ * - Node.js version
+ * - Dependencies installed (node_modules exists)
+ * - Data directory exists
+ * - Config files present
+ *
+ * Simulates running with and without an explicit init phase,
+ * showing how missing prerequisites cause silent failures later.
+ *
+ * Run: npx tsx docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as childProcess from "node:child_process";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface CheckItem {
+ name: string;
+ category: string;
+ check: () => { pass: boolean; detail: string };
+ impactIfMissing: string;
+}
+
+interface CheckResult {
+ name: string;
+ category: string;
+ passed: boolean;
+ detail: string;
+ impactIfMissing: string;
+}
+
+// ---------------------------------------------------------------------------
+// Checks
+// ---------------------------------------------------------------------------
+
+function createChecks(targetDir: string): CheckItem[] {
+ return [
+ {
+ name: "Node.js version >= 18",
+ category: "Runtime",
+ check: () => {
+ try {
+ const version = process.version; // e.g. "v20.11.0"
+ const major = parseInt(version.replace("v", "").split(".")[0], 10);
+ return {
+ pass: major >= 18,
+ detail: `Detected: ${version} (need >= v18)`,
+ };
+ } catch {
+ return { pass: false, detail: "Could not detect Node.js version" };
+ }
+ },
+ impactIfMissing: "TypeScript features and built-in APIs unavailable",
+ },
+ {
+ name: "package.json exists",
+ category: "Config",
+ check: () => {
+ const p = path.join(targetDir, "package.json");
+ const exists = fs.existsSync(p);
+ return {
+ pass: exists,
+ detail: exists ? `Found: ${p}` : "Not found in target directory",
+ };
+ },
+ impactIfMissing: "Cannot install dependencies or run scripts",
+ },
+ {
+ name: "Dependencies installed (node_modules)",
+ category: "Dependencies",
+ check: () => {
+ const p = path.join(targetDir, "node_modules");
+ const exists = fs.existsSync(p);
+ return {
+ pass: exists,
+ detail: exists ? `Found: ${p}` : "node_modules/ not found -- run npm install",
+ };
+ },
+ impactIfMissing: "All imports fail at runtime",
+ },
+ {
+ name: "TypeScript available",
+ category: "Toolchain",
+ check: () => {
+ try {
+ const result = childProcess.execSync("npx tsc --version", {
+ encoding: "utf-8",
+ timeout: 10000,
+ stdio: ["pipe", "pipe", "pipe"],
+ }).trim();
+ return { pass: true, detail: `Detected: ${result}` };
+ } catch {
+ return { pass: false, detail: "TypeScript not available via npx" };
+ }
+ },
+ impactIfMissing: "Cannot compile TypeScript files",
+ },
+ {
+ name: "tsconfig.json exists",
+ category: "Config",
+ check: () => {
+ const p = path.join(targetDir, "tsconfig.json");
+ const exists = fs.existsSync(p);
+ return {
+ pass: exists,
+ detail: exists ? `Found: ${p}` : "Not found",
+ };
+ },
+ impactIfMissing: "TypeScript compiler uses defaults, may not match project needs",
+ },
+ {
+ name: "Source directory exists",
+ category: "Structure",
+ check: () => {
+ const candidates = ["src", "lib", "app"];
+ const found = candidates.filter((d) => {
+ const p = path.join(targetDir, d);
+ return fs.existsSync(p) && fs.statSync(p).isDirectory();
+ });
+ return {
+ pass: found.length > 0,
+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No src/ lib/ or app/ directory found",
+ };
+ },
+ impactIfMissing: "Agent cannot locate source files to modify",
+ },
+ {
+ name: "Test directory exists",
+ category: "Structure",
+ check: () => {
+ const candidates = ["test", "tests", "__tests__", "spec"];
+ const found = candidates.filter((d) => {
+ const p = path.join(targetDir, d);
+ return fs.existsSync(p) && fs.statSync(p).isDirectory();
+ });
+ return {
+ pass: found.length > 0,
+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No test directory found",
+ };
+ },
+ impactIfMissing: "Agent cannot find or run existing tests",
+ },
+ {
+ name: "Git repository initialized",
+ category: "Version Control",
+ check: () => {
+ const gitDir = path.join(targetDir, ".git");
+ const exists = fs.existsSync(gitDir);
+ return {
+ pass: exists,
+ detail: exists ? "Git repository detected" : "No .git directory found",
+ };
+ },
+ impactIfMissing: "No rollback capability, no change history",
+ },
+ ];
+}
+
+// ---------------------------------------------------------------------------
+// Simulation: with and without init phase
+// ---------------------------------------------------------------------------
+
+interface SimResult {
+ scenario: string;
+ checksRun: boolean;
+ failuresBeforeWork: number;
+ workAttempted: boolean;
+ workSucceeded: boolean;
+ timeWastedMs: number;
+}
+
+function simulateWithoutInit(): SimResult {
+ // Agent skips init, goes straight to work.
+ // Encounters failures one at a time as it hits missing prerequisites.
+ const checks = createChecks(process.cwd());
+ let failures = 0;
+ let timeWasted = 0;
+
+ for (const check of checks) {
+ const result = check.check();
+ if (!result.pass) {
+ failures++;
+ timeWasted += 200; // Agent spends time discovering each missing piece
+ }
+ }
+
+ return {
+ scenario: "NO INIT PHASE",
+ checksRun: false,
+ failuresBeforeWork: 0, // Didn't check upfront
+ workAttempted: true,
+ workSucceeded: failures === 0,
+ timeWastedMs: timeWasted,
+ };
+}
+
+function simulateWithInit(): SimResult {
+ // Agent runs init phase first, discovers all issues upfront.
+ const checks = createChecks(process.cwd());
+ let failures = 0;
+
+ for (const check of checks) {
+ if (!check.check().pass) {
+ failures++;
+ }
+ }
+
+ return {
+ scenario: "WITH INIT PHASE",
+ checksRun: true,
+ failuresBeforeWork: failures,
+ workAttempted: failures === 0,
+ workSucceeded: failures === 0,
+ timeWastedMs: 0,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ const targetDir = process.cwd();
+ console.log("\n" + "=".repeat(80));
+ console.log(" INITIALIZATION PREREQUISITE CHECK");
+ console.log("=".repeat(80));
+ console.log(` Target: ${targetDir}\n`);
+
+ const checks = createChecks(targetDir);
+ const results: CheckResult[] = checks.map((c) => {
+ const r = c.check();
+ return {
+ name: c.name,
+ category: c.category,
+ passed: r.pass,
+ detail: r.detail,
+ impactIfMissing: c.impactIfMissing,
+ };
+ });
+
+ // Detailed report
+ const header = `| ${pad("Check", 35)}| ${pad("Category", 12)}| ${pad("Status", 6)}| Detail`;
+ const sep = `|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(8)}|${"-".repeat(40)}`;
+ console.log(header);
+ console.log(sep);
+
+ for (const r of results) {
+ const status = r.passed ? "PASS" : "FAIL";
+ console.log(`| ${pad(r.name, 35)}| ${pad(r.category, 12)}| ${pad(status, 6)}| ${r.detail}`);
+ }
+
+ const passCount = results.filter((r) => r.passed).length;
+ const failCount = results.filter((r) => !r.passed).length;
+
+ console.log("\n" + "-".repeat(80));
+ console.log(` Results: ${passCount} passed, ${failCount} failed out of ${results.length} checks`);
+
+ if (failCount > 0) {
+ console.log("\n FAILED CHECKS -- Impact if not resolved:");
+ for (const r of results.filter((r) => !r.passed)) {
+ console.log(` - ${r.name}: ${r.impactIfMissing}`);
+ }
+ }
+
+ // Comparison: with vs without init
+ const noInit = simulateWithoutInit();
+ const withInit = simulateWithInit();
+
+ console.log("\n" + "=".repeat(80));
+ console.log(" INIT PHASE COMPARISON");
+ console.log("=".repeat(80) + "\n");
+
+ const cHeader = `| ${pad("Metric", 35)}| ${pad("No Init Phase", 18)}| ${pad("With Init Phase", 18)}|`;
+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;
+ console.log(cHeader);
+ console.log(cSep);
+ console.log(`| ${pad("Prerequisites checked upfront", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);
+ console.log(`| ${pad("Work attempted despite issues", 35)}| ${pad(String(noInit.workAttempted), 18)}| ${pad(String(withInit.workAttempted), 18)}|`);
+ console.log(`| ${pad("Time wasted discovering issues late", 35)}| ${pad(noInit.timeWastedMs + "ms", 18)}| ${pad(withInit.timeWastedMs + "ms", 18)}|`);
+ console.log(`| ${pad("Work succeeded", 35)}| ${pad(String(noInit.workSucceeded), 18)}| ${pad(String(withInit.workSucceeded), 18)}|`);
+
+ console.log("\n An explicit init phase catches problems before they waste time.\n");
+}
+
+run();
diff --git a/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh
new file mode 100644
index 0000000..2c6e1b0
--- /dev/null
+++ b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "[init] installing dependencies"
+npm install
+
+echo "[init] starting the docs site is optional"
+echo "[init] use npm run docs:dev for course docs"
+
+echo "[init] project-specific startup would go here"
diff --git a/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md
new file mode 100644
index 0000000..58484c4
--- /dev/null
+++ b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md
@@ -0,0 +1,7 @@
+# Initializer Output Checklist
+
+- Is there a canonical startup command?
+- Is there a canonical verification command?
+- Is there a first progress artifact?
+- Is there a stable first commit?
+- Is there a visible feature surface for later runs?
diff --git a/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index 54ef801..840ce36 100644
--- a/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/)
+> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)
+> Practice project: [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)
+
# Lecture 06. Initialize Before Every Agent Session
## What Problem Does This Lecture Solve?
diff --git a/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md
new file mode 100644
index 0000000..cfa201b
--- /dev/null
+++ b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md
@@ -0,0 +1,8 @@
+# Code for Lecture 07
+
+Use this folder for examples of:
+
+- one-shot failures
+- oversized task prompts
+- incremental task shaping
+- structured feature surfaces
diff --git a/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md
new file mode 100644
index 0000000..b97cab0
--- /dev/null
+++ b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md
@@ -0,0 +1,6 @@
+# Next Task Template
+
+- Current highest-priority feature:
+- Why this feature is next:
+- What counts as passing:
+- What must not be changed during this step:
diff --git a/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md
new file mode 100644
index 0000000..1f52484
--- /dev/null
+++ b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md
@@ -0,0 +1,17 @@
+# Scope Surface Example
+
+Task:
+
+- Add indexing to the Electron knowledge app
+
+Bad scope shape:
+
+- “Implement indexing”
+
+Better scope shape:
+
+- Parse imported documents
+- Split documents into chunks
+- Persist chunk metadata
+- Expose indexing status in the UI
+- Add a reindex action
diff --git a/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts
new file mode 100644
index 0000000..c587a1d
--- /dev/null
+++ b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts
@@ -0,0 +1,151 @@
+/**
+ * scope-tracker.ts
+ *
+ * Reads a feature list and a change log. Enforces single-active-feature
+ * policy. Given a log of changes, flags any changes outside the active
+ * feature scope. Demonstrates how scope drift happens and how the tracker
+ * catches it.
+ *
+ * Run: npx tsx docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface Feature {
+ id: string;
+ name: string;
+ status: "active" | "pending" | "done";
+}
+
+interface ChangeLogEntry {
+ step: number;
+ file: string;
+ description: string;
+ featureId: string; // The feature this change claims to belong to
+}
+
+// ---------------------------------------------------------------------------
+// Sample data
+// ---------------------------------------------------------------------------
+
+const features: Feature[] = [
+ { id: "F-001", name: "Search endpoint", status: "active" },
+ { id: "F-002", name: "Delete endpoint", status: "pending" },
+ { id: "F-003", name: "Rate limiting", status: "pending" },
+ { id: "F-004", name: "User dashboard", status: "pending" },
+];
+
+// A realistic change log where the agent gradually drifts from the active feature
+const changeLog: ChangeLogEntry[] = [
+ { step: 1, file: "src/routes/search.ts", description: "Add search route handler", featureId: "F-001" },
+ { step: 2, file: "src/routes/search.ts", description: "Add query parameter validation", featureId: "F-001" },
+ { step: 3, file: "src/routes/search.ts", description: "Add search results pagination", featureId: "F-001" },
+ { step: 4, file: "src/routes/delete.ts", description: "Add delete route handler", featureId: "F-002" }, // DRIFT
+ { step: 5, file: "src/middleware/rate-limit.ts", description: "Add rate limiter middleware", featureId: "F-003" }, // DRIFT
+ { step: 6, file: "src/routes/search.ts", description: "Integrate rate limiter into search", featureId: "F-001" },
+ { step: 7, file: "src/dashboard/ui.tsx", description: "Create dashboard layout component", featureId: "F-004" }, // DRIFT
+ { step: 8, file: "src/routes/search.ts", description: "Add search response formatting", featureId: "F-001" },
+ { step: 9, file: "src/routes/delete.ts", description: "Add delete confirmation logic", featureId: "F-002" }, // DRIFT
+ { step: 10, file: "src/routes/search.ts", description: "Add search tests", featureId: "F-001" },
+];
+
+// ---------------------------------------------------------------------------
+// Scope tracker
+// ---------------------------------------------------------------------------
+
+interface ScopeCheckResult {
+ step: number;
+ file: string;
+ description: string;
+ featureId: string;
+ inScope: boolean;
+ activeFeature: string;
+}
+
+function trackScope(
+ featureList: Feature[],
+ changes: ChangeLogEntry[]
+): ScopeCheckResult[] {
+ const activeFeatures = featureList.filter((f) => f.status === "active");
+ const activeIds = new Set(activeFeatures.map((f) => f.id));
+ const activeNames = activeFeatures.map((f) => f.name).join(", ");
+
+ return changes.map((change) => ({
+ step: change.step,
+ file: change.file,
+ description: change.description,
+ featureId: change.featureId,
+ inScope: activeIds.has(change.featureId),
+ activeFeature: activeNames,
+ }));
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ const results = trackScope(features, changeLog);
+
+ console.log("\n" + "=".repeat(100));
+ console.log(" SCOPE TRACKER -- Single Active Feature Enforcement");
+ console.log("=".repeat(100));
+
+ console.log("\n Active feature: " + features.filter((f) => f.status === "active").map((f) => `${f.id} (${f.name})`).join(", "));
+ console.log(" Pending features: " + features.filter((f) => f.status === "pending").map((f) => `${f.id} (${f.name})`).join(", "));
+
+ // Detailed change log
+ console.log("\n" + "-".repeat(100));
+ const header = `| ${pad("Step", 5)}| ${pad("File", 35)}| ${pad("Description", 40)}| ${pad("Feature", 8)}| ${pad("In Scope", 10)}|`;
+ const sep = `|${"-".repeat(7)}|${"-".repeat(37)}|${"-".repeat(42)}|${"-".repeat(10)}|${"-".repeat(12)}|`;
+ console.log(header);
+ console.log(sep);
+
+ let inScopeCount = 0;
+ let driftCount = 0;
+
+ for (const r of results) {
+ const scopeLabel = r.inScope ? "OK" : "DRIFT";
+ if (r.inScope) inScopeCount++;
+ else driftCount++;
+
+ const marker = r.inScope ? " " : ">>";
+ console.log(`${marker}| ${pad(String(r.step), 5)}| ${pad(r.file, 35)}| ${pad(r.description, 40)}| ${pad(r.featureId, 8)}| ${pad(scopeLabel, 10)}|`);
+ }
+
+ // Summary
+ console.log("\n" + "=".repeat(100));
+ console.log(" SCOPE DRIFT SUMMARY");
+ console.log("=".repeat(100) + "\n");
+
+ const sHeader = `| ${pad("Metric", 40)}| ${pad("Value", 15)}|`;
+ const sSep = `|${"-".repeat(42)}|${"-".repeat(17)}|`;
+ console.log(sHeader);
+ console.log(sSep);
+ console.log(`| ${pad("Total changes", 40)}| ${pad(String(results.length), 15)}|`);
+ console.log(`| ${pad("Changes within active scope (F-001)", 40)}| ${pad(String(inScopeCount), 15)}|`);
+ console.log(`| ${pad("Changes outside active scope (DRIFT)", 40)}| ${pad(String(driftCount), 15)}|`);
+ console.log(`| ${pad("Features touched (total)", 40)}| ${pad(String(new Set(results.map((r) => r.featureId)).size), 15)}|`);
+
+ // Drift detail
+ const driftFeatures = [...new Set(results.filter((r) => !r.inScope).map((r) => r.featureId))];
+ if (driftFeatures.length > 0) {
+ console.log("\n DRIFTED FEATURES:");
+ for (const fid of driftFeatures) {
+ const feat = features.find((f) => f.id === fid);
+ const driftChanges = results.filter((r) => r.featureId === fid);
+ console.log(` ${fid} (${feat?.name}): ${driftChanges.length} unauthorized changes`);
+ }
+ }
+
+ console.log("\n Without a scope tracker, the agent silently worked on " + driftFeatures.length + " unrelated features.");
+ console.log(" The tracker catches this drift and enforces the single-active-feature policy.\n");
+}
+
+run();
diff --git a/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index 9ab7e4b..bde8876 100644
--- a/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/)
+> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/)
+> Practice project: [Project 04. Runtime feedback and scope control](./../../projects/project-04-incremental-indexing/index.md)
+
# Lecture 07. Draw Clear Task Boundaries for Agents
## What Problem Does This Lecture Solve?
diff --git a/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts
new file mode 100644
index 0000000..52d6a2b
--- /dev/null
+++ b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts
@@ -0,0 +1,218 @@
+/**
+ * feature-list-validator.ts
+ *
+ * Reads a feature_list.json, validates its schema, and checks for features
+ * marked "pass" without verification evidence. Outputs a structured report.
+ * Can run against any project directory that has a feature_list.json.
+ *
+ * Usage:
+ * npx tsx docs/lectures/lecture-08.../code/feature-list-validator.ts [path-to-dir]
+ * (defaults to the directory containing this script)
+ *
+ * Run: npx tsx docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface FeatureEntry {
+ id?: string;
+ category?: string;
+ description?: string;
+ verification?: string[];
+ passes?: boolean;
+ // Allow unknown fields for flexibility
+ [key: string]: unknown;
+}
+
+interface ValidationResult {
+ featureId: string;
+ schemaValid: boolean;
+ schemaErrors: string[];
+ hasVerification: boolean;
+ markedPassWithoutEvidence: boolean;
+ passes: boolean;
+ verificationCount: number;
+}
+
+// ---------------------------------------------------------------------------
+// Schema validation
+// ---------------------------------------------------------------------------
+
+function validateSchema(entry: FeatureEntry, index: number): string[] {
+ const errors: string[] = [];
+ const label = entry.id ?? `entry ${index + 1}`;
+
+ if (!entry.id || typeof entry.id !== "string") {
+ errors.push(`[${label}] Missing or invalid 'id' field`);
+ }
+ if (!entry.category || typeof entry.category !== "string") {
+ errors.push(`[${label}] Missing or invalid 'category' field`);
+ }
+ if (!entry.description || typeof entry.description !== "string") {
+ errors.push(`[${label}] Missing or invalid 'description' field`);
+ }
+ if (entry.verification !== undefined && !Array.isArray(entry.verification)) {
+ errors.push(`[${label}] 'verification' must be an array if present`);
+ }
+ if (entry.passes !== undefined && typeof entry.passes !== "boolean") {
+ errors.push(`[${label}] 'passes' must be a boolean if present`);
+ }
+
+ return errors;
+}
+
+// ---------------------------------------------------------------------------
+// Evidence validation
+// ---------------------------------------------------------------------------
+
+function checkEvidence(entry: FeatureEntry): {
+ hasVerification: boolean;
+ markedPassWithoutEvidence: boolean;
+} {
+ const hasVerification = Array.isArray(entry.verification) && entry.verification.length > 0;
+ const markedPassWithoutEvidence = entry.passes === true && !hasVerification;
+
+ return { hasVerification, markedPassWithoutEvidence };
+}
+
+// ---------------------------------------------------------------------------
+// Process feature list
+// ---------------------------------------------------------------------------
+
+function processFeatureList(entries: FeatureEntry[]): ValidationResult[] {
+ return entries.map((entry, index) => {
+ const schemaErrors = validateSchema(entry, index);
+ const evidence = checkEvidence(entry);
+
+ return {
+ featureId: (entry.id as string) ?? `entry-${index + 1}`,
+ schemaValid: schemaErrors.length === 0,
+ schemaErrors,
+ hasVerification: evidence.hasVerification,
+ markedPassWithoutEvidence: evidence.markedPassWithoutEvidence,
+ passes: entry.passes === true,
+ verificationCount: Array.isArray(entry.verification) ? entry.verification.length : 0,
+ };
+ });
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ // Resolve target directory
+ const scriptDir = path.dirname(new URL(import.meta.url).pathname);
+ const targetDir = process.argv[2]
+ ? path.resolve(process.argv[2])
+ : scriptDir;
+
+ const filePath = path.join(targetDir, "feature_list.json");
+
+ console.log("\n" + "=".repeat(90));
+ console.log(" FEATURE LIST VALIDATOR");
+ console.log("=".repeat(90));
+ console.log(` Reading: ${filePath}\n`);
+
+ if (!fs.existsSync(filePath)) {
+ console.error(` ERROR: feature_list.json not found at ${filePath}`);
+ console.error(" Usage: npx tsx feature-list-validator.ts [path-to-directory-containing-feature_list.json]\n");
+ process.exit(1);
+ }
+
+ let entries: FeatureEntry[];
+ try {
+ const raw = fs.readFileSync(filePath, "utf-8");
+ entries = JSON.parse(raw);
+ } catch (err) {
+ console.error(` ERROR: Could not parse feature_list.json: ${err}`);
+ process.exit(1);
+ }
+
+ if (!Array.isArray(entries)) {
+ console.error(" ERROR: feature_list.json must contain a JSON array at the top level.");
+ process.exit(1);
+ }
+
+ // For demo purposes, also validate an extended test set
+ const demoEntries: FeatureEntry[] = [
+ ...entries,
+ {
+ id: "qna-002",
+ category: "import",
+ description: "User can import a PDF document.",
+ verification: ["Upload a PDF file", "Verify it appears in the document list"],
+ passes: true,
+ },
+ {
+ id: "qna-003",
+ category: "grounded_qa",
+ description: "System hallucination rate is below 5%.",
+ verification: [], // Empty -- no evidence
+ passes: true, // Marked as pass WITHOUT evidence
+ },
+ {
+ id: "missing-fields",
+ // Missing 'category' and 'description'
+ passes: true,
+ } as FeatureEntry,
+ ];
+
+ const results = processFeatureList(demoEntries);
+
+ // Print report
+ const header = `| ${pad("Feature ID", 14)}| ${pad("Schema", 8)}| ${pad("Passes", 7)}| ${pad("Verifications", 14)}| ${pad("Evidence?", 12)}| Notes`;
+ const sep = `|${"-".repeat(16)}|${"-".repeat(10)}|${"-".repeat(9)}|${"-".repeat(16)}|${"-".repeat(14)}|${"-".repeat(30)}`;
+ console.log(header);
+ console.log(sep);
+
+ for (const r of results) {
+ const schemaLabel = r.schemaValid ? "OK" : "INVALID";
+ const passesLabel = r.passes ? "PASS" : "FAIL";
+ const evidenceLabel = r.hasVerification ? "Present" : "MISSING";
+ const notes = r.markedPassWithoutEvidence
+ ? "FLAGGED: passes without evidence!"
+ : r.schemaErrors.length > 0
+ ? r.schemaErrors[0]
+ : "";
+
+ const marker = r.markedPassWithoutEvidence ? ">>" : r.schemaValid ? " " : "!!";
+ console.log(
+ `${marker}| ${pad(r.featureId, 14)}| ${pad(schemaLabel, 8)}| ${pad(passesLabel, 7)}| ${pad(String(r.verificationCount), 14)}| ${pad(evidenceLabel, 12)}| ${notes}`
+ );
+ }
+
+ // Summary
+ const total = results.length;
+ const schemaOk = results.filter((r) => r.schemaValid).length;
+ const passing = results.filter((r) => r.passes).length;
+ const flagged = results.filter((r) => r.markedPassWithoutEvidence).length;
+ const withEvidence = results.filter((r) => r.hasVerification).length;
+
+ console.log("\n" + "-".repeat(90));
+ console.log(" SUMMARY");
+ console.log("-".repeat(90));
+ console.log(` Total features: ${total}`);
+ console.log(` Schema valid: ${schemaOk}/${total}`);
+ console.log(` Marked as passing: ${passing}/${total}`);
+ console.log(` With verification evidence: ${withEvidence}/${total}`);
+ console.log(` Flagged (pass without evidence): ${flagged}`);
+
+ if (flagged > 0) {
+ console.log(`\n WARNING: ${flagged} feature(s) marked as "pass" without any verification evidence.`);
+ console.log(" These features need verification before they can be trusted.\n");
+ } else {
+ console.log("\n All passing features have verification evidence. Feature list is healthy.\n");
+ }
+}
+
+run();
diff --git a/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json
new file mode 100644
index 0000000..8b973e3
--- /dev/null
+++ b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json
@@ -0,0 +1,15 @@
+[
+ {
+ "id": "qna-001",
+ "category": "grounded_qa",
+ "description": "User can ask a question about an imported document and receive an answer with visible citations.",
+ "verification": [
+ "Import a markdown document",
+ "Open the Q&A panel",
+ "Ask a question about known content",
+ "Verify the answer is returned",
+ "Verify one or more citations are displayed"
+ ],
+ "passes": false
+ }
+]
diff --git a/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md
new file mode 100644
index 0000000..ac4215f
--- /dev/null
+++ b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md
@@ -0,0 +1,8 @@
+# Code for Lecture 08
+
+Use this folder for examples of:
+
+- pass-state gating
+- end-to-end verification
+- weak vs strong completion criteria
+- evaluator-loop examples
diff --git a/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md
new file mode 100644
index 0000000..c922f64
--- /dev/null
+++ b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md
@@ -0,0 +1,8 @@
+# Pass Gate Policy
+
+A feature may only move from `passes: false` to `passes: true` when:
+
+- the expected workflow has been exercised
+- the evidence of success is recorded
+- no blocking error is present in the tested path
+- the implementation does not leave the app in a broken or ambiguous state
diff --git a/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 25d4269..1191526 100644
--- a/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/)
+> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)
+> Practice project: [Project 04. Runtime feedback and scope control](./../../projects/project-04-incremental-indexing/index.md)
+
# Lecture 08. Use Feature Lists to Constrain What the Agent Does
## What Problem Does This Lecture Solve?
diff --git a/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md
new file mode 100644
index 0000000..5a592e3
--- /dev/null
+++ b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md
@@ -0,0 +1,6 @@
+# Clean State Checklist
+
+- App starts without manual repair
+- Current progress is recorded
+- No half-finished import or indexing step remains undocumented
+- The next agent can run the standard startup and verification path immediately
diff --git a/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md
new file mode 100644
index 0000000..e6ea6fc
--- /dev/null
+++ b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md
@@ -0,0 +1,8 @@
+# Code for Lecture 09
+
+Use this folder for examples of:
+
+- logs as feedback
+- runtime-state visibility
+- clean-state checks
+- recovery examples
diff --git a/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts
new file mode 100644
index 0000000..fad1a3b
--- /dev/null
+++ b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts
@@ -0,0 +1,241 @@
+/**
+ * victory-detector.ts
+ *
+ * Simulates an agent that claims task completion, then checks the claimed
+ * state against actual verification. Outputs: claimed vs actual, highlighting
+ * gaps between what the agent said and what's really true.
+ *
+ * Run: npx tsx docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface Task {
+ name: string;
+ claimedComplete: boolean;
+ checks: VerificationCheck[];
+}
+
+interface VerificationCheck {
+ description: string;
+ claimed: boolean; // What the agent says
+ actual: boolean; // What is actually true
+ severity: "critical" | "warning";
+}
+
+// ---------------------------------------------------------------------------
+// Simulated tasks with claimed vs actual states
+// ---------------------------------------------------------------------------
+
+const tasks: Task[] = [
+ {
+ name: "Add search endpoint",
+ claimedComplete: true,
+ checks: [
+ {
+ description: "Route handler exists",
+ claimed: true,
+ actual: true,
+ severity: "critical",
+ },
+ {
+ description: "Authentication middleware applied",
+ claimed: true,
+ actual: false, // Agent forgot auth
+ severity: "critical",
+ },
+ {
+ description: "Input validation added",
+ claimed: true,
+ actual: true,
+ severity: "critical",
+ },
+ {
+ description: "Unit tests written",
+ claimed: true,
+ actual: false, // Agent skipped tests
+ severity: "critical",
+ },
+ {
+ description: "Integration tests pass",
+ claimed: true,
+ actual: false, // No tests to run
+ severity: "critical",
+ },
+ {
+ description: "Documentation updated",
+ claimed: true,
+ actual: false, // Agent skipped docs
+ severity: "warning",
+ },
+ ],
+ },
+ {
+ name: "Fix pagination bug",
+ claimedComplete: true,
+ checks: [
+ {
+ description: "Bug reproduction case confirmed",
+ claimed: true,
+ actual: true,
+ severity: "critical",
+ },
+ {
+ description: "Root cause identified",
+ claimed: true,
+ actual: true,
+ severity: "critical",
+ },
+ {
+ description: "Fix applied",
+ claimed: true,
+ actual: true,
+ severity: "critical",
+ },
+ {
+ description: "Edge cases tested",
+ claimed: true,
+ actual: false, // Only happy path tested
+ severity: "warning",
+ },
+ {
+ description: "Regression tests added",
+ claimed: true,
+ actual: false,
+ severity: "critical",
+ },
+ ],
+ },
+ {
+ name: "Refactor auth module",
+ claimedComplete: true,
+ checks: [
+ {
+ description: "Old code removed",
+ claimed: true,
+ actual: false, // Old code still present
+ severity: "warning",
+ },
+ {
+ description: "All existing tests still pass",
+ claimed: true,
+ actual: false, // Two tests broke
+ severity: "critical",
+ },
+ {
+ description: "New auth flow works",
+ claimed: true,
+ actual: true,
+ severity: "critical",
+ },
+ {
+ description: "Migration guide written",
+ claimed: true,
+ actual: false,
+ severity: "warning",
+ },
+ ],
+ },
+];
+
+// ---------------------------------------------------------------------------
+// Verification
+// ---------------------------------------------------------------------------
+
+interface TaskVerification {
+ taskName: string;
+ claimedComplete: boolean;
+ actuallyComplete: boolean;
+ totalChecks: number;
+ claimedPassing: number;
+ actualPassing: number;
+ gaps: { description: string; severity: string }[];
+}
+
+function verifyTask(task: Task): TaskVerification {
+ const claimedPassing = task.checks.filter((c) => c.claimed).length;
+ const actualPassing = task.checks.filter((c) => c.actual).length;
+ const gaps = task.checks.filter((c) => c.claimed && !c.actual);
+
+ return {
+ taskName: task.name,
+ claimedComplete: task.claimedComplete,
+ actuallyComplete: gaps.length === 0,
+ totalChecks: task.checks.length,
+ claimedPassing,
+ actualPassing,
+ gaps: gaps.map((g) => ({ description: g.description, severity: g.severity })),
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ console.log("\n" + "=".repeat(90));
+ console.log(" VICTORY DETECTOR -- Claimed vs Actual Verification");
+ console.log("=".repeat(90));
+
+ const verifications = tasks.map(verifyTask);
+
+ for (const v of verifications) {
+ console.log("\n Task: " + v.taskName);
+ console.log(" " + "-".repeat(70));
+ console.log(` Agent claimed: ${v.claimedComplete ? "COMPLETE" : "NOT COMPLETE"}`);
+ console.log(` Actually is: ${v.actuallyComplete ? "COMPLETE" : "INCOMPLETE"}`);
+
+ if (!v.actuallyComplete) {
+ console.log(` MISMATCH: Agent declared victory but ${v.gaps.length} check(s) failed!`);
+ }
+
+ // Detailed checks for this task
+ const task = tasks.find((t) => t.name === v.taskName)!;
+ console.log("\n Check detail:");
+ const header = ` | ${pad("Check", 40)}| ${pad("Claimed", 9)}| ${pad("Actual", 9)}| ${pad("Gap?", 6)}|`;
+ const sep = ` |${"-".repeat(42)}|${"-".repeat(11)}|${"-".repeat(11)}|${"-".repeat(8)}|`;
+ console.log(header);
+ console.log(sep);
+
+ for (const check of task.checks) {
+ const claimedLabel = check.claimed ? "PASS" : "FAIL";
+ const actualLabel = check.actual ? "PASS" : "FAIL";
+ const gapLabel = check.claimed && !check.actual ? "GAP" : "";
+ const marker = gapLabel ? ">>" : " ";
+ console.log(`${marker}| ${pad(check.description, 40)}| ${pad(claimedLabel, 9)}| ${pad(actualLabel, 9)}| ${pad(gapLabel, 6)}|`);
+ }
+ }
+
+ // Overall summary
+ console.log("\n" + "=".repeat(90));
+ console.log(" OVERALL SUMMARY");
+ console.log("=".repeat(90) + "\n");
+
+ const sHeader = `| ${pad("Task", 28)}| ${pad("Claimed", 10)}| ${pad("Actual", 10)}| ${pad("Gaps", 6)}| ${pad("Accuracy", 10)}|`;
+ const sSep = `|${"-".repeat(30)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(12)}|`;
+ console.log(sHeader);
+ console.log(sSep);
+
+ for (const v of verifications) {
+ const accuracy = Math.round((v.actualPassing / v.totalChecks) * 100);
+ const cLabel = v.claimedComplete ? "Done" : "Pending";
+ const aLabel = v.actuallyComplete ? "Done" : "Incomplete";
+ console.log(`| ${pad(v.taskName, 28)}| ${pad(cLabel, 10)}| ${pad(aLabel, 10)}| ${pad(String(v.gaps.length), 6)}| ${pad(accuracy + "%", 10)}|`);
+ }
+
+ const totalGaps = verifications.reduce((s, v) => s + v.gaps.length, 0);
+ const falseVictories = verifications.filter((v) => v.claimedComplete && !v.actuallyComplete).length;
+
+ console.log("\n False victories: " + falseVictories + " of " + verifications.length + " tasks");
+ console.log(" Total undetected gaps: " + totalGaps);
+ console.log("\n The agent declared 'done' on every task, but verification reveals " + totalGaps + " unmet criteria.");
+ console.log(" Without explicit verification, premature victory declarations go unchecked.\n");
+}
+
+run();
diff --git a/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index b9a306a..2b8c43a 100644
--- a/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/zh/lectures/lecture-09-why-agents-declare-victory-too-early/)
+> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/code/)
+> Practice project: [Project 05. Self-verification and role separation](./../../projects/project-05-grounded-qa-verification/index.md)
+
# Lecture 09. Stop Agents from Declaring Victory Early
## What Problem Does This Lecture Solve?
diff --git a/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md
new file mode 100644
index 0000000..6a6179b
--- /dev/null
+++ b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md
@@ -0,0 +1,6 @@
+# Electron Architecture Rules
+
+- Renderer code may not directly access the filesystem.
+- Preload is the only bridge between renderer and Electron main.
+- Retrieval and indexing logic live in service modules, not UI components.
+- Logging should be structured and emitted from service boundaries.
diff --git a/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts
new file mode 100644
index 0000000..2428416
--- /dev/null
+++ b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts
@@ -0,0 +1,253 @@
+/**
+ * e2e-runner.ts
+ *
+ * A minimal E2E test harness. Defines test cases as user action sequences
+ * (import doc -> index -> ask question -> verify citation). Simulates
+ * running them and shows the difference between "unit tests pass" and
+ * "full pipeline works".
+ *
+ * Run: npx tsx docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface PipelineStep {
+ name: string;
+ unitTestPasses: boolean;
+ // Simulated actual behavior in the pipeline
+ actualBehavior: "works" | "fails" | "partial";
+ failureReason?: string;
+}
+
+interface TestCase {
+ name: string;
+ steps: PipelineStep[];
+}
+
+interface TestResult {
+ testCase: string;
+ unitTestsPassed: number;
+ unitTestsTotal: number;
+ unitTestResult: "PASS" | "FAIL";
+ e2eResult: "PASS" | "FAIL";
+ e2eFailureStep?: string;
+ e2eFailureReason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Test cases -- realistic scenarios where unit tests pass but E2E fails
+// ---------------------------------------------------------------------------
+
+const testCases: TestCase[] = [
+ {
+ name: "Import document and ask question",
+ steps: [
+ {
+ name: "Parse uploaded document",
+ unitTestPasses: true,
+ actualBehavior: "works",
+ },
+ {
+ name: "Store document chunks",
+ unitTestPasses: true,
+ actualBehavior: "works",
+ },
+ {
+ name: "Index chunks for retrieval",
+ unitTestPasses: true,
+ actualBehavior: "partial", // Indexes but with wrong embedding dimensions
+ failureReason: "Embedding dimension mismatch between indexer and retriever",
+ },
+ {
+ name: "Retrieve relevant chunks",
+ unitTestPasses: true, // Unit test uses mock data with correct dimensions
+ actualBehavior: "fails",
+ failureReason: "Empty results due to dimension mismatch from previous step",
+ },
+ {
+ name: "Generate answer with citations",
+ unitTestPasses: true, // Unit test provides pre-retrieved chunks
+ actualBehavior: "fails",
+ failureReason: "No chunks retrieved, so answer has no citations",
+ },
+ ],
+ },
+ {
+ name: "Delete document and verify removal",
+ steps: [
+ {
+ name: "Find document by ID",
+ unitTestPasses: true,
+ actualBehavior: "works",
+ },
+ {
+ name: "Delete document record",
+ unitTestPasses: true,
+ actualBehavior: "works",
+ },
+ {
+ name: "Remove indexed chunks",
+ unitTestPasses: true,
+ actualBehavior: "fails", // Orphaned chunks remain in the index
+ failureReason: "Index cleanup query timed out, chunks remain orphaned",
+ },
+ {
+ name: "Verify document not in search results",
+ unitTestPasses: true, // Unit test mocks the search
+ actualBehavior: "fails",
+ failureReason: "Orphaned chunks from previous step still appear in results",
+ },
+ ],
+ },
+ {
+ name: "Multi-user concurrent access",
+ steps: [
+ {
+ name: "User A imports document",
+ unitTestPasses: true,
+ actualBehavior: "works",
+ },
+ {
+ name: "User B imports document",
+ unitTestPasses: true,
+ actualBehavior: "works",
+ },
+ {
+ name: "User A queries their document",
+ unitTestPasses: true,
+ actualBehavior: "partial", // Cross-contamination of results
+ failureReason: "No user-scoping on retrieval, returns chunks from User B's doc",
+ },
+ {
+ name: "Verify only User A's results returned",
+ unitTestPasses: true,
+ actualBehavior: "fails",
+ failureReason: "Results include documents from other users",
+ },
+ ],
+ },
+];
+
+// ---------------------------------------------------------------------------
+// Run tests
+// ---------------------------------------------------------------------------
+
+function runUnitTests(tc: TestCase): { passed: number; total: number } {
+ const passed = tc.steps.filter((s) => s.unitTestPasses).length;
+ return { passed, total: tc.steps.length };
+}
+
+function runE2ETest(tc: TestCase): { pass: boolean; failureStep?: string; failureReason?: string } {
+ // Pipeline: if any step actually fails, the whole E2E fails
+ for (const step of tc.steps) {
+ if (step.actualBehavior === "fails") {
+ return {
+ pass: false,
+ failureStep: step.name,
+ failureReason: step.failureReason ?? "Unknown failure",
+ };
+ }
+ // "partial" means the step technically completes but creates problems downstream
+ // We let it continue but track it
+ }
+ // Check if any step was "partial" (which may cause downstream issues)
+ const partialSteps = tc.steps.filter((s) => s.actualBehavior === "partial");
+ if (partialSteps.length > 0) {
+ // The partial steps may or may not cause overall failure
+ // In our simulation, partial steps always lead to failure downstream
+ // unless there's an explicit "fails" step that already caught it
+ // This case means all steps were either "works" or "partial"
+ return {
+ pass: false,
+ failureStep: partialSteps[partialSteps.length - 1].name,
+ failureReason: partialSteps[partialSteps.length - 1].failureReason ?? "Partial completion",
+ };
+ }
+
+ return { pass: true };
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ console.log("\n" + "=".repeat(95));
+ console.log(" E2E TEST RUNNER -- Unit Tests vs Full Pipeline");
+ console.log("=".repeat(95));
+
+ const results: TestResult[] = testCases.map((tc) => {
+ const unit = runUnitTests(tc);
+ const e2e = runE2ETest(tc);
+
+ return {
+ testCase: tc.name,
+ unitTestsPassed: unit.passed,
+ unitTestsTotal: unit.total,
+ unitTestResult: unit.passed === unit.total ? "PASS" : "FAIL",
+ e2eResult: e2e.pass ? "PASS" : "FAIL",
+ e2eFailureStep: e2e.failureStep,
+ e2eFailureReason: e2e.failureReason,
+ };
+ });
+
+ // Per-test-case detail
+ for (let i = 0; i < testCases.length; i++) {
+ const tc = testCases[i];
+ const r = results[i];
+
+ console.log("\n Test Case: " + tc.name);
+ console.log(" " + "-".repeat(70));
+
+ const stepHeader = ` | ${pad("Step", 40)}| ${pad("Unit Test", 11)}| ${pad("E2E Actual", 12)}|`;
+ const stepSep = ` |${"-".repeat(42)}|${"-".repeat(13)}|${"-".repeat(14)}|`;
+ console.log(stepHeader);
+ console.log(stepSep);
+
+ for (const step of tc.steps) {
+ const utLabel = step.unitTestPasses ? "PASS" : "FAIL";
+ let e2eLabel: string;
+ if (step.actualBehavior === "works") e2eLabel = "PASS";
+ else if (step.actualBehavior === "partial") e2eLabel = "PARTIAL*";
+ else e2eLabel = "FAIL";
+
+ const marker = step.actualBehavior !== "works" ? ">>" : " ";
+ console.log(`${marker}| ${pad(step.name, 40)}| ${pad(utLabel, 11)}| ${pad(e2eLabel, 12)}|`);
+ }
+
+ if (r.e2eFailureStep) {
+ console.log(`\n E2E Failure at: ${r.e2eFailureStep}`);
+ console.log(` Reason: ${r.e2eFailureReason}`);
+ }
+ }
+
+ // Summary comparison
+ console.log("\n" + "=".repeat(95));
+ console.log(" COMPARISON: Unit Tests vs E2E Tests");
+ console.log("=".repeat(95) + "\n");
+
+ const header = `| ${pad("Test Case", 35)}| ${pad("Unit Tests", 15)}| ${pad("E2E Result", 12)}| Discrepancy`;
+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(14)}|${"-".repeat(30)}`;
+ console.log(header);
+ console.log(sep);
+
+ for (const r of results) {
+ const utLabel = `${r.unitTestsPassed}/${r.unitTestsTotal} ${r.unitTestResult}`;
+ const discrepancy = r.unitTestResult === "PASS" && r.e2eResult === "FAIL";
+ const discLabel = discrepancy ? "UNIT PASS BUT E2E FAIL" : "Consistent";
+
+ console.log(`| ${pad(r.testCase, 35)}| ${pad(utLabel, 15)}| ${pad(r.e2eResult, 12)}| ${discLabel}`);
+ }
+
+ const falseConfidence = results.filter((r) => r.unitTestResult === "PASS" && r.e2eResult === "FAIL").length;
+ console.log("\n False confidence count: " + falseConfidence + " of " + results.length);
+ console.log(" Unit tests pass but E2E reveals integration failures that units cannot catch.\n");
+}
+
+run();
diff --git a/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md
new file mode 100644
index 0000000..8825e4e
--- /dev/null
+++ b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md
@@ -0,0 +1,8 @@
+# Code for Lecture 10
+
+Use this folder for examples of:
+
+- architecture constraints
+- structural tests
+- taste invariants
+- remediation-oriented lint messages
diff --git a/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md
new file mode 100644
index 0000000..f3cfd40
--- /dev/null
+++ b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md
@@ -0,0 +1,10 @@
+# Example: Turning Review Feedback into a Rule
+
+Repeated review comment:
+
+> Do not call filesystem utilities from the renderer. Use the preload bridge.
+
+Promoted harness rule:
+
+- add a lint or import rule preventing `fs` usage in renderer code
+- add remediation text explaining the preload boundary
diff --git a/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index c0b4a88..5f9a826 100644
--- a/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/)
+> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/)
+> Practice project: [Project 05. Self-verification and role separation](./../../projects/project-05-grounded-qa-verification/index.md)
+
# Lecture 10. Only a Full-Pipeline Run Counts as Real Verification
## What Problem Does This Lecture Solve?
diff --git a/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md
new file mode 100644
index 0000000..2c932d8
--- /dev/null
+++ b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md
@@ -0,0 +1,8 @@
+# Evaluator Rubric Example
+
+Use 1-5 scoring for each dimension:
+
+- Grounding: are answers clearly tied to imported sources?
+- Citation quality: are the source references visible and specific?
+- Functionality: can the user complete the question-answer flow?
+- Product coherence: does the workflow feel integrated?
diff --git a/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md
new file mode 100644
index 0000000..5f094b9
--- /dev/null
+++ b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md
@@ -0,0 +1,8 @@
+# Code for Lecture 11
+
+Use this folder for examples of:
+
+- planner outputs
+- evaluator rubrics
+- generator/evaluator loops
+- single-agent vs multi-role comparisons
diff --git a/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts
new file mode 100644
index 0000000..213dc19
--- /dev/null
+++ b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts
@@ -0,0 +1,260 @@
+/**
+ * runtime-logger.ts
+ *
+ * A structured logging module demo. Shows ad-hoc console.log output vs
+ * structured JSON log output when diagnosing a failure. Includes a seeded
+ * failure scenario and demonstrates how structured logs pinpoint the issue
+ * faster.
+ *
+ * Run: npx tsx docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface StructuredLogEntry {
+ timestamp: string;
+ level: "info" | "warn" | "error" | "debug";
+ component: string;
+ action: string;
+ durationMs?: number;
+ input?: unknown;
+ output?: unknown;
+ error?: string;
+ correlationId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Simulated pipeline with a seeded failure
+// ---------------------------------------------------------------------------
+
+const CORRELATION_ID = "req-" + Math.random().toString(36).slice(2, 8);
+
+// Simulated stages of a document Q&A pipeline
+interface PipelineStage {
+ component: string;
+ action: string;
+ durationMs: number;
+ success: boolean;
+ errorMessage?: string;
+ input?: unknown;
+ output?: unknown;
+}
+
+function runPipeline(): PipelineStage[] {
+ return [
+ {
+ component: "DocumentLoader",
+ action: "parse_upload",
+ durationMs: 45,
+ success: true,
+ input: { filename: "report.pdf", size: "2.3MB" },
+ output: { chunks: 47 },
+ },
+ {
+ component: "ChunkIndexer",
+ action: "embed_and_store",
+ durationMs: 230,
+ success: true,
+ input: { chunks: 47 },
+ output: { indexed: 47, embeddingDim: 1536 },
+ },
+ {
+ component: "QueryRouter",
+ action: "route_query",
+ durationMs: 12,
+ success: true,
+ input: { query: "What is the revenue target?" },
+ output: { routedTo: "RetrievalEngine" },
+ },
+ {
+ // SEEDED FAILURE: Retrieval returns 0 results due to dimension mismatch
+ component: "RetrievalEngine",
+ action: "semantic_search",
+ durationMs: 180,
+ success: false,
+ errorMessage: "Vector dimension mismatch: query embedding dim=768, index embedding dim=1536",
+ input: { query: "What is the revenue target?", topK: 5 },
+ output: { results: 0 },
+ },
+ {
+ component: "AnswerGenerator",
+ action: "generate_with_citations",
+ durationMs: 1500,
+ success: true, // Doesn't crash, but produces a bad answer
+ input: { context: [], query: "What is the revenue target?" },
+ output: { answer: "I could not find relevant information.", citations: 0 },
+ },
+ ];
+}
+
+// ---------------------------------------------------------------------------
+// Ad-hoc logging (console.log style)
+// ---------------------------------------------------------------------------
+
+function printAdHocLog(stages: PipelineStage[]): void {
+ console.log("Starting document Q&A pipeline...");
+ console.log("User uploaded report.pdf");
+
+ for (const stage of stages) {
+ if (stage.success) {
+ console.log(`${stage.component}: ${stage.action} done (${stage.durationMs}ms)`);
+ } else {
+ console.log(`${stage.component}: something went wrong`);
+ }
+ }
+
+ console.log("Pipeline finished. Answer: I could not find relevant information.");
+}
+
+// ---------------------------------------------------------------------------
+// Structured logging (JSON)
+// ---------------------------------------------------------------------------
+
+function printStructuredLog(stages: PipelineStage[]): StructuredLogEntry[] {
+ const entries: StructuredLogEntry[] = [];
+
+ for (const stage of stages) {
+ entries.push({
+ timestamp: new Date().toISOString(),
+ level: stage.success ? "info" : "error",
+ component: stage.component,
+ action: stage.action,
+ durationMs: stage.durationMs,
+ input: stage.input,
+ output: stage.output,
+ error: stage.errorMessage,
+ correlationId: CORRELATION_ID,
+ });
+ }
+
+ return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Diagnose failure from structured logs
+// ---------------------------------------------------------------------------
+
+function diagnoseFromStructured(entries: StructuredLogEntry[]): string[] {
+ const diagnosis: string[] = [];
+
+ // Find errors
+ const errors = entries.filter((e) => e.level === "error");
+ if (errors.length > 0) {
+ diagnosis.push("ERRORS FOUND:");
+ for (const err of errors) {
+ diagnosis.push(` - ${err.component}.${err.action}: ${err.error}`);
+ }
+ }
+
+ // Check for latency spikes
+ const slowStages = entries.filter((e) => (e.durationMs ?? 0) > 1000);
+ if (slowStages.length > 0) {
+ diagnosis.push("LATENCY SPIKES:");
+ for (const s of slowStages) {
+ diagnosis.push(` - ${s.component}.${s.action}: ${s.durationMs}ms`);
+ }
+ }
+
+ // Check for cascading failures
+ const emptyOutputs = entries.filter((e) => {
+ const out = e.output as Record<string, unknown> | undefined;
+ return out && typeof out === "object" && "results" in out && (out.results as number) === 0;
+ });
+ if (emptyOutputs.length > 0) {
+ diagnosis.push("EMPTY OUTPUTS (possible cascade):");
+ for (const e of emptyOutputs) {
+ diagnosis.push(` - ${e.component}.${e.action}: returned 0 results`);
+ }
+ }
+
+ return diagnosis;
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ const pipeline = runPipeline();
+
+ console.log("\n" + "=".repeat(90));
+ console.log(" OBSERVABILITY DEMO -- Ad-hoc vs Structured Logging");
+ console.log("=".repeat(90));
+
+ // --- Ad-hoc output ---
+ console.log("\n" + "-".repeat(90));
+ console.log(" SCENARIO A: Ad-hoc console.log output");
+ console.log("-".repeat(90) + "\n");
+ printAdHocLog(pipeline);
+ console.log("\n Diagnosis from ad-hoc logs: ??? Hard to tell what went wrong.");
+ console.log(" The failure message is vague: 'something went wrong'.");
+ console.log(" No dimensions, no input/output data, no correlation ID.");
+
+ // --- Structured output ---
+ console.log("\n" + "-".repeat(90));
+ console.log(" SCENARIO B: Structured JSON log output");
+ console.log("-".repeat(90) + "\n");
+
+ const structuredEntries = printStructuredLog(pipeline);
+
+ const header = `| ${pad("Timestamp", 26)}| ${pad("Level", 6)}| ${pad("Component", 20)}| ${pad("Action", 25)}| ${pad("Duration", 9)}| Error?`;
+ const sep = `|${"-".repeat(28)}|${"-".repeat(8)}|${"-".repeat(22)}|${"-".repeat(27)}|${"-".repeat(11)}|${"-".repeat(30)}`;
+ console.log(header);
+ console.log(sep);
+
+ for (const entry of structuredEntries) {
+ const hasError = entry.error ? entry.error.slice(0, 30) : "";
+ const marker = entry.level === "error" ? ">>" : " ";
+ console.log(
+ `${marker}| ${pad(entry.timestamp, 26)}| ${pad(entry.level, 6)}| ${pad(entry.component, 20)}| ${pad(entry.action, 25)}| ${pad(String(entry.durationMs) + "ms", 9)}| ${hasError}`
+ );
+ }
+
+ // --- Diagnosis ---
+ console.log("\n" + "-".repeat(90));
+ console.log(" AUTOMATED DIAGNOSIS FROM STRUCTURED LOGS");
+ console.log("-".repeat(90) + "\n");
+
+ const errors = structuredEntries.filter((e) => e.level === "error");
+ for (const err of errors) {
+ console.log(` ROOT CAUSE: ${err.component}.${err.action}`);
+ console.log(` Error: ${err.error}`);
+ console.log(` Input: ${JSON.stringify(err.input)}`);
+ console.log(` Output: ${JSON.stringify(err.output)}`);
+ console.log(` Correlation ID: ${err.correlationId}`);
+ }
+
+ // Downstream impact
+ console.log("\n DOWNSTREAM IMPACT:");
+ const answerGen = structuredEntries.find((e) => e.component === "AnswerGenerator");
+ if (answerGen) {
+ const out = answerGen.output as Record<string, unknown>;
+ console.log(` AnswerGenerator received empty context (${JSON.stringify(answerGen.input)})`);
+ console.log(` Produced answer: "${out.answer}" with ${out.citations} citations`);
+ }
+
+ // Comparison summary
+ console.log("\n" + "=".repeat(90));
+ console.log(" COMPARISON");
+ console.log("=".repeat(90) + "\n");
+
+ const cHeader = `| ${pad("Metric", 35)}| ${pad("Ad-hoc Logs", 18)}| ${pad("Structured Logs", 18)}|`;
+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;
+ console.log(cHeader);
+ console.log(cSep);
+ console.log(`| ${pad("Root cause identifiable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);
+ console.log(`| ${pad("Input/output traceable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);
+ console.log(`| ${pad("Correlation across steps", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);
+ console.log(`| ${pad("Machine-parseable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);
+ console.log(`| ${pad("Time to diagnose", 35)}| ${pad("Minutes (manual)", 18)}| ${pad("Seconds (auto)", 18)}|`);
+
+ console.log("\n Structured logging transforms debugging from guesswork into a deterministic lookup.\n");
+}
+
+run();
diff --git a/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md
new file mode 100644
index 0000000..bae2450
--- /dev/null
+++ b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md
@@ -0,0 +1,12 @@
+# Sprint Contract Example
+
+Sprint goal:
+
+- Add visible citations to grounded Q&A results
+
+Done means:
+
+- User asks a question
+- App returns an answer
+- At least one citation is shown
+- Clicking a citation opens the source location in the document view
diff --git a/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index e7dcc1b..42a16a4 100644
--- a/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/)
+> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/)
+> Practice project: [Project 06. Complete harness (Capstone)](./../../projects/project-06-runtime-observability-and-debugging/index.md)
+
# Lecture 11. Make the Agent's Runtime Observable
## What Problem Does This Lecture Solve?
diff --git a/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md
new file mode 100644
index 0000000..45d8a3d
--- /dev/null
+++ b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md
@@ -0,0 +1,18 @@
+# Benchmark Comparison Template
+
+Harness A:
+
+- completion rate
+- average retries
+- bugs caught before human review
+
+Harness B:
+
+- completion rate
+- average retries
+- bugs caught before human review
+
+Interpretation:
+
+- Which harness changed the result?
+- Which harness changed the cost of getting the result?
diff --git a/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts
new file mode 100644
index 0000000..0388cad
--- /dev/null
+++ b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts
@@ -0,0 +1,216 @@
+/**
+ * benchmark-runner.ts
+ *
+ * Reads a benchmark task definition (JSON array of tasks with pass criteria),
+ * "executes" each task, records timing and pass/fail, outputs a comparison
+ * report showing which tasks pass and which fail.
+ *
+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface BenchmarkTask {
+ id: string;
+ name: string;
+ category: string;
+ passCriteria: string[];
+ expectedDurationMs: number;
+ // Simulated actual results
+ actualDurationMs: number;
+ actualPass: boolean;
+ failureReason?: string;
+}
+
+interface BenchmarkResult {
+ id: string;
+ name: string;
+ category: string;
+ criteriaTotal: number;
+ criteriaPassed: number;
+ pass: boolean;
+ expectedMs: number;
+ actualMs: number;
+ durationDelta: number;
+ failureReason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark task definitions
+// ---------------------------------------------------------------------------
+
+const benchmarkTasks: BenchmarkTask[] = [
+ {
+ id: "bench-001",
+ name: "Import markdown document",
+ category: "Document Pipeline",
+ passCriteria: ["File accepted", "Chunks created", "Metadata stored"],
+ expectedDurationMs: 100,
+ actualDurationMs: 95,
+ actualPass: true,
+ },
+ {
+ id: "bench-002",
+ name: "Import PDF document",
+ category: "Document Pipeline",
+ passCriteria: ["File accepted", "Text extracted", "Chunks created", "Metadata stored"],
+ expectedDurationMs: 200,
+ actualDurationMs: 310,
+ actualPass: false,
+ failureReason: "PDF text extraction failed on page 3 -- encoding issue",
+ },
+ {
+ id: "bench-003",
+ name: "Ask grounded question",
+ category: "Q&A Pipeline",
+ passCriteria: ["Query received", "Relevant chunks retrieved", "Answer generated", "Citations present"],
+ expectedDurationMs: 500,
+ actualDurationMs: 480,
+ actualPass: true,
+ },
+ {
+ id: "bench-004",
+ name: "Ask question with no relevant docs",
+ category: "Q&A Pipeline",
+ passCriteria: ["Query received", "Graceful 'no results' message", "No hallucinated citations"],
+ expectedDurationMs: 400,
+ actualDurationMs: 420,
+ actualPass: false,
+ failureReason: "Model hallucinated a citation instead of saying 'no results'",
+ },
+ {
+ id: "bench-005",
+ name: "Delete imported document",
+ category: "Document Pipeline",
+ passCriteria: ["Document removed from list", "Chunks removed from index", "No orphan data"],
+ expectedDurationMs: 150,
+ actualDurationMs: 145,
+ actualPass: true,
+ },
+ {
+ id: "bench-006",
+ name: "Concurrent user access",
+ category: "Security",
+ passCriteria: ["Users isolated", "No cross-user data leak", "Performance within SLA"],
+ expectedDurationMs: 300,
+ actualDurationMs: 850,
+ actualPass: false,
+ failureReason: "Cross-user data leak detected + response time exceeded SLA (850ms > 500ms)",
+ },
+ {
+ id: "bench-007",
+ name: "Session continuity after restart",
+ category: "Reliability",
+ passCriteria: ["State persisted", "Session recovers", "No data loss"],
+ expectedDurationMs: 200,
+ actualDurationMs: 180,
+ actualPass: true,
+ },
+ {
+ id: "bench-008",
+ name: "API rate limiting",
+ category: "Security",
+ passCriteria: ["Rate limit enforced", "429 response after limit", "Legitimate traffic unaffected"],
+ expectedDurationMs: 100,
+ actualDurationMs: 100,
+ actualPass: true,
+ },
+];
+
+// ---------------------------------------------------------------------------
+// Execution simulation
+// ---------------------------------------------------------------------------
+
+function executeBenchmark(tasks: BenchmarkTask[]): BenchmarkResult[] {
+ return tasks.map((task) => ({
+ id: task.id,
+ name: task.name,
+ category: task.category,
+ criteriaTotal: task.passCriteria.length,
+ criteriaPassed: task.actualPass ? task.passCriteria.length : Math.floor(task.passCriteria.length * 0.5),
+ pass: task.actualPass,
+ expectedMs: task.expectedDurationMs,
+ actualMs: task.actualDurationMs,
+ durationDelta: task.actualDurationMs - task.expectedDurationMs,
+ failureReason: task.failureReason,
+ }));
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ console.log("\n" + "=".repeat(100));
+ console.log(" BENCHMARK RUNNER -- Task Execution Report");
+ console.log("=".repeat(100));
+
+ const results = executeBenchmark(benchmarkTasks);
+
+ // Detailed results
+ const header = `| ${pad("ID", 10)}| ${pad("Task", 35)}| ${pad("Category", 18)}| ${pad("Pass?", 6)}| ${pad("Criteria", 10)}| ${pad("Expected", 10)}| ${pad("Actual", 10)}| ${pad("Delta", 8)}|`;
+ const sep = `|${"-".repeat(12)}|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(8)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(10)}|`;
+ console.log("\n" + header);
+ console.log(sep);
+
+ for (const r of results) {
+ const passLabel = r.pass ? "PASS" : "FAIL";
+ const criteriaLabel = `${r.criteriaPassed}/${r.criteriaTotal}`;
+ const deltaLabel = r.durationDelta >= 0 ? `+${r.durationDelta}ms` : `${r.durationDelta}ms`;
+ const marker = r.pass ? " " : ">>";
+
+ console.log(
+ `${marker}| ${pad(r.id, 10)}| ${pad(r.name, 35)}| ${pad(r.category, 18)}| ${pad(passLabel, 6)}| ${pad(criteriaLabel, 10)}| ${pad(r.expectedMs + "ms", 10)}| ${pad(r.actualMs + "ms", 10)}| ${pad(deltaLabel, 8)}|`
+ );
+ }
+
+ // Failure details
+ const failures = results.filter((r) => !r.pass);
+ if (failures.length > 0) {
+ console.log("\n" + "-".repeat(100));
+ console.log(" FAILURE DETAILS");
+ console.log("-".repeat(100));
+ for (const f of failures) {
+ console.log(`\n [${f.id}] ${f.name}`);
+ console.log(` Category: ${f.category}`);
+ console.log(` Criteria: ${f.criteriaPassed}/${f.criteriaTotal} passed`);
+ console.log(` Reason: ${f.failureReason ?? "Unknown"}`);
+ console.log(` Timing: Expected ${f.expectedMs}ms, actual ${f.actualMs}ms (delta: ${f.durationDelta >= 0 ? "+" : ""}${f.durationDelta}ms)`);
+ }
+ }
+
+ // Summary
+ console.log("\n" + "=".repeat(100));
+ console.log(" SUMMARY BY CATEGORY");
+ console.log("=".repeat(100) + "\n");
+
+ const categories = [...new Set(results.map((r) => r.category))];
+ const catHeader = `| ${pad("Category", 20)}| ${pad("Total", 8)}| ${pad("Passed", 8)}| ${pad("Failed", 8)}| ${pad("Pass Rate", 12)}|`;
+ const catSep = `|${"-".repeat(22)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(14)}|`;
+ console.log(catHeader);
+ console.log(catSep);
+
+ for (const cat of categories) {
+ const catResults = results.filter((r) => r.category === cat);
+ const catPassed = catResults.filter((r) => r.pass).length;
+ const catFailed = catResults.filter((r) => !r.pass).length;
+ const rate = Math.round((catPassed / catResults.length) * 100);
+
+ console.log(`| ${pad(cat, 20)}| ${pad(String(catResults.length), 8)}| ${pad(String(catPassed), 8)}| ${pad(String(catFailed), 8)}| ${pad(rate + "%", 12)}|`);
+ }
+
+ // Overall
+ const totalPassed = results.filter((r) => r.pass).length;
+ const totalFailed = results.filter((r) => !r.pass).length;
+ console.log("\n" + "-".repeat(100));
+ console.log(` OVERALL: ${totalPassed}/${results.length} passed (${Math.round((totalPassed / results.length) * 100)}%), ${totalFailed} failures`);
+ console.log("=".repeat(100) + "\n");
+}
+
+run();
diff --git a/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md
new file mode 100644
index 0000000..effd751
--- /dev/null
+++ b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md
@@ -0,0 +1,9 @@
+# Cleanup Loop Example
+
+Recurring cleanup tasks:
+
+- scan for stale docs
+- scan for structural violations
+- update quality grades
+- open targeted cleanup PRs
+- rerun a fixed benchmark slice after cleanup
diff --git a/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts
new file mode 100644
index 0000000..6b35905
--- /dev/null
+++ b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts
@@ -0,0 +1,336 @@
+/**
+ * cleanup-scanner.ts
+ *
+ * Scans a project directory for stale artifacts, dead code, structural
+ * violations, and outputs a cleanup report. Helps enforce the "clean state
+ * at end of every session" principle.
+ *
+ * Usage:
+ * npx tsx docs/lectures/lecture-12.../code/cleanup-scanner.ts [path]
+ * (defaults to current working directory)
+ *
+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface ScanResult {
+ category: string;
+ check: string;
+ severity: "critical" | "warning" | "info";
+ found: string[];
+ description: string;
+}
+
+// ---------------------------------------------------------------------------
+// Scanner checks
+// ---------------------------------------------------------------------------
+
+interface ScannerCheck {
+ category: string;
+ name: string;
+ severity: "critical" | "warning" | "info";
+ description: string;
+ scan: (dir: string) => string[];
+}
+
+function createChecks(): ScannerCheck[] {
+ return [
+ {
+ category: "Stale Artifacts",
+ name: "Temporary files (*.tmp, *.bak, *.swp)",
+ severity: "warning",
+ description: "Leftover temp files from editing or processing",
+ scan: (dir) => findFiles(dir, [".tmp", ".bak", ".swp", "~"]),
+ },
+ {
+ category: "Stale Artifacts",
+ name: "Debug/log files in source",
+ severity: "warning",
+ description: "Log files that should not be in the source tree",
+ scan: (dir) => {
+ const found: string[] = [];
+ const logPatterns = [".log"];
+ for (const p of findFiles(dir, logPatterns)) {
+ // Only flag log files in source directories
+ if (p.includes("/src/") || p.includes("/lib/") || p.includes("/app/")) {
+ found.push(p);
+ }
+ }
+ return found;
+ },
+ },
+ {
+ category: "Dead Code",
+ name: "Unused imports (placeholder detection)",
+ severity: "info",
+ description: "Files that may contain unused code (heuristic scan)",
+ scan: (dir) => {
+ const found: string[] = [];
+ const srcDirs = ["src", "lib", "app"];
+ for (const srcDir of srcDirs) {
+ const srcPath = path.join(dir, srcDir);
+ if (fs.existsSync(srcPath)) {
+ scanForPatterns(srcPath, ["TODO:", "FIXME:", "HACK:", "XXX:"], found, dir);
+ }
+ }
+ return found;
+ },
+ },
+ {
+ category: "Structural Violations",
+ name: "Missing .gitignore",
+ severity: "warning",
+ description: "No .gitignore file found -- risk of committing build artifacts",
+ scan: (dir) => fs.existsSync(path.join(dir, ".gitignore")) ? [] : [".gitignore (MISSING)"],
+ },
+ {
+ category: "Structural Violations",
+ name: "Build artifacts in source",
+ severity: "critical",
+ description: "Compiled output (dist/, build/) mixed with source",
+ scan: (dir) => {
+ const found: string[] = [];
+ // Check if dist/ or build/ exists inside src/
+ const dirs = ["src/dist", "src/build", "lib/dist", "lib/build"];
+ for (const d of dirs) {
+ if (fs.existsSync(path.join(dir, d))) {
+ found.push(d + "/");
+ }
+ }
+ return found;
+ },
+ },
+ {
+ category: "Structural Violations",
+ name: "node_modules in source tree",
+ severity: "critical",
+ description: "node_modules directory found outside root (nested dependency)",
+ scan: (dir) => {
+ const found: string[] = [];
+ const srcDirs = ["src", "lib", "app", "test", "tests"];
+ for (const srcDir of srcDirs) {
+ const nmPath = path.join(dir, srcDir, "node_modules");
+ if (fs.existsSync(nmPath)) {
+ found.push(srcDir + "/node_modules/");
+ }
+ }
+ return found;
+ },
+ },
+ {
+ category: "Session Cleanliness",
+ name: "Uncommitted changes indicator",
+ severity: "info",
+ description: "Checks for common artifacts of incomplete sessions",
+ scan: (dir) => {
+ const found: string[] = [];
+ const indicators = [
+ "WIP.md", "IN_PROGRESS.md", "scratch.ts", "scratch.js",
+ "debug.ts", "test-manual.ts", "temp.ts",
+ ];
+ for (const f of indicators) {
+ if (fs.existsSync(path.join(dir, f))) {
+ found.push(f);
+ }
+ }
+ return found;
+ },
+ },
+ {
+ category: "Session Cleanliness",
+ name: "Empty directories",
+ severity: "info",
+ description: "Empty directories that may be leftover from incomplete work",
+ scan: (dir) => {
+ const found: string[] = [];
+ const commonDirs = ["src", "lib", "app", "test", "tests", "docs"];
+ for (const d of commonDirs) {
+ const dp = path.join(dir, d);
+ if (fs.existsSync(dp) && fs.statSync(dp).isDirectory()) {
+ try {
+ const contents = fs.readdirSync(dp);
+ if (contents.length === 0) {
+ found.push(d + "/");
+ }
+ } catch {
+ // Skip directories we can't read
+ }
+ }
+ }
+ return found;
+ },
+ },
+ {
+ category: "Configuration",
+ name: "Environment files in source",
+ severity: "critical",
+ description: ".env files that may contain secrets",
+ scan: (dir) => {
+ const found: string[] = [];
+ const envFiles = [".env", ".env.local", ".env.production", ".env.staging"];
+ for (const f of envFiles) {
+ if (fs.existsSync(path.join(dir, f))) {
+ found.push(f);
+ }
+ }
+ return found;
+ },
+ },
+ ];
+}
+
+// ---------------------------------------------------------------------------
+// Helper functions
+// ---------------------------------------------------------------------------
+
+function findFiles(dir: string, extensions: string[]): string[] {
+ const found: string[] = [];
+
+ function walk(current: string, depth: number): void {
+ if (depth > 4) return; // Limit recursion depth
+ try {
+ const entries = fs.readdirSync(current, { withFileTypes: true });
+ for (const entry of entries) {
+ // Skip common non-source directories
+ if (entry.isDirectory() && ["node_modules", ".git", "dist", "build", ".next", "coverage"].includes(entry.name)) {
+ continue;
+ }
+
+ const fullPath = path.join(current, entry.name);
+ const relativePath = path.relative(dir, fullPath);
+
+ if (entry.isDirectory()) {
+ walk(fullPath, depth + 1);
+ } else if (entry.isFile()) {
+ if (extensions.some((ext) => entry.name.endsWith(ext))) {
+ found.push(relativePath);
+ }
+ }
+ }
+ } catch {
+ // Skip directories we can't read
+ }
+ }
+
+ walk(dir, 0);
+ return found;
+}
+
+function scanForPatterns(dir: string, patterns: string[], results: string[], baseDir: string): void {
+ try {
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
+ for (const entry of entries) {
+ if (entry.isDirectory()) {
+ if (!["node_modules", ".git", "dist", "build"].includes(entry.name)) {
+ scanForPatterns(path.join(dir, entry.name), patterns, results, baseDir);
+ }
+ continue;
+ }
+
+ const fullPath = path.join(dir, entry.name);
+ if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".tsx") && !entry.name.endsWith(".js")) {
+ continue;
+ }
+
+ try {
+ const content = fs.readFileSync(fullPath, "utf-8");
+ const lines = content.split("\n");
+ for (let i = 0; i < Math.min(lines.length, 50); i++) {
+ for (const pattern of patterns) {
+ if (lines[i].includes(pattern)) {
+ const relative = path.relative(baseDir, fullPath);
+ results.push(`${relative}:${i + 1} contains ${pattern}`);
+ }
+ }
+ }
+ } catch {
+ // Skip files we can't read
+ }
+ }
+ } catch {
+ // Skip directories we can't read
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ const targetDir = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();
+
+ console.log("\n" + "=".repeat(90));
+ console.log(" CLEANUP SCANNER -- Stale Artifact & Violation Report");
+ console.log("=".repeat(90));
+ console.log(` Scanning: ${targetDir}\n`);
+
+ const checks = createChecks();
+ const results: ScanResult[] = [];
+
+ for (const check of checks) {
+ const found = check.scan(targetDir);
+ results.push({
+ category: check.category,
+ check: check.name,
+ severity: check.severity,
+ found,
+ description: check.description,
+ });
+ }
+
+ // Report
+ const header = `| ${pad("Category", 20)}| ${pad("Check", 40)}| ${pad("Severity", 10)}| ${pad("Count", 6)}| Details`;
+ const sep = `|${"-".repeat(22)}|${"-".repeat(42)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(30)}`;
+ console.log(header);
+ console.log(sep);
+
+ for (const r of results) {
+ const count = r.found.length;
+ const detail = count > 0 ? r.found.slice(0, 2).join(", ") : "(clean)";
+ const marker = count > 0 && r.severity === "critical" ? ">>" : count > 0 ? " * " : " ";
+
+ console.log(`${marker}| ${pad(r.category, 20)}| ${pad(r.check, 40)}| ${pad(r.severity, 10)}| ${pad(String(count), 6)}| ${detail}`);
+ }
+
+ // Summary
+ const criticals = results.filter((r) => r.severity === "critical" && r.found.length > 0);
+ const warnings = results.filter((r) => r.severity === "warning" && r.found.length > 0);
+ const infos = results.filter((r) => r.severity === "info" && r.found.length > 0);
+ const clean = results.filter((r) => r.found.length === 0);
+
+ console.log("\n" + "=".repeat(90));
+ console.log(" CLEANUP SUMMARY");
+ console.log("=".repeat(90) + "\n");
+
+ console.log(` Critical issues: ${criticals.length}`);
+ console.log(` Warnings: ${warnings.length}`);
+ console.log(` Info items: ${infos.length}`);
+ console.log(` Clean checks: ${clean.length}/${results.length}`);
+
+ if (criticals.length > 0) {
+ console.log("\n ACTION REQUIRED (Critical):");
+ for (const c of criticals) {
+ console.log(` - ${c.check}: ${c.found.length} item(s) found`);
+ console.log(` ${c.description}`);
+ }
+ }
+
+ const totalIssues = results.reduce((s, r) => s + r.found.length, 0);
+ if (totalIssues === 0) {
+ console.log("\n Project is in a clean state. No issues found.\n");
+ } else {
+ console.log(`\n Total issues found: ${totalIssues}. Run this scanner at the end of every session to maintain clean state.\n`);
+ }
+}
+
+run();
diff --git a/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md
new file mode 100644
index 0000000..29cf9f5
--- /dev/null
+++ b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md
@@ -0,0 +1,8 @@
+# Code for Lecture 12
+
+Use this folder for examples of:
+
+- benchmark slices
+- cleanup tasks
+- entropy reduction examples
+- repeatable harness runs
diff --git a/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index 7ee6f7c..1d57867 100644
--- a/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)
+> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/)
+> Practice project: [Project 06. Complete harness (Capstone)](./../../projects/project-06-runtime-observability-and-debugging/index.md)
+
# Lecture 12. Clean Handoff at the End of Every Session
## What Problem Does This Lecture Solve?
diff --git a/docs/en/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/en/projects/project-01-baseline-vs-minimal-harness/index.md
index d6467a4..d95939e 100644
--- a/docs/en/projects/project-01-baseline-vs-minimal-harness/index.md
+++ b/docs/en/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/projects/project-01-baseline-vs-minimal-harness/)
+> Related lectures: [Lecture 01. Strong models don't mean reliable execution](./../../lectures/lecture-01-why-capable-agents-still-fail/index.md) · [Lecture 02. What harness actually means](./../../lectures/lecture-02-what-a-harness-actually-is/index.md)
+> Template files: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/)
+
# Project 01. Prompt-Only vs. Rules-First: How Much Difference Does It Make
## What You Do
diff --git a/docs/en/projects/project-02-agent-readable-workspace/index.md b/docs/en/projects/project-02-agent-readable-workspace/index.md
index 5128db5..16b11d4 100644
--- a/docs/en/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/en/projects/project-02-agent-readable-workspace/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/projects/project-02-agent-readable-workspace/)
+> Related lectures: [Lecture 03. Make the repository your single source of truth](./../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) · [Lecture 04. Split instructions across files](./../../lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)
+> Template files: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/)
+
# Project 02. Make the Project Readable and Pick Up Where You Left Off
## What You Do
diff --git a/docs/en/projects/project-03-multi-session-continuity/index.md b/docs/en/projects/project-03-multi-session-continuity/index.md
index f82c948..a771a33 100644
--- a/docs/en/projects/project-03-multi-session-continuity/index.md
+++ b/docs/en/projects/project-03-multi-session-continuity/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/projects/project-03-multi-session-continuity/)
+> Related lectures: [Lecture 05. Keep context alive across sessions](./../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) · [Lecture 06. Initialize before every agent session](./../../lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)
+> Template files: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/)
+
# Project 03. Keep the Agent Working Across Session Restarts
## What You Do
diff --git a/docs/en/projects/project-04-incremental-indexing/index.md b/docs/en/projects/project-04-incremental-indexing/index.md
index 2932473..0c69a44 100644
--- a/docs/en/projects/project-04-incremental-indexing/index.md
+++ b/docs/en/projects/project-04-incremental-indexing/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/projects/project-04-incremental-indexing/)
+> Related lectures: [Lecture 07. Draw clear task boundaries for agents](./../../lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) · [Lecture 08. Use feature lists to constrain what the agent does](./../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)
+> Template files: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/)
+
# Project 04. Use Runtime Feedback to Correct Agent Behavior
## What You Do
diff --git a/docs/en/projects/project-05-grounded-qa-verification/index.md b/docs/en/projects/project-05-grounded-qa-verification/index.md
index 95647fb..fb509f0 100644
--- a/docs/en/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/en/projects/project-05-grounded-qa-verification/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/projects/project-05-grounded-qa-verification/)
+> Related lectures: [Lecture 09. Stop agents from declaring victory early](./../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) · [Lecture 10. Only a full-pipeline run counts as real verification](./../../lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)
+> Template files: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/)
+
# Project 05. Make the Agent Verify Its Own Work
## What You Do
diff --git a/docs/en/projects/project-06-runtime-observability-and-debugging/index.md b/docs/en/projects/project-06-runtime-observability-and-debugging/index.md
index 1310e9a..568936d 100644
--- a/docs/en/projects/project-06-runtime-observability-and-debugging/index.md
+++ b/docs/en/projects/project-06-runtime-observability-and-debugging/index.md
@@ -1,5 +1,8 @@
[中文版本 →](/projects/project-06-runtime-observability-and-debugging/)
+> Related lectures: [Lecture 11. Make the agent's runtime observable](./../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) · [Lecture 12. Clean handoff at the end of every session](./../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)
+> Template files: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/)
+
# Project 06. Build a Complete Agent Harness (Capstone)
## What You Do
diff --git a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md
index 8a1104c..4147f5b 100644
--- a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md
+++ b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md
@@ -1,5 +1,8 @@
[English Version →](/en/lectures/lecture-01-why-capable-agents-still-fail/)
+> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/)
+> 实战练习:[Project 01. 只写提示词让 agent 做,和定好规则再让它做,差多少](./../../projects/project-01-baseline-vs-minimal-harness/index.md)
+
# 第一讲. 模型能力强,不等于执行可靠
## 这节课要解决什么问题
diff --git a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md
index cc0bee8..aa85a80 100644
--- a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md
+++ b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md
@@ -1,5 +1,8 @@
[English Version →](/en/lectures/lecture-02-what-a-harness-actually-is/)
+> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-02-what-a-harness-actually-is/code/)
+> 实战练习:[Project 01. 只写提示词让 agent 做,和定好规则再让它做,差多少](./../../projects/project-01-baseline-vs-minimal-harness/index.md)
+
# 第二讲. Harness 到底是什么
## 这节课要解决什么问题
diff --git a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
index f942a4e..91d5fa2 100644
--- a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
+++ b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
@@ -1,5 +1,8 @@
[English Version →](/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)
+> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/)
+> 实战练习:[Project 02. 让 agent 看懂项目、接住上次的工作](./../../projects/project-02-agent-readable-workspace/index.md)
+
# 第三讲. 让代码仓库成为唯一的事实来源
## 这节课要解决什么问题
diff --git a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
index 9d0bdee..96c88f9 100644
--- a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
+++ b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
@@ -1,5 +1,8 @@
[English Version →](/en/lectures/lecture-04-why-one-giant-instruction-file-fails/)
+> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/code/)
+> 实战练习:[Project 02. 让 agent 看懂项目、接住上次的工作](./../../projects/project-02-agent-readable-workspace/index.md)
+
# 第四讲. 把指令拆分到不同文件里
## 这节课要解决什么问题
diff --git a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index e6bb270..2d4669b 100644
--- a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -1,5 +1,8 @@
[English Version →](/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/)
+> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/)
+> 实战练习:[Project 03. 让 agent 关掉再打开还能接着干](./../../projects/project-03-multi-session-continuity/index.md)
+
# 第五讲. 让跨会话的任务保持上下文连续
## 这节课要解决什么问题
diff --git a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index 4ac084e..476fc41 100644
--- a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -1,5 +1,8 @@
[English Version →](/en/lectures/lecture-06-why-initialization-needs-its-own-phase/)
+> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)
+> 实战练习:[Project 03. 让 agent 关掉再打开还能接着干](./../../projects/project-03-multi-session-continuity/index.md)
+
# 第六讲. 让 agent 每次工作前先初始化
## 这节课要解决什么问题
diff --git a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index 53d00c2..90d3ce3 100644
--- a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -1,5 +1,8 @@
[English Version →](/en/lectures/lecture-07-why-agents-overreach-and-under-finish/)
+> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/code/)
+> 实战练习:[Project 04. 用运行反馈修正 agent 的行为](./../../projects/project-04-incremental-indexing/index.md)
+
# 第七讲. 给 agent 划清每次任务的边界
## 这节课要解决什么问题
diff --git a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 7eb4f5e..e903496 100644
--- a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -1,5 +1,8 @@
[English Version →](/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/)
+> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)
+> 实战练习:[Project 04. 用运行反馈修正 agent 的行为](./../../projects/project-04-incremental-indexing/index.md)
+
# 第八讲. 用功能清单约束 agent 该做什么
## 这节课要解决什么问题
diff --git a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index f1c7100..eb49912 100644
--- a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -1,5 +1,8 @@
[English Version →](/en/lectures/lecture-09-why-agents-declare-victory-too-early/)
+> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/code/)
+> 实战练习:[Project 05. 让 agent 自己检查自己做的对不对](./../../projects/project-05-grounded-qa-verification/index.md)
+
# 第九讲. 防止 agent 提前宣告完成
## 这节课要解决什么问题
diff --git a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 656a928..7a55f6b 100644
--- a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -1,5 +1,8 @@
[English Version →](/en/lectures/lecture-10-why-end-to-end-testing-changes-results/)
+> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/code/)
+> 实战练习:[Project 05. 让 agent 自己检查自己做的对不对](./../../projects/project-05-grounded-qa-verification/index.md)
+
# 第十讲. 跑通完整流程才算真正验证
## 这节课要解决什么问题
diff --git a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 905e34f..c6af5a5 100644
--- a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -1,5 +1,8 @@
[English Version →](/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/)
+> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/)
+> 实战练习:[Project 06. 搭建一套完整的 agent 工作环境](./../../projects/project-06-runtime-observability-and-debugging/index.md)
+
# 第十一讲. 让 agent 的运行过程可观测
## 这节课要解决什么问题
diff --git a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index 2797e34..544d8c9 100644
--- a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -1,5 +1,8 @@
[English Version →](/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)
+> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/)
+> 实战练习:[Project 06. 搭建一套完整的 agent 工作环境](./../../projects/project-06-runtime-observability-and-debugging/index.md)
+
# 第十二讲. 每次会话结束前都做好交接
## 这节课要解决什么问题
diff --git a/docs/zh/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/zh/projects/project-01-baseline-vs-minimal-harness/index.md
index e8e04c4..a9d2ad4 100644
--- a/docs/zh/projects/project-01-baseline-vs-minimal-harness/index.md
+++ b/docs/zh/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -1,5 +1,8 @@
# Project 01. 只写提示词让 agent 做,和定好规则再让它做,差多少
+> 相关讲义:[L01. 模型能力强,不等于执行可靠](./../../lectures/lecture-01-why-capable-agents-still-fail/index.md) · [L02. Harness 到底是什么](./../../lectures/lecture-02-what-a-harness-actually-is/index.md)
+> 本篇模板文件:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/resources/templates/)
+
## 你要做什么
用 Electron 搭一个最简的知识库应用壳子——能启动窗口、左边显示文档列表、右边显示问答面板、本地有一个数据目录。任务本身不复杂,复杂的是你怎么让 agent 完成它。
diff --git a/docs/zh/projects/project-02-agent-readable-workspace/index.md b/docs/zh/projects/project-02-agent-readable-workspace/index.md
index bd64088..9ed60e5 100644
--- a/docs/zh/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/zh/projects/project-02-agent-readable-workspace/index.md
@@ -1,5 +1,8 @@
# Project 02. 让 agent 看懂项目、接住上次的工作
+> 相关讲义:[L03. 让代码仓库成为唯一的事实来源](./../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) · [L04. 为什么一个巨大的指令文件会失败](./../../lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)
+> 本篇模板文件:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/resources/templates/)
+
## 你要做什么
P01 证明了准备规则有用。但 P01 的任务一次会话就干完了。真实开发不是这样的——你昨天干了一半,今天开新会话,agent 得从仓库状态里搞清楚"做了什么、没做什么、接下来干什么"。
diff --git a/docs/zh/projects/project-03-multi-session-continuity/index.md b/docs/zh/projects/project-03-multi-session-continuity/index.md
index 2298113..720a509 100644
--- a/docs/zh/projects/project-03-multi-session-continuity/index.md
+++ b/docs/zh/projects/project-03-multi-session-continuity/index.md
@@ -1,5 +1,8 @@
# Project 03. 让 agent 关掉再打开还能接着干
+> 相关讲义:[L05. 为什么长时任务会丢失上下文](./../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) · [L06. 为什么初始化需要单独一个阶段](./../../lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)
+> 本篇模板文件:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/resources/templates/)
+
## 你要做什么
P02 解决了"接手"的问题,但 agent 接手之后能不能把活干完、干对了,又是另一回事。这个项目要你给 agent 加上范围控制和验证关卡。
diff --git a/docs/zh/projects/project-04-incremental-indexing/index.md b/docs/zh/projects/project-04-incremental-indexing/index.md
index 2417cc0..9d7d44c 100644
--- a/docs/zh/projects/project-04-incremental-indexing/index.md
+++ b/docs/zh/projects/project-04-incremental-indexing/index.md
@@ -1,5 +1,8 @@
# Project 04. 用运行反馈修正 agent 的行为
+> 相关讲义:[L07. 为什么 agent 会多做或少做](./../../lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) · [L08. 为什么功能清单是 harness 原语](./../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)
+> 本篇模板文件:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/resources/templates/)
+
## 你要做什么
前三个项目关注的是"让 agent 把活干完"。这个项目关注的是"出了问题怎么修"——而且不是你修,是让 agent 自己通过运行时信号来修。
diff --git a/docs/zh/projects/project-05-grounded-qa-verification/index.md b/docs/zh/projects/project-05-grounded-qa-verification/index.md
index b0d0859..5285c08 100644
--- a/docs/zh/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/zh/projects/project-05-grounded-qa-verification/index.md
@@ -1,5 +1,8 @@
# Project 05. 让 agent 自己检查自己做的对不对
+> 相关讲义:[L09. 为什么 agent 会提前宣告完成](./../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) · [L10. 为什么端到端测试会改变结果](./../../lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)
+> 本篇模板文件:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/resources/templates/)
+
## 你要做什么
前四个项目里,"检查做得对不对"这件事要么是你手动做的,要么是靠文件规则强制执行的。这个项目要让 agent 自己来检查。
diff --git a/docs/zh/projects/project-06-runtime-observability-and-debugging/index.md b/docs/zh/projects/project-06-runtime-observability-and-debugging/index.md
index c067171..2e777db 100644
--- a/docs/zh/projects/project-06-runtime-observability-and-debugging/index.md
+++ b/docs/zh/projects/project-06-runtime-observability-and-debugging/index.md
@@ -1,5 +1,8 @@
# Project 06. 搭建一套完整的 agent 工作环境
+> 相关讲义:[L11. 为什么可观测性属于 harness](./../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) · [L12. 为什么每次会话都要留干净状态](./../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)
+> 本篇模板文件:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/resources/templates/)
+
## 你要做什么
这是结业项目。把前五个项目学到的所有东西组装起来,跑一次完整的基准测试,然后做一轮清理,验证质量是可以持续维护的。