Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
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.tsnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 loopsdiff --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.mdnew file mode 100644index 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 successdiff --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.mdindex 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.mdnew file mode 100644index 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.tsnew file mode 100644index 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.mdnew file mode 100644index 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 setupsdiff --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.tsnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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 placementdiff --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.txtnew file mode 100644index 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.tsnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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 sessiondiff --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.mdnew file mode 100644index 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 contextdiff --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.mdnew file mode 100644index 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 patternsdiff --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.tsnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 patternsdiff --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.mdnew file mode 100644index 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 paneldiff --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.tsnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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 scaffoldingdiff --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.tsnew file mode 100644index 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.shnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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 surfacesdiff --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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 actiondiff --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.tsnew file mode 100644index 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.mdindex 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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 examplesdiff --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.mdnew file mode 100644index 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 statediff --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.mdindex 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.mdnew file mode 100644index 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 immediatelydiff --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.mdnew file mode 100644index 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 examplesdiff --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.tsnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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.tsnew file mode 100644index 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.mdnew file mode 100644index 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 messagesdiff --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.mdnew file mode 100644index 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 boundarydiff --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.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 comparisonsdiff --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.tsnew file mode 100644index 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.mdnew file mode 100644index 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 viewdiff --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.mdindex 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.mdnew file mode 100644index 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.tsnew file mode 100644index 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.mdnew file mode 100644index 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 cleanupdiff --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.tsnew file mode 100644index 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.mdnew file mode 100644index 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 runsdiff --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.mdindex 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.mdindex 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 Dodiff --git a/docs/en/projects/project-02-agent-readable-workspace/index.md b/docs/en/projects/project-02-agent-readable-workspace/index.mdindex 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 Dodiff --git a/docs/en/projects/project-03-multi-session-continuity/index.md b/docs/en/projects/project-03-multi-session-continuity/index.mdindex 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 Dodiff --git a/docs/en/projects/project-04-incremental-indexing/index.md b/docs/en/projects/project-04-incremental-indexing/index.mdindex 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 Dodiff --git a/docs/en/projects/project-05-grounded-qa-verification/index.md b/docs/en/projects/project-05-grounded-qa-verification/index.mdindex 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 Dodiff --git a/docs/en/projects/project-06-runtime-observability-and-debugging/index.md b/docs/en/projects/project-06-runtime-observability-and-debugging/index.mdindex 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 Dodiff --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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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/)+## 你要做什么这是结业项目。把前五个项目学到的所有东西组装起来,跑一次完整的基准测试,然后做一轮清理,验证质量是可以持续维护的。