@deepseek-insight/dsi 0.5.18 → 0.5.20

package/.agents/skills/dsi-spec/references/mermaid-pattern.md

@@ -0,0 +1,160 @@
+# Mermaid Diagram Pattern — Syntax, Accessibility & Error Prevention
+
+Shared reference for ai-research and yt-research skills. Both skills produce Obsidian pages with mermaid diagrams. This file defines the rules for writing diagrams that render correctly and meet accessibility standards.
+
+---
+
+## ⛔ When Is a Sequence Diagram Required?
+
+A `sequenceDiagram` is **conditionally mandatory** — only when the content involves actors with message flows.
+
+### Decision Rule
+
+Ask: **Does this topic involve who-talks-to-whom?**
+
+| Yes → Sequence Diagram REQUIRED | No → Single Diagram SUFFICES |
+|---|---|
+| Systems communicating (API calls, service-to-service) | Purely conceptual or statistical content |
+| Agents interacting (user → tool → AI → output) | Historical timelines without actor messaging |
+| Process flows between distinct participants | Comparison tables, feature lists |
+| Request/response patterns | Taxonomy or hierarchy (use mindmap instead) |
+
+**If no actors exist, do NOT force a sequence diagram.** A mindmap or flowchart alone is sufficient.
+
+### Mandatory Diagram Minimum
+
+Every research page MUST include at least:
+1. **One mindmap** (for conceptual frameworks or topic hierarchies) — MANDATORY
+2. **One sequence diagram** — ONLY IF actors with message flows exist in the content
+3. **Additional diagrams** (flowchart, timeline) — optional, based on content
+
+---
+
+## Syntax Rules — Avoiding Parse Errors
+
+### Sequence Diagram Rules
+
+| Rule | ❌ Breaks | ✅ Correct |
+|---|---|---|
+| No `style` directives | `style A fill:#4a90d9` inside sequenceDiagram → **PARSE ERROR** | Omit all styling from sequence diagrams. Mermaid does not support `style` in sequence context. |
+| No `#` in message text | `A->>B: Skill #1 activates` → **PARSE ERROR** (treated as comment) | `A->>B: Skill 1 activates` |
+| No raw `>` in messages | `A->>B: Source > Filters > Output` → **PARSE ERROR** (parsed as arrow) | `A->>B: Source to Filters to Output` |
+| No `/` in messages (sometimes) | `A->>B: saved to docs/` → may break in some renderers | `A->>B: saved to docs folder` |
+| No parentheses in messages (sometimes) | `A->>B: Verdict (Ship it)` → may break | `A->>B: Verdict — Ship it or Fix` |
+| Commas in `Note over` are delimiters | `Note over A,B: Phase 1` → correct (comma separates participants) | Fine — this is valid syntax |
+| Colons inside message text | `A->>B: Time: 12:00` → **PARSE ERROR** (colon ends the message) | `A->>B: Time is 12h00` |
+| Apostrophes in messages | `A->>B: What's the question?` → may break | `A->>B: What is the question?` |
+
+### Flowchart Rules
+
+| Rule | ❌ Breaks | ✅ Correct |
+|---|---|---|
+| `#` inside node labels | `A["Skill #1"]` → may break | `A["Skill 1"]` |
+| `&` multi-target syntax | `D2 & D3 & D4 --> E` → breaks in some renderers | Separate arrow per node: `D2 --> E` then `D3 --> E` etc. |
+| `style` IS valid in flowcharts | `style A fill:#4a90d9,color:#fff` → **works correctly** | Use freely in flowchart blocks. |
+| `<br/>` for line breaks in nodes | `A["Line 1\nLine 2"]` → may not render | `A["Line 1<br/>Line 2"]` |
+| Curlyly braces for decision nodes | `E{"Verdict?"}` → correct | Fine — this is valid syntax |
+| Pipe in labels | `A["a|b"]` → may break (pipe is graph syntax) | `A["a or b"]` |
+
+### Mindmap Rules
+
+| Rule | ❌ Breaks | ✅ Correct |
+|---|---|---|
+| No special chars in node text | `→`, `-`, `:`, `&`, `"` → **PARSE ERROR** | Use commas, spaces, `and` |
+| No parentheses in nodes | `root((Topic (2026)))` → may break | `root((Topic 2026))` |
+| No colons in nodes | `Key: Finding` → **PARSE ERROR** | `Key Finding` or `Key, Finding` |
+| No ampersands | `R&D` → breaks | `R and D` |
+
+### General Mermaid Rules (All Diagram Types)
+
+| Rule | Why |
+|---|---|
+| Always close code fences with ` ``` ` on its own line | Unclosed fences break the entire page |
+| Use `autonumber` as first line in sequence diagrams | Adds step numbers for accessibility and reference |
+| Keep participant aliases short (2-3 chars) | `participant SK as Stakeholder` not `participant StakeholderWithLongName as Stakeholder` |
+| Test in Obsidian before declaring pipeline complete | Mermaid version differences across Obsidian/validate |
+
+---
+
+## Accessibility — Color Contrast (WCAG AA)
+
+### Approved Color Palette
+
+All colors meet WCAG AA contrast ratio (≥ 4.5:1) with white text (`color:#fff`):
+
+| Color | Hex | Use Case | Contrast vs White |
+|---|---|---|---|
+| Blue | `#4a90d9` | Entry/starting nodes, first phase | 4.57:1 ✅ |
+| Orange | `#e67e22` | Process/skill activation | 4.80:1 ✅ |
+| Green | `#27ae60` | Positive/feasible outcomes | 4.51:1 ✅ |
+| Light Green | `#2ecc71` | Success confirmation | 3.27:1 ⚠️ (use only for large nodes) |
+| Red | `#e74c3c` | Warnings, blocks, hard walls | 5.02:1 ✅ |
+| Purple | `#9b59b6` | Analysis/output phases | 4.04:1 ⚠️ (borderline — use sparingly) |
+| Dark Blue | `#2c3e50` | Terminal/done nodes | 13.84:1 ✅ |
+| Amber | `#f39c12` | Conditional/warning outcomes | 4.07:1 ⚠️ (borderline) |
+| Gray | `#95a5a6` | Passive participants (codebase, files) | 2.63:1 ❌ (use `#7f8c8d` instead, 4.31:1) |
+
+### Where Colors Apply
+
+- **Flowcharts:** Use `style` directives freely. Always pair `fill` with `color:#fff`.
+- **Sequence diagrams:** CANNOT use `style`. Colors are NOT applicable — rely on clear participant naming and `autonumber` instead.
+- **Mindmaps:** CANNOT use `style`. Use node text clarity for differentiation.
+
+### Approved Pattern (Flowchart Only)
+
+```mermaid
+flowchart TD
+    A["Start"] --> B["Process"]
+    B --> C["Decision"]
+    C -->|Yes| D["Done"]
+    C -->|No| B
+
+    style A fill:#4a90d9,color:#fff
+    style B fill:#e67e22,color:#fff
+    style C fill:#f39c12,color:#fff
+    style D fill:#27ae60,color:#fff
+```
+
+### Anti-Patterns
+
+- ❌ `style A fill:#ffe066,color:#333` — yellow with dark text looks fine but fails in dark mode Obsidian
+- ❌ `style A fill:#e74c3c` — red fill without specifying `color:#fff` defaults to dark text on red (fails contrast)
+- ❌ Using colors inside sequence diagrams — Mermaid does not support this and will error
+- ❌ Using more than 5-6 distinct colors — creates cognitive overload, not accessibility
+
+---
+
+## Pre-Save Mermaid Checklist
+
+Before saving any Obsidian page, verify each diagram:
+
+```
+📋 Mermaid Checklist
+
+   [ ]  1. Code fence: opens with ```mermaid AND closes with ``` on separate line
+   [ ]  2. No `style` directives in sequenceDiagram blocks
+   [ ]  3. No `#` characters inside any mermaid block (use spaces or numbers)
+   [ ]  4. No raw `>` in message text (use "to" or "→" spelled out)
+   [ ]  5. No colons inside sequence message text after the label colon
+   [ ]  6. No `&` multi-target in flowchart arrows (use separate arrows)
+   [ ]  7. No special chars in mindmap nodes (→, -, :, &, ", parens)
+   [ ]  8. All flowchart `style` directives include both `fill` AND `color:#fff`
+   [ ]  9. Colors from approved palette only (WCAG AA compliant)
+   [ ] 10. Sequence diagrams use `autonumber` as first line
+   [ ] 11. At least 1 mindmap present (MANDATORY for all pages)
+   [ ] 12. Sequence diagram ONLY if actors with message flows exist
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Common Errors and Fixes
+
+| Error Message | Likely Cause | Fix |
+|---|---|---|
+| `Parse error... Expecting 'NEWLINE'` | `style` inside sequenceDiagram | Remove all `style` lines from sequence blocks |
+| `Parse error... got 'INVALID'` | Special char (`#`, `>`, `:`) in message text | Replace with plain text equivalent |
+| Diagram shows as empty rectangle | Unclosed code fence | Ensure ` ``` ` on its own line closes the block |
+| Node text disappears | `#` or `|` inside `["..."]` label | Remove `#`, replace `|` with `or` |
+| Mindmap shows broken layout | Special chars in node text | Use only letters, numbers, commas, spaces |
+| Flowchart arrows missing | `&` multi-target syntax | Use separate arrow lines for each target |

package/.agents/skills/dsi-spec/references/tasks-json-template.md

@@ -0,0 +1,125 @@
+# Tasks.json Template — The Machine Twin Contract
+
+Binding template for the `Tasks.json` file that ships beside every `Tasks.md`. The orchestration registration flow (`POST /api/orchestration/features`) maps these keys one-to-one into SQLite rows. If the JSON is missing, malformed, or contradicts the Markdown, **registration fails loudly at the door** — it never inserts half a feature.
+
+This file is the single source of truth for the JSON shape. When the orchestration schema changes, this file changes with it.
+
+---
+
+## The Shape
+
+```json
+{
+  "$schema": "openclaw-insight/tasks-twin/v1",
+  "featureName": "Orchestration Zoom Artifact Fix",
+  "featureSlug": "orchestration-zoom-artifact-fix",
+  "specPath": "dev/specs/2026-08-15 - Orchestration Zoom Artifact Fix",
+  "waves": [
+    {
+      "waveNumber": 1,
+      "name": "Geometry Fix + Unit Tests",
+      "tasks": [
+        {
+          "taskNumber": "1.1",
+          "title": "PanelsContainer viewport wrapper",
+          "description": "Wrap the .columns div in a .panels-viewport div...",
+          "assignedAgent": "app-dev",
+          "filesInvolved": ["src/lib/components/orchestration/PanelsContainer.svelte"],
+          "dependsOn": null
+        },
+        {
+          "taskNumber": "1.1-T",
+          "title": "Unit tests (PAIRED with 1.1)",
+          "description": "Host-pattern tests for the viewport wrapper...",
+          "assignedAgent": "app-dev",
+          "filesInvolved": ["tests/lib/components/orchestration/panels-container.test.ts"],
+          "dependsOn": "1.1"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Field Rules
+
+| Field | Type | Rule |
+|---|---|---|
+| `$schema` | string | **Required.** Literal `openclaw-insight/tasks-twin/v1` |
+| `featureName` | string | **Required.** Display name |
+| `featureSlug` | string | **Required.** Lowercase-hyphen ID. MUST equal the slug derived from the folder name (strip date prefix, lowercase, collapse spaces/hyphens, strip non-alphanumeric, trim hyphens — `deriveFeatureSlug`) |
+| `specPath` | string | **Required.** The spec folder path used at registration |
+| `waves[]` | array | **Required, at least 1 entry**, ordered by `waveNumber` |
+| `waves[].waveNumber` | integer | **Required.** Sequential from 1 |
+| `waves[].name` | string | **Required.** Human wave title |
+| `waves[].tasks[]` | array | **Required, at least 1 task per wave** — an empty wave is a spec bug |
+| `tasks[].taskNumber` | string | **Required.** Unique within the feature. Digits, dots, optional `-T` or letter suffix (`1.1`, `1.1-T`, `1.2a`) |
+| `tasks[].title` | string | **Required.** Non-empty |
+| `tasks[].description` | string | **Required.** Trimmed task body (Markdown allowed) |
+| `tasks[].assignedAgent` | string | Optional, default `app-dev`. Agent ID the start endpoint builds the session key for |
+| `tasks[].filesInvolved` | array of string or null | Optional. File paths touched by the task |
+| `tasks[].dependsOn` | string or null | Optional. A `taskNumber` in the same feature — never a wave-scoped ID |
+
+**Meta properties are forbidden.** No `phase`, `status`, `priority`, `notes`, or any other key. Status and runtime columns are owned by the database after insertion — spec files describe intent, the DB owns state.
+
+## JSON → SQLite Field Map
+
+Registration is a key-for-key copy. Nothing is inferred, guessed, or re-derived from prose.
+
+| Tasks.json key | SQLite column | Table |
+|---|---|---|
+| `featureSlug` | `id` | `features` |
+| `featureName` | `name` | `features` |
+| `specPath` | `spec_path` | `features` |
+| — (insert literal) | `status` = `'ready'` | `features` |
+| `waves[].waveNumber` | `wave_number` | `waves` |
+| `waves[].name` | `name` | `waves` |
+| — (insert literal) | `status` = `'ready'` | `waves` |
+| `tasks[].taskNumber` | `task_number` | `tasks` |
+| `tasks[].title` | `title` | `tasks` |
+| `tasks[].description` | `description` | `tasks` |
+| `tasks[].assignedAgent` | `assigned_agent` | `tasks` |
+| `tasks[].filesInvolved` | `files_involved` (joined with `,`) | `tasks` |
+| `tasks[].dependsOn` | `depends_on` | `tasks` |
+| — (insert literal) | `status` = `'ready'` | `tasks` |
+
+Composite IDs are built by the endpoint, not the spec: feature `id`, wave `{featureId}:w{n}`, task `{featureId}:w{n}:t{number with . and - replaced by _}`.
+
+## Validation at the Door
+
+| Constraint | Rejection |
+|---|---|
+| `$schema` missing or unknown | 400 |
+| Zero waves | 400 |
+| Any wave with zero tasks | 400 |
+| Zero tasks across the whole spec | 400 |
+| Duplicate `taskNumber` within feature | 400 |
+| `dependsOn` pointing at a missing `taskNumber` | 400 |
+| `featureSlug` differs from folder-name slug | 400 |
+| Feature slug already registered | 409 |
+
+## Registration Flow
+
+```mermaid
+flowchart TD
+    A["POST /features<br/>with folderPath"] --> B{"Tasks.json<br/>present?"}
+    B -->|No| X1["400 — machine twin missing"]
+    B -->|Yes| C{"$schema is<br/>tasks-twin/v1?"}
+    C -->|No| X2["400 — unknown schema"]
+    C -->|Yes| D["Validate field rules<br/>waves, tasks, slug, deps"]
+    D -->|fail| X3["400 — with rule name"]
+    D -->|pass| E["Insert feature row<br/>keys map 1 to 1"]
+    E --> F["Insert wave rows"]
+    F --> G["Insert task rows<br/>dependsOn resolved"]
+    G --> H["201 — counts plus feature id"]
+
+    style A fill:#4a90d9,color:#fff
+    style H fill:#27ae60,color:#fff
+    style X1 fill:#e74c3c,color:#fff
+    style X2 fill:#e74c3c,color:#fff
+    style X3 fill:#e74c3c,color:#fff
+```
+
+## Why the slug MUST match the folder name
+
+The registration identity is **the folder name**, and the feature slug is derived from it (`deriveFeatureSlug`). If `Tasks.json.featureSlug` disagrees with the folder-derived slug, the same spec would register under two identities (and one would never be re-registrable). Registration rejects the mismatch with 400 — one folder, one identity.

package/.agents/skills/dsi-task/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: "dsi-task"
+description: "Execute implementation tasks from a Karpathy context file and tasks document. Applies Visible Checklist Pattern, Playwright regression gates, and sub-agent comp"
+---
+
+# Task Executor
+
+Execute implementation tasks defined in a Karpathy context + tasks document.
+
+## SYSTEM PROTOCOL: STRUCTURED IMPLEMENTATION & LAYERING
+
+You must treat code generation as a spatial and structural architecture task, not just functional text completion. Your code layout must mirror the logical boundaries defined in the system design/sequence diagrams:
+
+### 1. DIRECTORY SANCTITY & ENCAPSULATION
+- Every domain or feature subset must reside within its own completely isolated directory.
+- Cross-module code bleeding is strictly prohibited. All module-specific state and logic must remain local to that module's folder.
+- Before creating any file, verify its target directory exists and aligns with the Module Map from the PRD.
+
+### 2. DECOUPLED COMMUNICATION MECHANISM
+- You are forbidden from hardcoding direct dependencies or side-effects between feature modules.
+- Execution orchestration must follow the project's communication pattern (event bus, pub/sub, middleware chain, dependency injection, message passing, etc.). Modules requiring observation or intervention must use the defined communication layer, not direct imports.
+- Document how each module connects to the system: what it receives, what it produces, and through which channel.
+
+### 3. ARCHITECTURAL DRY PRINCIPLE
+- Before implementing any utility logic (e.g., file checks, payload validation, format verifiers), check the global Shared Layer.
+- You must import shared utilities from the central shared directory rather than re-creating localized or redundant helper functions inside individual modules.
+
+### Enforcement Rules
+- Before writing code for any wave, verify the PRD's Module Map against the physical filesystem (`find | sort`)
+- Every new file must be created in its designated module directory — never in the root or another module's folder
+- Shared utilities must be placed in the designated shared directory and imported via relative paths — never duplicated
+- After each wave, run a "cross-module bleed check": verify no module imports from another module's directory
+- Module wiring (how modules connect to each other) must happen at the defined integration point — not scattered across module internals
+
+---
+
+## When to Use
+
+- User says `/execute-tasks {project-path}` — execute with project root (auto-discovers docs)
+- User says "execute the WebSocket tasks" or "implement the tasks from the Karpathy-context"
+- User provides a `{*} karpathy-context.md` file and asks to start implementation
+
+### Step 0: No Params — Usage Guide
+
+When the user sends `/execute-tasks` with no arguments:
+
+1. Ask for the two required paths:
+   - **Karpathy context** — path to the karpathy-context file (auto-discovered from project path)
+   - **Tasks document** — path to the tasks document (local file under project dev/)
+2. Reply with a usage guide — NOT execution
+
+**Response format:**
+
+```
+📋 **Task Executor** — No paths specified. I need two things:
+
+1. **Project path** — the codebase root (where dev/specs/ lives)
+   Example: `~/openclaw-insight`
+
+2. **Tasks document** — the implementation tasks (auto-resolved from project path)
+   Example: `openclaw-insight/dev/specs/WebSocket Real-Time/Tasks.md`
+
+Usage: `/execute-tasks {project-path}`
+
+Or just paste the project path and I'll find the latest tasks document.
+```
+
+**Rules:**
+- If project path is provided, auto-discover feature folder: `{project-path}/dev/specs/*/`
+- If multiple feature folders exist, ask which one to execute
+- If a karpathy-context file exists in `{project-path}/dev/specs/{feature}/`, load it automatically
+- If no Karpathy context found, ask if the user wants to proceed without it
+- If a path doesn't exist, say so and ask for the correct one
+- Do NOT proceed to Step 1 (Load Context) until paths are confirmed
+
+## Core Principle: Context Loading, Not Memorization
+
+This skill is intentionally SHORT. It references external documents instead of copying rules inline. This prevents attention degradation — the model loads only what it needs, when it needs it.
+<!-- RCA: AI-Research/YT-Research/2026-06-22 - Why Long Instructions Make AI Dumber - Attention Degradation Science.md -->
+
+---
+
+## Step 1: Load Context — MANDATORY
+
+Before any execution, load exactly these files:
+
+1. **Karpathy context** — `{project-path}/dev/specs/{feature}/karpathy-context.md` (auto-discovered)
+2. **Tasks document** — `{project-path}/dev/specs/{feature}/Tasks.md` (auto-discovered)
+3. **Visible Checklist Pattern** — `ai-research/references/visible-checklist-pattern.md` (loaded on demand)
+4. **Sub-Agent Completion Rules** — `TOOLS.md` lines 85-115
+
+Read these files at the start. Do NOT carry them from previous conversation context — reload fresh.
+
+---
+
+## Step 1.5: Date Resolution ⛔ MANDATORY
+
+Before constructing any date-prefixed filenames during execution, resolve today's date via `date +%Y-%m-%d`. Store as `TODAY`. Do not carry the date from the feature-spec session — it may be a different day.
+<!-- RCA: AI-Research/Troubleshooting/2026-06-18 - Wrong Date Prefix in yt-research Filename - RCA.md -->
+
+---
+
+## Step 2: Declare Execution Checklist — MANDATORY
+
+Output a checklist of ALL tasks for the current wave, INCLUDING the behavioral commitments. The user MUST see every rule I'm committing to follow.
+
+```
+📋 Execution: {project-name} — {wave name}
+
+   [ ]  1.5 ⛔ Resolve today's date via `date +%Y-%m-%d` (store as TODAY)
+   [ ]  2.1  {task 1 name}
+   [ ]  2.2  {task 2 name}
+   [ ]  2.3  {task 3 name}
+
+   ⛔ Behavioral Commitments (user can verify):
+   [ ]  I will NOT execute multiple waves without your confirmation
+   [ ]  I will NOT skip Playwright regression gate
+   [ ]  I will NOT rely on completion events as ground truth
+   [ ]  I will NOT post NO_REPLY after spawning sub-agents
+   [ ]  I will NOT self-certify completion without running verify commands
+   [ ]  I will NOT reload this skill + all referenced docs simultaneously
+   [ ]  I will NOT bleed code across module boundaries
+   [ ]  I will NOT duplicate shared utilities in module directories
+   [ ]  I will run unit tests after EACH code-writing task (not batched at end)
+   [ ]  I will re-output this checklist after each task completes
+
+   ⛔ Sub-Agent Safety (conditional — ⊘ skip if no sub-agents spawned):
+   [⊘]  Check ALL children via subagents list — not just one
+   [⊘]  Disk files = ground truth, events = convenience
+   [⊘]  Post ACK to user before other work
+
+   ⛔ Completion Gate:
+   [ ]  All task files exist on disk (verified via find)
+   [ ]  Directory structure matches PRD Module Map (verified via find | sort)
+   [ ]  No cross-module import violations (verified via grep)
+   [ ]  Unit tests pass (npx node --test or npm test) — MANDATORY, not optional
+   [ ]  Type-check zero new errors: if `npm run check` exits non-zero from pre-existing errors, grep output for this wave's exact new file paths — 0 hits satisfies the gate ONLY when the error count also matches the wave-start check counts. When the wave adds or changes a field on a shared type (interface/type alias), pre-existing object-literal fixtures typed as that interface break in files outside the wave list: the wave-file grep returns 0 hits while the count rises, so adjudicate every count delta by listing diagnostics per file (`--output machine`); errors naming the changed type are this wave's lockstep obligation — extend the fixture in-wave; prove the rest pre-existing via `git log --oneline -- <file>` (last-touch commit predates the wave) plus empty `git diff --stat HEAD -- <file>`. The same git-log proof settles a hit in a different file sharing a name substring; fall back to `git stash` → re-run check → confirm same hit on clean baseline → `git stash pop` only when history is ambiguous. Never judge by raw error-count deltas against a `git stash -u` baseline: `-u` also stashes new untracked test files, and the fix itself may resolve pre-existing errors — current < baseline is normal and proves nothing. A stash baseline only adjudicates files tracked in both states: plain `git stash` leaves this wave's untracked new files in the worktree, so they compile against the reverted tracked code and the baseline sprouts phantom errors in this wave's own files (e.g. missing-export errors the stash itself created) — classify those baseline hits as stash artifacts and settle them by grepping the intact worktree instead
+<!-- RCA: 2026-08-16 openclaw-insight ControlRail Wave 1 — adding required `deleted_at` to the shared Feature interface broke the untouched wave-prompt.test.ts fixture; wave-file grep said 0 hits while 26e→27e. Delta adjudication via machine diagnostics fixed the lockstep fixture in-wave; git-log + empty-diff proved the sibling sessionKey/TaskData errors pre-existing. -->
+   [ ]  Playwright regression: zero failures vs baseline ⊘ (skip if no Playwright)
+   [ ]  User acknowledged completion
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Check off each item as it completes: `[✅]` done, `[🔄]` current, `[ ]` remaining.
+
+### Check-Off Rules
+
+- **After each task completes within a wave**, re-output the full wave checklist with updated statuses
+- **At wave completion**, output the final checklist: ALL `[✅]`, any `[❌]` for failures, any `[⊘]` for skipped conditionals
+- **Do NOT deliver without showing the final checklist**
+<!-- RCA: AI-Research/LLMs Skip Mandatory Steps/001. LLMs Skip Mandatory Steps/002.The Visible checklist Pattern/2026-06-11 - The Visible Checklist Pattern - AI Research v1 - report.md -->
+
+---
+
+## Step 3: Execute Tasks Sequentially
+
+- Execute one task at a time within the current wave
+- Do NOT skip tasks or reorder
+- After each task: verify deliverables exist on disk (`ls`, `find`)
+- **After each code-writing task: run unit tests for the affected module** (`npx node --test dist/{module}/`). Do NOT proceed to the next task if tests fail.
+- If a task spawns a sub-agent: follow Step 4 (Sub-Agent Safety)
+
+### Step 3.5: Acceptance Scenarios Are the Contract ⛔
+
+When verification disagrees with user-stated acceptance scenarios:
+
+1. Treat the scenarios as the contract. Fix the implementation to satisfy them — never rewrite, loop, or weaken the test to match observed behavior.
+2. Follow the promised verification order: fix → headed run of the user's scenarios verbatim (one user action per assertion) → only then unit tests.
+3. When a simulated-DOM unit test (happy-dom/jsdom) fails while the headed real-browser run passes, trust the headed run and fix the harness — poll microtask-driven state with `vi.waitFor` instead of fixed sleeps.
+4. This binds user scenarios only — not edge-case assertions you authored from an assumption. When your own new test fails, verify the assumption against documented platform semantics; a false assumption means correct the assertion, not working code (e.g. Node `basename('dev/specs/')` → `'specs'` — trailing slash stripped, so a "basename empty → fallback" branch never fires for it).
+   <!-- RCA: 2026-08-16 openclaw-insight wave-prompt — fallback test expected the feature id for a trailing-slash spec path; basename semantics proved the assertion wrong; test corrected, implementation untouched, 17/17 green -->
+
+Criterion: every user scenario is asserted verbatim and passes, with no assertion softened to make a run green.
+<!-- RCA: 2026-08-13 openclaw-insight ghost-Backspace — headed test was softened (BS retry loops) to match buggy native-selection deletion; user rejected; keydown-intercept fix + verbatim-scenario headed run passed -->
+
+
+---
+
+### Step 3.6: Expected-Fail Sanity Proofs ⛔
+
+When a wave plans "old bug-spec must FAIL as proof of fix":
+
+1. Run it; if it unexpectedly PASSES, treat that as evidence the spec discriminates nothing — inspect what its assertions measure before drawing any conclusion.
+2. Symptom assertions anchored to the wrong reference (viewport/window instead of the fixed element's own container) pass both pre- and post-fix.
+3. Prove the fix with a reference-relative probe: assert the fixed element's rect against its wrapper rect within ±1px, plus a pixel scan of the artifact region; capture the evidence, then delete the probe spec.
+4. Scrollable wrapper: compare bottom/right edges against `clientHeight`/`clientWidth` — a rendered scrollbar occupies the bounding-rect edge, so a naive rect comparison reports a false gap (scrollbar px = rect height − clientHeight).
+
+Criterion: fix proven by reference-relative geometry (e.g. gap 301.3px → 0.01px), independent of the old spec's pass/fail; wrapper gaps measured client-relative (scrollbar not counted as gap).
+<!-- RCA: 2026-08-16 openclaw-insight zoom-artifact Wave 1 — old visual spec passed pre- AND post-fix because it asserted last-panel edge vs viewport; wrapper-relative probe proved the wrapper fix. Wave 2 — wrapperRect.bottom − childRect.bottom reported a false 15px gap: the h-scrollbar occupied the rect bottom while .columns exactly filled clientHeight -->
+
+
+---
+
+### Step 3.7: Deletion-Only Tasks — Zero-Reference Verification
+
+When a task deletes a file and its paired verification is "grep returns zero references":
+
+1. Confirm the deletion at three levels: absent from worktree (`ls`), untracked (`git ls-files <path>` empty), recorded in history (`git log --oneline --diff-filter=D -- <path>`).
+2. If the deletion already exists in a prior commit, verify and report — do not redo it.
+3. Run the prescribed grep over the full worktree, then classify every hit:
+   - code/config references (src, tests, configs, scripts) — the only hits that fail the gate
+   - spec-folder and ADR docs recording the retirement decision — intentional audit trail, keep
+   - gitignored runtime logs — not repo content
+4. Keep the audit-trail doc hits: the gate is zero code references, not a literal zero; scrubbing the spec's own record falsifies history.
+5. Before concluding, confirm similarly-named sibling files are unrelated, not misnamed leftovers.
+
+Criterion: filtered grep (docs + ignored dirs excluded) returns zero hits, with the hit classification stated in the task summary.
+<!-- RCA: 2026-08-16 openclaw-insight zoom-artifact Task 2.2-T — grep for deleted zz-zoom-artifact-headed.spec.ts returned 16 hits: ADR retirement table + spec-folder audit trail + gitignored logs/; zero-code-reference criterion satisfied without touching the retirement record, and zz-backspace-headed.spec.ts confirmed unrelated -->
+
+### Step 3.8: New E2E Specs — Assert the Component's Real DOM Contract
+
+When a wave adds a Playwright spec against existing UI:
+
+1. Read the target component source BEFORE writing selectors. Svelte classnames are hash-suffixed or absent; icon-only badges carry status only in `aria-label`. Select via `role`/`aria-label`/testid found in the source, never guessed classes.
+2. On a red run, read `test-results/<spec>/error-context.md` FIRST — its page snapshot shows the actual rendered tree and reveals state such as a collapsed accordion hiding the badges you assert on; expand each nesting level (feature card, then wave toggle) before asserting inside it.
+3. When a setup step fails on pointer interception and its UI is already covered by a sibling spec, drive the mocked API directly (`page.evaluate(() => fetch(...))`) — the setup is a means, not the subject.
+
+Criterion: every selector is verified present in component source, and red runs are diagnosed from the error-context snapshot before the assertion is touched.
+<!-- RCA: 2026-08-16 openclaw-insight wave-dispatch e2e — three red runs, all test-side: guessed `.task-completed` classes (StatusBadge is icon-only; real contract `[role="status"][aria-label="Completed"]`), register-popover click intercepted by panels-viewport (moved to mocked API; popover covered by orchestration-register.spec.ts), collapsed wave accordion hid task badges (added wave-toggle click). No production change, no softened assertions; 3 consecutive green runs after. -->
+
+### Step 3.9: Tagged Playwright Invocations — Prove Non-Empty Selection
+
+When a gate or spec pins a tag-filtered run (`--grep @tag`):
+
+1. Read the active config for a static `grep:` first — Playwright ANDs config grep with CLI `--grep`, and a static entry cannot be overridden from the CLI. An exclusion grep in config plus a tag grep on CLI silently selects ZERO tests: exit 0, green gate, nothing ran.
+2. Before trusting a tagged green run, read the reporter's collected/passed count and confirm it matches the expected suite size. Zero collected = false green.
+3. To diagnose emptiness, race an untagged control file against the tagged file under the same invocation: control collects while the tagged file never collects under `--grep`, `--grep-invert`, or path+grep ⇒ the config grep is the blocker.
+4. Fix additively: a sibling config that spreads the base config and clears ONLY `grep` (default-suite composition stays byte-identical), then invoke with `--config`. Record the working invocation in the completion notes as a documented deviation from the spec-pinned form.
+5. When the fix un-buries suites that have never run, classify every failure stale vs regression before judging the gate: `git log -1 -- <file>` predating the subject plus assertions naming removed UI ⇒ stale; document for owner adjudication and do not rewrite or delete foreign suites in-wave.
+
+Criterion: the tagged invocation reports the expected collected count, and every failure in a newly reachable suite is classified with git-log evidence.
+<!-- RCA: 2026-08-17 openclaw-insight Control Room Recovery W5 — the spec-pinned `--grep @orchestration` had selected zero tests ever since the base config gained its exclusion grep; a sibling config (spread base, clear only grep) un-buried the recovery spec (5/5 green) plus a 2026-08-08 suite asserting the removed pre-redesign page — stale, documented, not rewritten. -->
+
+## Step 4: Sub-Agent Safety — When Spawning Children
+
+Only fires when a task requires spawning a sub-agent. If no sub-agents are spawned, mark `[⊘]` in the checklist and skip this step.
+
+```
+📋 Sub-Agent Safety
+
+   [ ]  4.1  Spawn sub-agent with explicit model + taskName
+   [ ]  4.2  Continue independent work on main session
+   [ ]  4.3  On completion: verify output file on disk (find | wc -l)
+   [ ]  4.4  Post ACK to user before starting next task
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Step 4.5: 2-Minute Ledger Gate ⚠️ MANDATORY
+
+If 2 minutes pass after spawning a sub-agent without any completion event or user message, fire `subagents(action="list")` proactively — do not silently wait.
+<!-- RCA: AI-Research/Troubleshooting/Agentic Pipeline/2026-06-22 - Missing Sub-Agent Completion Event for Gemini but Not Perplexity - RCA 1.md -->
+
+**The rule:**
+1. After spawning, note the spawn timestamp
+2. If 2 minutes pass without a completion event: fire `subagents(action="list")` immediately
+3. Check ALL expected children — not just one
+4. For any child showing "done": verify output file on disk (find | wc -l)
+5. For any child still "running" past 5 minutes: flag as potentially stuck
+
+---
+
+## Step 5: Wave Completion Gate — MANDATORY
+
+Before declaring a wave complete, output the final checklist with ALL items checked.
+
+If any `[ ]` remains: fix it, do NOT proceed to next wave.
+
+If Playwright tests are part of the wave: run `npx playwright test --reporter=list` and show results.
+<!-- RCA: AI-Research/Troubleshooting/2026-06-11 - ADDITIONAL_PAGES Three Generations Same Bug - RCA.md -->
+
+---
+
+## Step 6: Save Completion Artifacts
+
+Save completion notes to the same project docs folder. Use the resolved `TODAY` date from Step 1.5.
+
+Path: `{project-path}/dev/specs/{feature}/{TODAY} - {Wave Name} - Completion Notes.md`
+
+Include: tasks completed, files modified, test results, blockers encountered.
+
+---
+
+## Step 7: Ask Before Next Wave
+
+After completing a wave, ask the user before proceeding to the next wave.
+
+"✅ {Wave N} complete. Ready to start {Wave N+1}? Tasks: {brief list}"

package/README.md

@@ -1,6 +1,9 @@
 # DeepSeek Insight
 
-DeepSeek Insight (DSI) is the insight layer and conversation surface for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`). And because reading is only half of developer experience, it also gives you a place to **talk back**: a conversation page that speaks the harness's own wire protocol.
+- `DSH web` shows you a conversation. 
+- [DeepSeek Insight](https://gitlab.com/wharsojo.dev/deepseek-insight) (DSI) shows you the **whole floor**
+
+> `DSI` as a `Control room` built on your harness's own records: every session, past and running, side by side on one page; lineage tree of sub-agents pinned under the parent that spawned them; every tool call with its pass/fail receipt; history you can search; prompts worth keeping filed for reuse. It speaks the same wire as the `DSH` you already run — nothing new to configure.
 
 ## Run
 
@@ -12,10 +15,10 @@ The whole DX loop lives in the home page: pick a preset + workspace, press **+ N
 Everything on the page is **real harness activity**, not a mock — every chip, diff, and reply is read straight from the running harness.
 
 - **Conversation, with receipts.** Each tool the agent runs shows as a chip that passes or fails, with its duration and its receipt; open it to see exactly what ran. Reasoning folds away until you want it, and long sessions load older turns as you scroll up.
-- **One-click approvals.** When the agent asks permission — run this command, edit that file — an approval card appears in the flow; answer it right there, no tab-switching.
 - **The workspace explorer, with git diff.** A side panel shows the files your agent is touching. Changed files are flagged and pulsing while the agent works; click one and you get a **real git diff** — additions in green, removals in red — rendered from the file's live buffer, so it updates as the agent edits and refreshes if you (or anything else) change the file underneath.
 - **Presets and workspaces.** Start each chat with the right agent for the job — a coder, a researcher, a generalist — pointed at the right folder.
 - **Many conversations, one page.** Conversations live in panels you can open side by side; compare two runs, or keep a scratch chat next to the main one.
+- **A family tree under every chat.** When your agent spawns sub-agents, they appear as their own panels **below the parent that made them** — a ghost-tinted panel that stays put on refresh, so you always know who was working for whom. And when one conversation is worth a second try, **fork it**: one click clones the loaded context into a fresh session that starts exactly where the original stood — same history, new task.
 - **A prompt library that files itself.** Save any bubble into the library and give it short filing words (tags) at save time; filter the prompt manager by tag chips or `+tag` words in the search box, and narrow the suggestion strip with its own tag chips — filters survive a reload. Tune the offered tags in `~/.dsi/settings.yaml` under `prompts.tags`.
 - **Your language.** The interface speaks English, Chinese, and Indonesian.
 
@@ -40,27 +43,6 @@ npx @deepseek-insight/dsi@latest dsh --sync
 
 When it is up, your browser opens the page by itself (default `http://127.0.0.1:5174`). Run it again later and DSI even cleans up after a lost previous run: `dsi dsh --sync-kills`.
 
-### Run from source
-
-```sh
-git clone git@gitlab.com:wharsojo.dev/deepseek-insight.git
-cd deepseek-insight
-pnpm install
-pnpm run build
-pnpm dsi dsh --sync
-```
-
-Hacking on DSI itself? `pnpm dsi dsh --sync --dev` serves the Vite dev server (hot reload) instead of the build, and the usual gates apply:
-
-```sh
-pnpm check                       # svelte-check, 0 errors
-pnpm test                        # unit tests (the live wire spike skips cleanly without DSH_LIVE)
-npx playwright test              # e2e on a stubbed DSH wire — no harness needed
-DSH_LIVE=1 pnpm run test:live    # only with `dsh web` running on :3080
-```
-
-The deeper story — architecture decisions (ADRs), wire-protocol guides, and KB notes — lives in [`dev/`](dev).
-
 ## License
 
 [Apache-2.0](LICENSE) — Copyright © 2026 Widi Harsojo