Skip to content

Harness engineering beginner tutorial, from 0 to 1

Align project docs with checked-in code

sanbuphybb0f2486e914
diff --git a/docs/ar/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/ar/projects/project-01-baseline-vs-minimal-harness/index.md
index e1aac95..c1c2d85 100644
--- a/docs/ar/projects/project-01-baseline-vs-minimal-harness/index.md
+++ b/docs/ar/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -11,7 +11,7 @@
ستنفذها مرتين. المرة الأولى: prompt فقط، دون تحضير. المرة الثانية: مع وضع `AGENTS.md` و `init.sh` و `feature_list.json` مسبقًا في المستودع. ثم قارن.
-جوهر هذا المشروع ليس كتابة الكود، بل قياس الفرق بين "قضاء 15 دقيقة في تحضير القواعد أولًا" و"ترك الوكيل يعمل مباشرة".
+يستخدم سيناريو الدورة هذا فترة قصيرة من إعادة الاكتشاف/التحضير كمثال، لا كنتيجة قياس ثابتة.
## الأدوات
@@ -23,3 +23,14 @@
## آلية harness
Harness بسيط: `AGENTS.md` + `init.sh` + `feature_list.json`
+
+## استخدم المشروع المضمَّن في المستودع
+
+مسار المشروع في المستودع: `projects/project-01/`
+
+| المجلد | ماذا يحتوي | كيف تستخدمه / ماذا تقارن |
+|------|------|------|
+| `starter/` | تشغيل الـ harness الضعيف. يحتوي فقط على `task-prompt.md` كوصف للمهمة ولا يتضمن `AGENTS.md` أو `feature_list.json`. | قدّم الـ prompt لوكيلك وقِس ما الذي ينجزه بدون أي هيكلة إضافية. |
+| `solution/` | نفس جزء المنتج مع ملفات harness صريحة: `AGENTS.md` و`CLAUDE.md` و`init.sh` و`feature_list.json` و`claude-progress.md`. | قارن كيف تجعل القواعد والتحقق نفس المهمة قابلة للتنفيذ والقياس. |
+
+الميزات الأربع الملموسة هي: تشغيل النافذة، قائمة المستندات، لوحة الأسئلة/الأجوبة، وإنشاء مجلد البيانات المحلي. راجع `solution/feature_list.json` لمعرفة الدليل المتوقع لكل ميزة.
diff --git a/docs/ar/projects/project-02-agent-readable-workspace/index.md b/docs/ar/projects/project-02-agent-readable-workspace/index.md
index 08afcdb..006a418 100644
--- a/docs/ar/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/ar/projects/project-02-agent-readable-workspace/index.md
@@ -11,6 +11,15 @@
ستنفذه مرتين: الأولى دون مساعدة، والثانية مع وضع `ARCHITECTURE.md` و `PRODUCT.md` و `session-handoff.md` مسبقًا في المستودع.
+## استخدم المشروع الموجود في المستودع
+
+مسار المستودع: `projects/project-02/`
+
+| المجلد | ماذا يحتوي | ماذا تقارن |
+|------|------|------|
+| `starter/` | كود Project 01 مع import المستندات، عرض التفاصيل، و persistence غير مكتملة بعد. توجد وثائق لكنها أخف، ولا يوجد `session-handoff.md`. | مقدار السياق الذي تحتاج الجلسة الثانية من الوكيل إلى اكتشافه من جديد. |
+| `solution/` | نفس جزء المنتج مكتمل، مع وثائق handoff تحت `projects/project-02/solution/`، بالإضافة إلى `feature_list.json` و `session-handoff.md`. | هل تستطيع جلسة جديدة المتابعة اعتمادًا على حالة المستودع فقط. |
+
## الأدوات
- Claude Code أو Codex
diff --git a/docs/ar/projects/project-03-multi-session-continuity/index.md b/docs/ar/projects/project-03-multi-session-continuity/index.md
index 6257bc7..0b45116 100644
--- a/docs/ar/projects/project-03-multi-session-continuity/index.md
+++ b/docs/ar/projects/project-03-multi-session-continuity/index.md
@@ -11,6 +11,15 @@
ستنفذه مرتين: الأولى دون قيود، والثانية مع تطبيق صارم.
+## استخدم المشروع الموجود في المستودع
+
+مسار المستودع: `projects/project-03/`
+
+| المجلد | ماذا يحتوي | ماذا تقارن |
+|------|------|------|
+| `starter/` | كود Project 02 وفيه indexing و Q&A مع citations غير مكتملين بعد. يوجد `feature_list.json` أولي، لكن لا توجد ملفات handoff/restart النهائية. | هل ينحرف الوكيل بين عدة ميزات أو يفقد الحالة بعد إعادة التشغيل. |
+| `solution/` | chunking و metadata و index status و citation-based Q&A مكتملة، مع `init.sh` و `session-handoff.md` و `claude-progress.md` و `clean-state-checklist.md`. | هل تملك كل ميزة دليل تحقق قبل وضعها في حالة pass. |
+
## الأدوات
- Claude Code أو Codex
diff --git a/docs/ar/projects/project-04-incremental-indexing/index.md b/docs/ar/projects/project-04-incremental-indexing/index.md
index 5682447..8daaa01 100644
--- a/docs/ar/projects/project-04-incremental-indexing/index.md
+++ b/docs/ar/projects/project-04-incremental-indexing/index.md
@@ -11,6 +11,17 @@
ستنفذه مرتين: الأولى دون سجلات أو قيود، والثانية بالأدوات والقواعد المناسبة.
+## استخدم المشروع الموجود في المستودع
+
+مسار المستودع: `projects/project-04/`
+
+| المجلد | ماذا يحتوي | ماذا تقارن |
+|------|------|------|
+| `starter/` | كود Project 03 مع إشارات تشخيص ضعيفة. عيب indexing المزروع قد يكسر chunking للملفات الكبيرة، ولا يوجد script لفحص المعمارية. | كم يستغرق الوكيل للوصول إلى السبب الجذري بدون إشارات runtime. |
+| `solution/` | structured logger، وثائق/script لحدود المعمارية، منطق chunking مصحح، و `clean-state-checklist.md`. | هل تجعل logs و boundary checks الإصلاح أسرع وأقل تدخلاً. |
+
+ملفات مهمة: `projects/project-04/solution/src/services/logger.ts`, `projects/project-04/solution/scripts/check-architecture.sh`, `projects/project-04/solution/docs/ARCHITECTURE.md`, `projects/project-04/solution/src/services/indexing-service.ts`.
+
## الأدوات
- Claude Code أو Codex
diff --git a/docs/ar/projects/project-05-grounded-qa-verification/index.md b/docs/ar/projects/project-05-grounded-qa-verification/index.md
index 74d618a..3278bd7 100644
--- a/docs/ar/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/ar/projects/project-05-grounded-qa-verification/index.md
@@ -11,6 +11,17 @@
اختر ترقية جوهرية لميزة، مثل محادثة متعددة الأدوار، أو إعادة تصميم لوحة الاستشهادات، أو فلترة المستندات، وحافظ عليها ثابتة في كل التشغيلات.
+## استخدم المشروع الموجود في المستودع
+
+مسار المستودع: `projects/project-05/`
+
+| المجلد | ماذا يحتوي | ماذا تقارن |
+|------|------|------|
+| `starter/` | تطبيق مبني على Project 04 قبل ترقية سجل المحادثة. | نقطة البداية إذا أردت إعادة تشغيل المتغيرات الثلاثة. |
+| `solution/single-role/` | وكيل واحد يخطط وينفذ ويقيّم نفسه. | الدرجة والعيوب في `evaluator-rubric.md`. |
+| `solution/gen-eval/` | generator + evaluator مع دليل مراجعة. | الدرجة وملاحظات revision في `evaluator-rubric.md`. |
+| `solution/plan-gen-eval/` | planner + generator + evaluator مع sprint contract. | `sprint-contract.md` ودليل الدرجة الأعلى في `evaluator-rubric.md`. |
+
## الأدوات
- Claude Code أو Codex
diff --git a/docs/ar/projects/project-06-runtime-observability-and-debugging/index.md b/docs/ar/projects/project-06-runtime-observability-and-debugging/index.md
index 3df3aac..fba3ca4 100644
--- a/docs/ar/projects/project-06-runtime-observability-and-debugging/index.md
+++ b/docs/ar/projects/project-06-runtime-observability-and-debugging/index.md
@@ -11,6 +11,15 @@
استخدم مجموعة مهام ثابتة متعددة الميزات تغطي شريحة منتج كاملة: استيراد المستندات، الفهرسة، Q&A مع الاستشهادات، قابلية ملاحظة runtime، وحالة مستودع قابلة للقراءة والاستئناف. ابدأ بتشغيل baseline مع harness ضعيف، ثم شغّل أقوى harness لديك، ثم نظف وأعد التشغيل. أخيرًا، نفذ تجربة ablation للـ harness: أزل مكونًا واحدًا كل مرة وانظر أيها مهم فعليًا.
+## استخدم المشروع الموجود في المستودع
+
+مسار المستودع: `projects/project-06/`
+
+| المجلد | ماذا يحتوي | ماذا تقارن |
+|------|------|------|
+| `starter/` | المنتج شبه مكتمل، لكن سطح harness ضعيف عمدًا: يوجد `AGENTS.md` أساسي فقط، ولا يوجد `feature_list.json` أو `session-handoff.md` أو clean-state checklist أو benchmark/cleanup scripts. | ملاحظات يدوية لخط baseline مع harness ضعيف. |
+| `solution/` | harness كامل: `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md`, quality/evaluator docs و scripts. | شغّل `projects/project-06/solution/scripts/benchmark.sh` و `projects/project-06/solution/scripts/cleanup-scanner.sh` ثم قارن أدلة الجودة. |
+
## الأدوات
- Claude Code أو Codex
diff --git a/docs/de/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/de/projects/project-01-baseline-vs-minimal-harness/index.md
index b133f09..73f91d2 100644
--- a/docs/de/projects/project-01-baseline-vs-minimal-harness/index.md
+++ b/docs/de/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -11,7 +11,7 @@ Baue das minimale Gerüst einer Electron-Wissensdatenbank-App: ein Fenster mit D
Du führst sie zweimal aus. Beim ersten Mal: nur ein Prompt, keine Vorbereitung. Beim zweiten Mal: `AGENTS.md`, `init.sh` und `feature_list.json` liegen bereits im Repository. Danach vergleichst du.
-Der Kern dieses Projekts ist nicht das Schreiben von Code, sondern herauszufinden, wie groß der Abstand zwischen "15 Minuten Regeln vorbereiten" und "den Agenten einfach loslaufen lassen" ist.
+Dieses Kursbeispiel nutzt eine kurze Wiederentdeckungs-/Vorbereitungsphase als Beispiel, nicht als fest gemessenes Ergebnis.
## Werkzeuge
@@ -23,3 +23,14 @@ Der Kern dieses Projekts ist nicht das Schreiben von Code, sondern herauszufinde
## Harness-Mechanismus
Minimaler harness: `AGENTS.md` + `init.sh` + `feature_list.json`
+
+## Nutze das eingecheckte Projekt
+
+Repository-Pfad: `projects/project-01/`
+
+| Verzeichnis | Inhalt | Nutzung/Vergleich |
+|------|------|------|
+| `starter/` | Weak-Harness-Lauf. Enthält nur `task-prompt.md` als Aufgabenbeschreibung und keine `AGENTS.md` oder `feature_list.json`. | Gib den Prompt an deinen Agenten und miss, was ohne zusätzliche Struktur fertig wird. |
+| `solution/` | Gleicher Produktslice mit expliziten Harness-Artefakten: `AGENTS.md`, `CLAUDE.md`, `init.sh`, `feature_list.json` und `claude-progress.md`. | Vergleiche, wie Regeln und Verifikation die gleiche Aufgabe konkret und überprüfbar machen. |
+
+Die vier konkreten Features sind Fensterstart, Dokumentliste, Frage-Panel und das lokale Datenverzeichnis. Schau in `solution/feature_list.json` für die erwartete Evidence pro Feature.
diff --git a/docs/de/projects/project-02-agent-readable-workspace/index.md b/docs/de/projects/project-02-agent-readable-workspace/index.md
index 87e3c40..1c8eb55 100644
--- a/docs/de/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/de/projects/project-02-agent-readable-workspace/index.md
@@ -11,6 +11,17 @@ Füge dem Repository "Lesbarkeit" hinzu, damit ein neuer Agent die Projektstrukt
Du führst es zweimal aus: zuerst ohne Hilfe, dann mit bereits abgelegten `ARCHITECTURE.md`, `PRODUCT.md` und `session-handoff.md`.
+## Nutze das eingecheckte Projekt
+
+Repository-Pfad: `projects/project-02/`
+
+| Verzeichnis | Inhalt | Vergleichspunkt |
+|------|------|------|
+| `starter/` | Code aus Project 01 mit noch unvollständigem Import, Detailansicht und Persistenz. Die Dokumentation ist vorhanden, aber dünner, und `session-handoff.md` fehlt. | Wie viel Kontext eine zweite Agent-Sitzung erneut herausfinden muss. |
+| `solution/` | Derselbe Produktschnitt ist fertig, mit Übergabedokumentation unter `projects/project-02/solution/` sowie `feature_list.json` und `session-handoff.md`. | Ob eine neue Sitzung nur aus dem Repository-Zustand weiterarbeiten kann. |
+
+Die Produktfunktionen sind Dokumentimport, vollständiges Laden von Details/Inhalt und Persistenz nach Neustart. Die Harness-Funktion ist ein gut übergebbarer Workspace.
+
## Werkzeuge
- Claude Code oder Codex
diff --git a/docs/de/projects/project-03-multi-session-continuity/index.md b/docs/de/projects/project-03-multi-session-continuity/index.md
index 4d7b153..7155670 100644
--- a/docs/de/projects/project-03-multi-session-continuity/index.md
+++ b/docs/de/projects/project-03-multi-session-continuity/index.md
@@ -11,6 +11,15 @@ Füge dem Agenten Scope-Kontrolle und Verifikationsgates hinzu. Implementiere Do
Du führst es zweimal aus: zuerst ohne Einschränkungen, dann mit strikter Durchsetzung.
+## Nutze das eingecheckte Projekt
+
+Repository-Pfad: `projects/project-03/`
+
+| Verzeichnis | Inhalt | Vergleichspunkt |
+|------|------|------|
+| `starter/` | Project-02-Code, bei dem Indexierung und zitierfähiges Q&A noch unvollständig sind. Es gibt ein erstes `feature_list.json`, aber keine finalen Neustart- und Übergabeartefakte. | Ob der Agent über mehrere Funktionen driftet oder nach einem Neustart Zustand verliert. |
+| `solution/` | Chunking, Metadaten, Indexierungsstatus und Q&A mit Zitaten sind fertig, plus `init.sh`, `session-handoff.md`, `claude-progress.md` und `clean-state-checklist.md`. | Ob jede Funktion konkrete Evidenz hat, bevor sie als bestanden markiert wird. |
+
## Werkzeuge
- Claude Code oder Codex
diff --git a/docs/de/projects/project-04-incremental-indexing/index.md b/docs/de/projects/project-04-incremental-indexing/index.md
index 9489dbb..4424dce 100644
--- a/docs/de/projects/project-04-incremental-indexing/index.md
+++ b/docs/de/projects/project-04-incremental-indexing/index.md
@@ -11,6 +11,17 @@ Füge Runtime-Beobachtbarkeit hinzu, etwa Startlogs, Import-/Indexierungslogs un
Du führst es zweimal aus: zuerst ohne Logs oder Regeln, dann mit passenden Werkzeugen und Regeln.
+## Nutze das eingecheckte Projekt
+
+Repository-Pfad: `projects/project-04/`
+
+| Verzeichnis | Inhalt | Vergleichspunkt |
+|------|------|------|
+| `starter/` | Project-03-Code mit schwachen Diagnosesignalen. Der eingebaute Indexierungsfehler kann Chunking bei großen Dateien brechen, und es gibt kein Architekturprüfskript. | Wie lange der Agent ohne Runtime-Signale bis zur Ursache braucht. |
+| `solution/` | Strukturierter Logger, Architekturgrenzendokumentation und Prüfsktipt, korrigierte Chunking-Logik und `clean-state-checklist.md`. | Ob Logs und Grenzprüfungen die Korrektur schneller und weniger invasiv machen. |
+
+Wichtige Dateien: `projects/project-04/solution/src/services/logger.ts`, `projects/project-04/solution/scripts/check-architecture.sh`, `projects/project-04/solution/docs/ARCHITECTURE.md`, `projects/project-04/solution/src/services/indexing-service.ts`.
+
## Werkzeuge
- Claude Code oder Codex
diff --git a/docs/de/projects/project-05-grounded-qa-verification/index.md b/docs/de/projects/project-05-grounded-qa-verification/index.md
index 7b20e17..481f13c 100644
--- a/docs/de/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/de/projects/project-05-grounded-qa-verification/index.md
@@ -11,6 +11,17 @@ Implementiere Rollentrennung: einen generator für die Umsetzung, einen evaluato
Wähle eine substanzielle Feature-Erweiterung, etwa Multi-Turn-Konversation, Neugestaltung des Zitat-Panels oder Dokumentfilterung, und halte sie über alle Läufe hinweg konstant.
+## Nutze das eingecheckte Projekt
+
+Repository-Pfad: `projects/project-05/`
+
+| Verzeichnis | Inhalt | Vergleichspunkt |
+|------|------|------|
+| `starter/` | Project-04-basierte App vor dem Upgrade für Gesprächshistorie. | Ausgangspunkt, wenn du die drei Varianten selbst erneut ausführen willst. |
+| `solution/single-role/` | Ein Agent plant, implementiert und bewertet sich selbst. | Bewertung und Defektliste in `evaluator-rubric.md`. |
+| `solution/gen-eval/` | Generator + Evaluator mit Revisionsnachweis. | Bewertung und Revisionsnotizen in `evaluator-rubric.md`. |
+| `solution/plan-gen-eval/` | Planner + Generator + Evaluator mit Sprint Contract. | `sprint-contract.md` und höhere Bewertungsnachweise in `evaluator-rubric.md`. |
+
## Werkzeuge
- Claude Code oder Codex
diff --git a/docs/de/projects/project-06-runtime-observability-and-debugging/index.md b/docs/de/projects/project-06-runtime-observability-and-debugging/index.md
index e59f71d..e344bc7 100644
--- a/docs/de/projects/project-06-runtime-observability-and-debugging/index.md
+++ b/docs/de/projects/project-06-runtime-observability-and-debugging/index.md
@@ -11,6 +11,15 @@ Dies ist das Abschlussprojekt. Setze alles zusammen, was du in den ersten fünf
Nutze ein festes Multi-Feature-Aufgabenset, das einen vollständigen Produktschnitt abdeckt: Dokumentimport, Indexierung, Q&A mit Zitaten, Runtime-Beobachtbarkeit und einen lesbaren, wiederaufnehmbaren Repository-Zustand. Führe zuerst einen schwachen harness-Baseline-Lauf aus, dann deinen stärksten harness, danach Cleanup und erneuten Lauf. Zum Schluss machst du ein harness-Ablationsexperiment: Entferne jeweils eine Komponente und beobachte, welche wirklich wichtig sind.
+## Nutze das eingecheckte Projekt
+
+Repository-Pfad: `projects/project-06/`
+
+| Verzeichnis | Inhalt | Vergleichspunkt |
+|------|------|------|
+| `starter/` | Produktcode ist weitgehend vollständig, aber die Harness-Oberfläche ist absichtlich geschwächt: nur grundlegendes `AGENTS.md`, kein `feature_list.json`, kein `session-handoff.md`, keine Clean-State-Checkliste und keine Benchmark/Cleanup-Skripte. | Manuelle Baseline-Beobachtungen mit schwachem Harness. |
+| `solution/` | Vollständiger Harness: `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md`, Qualitäts-/Evaluator-Dokumente und Skripte. | `projects/project-06/solution/scripts/benchmark.sh` und `projects/project-06/solution/scripts/cleanup-scanner.sh` ausführen und Qualitätsevidenz vergleichen. |
+
## Werkzeuge
- Claude Code oder Codex
diff --git a/docs/en/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/en/projects/project-01-baseline-vs-minimal-harness/index.md
index 80aba98..ae10820 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
@@ -11,7 +11,7 @@ Build a minimal Electron knowledge-base app shell — a window with a document l
You run it twice. First time: just a prompt, no preparation. Second time: `AGENTS.md`, `init.sh`, `feature_list.json` pre-placed in the repo. Then compare.
-The core of this project is not writing code — it's figuring out how big the gap is between "spend 15 minutes preparing rules first" and "just let the agent go."
+This course scenario uses a short rediscovery/preparation interval as an example, not a fixed measured result.
## Tools
@@ -23,3 +23,16 @@ The core of this project is not writing code — it's figuring out how big the g
## Harness Mechanism
Minimal harness: `AGENTS.md` + `init.sh` + `feature_list.json`
+
+## Use the Checked-In Project
+
+Repository path: `projects/project-01/`
+
+| Directory | What it contains | How to use it |
+|------|------|------|
+| `starter/` | The weak-harness run. It has only `task-prompt.md` as the task description and no `AGENTS.md` or `feature_list.json`. | Give the prompt to your coding agent and measure what it completes without extra structure. |
+| `solution/` | The same product slice with explicit harness artifacts: `AGENTS.md`, `CLAUDE.md`, `init.sh`, `feature_list.json`, and `claude-progress.md`. | Compare how the same task is made concrete through rules and verification evidence. |
+
+The four concrete features are window launch, document list, question panel, and
+local data directory creation. Inspect `solution/feature_list.json` for the
+expected evidence for each feature.
diff --git a/docs/en/projects/project-02-agent-readable-workspace/index.md b/docs/en/projects/project-02-agent-readable-workspace/index.md
index 70b4985..43bafec 100644
--- a/docs/en/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/en/projects/project-02-agent-readable-workspace/index.md
@@ -9,7 +9,9 @@
Add "readability" to the repo so a new agent can quickly understand the project structure, know the current progress, and pick up work. Specifically: implement document import, document detail view, and local persistence, completed across two sessions.
-You run it twice: first without any help, second with `ARCHITECTURE.md`, `PRODUCT.md`, and `session-handoff.md` pre-placed in the repo.
+You run it twice from the checked-in directories: first with the thinner
+starter workspace and no `session-handoff.md`, second against the solution shape
+that has expanded `ARCHITECTURE.md`, `PRODUCT.md`, and `session-handoff.md`.
## Tools
@@ -20,3 +22,16 @@ You run it twice: first without any help, second with `ARCHITECTURE.md`, `PRODUC
## Harness Mechanism
Agent-readable workspace + persistent state files
+
+## Use the Checked-In Project
+
+Repository path: `projects/project-02/`
+
+| Directory | What it contains | What to compare |
+|------|------|------|
+| `starter/` | Project 01 code plus incomplete document import, detail view, and persistence. The docs exist but are intentionally thinner, and there is no `session-handoff.md`. | How much rediscovery a second agent session does. |
+| `solution/` | The same slice completed, with expanded docs under `projects/project-02/solution/` (plus `feature_list.json` and `session-handoff.md`). | Whether a fresh session can resume from repo state without oral context. |
+
+The product features are document import, full document detail/content loading,
+and persistence across restart. The harness feature is the handoff-readable
+workspace.
diff --git a/docs/en/projects/project-03-multi-session-continuity/index.md b/docs/en/projects/project-03-multi-session-continuity/index.md
index 856e5cf..be3ccbf 100644
--- a/docs/en/projects/project-03-multi-session-continuity/index.md
+++ b/docs/en/projects/project-03-multi-session-continuity/index.md
@@ -9,7 +9,9 @@
Add scope control and verification gates to the agent. Implement document chunking, metadata extraction, indexing progress display, and citation-based Q&A flow. Use `feature_list.json` to track feature status — one feature at a time, no marking as "pass" without verification evidence.
-You run it twice: first without constraints, second with strict enforcement.
+You compare the checked-in starter and solution: the starter has only the early
+tracking surface, while the solution adds the stricter restart and handoff
+artifacts around the same feature list.
## Tools
@@ -19,4 +21,17 @@ You run it twice: first without constraints, second with strict enforcement.
## Harness Mechanism
-Progress log + session handoff + multi-session continuity
+Progress log + session handoff + multi-session continuity + one-feature-at-a-time verification
+
+## Use the Checked-In Project
+
+Repository path: `projects/project-03/`
+
+| Directory | What it contains | What to compare |
+|------|------|------|
+| `starter/` | Project 02 code with indexing and grounded QA still unfinished. It has a starter `feature_list.json`, but lacks the final restart/handoff artifacts. | Whether the agent drifts across multiple features or loses state after a restart. |
+| `solution/` | Completed chunking, metadata, index status, and citation-based QA, plus `init.sh`, `session-handoff.md`, `claude-progress.md`, and `clean-state-checklist.md`. | Whether each feature has concrete verification evidence before it is marked passing. |
+
+This project is not a generic "multi-session" exercise. The checked-in solution
+maps to four specific product features: document chunking, metadata extraction,
+indexing status UI, and grounded Q&A with citations.
diff --git a/docs/en/projects/project-04-incremental-indexing/index.md b/docs/en/projects/project-04-incremental-indexing/index.md
index 38fe462..90b9ee9 100644
--- a/docs/en/projects/project-04-incremental-indexing/index.md
+++ b/docs/en/projects/project-04-incremental-indexing/index.md
@@ -9,7 +9,9 @@
Add runtime observability (startup logs, import/indexing logs, error states) and architecture constraints to prevent cross-layer violations. Plant a runtime bug for the agent to fix.
-You run it twice: first without logs or constraints, second with proper tools and rules.
+You compare the checked-in starter and solution: the starter has weak diagnostics
+and no architecture guard script, while the solution adds structured logs,
+boundary checks, and the bug fix.
## Tools
@@ -20,3 +22,17 @@ You run it twice: first without logs or constraints, second with proper tools an
## Harness Mechanism
Runtime feedback + scope control + incremental indexing
+
+## Use the Checked-In Project
+
+Repository path: `projects/project-04/`
+
+| Directory | What it contains | What to compare |
+|------|------|------|
+| `starter/` | Project 03 code with weak diagnostics. A seeded indexing defect can make large-file chunking fail, and there is no architecture-check script. | How long the agent takes to find the root cause without runtime signals. |
+| `solution/` | Structured logger, architecture boundary docs and script, fixed chunking logic, and `clean-state-checklist.md`. | Whether logs and boundary checks make the fix faster and less invasive. |
+
+The concrete files to inspect are `projects/project-04/solution/src/services/logger.ts`,
+`projects/project-04/solution/scripts/check-architecture.sh`,
+`projects/project-04/solution/docs/ARCHITECTURE.md`, and
+`projects/project-04/solution/src/services/indexing-service.ts`.
diff --git a/docs/en/projects/project-05-grounded-qa-verification/index.md b/docs/en/projects/project-05-grounded-qa-verification/index.md
index 23f79db..f9b266b 100644
--- a/docs/en/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/en/projects/project-05-grounded-qa-verification/index.md
@@ -20,3 +20,17 @@ Choose a substantive feature upgrade (multi-turn conversation, citation panel re
## Harness Mechanism
Self-verification + grounded Q&A + evidence-based completion
+
+## Use the Checked-In Project
+
+Repository path: `projects/project-05/`
+
+| Directory | What it contains | What to compare |
+|------|------|------|
+| `starter/` | Project 04-based app before the conversation-history upgrade. | Starting point if you want to rerun the three variants yourself. |
+| `solution/single-role/` | One agent plans, implements, and self-reviews. | `evaluator-rubric.md` score 1.6/5 and listed defects. |
+| `solution/gen-eval/` | Generator plus evaluator with revision evidence. | `evaluator-rubric.md` score 3.3/5 and revision notes. |
+| `solution/plan-gen-eval/` | Planner plus generator plus evaluator. | `sprint-contract.md`, `evaluator-rubric.md` score 4.9/5. |
+
+The checked-in feature is multi-turn Q&A conversation history. Keep that feature
+constant across all three variants so the only variable is role separation.
diff --git a/docs/en/projects/project-06-runtime-observability-and-debugging/index.md b/docs/en/projects/project-06-runtime-observability-and-debugging/index.md
index 34072cf..b2e3a1b 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
@@ -23,3 +23,15 @@ Use a fixed multi-feature task set covering the complete product slice: document
## Harness Mechanism
Complete harness: all mechanisms + observability + ablation study
+
+## Use the Checked-In Project
+
+Repository path: `projects/project-06/`
+
+| Directory | What it contains | What to compare |
+|------|------|------|
+| `starter/` | Mostly complete product code with intentionally weak harness surface: basic `AGENTS.md`, no `feature_list.json`, no `session-handoff.md`, no clean-state checklist. | Manual weak-harness baseline observations. The starter intentionally does not include benchmark scripts. |
+| `solution/` | Full harness surface: `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md`, quality/evaluator docs, benchmark and cleanup scripts. | Run `projects/project-06/solution/scripts/benchmark.sh` and `projects/project-06/solution/scripts/cleanup-scanner.sh`, then compare quality-document evidence. |
+
+Unlike earlier projects, the capstone starter is not mostly missing product
+features. The main gap is the operating harness around the app.
diff --git a/docs/es/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/es/projects/project-01-baseline-vs-minimal-harness/index.md
index d986d20..3491029 100644
--- a/docs/es/projects/project-01-baseline-vs-minimal-harness/index.md
+++ b/docs/es/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -11,7 +11,7 @@ Construye el esqueleto mínimo de una aplicación Electron de base de conocimien
La ejecutarás dos veces. Primera vez: solo un prompt, sin preparación. Segunda vez: con `AGENTS.md`, `init.sh` y `feature_list.json` ya colocados en el repositorio. Luego compara.
-El núcleo de este proyecto no es escribir código, sino descubrir cuánta distancia hay entre "dedicar 15 minutos a preparar reglas primero" y "dejar que el agente avance sin más".
+Este escenario de curso usa un intervalo breve de redescubrimiento/preparación como ejemplo, no un resultado medido fijo.
## Herramientas
@@ -23,3 +23,14 @@ El núcleo de este proyecto no es escribir código, sino descubrir cuánta dista
## Mecanismo de harness
Harness mínimo: `AGENTS.md` + `init.sh` + `feature_list.json`
+
+## Usa el proyecto incluido
+
+Ruta en el repositorio: `projects/project-01/`
+
+| Directorio | Qué contiene | Cómo usarlo |
+|------|------|------|
+| `starter/` | Ejecución con harness débil. Solo tiene `task-prompt.md` como descripción de tarea y no incluye `AGENTS.md` ni `feature_list.json`. | Entrega el prompt a tu agente y mide qué completa sin estructura adicional. |
+| `solution/` | El mismo slice del producto con artefactos de harness explícitos: `AGENTS.md`, `CLAUDE.md`, `init.sh`, `feature_list.json` y `claude-progress.md`. | Compara cómo las reglas y la verificación convierten la misma tarea en algo ejecutable y comprobable. |
+
+Las cuatro funciones concretas son: lanzar la ventana, lista de documentos, panel de preguntas y respuestas, y creación del directorio de datos local. Consulta `solution/feature_list.json` para ver la evidencia esperada de cada función.
diff --git a/docs/es/projects/project-02-agent-readable-workspace/index.md b/docs/es/projects/project-02-agent-readable-workspace/index.md
index 10b2e02..8b4aabb 100644
--- a/docs/es/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/es/projects/project-02-agent-readable-workspace/index.md
@@ -11,6 +11,17 @@ Añade "legibilidad" al repositorio para que un agente nuevo pueda entender ráp
Lo ejecutarás dos veces: primero sin ayuda, y después con `ARCHITECTURE.md`, `PRODUCT.md` y `session-handoff.md` ya colocados en el repositorio.
+## Usa el proyecto incluido
+
+Ruta en el repositorio: `projects/project-02/`
+
+| Directorio | Qué contiene | Qué comparar |
+|------|------|------|
+| `starter/` | Código de Project 01 con importación, vista de detalle y persistencia todavía incompletas. La documentación existe, pero es más ligera y no hay `session-handoff.md`. | Cuánto contexto tiene que redescubrir una segunda sesión del agente. |
+| `solution/` | La misma porción de producto ya completada, con documentación de handoff bajo `projects/project-02/solution/`, además de `feature_list.json` y `session-handoff.md`. | Si una sesión nueva puede continuar solo desde el estado del repositorio. |
+
+Las funciones de producto son importación de documentos, carga completa del detalle/contenido y persistencia tras reiniciar. La función de harness es un workspace legible y fácil de retomar.
+
## Herramientas
- Claude Code o Codex
diff --git a/docs/es/projects/project-03-multi-session-continuity/index.md b/docs/es/projects/project-03-multi-session-continuity/index.md
index 5803e61..2177554 100644
--- a/docs/es/projects/project-03-multi-session-continuity/index.md
+++ b/docs/es/projects/project-03-multi-session-continuity/index.md
@@ -11,6 +11,15 @@ Añade control de alcance y gates de verificación al agente. Implementa partici
Lo ejecutarás dos veces: primero sin restricciones, luego con aplicación estricta de reglas.
+## Usa el proyecto incluido
+
+Ruta en el repositorio: `projects/project-03/`
+
+| Directorio | Qué contiene | Qué comparar |
+|------|------|------|
+| `starter/` | Código de Project 02 con indexación y Q&A fundamentado todavía incompletos. Incluye un `feature_list.json` inicial, pero no los artefactos finales de reinicio y handoff. | Si el agente se desvía entre varias funciones o pierde estado al reiniciar. |
+| `solution/` | Chunking, metadatos, estado de indexación y Q&A con citas completados, además de `init.sh`, `session-handoff.md`, `claude-progress.md` y `clean-state-checklist.md`. | Si cada función tiene evidencia concreta antes de marcarse como aprobada. |
+
## Herramientas
- Claude Code o Codex
diff --git a/docs/es/projects/project-04-incremental-indexing/index.md b/docs/es/projects/project-04-incremental-indexing/index.md
index 3364c15..e93117f 100644
--- a/docs/es/projects/project-04-incremental-indexing/index.md
+++ b/docs/es/projects/project-04-incremental-indexing/index.md
@@ -11,6 +11,17 @@ Añade observabilidad de runtime, como logs de arranque, logs de importación/in
Lo ejecutarás dos veces: primero sin logs ni restricciones, después con herramientas y reglas adecuadas.
+## Usa el proyecto incluido
+
+Ruta en el repositorio: `projects/project-04/`
+
+| Directorio | Qué contiene | Qué comparar |
+|------|------|------|
+| `starter/` | Código de Project 03 con diagnósticos débiles. El defecto sembrado de indexación puede romper el chunking de archivos grandes, y no hay script de arquitectura. | Cuánto tarda el agente en encontrar la causa raíz sin señales de runtime. |
+| `solution/` | Logger estructurado, documentación y script de límites arquitectónicos, lógica de chunking corregida y `clean-state-checklist.md`. | Si logs y checks de límites hacen la corrección más rápida y menos invasiva. |
+
+Archivos clave: `projects/project-04/solution/src/services/logger.ts`, `projects/project-04/solution/scripts/check-architecture.sh`, `projects/project-04/solution/docs/ARCHITECTURE.md`, `projects/project-04/solution/src/services/indexing-service.ts`.
+
## Herramientas
- Claude Code o Codex
diff --git a/docs/es/projects/project-05-grounded-qa-verification/index.md b/docs/es/projects/project-05-grounded-qa-verification/index.md
index 153e81d..62251c8 100644
--- a/docs/es/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/es/projects/project-05-grounded-qa-verification/index.md
@@ -11,6 +11,17 @@ Implementa separación de roles: un generator que implementa, un evaluator que r
Elige una mejora sustancial de función, como conversación multi-turno, rediseño del panel de citas o filtrado de documentos, y mantenla igual en todas las ejecuciones.
+## Usa el proyecto incluido
+
+Ruta en el repositorio: `projects/project-05/`
+
+| Directorio | Qué contiene | Qué comparar |
+|------|------|------|
+| `starter/` | Aplicación basada en Project 04 antes de la mejora de historial conversacional. | Punto de partida si quieres repetir las tres variantes. |
+| `solution/single-role/` | Un solo agente planifica, implementa y se autoevalúa. | Puntuación y defectos en `evaluator-rubric.md`. |
+| `solution/gen-eval/` | Generador + evaluador con evidencia de revisión. | Puntuación y notas de revisión en `evaluator-rubric.md`. |
+| `solution/plan-gen-eval/` | Planificador + generador + evaluador con sprint contract. | `sprint-contract.md` y evidencia de mayor puntuación en `evaluator-rubric.md`. |
+
## Herramientas
- Claude Code o Codex
diff --git a/docs/es/projects/project-06-runtime-observability-and-debugging/index.md b/docs/es/projects/project-06-runtime-observability-and-debugging/index.md
index d1e9ebf..b1360e8 100644
--- a/docs/es/projects/project-06-runtime-observability-and-debugging/index.md
+++ b/docs/es/projects/project-06-runtime-observability-and-debugging/index.md
@@ -11,6 +11,15 @@ Este es el proyecto final. Ensambla todo lo aprendido en los primeros cinco proy
Usa un conjunto fijo de tareas multi-función que cubra una porción completa del producto: importación de documentos, indexación, Q&A con citas, observabilidad de runtime y estado de repositorio legible y reiniciable. Primero ejecuta con un baseline de harness débil, luego con tu harness más fuerte, después limpia y vuelve a ejecutar. Finalmente, realiza un experimento de ablación del harness: elimina un componente cada vez y observa cuáles importan realmente.
+## Usa el proyecto incluido
+
+Ruta en el repositorio: `projects/project-06/`
+
+| Directorio | Qué contiene | Qué comparar |
+|------|------|------|
+| `starter/` | Producto casi completo, pero con superficie de harness debilitada: `AGENTS.md` básico, sin `feature_list.json`, `session-handoff.md`, checklist de estado limpio ni scripts de benchmark/cleanup. | Observaciones manuales de la línea base con harness débil. |
+| `solution/` | Harness completo: `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md`, documentos de calidad/evaluación y scripts. | Ejecutar `projects/project-06/solution/scripts/benchmark.sh` y `projects/project-06/solution/scripts/cleanup-scanner.sh`, y comparar la evidencia de calidad. |
+
## Herramientas
- Claude Code o Codex
diff --git a/docs/fr/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/fr/projects/project-01-baseline-vs-minimal-harness/index.md
index e8bf081..781bd7c 100644
--- a/docs/fr/projects/project-01-baseline-vs-minimal-harness/index.md
+++ b/docs/fr/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -11,7 +11,7 @@ Construisez le squelette minimal d'une application Electron de base de connaissa
Vous l'exécutez deux fois. Première fois : seulement un prompt, sans préparation. Deuxième fois : `AGENTS.md`, `init.sh` et `feature_list.json` déjà placés dans le dépôt. Ensuite, comparez.
-Le cœur de ce projet n'est pas d'écrire du code, mais de mesurer l'écart entre "passer 15 minutes à préparer les règles" et "laisser simplement l'agent partir".
+Ce scénario de cours prend un court intervalle de redécouverte/préparation comme exemple, pas un résultat mesuré fixe.
## Outils
@@ -23,3 +23,14 @@ Le cœur de ce projet n'est pas d'écrire du code, mais de mesurer l'écart entr
## Mécanisme de harness
Harness minimal : `AGENTS.md` + `init.sh` + `feature_list.json`
+
+## Utiliser le projet fourni dans le dépôt
+
+Chemin dans le dépôt : `projects/project-01/`
+
+| Dossier | Ce qu’il contient | Comment l’utiliser |
+|------|------|------|
+| `starter/` | Exécution « harness faible ». Contient uniquement `task-prompt.md` comme description de la tâche, sans `AGENTS.md` ni `feature_list.json`. | Donne le prompt à ton agent et mesure ce qu’il termine sans structure supplémentaire. |
+| `solution/` | Le même slice produit avec des artefacts de harness explicites : `AGENTS.md`, `CLAUDE.md`, `init.sh`, `feature_list.json` et `claude-progress.md`. | Compare comment les règles et la vérification rendent la même tâche concrète et vérifiable. |
+
+Les quatre fonctionnalités concrètes sont : ouverture de la fenêtre, liste de documents, panneau de questions, et création du répertoire de données local. Consulte `solution/feature_list.json` pour l’évidence attendue pour chaque fonctionnalité.
diff --git a/docs/fr/projects/project-02-agent-readable-workspace/index.md b/docs/fr/projects/project-02-agent-readable-workspace/index.md
index b5903df..37f5a5b 100644
--- a/docs/fr/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/fr/projects/project-02-agent-readable-workspace/index.md
@@ -11,6 +11,15 @@ Ajoutez de la "lisibilité" au dépôt pour qu'un nouvel agent comprenne rapidem
Vous l'exécutez deux fois : d'abord sans aide, puis avec `ARCHITECTURE.md`, `PRODUCT.md` et `session-handoff.md` déjà placés dans le dépôt.
+## Utiliser le projet fourni
+
+Chemin dans le dépôt : `projects/project-02/`
+
+| Dossier | Contenu | À comparer |
+|------|------|------|
+| `starter/` | Code de Project 01 avec import, vue détail et persistance encore incomplets. La documentation existe, mais elle est plus légère et il n'y a pas de `session-handoff.md`. | Combien de contexte une deuxième session doit redécouvrir. |
+| `solution/` | Même tranche produit terminée, avec documentation de reprise sous `projects/project-02/solution/`, plus `feature_list.json` et `session-handoff.md`. | Si une nouvelle session peut reprendre uniquement depuis l'état du dépôt. |
+
## Outils
- Claude Code ou Codex
diff --git a/docs/fr/projects/project-03-multi-session-continuity/index.md b/docs/fr/projects/project-03-multi-session-continuity/index.md
index 1c0cfd5..756d318 100644
--- a/docs/fr/projects/project-03-multi-session-continuity/index.md
+++ b/docs/fr/projects/project-03-multi-session-continuity/index.md
@@ -11,6 +11,15 @@ Ajoutez un contrôle de scope et des portes de vérification à l'agent. Implém
Vous l'exécutez deux fois : d'abord sans contraintes, puis avec application stricte.
+## Utiliser le projet fourni
+
+Chemin dans le dépôt : `projects/project-03/`
+
+| Dossier | Contenu | À comparer |
+|------|------|------|
+| `starter/` | Code de Project 02 avec indexation et Q&A avec citations encore incomplets. Il contient un premier `feature_list.json`, mais pas les artefacts finaux de reprise. | Si l'agent dérive entre plusieurs fonctions ou perd l'état après redémarrage. |
+| `solution/` | Chunking, métadonnées, état d'indexation et Q&A avec citations terminés, plus `init.sh`, `session-handoff.md`, `claude-progress.md`, `clean-state-checklist.md`. | Si chaque fonction a une preuve concrète avant d'être marquée comme réussie. |
+
## Outils
- Claude Code ou Codex
diff --git a/docs/fr/projects/project-04-incremental-indexing/index.md b/docs/fr/projects/project-04-incremental-indexing/index.md
index fa79ba7..c956382 100644
--- a/docs/fr/projects/project-04-incremental-indexing/index.md
+++ b/docs/fr/projects/project-04-incremental-indexing/index.md
@@ -11,6 +11,17 @@ Ajoutez de l'observabilité runtime, comme les logs de démarrage, les logs d'im
Vous l'exécutez deux fois : d'abord sans logs ni contraintes, puis avec les bons outils et règles.
+## Utiliser le projet fourni
+
+Chemin dans le dépôt : `projects/project-04/`
+
+| Dossier | Contenu | À comparer |
+|------|------|------|
+| `starter/` | Code de Project 03 avec diagnostics faibles. Le défaut d'indexation intégré peut casser le chunking des gros fichiers, et il n'y a pas de script de contrôle d'architecture. | Le temps nécessaire pour trouver la cause sans signaux runtime. |
+| `solution/` | Logger structuré, documentation/script de frontières d'architecture, logique de chunking corrigée et `clean-state-checklist.md`. | Si les logs et contrôles rendent la correction plus rapide et moins invasive. |
+
+Fichiers clés : `projects/project-04/solution/src/services/logger.ts`, `projects/project-04/solution/scripts/check-architecture.sh`, `projects/project-04/solution/docs/ARCHITECTURE.md`, `projects/project-04/solution/src/services/indexing-service.ts`.
+
## Outils
- Claude Code ou Codex
diff --git a/docs/fr/projects/project-05-grounded-qa-verification/index.md b/docs/fr/projects/project-05-grounded-qa-verification/index.md
index ecba516..61b6b21 100644
--- a/docs/fr/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/fr/projects/project-05-grounded-qa-verification/index.md
@@ -11,6 +11,17 @@ Implémentez la séparation des rôles : un generator qui implémente, un evalua
Choisissez une amélioration substantielle de fonctionnalité, comme une conversation multi-tour, une refonte du panneau de citations ou un filtrage de documents, et gardez-la identique dans toutes les exécutions.
+## Utiliser le projet fourni
+
+Chemin dans le dépôt : `projects/project-05/`
+
+| Dossier | Contenu | À comparer |
+|------|------|------|
+| `starter/` | Application basée sur Project 04 avant l'ajout de l'historique conversationnel. | Point de départ pour relancer les trois variantes. |
+| `solution/single-role/` | Un agent planifie, implémente et s'auto-évalue. | Score et défauts dans `evaluator-rubric.md`. |
+| `solution/gen-eval/` | Générateur + évaluateur avec preuve de révision. | Score et notes de révision dans `evaluator-rubric.md`. |
+| `solution/plan-gen-eval/` | Planner + générateur + évaluateur avec sprint contract. | `sprint-contract.md` et preuves de score plus élevé dans `evaluator-rubric.md`. |
+
## Outils
- Claude Code ou Codex
diff --git a/docs/fr/projects/project-06-runtime-observability-and-debugging/index.md b/docs/fr/projects/project-06-runtime-observability-and-debugging/index.md
index d6955ce..817c19d 100644
--- a/docs/fr/projects/project-06-runtime-observability-and-debugging/index.md
+++ b/docs/fr/projects/project-06-runtime-observability-and-debugging/index.md
@@ -11,6 +11,15 @@ C'est le projet final. Assemblez tout ce qui a été appris dans les cinq premie
Utilisez un ensemble fixe de tâches multi-fonctionnalités couvrant une tranche complète du produit : import de documents, indexation, Q&A avec citations, observabilité runtime et état de dépôt lisible et redémarrable. Lancez d'abord avec un baseline de harness faible, puis avec votre harness le plus fort, puis nettoyez et relancez. Enfin, réalisez une expérience d'ablation du harness : retirez un composant à la fois et voyez lesquels comptent vraiment.
+## Utiliser le projet fourni
+
+Chemin dans le dépôt : `projects/project-06/`
+
+| Dossier | Contenu | À comparer |
+|------|------|------|
+| `starter/` | Produit presque complet, mais surface de harness affaiblie : `AGENTS.md` de base, pas de `feature_list.json`, `session-handoff.md`, checklist clean-state ni scripts benchmark/cleanup. | Observations manuelles de la baseline à harness faible. |
+| `solution/` | Harness complet : `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md`, documents qualité/évaluation et scripts. | Exécuter `projects/project-06/solution/scripts/benchmark.sh` et `projects/project-06/solution/scripts/cleanup-scanner.sh`, puis comparer les preuves qualité. |
+
## Outils
- Claude Code ou Codex
diff --git a/docs/ja/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/ja/projects/project-01-baseline-vs-minimal-harness/index.md
index 8eebfc8..dfc91f9 100644
--- a/docs/ja/projects/project-01-baseline-vs-minimal-harness/index.md
+++ b/docs/ja/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -11,7 +11,7 @@
同じ作業を 2 回実行します。1 回目は準備なしでプロンプトだけ。2 回目は `AGENTS.md`、`init.sh`、`feature_list.json` をあらかじめリポジトリに置いてから実行します。その後、結果を比較します。
-このプロジェクトの核心はコードを書くことではありません。「最初に 15 分かけてルールを用意する」ことと「そのままエージェントに任せる」ことの差がどれほど大きいかを測ることです。
+このコース例は、短い再探索/準備の時間を例として使っており、固定の測定結果ではありません。
## ツール
@@ -23,3 +23,14 @@
## Harness メカニズム
最小 harness: `AGENTS.md` + `init.sh` + `feature_list.json`
+
+## リポジトリに同梱されたプロジェクトを使う
+
+リポジトリ内のパス: `projects/project-01/`
+
+| ディレクトリ | 含まれるもの | 使い方 / 比較ポイント |
+|------|------|------|
+| `starter/` | 弱い harness の実行用。タスク説明は `task-prompt.md` のみで、`AGENTS.md` や `feature_list.json` はありません。 | prompt だけをエージェントに渡し、追加の構造なしで何が完了するか測定します。 |
+| `solution/` | 同じプロダクトスライスに、明示的な harness 成果物を追加: `AGENTS.md`、`CLAUDE.md`、`init.sh`、`feature_list.json`、`claude-progress.md`。 | ルールと検証が同じタスクをどう具体化・検証可能にするか比較します。 |
+
+具体的な4機能は「ウィンドウ起動」「ドキュメント一覧」「質問パネル」「ローカルデータディレクトリ作成」です。各機能の期待される証拠は `solution/feature_list.json` を参照してください。
diff --git a/docs/ja/projects/project-02-agent-readable-workspace/index.md b/docs/ja/projects/project-02-agent-readable-workspace/index.md
index 16c17fa..f21a6a0 100644
--- a/docs/ja/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/ja/projects/project-02-agent-readable-workspace/index.md
@@ -11,6 +11,15 @@
同じ作業を 2 回実行します。1 回目は補助なし。2 回目は `ARCHITECTURE.md`、`PRODUCT.md`、`session-handoff.md` をあらかじめリポジトリに置いて実行します。
+## リポジトリ内のプロジェクトを使う
+
+リポジトリ内のパス: `projects/project-02/`
+
+| ディレクトリ | 含まれるもの | 比較すること |
+|------|------|------|
+| `starter/` | Project 01 のコードに、未完成のドキュメント import、詳細ビュー、永続化が入っています。ドキュメントはありますが薄く、`session-handoff.md` はありません。 | 2 回目のエージェントセッションがどれだけ再探索するか。 |
+| `solution/` | 同じプロダクト範囲が完成しており、`projects/project-02/solution/` 配下に引き継ぎ用ドキュメント、`feature_list.json`、`session-handoff.md` があります。 | 新しいセッションがリポジトリ状態だけで再開できるか。 |
+
## ツール
- Claude Code または Codex
diff --git a/docs/ja/projects/project-03-multi-session-continuity/index.md b/docs/ja/projects/project-03-multi-session-continuity/index.md
index 74b77df..33500e4 100644
--- a/docs/ja/projects/project-03-multi-session-continuity/index.md
+++ b/docs/ja/projects/project-03-multi-session-continuity/index.md
@@ -11,6 +11,15 @@
同じ作業を 2 回実行します。1 回目は制約なし。2 回目は厳格なルールを適用します。
+## リポジトリ内のプロジェクトを使う
+
+リポジトリ内のパス: `projects/project-03/`
+
+| ディレクトリ | 含まれるもの | 比較すること |
+|------|------|------|
+| `starter/` | Project 02 のコードで、indexing と citation 付き Q&A がまだ未完成です。初期の `feature_list.json` はありますが、最終的な handoff/restart 成果物はありません。 | 複数機能をまたぐときにエージェントが逸れたり状態を失ったりするか。 |
+| `solution/` | chunking、metadata、index status、citation-based QA が完成し、`init.sh`、`session-handoff.md`、`claude-progress.md`、`clean-state-checklist.md` もあります。 | 各機能が pass になる前に具体的な検証証拠を持つか。 |
+
## ツール
- Claude Code または Codex
diff --git a/docs/ja/projects/project-04-incremental-indexing/index.md b/docs/ja/projects/project-04-incremental-indexing/index.md
index f581ea3..5841d18 100644
--- a/docs/ja/projects/project-04-incremental-indexing/index.md
+++ b/docs/ja/projects/project-04-incremental-indexing/index.md
@@ -11,6 +11,17 @@
同じ作業を 2 回実行します。1 回目はログや制約なし。2 回目は適切なツールとルールを使います。
+## リポジトリ内のプロジェクトを使う
+
+リポジトリ内のパス: `projects/project-04/`
+
+| ディレクトリ | 含まれるもの | 比較すること |
+|------|------|------|
+| `starter/` | Project 03 のコードで診断シグナルが弱い状態です。仕込まれた indexing 欠陥により大きなファイルの chunking が壊れる可能性があり、architecture check script もありません。 | runtime シグナルなしで根本原因にたどり着く時間。 |
+| `solution/` | structured logger、architecture boundary docs/script、修正済み chunking logic、`clean-state-checklist.md` があります。 | logs と boundary checks が修正を速く、影響範囲を小さくするか。 |
+
+確認するファイル: `projects/project-04/solution/src/services/logger.ts`, `projects/project-04/solution/scripts/check-architecture.sh`, `projects/project-04/solution/docs/ARCHITECTURE.md`, `projects/project-04/solution/src/services/indexing-service.ts`.
+
## ツール
- Claude Code または Codex
diff --git a/docs/ja/projects/project-05-grounded-qa-verification/index.md b/docs/ja/projects/project-05-grounded-qa-verification/index.md
index 04baf17..e3e45f3 100644
--- a/docs/ja/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/ja/projects/project-05-grounded-qa-verification/index.md
@@ -11,6 +11,17 @@
複数ターン会話、引用パネルの再設計、ドキュメントフィルタリングなど、実質的な機能改善を 1 つ選び、すべての実行で同じ対象を使います。
+## リポジトリ内のプロジェクトを使う
+
+リポジトリ内のパス: `projects/project-05/`
+
+| ディレクトリ | 含まれるもの | 比較すること |
+|------|------|------|
+| `starter/` | Project 04 ベースのアプリで、会話履歴アップグレード前の状態です。 | 3 つの変種を自分で再実行する出発点。 |
+| `solution/single-role/` | 1 つのエージェントが計画・実装・自己評価を行います。 | `evaluator-rubric.md` のスコアと欠陥。 |
+| `solution/gen-eval/` | generator + evaluator で修正証拠があります。 | `evaluator-rubric.md` のスコアと revision notes。 |
+| `solution/plan-gen-eval/` | planner + generator + evaluator と sprint contract があります。 | `sprint-contract.md` と `evaluator-rubric.md` の高い評価証拠。 |
+
## ツール
- Claude Code または Codex
diff --git a/docs/ja/projects/project-06-runtime-observability-and-debugging/index.md b/docs/ja/projects/project-06-runtime-observability-and-debugging/index.md
index 4958077..94a2165 100644
--- a/docs/ja/projects/project-06-runtime-observability-and-debugging/index.md
+++ b/docs/ja/projects/project-06-runtime-observability-and-debugging/index.md
@@ -11,6 +11,15 @@
ドキュメントインポート、インデックス、引用付き Q&A、ランタイム観測性、読みやすく再開可能なリポジトリ状態を含む、固定された複数機能タスクセットを使います。まず弱い harness のベースラインで実行し、次に最も強い harness で実行し、その後クリーンアップして再実行します。最後に harness の ablation 実験を行い、コンポーネントを 1 つずつ外して、どれが本当に重要かを確認します。
+## リポジトリ内のプロジェクトを使う
+
+リポジトリ内のパス: `projects/project-06/`
+
+| ディレクトリ | 含まれるもの | 比較すること |
+|------|------|------|
+| `starter/` | プロダクトはほぼ完成していますが、harness は意図的に弱められています。基本的な `AGENTS.md` のみで、`feature_list.json`、`session-handoff.md`、clean-state checklist、benchmark/cleanup scripts はありません。 | 弱い harness baseline の手動観察。 |
+| `solution/` | 完全な harness: `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md`, quality/evaluator docs, scripts。 | `projects/project-06/solution/scripts/benchmark.sh` と `projects/project-06/solution/scripts/cleanup-scanner.sh` を実行し、quality evidence を比較します。 |
+
## ツール
- Claude Code または Codex
diff --git a/docs/ko/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/ko/projects/project-01-baseline-vs-minimal-harness/index.md
index d1123c2..37651c0 100644
--- a/docs/ko/projects/project-01-baseline-vs-minimal-harness/index.md
+++ b/docs/ko/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -11,7 +11,7 @@
두 번 실행합니다. 첫 번째: 프롬프트만 사용하고 사전 준비 없이 진행합니다. 두 번째: `AGENTS.md`, `init.sh`, `feature_list.json`을 저장소에 미리 배치한 상태로 진행합니다. 그런 다음 비교합니다.
-이 프로젝트의 핵심은 코드를 작성하는 것이 아닙니다. "규칙을 먼저 준비하는 데 15분을 쓰는 것"과 "에이전트를 그냥 실행시키는 것" 사이의 격차가 얼마나 큰지 파악하는 것입니다.
+이 코스 시나리오는 짧은 재탐색/준비 시간을 예로 들며, 고정된 측정 결과가 아닙니다.
에이전트에게 규칙(rule)과 초기화(initialization) 단서를 제공하면 작업 범위를 스스로 파악하고 불필요한 탐색을 줄일 수 있습니다. 이처럼 최소한의 하네스만으로도 에이전트의 출발점과 결과 품질이 크게 달라집니다.
@@ -25,3 +25,14 @@
## 하네스 메커니즘
최소 하네스(minimal harness): `AGENTS.md` + `init.sh` + `feature_list.json`
+
+## 저장소에 포함된 프로젝트 사용하기
+
+저장소 경로: `projects/project-01/`
+
+| 디렉터리 | 무엇이 들어있나 | 어떻게 사용할까 / 무엇을 비교할까 |
+|------|------|------|
+| `starter/` | 약한 하네스 실행용. 작업 설명은 `task-prompt.md`만 있고 `AGENTS.md`나 `feature_list.json`은 없습니다. | 프롬프트만 에이전트에 주고, 추가 구조 없이 무엇을 완성하는지 측정합니다. |
+| `solution/` | 같은 제품 슬라이스에 명시적인 하네스 산출물 포함: `AGENTS.md`, `CLAUDE.md`, `init.sh`, `feature_list.json`, `claude-progress.md`. | 규칙/검증이 같은 작업을 어떻게 구체화하고 검증 가능하게 만드는지 비교합니다. |
+
+구체적인 4개 기능은 창 실행, 문서 목록, 질문 패널, 로컬 데이터 디렉터리 생성입니다. 각 기능의 기대 증거는 `solution/feature_list.json`을 확인하세요.
diff --git a/docs/ko/projects/project-02-agent-readable-workspace/index.md b/docs/ko/projects/project-02-agent-readable-workspace/index.md
index c34126a..c6e188c 100644
--- a/docs/ko/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/ko/projects/project-02-agent-readable-workspace/index.md
@@ -13,6 +13,15 @@
에이전트는 컨텍스트 윈도(context window)가 초기화되면 이전 작업 흐름을 기억하지 못합니다. 세션 핸드오프(session handoff) 파일을 통해 이전 세션의 상태(state)를 영속화하면, 새 세션의 에이전트도 동일한 진행 지점에서 출발할 수 있습니다.
+## 저장소에 포함된 프로젝트 사용하기
+
+저장소 경로: `projects/project-02/`
+
+| 디렉터리 | 내용 | 비교할 것 |
+|------|------|------|
+| `starter/` | Project 01 코드에 문서 가져오기, 상세 보기, 지속성이 아직 완성되지 않은 상태입니다. 문서는 있지만 더 얇고 `session-handoff.md`가 없습니다. | 두 번째 에이전트 세션이 얼마나 많은 컨텍스트를 다시 찾아야 하는지. |
+| `solution/` | 같은 제품 범위가 완성되어 있고, `projects/project-02/solution/` 아래에 인수인계 문서와 `feature_list.json`, `session-handoff.md`가 있습니다. | 새 세션이 저장소 상태만 보고 이어갈 수 있는지. |
+
## 도구
- Claude Code 또는 Codex
diff --git a/docs/ko/projects/project-03-multi-session-continuity/index.md b/docs/ko/projects/project-03-multi-session-continuity/index.md
index 0364474..f93aee1 100644
--- a/docs/ko/projects/project-03-multi-session-continuity/index.md
+++ b/docs/ko/projects/project-03-multi-session-continuity/index.md
@@ -13,6 +13,15 @@
두 번 실행합니다. 첫 번째는 제약 없이, 두 번째는 엄격한 적용 방식으로 진행합니다.
+## 저장소에 포함된 프로젝트 사용하기
+
+저장소 경로: `projects/project-03/`
+
+| 디렉터리 | 내용 | 비교할 것 |
+|------|------|------|
+| `starter/` | Project 02 코드에서 indexing과 citation 기반 Q&A가 아직 미완성입니다. 초기 `feature_list.json`은 있지만 최종 handoff/restart 산출물은 없습니다. | 여러 기능 사이에서 에이전트가 drift하거나 재시작 후 상태를 잃는지. |
+| `solution/` | chunking, metadata, index status, citation-based QA가 완성되어 있고 `init.sh`, `session-handoff.md`, `claude-progress.md`, `clean-state-checklist.md`가 있습니다. | 각 기능이 pass로 표시되기 전에 구체적 검증 증거가 있는지. |
+
## 도구
- Claude Code 또는 Codex
diff --git a/docs/ko/projects/project-04-incremental-indexing/index.md b/docs/ko/projects/project-04-incremental-indexing/index.md
index 10917b3..669206a 100644
--- a/docs/ko/projects/project-04-incremental-indexing/index.md
+++ b/docs/ko/projects/project-04-incremental-indexing/index.md
@@ -13,6 +13,17 @@
두 번 실행합니다. 첫 번째는 로그나 제약 없이, 두 번째는 적절한 도구와 규칙(rules)을 갖춘 상태로 진행합니다.
+## 저장소에 포함된 프로젝트 사용하기
+
+저장소 경로: `projects/project-04/`
+
+| 디렉터리 | 내용 | 비교할 것 |
+|------|------|------|
+| `starter/` | Project 03 코드이며 진단 신호가 약합니다. 삽입된 indexing 결함이 큰 파일 chunking을 깨뜨릴 수 있고 architecture check script가 없습니다. | runtime 신호 없이 근본 원인을 찾는 데 걸리는 시간. |
+| `solution/` | structured logger, architecture boundary docs/script, 수정된 chunking logic, `clean-state-checklist.md`가 있습니다. | logs와 boundary checks가 수정 속도와 안정성을 개선하는지. |
+
+확인 파일: `projects/project-04/solution/src/services/logger.ts`, `projects/project-04/solution/scripts/check-architecture.sh`, `projects/project-04/solution/docs/ARCHITECTURE.md`, `projects/project-04/solution/src/services/indexing-service.ts`.
+
## 도구
- Claude Code 또는 Codex
diff --git a/docs/ko/projects/project-05-grounded-qa-verification/index.md b/docs/ko/projects/project-05-grounded-qa-verification/index.md
index 1e44149..5c96ef4 100644
--- a/docs/ko/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/ko/projects/project-05-grounded-qa-verification/index.md
@@ -13,6 +13,17 @@
실질적인 기능 업그레이드(멀티턴 대화, 인용 패널 재설계, 또는 문서 필터링)를 선택하고 모든 실행에서 동일하게 유지합니다.
+## 저장소에 포함된 프로젝트 사용하기
+
+저장소 경로: `projects/project-05/`
+
+| 디렉터리 | 내용 | 비교할 것 |
+|------|------|------|
+| `starter/` | Project 04 기반 앱이며 대화 기록 업그레이드 전 상태입니다. | 세 변형을 다시 실행할 때의 시작점. |
+| `solution/single-role/` | 한 에이전트가 계획, 구현, 자기 평가를 모두 수행합니다. | `evaluator-rubric.md`의 점수와 결함. |
+| `solution/gen-eval/` | generator + evaluator 구조이며 수정 증거가 있습니다. | `evaluator-rubric.md`의 점수와 revision notes. |
+| `solution/plan-gen-eval/` | planner + generator + evaluator와 sprint contract가 있습니다. | `sprint-contract.md`와 `evaluator-rubric.md`의 높은 평가 증거. |
+
## 도구
- Claude Code 또는 Codex
diff --git a/docs/ko/projects/project-06-runtime-observability-and-debugging/index.md b/docs/ko/projects/project-06-runtime-observability-and-debugging/index.md
index d4ef174..223b93e 100644
--- a/docs/ko/projects/project-06-runtime-observability-and-debugging/index.md
+++ b/docs/ko/projects/project-06-runtime-observability-and-debugging/index.md
@@ -13,6 +13,15 @@
앞선 프로젝트들에서 개별적으로 효과를 확인한 메커니즘들이 함께 작동할 때 어떤 시너지를 만들어 내는지, 그리고 어떤 구성 요소를 제거했을 때 품질이 가장 크게 저하되는지 파악하는 것이 이 캡스톤의 핵심입니다.
+## 저장소에 포함된 프로젝트 사용하기
+
+저장소 경로: `projects/project-06/`
+
+| 디렉터리 | 내용 | 비교할 것 |
+|------|------|------|
+| `starter/` | 제품 기능은 거의 완성되어 있지만 harness 표면은 의도적으로 약합니다. 기본 `AGENTS.md`만 있고 `feature_list.json`, `session-handoff.md`, clean-state checklist, benchmark/cleanup scripts가 없습니다. | 약한 harness baseline의 수동 관찰. |
+| `solution/` | 완전한 harness: `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md`, 품질/평가 문서와 scripts. | `projects/project-06/solution/scripts/benchmark.sh`와 `projects/project-06/solution/scripts/cleanup-scanner.sh`를 실행하고 품질 증거를 비교합니다. |
+
## 도구
- Claude Code 또는 Codex
diff --git a/docs/ru/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/ru/projects/project-01-baseline-vs-minimal-harness/index.md
index 69c3a45..b088e2f 100644
--- a/docs/ru/projects/project-01-baseline-vs-minimal-harness/index.md
+++ b/docs/ru/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -11,7 +11,7 @@
Вы запускаете её дважды. Первый раз: только промпт, без подготовки. Второй раз: `AGENTS.md`, `init.sh`, `feature_list.json` уже размещены в репозитории. Затем сравниваете.
-Суть этого проекта не в написании кода — а в том, чтобы понять, насколько велика разница между «потратить 15 минут на правила» и «просто отпустить агента».
+Этот сценарий курса использует короткий интервал повторного исследования/подготовки как пример, а не как фиксированный измеренный результат.
## Инструменты
@@ -23,3 +23,14 @@
## Механизм harness
Минимальный harness: `AGENTS.md` + `init.sh` + `feature_list.json`
+
+## Используйте проект, уже добавленный в репозиторий
+
+Путь в репозитории: `projects/project-01/`
+
+| Каталог | Что внутри | Как использовать / что сравнивать |
+|------|------|------|
+| `starter/` | Запуск со слабым harness. Есть только `task-prompt.md` как описание задачи, без `AGENTS.md` и `feature_list.json`. | Дайте агенту prompt и измерьте, что он выполнит без дополнительной структуры. |
+| `solution/` | Тот же срез продукта с явными harness-артефактами: `AGENTS.md`, `CLAUDE.md`, `init.sh`, `feature_list.json`, `claude-progress.md`. | Сравните, как правила и проверка делают ту же задачу конкретной и проверяемой. |
+
+Четыре конкретные фичи: запуск окна, список документов, панель вопросов и ответов, создание локального каталога данных. Смотрите `solution/feature_list.json` для ожидаемых доказательств по каждой фиче.
diff --git a/docs/ru/projects/project-02-agent-readable-workspace/index.md b/docs/ru/projects/project-02-agent-readable-workspace/index.md
index d86d5e1..226ca6e 100644
--- a/docs/ru/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/ru/projects/project-02-agent-readable-workspace/index.md
@@ -11,6 +11,15 @@
Вы запускаете задачу дважды: первый раз — без какой-либо помощи, второй — с заранее размещёнными в репозитории `ARCHITECTURE.md`, `PRODUCT.md` и `session-handoff.md`.
+## Используйте проект из репозитория
+
+Путь: `projects/project-02/`
+
+| Каталог | Что внутри | Что сравнивать |
+|------|------|------|
+| `starter/` | Код Project 01, где импорт документов, детальная страница и persistence ещё не завершены. Документация есть, но она тоньше, и нет `session-handoff.md`. | Сколько контекста второй сессии агента приходится открывать заново. |
+| `solution/` | Тот же срез продукта завершён; документы для передачи состояния находятся в `projects/project-02/solution/`, также есть `feature_list.json` и `session-handoff.md`. | Может ли новая сессия продолжить работу только по состоянию репозитория. |
+
## Инструменты
- Claude Code или Codex
diff --git a/docs/ru/projects/project-03-multi-session-continuity/index.md b/docs/ru/projects/project-03-multi-session-continuity/index.md
index 7ba3404..f11c657 100644
--- a/docs/ru/projects/project-03-multi-session-continuity/index.md
+++ b/docs/ru/projects/project-03-multi-session-continuity/index.md
@@ -11,6 +11,15 @@
Вы запускаете задачу дважды: первый раз — без ограничений, второй — со строгим контролем.
+## Используйте проект из репозитория
+
+Путь: `projects/project-03/`
+
+| Каталог | Что внутри | Что сравнивать |
+|------|------|------|
+| `starter/` | Код Project 02, где indexing и Q&A с цитатами ещё не завершены. Есть начальный `feature_list.json`, но нет финальных файлов handoff/restart. | Теряет ли агент состояние или уходит ли в сторону между несколькими функциями. |
+| `solution/` | Готовы chunking, metadata, статус index и Q&A с цитатами; есть `init.sh`, `session-handoff.md`, `claude-progress.md`, `clean-state-checklist.md`. | Есть ли доказательство проверки перед отметкой функции как готовой. |
+
## Инструменты
- Claude Code или Codex
diff --git a/docs/ru/projects/project-04-incremental-indexing/index.md b/docs/ru/projects/project-04-incremental-indexing/index.md
index 5a32ea9..7daaa5e 100644
--- a/docs/ru/projects/project-04-incremental-indexing/index.md
+++ b/docs/ru/projects/project-04-incremental-indexing/index.md
@@ -11,6 +11,17 @@
Вы запускаете задачу дважды: первый раз — без логов и ограничений, второй — с правильными инструментами и правилами.
+## Используйте проект из репозитория
+
+Путь: `projects/project-04/`
+
+| Каталог | Что внутри | Что сравнивать |
+|------|------|------|
+| `starter/` | Код Project 03 со слабыми диагностическими сигналами. Встроенный дефект indexing может ломать chunking больших файлов; скрипта проверки архитектуры нет. | Как быстро агент находит причину без runtime-сигналов. |
+| `solution/` | Структурированный logger, документы и скрипт архитектурных границ, исправленная логика chunking и `clean-state-checklist.md`. | Помогают ли logs и проверки границ исправлять быстрее и аккуратнее. |
+
+Ключевые файлы: `projects/project-04/solution/src/services/logger.ts`, `projects/project-04/solution/scripts/check-architecture.sh`, `projects/project-04/solution/docs/ARCHITECTURE.md`, `projects/project-04/solution/src/services/indexing-service.ts`.
+
## Инструменты
- Claude Code или Codex
diff --git a/docs/ru/projects/project-05-grounded-qa-verification/index.md b/docs/ru/projects/project-05-grounded-qa-verification/index.md
index 41ce956..7213af5 100644
--- a/docs/ru/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/ru/projects/project-05-grounded-qa-verification/index.md
@@ -11,6 +11,17 @@
Выберите содержательную фичу-апгрейд (многоходовой диалог, редизайн панели цитирования или фильтрация документов) и удерживайте её одинаковой во всех запусках.
+## Используйте проект из репозитория
+
+Путь: `projects/project-05/`
+
+| Каталог | Что внутри | Что сравнивать |
+|------|------|------|
+| `starter/` | Приложение на базе Project 04 до добавления истории диалога. | Стартовая точка для повторного запуска трёх вариантов. |
+| `solution/single-role/` | Один агент планирует, реализует и сам себя оценивает. | Оценка и дефекты в `evaluator-rubric.md`. |
+| `solution/gen-eval/` | Generator + evaluator с доказательствами правок. | Оценка и заметки ревизии в `evaluator-rubric.md`. |
+| `solution/plan-gen-eval/` | Planner + generator + evaluator со sprint contract. | `sprint-contract.md` и более высокая оценка в `evaluator-rubric.md`. |
+
## Инструменты
- Claude Code или Codex
diff --git a/docs/ru/projects/project-06-runtime-observability-and-debugging/index.md b/docs/ru/projects/project-06-runtime-observability-and-debugging/index.md
index ce41159..3ca84c2 100644
--- a/docs/ru/projects/project-06-runtime-observability-and-debugging/index.md
+++ b/docs/ru/projects/project-06-runtime-observability-and-debugging/index.md
@@ -11,6 +11,15 @@
Используйте фиксированный набор multi-feature задач, охватывающий полный продуктовый срез: импорт документов, индексация, Q&A с цитатами, runtime-наблюдаемость и читаемое перезапускаемое состояние репозитория. Сначала запустите со слабым harness-baseline, затем с самым сильным harness, потом — уборку и повторный запуск. Наконец, проведите эксперимент с абляцией harness — убирайте по одному компоненту за раз и смотрите, какие из них реально важны.
+## Используйте проект из репозитория
+
+Путь: `projects/project-06/`
+
+| Каталог | Что внутри | Что сравнивать |
+|------|------|------|
+| `starter/` | Продукт почти готов, но harness намеренно ослаблен: базовый `AGENTS.md`, нет `feature_list.json`, `session-handoff.md`, clean-state checklist и benchmark/cleanup scripts. | Ручные наблюдения baseline со слабым harness. |
+| `solution/` | Полный harness: `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md`, quality/evaluator docs и scripts. | Запустить `projects/project-06/solution/scripts/benchmark.sh` и `projects/project-06/solution/scripts/cleanup-scanner.sh`, затем сравнить quality evidence. |
+
## Инструменты
- Claude Code или Codex
diff --git a/docs/tr/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/tr/projects/project-01-baseline-vs-minimal-harness/index.md
index f7f25d0..9c16c90 100644
--- a/docs/tr/projects/project-01-baseline-vs-minimal-harness/index.md
+++ b/docs/tr/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -11,7 +11,18 @@ Minimal bir Electron bilgi tabanı uygulama iskeleti inşa edin — solda doküm
İki kez çalıştırın. İlk seferinde: yalnızca bir prompt, hiçbir hazırlık yok. İkinci seferinde: `AGENTS.md`, `init.sh`, `feature_list.json` önceden depoya yerleştirilmiş. Sonra karşılaştırın.
-Bu projenin özü kod yazmak değil — "önce 15 dakika kuralları hazırlamak" ile "ajanı serbest bırakmak" arasındaki farkın ne kadar büyük olduğunu görmek.
+Kurs senaryosu kısa bir hazırlık veya yeniden keşif süresini örnek olarak kullanır; sabit ölçüm değerlerine bağlı değildir.
+
+## Depodaki projeyi kullanın
+
+Depo yolu: `projects/project-01/`
+
+| Dizin | İçerik | Nasıl kullanılır |
+|------|------|------|
+| `starter/` | Zayıf harness sürümü; yalnızca `task-prompt.md` vardır, `AGENTS.md` veya `feature_list.json` yoktur. | Prompt'u coding agent'a verin ve ek yapı olmadan neleri tamamladığını ölçün. |
+| `solution/` | Aynı ürün dilimi; ayrıca `AGENTS.md`, `CLAUDE.md`, `init.sh`, `feature_list.json`, `claude-progress.md` içerir. | Kuralların ve doğrulama kanıtlarının aynı görevi nasıl somutlaştırdığını karşılaştırın. |
+
+Dört somut özellik: pencerenin açılması, doküman listesi, Soru-Cevap paneli ve yerel veri dizini. Beklenen kanıt `solution/feature_list.json` içindedir.
## Araçlar
diff --git a/docs/tr/projects/project-02-agent-readable-workspace/index.md b/docs/tr/projects/project-02-agent-readable-workspace/index.md
index c8a0d70..0e3e7a1 100644
--- a/docs/tr/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/tr/projects/project-02-agent-readable-workspace/index.md
@@ -11,6 +11,17 @@ Depoya "okunabilirlik" ekleyin; böylece yeni bir ajan proje yapısını hızla
İki kez çalıştırın: ilk seferinde hiçbir yardım olmadan, ikinci seferinde `ARCHITECTURE.md`, `PRODUCT.md` ve `session-handoff.md` önceden depoya yerleştirilmiş şekilde.
+## Depodaki projeyi kullanın
+
+Depo yolu: `projects/project-02/`
+
+| Dizin | İçerik | Nasıl kullanılır |
+|------|------|------|
+| `starter/` | Project 01 kodu; tamamlanmamış doküman içe aktarma, detay görünümü ve kalıcılık içerir. Dokümanlar vardır ama incedir; `session-handoff.md` yoktur. | İkinci agent oturumunun ne kadar bağlamı yeniden keşfetmesi gerektiğini ölçün. |
+| `solution/` | Aynı ürün dilimini tamamlar ve `projects/project-02/solution/` altında çekirdek dokümanları, `feature_list.json` ve `session-handoff.md` dosyalarını ekler. | Yeni oturumun yalnızca depo durumuna bakarak çalışmaya devam edip edemediğini kontrol edin. |
+
+Ürün özellikleri doküman içe aktarma, tam detay/içerik yükleme ve yeniden başlatmalar arasında kalıcılıktır; harness özelliği ise devredilebilir, agent-readable workspace'tir.
+
## Araçlar
- Claude Code veya Codex
diff --git a/docs/tr/projects/project-03-multi-session-continuity/index.md b/docs/tr/projects/project-03-multi-session-continuity/index.md
index ddae745..fb6e7c2 100644
--- a/docs/tr/projects/project-03-multi-session-continuity/index.md
+++ b/docs/tr/projects/project-03-multi-session-continuity/index.md
@@ -7,10 +7,21 @@
## Ne Yapacaksınız
-Ajana kapsam kontrolü ve doğrulama eşikleri ekleyin. Doküman parçalama, üst veri çıkarımı, dizinleme ilerleme göstergesi ve alıntı tabanlı Soru-Cevap akışını uygulayın. Özellik durumunu izlemek için `feature_list.json` kullanın — aynı anda tek özellik, doğrulama kanıtı olmadan "geçti" işaretlemesi yok.
+Ajana kapsam kontrolü ve doğrulama eşikleri ekleyin. Doküman parçalama, üst veri çıkarımı, dizinleme ilerleme göstergesi ve alıntı tabanlı Soru-Cevap akışını uygulayın.
+
+Bir `feature_list.json` gerekir; her özelliğin açık bir durumu olmalıdır. Kural basittir: aynı anda tek özellik, çalışır doğrulama kanıtı olmadan `passing` işaretlemesi yok. Depodaki starter erken bir özellik listesi içerir ama tam yeniden başlatma ve devir artefaktları eksiktir; solution bu artefaktları tamamlar. İkisini karşılaştırın.
İki kez çalıştırın: ilk seferinde kısıt olmadan, ikinci seferinde katı uygulamayla.
+## Depodaki projeyi kullanın
+
+Depo yolu: `projects/project-03/`
+
+| Dizin | İçerik | Nasıl kullanılır |
+|------|------|------|
+| `starter/` | Project 02 kodu; indeksleme ve alıntılı Soru-Cevap tamamlanmamıştır. Starter sürümü `feature_list.json` içerir ama son yeniden başlatma/devir artefaktları eksiktir. | Agent'ın birden çok özellik arasında kayıp kaymadığını ve yeniden başlatmadan sonra durumu kaybedip kaybetmediğini ölçün. |
+| `solution/` | Doküman parçalama, üst veri, indeksleme durumu ve alıntılı Soru-Cevap tamamlanmıştır; ayrıca `init.sh`, `session-handoff.md`, `claude-progress.md`, `clean-state-checklist.md` eklenmiştir. | Her özelliğin ancak doğrulama kanıtı varsa `passing` olup olmadığını kontrol edin. |
+
## Araçlar
- Claude Code veya Codex
diff --git a/docs/tr/projects/project-04-incremental-indexing/index.md b/docs/tr/projects/project-04-incremental-indexing/index.md
index 5a3677d..563b633 100644
--- a/docs/tr/projects/project-04-incremental-indexing/index.md
+++ b/docs/tr/projects/project-04-incremental-indexing/index.md
@@ -9,8 +9,21 @@
Runtime gözlemlenebilirliği (başlangıç günlükleri, içe aktarma/dizinleme günlükleri, hata durumları) ve katmanlar arası ihlalleri önlemek için mimari kısıtlar ekleyin. Ajanın düzeltmesi için bir runtime hatası yerleştirin.
+Depodaki starter'da runtime bug'ı kasıtlı olarak bırakılmıştır; fakat tanılama sinyali zayıftır ve mimari kontrol betiği yoktur. Solution yapılandırılmış loglar, mimari kurallar ve düzeltilmiş parçalama mantığı ekler. Runtime geri bildiriminin düzeltme kalitesini nasıl etkilediğini karşılaştırın.
+
İki kez çalıştırın: ilk seferinde günlükler veya kısıtlar olmadan, ikinci seferinde uygun araçlar ve kurallarla.
+## Depodaki projeyi kullanın
+
+Depo yolu: `projects/project-04/`
+
+| Dizin | İçerik | Nasıl kullanılır |
+|------|------|------|
+| `starter/` | Project 03 kodu; tanılama sinyali zayıftır. Gömülü indexing hatası büyük dosya parçalamayı bozar ve mimari kontrol betiği yoktur. | Runtime sinyali yokken agent'ın kök nedeni ne kadar sürede bulduğunu ölçün. |
+| `solution/` | Yapılandırılmış logger, mimari sınır dokümanı ve betiği, düzeltilmiş parçalama mantığı ve `clean-state-checklist.md`. | Logların ve sınır kontrollerinin düzeltmeyi hızlandırıp daha az yan etki üretip üretmediğini kontrol edin. |
+
+Özellikle `projects/project-04/solution/src/services/logger.ts`, `projects/project-04/solution/scripts/check-architecture.sh`, `projects/project-04/solution/docs/ARCHITECTURE.md` ve `projects/project-04/solution/src/services/indexing-service.ts` dosyalarına bakın.
+
## Araçlar
- Claude Code veya Codex
diff --git a/docs/tr/projects/project-05-grounded-qa-verification/index.md b/docs/tr/projects/project-05-grounded-qa-verification/index.md
index 22f2749..f29e28a 100644
--- a/docs/tr/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/tr/projects/project-05-grounded-qa-verification/index.md
@@ -11,6 +11,19 @@ Rol ayrımını uygulayın — uygulamayı yapan bir üretici, inceleyen bir de
Esaslı bir özellik yükseltmesi seçin (çok turlu konuşma, alıntı paneli yeniden tasarımı veya doküman filtreleme) ve tüm çalıştırmalarda tutarlı tutun.
+## Depodaki projeyi kullanın
+
+Depo yolu: `projects/project-05/`
+
+| Dizin | İçerik | Nasıl kullanılır |
+|------|------|------|
+| `starter/` | ConversationHistory yükseltmesinden önceki Project 04 uygulaması. | Üç varyantı kendiniz yeniden çalıştırmak istiyorsanız buradan başlayın. |
+| `solution/single-role/` | Tek agent planlar, uygular ve kendini değerlendirir. | `evaluator-rubric.md` içinde 1.6/5 puan ve hata listesi vardır. |
+| `solution/gen-eval/` | Üretici + değerlendirici; revizyon kanıtı içerir. | `evaluator-rubric.md` içinde 3.3/5 puan ve revizyon kaydı vardır. |
+| `solution/plan-gen-eval/` | Planlayıcı + üretici + değerlendirici. | `sprint-contract.md` ve `evaluator-rubric.md` içinde 4.9/5 puan vardır. |
+
+Amaç, aynı ürün yükseltmesini üç farklı harness yapısıyla karşılaştırmaktır; rastgele farklı özellikler seçerseniz puanlar karşılaştırılamaz.
+
## Araçlar
- Claude Code veya Codex
diff --git a/docs/tr/projects/project-06-runtime-observability-and-debugging/index.md b/docs/tr/projects/project-06-runtime-observability-and-debugging/index.md
index 07cf854..6e419ca 100644
--- a/docs/tr/projects/project-06-runtime-observability-and-debugging/index.md
+++ b/docs/tr/projects/project-06-runtime-observability-and-debugging/index.md
@@ -11,6 +11,17 @@ Bu, bitirme projesidir. İlk beş projede öğrendiğiniz her şeyi bir araya ge
Tüm ürün dilimini kapsayan sabit, çok özellikli bir görev seti kullanın: doküman içe aktarma, dizinleme, alıntı tabanlı Soru-Cevap, runtime gözlemlenebilirliği ve okunabilir, yeniden başlatılabilir depo durumu. Önce zayıf harness temeli ile, sonra en güçlü harness'ınızla, ardından bir temizleme ve yeniden çalıştırma. Son olarak bir harness ablation deneyi yapın — bileşenleri tek tek çıkarın ve hangilerinin gerçekten önemli olduğunu görün.
+## Depodaki projeyi kullanın
+
+Depo yolu: `projects/project-06/`
+
+| Dizin | İçerik | Nasıl kullanılır |
+|------|------|------|
+| `starter/` | Ürün kodunun çoğu tamamlanmıştır; fakat harness yüzeyi zayıftır: yalnızca temel `AGENTS.md` vardır, `feature_list.json`, `session-handoff.md` ve clean-state checklist yoktur. | Zayıf harness temelini elle kaydedin. Starter kasıtlı olarak benchmark betiği içermez. |
+| `solution/` | Tam harness: `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md`, kalite/değerlendirme dokümanları, benchmark ve cleanup betikleri. | `projects/project-06/solution/scripts/benchmark.sh` ve `projects/project-06/solution/scripts/cleanup-scanner.sh` çalıştırın; kalite dokümanı kanıtlarını karşılaştırın. |
+
+Önceki projelerden farklı olarak capstone starter çok sayıda ürün özelliğinden yoksun değildir; ana eksik uygulamanın etrafındaki operasyonel harness'tır.
+
## Araçlar
- Claude Code veya Codex
diff --git a/docs/uz/GLOSSARY.md b/docs/uz/GLOSSARY.md
index d3a7fdd..f03aeea 100644
--- a/docs/uz/GLOSSARY.md
+++ b/docs/uz/GLOSSARY.md
@@ -70,11 +70,11 @@ Ushbu hujjat barcha tarjimalarda atamalar bir xil qoʻllanishini taʼminlaydi. Y
- **Tafsif:** Modelda imkoniyat bor, lekin muhitda nuqson tufayli yiqilish.
- **Qoʻllash:** Toʻliq atama saqlanadi. Tarjimaga "harness sabab" deb yozmang — "harness keltirib chiqargan" toʻgʻri.
-### Context Anxiety
-- **EN:** Context anxiety
-- **UZ:** Kontekst xavotiri (context anxiety)
-- **Tafsif:** Agent kontekst tugayotganini sezsa shoshilib oddiy yechimni tanlaydigan hodisa.
-- **Qoʻllash:** Birinchi marta toʻliq, keyin `kontekst xavotiri`.
+### Context Pressure
+- **EN:** Context pressure
+- **UZ:** Kontekst bosimi (context pressure)
+- **Tafsif:** Kontekst haddan tashqari gavjumlashganda agent ishni erta yakunlashga, tekshiruvni qisqartirishga yoki soddaroq yoʻlni tanlashga moyil boʻladigan kurs atamasi.
+- **Qoʻllash:** Birinchi marta toʻliq, keyin `kontekst bosimi`.
### Five Failure Layers (Beshta muvaffaqiyatsizlik qatlami)
diff --git a/docs/uz/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/uz/projects/project-01-baseline-vs-minimal-harness/index.md
index 79e1fbc..d2d1f47 100644
--- a/docs/uz/projects/project-01-baseline-vs-minimal-harness/index.md
+++ b/docs/uz/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -11,7 +11,7 @@ Minimal Electron bilimlar bazasi (knowledge-base) ilovasi (app) qobigʻini qurin
Buni ikki marta ishga tushirasiz. Birinchi marta: hech qanday tayyorgarliksiz, faqat prompt bilan. Ikkinchi marta: repoda oldindan joylashtirilgan `AGENTS.md`, `init.sh`, `feature_list.json` bilan. Va keyin taqqoslaysiz.
-Bu loyihaning asosiy maqsadi kod yozish emas — “avval qoidalarni tayyorlash uchun 15 daqiqa sarflash” bilan “shunchaki agentga qoʻyib berish” oʻrtasidagi tafovut qanchalik katta ekanligini anglab yetishdir.
+Bu kurs ssenariysi qatʼiy oʻlchangan natijaga emas, balki qisqa qayta kashf qilish/tayyorgarlik oraligʻini misol sifatida oladi.
## Vositalar
@@ -23,3 +23,14 @@ Bu loyihaning asosiy maqsadi kod yozish emas — “avval qoidalarni tayyorlash
## Harness mexanizmi
Minimal harness: `AGENTS.md` + `init.sh` + `feature_list.json`
+
+## Repoga kiritilgan loyihadan foydalaning
+
+Repo yo‘li: `projects/project-01/`
+
+| Katalog | Nimalar bor | Qanday ishlatish / nimani taqqoslash |
+|------|------|------|
+| `starter/` | Zaif harness yugurishi. Vazifa tavsifi sifatida faqat `task-prompt.md` bor, `AGENTS.md` yoki `feature_list.json` yo‘q. | Promptni agentga bering va qo‘shimcha tuzilmasiz nimalarni tugatishini o‘lchang. |
+| `solution/` | Xuddi shu mahsulot kesimi, lekin aniq harness artefaktlari bilan: `AGENTS.md`, `CLAUDE.md`, `init.sh`, `feature_list.json`, `claude-progress.md`. | Qoidalar va tekshiruv bir xil vazifani qanday aniq va tekshiriladigan qiladi — taqqoslang. |
+
+4 ta aniq feature: oynani ishga tushirish, hujjatlar ro‘yxati, savol paneli va lokal ma’lumotlar katalogini yaratish. Har bir feature uchun kutiladigan evidence `solution/feature_list.json`da.
diff --git a/docs/uz/projects/project-02-agent-readable-workspace/index.md b/docs/uz/projects/project-02-agent-readable-workspace/index.md
index 8de6d65..f9d5935 100644
--- a/docs/uz/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/uz/projects/project-02-agent-readable-workspace/index.md
@@ -11,6 +11,15 @@ Yangi agent loyiha tuzilishini tez tushunib olishi, joriy jarayon (progress) qay
Siz buni ikki marta bajarasiz: birinchisi hech qanday yordamsiz, ikkinchisi repoda oldindan joylashtirilgan `ARCHITECTURE.md`, `PRODUCT.md` va `session-handoff.md` fayllari bilan.
+## Repodagi tayyor loyihadan foydalaning
+
+Repo yoʻli: `projects/project-02/`
+
+| Katalog | Nimalar bor | Nimani taqqoslash |
+|------|------|------|
+| `starter/` | Project 01 kodi, lekin hujjat importi, detail view va persistence hali toʻliq emas. Hujjatlar bor, ammo qisqaroq; `session-handoff.md` yoʻq. | Ikkinchi agent sessiyasi qancha kontekstni qayta topishi kerak. |
+| `solution/` | Xuddi shu mahsulot kesimi tugallangan; handoff hujjatlari `projects/project-02/solution/` ostida, shuningdek `feature_list.json` va `session-handoff.md` bor. | Yangi sessiya faqat repo holatidan davom eta oladimi. |
+
## Vositalar
- Claude Code yoki Codex
diff --git a/docs/uz/projects/project-03-multi-session-continuity/index.md b/docs/uz/projects/project-03-multi-session-continuity/index.md
index 6b5baa8..b47a085 100644
--- a/docs/uz/projects/project-03-multi-session-continuity/index.md
+++ b/docs/uz/projects/project-03-multi-session-continuity/index.md
@@ -11,6 +11,15 @@ Agentga skoup nazorati (scope control) va tekshirish eshiklarini (verification g
Siz buni ikki marta bajarasiz: birinchisida hech qanday cheklovlarsiz, ikkinchisida esa qatʼiy talablar asosida.
+## Repodagi tayyor loyihadan foydalaning
+
+Repo yoʻli: `projects/project-03/`
+
+| Katalog | Nimalar bor | Nimani taqqoslash |
+|------|------|------|
+| `starter/` | Project 02 kodi, indexing va citation-based Q&A hali tugallanmagan. Boshlangʻich `feature_list.json` bor, lekin yakuniy handoff/restart artefaktlari yoʻq. | Agent bir nechta feature orasida chalgʻiydimi yoki restartdan keyin holatni yoʻqotadimi. |
+| `solution/` | Chunking, metadata, index status va citation-based Q&A tugallangan; `init.sh`, `session-handoff.md`, `claude-progress.md`, `clean-state-checklist.md` bor. | Har bir feature pass bo‘lishidan oldin aniq tekshiruv daliliga egami. |
+
## Vositalar
- Claude Code yoki Codex
diff --git a/docs/uz/projects/project-04-incremental-indexing/index.md b/docs/uz/projects/project-04-incremental-indexing/index.md
index a2287d3..0ce497f 100644
--- a/docs/uz/projects/project-04-incremental-indexing/index.md
+++ b/docs/uz/projects/project-04-incremental-indexing/index.md
@@ -11,6 +11,17 @@ Qatlamlararo qoidabuzilishlarning (cross-layer violations) oldini olish uchun ru
Siz buni ikki marta bajarasiz: birinchisida loglar va cheklovlarsiz, ikkinchisida tegishli vositalar va qoidalar bilan.
+## Repodagi tayyor loyihadan foydalaning
+
+Repo yoʻli: `projects/project-04/`
+
+| Katalog | Nimalar bor | Nimani taqqoslash |
+|------|------|------|
+| `starter/` | Project 03 kodi, diagnostika signallari zaif. Kiritilgan indexing nuqsoni katta fayllar chunkingʼini buzishi mumkin; architecture check script yoʻq. | Runtime signallarsiz agent root causeʼni qancha vaqtda topadi. |
+| `solution/` | Structured logger, architecture boundary hujjatlari va script, tuzatilgan chunking logic, `clean-state-checklist.md`. | Logs va boundary checks tuzatishni tezroq va kamroq xavfli qiladimi. |
+
+Tekshiriladigan fayllar: `projects/project-04/solution/src/services/logger.ts`, `projects/project-04/solution/scripts/check-architecture.sh`, `projects/project-04/solution/docs/ARCHITECTURE.md`, `projects/project-04/solution/src/services/indexing-service.ts`.
+
## Vositalar
- Claude Code yoki Codex
diff --git a/docs/uz/projects/project-05-grounded-qa-verification/index.md b/docs/uz/projects/project-05-grounded-qa-verification/index.md
index 7789c9e..ef5657e 100644
--- a/docs/uz/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/uz/projects/project-05-grounded-qa-verification/index.md
@@ -11,6 +11,17 @@ Rollarni ajratishni (role separation) amalga oshiring — kod yozuvchi (generato
Diqqatga sazovor boʻlgan biror funksiya yangilanishini tanlang (koʻp bosqichli suhbat, iqtibos panelini qayta dizayn qilish yoki hujjatlarni filtrlash) va uni barcha urinishlar davomida bir xil qilib saqlang.
+## Repodagi tayyor loyihadan foydalaning
+
+Repo yoʻli: `projects/project-05/`
+
+| Katalog | Nimalar bor | Nimani taqqoslash |
+|------|------|------|
+| `starter/` | Project 04 asosidagi app, conversation history upgradeʼdan oldingi holat. | Uch variantni qayta ishga tushirish uchun boshlangʻich nuqta. |
+| `solution/single-role/` | Bitta agent rejalaydi, implement qiladi va oʻzini baholaydi. | `evaluator-rubric.md`dagi ball va nuqsonlar. |
+| `solution/gen-eval/` | Generator + evaluator, revision dalillari bor. | `evaluator-rubric.md`dagi ball va revision notes. |
+| `solution/plan-gen-eval/` | Planner + generator + evaluator va sprint contract. | `sprint-contract.md` hamda `evaluator-rubric.md`dagi yuqoriroq baho dalillari. |
+
## Vositalar
- Claude Code yoki Codex
diff --git a/docs/uz/projects/project-06-runtime-observability-and-debugging/index.md b/docs/uz/projects/project-06-runtime-observability-and-debugging/index.md
index ed167df..ba3f3ed 100644
--- a/docs/uz/projects/project-06-runtime-observability-and-debugging/index.md
+++ b/docs/uz/projects/project-06-runtime-observability-and-debugging/index.md
@@ -11,6 +11,15 @@ Bu capstone (yakunlovchi) loyihadir. Dastlabki beshta loyihada oʻrganilgan barc
Toʻliq mahsulot boʻlagini (product slice) qamrab oladigan qatʼiy koʻp funksiyali (multi-feature) vazifalar toʻplamidan foydalaning: hujjatni import qilish, indekslash, iqtiboslarga asoslangan Q&A, runtime kuzatuvchanligi va oʻqish mumkin boʻlgan qayta ishga tushiriladigan (restartable) repo holati. Avval kuchsiz asosiy (baseline) harness bilan ishga tushiring, soʻngra oʻzingizning eng kuchli harnessʼingiz bilan, oxirida esa tozalash qilib, qayta ishlating. Va nihoyat, harnessʼda ablasyon (ablation) tajribasini oʻtkazing — har bir komponentni bittadan olib tashlang va haqiqatda qaysi biri muhim ekanligini aniqlang.
+## Repodagi tayyor loyihadan foydalaning
+
+Repo yoʻli: `projects/project-06/`
+
+| Katalog | Nimalar bor | Nimani taqqoslash |
+|------|------|------|
+| `starter/` | Mahsulot deyarli tayyor, lekin harness ataylab zaiflashtirilgan: faqat asosiy `AGENTS.md`, `feature_list.json`, `session-handoff.md`, clean-state checklist va benchmark/cleanup scripts yoʻq. | Zaif harness baselineʼini qoʻlda kuzatish. |
+| `solution/` | Toʻliq harness: `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md`, quality/evaluator docs va scripts. | `projects/project-06/solution/scripts/benchmark.sh` va `projects/project-06/solution/scripts/cleanup-scanner.sh`ni ishga tushirib, quality evidenceʼni taqqoslash. |
+
## Vositalar
- Claude Code yoki Codex
diff --git a/docs/vi/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/vi/projects/project-01-baseline-vs-minimal-harness/index.md
index d7abd3b..626cb6e 100644
--- a/docs/vi/projects/project-01-baseline-vs-minimal-harness/index.md
+++ b/docs/vi/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -11,7 +11,7 @@ Xây dựng một ứng dụng Electron knowledge-base shell tối giản — m
Bạn chạy hai lần. Lần đầu: chỉ một prompt, không chuẩn bị gì. Lần hai: `AGENTS.md`, `init.sh`, `feature_list.json` được đặt sẵn trong repo. Sau đó so sánh.
-Cốt lõi của dự án này không phải là viết mã — mà là tìm hiểu khoảng cách lớn thế nào giữa "dành 15 phút chuẩn bị quy tắc trước" và "cứ để agent tự làm."
+Kịch bản của bài học này dùng một khoảng tái khám phá/chuẩn bị ngắn làm ví dụ, không phải kết quả đo cố định.
## Công cụ
@@ -23,3 +23,14 @@ Cốt lõi của dự án này không phải là viết mã — mà là tìm hi
## Cơ chế Harness
Harness tối giản: `AGENTS.md` + `init.sh` + `feature_list.json`
+
+## Dùng project đã có sẵn trong repo
+
+Đường dẫn trong repo: `projects/project-01/`
+
+| Thư mục | Có gì bên trong | Cách dùng / so sánh |
+|------|------|------|
+| `starter/` | Lượt chạy harness yếu. Chỉ có `task-prompt.md` làm mô tả nhiệm vụ, không có `AGENTS.md` hay `feature_list.json`. | Đưa prompt cho agent và đo xem nó hoàn thành được gì khi không có cấu trúc bổ sung. |
+| `solution/` | Cùng slice sản phẩm nhưng có artefact harness rõ ràng: `AGENTS.md`, `CLAUDE.md`, `init.sh`, `feature_list.json`, `claude-progress.md`. | So sánh cách quy tắc và kiểm chứng biến cùng nhiệm vụ thành thứ có thể chạy và kiểm tra được. |
+
+Bốn tính năng cụ thể là: mở cửa sổ, danh sách tài liệu, panel câu hỏi, và tạo thư mục dữ liệu cục bộ. Xem `solution/feature_list.json` để biết bằng chứng mong đợi cho từng tính năng.
diff --git a/docs/vi/projects/project-02-agent-readable-workspace/index.md b/docs/vi/projects/project-02-agent-readable-workspace/index.md
index 68a4fa9..07b9c46 100644
--- a/docs/vi/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/vi/projects/project-02-agent-readable-workspace/index.md
@@ -11,6 +11,15 @@ Thêm "khả năng đọc được" vào repo để một agent mới có thể
Bạn chạy hai lần: lần đầu không có sự trợ giúp nào, lần hai với `ARCHITECTURE.md`, `PRODUCT.md`, và `session-handoff.md` được đặt sẵn trong repo.
+## Dùng project có sẵn trong repo
+
+Đường dẫn repo: `projects/project-02/`
+
+| Thư mục | Nội dung | So sánh gì |
+|------|------|------|
+| `starter/` | Code từ Project 01, nhưng import tài liệu, trang chi tiết và persistence vẫn chưa hoàn chỉnh. Tài liệu có nhưng mỏng hơn, và không có `session-handoff.md`. | Phiên agent thứ hai phải tự khám phá lại bao nhiêu ngữ cảnh. |
+| `solution/` | Cùng phạm vi sản phẩm đã hoàn thành, có tài liệu handoff dưới `projects/project-02/solution/`, cùng `feature_list.json` và `session-handoff.md`. | Phiên mới có thể tiếp tục chỉ từ trạng thái repo hay không. |
+
## Công cụ
- Claude Code hoặc Codex
diff --git a/docs/vi/projects/project-03-multi-session-continuity/index.md b/docs/vi/projects/project-03-multi-session-continuity/index.md
index a0ac963..9bde8e5 100644
--- a/docs/vi/projects/project-03-multi-session-continuity/index.md
+++ b/docs/vi/projects/project-03-multi-session-continuity/index.md
@@ -11,6 +11,15 @@ Thêm kiểm soát phạm vi và cổng xác minh vào agent. Triển khai docum
Bạn chạy hai lần: lần đầu không có ràng buộc, lần hai với thực thi nghiêm ngặt.
+## Dùng project có sẵn trong repo
+
+Đường dẫn repo: `projects/project-03/`
+
+| Thư mục | Nội dung | So sánh gì |
+|------|------|------|
+| `starter/` | Code Project 02 với indexing và Q&A có citation vẫn chưa hoàn chỉnh. Có `feature_list.json` ban đầu nhưng chưa có artefact handoff/restart cuối cùng. | Agent có drift qua nhiều tính năng hoặc mất trạng thái sau restart không. |
+| `solution/` | Chunking, metadata, index status và citation-based QA đã hoàn thành, thêm `init.sh`, `session-handoff.md`, `claude-progress.md`, `clean-state-checklist.md`. | Mỗi tính năng có bằng chứng kiểm chứng trước khi đánh dấu pass không. |
+
## Công cụ
- Claude Code hoặc Codex
diff --git a/docs/vi/projects/project-04-incremental-indexing/index.md b/docs/vi/projects/project-04-incremental-indexing/index.md
index fdaba73..69e210d 100644
--- a/docs/vi/projects/project-04-incremental-indexing/index.md
+++ b/docs/vi/projects/project-04-incremental-indexing/index.md
@@ -11,6 +11,17 @@ Thêm observability runtime (log khởi động, log import/indexing, trạng th
Bạn chạy hai lần: lần đầu không có log hoặc ràng buộc, lần hai với các công cụ và quy tắc phù hợp.
+## Dùng project có sẵn trong repo
+
+Đường dẫn repo: `projects/project-04/`
+
+| Thư mục | Nội dung | So sánh gì |
+|------|------|------|
+| `starter/` | Code Project 03 với tín hiệu chẩn đoán yếu. Lỗi indexing được cài sẵn có thể làm hỏng chunking file lớn, và không có script kiểm tra kiến trúc. | Agent mất bao lâu để tìm root cause khi thiếu runtime signals. |
+| `solution/` | Structured logger, tài liệu/script ranh giới kiến trúc, logic chunking đã sửa và `clean-state-checklist.md`. | Logs và boundary checks có giúp sửa nhanh hơn, ít xâm lấn hơn không. |
+
+File cần xem: `projects/project-04/solution/src/services/logger.ts`, `projects/project-04/solution/scripts/check-architecture.sh`, `projects/project-04/solution/docs/ARCHITECTURE.md`, `projects/project-04/solution/src/services/indexing-service.ts`.
+
## Công cụ
- Claude Code hoặc Codex
diff --git a/docs/vi/projects/project-05-grounded-qa-verification/index.md b/docs/vi/projects/project-05-grounded-qa-verification/index.md
index 3c1302d..3487dcf 100644
--- a/docs/vi/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/vi/projects/project-05-grounded-qa-verification/index.md
@@ -11,6 +11,17 @@ Triển khai phân tách vai trò — một generator thực hiện, một evalu
Chọn một tính năng nâng cấp thực chất (hội thoại đa lượt, thiết kế lại citation panel, hoặc lọc tài liệu) và giữ nó nhất quán qua tất cả các lần chạy.
+## Dùng project có sẵn trong repo
+
+Đường dẫn repo: `projects/project-05/`
+
+| Thư mục | Nội dung | So sánh gì |
+|------|------|------|
+| `starter/` | Ứng dụng dựa trên Project 04 trước khi nâng cấp lịch sử hội thoại. | Điểm bắt đầu nếu muốn chạy lại ba biến thể. |
+| `solution/single-role/` | Một agent tự lập kế hoạch, triển khai và tự đánh giá. | Điểm số và lỗi trong `evaluator-rubric.md`. |
+| `solution/gen-eval/` | Generator + evaluator, có bằng chứng sửa đổi. | Điểm số và revision notes trong `evaluator-rubric.md`. |
+| `solution/plan-gen-eval/` | Planner + generator + evaluator với sprint contract. | `sprint-contract.md` và bằng chứng điểm cao hơn trong `evaluator-rubric.md`. |
+
## Công cụ
- Claude Code hoặc Codex
diff --git a/docs/vi/projects/project-06-runtime-observability-and-debugging/index.md b/docs/vi/projects/project-06-runtime-observability-and-debugging/index.md
index f36607d..02401ed 100644
--- a/docs/vi/projects/project-06-runtime-observability-and-debugging/index.md
+++ b/docs/vi/projects/project-06-runtime-observability-and-debugging/index.md
@@ -11,6 +11,15 @@
Sử dụng một bộ tác vụ đa tính năng cố định bao phủ toàn bộ product slice: import tài liệu, indexing, Q&A dựa trên trích dẫn, observability runtime, và trạng thái repo có thể đọc và khởi động lại. Lần đầu chạy với baseline harness yếu, sau đó với harness mạnh nhất của bạn, sau đó dọn dẹp và chạy lại. Cuối cùng, thực hiện thí nghiệm ablation harness — xóa từng thành phần một và xem cái nào thực sự quan trọng.
+## Dùng project có sẵn trong repo
+
+Đường dẫn repo: `projects/project-06/`
+
+| Thư mục | Nội dung | So sánh gì |
+|------|------|------|
+| `starter/` | Sản phẩm gần như hoàn chỉnh, nhưng harness bị cố ý làm yếu: chỉ có `AGENTS.md` cơ bản, không có `feature_list.json`, `session-handoff.md`, clean-state checklist hay benchmark/cleanup scripts. | Ghi nhận thủ công baseline với harness yếu. |
+| `solution/` | Harness đầy đủ: `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md`, tài liệu chất lượng/đánh giá và scripts. | Chạy `projects/project-06/solution/scripts/benchmark.sh` và `projects/project-06/solution/scripts/cleanup-scanner.sh`, rồi so sánh bằng chứng chất lượng. |
+
## Công cụ
- Claude Code hoặc Codex
diff --git a/docs/zh-TW/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/zh-TW/projects/project-01-baseline-vs-minimal-harness/index.md
index 22bbe76..9b74216 100644
--- a/docs/zh-TW/projects/project-01-baseline-vs-minimal-harness/index.md
+++ b/docs/zh-TW/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -9,7 +9,18 @@
你需要跑兩次。第一次只給一段提示詞,什麼都不準備,看 agent 能做到什麼程度。第二次提前在倉庫裡放好 `AGENTS.md`、`init.sh`、`feature_list.json`,用結構化的方式告訴 agent 該幹什麼、怎麼驗證、什麼時候算做完。然後對比兩次結果。
-這個項目的核心不是寫代碼,是搞清楚"提前花 15 分鐘準備規則"和"上來就讓 agent 幹"之間到底差多少。
+課程場景使用一小段準備或重新探索時間作為示例,不依賴固定測量值。
+
+## 使用倉庫內建專案
+
+倉庫路徑:`projects/project-01/`
+
+| 目錄 | 內容 | 怎麼用 / 比較什麼 |
+|------|------|------|
+| `starter/` | 弱 harness 版本。只有 `task-prompt.md` 作為任務描述,沒有 `AGENTS.md` 或 `feature_list.json`。 | 把 prompt 交給 coding agent,量測它在沒有額外結構時完成了什麼。 |
+| `solution/` | 相同的產品切片,但加入明確的 harness 產物:`AGENTS.md`、`CLAUDE.md`、`init.sh`、`feature_list.json`、`claude-progress.md`。 | 對照規則與驗證證據如何把同一任務變得可執行、可驗收。 |
+
+四個具體功能是:視窗啟動、文件清單、問答面板、本地資料目錄建立。每個功能的預期證據請看 `solution/feature_list.json`。
## 用什麼工具
diff --git a/docs/zh-TW/projects/project-02-agent-readable-workspace/index.md b/docs/zh-TW/projects/project-02-agent-readable-workspace/index.md
index b5c4c55..a40ce78 100644
--- a/docs/zh-TW/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/zh-TW/projects/project-02-agent-readable-workspace/index.md
@@ -11,6 +11,15 @@ P01 證明了準備規則有用。但 P01 的任務一次會話就幹完了。
你需要跑兩次。第一次不給 agent 任何幫助,看它在第二個會話裡要花多久才能"接上"。第二次提前放好 `ARCHITECTURE.md`、`PRODUCT.md`、`session-handoff.md`,讓它快速對齊上下文。
+## 使用倉庫內建專案
+
+倉庫路徑:`projects/project-02/`
+
+| 目錄 | 內容 | 比較什麼 |
+|------|------|------|
+| `starter/` | 基於 Project 01 solution 的代碼,但導入/詳情/持久化仍未完整;文檔更薄,且缺少 `session-handoff.md`。 | 新開會話時,agent 需要做多少重新探索才能接上進度。 |
+| `solution/` | 同一產品切片已完成,並在 `projects/project-02/solution/` 下補齊核心文檔(以及 `feature_list.json`、`session-handoff.md`)等可接手產物。 | 只依靠倉庫狀態,能否快速續寫而不靠口頭上下文。 |
+
## 用什麼工具
- Claude Code 或 Codex(和 P01 保持一致)
diff --git a/docs/zh-TW/projects/project-03-multi-session-continuity/index.md b/docs/zh-TW/projects/project-03-multi-session-continuity/index.md
index a6cf4c8..07f9365 100644
--- a/docs/zh-TW/projects/project-03-multi-session-continuity/index.md
+++ b/docs/zh-TW/projects/project-03-multi-session-continuity/index.md
@@ -11,6 +11,15 @@ P02 解決了"接手"的問題,但 agent 接手之後能不能把活幹完、
你需要一個 `feature_list.json`,每個功能有明確的狀態(failing / passing)。規則很簡單:一次只做一個功能,沒有可運行的驗證證據就不能標成 passing。跑兩次,一次不給這些約束,一次嚴格執行,看結果差多少。
+## 使用倉庫內建專案
+
+倉庫路徑:`projects/project-03/`
+
+| 目錄 | 內容 | 比較什麼 |
+|------|------|------|
+| `starter/` | Project 02 代碼基礎上,索引與 grounded QA 尚未完善;有初版 `feature_list.json`,但缺少最終的重啟/交接與乾淨狀態產物。 | 多次重啟/多功能任務下,agent 是否漂移、是否丟狀態。 |
+| `solution/` | 完整的 chunking、metadata、indexing status、citation-based QA,並補齊 `init.sh`、`session-handoff.md`、`claude-progress.md`、`clean-state-checklist.md`。 | 是否能做到“一次只做一個功能”,且每個功能都有可執行證據才標記通過。 |
+
## 用什麼工具
- Claude Code 或 Codex
diff --git a/docs/zh-TW/projects/project-04-incremental-indexing/index.md b/docs/zh-TW/projects/project-04-incremental-indexing/index.md
index bd48f66..5736dc3 100644
--- a/docs/zh-TW/projects/project-04-incremental-indexing/index.md
+++ b/docs/zh-TW/projects/project-04-incremental-indexing/index.md
@@ -11,6 +11,15 @@
然後你會在代碼裡埋一個運行時 bug,讓 agent 去修。跑兩次:一次不給日誌和約束,看 agent 怎麼修;一次給好日誌和架構規則,看差別。
+## 使用倉庫內建專案
+
+倉庫路徑:`projects/project-04/`
+
+| 目錄 | 內容 | 比較什麼 |
+|------|------|------|
+| `starter/` | Project 03 代碼,但診斷較弱;存在一個種子缺陷,可能導致大文件 chunking/索引失敗;也沒有架構檢查腳本。 | 沒有運行時信號時,定位根因需要多久、改動是否擴散。 |
+| `solution/` | 結構化 logger、架構邊界文檔與腳本、修復 chunking/索引邏輯,並補齊 `clean-state-checklist.md`。 | 有日誌與邊界檢查後,修復是否更快、更可控、可復現。 |
+
## 用什麼工具
- Claude Code 或 Codex
diff --git a/docs/zh-TW/projects/project-05-grounded-qa-verification/index.md b/docs/zh-TW/projects/project-05-grounded-qa-verification/index.md
index 022be09..dc4f54f 100644
--- a/docs/zh-TW/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/zh-TW/projects/project-05-grounded-qa-verification/index.md
@@ -11,12 +11,23 @@
選一個實質性的功能升級(比如多輪對話歷史、引用面板重設計、文檔集合與篩選),三次都做同一個升級,唯一變量是 harness 的角色分工。
+## 使用倉庫內建專案
+
+倉庫路徑:`projects/project-05/`
+
+| 目錄 | 內容 | 比較什麼 |
+|------|------|------|
+| `starter/` | 基於 Project 04 的應用,尚未做 ConversationHistory(多輪對話歷史)升級。 | 若你要自己重跑三種變體,從這裡開始。 |
+| `solution/single-role/` | 單角色:同一個 agent 規劃/實作/自查。 | `evaluator-rubric.md` 低分與缺陷清單。 |
+| `solution/gen-eval/` | 生成者 + 評估者:有修訂與回饋證據。 | `evaluator-rubric.md` 分數與 revision 記錄。 |
+| `solution/plan-gen-eval/` | 規劃者 + 生成者 + 評估者:有 sprint contract。 | `sprint-contract.md` 與 `evaluator-rubric.md` 高分證據。 |
+
## 用什麼工具
- Claude Code 或 Codex(用於生成和規劃角色)
- 同一個或另一個 agent 實例(用於評估角色)
- 評估量表(參考 `docs/zh-TW/resources/templates/evaluator-rubric.md`)
-- Sprint contract 範本(參考 `docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md`)
+- Sprint contract 範本(參考 `docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md`)
## 具體步驟
diff --git a/docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.md b/docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.md
index bae97c4..b97dec3 100644
--- a/docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.md
+++ b/docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.md
@@ -9,6 +9,15 @@
你要用一套固定的多功能任務集,覆蓋知識庫應用的完整產品切片:導入文檔、構建索引、帶引用的問答、運行時可觀測性、可讀可重啟的倉庫狀態。先跑一次弱 harness 基線,再跑一次你組裝的最強 harness,然後做一輪清理和重跑。最後還要做一次 harness 精簡實驗——刪掉一個組件看看結果會不會變差,判斷哪些組件是真正有用的、哪些是多餘的開銷。
+## 使用倉庫內建專案
+
+倉庫路徑:`projects/project-06/`
+
+| 目錄 | 內容 | 怎麼用 / 比較什麼 |
+|------|------|------|
+| `starter/` | 產品功能基本完整,但 harness 表面刻意削弱(只有基礎 `AGENTS.md`,沒有 `feature_list.json` / `session-handoff.md` / `clean-state-checklist.md`,也沒有 benchmark/cleanup 腳本)。 | 手動記錄弱 harness 基線行為(錯誤定位速度、是否過早宣告完成等)。 |
+| `solution/` | 最大化 harness:`AGENTS.md`、`CLAUDE.md`、`feature_list.json`、`init.sh`、`session-handoff.md`、`clean-state-checklist.md`、品質/評估文檔、benchmark 與 cleanup 腳本。 | 在 `projects/project-06/solution/` 下跑 `./scripts/benchmark.sh` 與 `./scripts/cleanup-scanner.sh`,再對照品質文檔證據。 |
+
## 用什麼工具
- Claude Code 或 Codex
diff --git a/docs/zh/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/zh/projects/project-01-baseline-vs-minimal-harness/index.md
index a9d2ad4..1ecb68e 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
@@ -9,7 +9,18 @@
你需要跑两次。第一次只给一段提示词,什么都不准备,看 agent 能做到什么程度。第二次提前在仓库里放好 `AGENTS.md`、`init.sh`、`feature_list.json`,用结构化的方式告诉 agent 该干什么、怎么验证、什么时候算做完。然后对比两次结果。
-这个项目的核心不是写代码,是搞清楚"提前花 15 分钟准备规则"和"上来就让 agent 干"之间到底差多少。
+课程场景使用一小段准备或重新探索时间作为示例,不依赖固定测量值。
+
+## 使用仓库里的项目
+
+仓库路径:`projects/project-01/`
+
+| 目录 | 里面有什么 | 怎么用 |
+|------|------|------|
+| `starter/` | 弱 harness 版本,只有 `task-prompt.md`,没有 `AGENTS.md` 或 `feature_list.json`。 | 把 prompt 给 coding agent,测量它在没有额外结构时完成了什么。 |
+| `solution/` | 同一个产品切片,加上 `AGENTS.md`、`CLAUDE.md`、`init.sh`、`feature_list.json`、`claude-progress.md`。 | 对照规则和验证证据如何把同一任务具体化。 |
+
+四个具体功能是窗口启动、文档列表、问答面板、本地数据目录。预期证据见 `solution/feature_list.json`。
## 用什么工具
diff --git a/docs/zh/projects/project-02-agent-readable-workspace/index.md b/docs/zh/projects/project-02-agent-readable-workspace/index.md
index 9ed60e5..e6e8343 100644
--- a/docs/zh/projects/project-02-agent-readable-workspace/index.md
+++ b/docs/zh/projects/project-02-agent-readable-workspace/index.md
@@ -11,6 +11,17 @@ P01 证明了准备规则有用。但 P01 的任务一次会话就干完了。
你需要跑两次。第一次不给 agent 任何帮助,看它在第二个会话里要花多久才能"接上"。第二次提前放好 `ARCHITECTURE.md`、`PRODUCT.md`、`session-handoff.md`,让它快速对齐上下文。
+## 使用仓库里的项目
+
+仓库路径:`projects/project-02/`
+
+| 目录 | 里面有什么 | 比较什么 |
+|------|------|------|
+| `starter/` | Project 01 代码,加上未完成的文档导入、详情视图、持久化。文档存在但较薄,没有 `session-handoff.md`。 | 第二个 agent 会话要重新发现多少上下文。 |
+| `solution/` | 完成同一产品切片,并在 `projects/project-02/solution/` 下补齐核心文档(以及 `feature_list.json`、`session-handoff.md`)。 | 新会话能否只靠仓库状态继续工作。 |
+
+产品功能是文档导入、完整详情/内容加载、跨重启持久化;harness 功能是可交接的 agent-readable workspace。
+
## 用什么工具
- Claude Code 或 Codex(和 P01 保持一致)
diff --git a/docs/zh/projects/project-03-multi-session-continuity/index.md b/docs/zh/projects/project-03-multi-session-continuity/index.md
index 720a509..524f25a 100644
--- a/docs/zh/projects/project-03-multi-session-continuity/index.md
+++ b/docs/zh/projects/project-03-multi-session-continuity/index.md
@@ -9,7 +9,18 @@ P02 解决了"接手"的问题,但 agent 接手之后能不能把活干完、
你要实现的知识库功能是:文档分块、元数据提取、索引进度显示、带引用的问答流程。这些功能比前两个项目复杂,agent 更容易跑偏——要么多做了不该做的,要么说做完了但其实没通过验证。
-你需要一个 `feature_list.json`,每个功能有明确的状态(failing / passing)。规则很简单:一次只做一个功能,没有可运行的验证证据就不能标成 passing。跑两次,一次不给这些约束,一次严格执行,看结果差多少。
+你需要一个 `feature_list.json`,每个功能有明确的状态。规则很简单:一次只做一个功能,没有可运行的验证证据就不能标成 passing。仓库里的 starter 已经有早期版功能清单,但缺少完整的重启和交接产物;solution 则补齐这些产物。比较两者,看结果差多少。
+
+## 使用仓库里的项目
+
+仓库路径:`projects/project-03/`
+
+| 目录 | 里面有什么 | 比较什么 |
+|------|------|------|
+| `starter/` | Project 02 代码,索引和带引用问答未完成。有 starter 版 `feature_list.json`,但缺少最终重启/交接产物。 | agent 是否跨多个功能漂移,重启后是否丢状态。 |
+| `solution/` | 完成文档分块、元数据、索引状态、带引用问答,并加入 `init.sh`、`session-handoff.md`、`claude-progress.md`、`clean-state-checklist.md`。 | 每个功能是否有验证证据后才标为 passing。 |
+
+本项目对应的产品功能不是泛泛的"多会话",而是文档分块、元数据提取、索引状态 UI、带引用问答。
## 用什么工具
@@ -31,9 +42,9 @@ P02 解决了"接手"的问题,但 agent 接手之后能不能把活干完、
切到 `p03-baseline` 分支。
1. 启动 agent,给一段模糊的任务提示词。
-2. 不提供 `feature_list.json`,没有状态追踪。
-3. 不限制 agent 一次做几个功能。
-4. 没有明确的验证标准——agent 自己说"完成了"就算。
+2. 使用 starter 里已有的早期版 `feature_list.json`,但不提供额外的重启/交接产物。
+3. 不额外强化"一次一个功能"和交接更新要求。
+4. 验证标准较弱——重点观察 agent 是否自己补足证据。
5. 运行结束后,手动检查每个功能是否真的能用。
6. 记录哪些功能 agent 声称完成但实际没通过验证。
@@ -41,9 +52,9 @@ P02 解决了"接手"的问题,但 agent 接手之后能不能把活干完、
切到 `p03-improved` 分支。在启动 agent 之前:
-- 在仓库根目录放好 `feature_list.json`,四个功能全部标为 `failing`。
-- 在 `AGENTS.md` 里写明规则:一次只做一个功能;状态只能从 `failing` 切到 `passing`,且必须有验证证据。
-- 准备好 `init.sh`。
+- 对照 solution 中的 `AGENTS.md`、`feature_list.json`、`init.sh`、`session-handoff.md`、`claude-progress.md`。
+- 明确规则:一次只做一个功能;状态只能在有验证证据后切到 `pass`。
+- 每次会话结束前更新交接和进度产物。
然后启动 agent:
diff --git a/docs/zh/projects/project-04-incremental-indexing/index.md b/docs/zh/projects/project-04-incremental-indexing/index.md
index 9d7d44c..669df5b 100644
--- a/docs/zh/projects/project-04-incremental-indexing/index.md
+++ b/docs/zh/projects/project-04-incremental-indexing/index.md
@@ -9,7 +9,18 @@
你要做两件事。第一,给知识库应用加上运行时可观测性:启动日志、导入和索引的日志、问答失败时的用户可见错误状态。第二,在仓库里编码架构约束,让 agent 不可能静默地跨层违规(main / preload / renderer / services 之间的边界)。
-然后你会在代码里埋一个运行时 bug,让 agent 去修。跑两次:一次不给日志和约束,看 agent 怎么修;一次给好日志和架构规则,看差别。
+仓库里的 starter 已经埋好了运行时 bug,但诊断信号很弱,也没有架构检查脚本。solution 加上结构化日志、架构规则和修复后的分块逻辑。比较两者,看运行时反馈对修复质量的影响。
+
+## 使用仓库里的项目
+
+仓库路径:`projects/project-04/`
+
+| 目录 | 里面有什么 | 比较什么 |
+|------|------|------|
+| `starter/` | Project 03 代码,诊断信号较弱。植入的 indexing 缺陷会让大文件分块异常,并且没有架构检查脚本。 | 没有运行时信号时,agent 多久能找到根因。 |
+| `solution/` | 结构化 logger、架构边界文档和脚本、修复后的分块逻辑、`clean-state-checklist.md`。 | 日志和边界检查是否让修复更快、更少破坏。 |
+
+重点检查 `projects/project-04/solution/src/services/logger.ts`、`projects/project-04/solution/scripts/check-architecture.sh`、`projects/project-04/solution/docs/ARCHITECTURE.md`、`projects/project-04/solution/src/services/indexing-service.ts`。
## 用什么工具
@@ -33,7 +44,7 @@
切到 `p04-baseline` 分支。
1. 启动 agent,告诉它"问答功能返回空结果,请修复"。
-2. 仓库里没有运行时日志,没有架构约束文件。
+2. 仓库里没有结构化 logger,也没有架构检查脚本。
3. 记录 agent 花了多久找到根因、怎么确认修复的、修复过程中是否引入了新的层边界违规。
4. 修复后重启应用,确认是否能干净启动。
@@ -41,8 +52,8 @@
切到 `p04-improved` 分支。在启动 agent 之前,先在仓库里准备好:
-- **运行时日志**:启动时打印初始化步骤,导入时打印文件数量和 chunk 结果,索引时打印进度,问答失败时打印错误原因。
-- **架构约束**:在 `AGENTS.md` 里明确写 Electron 四层边界(main / preload / renderer / services),说明哪些调用路径是允许的。用 ESLint 规则或 guard 脚本检查违规。
+- **运行时日志**:对照 solution 的 `src/services/logger.ts`,启动、导入、索引、问答失败路径都有结构化日志。
+- **架构约束**:对照 solution 的 `AGENTS.md`、`projects/project-04/solution/docs/ARCHITECTURE.md` 和 `projects/project-04/solution/scripts/check-architecture.sh`,明确 Electron 四层边界(main / preload / renderer / services)。
- **干净状态要求**:最终交付前必须能干净重启。
然后启动 agent:
diff --git a/docs/zh/projects/project-05-grounded-qa-verification/index.md b/docs/zh/projects/project-05-grounded-qa-verification/index.md
index 5285c08..50fa291 100644
--- a/docs/zh/projects/project-05-grounded-qa-verification/index.md
+++ b/docs/zh/projects/project-05-grounded-qa-verification/index.md
@@ -11,12 +11,25 @@
选一个实质性的功能升级(比如多轮对话历史、引用面板重设计、文档集合与筛选),三次都做同一个升级,唯一变量是 harness 的角色分工。
+## 使用仓库里的项目
+
+仓库路径:`projects/project-05/`
+
+| 目录 | 里面有什么 | 比较什么 |
+|------|------|------|
+| `starter/` | ConversationHistory 升级前的 Project 04 应用。 | 如果要自己重跑三种变体,从这里开始。 |
+| `solution/single-role/` | 一个 agent 规划、实现、自评。 | `evaluator-rubric.md` 评分 1.6/5 和缺陷列表。 |
+| `solution/gen-eval/` | 生成者 + 评估者,有修订证据。 | `evaluator-rubric.md` 评分 3.3/5 和修订记录。 |
+| `solution/plan-gen-eval/` | 规划者 + 生成者 + 评估者。 | `sprint-contract.md`、`evaluator-rubric.md` 评分 4.9/5。 |
+
+已提交的固定功能是多轮问答历史。重跑时保持功能不变,唯一变量是角色分工。
+
## 用什么工具
- Claude Code 或 Codex(用于生成和规划角色)
- 同一个或另一个 agent 实例(用于评估角色)
- 评估量表(参考 `docs/zh/resources/templates/evaluator-rubric.md`)
-- Sprint contract 模板(参考 `docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md`)
+- Sprint contract 模板(参考 `docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md`)
## 具体步骤
diff --git a/docs/zh/projects/project-06-runtime-observability-and-debugging/index.md b/docs/zh/projects/project-06-runtime-observability-and-debugging/index.md
index 2e777db..41261ba 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
@@ -9,6 +9,17 @@
你要用一套固定的多功能任务集,覆盖知识库应用的完整产品切片:导入文档、构建索引、带引用的问答、运行时可观测性、可读可重启的仓库状态。先跑一次弱 harness 基线,再跑一次你组装的最强 harness,然后做一轮清理和重跑。最后还要做一次 harness 精简实验——删掉一个组件看看结果会不会变差,判断哪些组件是真正有用的、哪些是多余的开销。
+## 使用仓库里的项目
+
+仓库路径:`projects/project-06/`
+
+| 目录 | 里面有什么 | 比较什么 |
+|------|------|------|
+| `starter/` | 大部分产品代码已经完成,但 harness 表面较弱:只有基础 `AGENTS.md`,没有 `feature_list.json`、`session-handoff.md`、clean-state checklist。 | 手动记录弱 harness 基线。starter 故意不包含 benchmark 脚本。 |
+| `solution/` | 完整 harness:`AGENTS.md`、`CLAUDE.md`、`feature_list.json`、`init.sh`、`session-handoff.md`、`clean-state-checklist.md`、质量/评估文档、benchmark 和 cleanup 脚本。 | 运行 `projects/project-06/solution/scripts/benchmark.sh`、`projects/project-06/solution/scripts/cleanup-scanner.sh`,对比质量文档证据。 |
+
+和前几个项目不同,capstone starter 不是缺很多产品功能;主要缺口是应用周围的操作 harness。
+
## 用什么工具
- Claude Code 或 Codex
diff --git a/projects/project-01/README-CN.md b/projects/project-01/README-CN.md
index 8c06b3a..88baea1 100644
--- a/projects/project-01/README-CN.md
+++ b/projects/project-01/README-CN.md
@@ -17,11 +17,13 @@ cd starter
npm install
# 把 task-prompt.md 的内容作为 prompt 给 Claude Code / Codex
# 让代理尝试完成:窗口启动、文档列表、问答面板、数据目录
+# 这一轮不要把 solution 文件给代理
# 2. 用 solution(显式 harness)跑一次
cd ../solution
npm install
-# 让代理读取 AGENTS.md,按规则执行同样的任务
+# 让代理先读取 AGENTS.md、init.sh、feature_list.json、claude-progress.md
+# 产品代码本身应该已经满足同样四个功能
# 3. 对比两次结果
# - 任务是否完成?
@@ -29,6 +31,20 @@ npm install
# - 代理是否提前声称"完成"?
```
+## 具体任务对应关系
+
+`starter/task-prompt.md` 故意只有一句话:"Build an Electron app that can show
+documents and answer questions." 请用 solution 中的 harness 文件把这句话具体化。
+
+| 功能 | starter 中检查哪里 | solution 中对照哪里 |
+|------|------|------|
+| 窗口启动 | `src/main/main.ts`, `src/preload/preload.ts` | `feature_list.json` 的 `window-launch` |
+| 文档列表区域 | `src/renderer/components/DocumentList.tsx` | `feature_list.json` 的 `document-list` |
+| 问答面板 | `src/renderer/components/QuestionPanel.tsx` | `feature_list.json` 的 `question-panel` |
+| 本地数据目录 | `src/services/persistence-service.ts` | `feature_list.json` 的 `data-directory` |
+
+这个项目不是普通的"把 starter 改成 solution"练习,而是比较 prompt-only 和显式规则/验证产物之间的差异。
+
## 本项目涉及的功能
- Electron 窗口成功启动
diff --git a/projects/project-01/README.md b/projects/project-01/README.md
index 192da5a..f962761 100644
--- a/projects/project-01/README.md
+++ b/projects/project-01/README.md
@@ -17,11 +17,13 @@ cd starter
npm install
# Give the contents of task-prompt.md as the prompt to Claude Code / Codex
# Ask the agent to complete: window startup, document list, QA panel, data directory
+# Do not give the agent solution files during this run.
# 2. Run the same task with solution (explicit harness)
cd ../solution
npm install
-# Ask the agent to read AGENTS.md and follow the rules for the same task
+# Ask the agent to read AGENTS.md, init.sh, feature_list.json, and claude-progress.md
+# before touching code. The product code should already satisfy the same four features.
# 3. Compare the two results
# - Was the task completed?
@@ -29,6 +31,24 @@ npm install
# - Did the agent claim "done" too early?
```
+## Exact Task Contract
+
+The starter prompt is intentionally vague (`starter/task-prompt.md` contains only
+"Build an Electron app that can show documents and answer questions."). Use the
+solution harness to make that vague request concrete:
+
+| Feature | Starter evidence to inspect | Solution evidence to compare |
+|------|------|------|
+| Window launch | `src/main/main.ts`, `src/preload/preload.ts` | `feature_list.json` item `window-launch` |
+| Document list panel | `src/renderer/components/DocumentList.tsx` | `feature_list.json` item `document-list` |
+| Question panel | `src/renderer/components/QuestionPanel.tsx` | `feature_list.json` item `question-panel` |
+| Data directory | `src/services/persistence-service.ts` | `feature_list.json` item `data-directory` |
+
+This project is an experiment, not a normal "fill in the starter until it equals
+solution" assignment. The learning outcome is the measured difference between a
+prompt-only run and a run that starts from explicit repo rules and verification
+artifacts.
+
## Features Covered
- Electron window starts successfully
diff --git a/projects/project-02/README-CN.md b/projects/project-02/README-CN.md
index 13a6362..e98b9da 100644
--- a/projects/project-02/README-CN.md
+++ b/projects/project-02/README-CN.md
@@ -23,6 +23,20 @@ npm install
# 用完整 harness 重跑,对比会话恢复速度
```
+## 具体任务对应关系
+
+从 `starter/` 开始。starter 已经有 Project 01 的应用壳和一个较弱的
+harness。本项目要补的是 Project 02 的产品切片,以及让第二个会话能快速接手的仓库文档。
+
+| 功能 / 产物 | starter 状态 | solution 证据 |
+|------|------|------|
+| 文档导入 | renderer、preload、IPC、`DocumentService` 的导入链路不完整 | `ImportPanel.tsx`, `ipc-handlers.ts`, `document-service.ts` |
+| 文档详情 | 详情面板还不能通过 IPC 加载并显示完整内容 | `DocumentDetail.tsx`, `IPC_CHANNELS.GET_DOCUMENT_CONTENT` |
+| 基本持久化 | 导入文档不能完整跨重启恢复 | `persistence-service.ts`, `documents-meta.json` 处理 |
+| agent 可读状态 | starter 没有最终交接文件 | `session-handoff.md`, 扩展后的 `docs/ARCHITECTURE.md` 和 `docs/PRODUCT.md` |
+
+请按两次会话来跑:Session A 在三个功能全部完成前停止,Session B 只能依靠仓库状态继续。主要比较指标是有无交接文件时的恢复速度。
+
## 本项目涉及的功能
- 文档导入流程(文件选择器 + IPC 传输)
diff --git a/projects/project-02/README.md b/projects/project-02/README.md
index f162dba..e0e5e6c 100644
--- a/projects/project-02/README.md
+++ b/projects/project-02/README.md
@@ -23,6 +23,24 @@ npm install
# Rerun with the complete harness and compare session recovery speed
```
+## Exact Task Contract
+
+Start from `starter/`. The starter already contains the Project 01 shell and a
+minimal harness. The work is to add the Project 02 product slice and the
+workspace documentation that makes a second session recover quickly.
+
+| Feature / artifact | Starter state | Solution evidence |
+|------|------|------|
+| Document import | Import flow is incomplete across renderer, preload, IPC, and `DocumentService` | `src/renderer/components/ImportPanel.tsx`, `src/main/ipc-handlers.ts`, `src/services/document-service.ts` |
+| Document detail | Detail panel does not load and render full file content through IPC | `src/renderer/components/DocumentDetail.tsx`, `IPC_CHANNELS.GET_DOCUMENT_CONTENT` |
+| Basic persistence | Imported documents are not fully restored after restart | `src/services/persistence-service.ts`, `documents-meta.json` handling |
+| Agent-readable state | No final handoff file in starter | `session-handoff.md`, expanded `docs/ARCHITECTURE.md`, expanded `docs/PRODUCT.md` |
+
+Run this as a two-session exercise. Stop Session A before all three product
+features are complete, then start Session B from only the repository state. The
+main comparison is how much faster Session B can resume when `session-handoff.md`
+and the docs exist.
+
## Features Covered
- Document import flow (file picker plus IPC transfer)
diff --git a/projects/project-03/README-CN.md b/projects/project-03/README-CN.md
index a183594..1c55c25 100644
--- a/projects/project-03/README-CN.md
+++ b/projects/project-03/README-CN.md
@@ -1,26 +1,41 @@
-# Project 03: Scope Control and Grounded Verification
+# Project 03: Multi-Session Continuity with Scope Control
-评估显式范围控制和验证门控是否能提高交付准确性。
+评估进度记录、会话交接、显式范围控制和验证门控是否能提高跨重启交付准确性。
## 目录说明
| 目录 | 含义 |
|------|------|
-| `starter/` | **起点**——基于 P2 solution,新增文档分块、元数据提取、索引状态、基础问答功能待实现。没有一次一个功能的策略约束。 |
-| `solution/` | **参考实现**——所有功能已实现,AGENTS.md 包含"一次一个功能"策略,feature_list.json 展示 fail→pass 的转换过程和验证证据。 |
+| `starter/` | **起点**——基于 P2 solution,文档分块、元数据提取、索引状态、带引用问答待实现。它有 starter 版 `feature_list.json`,但缺少完整的重启/交接 harness(`init.sh`、`session-handoff.md`、`claude-progress.md`、clean-state checklist)。 |
+| `solution/` | **参考实现**——所有功能已实现,AGENTS.md 包含"一次一个功能"策略,并补齐重启/连续性产物。 |
## 使用方法
```sh
cd starter
npm install
-# 观察 agent 是否会同时实现多个功能(范围漂移)
+# 至少跑两个 agent 会话。中途停止一次,再只靠仓库状态恢复。
+# 观察 agent 是否保持范围并更新 feature_list.json。
cd ../solution
npm install
-# 用 scope control 重跑,对比功能交付准确性
+# 检查完成后的连续性产物和功能证据
```
+## 具体任务对应关系
+
+Project 03 starter 不是空应用,而是 Project 02 加上未完成的索引和带引用问答。按一次一个功能完成:
+
+| 功能 / 产物 | starter 状态 | solution 证据 |
+|------|------|------|
+| 文档分块 | `IndexingService` 需要段落感知的 chunk 创建 | `indexing-service.ts`, `feature_list.json` 的 `document-chunking` |
+| 元数据提取 | 索引所需的文档元数据不完整 | `document-service.ts`, `DocumentDetail.tsx`, `metadata-extraction` |
+| 索引状态 UI | 状态栏需要 indexed count / total chunks / 状态颜色 | `StatusBar.tsx`, `App.tsx`, `indexing-status-ui` |
+| 带引用问答 | QA 必须返回 chunk 引用、摘录和置信度 | `qa-service.ts`, `QuestionPanel.tsx`, `grounded-qa` |
+| 连续性 harness | starter 缺少最终重启/交接产物 | `init.sh`, `session-handoff.md`, `claude-progress.md`, `clean-state-checklist.md` |
+
+不要把这个项目理解成泛泛的"多会话"练习;产品切片是索引 + 带引用问答,harness 切片是可重启的进度追踪。
+
## 本项目涉及的功能
- 文档分块(段落感知,~500 字符)
diff --git a/projects/project-03/README.md b/projects/project-03/README.md
index 1714dea..547d8bd 100644
--- a/projects/project-03/README.md
+++ b/projects/project-03/README.md
@@ -1,26 +1,45 @@
-# Project 03: Scope Control and Grounded Verification
+# Project 03: Multi-Session Continuity with Scope Control
-Evaluate whether explicit scope control and verification gates improve delivery accuracy.
+Evaluate whether progress logs, session handoff, explicit scope control, and
+verification gates improve delivery accuracy across restarts.
## Directory Guide
| Directory | Meaning |
|------|------|
-| `starter/` | **Starting point**: based on the P2 solution, with document chunking, metadata extraction, index status, and basic QA still to implement. There is no "one feature at a time" strategy constraint. |
-| `solution/` | **Reference implementation**: all features are implemented. AGENTS.md includes a "one feature at a time" strategy, and feature_list.json shows the fail-to-pass transition and verification evidence. |
+| `starter/` | **Starting point**: based on the P2 solution, with document chunking, metadata extraction, index status, and grounded QA still to implement. It has a starter `feature_list.json`, but lacks the full restart harness (`init.sh`, `session-handoff.md`, `claude-progress.md`, clean-state checklist). |
+| `solution/` | **Reference implementation**: all features are implemented. AGENTS.md includes the "one feature at a time" strategy, and the repo adds restart/continuity artifacts (`init.sh`, `session-handoff.md`, `claude-progress.md`, `clean-state-checklist.md`). |
## How to Use
```sh
cd starter
npm install
-# Observe whether the agent implements multiple features at once (scope drift)
+# Run at least two agent sessions. Stop once mid-task, then resume from repo state.
+# Observe whether the agent preserves scope and updates feature_list.json.
cd ../solution
npm install
-# Rerun with scope control and compare feature delivery accuracy
+# Inspect the completed continuity artifacts and feature evidence.
```
+## Exact Task Contract
+
+The Project 03 starter is not an empty app. It is Project 02 plus unfinished
+indexing and grounded QA work. Complete these items one at a time:
+
+| Feature / artifact | Starter state | Solution evidence |
+|------|------|------|
+| Document chunking | `IndexingService` needs paragraph-aware chunk creation | `src/services/indexing-service.ts`, `feature_list.json` item `document-chunking` |
+| Metadata extraction | Document metadata is incomplete for indexing work | `src/services/document-service.ts`, `DocumentDetail.tsx`, item `metadata-extraction` |
+| Indexing status UI | Status bar needs indexed count / total chunks / status colors | `src/renderer/components/StatusBar.tsx`, `App.tsx`, item `indexing-status-ui` |
+| Grounded Q&A | QA must cite retrieved chunks with excerpts and confidence | `src/services/qa-service.ts`, `QuestionPanel.tsx`, item `grounded-qa` |
+| Continuity harness | Starter lacks final restart/handoff artifacts | `init.sh`, `session-handoff.md`, `claude-progress.md`, `clean-state-checklist.md` |
+
+Do not treat this as "add any multi-session feature." The intended product
+slice is indexing plus citation-based QA, and the intended harness slice is
+restartable progress tracking.
+
## Features Covered
- Document chunking (paragraph-aware, about 500 characters)
diff --git a/projects/project-03/solution/AGENTS.md b/projects/project-03/solution/AGENTS.md
index 64d1391..4c60133 100644
--- a/projects/project-03/solution/AGENTS.md
+++ b/projects/project-03/solution/AGENTS.md
@@ -1,4 +1,4 @@
-# AGENTS.md -- Project 03: Scope Control and Grounded Verification
+# AGENTS.md -- Project 03: Multi-Session Continuity with Scope Control
## Startup Rules
diff --git a/projects/project-03/solution/feature_list.json b/projects/project-03/solution/feature_list.json
index 5a3b016..a7317f8 100644
--- a/projects/project-03/solution/feature_list.json
+++ b/projects/project-03/solution/feature_list.json
@@ -1,6 +1,6 @@
{
"project": "project-03",
- "description": "Scope control and grounded verification with indexing, metadata, and grounded QA",
+ "description": "Multi-session continuity with scope control, indexing, metadata, and grounded QA",
"features": [
{
"id": "window-launch",
diff --git a/projects/project-03/starter/AGENTS.md b/projects/project-03/starter/AGENTS.md
index b3b7ac7..cd14750 100644
--- a/projects/project-03/starter/AGENTS.md
+++ b/projects/project-03/starter/AGENTS.md
@@ -1,4 +1,4 @@
-# AGENTS.md -- Project 03: Scope Control and Grounded Verification
+# AGENTS.md -- Project 03: Multi-Session Continuity with Scope Control
## Quick Start
@@ -41,4 +41,7 @@ A feature is "done" when:
## Session Handoff
-When resuming work, read `session-handoff.md` for context from the previous session.
+When resuming work, first check whether `session-handoff.md` exists. The starter
+does not include it by default; if it is missing, reconstruct state from
+`feature_list.json`, `docs/ARCHITECTURE.md`, `docs/PRODUCT.md`, and the current
+git diff.
diff --git a/projects/project-03/starter/feature_list.json b/projects/project-03/starter/feature_list.json
index 33c5fa7..505cb79 100644
--- a/projects/project-03/starter/feature_list.json
+++ b/projects/project-03/starter/feature_list.json
@@ -1,6 +1,6 @@
{
"project": "project-03",
- "description": "Scope control and grounded verification with indexing, metadata, and grounded QA",
+ "description": "Multi-session continuity with scope control, indexing, metadata, and grounded QA",
"features": [
{
"id": "window-launch",
diff --git a/projects/project-04/README-CN.md b/projects/project-04/README-CN.md
index fe77ce1..98cadc8 100644
--- a/projects/project-04/README-CN.md
+++ b/projects/project-04/README-CN.md
@@ -1,4 +1,4 @@
-# Project 04: Runtime Observability and Structural Control
+# Project 04: Runtime Feedback and Structural Control
引入运行时可观测性和结构化边界检查,同时调试一个植入的运行时缺陷。
@@ -6,7 +6,7 @@
| 目录 | 含义 |
|------|------|
-| `starter/` | **起点**——基于 P3 solution,新增日志、结构化边界功能待实现。`IndexingService` 中植入了一个隐蔽 bug:超过 1000 字符的文件会产生空分块。没有架构检查脚本。 |
+| `starter/` | **起点**——基于 P3 solution,新增日志、结构化边界功能待实现。`IndexingService` 中植入了一个隐蔽 bug:超过 1000 字符的文件可能产生无效/空分块。没有架构检查脚本,也没有最终 clean-state checklist。 |
| `solution/` | **参考实现**——结构化日志模块、架构边界检查脚本、植入 bug 已修复。 |
## 使用方法
@@ -22,6 +22,20 @@ npm install
# 对比:结构化日志如何加速问题诊断
```
+## 具体任务对应关系
+
+Project 04 是调试和护栏练习。starter 已有 Project 03 的产品切片,但运行时信号不足,并且植入了分块缺陷。应该先让 agent 看见足够诊断证据,再修 bug。
+
+| 功能 / 产物 | starter 状态 | solution 证据 |
+|------|------|------|
+| 结构化日志 | 没有共享 logger service | `src/services/logger.ts`,以及 `main.ts`、`ipc-handlers.ts`、services 中的日志调用 |
+| 导入/索引诊断 | 运行输出难以定位失败 | 导入、索引开始/完成、QA 失败路径的日志 |
+| 架构边界 | 没有脚本检查 renderer/main/service 越界 | `scripts/check-architecture.sh`, `docs/ARCHITECTURE.md`, AGENTS 边界规则 |
+| 植入分块 bug | 大文件可能产生无效/空 chunk | 修复后的 `src/services/indexing-service.ts` |
+| 干净交接 | starter 没有最终清单 | `clean-state-checklist.md` |
+
+修复前后都用长文档复现一次。合格解法要有诊断证据,而不只是声称通过。
+
## 本项目涉及的功能
- 启动日志
diff --git a/projects/project-04/README.md b/projects/project-04/README.md
index 0c0ed34..5bdd4d4 100644
--- a/projects/project-04/README.md
+++ b/projects/project-04/README.md
@@ -1,4 +1,4 @@
-# Project 04: Runtime Observability and Structural Control
+# Project 04: Runtime Feedback and Structural Control
Introduce runtime observability and structural boundary checks while debugging a seeded runtime defect.
@@ -6,7 +6,7 @@ Introduce runtime observability and structural boundary checks while debugging a
| Directory | Meaning |
|------|------|
-| `starter/` | **Starting point**: based on the P3 solution, with logging and structural boundary features still to implement. `IndexingService` contains a hidden seeded bug: files longer than 1000 characters produce empty chunks. There is no architecture-check script. |
+| `starter/` | **Starting point**: based on the P3 solution, with logging and structural boundary features still to implement. `IndexingService` contains a hidden seeded bug: files longer than 1000 characters can produce empty chunks. There is no architecture-check script and no final clean-state checklist. |
| `solution/` | **Reference implementation**: structured logging module, architecture boundary-check script, and the seeded bug fixed. |
## How to Use
@@ -22,6 +22,24 @@ npm install
# Compare how structured logs speed up diagnosis
```
+## Exact Task Contract
+
+Project 04 is a debugging and guardrail exercise. The starter already contains
+the Project 03 product slice, but the runtime is harder to inspect and the seeded
+chunking defect should be fixed only after the agent can see enough evidence.
+
+| Feature / artifact | Starter state | Solution evidence |
+|------|------|------|
+| Structured logging | No shared logger service | `src/services/logger.ts`, logging calls in `main.ts`, `ipc-handlers.ts`, and services |
+| Import / indexing diagnostics | Failures are hard to trace from runtime output | Log entries around import, indexing start/completion, and QA failure paths |
+| Architecture boundaries | No script checks renderer/main/service boundary drift | `scripts/check-architecture.sh`, `docs/ARCHITECTURE.md`, AGENTS boundary rules |
+| Seeded chunking bug | Large files can produce invalid/empty chunk output | Fixed `src/services/indexing-service.ts` paragraph/chunk logic |
+| Clean handoff | Starter has no final checklist | `clean-state-checklist.md` |
+
+Use a long sample document to reproduce the bug before and after the fix. A
+successful solution should show both code changes and diagnostic evidence, not
+only a passing claim.
+
## Features Covered
- Startup logs
diff --git a/projects/project-04/solution/AGENTS.md b/projects/project-04/solution/AGENTS.md
index f59ac26..c691c5f 100644
--- a/projects/project-04/solution/AGENTS.md
+++ b/projects/project-04/solution/AGENTS.md
@@ -9,11 +9,11 @@ next session can continue without guessing.
Before writing code:
1. Confirm the working directory with `pwd`.
-2. Read `claude-progress.md` for the latest verified state and next step.
-3. Read `feature_list.json` and choose the highest-priority unfinished feature.
-4. Review recent commits with `git log --oneline -5`.
-5. Run `./init.sh`.
-6. Run the required smoke or end-to-end verification before starting new work.
+2. Read `docs/ARCHITECTURE.md` for the Electron layer boundaries.
+3. Review recent commits with `git log --oneline -5`.
+4. Run `npm install` if dependencies are missing.
+5. Run `npm run check`.
+6. Run `bash scripts/check-architecture.sh`.
If baseline verification is already failing, fix that first. Do not stack new
feature work on top of a broken starting state.
@@ -51,19 +51,26 @@ Run `bash scripts/check-architecture.sh` before committing.
## Required Artifacts
-- `feature_list.json`: source of truth for feature state
-- `claude-progress.md`: session log and current verified status
-- `init.sh`: standard startup and verification path
-- `session-handoff.md`: optional compact handoff for larger sessions
+Project 04 intentionally keeps a smaller harness than the capstone projects.
+The required artifacts in this solution are:
+
+- `AGENTS.md`: operating rules for this project
+- `docs/ARCHITECTURE.md`: layer boundaries and data flow
+- `scripts/check-architecture.sh`: boundary guard
- `clean-state-checklist.md`: pre-commit repository health check
+Do not assume `feature_list.json`, `claude-progress.md`, `init.sh`, or
+`session-handoff.md` exist in this project. Those artifacts are introduced in
+other project stages.
+
## Definition Of Done
A feature is done only when all of the following are true:
- the target behavior is implemented
- the required verification actually ran
-- evidence is recorded in `feature_list.json` or `claude-progress.md`
+- evidence is recorded in the final summary or a project document touched by
+ the task
- the repository remains restartable from the standard startup path
- `scripts/check-architecture.sh` passes with no violations
@@ -71,10 +78,8 @@ A feature is done only when all of the following are true:
Before ending a session:
-1. Update `claude-progress.md`.
-2. Update `feature_list.json`.
-3. Record any unresolved risk or blocker.
-4. Run `bash scripts/check-architecture.sh`.
-5. Commit with a descriptive message once the work is in a safe state.
-6. Leave the repo clean enough for the next session to run `./init.sh`
- immediately.
+1. Record any unresolved risk or blocker in your final summary.
+2. Run `npm run check`.
+3. Run `bash scripts/check-architecture.sh`.
+4. Commit with a descriptive message once the work is in a safe state.
+5. Leave the repo clean enough for the next session to run the startup workflow.
diff --git a/projects/project-04/solution/clean-state-checklist.md b/projects/project-04/solution/clean-state-checklist.md
index 8ce2e06..6b060a5 100644
--- a/projects/project-04/solution/clean-state-checklist.md
+++ b/projects/project-04/solution/clean-state-checklist.md
@@ -32,5 +32,5 @@ Run this checklist before committing and at the end of each session.
- [ ] No unintended files in git status
- [ ] No sensitive data (.env, credentials) staged
-- [ ] `claude-progress.md` updated with current state
-- [ ] `feature_list.json` reflects actual feature status
+- [ ] Final summary records current state, verification run, and any unresolved risk
+- [ ] `AGENTS.md`, `docs/ARCHITECTURE.md`, and this checklist still match the files that actually exist in Project 04
diff --git a/projects/project-05/README-CN.md b/projects/project-05/README-CN.md
index 891bf70..eab5ea2 100644
--- a/projects/project-05/README-CN.md
+++ b/projects/project-05/README-CN.md
@@ -14,7 +14,12 @@
## 使用方法
```sh
-# 三个变体各自独立运行
+# 如果要自己重跑练习,从 starter 开始
+cd starter
+npm install
+# 用下面三种角色配置实现同一个 ConversationHistory 升级
+
+# 检查三个参考变体
cd solution/single-role && npm install # 单角色模式
cd solution/gen-eval && npm install # 生成+评估模式
cd solution/plan-gen-eval && npm install # 完整三角色模式
@@ -25,6 +30,19 @@ cd solution/plan-gen-eval && npm install # 完整三角色模式
# - 需要返工的程度
```
+## 具体任务对应关系
+
+已提交的 solution 固定为同一个产品升级:通过 `ConversationHistory` 实现多轮问答历史。三个 solution 目录不是顺序阶段,而是同一功能在不同角色 harness 下的三个独立运行结果。
+
+| 变体 | 展示什么 | 检查证据 |
+|------|------|------|
+| `starter/` | ConversationHistory 升级前的 P4 应用 | `ConversationHistory.tsx`, `App.tsx` |
+| `solution/single-role/` | 一个 agent 规划、实现、自评 | `evaluator-rubric.md` 评分 1.6/5 和缺陷列表 |
+| `solution/gen-eval/` | 生成者 + 评估者,有修订证据 | `evaluator-rubric.md` 评分 3.3/5 和修订记录 |
+| `solution/plan-gen-eval/` | 规划者 + 生成者 + 评估者,有 sprint contract | `sprint-contract.md`, `evaluator-rubric.md` 评分 4.9/5 |
+
+重跑时请保持功能不变。三个变体唯一应该变化的是角色分工,否则比较无效。
+
## 本项目涉及的功能
- 多轮问答历史(对话式 UI)
diff --git a/projects/project-05/README.md b/projects/project-05/README.md
index 34b784a..5ffa100 100644
--- a/projects/project-05/README.md
+++ b/projects/project-05/README.md
@@ -14,7 +14,12 @@ Measure how role separation (single role, generator plus evaluator, planner plus
## How to Use
```sh
-# Run each of the three variants independently
+# Start from starter if you want to run the exercise yourself.
+cd starter
+npm install
+# Implement the same ConversationHistory upgrade three times using the role setup below.
+
+# Inspect the three reference variants independently
cd solution/single-role && npm install # single-role mode
cd solution/gen-eval && npm install # generator plus evaluator mode
cd solution/plan-gen-eval && npm install # full three-role mode
@@ -25,6 +30,24 @@ cd solution/plan-gen-eval && npm install # full three-role mode
# - Amount of rework required
```
+## Exact Task Contract
+
+The product upgrade for the checked-in solutions is fixed: implement multi-turn
+Q&A history through `ConversationHistory`. The three solution directories are
+not sequential stages; they are three independent runs of the same feature with
+different harness roles.
+
+| Variant | What it demonstrates | Evidence to inspect |
+|------|------|------|
+| `starter/` | P4-based app before the conversation-history upgrade | `src/renderer/components/ConversationHistory.tsx`, `App.tsx` |
+| `solution/single-role/` | One agent plans, implements, and self-reviews | `evaluator-rubric.md` score 1.6/5 and listed defects |
+| `solution/gen-eval/` | Separate generator and evaluator with revision evidence | `evaluator-rubric.md` score 3.3/5 and revision notes |
+| `solution/plan-gen-eval/` | Planner + generator + evaluator with a sprint contract | `sprint-contract.md`, `evaluator-rubric.md` score 4.9/5 |
+
+Keep the feature constant when you rerun the project. Changing the feature
+between variants invalidates the comparison because role separation is the only
+intended variable.
+
## Features Covered
- Multi-turn QA history (conversational UI)
diff --git a/projects/project-05/solution/gen-eval/AGENTS.md b/projects/project-05/solution/gen-eval/AGENTS.md
index f59ac26..dfdebe0 100644
--- a/projects/project-05/solution/gen-eval/AGENTS.md
+++ b/projects/project-05/solution/gen-eval/AGENTS.md
@@ -1,19 +1,20 @@
# AGENTS.md
-This repository is designed for long-running coding-agent work. The goal is not
-to maximize raw code output. The goal is to leave the repo in a state where the
-next session can continue without guessing.
+This Project 05 variant demonstrates the generator plus evaluator pattern for
+ConversationHistory. It includes the completed code and evaluator rubric, but it
+does not include the full capstone harness files.
## Startup Workflow
Before writing code:
1. Confirm the working directory with `pwd`.
-2. Read `claude-progress.md` for the latest verified state and next step.
-3. Read `feature_list.json` and choose the highest-priority unfinished feature.
-4. Review recent commits with `git log --oneline -5`.
-5. Run `./init.sh`.
-6. Run the required smoke or end-to-end verification before starting new work.
+2. Read `docs/ARCHITECTURE.md` for the Electron layer boundaries.
+3. Read `evaluator-rubric.md` to understand this variant's revision evidence.
+4. Read `clean-state-checklist.md`.
+5. Run `npm install` if dependencies are missing.
+6. Run `npm run check`.
+7. Run `bash scripts/check-architecture.sh`.
If baseline verification is already failing, fix that first. Do not stack new
feature work on top of a broken starting state.
@@ -51,11 +52,14 @@ Run `bash scripts/check-architecture.sh` before committing.
## Required Artifacts
-- `feature_list.json`: source of truth for feature state
-- `claude-progress.md`: session log and current verified status
-- `init.sh`: standard startup and verification path
-- `session-handoff.md`: optional compact handoff for larger sessions
+- `AGENTS.md`: operating rules for this project
+- `docs/ARCHITECTURE.md`: layer boundaries and data flow
+- `scripts/check-architecture.sh`: boundary guard
- `clean-state-checklist.md`: pre-commit repository health check
+- `evaluator-rubric.md`: quality and revision evidence for this variant
+
+Do not assume `feature_list.json`, `claude-progress.md`, `init.sh`, or
+`session-handoff.md` exist in this variant.
## Definition Of Done
@@ -63,7 +67,7 @@ A feature is done only when all of the following are true:
- the target behavior is implemented
- the required verification actually ran
-- evidence is recorded in `feature_list.json` or `claude-progress.md`
+- evidence is recorded in `evaluator-rubric.md` or the final summary
- the repository remains restartable from the standard startup path
- `scripts/check-architecture.sh` passes with no violations
@@ -71,10 +75,8 @@ A feature is done only when all of the following are true:
Before ending a session:
-1. Update `claude-progress.md`.
-2. Update `feature_list.json`.
-3. Record any unresolved risk or blocker.
-4. Run `bash scripts/check-architecture.sh`.
-5. Commit with a descriptive message once the work is in a safe state.
-6. Leave the repo clean enough for the next session to run `./init.sh`
- immediately.
+1. Record any unresolved risk or blocker in your final summary.
+2. Run `npm run check`.
+3. Run `bash scripts/check-architecture.sh`.
+4. Commit with a descriptive message once the work is in a safe state.
+5. Leave the repo clean enough for the next session to run the startup workflow.
diff --git a/projects/project-05/solution/gen-eval/clean-state-checklist.md b/projects/project-05/solution/gen-eval/clean-state-checklist.md
index 8ce2e06..96ac660 100644
--- a/projects/project-05/solution/gen-eval/clean-state-checklist.md
+++ b/projects/project-05/solution/gen-eval/clean-state-checklist.md
@@ -32,5 +32,5 @@ Run this checklist before committing and at the end of each session.
- [ ] No unintended files in git status
- [ ] No sensitive data (.env, credentials) staged
-- [ ] `claude-progress.md` updated with current state
-- [ ] `feature_list.json` reflects actual feature status
+- [ ] Final summary records current state, verification run, and any unresolved risk
+- [ ] `evaluator-rubric.md` still matches the implemented ConversationHistory variant
diff --git a/projects/project-05/solution/plan-gen-eval/AGENTS.md b/projects/project-05/solution/plan-gen-eval/AGENTS.md
index f59ac26..5f511ff 100644
--- a/projects/project-05/solution/plan-gen-eval/AGENTS.md
+++ b/projects/project-05/solution/plan-gen-eval/AGENTS.md
@@ -1,19 +1,22 @@
# AGENTS.md
-This repository is designed for long-running coding-agent work. The goal is not
-to maximize raw code output. The goal is to leave the repo in a state where the
-next session can continue without guessing.
+This Project 05 variant demonstrates the planner plus generator plus evaluator
+pattern for ConversationHistory. It includes the completed code, sprint
+contract, and evaluator rubric, but it does not include the full capstone
+harness files.
## Startup Workflow
Before writing code:
1. Confirm the working directory with `pwd`.
-2. Read `claude-progress.md` for the latest verified state and next step.
-3. Read `feature_list.json` and choose the highest-priority unfinished feature.
-4. Review recent commits with `git log --oneline -5`.
-5. Run `./init.sh`.
-6. Run the required smoke or end-to-end verification before starting new work.
+2. Read `sprint-contract.md` for scope and acceptance criteria.
+3. Read `evaluator-rubric.md` for final quality evidence.
+4. Read `docs/ARCHITECTURE.md` for the Electron layer boundaries.
+5. Read `clean-state-checklist.md`.
+6. Run `npm install` if dependencies are missing.
+7. Run `npm run check`.
+8. Run `bash scripts/check-architecture.sh`.
If baseline verification is already failing, fix that first. Do not stack new
feature work on top of a broken starting state.
@@ -51,11 +54,15 @@ Run `bash scripts/check-architecture.sh` before committing.
## Required Artifacts
-- `feature_list.json`: source of truth for feature state
-- `claude-progress.md`: session log and current verified status
-- `init.sh`: standard startup and verification path
-- `session-handoff.md`: optional compact handoff for larger sessions
+- `AGENTS.md`: operating rules for this project
+- `docs/ARCHITECTURE.md`: layer boundaries and data flow
+- `scripts/check-architecture.sh`: boundary guard
- `clean-state-checklist.md`: pre-commit repository health check
+- `sprint-contract.md`: planner scope, acceptance criteria, and sprint log
+- `evaluator-rubric.md`: quality and revision evidence for this variant
+
+Do not assume `feature_list.json`, `claude-progress.md`, `init.sh`, or
+`session-handoff.md` exist in this variant.
## Definition Of Done
@@ -63,7 +70,8 @@ A feature is done only when all of the following are true:
- the target behavior is implemented
- the required verification actually ran
-- evidence is recorded in `feature_list.json` or `claude-progress.md`
+- evidence is recorded in `sprint-contract.md`, `evaluator-rubric.md`, or the
+ final summary
- the repository remains restartable from the standard startup path
- `scripts/check-architecture.sh` passes with no violations
@@ -71,10 +79,8 @@ A feature is done only when all of the following are true:
Before ending a session:
-1. Update `claude-progress.md`.
-2. Update `feature_list.json`.
-3. Record any unresolved risk or blocker.
-4. Run `bash scripts/check-architecture.sh`.
-5. Commit with a descriptive message once the work is in a safe state.
-6. Leave the repo clean enough for the next session to run `./init.sh`
- immediately.
+1. Record any unresolved risk or blocker in your final summary.
+2. Run `npm run check`.
+3. Run `bash scripts/check-architecture.sh`.
+4. Commit with a descriptive message once the work is in a safe state.
+5. Leave the repo clean enough for the next session to run the startup workflow.
diff --git a/projects/project-05/solution/plan-gen-eval/clean-state-checklist.md b/projects/project-05/solution/plan-gen-eval/clean-state-checklist.md
index 8ce2e06..ad6359e 100644
--- a/projects/project-05/solution/plan-gen-eval/clean-state-checklist.md
+++ b/projects/project-05/solution/plan-gen-eval/clean-state-checklist.md
@@ -32,5 +32,5 @@ Run this checklist before committing and at the end of each session.
- [ ] No unintended files in git status
- [ ] No sensitive data (.env, credentials) staged
-- [ ] `claude-progress.md` updated with current state
-- [ ] `feature_list.json` reflects actual feature status
+- [ ] Final summary records current state, verification run, and any unresolved risk
+- [ ] `sprint-contract.md` and `evaluator-rubric.md` still match the implemented ConversationHistory variant
diff --git a/projects/project-05/solution/single-role/AGENTS.md b/projects/project-05/solution/single-role/AGENTS.md
index f59ac26..d2223f5 100644
--- a/projects/project-05/solution/single-role/AGENTS.md
+++ b/projects/project-05/solution/single-role/AGENTS.md
@@ -1,19 +1,20 @@
# AGENTS.md
-This repository is designed for long-running coding-agent work. The goal is not
-to maximize raw code output. The goal is to leave the repo in a state where the
-next session can continue without guessing.
+This Project 05 variant demonstrates a single-role implementation of
+ConversationHistory. It includes the completed code and evaluator rubric, but it
+does not include the full capstone harness files.
## Startup Workflow
Before writing code:
1. Confirm the working directory with `pwd`.
-2. Read `claude-progress.md` for the latest verified state and next step.
-3. Read `feature_list.json` and choose the highest-priority unfinished feature.
-4. Review recent commits with `git log --oneline -5`.
-5. Run `./init.sh`.
-6. Run the required smoke or end-to-end verification before starting new work.
+2. Read `docs/ARCHITECTURE.md` for the Electron layer boundaries.
+3. Read `evaluator-rubric.md` to understand this variant's quality evidence.
+4. Read `clean-state-checklist.md`.
+5. Run `npm install` if dependencies are missing.
+6. Run `npm run check`.
+7. Run `bash scripts/check-architecture.sh`.
If baseline verification is already failing, fix that first. Do not stack new
feature work on top of a broken starting state.
@@ -51,11 +52,14 @@ Run `bash scripts/check-architecture.sh` before committing.
## Required Artifacts
-- `feature_list.json`: source of truth for feature state
-- `claude-progress.md`: session log and current verified status
-- `init.sh`: standard startup and verification path
-- `session-handoff.md`: optional compact handoff for larger sessions
+- `AGENTS.md`: operating rules for this project
+- `docs/ARCHITECTURE.md`: layer boundaries and data flow
+- `scripts/check-architecture.sh`: boundary guard
- `clean-state-checklist.md`: pre-commit repository health check
+- `evaluator-rubric.md`: quality evidence for this variant
+
+Do not assume `feature_list.json`, `claude-progress.md`, `init.sh`, or
+`session-handoff.md` exist in this variant.
## Definition Of Done
@@ -63,7 +67,7 @@ A feature is done only when all of the following are true:
- the target behavior is implemented
- the required verification actually ran
-- evidence is recorded in `feature_list.json` or `claude-progress.md`
+- evidence is recorded in `evaluator-rubric.md` or the final summary
- the repository remains restartable from the standard startup path
- `scripts/check-architecture.sh` passes with no violations
@@ -71,10 +75,8 @@ A feature is done only when all of the following are true:
Before ending a session:
-1. Update `claude-progress.md`.
-2. Update `feature_list.json`.
-3. Record any unresolved risk or blocker.
-4. Run `bash scripts/check-architecture.sh`.
-5. Commit with a descriptive message once the work is in a safe state.
-6. Leave the repo clean enough for the next session to run `./init.sh`
- immediately.
+1. Record any unresolved risk or blocker in your final summary.
+2. Run `npm run check`.
+3. Run `bash scripts/check-architecture.sh`.
+4. Commit with a descriptive message once the work is in a safe state.
+5. Leave the repo clean enough for the next session to run the startup workflow.
diff --git a/projects/project-05/solution/single-role/clean-state-checklist.md b/projects/project-05/solution/single-role/clean-state-checklist.md
index 8ce2e06..96ac660 100644
--- a/projects/project-05/solution/single-role/clean-state-checklist.md
+++ b/projects/project-05/solution/single-role/clean-state-checklist.md
@@ -32,5 +32,5 @@ Run this checklist before committing and at the end of each session.
- [ ] No unintended files in git status
- [ ] No sensitive data (.env, credentials) staged
-- [ ] `claude-progress.md` updated with current state
-- [ ] `feature_list.json` reflects actual feature status
+- [ ] Final summary records current state, verification run, and any unresolved risk
+- [ ] `evaluator-rubric.md` still matches the implemented ConversationHistory variant
diff --git a/projects/project-05/starter/AGENTS.md b/projects/project-05/starter/AGENTS.md
index f59ac26..87bb941 100644
--- a/projects/project-05/starter/AGENTS.md
+++ b/projects/project-05/starter/AGENTS.md
@@ -1,19 +1,20 @@
# AGENTS.md
-This repository is designed for long-running coding-agent work. The goal is not
-to maximize raw code output. The goal is to leave the repo in a state where the
-next session can continue without guessing.
+This Project 05 starter is the Project 04 app before the conversation-history
+role-separation exercise. It has architecture rules and a clean-state checklist,
+but it intentionally does not include the full capstone harness files.
## Startup Workflow
Before writing code:
1. Confirm the working directory with `pwd`.
-2. Read `claude-progress.md` for the latest verified state and next step.
-3. Read `feature_list.json` and choose the highest-priority unfinished feature.
+2. Read `docs/ARCHITECTURE.md` for the Electron layer boundaries.
+3. Read `clean-state-checklist.md`.
4. Review recent commits with `git log --oneline -5`.
-5. Run `./init.sh`.
-6. Run the required smoke or end-to-end verification before starting new work.
+5. Run `npm install` if dependencies are missing.
+6. Run `npm run check`.
+7. Run `bash scripts/check-architecture.sh`.
If baseline verification is already failing, fix that first. Do not stack new
feature work on top of a broken starting state.
@@ -51,19 +52,21 @@ Run `bash scripts/check-architecture.sh` before committing.
## Required Artifacts
-- `feature_list.json`: source of truth for feature state
-- `claude-progress.md`: session log and current verified status
-- `init.sh`: standard startup and verification path
-- `session-handoff.md`: optional compact handoff for larger sessions
+- `AGENTS.md`: operating rules for this project
+- `docs/ARCHITECTURE.md`: layer boundaries and data flow
+- `scripts/check-architecture.sh`: boundary guard
- `clean-state-checklist.md`: pre-commit repository health check
+Do not assume `feature_list.json`, `claude-progress.md`, `init.sh`, or
+`session-handoff.md` exist in this starter.
+
## Definition Of Done
A feature is done only when all of the following are true:
- the target behavior is implemented
- the required verification actually ran
-- evidence is recorded in `feature_list.json` or `claude-progress.md`
+- evidence is recorded in the final summary or in the variant artifacts you add
- the repository remains restartable from the standard startup path
- `scripts/check-architecture.sh` passes with no violations
@@ -71,10 +74,8 @@ A feature is done only when all of the following are true:
Before ending a session:
-1. Update `claude-progress.md`.
-2. Update `feature_list.json`.
-3. Record any unresolved risk or blocker.
-4. Run `bash scripts/check-architecture.sh`.
-5. Commit with a descriptive message once the work is in a safe state.
-6. Leave the repo clean enough for the next session to run `./init.sh`
- immediately.
+1. Record any unresolved risk or blocker in your final summary.
+2. Run `npm run check`.
+3. Run `bash scripts/check-architecture.sh`.
+4. Commit with a descriptive message once the work is in a safe state.
+5. Leave the repo clean enough for the next session to run the startup workflow.
diff --git a/projects/project-05/starter/clean-state-checklist.md b/projects/project-05/starter/clean-state-checklist.md
index 8ce2e06..eed06c0 100644
--- a/projects/project-05/starter/clean-state-checklist.md
+++ b/projects/project-05/starter/clean-state-checklist.md
@@ -32,5 +32,5 @@ Run this checklist before committing and at the end of each session.
- [ ] No unintended files in git status
- [ ] No sensitive data (.env, credentials) staged
-- [ ] `claude-progress.md` updated with current state
-- [ ] `feature_list.json` reflects actual feature status
+- [ ] Final summary records current state, verification run, and any unresolved risk
+- [ ] `AGENTS.md`, `docs/ARCHITECTURE.md`, and this checklist still match the files that actually exist in this starter
diff --git a/projects/project-06/README-CN.md b/projects/project-06/README-CN.md
index 9d846f5..b0f2eda 100644
--- a/projects/project-06/README-CN.md
+++ b/projects/project-06/README-CN.md
@@ -14,7 +14,8 @@
```sh
cd starter
npm install
-# 用弱 harness 跑基准测试套件,记录结果
+# 运行应用并手动记录弱 harness 表现
+# starter 故意不包含 benchmark.sh 或 cleanup-scanner.sh
cd ../solution
npm install
@@ -29,6 +30,20 @@ npm install
./scripts/cleanup-scanner.sh
```
+## 具体任务对应关系
+
+Project 06 是完整产品 + 弱 harness 表面,与完整产品 + 强 harness 表面的对比。和前几个项目不同,starter 已经包含大部分产品功能,差距主要在代码周围的操作系统。
+
+| 领域 | starter 状态 | solution 证据 |
+|------|------|------|
+| 产品行为 | 导入、索引、QA、历史、反馈、重置大多已存在 | 同功能,并有更强验证和持久化证据 |
+| Harness 文件 | 只有基础 `AGENTS.md`,没有 `feature_list.json`、`session-handoff.md`、clean-state checklist | `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md` |
+| 质量追踪 | 初始 `quality-document.md` | 更高评分的 `quality-document.md`, `evaluator-rubric.md` |
+| 基准测试 | 没有 benchmark / cleanup 脚本 | `scripts/benchmark.sh`, `scripts/cleanup-scanner.sh`, `scripts/check-architecture.sh` |
+| 可靠性文档 | 文档较少 | `docs/ARCHITECTURE.md`, `docs/PRODUCT.md`, `docs/RELIABILITY.md` |
+
+不要期待 starter 里有 solution 才提供的 benchmark 命令。弱 harness 运行使用手动基线记录,solution 运行使用已提交脚本。
+
## 本项目涉及的功能
- 导入文档
diff --git a/projects/project-06/README.md b/projects/project-06/README.md
index d312ab3..95ad383 100644
--- a/projects/project-06/README.md
+++ b/projects/project-06/README.md
@@ -14,7 +14,8 @@ Capstone project: build and benchmark a complete harness, then run cleanup loops
```sh
cd starter
npm install
-# Run the benchmark suite with the weak harness and record the results
+# Run the app and record weak-harness behavior manually.
+# The starter intentionally does not include benchmark.sh or cleanup-scanner.sh.
cd ../solution
npm install
@@ -29,6 +30,25 @@ npm install
./scripts/cleanup-scanner.sh
```
+## Exact Task Contract
+
+Project 06 is a capstone comparison between a complete product with weak harness
+surface and the same product hardened with full harness artifacts. Unlike earlier
+projects, the starter already contains most product functionality. The gap is the
+operating system around the code.
+
+| Area | Starter state | Solution evidence |
+|------|------|------|
+| Product behavior | Import, indexing, QA, history, feedback, reset mostly exist | Same features plus stronger validation and persistence evidence |
+| Harness files | Basic `AGENTS.md`, no `feature_list.json`, no `session-handoff.md`, no clean-state checklist | `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md` |
+| Quality tracking | Initial `quality-document.md` only | Higher-scored `quality-document.md`, `evaluator-rubric.md` |
+| Benchmarking | No benchmark or cleanup scripts | `scripts/benchmark.sh`, `scripts/cleanup-scanner.sh`, `scripts/check-architecture.sh` |
+| Reliability docs | Minimal docs | `docs/ARCHITECTURE.md`, `docs/PRODUCT.md`, `docs/RELIABILITY.md` |
+
+Do not expect the starter to contain the benchmark commands shown for the
+solution. For the weak-harness run, record manual baseline observations; for the
+solution run, use the checked-in benchmark and cleanup scripts.
+
## Features Covered
- Import documents
diff --git a/projects/project-06/solution/docs/PRODUCT.md b/projects/project-06/solution/docs/PRODUCT.md
index 788ad4f..468c53f 100644
--- a/projects/project-06/solution/docs/PRODUCT.md
+++ b/projects/project-06/solution/docs/PRODUCT.md
@@ -80,7 +80,7 @@ A desktop application for managing a personal knowledge base. Users import text
| 3.2 KB | Q&A Response: |
| doc2 (Imported) | Answer text... |
| 1.8 KB | Citations: [expandable] |
-| | Confidence: 85% |
+| | Confidence: high |
| | [+1] [-1] feedback |
+------------------+----------------------------------------+
| Ask a question... [Ask] |
diff --git a/projects/project-06/starter/AGENTS.md b/projects/project-06/starter/AGENTS.md
index dcc7142..bb3b361 100644
--- a/projects/project-06/starter/AGENTS.md
+++ b/projects/project-06/starter/AGENTS.md
@@ -11,17 +11,22 @@
This is the capstone project for the Learn Harness Engineering course. It combines all features from previous projects:
- Document import, indexing, and Q&A
- Conversation history view
-- Structured logging for observability
- Clean state management for testing
-## What to Build
+This starter intentionally has a weak harness surface. It does not include
+`CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, benchmark
+scripts, or cleanup scripts. Use it as the baseline for comparison with
+`../solution/`.
-The application needs:
-1. A working ConversationHistory component with chat-style display
+## What to Evaluate or Improve
+
+The baseline should be evaluated against the solution on:
+
+1. ConversationHistory completeness
2. Feedback buttons on Q&A responses (thumbs up/down)
-3. Structured logging that all services use
-4. A clean state reset function
-5. Benchmark scripts for measuring performance
+3. Structured logging coverage
+4. Clean state reset behavior
+5. Harness artifacts and benchmark automation that exist in `../solution/`
## Conventions
diff --git a/scripts/validate-project-docs.ts b/scripts/validate-project-docs.ts
new file mode 100644
index 0000000..8fe7c4b
--- /dev/null
+++ b/scripts/validate-project-docs.ts
@@ -0,0 +1,295 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs"
+import path from "node:path"
+
+type Finding = {
+ docPath: string
+ line: number
+ ref: string
+ message: string
+}
+
+const repoRoot = path.resolve(__dirname, "..")
+const docsRoot = path.join(repoRoot, "docs")
+
+function walk(dir: string): string[] {
+ const entries = readdirSync(dir, { withFileTypes: true }) as Array<{
+ name: string
+ isDirectory(): boolean
+ isFile(): boolean
+ }>
+ const out: string[] = []
+ for (const entry of entries) {
+ const full = path.join(dir, entry.name)
+ if (entry.isDirectory()) out.push(...walk(full))
+ else if (entry.isFile()) out.push(full)
+ }
+ return out
+}
+
+function isProjectDoc(filePath: string): boolean {
+ const normalized = filePath.split(path.sep).join("/")
+ return /\/docs\/[^/]+\/projects\/project-\d{2}-[^/]+\/index\.md$/.test(normalized)
+}
+
+const backtickRe = /`([^`]+)`/g
+
+function validatePathLiteral(
+ docPath: string,
+ line: number,
+ ref: string,
+ findings: Finding[],
+): void {
+ const trimmed = ref.trim()
+
+ if (trimmed === "starter/" || trimmed === "solution/") return
+ // Project docs often mention per-project commands like `./init.sh` or `./scripts/*.sh`
+ // which are only valid after `cd projects/project-XX/...`. We treat those as context-relative
+ // and do not validate them at repo root.
+ if (trimmed === "./init.sh" || trimmed.startsWith("./scripts/")) return
+
+ // Only validate repo-relative path literals; avoid false positives like "main / preload / renderer".
+ const isRepoRelative =
+ trimmed.startsWith("projects/") ||
+ trimmed.startsWith("docs/") ||
+ trimmed.startsWith("scripts/") ||
+ trimmed.startsWith("./")
+ if (!isRepoRelative) return
+
+ const normalized = trimmed.startsWith("./") ? trimmed.slice(2) : trimmed
+ const abs = path.join(repoRoot, normalized)
+ if (!existsSync(abs)) {
+ findings.push({
+ docPath,
+ line,
+ ref: trimmed,
+ message: `Path does not exist: ${normalized}`,
+ })
+ }
+}
+
+function validateProjectArtifacts(findings: Finding[]): void {
+ for (let i = 1; i <= 6; i += 1) {
+ const projectId = `project-${String(i).padStart(2, "0")}`
+ const projectRoot = path.join(repoRoot, "projects", projectId)
+ const starterRoot = path.join(projectRoot, "starter")
+ const solutionRoot = path.join(projectRoot, "solution")
+
+ if (!existsSync(projectRoot)) {
+ findings.push({
+ docPath: "scripts/validate-project-docs.ts",
+ line: 1,
+ ref: projectRoot,
+ message: "Project directory missing",
+ })
+ continue
+ }
+
+ if (!existsSync(starterRoot)) {
+ findings.push({
+ docPath: "scripts/validate-project-docs.ts",
+ line: 1,
+ ref: starterRoot,
+ message: "starter/ directory missing",
+ })
+ }
+
+ if (!existsSync(solutionRoot)) {
+ findings.push({
+ docPath: "scripts/validate-project-docs.ts",
+ line: 1,
+ ref: solutionRoot,
+ message: "solution/ directory missing",
+ })
+ }
+
+ // Project 01 contract: starter has task prompt only; solution has harness artifacts.
+ if (projectId === "project-01") {
+ const expectedStarter = ["task-prompt.md"]
+ for (const file of expectedStarter) {
+ const abs = path.join(starterRoot, file)
+ if (!existsSync(abs)) {
+ findings.push({
+ docPath: "projects/project-01/README.md",
+ line: 1,
+ ref: `projects/project-01/starter/${file}`,
+ message: "Expected file missing for Project 01 starter contract",
+ })
+ }
+ }
+
+ const expectedSolution = ["AGENTS.md", "feature_list.json", "init.sh", "claude-progress.md", "CLAUDE.md"]
+ for (const file of expectedSolution) {
+ const abs = path.join(solutionRoot, file)
+ if (!existsSync(abs)) {
+ findings.push({
+ docPath: "projects/project-01/README.md",
+ line: 1,
+ ref: `projects/project-01/solution/${file}`,
+ message: "Expected file missing for Project 01 solution contract",
+ })
+ }
+ }
+ }
+
+ // Project 02 contract: solution includes continuity docs.
+ if (projectId === "project-02") {
+ const expectedSolution = [
+ "docs/ARCHITECTURE.md",
+ "docs/PRODUCT.md",
+ "feature_list.json",
+ "session-handoff.md",
+ "AGENTS.md",
+ ]
+ for (const rel of expectedSolution) {
+ const abs = path.join(solutionRoot, rel)
+ if (!existsSync(abs)) {
+ findings.push({
+ docPath: "projects/project-02/README.md",
+ line: 1,
+ ref: `projects/project-02/solution/${rel}`,
+ message: "Expected artifact missing for Project 02 solution contract",
+ })
+ }
+ }
+ }
+
+ // Project 03 contract: solution includes init + handoff + clean-state artifacts.
+ if (projectId === "project-03") {
+ const expectedSolution = [
+ "feature_list.json",
+ "init.sh",
+ "session-handoff.md",
+ "claude-progress.md",
+ "clean-state-checklist.md",
+ "AGENTS.md",
+ ]
+ for (const rel of expectedSolution) {
+ const abs = path.join(solutionRoot, rel)
+ if (!existsSync(abs)) {
+ findings.push({
+ docPath: "projects/project-03/README.md",
+ line: 1,
+ ref: `projects/project-03/solution/${rel}`,
+ message: "Expected artifact missing for Project 03 solution contract",
+ })
+ }
+ }
+ }
+
+ // Project 04 contract: solution includes architecture check + clean-state checklist.
+ if (projectId === "project-04") {
+ const expectedSolution = [
+ "scripts/check-architecture.sh",
+ "docs/ARCHITECTURE.md",
+ "clean-state-checklist.md",
+ "AGENTS.md",
+ ]
+ for (const rel of expectedSolution) {
+ const abs = path.join(solutionRoot, rel)
+ if (!existsSync(abs)) {
+ findings.push({
+ docPath: "projects/project-04/README.md",
+ line: 1,
+ ref: `projects/project-04/solution/${rel}`,
+ message: "Expected artifact missing for Project 04 solution contract",
+ })
+ }
+ }
+ }
+
+ // Project 05 contract: three solution variants must include evaluator rubric; plan-gen-eval adds sprint contract.
+ if (projectId === "project-05") {
+ const variants = ["single-role", "gen-eval", "plan-gen-eval"] as const
+ for (const variant of variants) {
+ const variantRoot = path.join(solutionRoot, variant)
+ if (!existsSync(variantRoot)) {
+ findings.push({
+ docPath: "projects/project-05/README.md",
+ line: 1,
+ ref: `projects/project-05/solution/${variant}/`,
+ message: "Expected variant directory missing for Project 05 solution contract",
+ })
+ continue
+ }
+
+ const required = ["AGENTS.md", "clean-state-checklist.md", "evaluator-rubric.md"]
+ for (const rel of required) {
+ const abs = path.join(variantRoot, rel)
+ if (!existsSync(abs)) {
+ findings.push({
+ docPath: "projects/project-05/README.md",
+ line: 1,
+ ref: `projects/project-05/solution/${variant}/${rel}`,
+ message: "Expected artifact missing for Project 05 variant contract",
+ })
+ }
+ }
+
+ if (variant === "plan-gen-eval") {
+ const abs = path.join(variantRoot, "sprint-contract.md")
+ if (!existsSync(abs)) {
+ findings.push({
+ docPath: "projects/project-05/README.md",
+ line: 1,
+ ref: "projects/project-05/solution/plan-gen-eval/sprint-contract.md",
+ message: "Expected sprint contract missing for plan-gen-eval variant",
+ })
+ }
+ }
+ }
+ }
+
+ // Project 06 contract: solution has benchmark and cleanup scripts.
+ if (projectId === "project-06") {
+ const expected = ["scripts/benchmark.sh", "scripts/cleanup-scanner.sh", "scripts/check-architecture.sh"]
+ for (const rel of expected) {
+ const abs = path.join(solutionRoot, rel)
+ if (!existsSync(abs)) {
+ findings.push({
+ docPath: "projects/project-06/README.md",
+ line: 1,
+ ref: `projects/project-06/solution/${rel}`,
+ message: "Expected script missing for Project 06 solution contract",
+ })
+ }
+ }
+ }
+ }
+}
+
+function main(): void {
+ const mdFiles = walk(docsRoot).filter((p) => p.endsWith(".md") && isProjectDoc(p))
+ const findings: Finding[] = []
+
+ for (const filePath of mdFiles) {
+ const relDoc = path.relative(repoRoot, filePath).split(path.sep).join("/")
+ const content = readFileSync(filePath, "utf-8")
+ const lines = content.split("\n")
+ for (let i = 0; i < lines.length; i += 1) {
+ const lineNo = i + 1
+ const line = lines[i]
+ if (!line.includes("`")) continue
+ for (const match of line.matchAll(backtickRe)) {
+ validatePathLiteral(relDoc, lineNo, match[1], findings)
+ }
+ }
+ }
+
+ validateProjectArtifacts(findings)
+
+ if (findings.length === 0) {
+ // eslint-disable-next-line no-console
+ console.log("OK: no missing repo-relative path literals in project docs.")
+ return
+ }
+
+ // eslint-disable-next-line no-console
+ console.error(`Found ${findings.length} invalid path reference(s):`)
+ for (const f of findings) {
+ // eslint-disable-next-line no-console
+ console.error(`- ${f.docPath}:${f.line} \`${f.ref}\` -> ${f.message}`)
+ }
+ process.exitCode = 1
+}
+
+main()