1	# AGENTS.md -- Project 01: Baseline vs Minimal Harness
2
3	## Startup Rules
4
5	Before writing any code, complete these steps in order:
6
7	1. **Read this file completely.** It defines the boundaries and conventions for this project.
8	2. **Read `docs/ARCHITECTURE.md`** to understand the Electron layer structure.
9	3. **Read `docs/PRODUCT.md`** to understand the feature requirements.
10	4. **Run `bash init.sh`** to verify the project builds cleanly. If it fails, fix build errors before proceeding.
11	5. **Read `feature_list.json`** to see the current state of all features.
12
13	## Electron Layer Boundaries
14
15	This project has four strict layers. Code must respect these boundaries:
16
17	### Main Process (`src/main/`)
18	- Owns the `BrowserWindow` lifecycle and IPC registration.
19	- Imports services but never renderer code.
20	- All filesystem access happens here via services.
21
22	### Preload (`src/preload/`)
23	- The ONLY bridge between main and renderer.
24	- Uses `contextBridge.exposeInMainWorld` to expose typed APIs.
25	- Never imports React or renderer code.
26
27	### Renderer (`src/renderer/`)
28	- React + TypeScript UI layer.
29	- Communicates with main process exclusively through `window.knowledgeBase` API.
30	- Never imports Node.js modules (`fs`, `path`, `electron`).
31	- Uses the type declarations in `types.d.ts`.
32
33	### Services (`src/services/`)
34	- Pure TypeScript business logic running in the main process.
35	- Services may import from `src/shared/` but never from `src/renderer/`.
36	- Each service receives `PersistenceService` via constructor injection.
37
38	## Conventions
39
40	- TypeScript strict mode is enabled. No `any` types without a comment explaining why.
41	- Use named exports (no default exports).
42	- IPC channel names are defined once in `src/shared/types.ts` (`IPC_CHANNELS`).
43	- All async operations return Promises; never use synchronous I/O in the renderer.
44
45	## Definition of Done
46
47	A feature is "done" when all of the following are true:
48
49	1. TypeScript compiles without errors (`npm run check`).
50	2. The app launches and the window is visible (`npm run dev`).
51	3. The feature appears in `feature_list.json` with status `"pass"` and evidence.
52	4. The code respects Electron layer boundaries defined above.
53	5. No console errors during normal operation.
54
55	## Working with the Feature List
56
57	The `feature_list.json` file is the source of truth for project progress:
58
59	- Each feature has a `status`: `"pass"`, `"fail"`, `"not-started"`.
60	- When implementing a feature, update its status to `"pass"` with evidence.
61	- If a feature is blocked, set status to `"fail"` with a reason.
62	- Never delete features from the list.
63


1	{
2	  "project": "project-01",
3	  "description": "Baseline Electron knowledge base with minimal harness",
4	  "features": [
5	    {
6	      "id": "window-launch",
7	      "name": "Window Launch",
8	      "description": "Electron app opens a BrowserWindow with correct dimensions and preload script",
9	      "status": "pass",
10	      "evidence": "npm run dev launches window at 1200x800 with contextIsolation=true and nodeIntegration=false",
11	      "testedAt": "2026-03-30T10:00:00Z"
12	    },
13	    {
14	      "id": "document-list",
15	      "name": "Document List Panel",
16	      "description": "Left sidebar shows imported documents with empty state message",
17	      "status": "pass",
18	      "evidence": "DocumentList component renders empty state when no documents, shows document cards when data present",
19	      "testedAt": "2026-03-30T10:05:00Z"
20	    },
21	    {
22	      "id": "question-panel",
23	      "name": "Question Panel",
24	      "description": "Bottom input bar accepts questions and submits via IPC",
25	      "status": "pass",
26	      "evidence": "QuestionPanel renders text input and Ask button, submits to window.knowledgeBase.qa.ask on Enter or click",
27	      "testedAt": "2026-03-30T10:08:00Z"
28	    },
29	    {
30	      "id": "data-directory",
31	      "name": "Data Directory",
32	      "description": "PersistenceService creates and manages userData/knowledge-base-data directory",
33	      "status": "pass",
34	      "evidence": "PersistenceService constructor calls ensureDirectories() creating data, documents, and index subdirectories",
35	      "testedAt": "2026-03-30T10:10:00Z"
36	    }
37	  ]
38	}
39


1	#!/usr/bin/env bash
2	# init.sh -- Verify the project builds cleanly before starting work.
3	# Run this after cloning or when resuming work.
4	set -euo pipefail
5
6	echo "=== Project 01 Init ==="
7	echo ""
8
9	echo "[1/3] Installing dependencies..."
10	npm install
11	echo ""
12
13	echo "[2/3] Running type checks..."
14	npm run check
15	echo ""
16
17	echo "[3/3] Building project..."
18	npm run build
19	echo ""
20
21	echo "=== Init complete. All checks passed. ==="
22	echo "Run 'npm run dev' to launch the application."
23


1	# claude-progress.md -- Session Log
2
3	## Project 01: Baseline vs Minimal Harness
4
5	### Session 1 -- 2026-03-30
6
7	**Duration**: ~45 minutes
8	**Goal**: Establish baseline Electron app with proper harness
9
10	**What was done**:
11	- Verified Electron window launches at 1200x800 with correct webPreferences
12	- Confirmed document list panel renders with empty state message
13	- Confirmed question panel accepts input and submits via IPC
14	- Verified PersistenceService creates data directories under userData
15	- Updated feature_list.json with all 4 features at status "pass"
16	- Wrote AGENTS.md with startup rules and layer boundaries
17	- Wrote docs/ARCHITECTURE.md describing Electron layer structure
18	- Wrote docs/PRODUCT.md describing knowledge base requirements
19
20	**Decisions**:
21	- Used constructor injection for PersistenceService to keep services testable
22	- Kept all IPC channel names in a single const object in types.ts
23	- Window title set to "Knowledge Base" for consistency
24
25	**Issues**: None
26
27	**Next session**: Proceed to Project 02 to add import, detail view, and persistence features.
28


Now let me check a more advanced project to see how harness evolves:


total 28
drwxr-xr-x 6 root root 4096 Apr  1 11:55 .
drwxr-xr-x 4 root root   54 Apr  1 11:55 ..
-rw-r--r-- 1 root root 2924 Apr  1 11:55 AGENTS.md
-rw-r--r-- 1 root root 1148 Apr  1 11:55 clean-state-checklist.md
drwxr-xr-x 3 root root   30 Apr  1 11:55 data
drwxr-xr-x 2 root root   29 Apr  1 11:55 docs
-rw-r--r-- 1 root root  799 Apr  1 11:55 package.json
drwxr-xr-x 2 root root   49 Apr  1 11:55 scripts
drwxr-xr-x 7 root root   79 Apr  1 11:55 src
-rw-r--r-- 1 root root  777 Apr  1 11:55 tsconfig.json
-rw-r--r-- 1 root root  570 Apr  1 11:55 tsconfig.node.json
-rw-r--r-- 1 root root  427 Apr  1 11:55 vite.config.ts


1	# AGENTS.md
2
3	This repository is designed for long-running coding-agent work. The goal is not
4	to maximize raw code output. The goal is to leave the repo in a state where the
5	next session can continue without guessing.
6
7	## Startup Workflow
8
9	Before writing code:
10
11	1. Confirm the working directory with `pwd`.
12	2. Read `claude-progress.md` for the latest verified state and next step.
13	3. Read `feature_list.json` and choose the highest-priority unfinished feature.
14	4. Review recent commits with `git log --oneline -5`.
15	5. Run `./init.sh`.
16	6. Run the required smoke or end-to-end verification before starting new work.
17
18	If baseline verification is already failing, fix that first. Do not stack new
19	feature work on top of a broken starting state.
20
21	## Working Rules
22
23	- Work on one feature at a time.
24	- Do not mark a feature complete just because code was added.
25	- Keep changes within the selected feature scope unless a blocker forces a
26	  narrow supporting fix.
27	- Do not silently change verification rules during implementation.
28	- Prefer durable repo artifacts over chat summaries.
29
30	## Runtime Observability
31
32	All services use structured logging via `src/services/logger.ts`. Log output is
33	JSON-formatted with timestamp, level, service name, and message. Log levels:
34	DEBUG, INFO, WARN, ERROR.
35
36	When debugging, check logs for:
37	- Service initialization events at startup
38	- IPC channel invocations and their parameters
39	- Indexing chunk counts and content lengths
40	- Q&A confidence scores and citation counts
41
42	## Architecture Constraints
43
44	The following layer boundaries are enforced by `scripts/check-architecture.sh`:
45
46	- **Renderer** must not import `fs`, `path`, or any Node.js core modules.
47	- **Services** must not import Electron IPC or renderer-specific modules.
48	- **Preload** must only expose the typed API via contextBridge.
49
50	Run `bash scripts/check-architecture.sh` before committing.
51
52	## Required Artifacts
53
54	- `feature_list.json`: source of truth for feature state
55	- `claude-progress.md`: session log and current verified status
56	- `init.sh`: standard startup and verification path
57	- `session-handoff.md`: optional compact handoff for larger sessions
58	- `clean-state-checklist.md`: pre-commit repository health check
59
60	## Definition Of Done
61
62	A feature is done only when all of the following are true:
63
64	- the target behavior is implemented
65	- the required verification actually ran
66	- evidence is recorded in `feature_list.json` or `claude-progress.md`
67	- the repository remains restartable from the standard startup path
68	- `scripts/check-architecture.sh` passes with no violations
69
70	## End Of Session
71
72	Before ending a session:
73
74	1. Update `claude-progress.md`.
75	2. Update `feature_list.json`.
76	3. Record any unresolved risk or blocker.
77	4. Run `bash scripts/check-architecture.sh`.
78	5. Commit with a descriptive message once the work is in a safe state.
79	6. Leave the repo clean enough for the next session to run `./init.sh`
80	   immediately.
81


1	# Clean State Checklist
2
3	Run this checklist before committing and at the end of each session.
4
5	## Build
6
7	- [ ] `npm run check` passes with no type errors
8	- [ ] `npm run build` completes successfully
9
10	## Architecture
11
12	- [ ] `bash scripts/check-architecture.sh` passes with no violations
13	- [ ] No `fs` or `path` imports in renderer code
14	- [ ] No Electron IPC in service code
15	- [ ] No React imports in services or main process
16
17	## Runtime
18
19	- [ ] Application starts without errors (`npm run dev`)
20	- [ ] Structured log output appears in console at startup
21	- [ ] Document import works (check logs for IMPORT_DOCUMENT event)
22	- [ ] Indexing works for documents of all sizes
23	- [ ] Q&A returns answers with citations (check logs for ASK_QUESTION event)
24
25	## Data Integrity
26
27	- [ ] No empty chunks in indexed documents (verify with GET_CHUNKS)
28	- [ ] Q&A history persists across restarts
29	- [ ] Document metadata is consistent with actual files
30
31	## Repository
32
33	- [ ] No unintended files in git status
34	- [ ] No sensitive data (.env, credentials) staged
35	- [ ] `claude-progress.md` updated with current state
36	- [ ] `feature_list.json` reflects actual feature status
37


Now let me check the resources section for templates:


total 8
drwxr-xr-x 5 root root   79 Apr  1 11:55 .
drwxr-xr-x 5 root root   71 Apr  1 11:55 ..
-rw-r--r-- 1 root root 2163 Apr  1 11:55 index.md
drwxr-xr-x 4 root root   55 Apr  1 11:55 openai-advanced
drwxr-xr-x 2 root root  145 Apr  1 11:55 reference
drwxr-xr-x 2 root root 4096 Apr  1 11:55 templates


total 52
drwxr-xr-x 2 root root 4096 Apr  1 11:55 .
drwxr-xr-x 5 root root   79 Apr  1 11:55 ..
-rw-r--r-- 1 root root 1949 Apr  1 11:55 AGENTS.md
-rw-r--r-- 1 root root 1408 Apr  1 11:55 CLAUDE.md
-rw-r--r-- 1 root root  561 Apr  1 11:55 claude-progress.md
-rw-r--r-- 1 root root  357 Apr  1 11:55 clean-state-checklist.md
-rw-r--r-- 1 root root  791 Apr  1 11:55 evaluator-rubric.md
-rw-r--r-- 1 root root 2007 Apr  1 11:55 feature_list.json
-rw-r--r-- 1 root root 9165 Apr  1 11:55 index.md
-rwxr-xr-x 1 root root  664 Apr  1 11:55 init.sh
-rw-r--r-- 1 root root 1508 Apr  1 11:55 quality-document.md
-rw-r--r-- 1 root root  488 Apr  1 11:55 session-handoff.md


1	# Template Guide
2
3	These templates are ready to copy into your own project. Each one serves a specific purpose in the agent's workflow. Edit the contents to match your project's commands, paths, feature names, and verification steps.
4
5	## How to Get Started
6
7	Copy these four files into your project root first:
8
9	1. `AGENTS.md` or `CLAUDE.md`
10	2. `init.sh`
11	3. `claude-progress.md`
12	4. `feature_list.json`
13
14	Add the remaining files as your project grows.
15
16	---
17
18	## AGENTS.md
19
20	The root instruction file. This is the first thing the agent reads when it starts a session. It defines the operating rules: what to do before writing code, how to work, and how to wrap up.
21
22	**How to use it:**
23
24	- Copy to your project root directory
25	- Replace the startup workflow steps with your actual project paths and commands
26	- Adjust the working rules to match your team's conventions
27	- Keep the definition of done section — it's the most important part
28
29	**What it does for the agent:**
30
31	- Tells it to read progress and feature state before starting work
32	- Forces it to work on one feature at a time
33	- Requires evidence before marking anything as done
34	- Defines what a clean end-of-session looks like
35
36	Use `AGENTS.md` for Codex or other agents. Use `CLAUDE.md` if you're working with Claude Code — the structure is the same, just formatted for Claude's instruction style.
37
38	## init.sh
39
40	The startup script. Runs dependency installation, verification, and prints the start command — all in one shot.
41
42	**How to use it:**
43
44	- Copy to your project root
45	- Edit these three variables at the top:
46	  - `INSTALL_CMD` — your dependency install command (e.g. `npm install`, `pip install -r requirements.txt`)
47	  - `VERIFY_CMD` — your basic verification command (e.g. `npm test`, `pytest`)
48	  - `START_CMD` — your dev server start command (e.g. `npm run dev`)
49	- Make it executable: `chmod +x init.sh`
50
51	**What it does:**
52
53	1. Prints the current directory (so you can confirm it's running in the right place)
54	2. Installs dependencies
55	3. Runs the verification command
56	4. Prints the start command (or runs it if `RUN_START_COMMAND=1` is set)
57
58	If verification fails, the agent should stop and fix the baseline before doing anything else.
59
60	## claude-progress.md
61
62	The progress log. Every session writes to this file, and every new session reads it first.
63
64	**How to use it:**
65
66	- Copy to your project root
67	- Fill in the "Current Verified State" section with your project's info
68	- After each session, update the session record
69
70	**What each field means:**
71
72	- **Current Verified State** — the single source of truth for where the project stands
73	  - `Repository root directory` — where the project lives
74	  - `Standard startup path` — the command to get the project running
75	  - `Standard verification path` — the command to run tests
76	  - `Highest priority unfinished feature` — what the next session should work on
77	  - `Current blocker` — anything that's stuck
78	- **Session Record** — one entry per session
79	  - `Goal` — what you planned to do
80	  - `Completed` — what actually got done
81	  - `Verification run` — what tests were executed
82	  - `Evidence recorded` — what proof was captured
83	  - `Commits` — what was committed
84	  - `Known risks` — what might be broken
85	  - `Next best action` — where the next session should start
86
87	## feature_list.json
88
89	The feature tracker. A machine-readable list of every feature the agent needs to implement, along with its status, verification steps, and evidence.
90
91	**How to use it:**
92
93	- Copy to your project root
94	- Replace the example features with your own
95	- Each feature needs:
96	  - `id` — a short unique identifier
97	  - `priority` — integer, lower = higher priority
98	  - `area` — which part of the app (e.g. "chat", "import", "search")
99	  - `title` — short description
100	  - `user_visible_behavior` — what the user should see when it works
101	  - `status` — one of `not_started`, `in_progress`, `blocked`, `passing`
102	  - `verification` — step-by-step instructions to confirm it works
103	  - `evidence` — recorded proof that verification passed (filled in by the agent)
104	  - `notes` — any extra context
105
106	**Status rules:**
107
108	- `not_started` — hasn't been touched
109	- `in_progress` — the one feature currently being worked on (only one at a time)
110	- `blocked` — can't proceed due to a documented issue
111	- `passing` — verification passed and evidence is recorded
112
113	The agent should only have one feature in `in_progress` at any time.
114
115	## session-handoff.md
116
117	A compact handoff note between sessions. Use this when a session ends and you want the next one to pick up quickly.
118
119	**How to use it:**
120
121	- Copy to your project root
122	- Fill it out at the end of each session (or have the agent fill it out)
123
124	**What each section covers:**
125
126	- **Currently verified** — what's confirmed working and what verification was run
127	- **Changes this session** — what code or infrastructure changed
128	- **Still broken or unverified** — known issues and risky areas
129	- **Next best action** — what the next session should do, and what not to touch
130	- **Commands** — startup, verification, and debug commands for quick reference
131
132	This file is optional for small sessions. It becomes important when sessions are long or when the project has multiple active areas.
133
134	## clean-state-checklist.md
135
136	A checklist to run through before ending each session. Makes sure the repo is in a good state for the next session to start cleanly.
137
138	**How to use it:**
139
140	- Copy to your project root
141	- Run through it before you close a session
142	- The agent should also check these items as part of its end-of-session routine
143
144	**What it checks:**
145
146	- Standard startup still works
147	- Standard verification still runs
148	- Progress log is updated
149	- Feature list reflects actual state (no false `passing` entries)
150	- No half-finished work left unrecorded
151	- Next session can continue without manual fixes
152
153	## evaluator-rubric.md
154
155	A scorecard for reviewing agent output quality. Use this after a session or at project milestones to evaluate whether the work meets the bar.
156
157	**How to use it:**
158
159	- Copy to your project root
160	- After a session (or a set of sessions), score the agent's work across six dimensions
161	- Each dimension is scored 0-2
162
163	**The six dimensions:**
164
165	1. **Correctness** — does the implementation match the target behavior?
166	2. **Verification** — were the required checks actually run, with evidence?
167	3. **Scope discipline** — did the agent stay within the selected feature?
168	4. **Reliability** — does the result survive a restart or re-run?
169	5. **Maintainability** — is the code and documentation clear enough for the next session?
170	6. **Handoff readiness** — can a new session continue using only repo artifacts?
171
172	**Conclusion options:**
173
174	- Accept — meets the bar
175	- Revise — needs fixes before accepting
176	- Block — fundamental issues that need to be resolved first
177
178	**Important: the evaluator needs tuning.** Out of the box, agents are poor self-judges — they identify issues then talk themselves into approving. You will need to iterate:
179
180	1. Run the evaluator on a completed sprint.
181	2. Compare its scores against your own human judgment.
182	3. Where they diverge, make the rubric more specific about pass/fail criteria.
183	4. Re-run and check alignment.
184	5. Repeat until the evaluator consistently matches human review.
185
186	Plan for 3-5 tuning rounds. Record each change so you can track what improved alignment.
187
188	## quality-document.md
189
190	A quality snapshot that grades each product domain and architectural layer in your project. Tracks codebase health over time, not just individual session output.
191
192	**How to use it:**
193
194	- Copy to your project root
195	- Before starting a session: read it to understand where the codebase is weakest
196	- After a session: update grades based on what changed
197	- Over time: compare snapshots to see which harness changes actually improved codebase health
198
199	**What it grades:**
200
201	- **Product domains** (e.g., document import, Q&A flow, indexing): each domain gets a grade (A-D) across verification status, agent legibility, test stability, and key gaps
202	- **Architectural layers** (e.g., main process, preload, renderer, services): each layer gets a grade for boundary enforcement and agent legibility
203
204	**Why it matters:**
205
206	The evaluator rubric scores individual agent outputs. The quality document scores the codebase itself. They answer different questions:
207
208	- Evaluator rubric: "Did the agent do good work this session?"
209	- Quality document: "Is the project getting stronger or weaker over time?"
210
211	**When to update:**
212
213	- After each significant session
214	- Before benchmark comparisons
215	- After cleanup or simplification passes
216	- When onboarding a new agent or model to the project
217
218	**Harness simplification tie-in:**
219
220	The quality document also supports harness simplification. Every harness component encodes an assumption about what the model cannot do. As models improve, these assumptions go stale. To check whether a component is still needed:
221
222	1. Take a quality document snapshot.
223	2. Remove one harness component.
224	3. Run the benchmark task suite.
225	4. Take another snapshot.
226	5. Compare — if grades didn't drop, the component was overhead. If they did, restore it.
227


Let me read a few more key templates and check the remaining lectures briefly:


1	{
2	  "project": "replace-with-project-name",
3	  "last_updated": "YYYY-MM-DD",
4	  "rules": {
5	    "single_active_feature": true,
6	    "passing_requires_evidence": true,
7	    "do_not_skip_verification": true
8	  },
9	  "status_legend": {
10	    "not_started": "Work has not begun.",
11	    "in_progress": "The feature is the current active task.",
12	    "blocked": "Work cannot continue until a documented blocker is resolved.",
13	    "passing": "Required verification has passed and evidence is recorded."
14	  },
15	  "features": [
16	    {
17	      "id": "chat-001",
18	      "priority": 1,
19	      "area": "chat",
20	      "title": "Create a new conversation",
21	      "user_visible_behavior": "A user can click New Chat and see a fresh empty conversation.",
22	      "status": "not_started",
23	      "verification": [
24	        "Open the app.",
25	        "Click New Chat.",
26	        "Verify a new conversation appears in the sidebar.",
27	        "Verify the main panel shows an empty conversation state."
28	      ],
29	      "evidence": [],
30	      "notes": ""
31	    },
32	    {
33	      "id": "chat-002",
34	      "priority": 2,
35	      "area": "chat",
36	      "title": "Send a message in the current conversation",
37	      "user_visible_behavior": "A user can submit a message and see it appear in the active thread.",
38	      "status": "not_started",
39	      "verification": [
40	        "Open an existing conversation.",
41	        "Type a message into the input.",
42	        "Submit the message.",
43	        "Verify the new message appears in the thread."
44	      ],
45	      "evidence": [],
46	      "notes": ""
47	    },
48	    {
49	      "id": "chat-003",
50	      "priority": 3,
51	      "area": "chat",
52	      "title": "Persist the active conversation list",
53	      "user_visible_behavior": "A user sees previously created conversations after restarting the app.",
54	      "status": "not_started",
55	      "verification": [
56	        "Create two conversations.",
57	        "Restart the app.",
58	        "Verify both conversations still appear in the sidebar."
59	      ],
60	      "evidence": [],
61	      "notes": ""
62	    }
63	  ]
64	}
65


1	# AGENTS.md
2
3	This repository is designed for long-running coding-agent work. The goal is not
4	to maximize raw code output. The goal is to leave the repo in a state where the
5	next session can continue without guessing.
6
7	## Startup Workflow
8
9	Before writing code:
10
11	1. Confirm the working directory with `pwd`.
12	2. Read `claude-progress.md` for the latest verified state and next step.
13	3. Read `feature_list.json` and choose the highest-priority unfinished feature.
14	4. Review recent commits with `git log --oneline -5`.
15	5. Run `./init.sh`.
16	6. Run the required smoke or end-to-end verification before starting new work.
17
18	If baseline verification is already failing, fix that first. Do not stack new
19	feature work on top of a broken starting state.
20
21	## Working Rules
22
23	- Work on one feature at a time.
24	- Do not mark a feature complete just because code was added.
25	- Keep changes within the selected feature scope unless a blocker forces a
26	  narrow supporting fix.
27	- Do not silently change verification rules during implementation.
28	- Prefer durable repo artifacts over chat summaries.
29
30	## Required Artifacts
31
32	- `feature_list.json`: source of truth for feature state
33	- `claude-progress.md`: session log and current verified status
34	- `init.sh`: standard startup and verification path
35	- `session-handoff.md`: optional compact handoff for larger sessions
36
37	## Definition Of Done
38
39	A feature is done only when all of the following are true:
40
41	- the target behavior is implemented
42	- the required verification actually ran
43	- evidence is recorded in `feature_list.json` or `claude-progress.md`
44	- the repository remains restartable from the standard startup path
45
46	## End Of Session
47
48	Before ending a session:
49
50	1. Update `claude-progress.md`.
51	2. Update `feature_list.json`.
52	3. Record any unresolved risk or blocker.
53	4. Commit with a descriptive message once the work is in a safe state.
54	5. Leave the repo clean enough for the next session to run `./init.sh`
55	   immediately.
56


Now let me quickly read the remaining lectures summaries:


Bash

for lecture in /root/projects/learn-harness-engineering/docs/en/lectures/lecture-09-*/index.md /root/projects/learn-harness-engineering/docs/en/lectures/lecture-10-*/index.md /root/projects/learn-harness-engineering/docs/en/lectures/lecture-11-*/index.md /root/projects/learn-harness-engineering/docs/en/lectures/lecture-12-*/index.md; do echo "=== $(basename $(dirname $lecture)) ==="; head -80 "$lecture" | tail -75; echo ""; done


=== lecture-09-why-agents-declare-victory-too-early ===
# Lecture 09. Stop Agents from Declaring Victory Early

## What Problem Does This Lecture Solve?

You ask the agent to implement a "password reset" feature. It modifies the database schema, writes the API endpoint, adds email templates, runs the unit tests (all green), and confidently tells you "done." But when you actually test it — the reset link can't be sent (email service config missing), the database migration fails halfway through (schema inconsistency), and the end-to-end flow was never exercised once.

This isn't a random event. Guo et al.'s classic 2017 ICML paper proved that **modern neural networks are systematically overconfident** — the model's reported confidence significantly exceeds its actual accuracy. AI coding agents are no different: they "feel" done when they're far from it. Your harness must replace the agent's "feeling" with externalized, execution-based verification.

## Core Concepts

- **Premature completion declaration**: The agent asserts the task is done, but correctness specifications remain unsatisfied. Core issue: the agent judges based on local code-level confidence; system-level correctness requires global verification.
- **Confidence calibration gap**: The systematic difference between the agent's self-reported completion confidence and actual completion quality. For complex multi-file tasks, this gap is significantly positive — agents are always more confident than they should be.
- **Termination criteria**: A set of explicit, executable judgment conditions defined in the harness. The agent must satisfy all conditions before declaring completion. "Done" transforms from a subjective judgment to an objective determination.
- **Verification-Validation dual gate**: First layer (verification) checks "does the code correctly implement the specified behavior"; second layer (validation) checks "does the system-level behavior meet end-to-end requirements." Both must pass.
- **Runtime feedback signals**: Logs, process states, health checks from program execution. These are the harness's objective basis for judging completion quality — not optional debugging tools.
- **Completion priority constraint**: Verify functional correctness first, then performance, then style. No refactoring allowed until core functionality is verified.

## Why This Happens

### The Four-Step Slippery Slope of Agent Completion

Premature completion declarations almost always follow the same sequence:

1. **Local code looks fine**: Syntax is correct, logic seems reasonable. No obvious errors at the static inspection level.
2. **Runtime behavior insufficiently observed**: The harness didn't require comprehensive execution verification, so the agent skipped actually running the code or only ran partial tests.
3. **Verification skipped or incomplete**: Ran unit tests but skipped integration tests, or ran tests without checking coverage adequacy.
4. **Completion assertion based on insufficient evidence**: "The code looks fine" is treated as evidence of "feature complete."

Every step loses information. From task specification to code implementation to runtime behavior, each transition can introduce bias, and every skipped verification widens the information asymmetry.

### Unit Tests Passing != Task Complete

This is the most common trap. The agent writes code, runs unit tests, all green, then says "done." But unit tests are designed to isolate the unit under test and mock dependencies — exactly the philosophy that makes them unable to detect cross-component issues:

- **Interface mismatch**: A calls B with correctly-formatted parameters, but B's actual behavior doesn't match A's assumptions. Each unit test passes separately; together they break.
- **State propagation errors**: A database migration changed the table structure, but the cache layer still holds entries with the old structure. Unit tests don't test cross-layer state.
- **Environment dependency**: Code behaves correctly in the test environment (everything mocked) but fails in the real environment due to config differences, network latency, or unavailable services.

### "Refactoring While You're at It" Poisons Completion

Claude Code has a common behavior pattern: it starts refactoring code, optimizing performance, or improving style before the core functionality has passed verification. Knuth's "premature optimization is the root of all evil" takes on new meaning for agents — refactoring changes the boundary between verified and unverified code, potentially breaking code paths that were implicitly correct.

## How to Do It Right

### 1. Externalize Termination Judgment

Completion judgment shouldn't be made by the agent itself. The harness independently executes termination checks, taking runtime signals as input — not the agent's confidence. Write in CLAUDE.md:

```
## Definition of Done
- Feature complete = end-to-end verification passes, NOT "code is written"
- Required verification levels:
  1. Unit tests pass
  2. Integration tests pass
  3. End-to-end flow verification passes
- Don't proceed to level 2 until level 1 passes
- Don't proceed to level 3 until level 2 passes
```

### 2. Build a Three-Layer Termination Check

- **Layer 1: Syntax and static analysis**. Lowest cost, least information, but must pass.
- **Layer 2: Runtime behavior verification**. Test execution, application startup checks, critical path verification. This is the core completion evidence.
- **Layer 3: System-level validation**. End-to-end tests, integration verification, user scenario simulation. The last line of defense against premature declarations.

### 3. Design Error Messages for Agents

OpenAI's Codex practice highlights a particularly effective pattern: **error messages written for agents should include repair guidance.** Don't use `"Test failed"` — use `"Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html."` This specific, actionable feedback lets the agent self-correct without human intervention.

### 4. Concrete Forms of Runtime Signals

Effective runtime signals include:

- Did the application successfully start and reach a ready state?
- Do critical feature paths execute successfully at runtime?

=== lecture-10-why-end-to-end-testing-changes-results ===
# Lecture 10. Only a Full-Pipeline Run Counts as Real Verification

## What Problem Does This Lecture Solve?

You ask the agent to add a file export feature to an Electron app. It writes the renderer component, preload script, and service layer logic. Unit tests for each component pass. The agent says "done." You click the export button — wrong file path format, progress bar doesn't respond, memory leak on large files. Five component boundary defects, and unit tests caught zero of them.

Google's test pyramid tells us: lots of unit tests form the base, but if you stop there, you'll systematically miss component interaction issues. For AI coding agents, this problem is worse — agents tend to run the fastest tests and then declare completion. **Only end-to-end tests provide a stronger proof of system-level defect absence** than unit tests alone.

## Core Concepts

- **Component boundary defects**: Components A and B each pass unit tests individually, but their interaction produces incorrect behavior. This is the defect category end-to-end tests excel at catching.
- **Test adequacy gradient**: Defects detectable by unit tests <= defects detectable by integration tests <= defects detectable by end-to-end tests. Each layer up strengthens detection capability.
- **Architecture boundary enforcement rules**: Turn architecture document rules (like "renderer process can't directly access the filesystem") into executable automated checks.
- **Review feedback promotion**: Transform recurring code review comments into automated tests. Each newly captured defect category adds a permanent defense line — the harness automatically gets stronger over time.
- **Agent-oriented error messages**: Failure messages don't just say "what went wrong" — they tell the agent exactly how to fix it. This turns test failures into self-correcting feedback loops.

## Why This Happens

### Unit Tests' Blind Spots

Unit tests are designed around isolation — mock dependencies, focus on the unit under test. This philosophy makes unit tests fast and precise, but creates systematic blind spots:

**Interface mismatch**: The renderer passes relative file paths to the preload script, but the preload expects absolute paths. Each unit test uses mocks, each passes. Only an end-to-end run reveals the mismatch.

**State propagation errors**: A database migration changed the table structure, but the ORM's cache layer still holds entries with the old structure. Unit tests create fresh mock environments for each test and never expose this cross-layer state inconsistency.

**Resource lifecycle issues**: File handles, database connections, and network sockets are acquired and released across multiple components. Unit tests create and destroy independent resources per test, never exposing resource races or leaks.

**Environment dependency**: Code behaves correctly in the test environment (everything mocked) but fails in the real environment due to config differences, network latency, or service unavailability.

### End-to-End Testing Changes Agent Behavior Too

When the agent knows its work will be verified by end-to-end tests, its coding behavior changes:

1. **Considers component interactions**: Writes code thinking "how does this interface connect with upstream" rather than focusing only on individual functions.
2. **Respects architecture boundaries**: In systems with architecture constraints, end-to-end tests force the agent to respect boundary rules.
3. **Handles error paths**: End-to-end tests typically include failure scenarios, forcing the agent to think about error handling.

OpenAI's Codex engineering practice emphasizes: **error messages written for agents must include repair guidance.** Don't write `"Direct filesystem access in renderer"` — write `"Direct filesystem access in renderer. All file operations must go through the preload bridge. Move this call to preload/file-ops.ts and invoke it via window.api."` This turns architecture rules into a self-correcting loop.

### Review Feedback Promotion: Making the Harness Stronger Over Time

Human reviewers often give the same type of feedback repeatedly. Review feedback promotion turns this pattern into system improvement:

1. Identify recurring comment types in code review logs
2. Transform comments into executable regex patterns, AST patterns, or runtime assertions
3. Write automated checks with agent-oriented error messages
4. Integrate into the harness verification flow
5. Validate effectiveness with benchmark tasks

Every captured defect category adds a permanent defense line. The harness automatically strengthens over time.

## How to Do It Right

### 1. The Harness Must Include an End-to-End Layer

In your verification flow, make it explicit: for tasks involving cross-component modifications, end-to-end test passing is a prerequisite for completion. Write in CLAUDE.md:

```
## Verification Levels
- Level 1: Unit tests (must pass)
- Level 2: Integration tests (must pass)
- Level 3: End-to-end tests (must pass for cross-component changes)
- Skipping any required level = task not complete
```

### 2. Make Architecture Rules Executable

Every architecture constraint should have a corresponding test or lint rule:

```bash
# Check if renderer process directly calls Node.js APIs
grep -r "require('fs')" src/renderer/ && exit 1 || echo "OK: no direct fs access in renderer"
```

=== lecture-11-why-observability-belongs-inside-the-harness ===
# Lecture 11. Make the Agent's Runtime Observable

## What Problem Does This Lecture Solve?

You ask an agent to implement a feature. It runs for 20 minutes, modifies a bunch of files, then tells you "done, but two tests are failing." You ask why they're failing — "not sure, might be a timing issue." You ask which critical paths it changed — "let me look at the code..."

This isn't about the agent lacking capability. It's about your harness not providing enough observability. **Without observability, agents make decisions under uncertainty, evaluations become subjective judgments, and retries become blind wandering.** Both OpenAI and Anthropic define reliability as an evidence problem — the harness must expose runtime behavior and evaluation signals in a form that can guide the next decision.

## Core Concepts

- **Runtime observability**: System-level signals — logs, traces, process events, health checks. Answers "what did the system do."
- **Process observability**: Visibility into harness decision artifacts — plans, scoring rubrics, acceptance criteria. Answers "why should this change be accepted."
- **Task trace**: A complete decision-path record from task start to completion, analogous to request tracing in distributed systems. Every step the agent takes, with context, is recorded.
- **Sprint contract**: A short-term agreement negotiated before coding begins — specifying task scope, verification standards, and exclusions. The core tool for process observability.
- **Evaluator rubric**: Transforms quality evaluation from subjective judgment into evidence-based structured scoring. Makes different evaluators produce similar results for the same output.
- **Layered observability**: System-layer and process-layer observability designed simultaneously and reinforcing each other. Runtime signals explain behavior; process artifacts explain intent.

## Why This Happens

### The Real Cost of Missing Observability

When a harness lacks observability, four types of problems systematically appear:

**Cannot distinguish "correct" from "looks correct"**: A function looks perfectly right during code review — correct syntax, sound logic. But at runtime, an edge case handling error produces incorrect results under specific inputs. Only runtime traces can reveal that the actual execution path deviated from expectations.

**Evaluation becomes mysticism**: Without scoring rubrics and acceptance criteria, evaluators (human or agent) rely on implicit assumptions. The same output might get wildly different evaluations from different assessors. Quality assessment becomes non-reproducible.

**Retries become blind guesses**: When the agent doesn't know why something failed, retry direction is random. It might try repeatedly in the wrong direction — fixing unrelated code paths while ignoring the actual failure root cause. Every blind retry costs tokens and time.

**Session handoff information cliff**: When incomplete work is handed to the next session, missing observability means the new session must diagnose system state from scratch. Anthropic's long-running agent observations show this redundant diagnosis can consume 30-50% of total session time.

### A Real Claude Code Scenario

Imagine a harness using a "planner-generator-evaluator" three-role workflow, executing an "add dark mode to the app" task.

**Without observability**: The planner outputs a vague description. The generator implements dark mode based on that vagueness, but it doesn't match the planner's implicit expectations. The evaluator rejects based on their own implicit standards but can't articulate what's specifically wrong. The generator retries blindly based on vague rejection reasons. The cycle repeats 3-4 times, taking about 45 minutes, producing a barely acceptable output.

**With full observability**: The planner outputs a sprint contract — listing which components to modify, verification standards for each, and exclusions (no print styles). The generator implements according to the contract. Runtime observability records each component's style loading and application process. The evaluator uses a scoring rubric to evaluate dimension by dimension, with specific evidence citations. One iteration produces a high-quality result, in about 15 minutes.

3x efficiency difference. The only change is observability.

### Why Agents Can't Solve This Themselves

You might be thinking: "Can't the agent just print its own logs?" The problems are:

1. The agent doesn't know what it doesn't know — it won't proactively record signals it doesn't realize it needs.
2. Log formats are inconsistent — different sessions use different log formats, making systematic analysis impossible.
3. Process observability can't be solved by logs — sprint contracts and scoring rubrics are structured artifacts that need harness-level support.

## How to Do It Right

### 1. Build Runtime Signal Collection into the Harness

Don't rely on the agent to print its own logs. The harness should automatically collect these signals:

- **Application lifecycle**: Startup, ready, running, shutdown phase states
- **Feature path execution**: Records of critical path execution, including entry points, checkpoints, and exits
- **Data flow**: Records of data flowing between components
- **Resource utilization**: Abnormal resource usage patterns (e.g., continuously growing memory)
- **Errors and exceptions**: Full error context, not just error messages

### 2. Implement Sprint Contracts

Before each task starts, the generator and evaluator (which may be different invocations of the same agent) negotiate a contract:

```markdown
# Sprint Contract: Dark Mode Support

## Scope
- Modify the theme toggle component
- Update global CSS variables
- Add dark mode tests

## Verification Standards
- Visual regression tests pass for each component

=== lecture-12-why-every-session-must-leave-a-clean-state ===
# Lecture 12. Clean Handoff at the End of Every Session

## What Problem Does This Lecture Solve?

Your agent runs all afternoon, modifies 20 files, commits the code, session ends. The next agent session starts and immediately discovers: build is broken, tests are red, temporary debug files are everywhere, the feature list wasn't updated, and progress is completely unclear. The new session spends its first 30 minutes just figuring out "what did the last session actually do."

Both OpenAI and Anthropic state clearly: **long-term reliability depends on operational discipline, not just single-run success.** The quality of state at session exit directly determines the next session's efficiency. Think of it like Git best practices — every commit should be an atomic, compilable change, not a pile of half-finished code.

## Core Concepts

- **Clean state**: The system satisfies five conditions at session end — build passes, tests pass, progress recorded, no stale artifacts, startup path available. Missing any one means the session isn't "done."
- **Session integrity**: Analogous to database transactions — either fully commit and leave a clean state, or roll back to the last consistent state. No middle ground.
- **Quality document**: An active artifact that continuously records quality ratings for each module. Not a one-time assessment, but a tracker showing whether the codebase is getting stronger or weaker over time.
- **Cleanup loop**: A regular maintenance session aimed at systematically reducing entropy in the codebase. Not an emergency fix, but routine operations.
- **Harness simplification**: As model capabilities improve, periodically remove harness components that are no longer necessary. A constraint essential today may be unnecessary overhead in three months.
- **Idempotent cleanup**: Cleanup operations produce the same result regardless of how many times they run. Ensures cleanup remains safe even in failure-retry scenarios.

## Why This Happens

### Entropy Growth Is the Default State

Lehman's laws of software evolution tell us: systems undergoing continuous change will inevitably increase in complexity unless actively managed. This is especially true for AI coding agents — every session introduces changes, and without cleanup at exit, technical debt accumulates exponentially.

Real data is telling. A project developed with agents for 12 weeks, without cleanup strategy:

- Week 1: Build pass rate 100%, test pass rate 100%, new session startup 5 min
- Week 4: Build 95%, tests 92%, startup 15 min
- Week 8: Build 82%, tests 78%, startup 35 min
- Week 12: Build 68%, tests 61%, startup 60+ min

Same project with a cleanup strategy:

- Week 1: 100%, 100%, 5 min
- Week 12: 97%, 95%, 9 min

After 12 weeks: build pass rate differs by 29 percentage points, new session startup time differs by 85%. This is not theoretical — it's an observed difference.

### Five Dimensions of Clean State

Clean state isn't just "the code compiles." It's five dimensions evaluated together:

**Build dimension**: Does the code build without errors? This is the most basic — the next session shouldn't have to fix build errors first.

**Test dimension**: Do all tests pass? Including tests that existed before the session — the session is responsible for not breaking existing functionality. And it should be verified in CI, not just "works on my machine."

**Progress dimension**: Is current progress recorded in a machine-readable artifact? Completed subtasks with their passing criteria, in-progress but incomplete subtasks with current state, not-yet-started subtasks. Good progress records reduce 60-80% of session startup diagnostic time.

**Artifact dimension**: Are there stale or ambiguous temporary artifacts? Debug logs, temporary files, commented-out code, TODO markers — all of these increase cognitive load for the next session.

**Startup dimension**: Is the standard startup path available? Can the next session start working without manual intervention? Environment initialization, codebase loading, context acquisition, task selection — these paths must not be broken.

### "Clean Up Later" Means Never Clean Up

The most common mental trap is "no time to clean up this session, I'll do it next time." But the next agent session doesn't know what you left behind — it sees a mess of code and uncertain state. It'll spend significant time inferring "which parts of this code are intentional and which are temporary."

Worse, every session has its own task objectives. The new session is there to do new work, not clean up the previous session's mess. It'll ignore the chaos and start new work on top of it, introducing more chaos on top of chaos. This is entropy's positive feedback loop.

## How to Do It Right

### 1. Clean State as a Completion Requirement

Define explicitly in the harness: **session completion = task passes verification AND clean state check passes.** Missing either one means the session isn't complete. Write in CLAUDE.md:

```
## Session Exit Checklist
- [ ] Build passes (npm run build)
- [ ] All tests pass (npm test)
- [ ] Feature list updated
- [ ] No debug code remaining (console.log, debugger, TODO)
- [ ] Standard startup path available (npm run dev)
```

### 2. Dual-Mode Cleanup Strategy

Combine two cleanup modes:


Perfect! Now let me check the VitePress configuration to understand the full curriculum:


1	import { defineConfig } from "vitepress";
2
3	const docsBase = process.env.DOCS_BASE_PATH ?? "/";
4
5	const zhLectureItems = [
6	  { text: "L01. 模型能力强，不等于执行可靠", link: "/zh/lectures/lecture-01-why-capable-agents-still-fail/" },
7	  { text: "L02. Harness 的定义", link: "/zh/lectures/lecture-02-what-a-harness-actually-is/" },
8	  { text: "L03. 让代码仓库成为唯一的事实来源", link: "/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },
9	  { text: "L04. 把指令拆分到不同文件里", link: "/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/" },
10	  { text: "L05. 让跨会话的任务保持上下文连续", link: "/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },
11	  { text: "L06. 让 agent 每次工作前先初始化", link: "/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/" },
12	  { text: "L07. 给 agent 划清每次任务的边界", link: "/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/" },
13	  { text: "L08. 用功能清单约束 agent 该做什么", link: "/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },
14	  { text: "L09. 防止 agent 提前宣告完成", link: "/zh/lectures/lecture-09-why-agents-declare-victory-too-early/" },
15	  { text: "L10. 跑通完整流程才算真正验证", link: "/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/" },
16	  { text: "L11. 让 agent 的运行过程可观测", link: "/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },
17	  { text: "L12. 每次会话结束前都做好交接", link: "/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }
18	];
19
20	const zhProjectItems = [
21	  { text: "P01. 只写提示词让 agent 做，和定好规则再让它做，差多少", link: "/zh/projects/project-01-baseline-vs-minimal-harness/" },
22	  { text: "P02. 让 agent 看懂项目、接住上次的工作", link: "/zh/projects/project-02-agent-readable-workspace/" },
23	  { text: "P03. 让 agent 关掉再打开还能接着干", link: "/zh/projects/project-03-multi-session-continuity/" },
24	  { text: "P04. 用运行反馈修正 agent 的行为", link: "/zh/projects/project-04-incremental-indexing/" },
25	  { text: "P05. 让 agent 自己检查自己做的对不对", link: "/zh/projects/project-05-grounded-qa-verification/" },
26	  { text: "P06. 搭建一套完整的 agent 工作环境", link: "/zh/projects/project-06-runtime-observability-and-debugging/" }
27	];
28
29	const zhResourceItems = [
30	  { text: "资料库总览", link: "/zh/resources/" },
31	  { text: "中文模板", link: "/zh/resources/templates/" },
32	  { text: "中文参考", link: "/zh/resources/reference/" },
33	  { text: "高级资源包", link: "/zh/resources/openai-advanced/" },
34	  { text: "English Templates", link: "/en/resources/templates/" },
35	  { text: "English Reference", link: "/en/resources/reference/" }
36	];
37
38	const enLectureItems = [
39	  { text: "Lecture 01. Why Capable Agents Still Fail", link: "/en/lectures/lecture-01-why-capable-agents-still-fail/" },
40	  { text: "Lecture 02. What a Harness Actually Is", link: "/en/lectures/lecture-02-what-a-harness-actually-is/" },
41	  { text: "Lecture 03. Why the Repository Must Become the System of Record", link: "/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },
42	  { text: "Lecture 04. Why One Giant Instruction File Fails", link: "/en/lectures/lecture-04-why-one-giant-instruction-file-fails/" },
43	  { text: "Lecture 05. Why Long-Running Tasks Lose Continuity", link: "/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },
44	  { text: "Lecture 06. Why Initialization Needs Its Own Phase", link: "/en/lectures/lecture-06-why-initialization-needs-its-own-phase/" },
45	  { text: "Lecture 07. Why Agents Overreach and Under-Finish", link: "/en/lectures/lecture-07-why-agents-overreach-and-under-finish/" },
46	  { text: "Lecture 08. Why Feature Lists Are Harness Primitives", link: "/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },
47	  { text: "Lecture 09. Why Agents Declare Victory Too Early", link: "/en/lectures/lecture-09-why-agents-declare-victory-too-early/" },
48	  { text: "Lecture 10. Why End-to-End Testing Changes Results", link: "/en/lectures/lecture-10-why-end-to-end-testing-changes-results/" },
49	  { text: "Lecture 11. Why Observability Belongs Inside the Harness", link: "/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },
50	  { text: "Lecture 12. Why Every Session Must Leave a Clean State", link: "/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }
51	];
52
53	const enProjectItems = [
54	  { text: "Project 01. Prompt-Only vs. Rules-First", link: "/en/projects/project-01-baseline-vs-minimal-harness/" },
55	  { text: "Project 02. Agent-Readable Workspace", link: "/en/projects/project-02-agent-readable-workspace/" },
56	  { text: "Project 03. Multi-Session Continuity", link: "/en/projects/project-03-multi-session-continuity/" },
57	  { text: "Project 04. Runtime Feedback and Scope Control", link: "/en/projects/project-04-incremental-indexing/" },
58	  { text: "Project 05. Self-Verification and Role Separation", link: "/en/projects/project-05-grounded-qa-verification/" },
59	  { text: "Project 06. Complete Harness (Capstone)", link: "/en/projects/project-06-runtime-observability-and-debugging/" }
60	];
61
62	const enResourceItems = [
63	  { text: "Overview", link: "/en/resources/" },
64	  { text: "English Templates", link: "/en/resources/templates/" },
65	  { text: "English Reference", link: "/en/resources/reference/" },
66	  { text: "Advanced Pack", link: "/en/resources/openai-advanced/" },
67	  { text: "中文模板", link: "/zh/resources/templates/" },
68	  { text: "中文参考", link: "/zh/resources/reference/" }
69	];
70
71	export default defineConfig({
72	  base: docsBase,
73	  title: "Learn Harness Engineering",
74	  description:
75	    "A project-based course on designing the environments, state, verification, and control systems that make Codex and Claude Code reliable.",
76	  cleanUrls: true,
77	  srcExclude: ["temp/**"],
78	  ignoreDeadLinks: true,
79	  locales: {
80	    root: {
81	      label: "简体中文",
82	      lang: "zh-CN",
83	      themeConfig: {
84	        nav: [
85	          { text: "首页", link: "/" },
86	          { text: "中文", link: "/zh/" },
87	          { text: "English", link: "/en/" }
88	        ],
89	        sidebar: [],
90	        socialLinks: [{ icon: "github", link: "https://github.com/walkinglabs/learn-harness-engineering" }]
91	      }
92	    },
93	    zh: {
94	      label: "简体中文",
95	      lang: "zh-CN",
96	      link: "/zh/",
97	      themeConfig: {
98	        nav: [
99	          { text: "首页", link: "/zh/" },
100	          { text: "讲义", link: zhLectureItems[0].link },
101	          { text: "项目", link: zhProjectItems[0].link },
102	          { text: "资料库", link: "/zh/resources/" }
103	        ],
104	        sidebar: [
105	          {
106	            text: "讲义",
107	            items: zhLectureItems
108	          },
109	          {
110	            text: "项目",
111	            items: zhProjectItems
112	          },
113	          {
114	            text: "资料库",
115	            items: zhResourceItems
116	          }
117	        ],
118	        outline: {
119	          level: [2, 3]
120	        },
121	        docFooter: {
122	          prev: "上一篇",
123	          next: "下一篇"
124	        },
125	        lastUpdated: {
126	          text: "最后更新于"
127	        },
128	        returnToTopLabel: "回到顶部",
129	        sidebarMenuLabel: "菜单",
130	        darkModeSwitchLabel: "主题",
131	        lightModeSwitchTitle: "切换到浅色模式",
132	        darkModeSwitchTitle: "切换到深色模式",
133	        socialLinks: [{ icon: "github", link: "https://github.com/walkinglabs/learn-harness-engineering" }]
134	      }
135	    },
136	    en: {
137	      label: "English",
138	      lang: "en",
139	      link: "/en/",
140	      themeConfig: {
141	        nav: [
142	          { text: "Home", link: "/en/" },
143	          { text: "Lectures", link: enLectureItems[0].link },
144	          { text: "Projects", link: enProjectItems[0].link },
145	          { text: "Library", link: "/en/resources/" }
146	        ],
147	        sidebar: [
148	          {
149	            text: "Lectures",
150	            items: enLectureItems
151	          },
152	          {
153	            text: "Projects",
154	            items: enProjectItems
155	          },
156	          {
157	            text: "Resource Library",
158	            items: enResourceItems
159	          }
160	        ],
161	        outline: {
162	          level: [2, 3]
163	        },
164	        docFooter: {
165	          prev: "Previous page",
166	          next: "Next page"
167	        },
168	        lastUpdated: {
169	          text: "Last updated"
170	        },
171	        returnToTopLabel: "Return to top",
172	        sidebarMenuLabel: "Menu",
173	        darkModeSwitchLabel: "Appearance",
174	        lightModeSwitchTitle: "Switch to light theme",
175	        darkModeSwitchTitle: "Switch to dark theme"
176	      }
177	    }
178	  },
179	  themeConfig: {
180	    search: {
181	      provider: "local"
182	    },
183	    socialLinks: [{ icon: "github", link: "https://github.com/walkinglabs/learn-harness-engineering" }]
184	  }
185	});
186


Excellent! Now let me examine one more project example to see how the harness evolves:


total 48
drwxr-xr-x 6 root root 4096 Apr  1 11:55 .
drwxr-xr-x 4 root root   54 Apr  1 11:55 ..
-rw-r--r-- 1 root root 3465 Apr  1 11:55 AGENTS.md
-rw-r--r-- 1 root root 3217 Apr  1 11:55 claude-progress.md
-rw-r--r-- 1 root root 1994 Apr  1 11:55 clean-state-checklist.md
drwxr-xr-x 3 root root   30 Apr  1 11:55 data
drwxr-xr-x 2 root root   47 Apr  1 11:55 docs
-rw-r--r-- 1 root root 4329 Apr  1 11:55 feature_list.json
-rwxr-xr-x 1 root root  473 Apr  1 11:55 init.sh
-rw-r--r-- 1 root root  845 Apr  1 11:55 package.json
drwxr-xr-x 2 root root   20 Apr  1 11:55 scripts
-rw-r--r-- 1 root root 3575 Apr  1 11:55 session-handoff.md
drwxr-xr-x 7 root root   79 Apr  1 11:55 src
-rw-r--r-- 1 root root  777 Apr  1 11:55 tsconfig.json
-rw-r--r-- 1 root root  570 Apr  1 11:55 tsconfig.node.json
-rw-r--r-- 1 root root  427 Apr  1 11:55 vite.config.ts


1	{
2	  "project": "project-03",
3	  "description": "Scope control and grounded verification with indexing, metadata, and grounded QA",
4	  "features": [
5	    {
6	      "id": "window-launch",
7	      "name": "Window Launch",
8	      "description": "Electron app opens a BrowserWindow with correct dimensions and preload script",
9	      "status": "pass",
10	      "evidence": "Carried over from P2 -- verified working",
11	      "testedAt": "2026-03-30T10:00:00Z"
12	    },
13	    {
14	      "id": "document-list",
15	      "name": "Document List Panel",
16	      "description": "Left sidebar shows imported documents with empty state message",
17	      "status": "pass",
18	      "evidence": "Carried over from P2 -- verified working",
19	      "testedAt": "2026-03-30T10:05:00Z"
20	    },
21	    {
22	      "id": "question-panel",
23	      "name": "Question Panel",
24	      "description": "Bottom input bar accepts questions and submits via IPC",
25	      "status": "pass",
26	      "evidence": "Carried over from P2 -- verified working",
27	      "testedAt": "2026-03-30T10:08:00Z"
28	    },
29	    {
30	      "id": "data-directory",
31	      "name": "Data Directory",
32	      "description": "PersistenceService creates and manages userData/knowledge-base-data directory",
33	      "status": "pass",
34	      "evidence": "Carried over from P2 -- verified working",
35	      "testedAt": "2026-03-30T10:10:00Z"
36	    },
37	    {
38	      "id": "document-import",
39	      "name": "Document Import",
40	      "description": "Users can import .txt and .md files via ImportPanel with file picker",
41	      "status": "pass",
42	      "evidence": "Carried over from P2 -- verified working",
43	      "testedAt": "2026-03-30T11:00:00Z"
44	    },
45	    {
46	      "id": "document-detail",
47	      "name": "Document Detail with Content",
48	      "description": "DocumentDetail shows full document content, metadata, and delete button",
49	      "status": "pass",
50	      "evidence": "Carried over from P2 -- verified working",
51	      "testedAt": "2026-03-30T11:15:00Z"
52	    },
53	    {
54	      "id": "basic-persistence",
55	      "name": "Basic Persistence",
56	      "description": "Imported documents persist across app restarts via filesystem storage",
57	      "status": "pass",
58	      "evidence": "Carried over from P2 -- verified working",
59	      "testedAt": "2026-03-30T11:30:00Z"
60	    },
61	    {
62	      "id": "document-chunking",
63	      "name": "Document Chunking",
64	      "description": "IndexingService splits documents into ~500 char chunks at paragraph boundaries with metadata",
65	      "status": "pass",
66	      "evidence": "IndexingService.chunkDocument() splits on paragraph boundaries, merges paragraphs until ~500 chars, creates Chunk objects with charCount/wordCount metadata. Verified: indexing:start IPC creates chunks/<docId>.json files.",
67	      "testedAt": "2026-03-30T12:30:00Z"
68	    },
69	    {
70	      "id": "metadata-extraction",
71	      "name": "Metadata Extraction",
72	      "description": "On import, extract word count, line count, file type, and paragraph count metadata from documents",
73	      "status": "pass",
74	      "evidence": "DocumentService.importDocument() calls extractMetadata() to compute wordCount, lineCount, fileType, paragraphCount, charCount. Document metadata field populated on import. DocumentDetail displays metadata section.",
75	      "testedAt": "2026-03-30T12:15:00Z"
76	    },
77	    {
78	      "id": "indexing-status-ui",
79	      "name": "Indexing Status in StatusBar",
80	      "description": "StatusBar shows indexing progress with indexed count, total chunks, and color-coded status indicator",


Perfect! Now let me check the session-handoff to see how continuity is documented:


1	# Session Handoff -- Project 03
2
3	## Last Session: 2026-03-30
4
5	### What Was Accomplished
6
7	1. **Metadata Extraction** -- Enhanced DocumentService with metadata extraction on import:
8	   - Added `DocumentMetadata` interface to shared types (wordCount, lineCount, fileType, paragraphCount, charCount)
9	   - `DocumentService.extractMetadata()` analyzes content on import
10	   - DocumentDetail component displays metadata section
11	   - Feature implemented one at a time per AGENTS.md policy
12
13	2. **Document Chunking** -- IndexingService chunking pipeline is fully working:
14	   - `chunkDocument()` splits content into ~500-char chunks at paragraph boundaries
15	   - Each chunk includes charCount and wordCount metadata
16	   - Chunks stored as JSON in `chunks/<docId>.json`
17	   - Index meta tracks which documents have been indexed
18	   - Update to document status after indexing (imported -> indexed)
19
20	3. **Indexing Status UI** -- StatusBar shows real-time indexing progress:
21	   - Color-coded status dot: gray (idle), yellow (indexing), green (ready), red (error)
22	   - Displays indexed document count and total chunk count
23	   - AppStatus type extended with indexedCount and totalChunks
24	   - App.tsx refreshes status after import and indexing operations
25
26	4. **Grounded Q&A with Citations** -- QaService returns grounded answers:
27	   - Keyword-based retrieval scores chunks by query overlap
28	   - Top 2 relevant chunks returned as citations with documentId, title, chunkIndex, excerpt
29	   - Mock answer patterns for common topics (design, import, indexing, meetings)
30	   - Confidence scores: 0.85 with citations, 0.30 without
31	   - Q&A history persisted to qa-history.json
32
33	### What Remains
34
35	No remaining features for Project 03. All 11 features in feature_list.json are at status "pass".
36
37	### Decisions Made
38
39	- Metadata is extracted at import time rather than lazily to ensure it is always available.
40	- Chunking uses paragraph-aware splitting (double newlines) to avoid breaking sentences.
41	- The one-feature-at-a-time policy from AGENTS.md was followed strictly: each feature was implemented, verified, and recorded before moving to the next.
42	- IndexingService receives a reference from main.ts to ensure QaService can access it for chunk retrieval.
43
44	### Files Modified
45
46	- `src/shared/types.ts` -- Added DocumentMetadata interface, extended AppStatus with indexedCount/totalChunks
47	- `src/services/document-service.ts` -- Added extractMetadata(), metadata populated on import
48	- `src/services/indexing-service.ts` -- Full chunking implementation with paragraph-aware splitting
49	- `src/services/qa-service.ts` -- Keyword retrieval, citations, confidence scoring, mock patterns
50	- `src/services/persistence-service.ts` -- No changes, inherited from P2
51	- `src/main/main.ts` -- Updated service wiring to pass indexingService to qaService
52	- `src/main/ipc-handlers.ts` -- No new IPC channels needed, existing channels sufficient
53	- `src/preload/preload.ts` -- No changes needed
54	- `src/renderer/App.tsx` -- Added metadata-aware refresh, status polling
55	- `src/renderer/components/DocumentDetail.tsx` -- Metadata display section
56	- `src/renderer/components/StatusBar.tsx` -- Enhanced with indexed count, total chunks, color indicator
57	- `AGENTS.md` -- Added one-feature-at-a-time policy and feature dependency graph
58	- `feature_list.json` -- All features marked pass with evidence
59	- `docs/ARCHITECTURE.md` -- Added chunking pipeline and Q&A flow sections
60	- `docs/PRODUCT.md` -- Updated with new features
61
62	### Blockers
63
64	None.
65
66	### Next Steps
67
68	Proceed to Project 04 to add test infrastructure and automated verification.
69


Perfect! I have comprehensive information now. Let me compile a detailed report for the user:

## Comprehensive Harness Engineering Best Practices Report

Based on my thorough exploration of the learn-harness-engineering project, here are the key findings:

---

## **KEY PRINCIPLES OF HARNESS ENGINEERING**

The course teaches that **model capability and execution reliability are fundamentally different things**. A strong model in a terrible harness still fails. The "harness" is everything outside the model—instructions, tools, environment, state management, and verification feedback.

### Core Principle Stack

The five subsystems of a harness (from Lecture 02):

1. **Instructions** - Tell the agent what to do, in what order, and what to read
2. **Tools** - Agent access to environments and commands
3. **Environment** - Self-describing project state, dependencies, versions
4. **State** - Persistent progress tracking across sessions
5. **Feedback** - Verification commands and runtime signals

The weakest subsystem determines overall effectiveness. Lecture 02 shows real data: a TypeScript/React frontend went from 20% success rate (minimal harness) to 80-100% (full five-tuple harness) by systematically improving each subsystem.

---

## **WHAT FILES MAKE UP A GOOD HARNESS**

A complete harness consists of these artifacts (found in `/root/projects/learn-harness-engineering/docs/en/resources/templates/` and demonstrated in project solutions):

### **Core Required Files** (4 files minimum)

1. **`AGENTS.md`** (or `CLAUDE.md` for Claude Code) — The routing/entry file
   - **Path example**: `/root/projects/learn-harness-engineering/projects/project-01/solution/AGENTS.md`
   - **Purpose**: First thing the agent reads; defines startup workflow, working rules, definition of done
   - **Content**:
     - Startup checklist (read progress, read features, run init.sh)
     - Working rules (one feature at a time, no overreach)
     - Hard constraints (15 or fewer global rules, at top/bottom to avoid "lost in the middle" effect)
     - Required artifacts list
     - Definition of Done (completion criteria: code written + verification ran + evidence recorded)
   - **Size**: 50-200 lines (template is 56 lines)
   - **Key rule**: Don't stuff everything here. Use it as a router pointing to topic docs.

2. **`init.sh`** — Bootstrap script
   - **Path example**: `/root/projects/learn-harness-engineering/projects/project-01/solution/init.sh`
   - **Purpose**: Standardized startup path; agents run this at session start
   - **Content**:
     - `npm install` (or equivalent dependency installation)
     - `npm run check` (type checking)
     - `npm run build` (build verification)
   - **Why**: Ensures baseline is clean before agents start work; includes verification steps upfront

3. **`feature_list.json`** — Machine-readable task state tracker
   - **Path example**: `/root/projects/learn-harness-engineering/projects/project-01/solution/feature_list.json`
   - **Purpose**: Single source of truth for project state; essential for scope control
   - **Structure**:
     ```json
     {
       "project": "project-name",
       "features": [
         {
           "id": "F01",
           "behavior": "User can do X",
           "verification": "curl -X POST ... | jq .status == 201",
           "status": "passing",  // not_started, in_progress, blocked, passing
           "evidence": "commit abc123"
         }
       ]
     }
     ```
   - **Rules**:
     - Each feature has a triple: (behavior, verification command, status)
     - Only ONE feature can be `in_progress` at a time (WIP=1)
     - Status moves to `passing` only when verification actually succeeds
     - Pass-state gating: harness controls transitions, agent can't force it

4. **`claude-progress.md`** — Session continuity log
   - **Path example**: `/root/projects/learn-harness-engineering/projects/project-01/solution/claude-progress.md`
   - **Purpose**: Cross-session continuity artifact; every new session reads this first
   - **Content**:
     - Current verified state (commit hash, test status)
     - Completed features (with evidence)
     - In-progress features (with blockers)
     - Known issues
     - Next steps
   - **Timing**: Updated before every session ends

### **Advanced Optional Files** (add as project grows)

5. **`session-handoff.md`** — Compact handoff for complex sessions
   - **Path example**: `/root/projects/learn-harness-engineering/projects/project-03/solution/session-handoff.md`
   - **Content**: What was accomplished, what remains, decisions made, files modified, blockers, next steps
   - **When to use**: Sessions longer than 45 minutes or complex multi-feature work

6. **`clean-state-checklist.md`** — Pre-commit validation
   - **Path example**: `/root/projects/learn-harness-engineering/projects/project-04/solution/clean-state-checklist.md`
   - **Purpose**: Verify repo health before ending session
   - **Checks**:
     - [ ] Build passes
     - [ ] Tests pass
     - [ ] No debug code (console.log, debugger)
     - [ ] No untracked files
     - [ ] Progress files updated
     - [ ] Architecture constraints met

7. **Architecture docs** (e.g., `docs/ARCHITECTURE.md`) — Layer boundaries
   - Describes module responsibilities and constraints
   - Placed next to code it describes (not in a giant central doc)

8. **`evaluator-rubric.md`** — Quality scorecard
   - Grades work across 6 dimensions: correctness, verification, scope discipline, reliability, maintainability, handoff readiness
   - Used to evaluate agent output quality systematically

---

## **KEY PATTERNS AND BEST PRACTICES**

### **Pattern 1: Progressive Disclosure (Lecture 04)**

**Problem**: Giant 600-line AGENTS.md causes "lost in the middle" effect (critical info at line 300 is ignored by models).

**Solution**: Three-layer instruction structure:
- **Layer 1 (Routing file)**: AGENTS.md, 50-200 lines, only overview + hard constraints + links
- **Layer 2 (Topic documents)**: `docs/api-patterns.md`, `docs/database-rules.md`, loaded on demand
- **Layer 3 (Inline)**: Comments in code where constraints apply

**Real example from Lecture 04**: SaaS team reduced AGENTS.md from 600 to 80 lines by splitting into topic docs. Result: success rate 45% → 72%, security compliance 60% → 95%.

### **Pattern 2: Work-in-Progress Limit (Lecture 07)**

**Problem**: Agents activate 5 features at once, finish 0 completely (overreach + under-finish).

**Solution**: Enforce WIP=1 in AGENTS.md:
```
## Work Rules
- Work on one feature at a time
- Only start next feature after current passes verification
- Don't refactor feature B while implementing feature A
```

**Data from Lecture 07**:
- Unconstrained: agent produces 800 lines across 12 files, 20% end-to-end pass rate (only 1 of 5 features work)
- WIP=1: agent produces 200 lines, 100% pass rate for completed features, 7 of 8 total features complete

**Key metric**: Verified Completion Rate (VCR) = verified tasks / activated tasks. Keep this at 1.0.

### **Pattern 3: Feature List as Harness Primitive (Lecture 08)**

**Problem**: Unstructured progress notes ("mostly done cart, still need payments") lead to duplicate work and missed requirements.

**Solution**: Feature list is not a document, it's a data structure the harness executes against:
- Scheduler reads states, picks next `not_started` feature
- Verifier executes verification commands, controls state transitions
- Handoff reporter auto-generates summaries
- Progress tracker provides health metrics

**Granularity rule**: Scope each feature to "completable in one session" (~1 hour of focused work).

### **Pattern 4: ACID State Management (Lecture 03)**

Apply database transaction principles to agent state:
- **Atomicity**: Each logical operation gets one git commit; `git stash` to rollback
- **Consistency**: Define "consistent state" predicates (all tests pass, lint clean); verify before committing
- **Isolation**: Concurrent agents use separate branches or feature files
- **Durability**: Critical knowledge in git-tracked files (not just session memory)

### **Pattern 5: Three-Layer Verification (Lecture 09)**

Don't accept unit tests as evidence of completion:
- **Layer 1**: Unit tests (fastest, most blind spots)
- **Layer 2**: Integration tests (catches component boundary issues)
- **Layer 3**: End-to-end tests (catches system-level defects)

**Required**: All three must pass before marking feature as "passing".

### **Pattern 6: Multi-Artifact Continuity (Lecture 05)**

Long tasks spanning sessions require:
- **Progress file**: Current state, tests passing, next steps
- **Decision log**: Why was option B chosen over A?
- **Git commits**: Checkpoint statements
- **Init workflow**: Written in AGENTS.md

**Real data from Lecture 05**:
- Without artifacts: 7 of 12 features complete, rebuild cost 15 min per session
- With artifacts: 12 of 12 features complete, rebuild cost 3 min per session

### **Pattern 7: Dedicated Initialization Phase (Lecture 06)**

Don't mix initialization with feature implementation:

**Initialization output** (no business code):
1. Runnable environment
2. Verifiable test framework (≥1 passing test proves it works)
3. Bootstrap contract document
4. Task breakdown file
5. Git checkpoint

**Result**: Next session spends <3 min understanding state instead of 20 min re-exploring.

### **Pattern 8: Observable Runtime (Lecture 11)**

Without runtime observability, agents make blind decisions:
- Structured logging (JSON format with timestamp, level, service name)
- Process tracing (which paths executed, what data flowed)
- Health checks (startup events, IPC invocations, critical path execution)

**Example from project-04**: `src/services/logger.ts` provides structured logging; AGENTS.md tells agents to check logs for service init, IPC calls, indexing chunk counts.

### **Pattern 9: Clean State Exits (Lecture 12)**

Every session must end in a clean state:
```
Before session end:
1. Update claude-progress.md
2. Update feature_list.json
3. Run bash scripts/check-architecture.sh
4. Commit all completed work
5. Verify: `npm run build && npm test` both pass
```

**Metric that matters**: Can the next session run `./init.sh` immediately and continue? Yes = clean state.

**Data from Lecture 12**: Projects with cleanup strategy: build pass rate 97% in week 12. Without: 68%.

---

## **WHAT A COMPLETE HARNESS LOOKS LIKE IN PRACTICE**

### **Project 01 Baseline** (minimal harness)
- **Path**: `/root/projects/learn-harness-engineering/projects/project-01/solution/`
- **Contains**:
  - AGENTS.md (startup rules, layer boundaries, definition of done)
  - CLAUDE.md (quick reference for Claude Code)
  - feature_list.json (4 features, all passing)
  - init.sh (verify dependencies, type-check, build)
  - claude-progress.md (session log with decisions and next steps)
  - docs/ARCHITECTURE.md (4 Electron layers and their contracts)
  - docs/PRODUCT.md (feature requirements)
- **Verification**: npm run check (type-check), npm run dev (launch), npm test (tests)
- **Result**: Baseline agent success rate ~60-70%

### **Project 03 Multi-Session Example** (intermediate harness)
- **Path**: `/root/projects/learn-harness-engineering/projects/project-03/solution/`
- **Adds over P01**:
  - session-handoff.md (detailed handoff with decisions and files modified)
  - clean-state-checklist.md (20-item health check)
  - **feature_list.json**: 11 features with detailed evidence
    - Metadata Extraction — "extractMetadata() analyzes content, DocumentDetail displays metadata"
    - Document Chunking — "chunks stored as JSON in chunks/<docId>.json with charCount/wordCount"
    - Indexing Status UI — "color-coded status indicator, indexed count, total chunks"
    - Grounded Q&A — "keyword retrieval returns top 2 chunks as citations with confidence scoring"
  - **Architecture enforcement**: scripts/check-architecture.sh validates layer boundaries
- **Key decision documented**: "Metadata extracted at import time (not lazily) to ensure availability"
- **Result**: Agent success rate ~80-90%, rebuild time <3 min

### **Project 04 Full Harness** (advanced harness)
- **Path**: `/root/projects/learn-harness-engineering/projects/project-04/solution/`
- **Key additions**:
  - AGENTS.md explicitly covers: startup workflow, working rules, runtime observability, architecture constraints, required artifacts, definition of done, end-of-session checklist
  - Structured logging via `src/services/logger.ts` with DEBUG/INFO/WARN/ERROR levels
  - Verification script (`scripts/check-architecture.sh`) to enforce no fs/path in renderer, no Electron in services
  - clean-state-checklist.md with runtime verification section: "Structured log output appears at startup", "Document import works (check logs for IMPORT_DOCUMENT event)"
  - Feature list tracks: window launch, document list, question panel, data directory, document import, detail view, persistence, chunking, metadata, indexing UI, Q&A, history
- **Architecture constraints enforced at commit time**: No "pushing broken code and fixing later"
- **Result**: Agent success rate ~90%+, multi-session reliability very high

---

## **TEMPLATES AND REFERENCE ARTIFACTS**

All templates available at: `/root/projects/learn-harness-engineering/docs/en/resources/templates/`

1. **AGENTS.md template** (56 lines) — Startup workflow, working rules, definition of done
2. **init.sh template** — Standardized install, verify, build steps
3. **claude-progress.md template** — Current state, session record structure
4. **feature_list.json template** — Feature schema with behavior, verification, status triple
5. **session-handoff.md template** — Accomplishments, decisions, blockers, next steps
6. **clean-state-checklist.md template** — Build, tests, architecture, runtime, data, repo checks
7. **evaluator-rubric.md template** — 6-dimension quality scorecard
8. **quality-document.md template** — Codebase health grades per domain and layer

---

## **THE 12-LECTURE CURRICULUM STRUCTURE**

The course is organized around **5 failure modes that harnesses prevent**:

1. **Lecture 01**: Why models fail (5 defense layers: task spec, context, environment, verification, state)
2. **Lectures 02-04**: Build the five-subsystem harness (instructions split across files)
3. **Lectures 05-06**: Maintain continuity (state persistence, dedicated initialization)
4. **Lectures 07-08**: Control scope (WIP=1, feature lists as primitives)
5. **Lectures 09-10**: Verify completion (three-layer verification, end-to-end tests)
6. **Lectures 11-12**: Observe and clean (runtime observability, clean state exits)

---

## **KEY METRICS THAT MATTER**

- **Verified Completion Rate** (VCR) = features passing verification / features activated
- **Rebuild cost** = minutes needed for new session to reach working state (target: <3 min)
- **Feature completion rate** = features passing / total features (compare with/without harness)
- **Verification gap** = (agent says done but actually broken) / total tasks
- **Knowledge visibility gap** = (critical info outside repo) / (total critical info)

---

## **CRITICAL INSIGHTS FROM THE COURSE**

1. **Same model, different harnesses = order-of-magnitude difference**: Anthropic's experiment shows Opus 4.5 with bare prompt = $9, 20 min, broken output; same model with full harness = $200, 6 hours, working application.

2. **"Add a rule" is a slippery slope**: Each time something fails, agents naturally want to add a rule to AGENTS.md. But this bloats the file and introduces the "lost in the middle" effect. Solution: split into topic documents.

3. **Feature lists are not planning tools**: They're data structures the harness executes against. The agent can't change feature states; the harness does, based on verification results.

4. **Unit tests passing ≠ task complete**: Component boundary defects are invisible to unit tests. Only integration + end-to-end tests catch them.

5. **Initialization is its own phase**: Mixing initialization with feature work leads to incomplete infrastructure. Spend one session on init (no business code), then subsequent sessions fly.

6. **Session handoff is not optional**: Without progress files + decision logs, every new session re-explores the project. Handoff artifacts reduce startup time from 15 min to 3 min.

7. **Clean state is a completion requirement**: If the repo builds broken or tests fail, the session isn't done. This forces agents to leave clean checkpoints.

---

## **FILE PATH SUMMARY**

**Core lectures** (understand these in order):
- `/root/projects/learn-harness-engineering/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md`
- `/root/projects/learn-harness-engineering/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md`
- `/root/projects/learn-harness-engineering/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md`
- `/root/projects/learn-harness-engineering/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md`

**Complete example harnesses** (working implementations):
- Project 01 (minimal): `/root/projects/learn-harness-engineering/projects/project-01/solution/`
- Project 03 (intermediate): `/root/projects/learn-harness-engineering/projects/project-03/solution/`
- Project 04 (full): `/root/projects/learn-harness-engineering/projects/project-04/solution/`

**Templates** (copy-paste starting points):
- `/root/projects/learn-harness-engineering/docs/en/resources/templates/`

**VitePress config** (curriculum overview):
- `/root/projects/learn-harness-engineering/docs/.vitepress/config.mts` (12 lectures, 6 projects, all organized)