coding-agent-harness 1.0.2 → 1.0.5

package/docs-release/architecture/system-explainer/en-US/05-data-flow.md

@@ -0,0 +1,290 @@
+# 05 — Data Flow: From Markdown to Dashboard
+
+## Level 0 — Where data starts and ends
+
+```mermaid
+flowchart LR
+  A["📄 Markdown files\n(source files under docs/)"]
+  B["⚙️ Scanner\n(parse + validate)"]
+  C["📊 Dashboard\n(HTML + JSON)"]
+
+  A -->|"read"| B -->|"generate"| C
+```
+
+All data comes from Markdown files — no database, no external services.
+Every run re-reads from the filesystem from scratch, caching no intermediate state.
+
+---
+
+## Level 1 — Which files are data sources
+
+```mermaid
+flowchart TD
+  Sources["Data source files"]
+
+  Sources --> TP["task_plan.md\nBudget / title / metadata / Preset info\nTask Contract marker"]
+  Sources --> PR["progress.md\nCurrent state / operation log"]
+  Sources --> VM["visual_map.md\nPhase list / completion / evidence status"]
+  Sources --> RV["review.md\nFindings table / human confirmation block"]
+  Sources --> BR["brief.md\nTask summary"]
+  Sources --> LC["lesson_candidates.md\nLesson candidates / decision state"]
+  Sources --> HL["Harness-Ledger.md\nGlobal ledger (all tasks summarized)"]
+  Sources --> ES["execution_strategy.md\nSubagent authorization state"]
+```
+
+---
+
+## Level 2 — How the Scanner processes these files
+
+The Scanner layer (`task-scanner.mjs` + `task-review-model.mjs`) parses raw Markdown
+into structured objects.
+
+### collectTasks() discovery flow
+
+```mermaid
+flowchart TD
+  CT["collectTasks()"]
+
+  CT --> Discover["listTaskPlanPaths()\nScans two root directories:\n09-PLANNING/TASKS/\n09-PLANNING/MODULES/\nFilters out template and archive directories"]
+
+  Discover --> ReadFiles["For each task directory, reads 9 files:\ntask_plan / brief / progress\nreview / visual_map\nexecution_strategy\nlesson_candidates / findings / context"]
+
+  ReadFiles --> Parse["Parse each file"]
+
+  Parse --> P1["parseTaskBudget()\nExtract budget from task_plan.md"]
+  Parse --> P2["parseTaskState()\nExtract state from progress.md"]
+  Parse --> P3["parsePhases()\nExtract phase list from visual_map.md"]
+  Parse --> P4["parseAgentReviewSubmission()\nExtract Agent submission state from review.md"]
+  Parse --> P5["parseReviewConfirmation()\nExtract human confirmation block from review.md"]
+  Parse --> P6["parseLessonCandidateStatus()\nExtract decision state from lesson_candidates.md"]
+  Parse --> P7["parseTaskTombstone()\nExtract soft-delete state from task_plan.md"]
+
+  P1 & P2 & P3 & P4 & P5 & P6 & P7 --> Derive["Derivation (pure functions)"]
+
+  Derive --> LS["deriveLifecycleState()\nDerive lifecycleState from combined inputs"]
+  Derive --> QS["deriveTaskQueues()\nDetermine which queues the task belongs to"]
+  Derive --> RQS["deriveReviewQueueState()\nDerive reviewQueueState"]
+```
+
+### parseTaskState() format
+
+Extracts state from the first line after the `## Current Status` or `## Status` heading
+in `progress.md`:
+
+```markdown
+## Current Status
+
+in_progress
+```
+
+Supports Chinese aliases (`进行中` → `in_progress`). Falls back to legacy table parsing
+mode if the format doesn't match expectations.
+
+### parsePhases() table format
+
+Finds the table with a `Phase ID` column header in `visual_map.md` and extracts 9 fields:
+
+```markdown
+| Phase ID | Depends On | State | Completion | Output | Required Evidence | Evidence Status | Blocking Risk | Owner / Handoff |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| P1 | — | done | 100 | ... | E-001 | present | low | coordinator |
+```
+
+The dependency field supports multiple values separated by commas, semicolons, or `&`.
+
+---
+
+## Level 2 — What buildStatus() assembles from Scanner results
+
+```mermaid
+flowchart TD
+  BS["buildStatus()"]
+
+  BS --> Tasks["tasks[]\nComplete structured data for each task\n(see field list below)"]
+  BS --> Failures["failures[]\nHard failure list"]
+  BS --> Warnings["warnings[]\nSoft warning list"]
+  BS --> Caps["capabilities[]\nCapability registry state"]
+  BS --> Git["git\nGit status summary (dirty files etc.)"]
+  BS --> Summary["summary\nbriefCoverage / visualMapCoverage\nfullCutoverEligible and other aggregate metrics"]
+```
+
+**Complete fields of a task object**:
+
+| Field | Meaning |
+| --- | --- |
+| `path` | Relative path |
+| `title` | Task title |
+| `state` | Task state (`in_progress / done / ...`) |
+| `stateSource` | State source (`valid / invalid`) |
+| `budget` | Budget level (`simple / standard / complex`) |
+| `lifecycleState` | Derived lifecycle state |
+| `reviewQueueState` | Review queue state |
+| `taskQueues[]` | List of queues the task belongs to |
+| `phases[]` | Phase list (with id / state / completion / evidenceStatus) |
+| `closeoutStatus` | Closeout status |
+| `tombstone` | Soft-delete information |
+| `briefSource` | Brief source (`standalone / missing / ...`) |
+| `visualMapSource` | Visual map source (`canonical / legacy / missing`) |
+| `taskPreset` | Preset ID used |
+| `presetVersion` | Preset version |
+| `handoffs` | Handoff information array |
+| `lessonCandidateDecisionComplete` | Whether Lesson decision is complete |
+
+---
+
+## Level 3 — What buildDashboardBundle() adds on top of status
+
+`buildDashboardBundle()` calls `buildStatus()` then additionally collects four types of data:
+
+```mermaid
+flowchart TD
+  Bundle["buildDashboardBundle()"]
+
+  Bundle --> Status["status\n(from buildStatus)"]
+  Bundle --> Documents["documents[]\nContent of all Markdown documents\nEach document: id / path / title / type / content"]
+  Bundle --> Tables["tables[]\nMarkdown tables extracted from documents\nEach table: column definitions + row data"]
+  Bundle --> Graph["graph\nTask dependency graph\nnodes (tasks/phases/modules/steps)\nedges (dependency/containment/handoff relationships)"]
+  Bundle --> Adoption["adoption\nMigration adoption state analysis\n(warnings categorized with priority and fix suggestions)"]
+```
+
+### documents collection scope
+
+Which files `collectMarkdownDocuments()` collects:
+
+```mermaid
+flowchart TD
+  Collect["collectMarkdownDocuments()"]
+
+  Collect --> Fixed["Fixed paths (collected when they exist)\nHarness-Ledger.md\n09-PLANNING/Module-Registry.md\n05-TEST-QA/Regression-SSoT.md\n10-WALKTHROUGH/Closeout-SSoT.md"]
+
+  Collect --> Walkthrough["All .md files under 10-WALKTHROUGH/\n(excluding _archive/ and files starting with _)"]
+
+  Collect --> TaskDocs["Under each task directory:\nbrief / task_plan / execution_strategy\nvisual_map / lesson_candidates\nprogress / review / findings\nreferences/INDEX.md / artifacts/INDEX.md"]
+
+  Collect --> ModuleDocs["Under 09-PLANNING/MODULES/:\nmodule_plan.md for each module\nbrief.md for each module"]
+
+  Collect --> Lessons["All .md files under 01-GOVERNANCE/lessons/"]
+```
+
+After collection, uniformly filters out `_archive/`, `_task-template/`, and
+`_optional-structures/` paths.
+
+### graph data structure
+
+The graph contains two types of elements:
+
+- **nodes**: task nodes, phase nodes, module nodes, step nodes
+- **edges**: dependency relationships (phase → phase), containment relationships (task → phase),
+  handoff relationships (step → step)
+
+If the source node of a dependency doesn't exist, a virtual node of type
+`external-dependency` is created.
+
+---
+
+## Level 2 — Two Dashboard generation modes
+
+```mermaid
+flowchart LR
+  subgraph "Static mode (read-only snapshot)"
+    SC["harness dashboard\n--out-dir ./out"]
+    SC --> SH["index.html\n(all resources inlined)"]
+    SC --> SJ["dashboard-data.json\n(for external tools to read)"]
+    SC --> SF["status.json / tables.json\ndocuments.json / graph.json\nadoption.json"]
+  end
+
+  subgraph "Dynamic mode (Workbench)"
+    DC["harness dev"]
+    DC --> HTTP["Local HTTP server\nlocalhost:PORT"]
+    DC --> Watch["File watching\nPolling mode, checks every 1 second\nRegenerates after 250ms delay on change"]
+    HTTP --> Browser["Live browser view\nSupports review-confirm and other write operations"]
+  end
+```
+
+**Key boundary**: The static Dashboard is read-only and cannot trigger any write operations.
+Only `harness dev` (Workbench mode) can execute write operations like `review-confirm`
+and `task-start`.
+
+### Dashboard HTML generation
+
+Dashboard HTML is generated via string concatenation (no template engine).
+`app.js` is obtained via manifest or direct read — if a manifest exists, it reads and
+concatenates multiple source files in order (modular source code under `app-src/`).
+
+`<` in the payload is escaped to `&lt;` to prevent HTML injection.
+
+### File watching implementation
+
+`dashboard-workbench.mjs` file watching uses **polling mode** (`startPollingWatch()`):
+- Checks the latest modification time (mtime) of the directory tree every 1000ms
+- When a change is detected, triggers regeneration after a 250ms delay (debounce)
+- Watch scope: the entire `target.docsRoot`, excluding `.git`, `node_modules`, `tmp`
+
+---
+
+## Level 3 — Core capabilities of markdown-utils.mjs
+
+The technical foundation that lets the whole system derive state from Markdown files is
+the table parsing capability provided by `markdown-utils.mjs`:
+
+| Function | Purpose |
+| --- | --- |
+| `markdownTableRows()` | Extract all table rows |
+| `parseAllMarkdownTables()` | Parse all tables in a document, return array of structured objects |
+| `splitMarkdownRow()` | Split row cells (handles escaped pipe characters and code blocks) |
+| `tableAfterHeading()` | Locate the table after a specific heading |
+| `getCell()` | Get a cell by column name (supports multiple aliases) |
+| `splitList()` | Split comma/semicolon/plus-separated lists |
+| `splitDependencies()` | Split dependencies, filtering out `none/n/a` placeholders |
+
+**Pipe characters inside code blocks**: `splitMarkdownRow()` tracks code block state —
+`|` inside code blocks is not treated as a column separator and the original content is preserved.
+
+---
+
+## Level 2 — Design decisions
+
+### Why Dashboard is plain HTML + vanilla JS, not React/Vite
+
+harness is distributed via `npx`. Introducing React/Vite would mean users pull in large
+build dependencies on every run, breaking the zero-dependency portability. Static HTML can
+be opened directly from `file://` and shared as a CI evidence snapshot without any runtime.
+
+The vanilla JS components in app-src (`DashboardShell`, `SidebarNav`, `TableView`, etc.)
+are concatenated in order via manifest. Each file is < 600 lines, git-diff readable,
+no webpack/esbuild needed.
+
+### Why the static Dashboard is read-only
+
+The static Dashboard's role is "shareable evidence snapshot" — it can be generated by CI,
+opened offline, and sent to external reviewers. In these scenarios, write operations have
+no security boundary (no CSRF/Origin/Host validation). Write operations can only be
+executed in Workbench mode, because the Workbench server binds to `127.0.0.1` and has
+a complete security validation chain.
+
+### Why `harness dev` and `harness dashboard` are two separate commands
+
+`harness dashboard` generates a static read-only snapshot (suitable for CI, migration
+reports, offline evidence). `harness dev` starts a local dynamic Workbench server with
+file watching, auto-refresh, and review-confirm write operations. The boundary is:
+**static snapshots can be shared; the dynamic Workbench is local-only**.
+
+### Why file watching uses polling instead of fs.watch
+
+`fs.watch` has known missed-event issues on macOS for deep directory trees, and harness's
+docs directory structure is a multi-level nested Markdown file tree. The polling approach
+is simple to implement, has predictable behavior, and doesn't introduce third-party
+dependencies like chokidar (consistent with the zero-dependency principle).
+1-second polling + 250ms debounce is sufficient for human editing scenarios.
+
+### Why not introduce SQLite or a JSON database
+
+Introducing JSON/SQLite without a clear authority boundary would create drift between
+Markdown, JSON, and SQLite as three separate facts. Git review is friendly to Markdown/JSON
+diffs but not to SQLite diffs. Current scale is "hundreds of tasks" — generated JSON +
+indexed in-memory filtering is sufficient.
+
+The decision: Markdown is the single source of truth, generated JSON index is a
+regenerable cache, and SQLite is only considered when task count and query complexity
+exceed what JSON can handle — and even then, only as a regenerable query cache, never
+hand-written, never as an authoritative source of truth.

package/docs-release/architecture/system-explainer/en-US/06-preset-and-migration.md

@@ -0,0 +1,323 @@
+# 06 — Preset System and Migration Engine
+
+## Level 0 — Two independent subsystems
+
+This document covers two related but independent subsystems:
+
+```mermaid
+flowchart LR
+  A["Preset system\nReusable task method packages\n(injected at new-task time)"]
+  B["Migration engine\nOnboarding legacy projects to harness\n(migrate-* commands)"]
+
+  A -->|"legacy-migration Preset\nis the migration engine's dedicated Preset"| B
+```
+
+Their relationship: the migration engine has a dedicated Preset (`legacy-migration`), but
+the Preset system itself is general-purpose — any type of task can have its own Preset.
+
+---
+
+## Part 1 — Preset System
+
+### Level 1 — What is a Preset
+
+A Preset is a **reusable task method package** that bundles everything a specific type of
+task needs:
+- Template append content (appended on top of standard templates)
+- Execution scripts (run during plan / scaffold phases)
+- Check scripts (validate Preset compliance)
+- Resource declarations (reference files, artifacts, required reads)
+
+```mermaid
+flowchart TD
+  Preset["Preset package\npresets/<id>/"]
+
+  Preset --> Manifest["preset.yaml\nPackage manifest (required)"]
+  Preset --> Templates["templates/\nTemplate append files"]
+  Preset --> Scripts["scripts/\nPlan / scaffold scripts"]
+  Preset --> Checks["checks/\nCheck scripts"]
+  Preset --> Workbench["workbench/\nDashboard panel definitions (optional)"]
+```
+
+### Level 1 — Layered discovery: three search layers
+
+Presets are searched in **project → user → builtin** order, with **first-match-wins** for
+same-named Presets:
+
+```mermaid
+flowchart LR
+  P["project layer\n<target>/.coding-agent-harness/presets/\n(highest priority)"]
+  U["user layer\n~/.coding-agent-harness/presets/\n(second priority)"]
+  B["builtin layer\npackage/presets/\n(lowest priority)"]
+
+  P -->|"continue if not found"| U -->|"continue if not found"| B
+```
+
+This design allows:
+- **Project-level override**: put a same-named Preset in the project to override the builtin version
+- **User-level override**: put a Preset in the home directory to apply to all projects
+- **Builtin fallback**: Presets bundled with the package serve as the default implementation
+
+`harness preset install --project <preset-id>` installs a Preset to the project layer;
+`harness preset uninstall --project <preset-id>` removes it from the project layer
+(doesn't affect user and builtin layers).
+
+### Level 2 — preset.yaml structure
+
+```mermaid
+flowchart TD
+  YAML["preset.yaml"]
+
+  YAML --> Meta["Basic info\nid / version / purpose\ncompatibleBudgets / localeSupport"]
+  YAML --> Task["task config\nkind / requiresFromSession\nprojectLevelOnly"]
+  YAML --> EP["entrypoints\n(see below)"]
+  YAML --> WS["writeScopes\nRestrict write paths (security boundary)"]
+  YAML --> Resources["resources\nreferences / artifacts / context.requiredReads"]
+  YAML --> Audit["audit\nmanifestRequired: true\nevidenceFiles[]"]
+```
+
+### Level 3 — Entrypoint type system
+
+Each entrypoint has two dimensions: **name** (when it triggers) and **type** (how it executes):
+
+```mermaid
+flowchart LR
+  subgraph "Name (when it triggers)"
+    N1["newTask\nWhen harness new-task --preset X is run"]
+    N2["plan\nMigration plan phase"]
+    N3["scaffold\nBulk completion phase"]
+    N4["check\nValidation phase"]
+  end
+
+  subgraph "Type (how it executes)"
+    T1["template\nAppend template content to task files"]
+    T2["script\nRun a Node.js script"]
+    T3["check\nRun a check script"]
+  end
+```
+
+Differences between the three execution types:
+- **template**: Renders a template file and appends the result to task files
+  (`task_plan.md`, `execution_strategy.md`, etc.)
+- **script**: Executes a Node.js script that can read/write the filesystem;
+  returns results as audit evidence
+- **check**: Executes a check script that validates Preset application completeness;
+  blocks task creation on failure
+
+Each entrypoint also declares `writes` (allowed write path globs) and `reads`
+(allowed read path globs).
+
+### Level 3 — writeScopes security boundary
+
+`writeScopes` is a path allowlist that restricts Presets to only writing to declared directories.
+`assertPresetWriteScope()` checks whether the relative path matches any scope on every file write.
+
+```
+writeScopes:
+  tasks:
+    path: docs/09-PLANNING/TASKS/**
+    access: write
+```
+
+Supports `path/**` wildcards for a directory and all its subdirectories.
+Relative paths must be normalized (no `../`, no absolute paths) to prevent path traversal attacks.
+
+### Level 2 — Preset lifecycle
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant CLI as harness CLI
+  participant Registry as preset-registry.mjs
+  participant Engine as preset-engine.mjs
+  participant TaskDir as Task directory
+
+  User->>CLI: harness new-task my-task --preset legacy-migration --from-session session.json
+  CLI->>Registry: listPresetPackages()\n(layered discovery, first-match-wins)
+  Registry-->>CLI: Preset object (with manifest + path)
+  CLI->>TaskDir: Create standard task scaffold (brief / task_plan / visual_map etc.)
+  CLI->>Engine: executeEntrypoint("newTask", preset, taskDir)
+  Engine->>TaskDir: Append Preset template content to task files
+  CLI->>TaskDir: Write Preset metadata to task_plan.md
+  CLI->>TaskDir: Generate evidence bundle (preset-manifest.json / preset-audit.json)
+  CLI-->>User: Task creation complete
+```
+
+### Level 1 — Currently available Presets
+
+| Preset ID | Purpose | Compatible Budget | Special requirements |
+| --- | --- | --- | --- |
+| `legacy-migration` | Migrate legacy harness projects to v1.0 | complex | Requires `--from-session session.json` |
+| `lesson-sedimentation` | Lesson sedimentation tasks | standard, complex | None |
+| `module` | Module parallel work tasks | standard, complex | Requires `--module <module-id>` |
+| `standard-task` | Standard task method | standard, complex | None |
+
+---
+
+## Part 2 — Migration Engine
+
+### Level 1 — Three phases of migration
+
+```mermaid
+flowchart LR
+  A["① migrate-plan\nAnalyze gaps\nGenerate action queue"] --> B["② migrate-run\nExecute migration actions\nWrite session record"] --> C["③ migrate-verify\nVerify migration results\nCompare against baseline"]
+```
+
+### Level 2 — What migrate-plan does
+
+`buildMigrationPlan()` identifies 6 types of gaps:
+
+```mermaid
+flowchart TD
+  Plan["harness migrate-plan"]
+
+  Plan --> Scan["Scan target repo\nbuildStatus (non-strict mode)"]
+  Scan --> Detect["Detect existing capabilities\nreadCapabilityRegistry()"]
+  Detect --> Gaps["Identify gaps (6 types)"]
+
+  Gaps --> TaskActions["taskActions\nActive tasks missing execution_strategy.md\nor visual_map.md"]
+  Gaps --> ReviewActions["reviewActions\nMissing review fields\n(Reviewer Identity etc.)"]
+  Gaps --> LegacyActions["legacyActions\nMissing required reference files"]
+  Gaps --> LegacyResiduals["legacyResiduals\nContract gaps in historical tasks\n(should not be auto-migrated)"]
+  Gaps --> WeakBriefs["weakBriefTasks\nbrief.md quality below threshold"]
+  Gaps --> UnknownClass["unknownClassificationTasks\nTask classification unclear"]
+```
+
+**Action queue format**: Each taskAction contains `taskId`, `path`, `files[]`, `commands[]`,
+and an `action` description. `commands[]` is a list of harness CLI commands that can be
+executed directly.
+
+### Level 2 — Two modes of migrate-verify
+
+```mermaid
+flowchart TD
+  Verify["harness migrate-verify session.json"]
+
+  Verify --> Normal["Normal mode\nRe-run checks\nReport failures / warnings"]
+
+  Verify --> FullCutover["--full-cutover mode\nStrictest validation (8 conditions)"]
+
+  FullCutover --> C1{"session.result == complete?"}
+  C1 -->|"no"| F1["FAIL"]
+  C1 -->|"yes"| C2{"No strictDeferred?"}
+  C2 -->|"no"| F2["FAIL"]
+  C2 -->|"yes"| C3{"All counters == 0?\n(warnings / taskActions\nreviewSchemaGaps / legacyResiduals etc.)"}
+  C3 -->|"no"| F3["FAIL (list non-zero counters)"]
+  C3 -->|"yes"| C4{"fullCutoverEligible == true?"}
+  C4 -->|"no"| F4["FAIL"]
+  C4 -->|"yes"| P1["PASS (full cutover ready)"]
+```
+
+`--full-cutover` is the final acceptance criteria for migration completion: all 8 conditions
+must be satisfied to pass.
+
+---
+
+## Part 3 — Capability Registry
+
+### Level 1 — Capability dependency graph
+
+```mermaid
+flowchart TD
+  Core["core\n(required, foundation for all other capabilities)"]
+
+  Core --> ModParallel["module-parallel\nModule registry + parallel work"]
+  Core --> AdvReview["adversarial-review\nAdversarial review reports\n(alias: review-contract)"]
+  Core --> LongRunning["long-running-task\nLong-running task contracts"]
+  Core --> Dashboard["dashboard\nLocal HTML Dashboard"]
+  Core --> SafeAdoption["safe-adoption\nSmooth onboarding for legacy projects"]
+
+  ModParallel --> SubagentWorker["subagent-worker\nCommit-backed worker handoff protocol"]
+```
+
+### Level 2 — selectWhen for each capability
+
+| Capability | When to enable |
+| --- | --- |
+| `core` | Always — this is the required foundation |
+| `module-parallel` | When the project has 2+ independent modules needing parallel ownership |
+| `subagent-worker` | When code-change subagents need to work in isolated worktrees and commit handoffs |
+| `adversarial-review` | When release, architecture, security, data, or policy risks require independent review artifacts |
+| `long-running-task` | When Agents may run across multiple loops without per-step user confirmation |
+| `dashboard` | When local read-only state visualization is needed |
+| `safe-adoption` | When onboarding v1.0 into an existing harness project without rewriting history |
+
+### Level 2 — Preset resource declarations (resources)
+
+Presets can declare three types of resources. These are auto-generated at task creation
+time and validated by the checker:
+
+| Resource type | Meaning | Validation |
+| --- | --- | --- |
+| `resources.references` | Reference files provided by the Preset | File exists + indexed in `references/INDEX.md` + required reads declared in `task_plan.md` |
+| `resources.artifacts` | Artifacts generated by the Preset | File exists + indexed in `artifacts/INDEX.md` |
+| `context.requiredReads` | Reference file IDs that must be read | Recorded in both indexes |
+
+This is a **three-layer validation chain**: file exists → indexed in index table →
+required reads declared in task_plan.md. Any missing layer produces a failure.
+
+---
+
+## Part 4 — Design decisions
+
+### Why Presets weren't there from the start
+
+The Preset system evolved from the need "migrating legacy projects is too complex". Initially
+there was only `new-task --budget complex` with no Preset concept. When users raised the
+legacy project migration need, the initial proposal was to invent a new "Ultra" task level.
+
+Research found the problem wasn't that Complex was insufficient — it was "without Presets,
+every Agent has to figure out how to structure the migration process from scratch". Three
+independent subagent adversarial reviews all pointed to the same conclusion: Preset is the
+right abstraction, Ultra is over-engineering.
+
+Reasons for rejecting Ultra:
+1. Ultra would introduce a second task system, breaking the consistency of simple/standard/complex
+2. The root cause wasn't that Complex couldn't handle it, but that there was no pre-filled scaffold
+3. Preset is a general abstraction, not just for migration — any type of task can have its own Preset
+
+### Why Preset manifests use YAML
+
+YAML was chosen for readability — Preset manifests need to be written and reviewed by humans,
+and YAML has fewer quotes and brackets than JSON. A lightweight custom parser (`parseSimpleYaml()`)
+was written instead of introducing `js-yaml` to maintain zero dependencies. JS format was
+ruled out because Presets need to be cross-tool auditable and can't be executable code.
+
+### Why layered discovery (project/user/builtin)
+
+Layered discovery was introduced two days after the Preset system itself. Initially it only
+read from the package's fixed `presets/` path. The core problem layered design solves:
+- Different projects can have their own private Presets (project layer)
+- Users can install Presets shared across projects (user layer)
+- Package bundled Presets serve as fallback, usable without installation (builtin layer)
+
+Priority order (project > user > builtin) ensures project-level customization can override
+global defaults.
+
+### Why migration is split into three phases instead of one step
+
+The core consideration is "can't auto-migrate" — Presets only scaffold structure, they don't
+automatically modify historical docs, auto-stage, or auto-commit. Before actually writing to
+the target repo, users still need to confirm the write scope and migration depth.
+
+- `migrate-plan`: read-only analysis, no side effects
+- `migrate-run`: write execution, requires user confirmation
+- `migrate-verify`: post-hoc verification, confirms migration results
+
+Three separate steps give users a confirmation opportunity at every node with side effects.
+
+### Why full-cutover verification is so strict
+
+`full-cutover` is an irreversible declaration — once migration is declared complete,
+subsequent Agents won't treat this project as a migration target anymore. A more lenient
+approach (only checking strict pass) was rejected because real-world project validation
+(471 tasks) proved that even with a strict pass, weak briefs or legacy-only visual maps
+could still remain.
+
+### writeScopes security boundary
+
+writeScopes and the Preset system were introduced simultaneously — it wasn't a security
+hardening added later. Presets are third-party installable packages, and without write
+scope restrictions, a malicious or buggy Preset could overwrite arbitrary files. The
+runtime enforces path checks, rejecting paths starting with `../` and absolute paths
+(path traversal protection).

package/docs-release/architecture/system-explainer/en-US/README.md

@@ -0,0 +1,70 @@
+# Coding Agent Harness — Architecture Explainer
+
+This set of documents helps you understand the system architecture of `coding-agent-harness`.
+Whether you want to contribute code, integrate it into your own project, or just figure out
+"how does this thing actually work" — this is the best place to start.
+
+Each document uses a **top-down, layer-by-layer** approach: it gives you a big picture first
+to build an overall mental model, then dives into each module. You can stop at any layer —
+you don't need to read every detail.
+
+---
+
+## Why these docs exist
+
+The `coding-agent-harness` codebase itself isn't complex, but its **design intent** isn't
+easy to read directly from the code.
+
+For example:
+- Why is state stored in Markdown files instead of a database?
+- Why are there three check profiles instead of one?
+- What's the difference between `governance-sync` and `governance rebuild`, and why are they separate?
+- Why must `review-confirm` be a manual operation — why can't it be automated?
+
+The answers to these questions are scattered across design decisions, historical evolution,
+and operating standards. These docs bring them together so you can understand the system's
+"why" without digging through git log.
+
+---
+
+## Reading order
+
+Reading in order works best, about 15-25 minutes per doc:
+
+| File | Topic | What you'll understand |
+| --- | --- | --- |
+| [01-system-overview.md](01-system-overview.md) | System overview | What this is, what problem it solves, what the four main blocks do |
+| [02-module-dependency.md](02-module-dependency.md) | Code modules | How the CLI dispatches, how the 30+ modules in lib/ are layered, dependency relationships |
+| [03-task-lifecycle.md](03-task-lifecycle.md) | Task lifecycle | The full flow of a task from creation to closeout, gates, and the queue system |
+| [04-check-and-governance.md](04-check-and-governance.md) | Check system | Three profiles, what each of the 9 validators checks, how governance indexes are rebuilt |
+| [05-data-flow.md](05-data-flow.md) | Data flow | How Markdown files become a Dashboard, the boundary between two generation modes |
+| [06-preset-and-migration.md](06-preset-and-migration.md) | Preset and migration | Preset package structure and entrypoint type system, three phases of legacy project migration |
+
+---
+
+## Document conventions
+
+Each file uses `Level 0 / 1 / 2 / 3` to mark depth:
+
+- **Level 0**: Highest level, 3-5 big blocks, builds overall understanding (required reading)
+- **Level 1**: Expands the blocks, shows sub-modules (recommended)
+- **Level 2**: Dives into sub-modules, explains internal logic (read as needed)
+- **Level 3**: Most detailed, function-level flows (reference use)
+
+You can stop at Level 1 and go deeper only when you need to.
+
+---
+
+## Quick lookup
+
+If you have a specific question, jump directly to the relevant file:
+
+| I want to know… | Go to |
+| --- | --- |
+| What problem this system solves | [01 — System overview](01-system-overview.md) |
+| What `harness check` validates | [04 — Check system](04-check-and-governance.md) |
+| What a task's `review` state means | [03 — Task lifecycle](03-task-lifecycle.md) |
+| Where Dashboard data comes from | [05 — Data flow](05-data-flow.md) |
+| How to write a Preset | [06 — Preset and migration](06-preset-and-migration.md) |
+| What a module in the code does | [02 — Code modules](02-module-dependency.md) |
+| How to migrate a legacy project | [06 — Preset and migration](06-preset-and-migration.md) |