dsh-embedded-workbench 0.7.1

package/skills/keil-mdk-build/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: keil-mdk-build
+description: "Use when building, flashing, or packaging firmware with Keil MDK (UV4 CLI, ARMCLANG), analyzing .map files for ROM/RAM optimization and memory budget, or diagnosing Keil-specific build failures. NOT for non-Keil build systems (Makefile, CMake, IAR, GCC-only). For crash triage see hardfault-triage."
+---
+
+<HARD-GATE>
+This is a domain implementation skill. If you are planning, designing, or entering plan mode — load `Skill("embedded-workbench")` first to activate the workflow gates (Plan Verification Gate, Approval Gate, Closure Gate). Domain skills carry implementation guidance, not workflow enforcement.
+</HARD-GATE>
+
+# Keil MDK Build
+
+Patterns for building embedded firmware with Keil MDK. Covers both ARM Compiler 5 (armcc) and ARM Compiler 6 (armclang).
+
+## UV4 CLI Build (Authoritative)
+
+UV4.exe batch mode is the canonical build path. The Python CLI reimplementation is useful for CI but may miss include paths.
+
+```powershell
+<Keil>\UV4\UV4.exe -b project.uvprojx -t TargetName -j0 -o <log_path>
+```
+
+Replace `<Keil>` with the Keil install root. Auto-discover by checking common locations or ask the user when unknown.
+
+**Flags**:
+
+| Flag | Meaning |
+| ---- | ------- |
+| `-b` | Batch mode (no GUI) |
+| `-t <target>` | Target name within the multi-target project |
+| `-j0` | Auto-parallelism (use all cores) |
+| `-o <path>` | Log output file |
+
+**Exit codes**:
+
+| Code | Meaning |
+| :--: | ------- |
+| 0 | Success (no errors, no warnings) |
+| 1 | Warnings but no errors |
+| 2 | Errors |
+| 3 | Errors (when `<StopOnExitCode>3</StopOnExitCode>` is set in uvprojx) |
+
+**Critical: Log path resolution** — The `-o` path is resolved **relative to the `.uvprojx` file's directory**, not the current working directory. Always use an absolute path or a path under a known-existing subdirectory (e.g., `objects\`) of the project directory.
+
+**Recommended invocation** — UV4 produces no stdout; use `Start-Process` with `-Wait -PassThru` and check `ExitCode`:
+
+```powershell
+$keil = "<Keil_install_root>"  # Ask user or auto-discover
+$log = Join-Path (Get-Location) "build.log"
+$p = Start-Process -FilePath "$keil\UV4\UV4.exe" `
+    -ArgumentList "-b project.uvprojx -t Target -j0 -o $log" `
+    -Wait -PassThru -NoNewWindow
+if ($p.ExitCode -ne 0) { throw "Build failed (exit $($p.ExitCode))" }
+```
+
+## Compiler Selection
+
+Keil MDK supports two compiler generations. Identify which one the project uses before generating commands.
+
+| Compiler | Keil Name | Binary | Install Path | Check Version |
+|----------|-----------|--------|-------------|---------------|
+| ARM Compiler 5 | AC5 | `armcc` | `<Keil>\ARM\ARMCC` | `armcc --vsn` |
+| ARM Compiler 6 | AC6 | `armclang` | `<Keil>\ARM\ARMCLANG*` | `armclang --version` |
+
+**How to identify**: Check the `.uvprojx` XML for `<ARMCC>` (AC5) or `<ARMCLANG>` (AC6) sections. A project can mix both — check per-file or per-group settings.
+
+## ARM Compiler 5 (armcc)
+
+Legacy compiler, still common in long-lived projects. Uses its own flag syntax, incompatible with AC6.
+
+**Detection**: Installed at `<Keil>\ARM\ARMCC`. Run `armcc --vsn` to verify.
+
+**Optimization levels** — AC5 has two orthogonal axes: optimization level (`-On`) and optimization goal (`-Ospace` vs `-Otime`). Keil's UI combines them into a single dropdown:
+
+| Keil Level | AC5 Flags (actual) | Effect |
+| :----------: | -------------------- | -------- |
+| 0 | `-O0` | Minimum optimization, best debug view |
+| 1 | `-O1` | Restricted optimization, good debug view |
+| 2 | `-O2` | High optimization (AC5 **default**) |
+| 3 | `-O3` | Maximum optimization |
+| 4 | `-O3 -Otime` | Max optimization + favor speed over size |
+
+`-Ospace` is the default goal at levels 0-3 (favor smaller code). `-Otime` swaps to favor speed. These are separate from the `-On` level.
+
+Sources: ARM Compiler v5.06 User Guide ([DUI0472M](https://developer.arm.com/documentation/dui0472m)), §3.154-3.159.
+
+**Key flags**:
+
+- `--cpu Cortex-M4` (adjust to target MCU; use `--cpu=list` to see supported targets)
+- `--c99` or `--c11` (language standard; C90 is the AC5 default)
+- `--gnu` (enable GNU extensions if project relies on them)
+- `--apcs=/interwork` (ARM/Thumb interworking)
+- `-c` (compile only, no link)
+- `--split_sections` (equivalent to `-ffunction-sections -fdata-sections`)
+
+**Warning control**: `--diag_suppress=<id>` to suppress specific warnings; `--diag_error=<id>` to promote to error.
+
+## ARM Compiler 6 (armclang)
+
+LLVM-based, current generation. Installed at `<Keil>\ARM\ARMCLANG*`.
+
+**Detection**: Search common install roots for directories matching `ARMCLANG*`. Validate with `armclang --version`. If detection fails, ask the user.
+
+**Optimization levels**:
+
+| Keil Level | AC6 Flag |
+| :----------: | ------ |
+| 0 | `-O0` |
+| 1 | `-O1` |
+| 2 | `-O2` |
+| 3 | `-O3` |
+| 4 | `-Os` |
+| 5 | `-Ofast` |
+
+**Key flags for Cortex-M**:
+
+- `--target=arm-arm-none-eabi -mcpu=cortex-m4 -mfpu=fpv4-sp-d16 -mfloat-abi=hard` (adjust MCU/FPU to target)
+- `-c` (compile only, no link)
+- `-ffunction-sections -fdata-sections` (enable linker garbage collection)
+- `-fshort-enums -fshort-wchar` (common embedded defaults)
+
+## AC5 to AC6 Migration Traps
+
+Projects migrating from AC5 to AC6 commonly hit these issues. Sources: [ARM Compiler Migration Guide (DUI0742)](https://developer.arm.com/documentation/dui0742), [Arm Compiler for Embedded FuSa Migration Guide](https://developer.arm.com/documentation/109444).
+
+| AC5 | AC6 | Trap |
+| ----- | ----- | ------ |
+| `__packed struct { ... }` | `struct __attribute__((packed, aligned(1))) { ... }` | AC5 keyword silently ignored by AC6; struct layout changes. `aligned(1)` ensures no implicit alignment. |
+| `__irq void Handler()` | `void Handler(void) __attribute__((interrupt))` | AC5 attribute not recognized; ISR stack frame broken. Alternatively use CMSIS `IRQn_Type`. |
+| `__asm { ... }` | `__asm volatile ("..." : : : )` | Inline assembly switches from armasm syntax to GAS (GNU assembler) syntax with GCC-style operand constraints. |
+| `--c99` | `-std=c99` | Flag syntax differs; AC6 defaults to gnu11 |
+| `--gnu` | `-fgnu89-inline` | GNU inline semantics differ between compilers |
+| `--diag_suppress=<n>` | `-Wno-<name>` | Warning names differ; numbers don't map 1:1. Use AC6 `-Weverything` to list available warnings. |
+| `#pragma diag_suppress` | `#pragma clang diagnostic ignored "-Wname"` | Pragma syntax differs |
+| `char` unsigned by default | `-funsigned-char` | AC5 defaulted to `unsigned char`; AC6 defaults to signed. Add flag to preserve behavior. |
+
+**Migration verification**: After switching compiler, compare `.map` file sizes and symbol lists. Unexpected size changes often indicate a packing or inlining difference.
+
+## Build Lifecycle
+
+A full Keil build has 5 stages:
+
+1. **Pre-build** — Version header generation, manifest updates
+2. **Compile** — `.c`/`.cpp`/`.s` → `.o` via armcc (AC5) or armclang (AC6)
+3. **Link** — `armlink --via=<response>.lnp` → `.axf`
+4. **Post-build (fromelf)** — `fromelf --bin objects/app.axf → application.bin`
+5. **Post-build (merge)** — Merge application BIN + filesystem + bootloader into flash image
+
+If bypassing UV4 (CI build), all 5 stages must be replicated. The Python CLI build tool handles this internally.
+
+## Merge / Packaging
+
+Embedded firmware packages typically merge multiple components into a single flash image.
+
+### Bootloader Selection (Parity Rule)
+
+A common pattern: use `version.build` parity to select development vs. production bootloader.
+
+- Parse `version.build` as hexadecimal (not decimal)
+- **Odd** → production bootloader
+- **Even** → development bootloader
+
+This is the most common source of confusion — `0x10` (hex) is even, even though "16" as a decimal number looks like it could be interpreted differently.
+
+### Manifest Structure
+
+Merged firmware images include a manifest at a fixed address with:
+
+- Version fields (major, minor, patch, build)
+- Component sizes (firmware, filesystem)
+- CRC32 checksums for each component
+- Magic number for validation
+
+Components are typically padded to alignment boundaries before CRC calculation.
+
+### Non-Standard CRC32
+
+Embedded firmware CRC32 often differs from the standard `zlib`/`crc32` implementation:
+
+- **Byte-swapped within each word** (MCU word order)
+- No reflection (forward bit order)
+- No final XOR
+- Polynomial: `0x104C11DB7`
+
+Verify the CRC implementation against a known-good reference before trusting any reimplementation.
+
+## Common Build Failures
+
+| Failure | Cause | Fix |
+| --------- | ------- | ----- |
+| UV4 log written to wrong location | `-o` path is relative to uvprojx directory | Use absolute path |
+| CLI build: missing CMSIS headers | Pack directory detection incomplete | Use UV4 CLI (`UV4.exe -b`) for authoritative builds |
+| CLI build: no compile entries | `.dep` file stale or from different target | Run Keil IDE build first to regenerate |
+| merge: input file not found | fromelf step didn't produce `application.bin` | Check after-build hooks; ensure fromelf completed |
+| Wrong bootloader selected | `version.build` parsed as decimal instead of hex | Always parse build number as hexadecimal |
+| "file not found" for OTA component | Filesystem image not generated | Build filesystem assets before merge step |
+| AC6: struct layout differs from AC5 | `__packed` ignored by AC6 | Replace with `__attribute__((packed))` |
+| AC6: ISR crashes after migration | `__irq` attribute not recognized | Use `__attribute__((interrupt))` or CMSIS `IRQn_Type` |
+| AC6: inline asm syntax errors | AC5 `__asm { }` in sources | Rewrite as `__asm volatile ("...")` |
+| Linker: "No section matches selector" | Scatter file syntax differs between AC5/AC6 | Check scatter file against compiler docs; AC5 uses different section naming |
+
+## MAP File Analysis
+
+The `.map` file (at `<listings>/<target>.map`) is the linker's memory blueprint. Make it a habit to review after each build.
+
+### Key Sections
+
+| Section | What It Tells You |
+| --------- | ------------------- |
+| **Image component sizes** | Per-file Code / RO Data / RW Data / ZI Data breakdown. Find the bloat. |
+| **Memory Map of the image** | Flash and RAM layout: load regions, execution regions, stack, heap |
+| **Global Symbols** | Every function/variable address and size — essential for HardFault analysis |
+| **Removing unused sections** | What the linker eliminated. Check for unexpected removals. |
+| **Cross References** | Which `.o` calls which. Trace startup and verify call graphs. |
+
+### Size Optimization Workflow
+
+1. Sort **Image component sizes** by Code + RO Data. Focus on the top 5 files.
+2. In **Global Symbols**, find functions with large `Size` values. Consider splitting or rewriting.
+3. Check `.constdata` / `.rodata` for debug strings — guard with `#if` or move to runtime generation.
+4. In **Memory Map**, look for `PAD` entries — these are alignment waste. Reorder struct members to minimize.
+5. Verify MicroLIB is enabled; check that no accidental `printf`/`sprintf`/`malloc` drags in heavy library code.
+6. Keep an optimization log: ROM/RAM before and after each change.
+
+### Memory Budget Verification
+
+From the **Memory Map** section:
+
+- **Load Region LR_IROM1** size = total Flash used (Code + RO + RW initial values)
+- **Execution Region RW_IRAM1** = total RAM used (RW data + ZI data + Stack + Heap)
+- **RW Data** consumes BOTH Flash and RAM — initial values stored in Flash, copied to RAM at startup
+- **ZI Data** consumes RAM only — zero-initialized at startup
+
+Check that Stack + Heap sizes match the worst-case call chains (from `.htm` call graph) plus margin.
+
+## HardFault / Exception Triage
+
+For crash analysis — fault registers, stack-frame capture, PC-to-source resolution, root-cause classification — load `Skill("hardfault-triage")`. The `.map` file sections described above (Global Symbols, Memory Map) are the bridge between the two skills: build the `.map` here, debug the crash there.

package/skills/state-machine-design/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: state-machine-design
+description: "Use when reviewing or fixing async protocols, retries, ACK/NACK handling, pending flags, timeout logic, or state-machine lockups in embedded firmware. NOT for generic network protocol design (TCP/HTTP/MQTT) unless targeting embedded firmware stack."
+---
+
+<HARD-GATE>
+This is a domain implementation skill. If you are planning, designing, or entering plan mode — load `Skill("embedded-workbench")` first to activate the workflow gates (Plan Verification Gate, Approval Gate, Closure Gate). Domain skills carry implementation guidance, not workflow enforcement.
+</HARD-GATE>
+
+# State Machine Design
+
+## Core Rules
+
+- Fix the state model, not the symptom. Every in-progress or pending flag must have explicit success, failure, timeout, and reset exits.
+- Timeout logic must be gated on real pending work. Idle states must not trigger retry, recovery, or error transitions.
+- Do not trust a low-level send return value as proof of delivery when an application-layer ACK exists. Use the protocol's completion signal.
+- When adding retries, also define attempt timestamps, backoff rules, and cleanup paths so the state machine cannot lock up silently.
+- If pause, stop, or reconnect can interrupt the normal flow, add an explicit recovery or re-drive branch instead of assuming the old path will naturally resume.
+
+## Transition Gates
+
+- When a state transition depends on multiple preconditions, verify every one explicitly at the transition gate. Do not rely on implicit assumptions (e.g., "the timer expired, therefore everything must be healthy"). A single unchecked precondition is the most common source of silent state corruption.
+- If a target state's preconditions can become false while already in that state, define a reverse transition back to the source state. One-way state latches without fallback paths will eventually leak incorrect state to downstream consumers.
+
+## Transient Tolerance
+
+- Distinguish between genuine state-changing events and transient perturbations during mode switches, direction reversals, or re-initialization windows. The latter need a tolerance or grace window; only the former should advance the state machine or increment error counters.
+
+## Implementation Patterns
+
+### Pattern A: Per-State Handlers + Unified Error Gate
+
+Each state gets its own handler function. The dispatcher is a pure `switch(state)`. A unified fault-threshold check runs **after all** state handlers — no handler triggers the error transition itself. This keeps handlers simple and fault logic centralized.
+
+```c
+// === State enum: exactly one valid state at all times ===
+typedef enum {
+    COMM_STATE_INIT,
+    COMM_STATE_IDLE,
+    COMM_STATE_SAMPLE_STARTING,
+    COMM_STATE_SAMPLING,
+    COMM_STATE_ERROR,
+    COMM_STATE_RECOVERING,
+} comm_state_t;
+
+// === Runtime context: all flags explicit in one struct ===
+typedef struct {
+    comm_state_t state;
+    uint32_t     command_fail_count;
+    bool         data_ready;
+    bool         communication_lost;
+} comm_runtime_t;
+
+// === Per-state handlers: each reads only what it needs ===
+static void comm_handle_idle(comm_runtime_t *rt) {
+    rt->warmup_start_time = sys_tick();
+    comm_start_sample();
+    rt->state = COMM_STATE_SAMPLE_STARTING;
+}
+
+static void comm_handle_error(comm_runtime_t *rt) {
+    static uint32_t retry_tick = 0;
+    if (retry_tick == 0) {
+        retry_tick = sys_tick();
+        rt->data_ready = false;
+    }
+    comm_power_off();
+    if (sys_tick() - retry_tick < 500) return;  // 500ms cooldown
+    retry_tick = 0;
+    rt->state = COMM_STATE_RECOVERING;
+}
+
+static void comm_handle_recovering(comm_runtime_t *rt) {
+    comm_handle_initializing(rt);   // Recovery RE-USES init — no duplicated paths
+}
+
+// === Dispatcher: pure switch, single exit ===
+static void comm_state_process(comm_runtime_t *rt) {
+    switch (rt->state) {
+    case COMM_STATE_INIT:            comm_handle_initializing(rt);   break;
+    case COMM_STATE_IDLE:            comm_handle_idle(rt);           break;
+    case COMM_STATE_SAMPLE_STARTING: comm_handle_sample_starting(rt);break;
+    case COMM_STATE_SAMPLING:        comm_handle_sampling(rt);       break;
+    case COMM_STATE_ERROR:           comm_handle_error(rt);          break;
+    case COMM_STATE_RECOVERING:      comm_handle_recovering(rt);     break;
+    default:
+        rt->state = COMM_STATE_INIT;  // Unknown state → safe fallback
+        break;
+    }
+
+    // Unified error gate: checked AFTER every state, not buried inside handlers.
+    // A new state cannot accidentally bypass this check.
+    if (rt->command_fail_count >= COMM_MAX_FAILS) {
+        rt->state = COMM_STATE_ERROR;
+        rt->command_fail_count = 0;
+        rt->communication_lost = true;
+    }
+}
+```
+
+Key properties:
+
+- **Fault logic is centralized** — the error gate runs exactly once, after every state. New states cannot bypass it.
+- **Recovery reuses init** — `comm_handle_recovering()` calls `comm_handle_initializing()`. No duplicated paths to drift apart.
+- **All exits are explicit** — `Error` has a cooldown period (500ms), then transitions to `Recovering`. No fall-through, no implicit assumption.
+- **Unknown state → safe fallback** — the `default` case resets to `Init`.
+
+### Pattern B: Function-Pointer Table Dispatch
+
+Heavier than switch-case, but useful when states are added/removed frequently or handlers need different signatures.
+
+```c
+static const struct {
+    comm_state_t state;
+    void (*process)(void);
+} comm_state_table[] = {
+    {COMM_STATE_INIT,       comm_init_process},
+    {COMM_STATE_IDLE,       comm_idle_process},
+    {COMM_STATE_CONNECTED,  comm_connected_process},
+    {COMM_STATE_ERROR,      comm_error_process},
+    {COMM_STATE_RECOVERING, comm_recovering_process},
+};
+
+void comm_state_dispatch(void) {
+    for (size_t i = 0; i < ARRAY_LEN(comm_state_table); i++) {
+        if (g_comm_runtime.state == comm_state_table[i].state
+            && comm_state_table[i].process != NULL) {
+            comm_state_table[i].process();
+            return;
+        }
+    }
+    // Unknown state: reset to safe default
+    g_comm_runtime.state = COMM_STATE_INIT;
+}
+```
+
+### Pattern C: ACK Timeout With Explicit Retry Limit
+
+All core rules in one function: timeout gated only when work is pending, explicit retry count, predefined max retries, all exits defined.
+
+```c
+static void comm_ack_check(uint32_t now_sec) {
+    // GUARD: timeout logic only runs when there is real pending work
+    if (!g_comm.report_in_progress) return;
+
+    // GUARD: timeout hasn't expired yet
+    if (elapsed_sec(g_comm.send_time, now_sec) < COMM_ACK_TIMEOUT_S) return;
+
+    // Timeout fired. Explicit retry branch:
+    if (g_comm.retry_count == 0) {
+        g_comm.retry_count++;
+        g_comm.send_time = now_sec;
+        comm_send_report();                    // One automatic retry
+        return;
+    }
+    // All retries exhausted → terminal exit
+    g_comm.report_in_progress = false;
+    g_comm.retry_count = 0;                    // Reset for next cycle
+    comm_report_result(false);                 // Notify caller: failed
+}
+```
+
+### Anti-Patterns
+
+```c
+// BAD: implicit state via flags — new flag creates untested state combinations
+if (g_flags.busy && !g_flags.paused && g_flags.online) { ... }
+// Fix: use explicit enum — exactly one valid state at all times
+
+// BAD: idle state triggers timeout — retry fires with nothing pending
+if (elapsed_ms(t0, now) > TIMEOUT) { retry(); }
+// t0 is always running, even when no work is in flight
+
+// BAD: retry loop with no exit condition
+void retry_forever(void) {
+    while (!send_packet()) { delay(100); }  // Will lock up if HW is dead
+}
+
+// BAD: recovery path duplicates init logic instead of reusing it.
+// The copy drifts over time — one path gets a fix, the other doesn't.
+
+// BAD: Error handler directly calls power_off() without cooldown period.
+// Power-cycling faster than the hardware spec causes unpredictable state.
+```
+
+## When To Escalate
+
+- When diagnostics point to an architecture-level or state-machine design defect, proactively offer high-level remediation focused on boundary clarity, lifecycle contracts, and reversible transitions — don't just propose ad-hoc runtime patches.
+
+**REQUIRED SUB-SKILL:** If you find a state machine bug, also load `Skill("debug-methodology")` to apply structured root-cause analysis. If the bug involves async lifecycle flags or hardware events, load `Skill("embedded-firmware-dev")`. If the state machine lockup triggers a watchdog reset or HardFault, load `Skill("hardfault-triage")`.

package/src/index.ts

@@ -0,0 +1,209 @@
+/**
+ * embedded-workbench — DeepSeek Harness native plugin for the Embedded
+ * Workbench toolbox. Injects the session-start gate text (1% Rule, Red
+ * Flags, Plan Verification Gate, skills roster) into the first model step
+ * of every agent session, mirroring the SessionStart hook the Claude Code
+ * plugin installs. The 7 skills ship in this package's `skills/` directory
+ * and are registered at apply time into dsh's `ctx.skills` registry through
+ * the standard filesystem provider, so they appear in every session catalog
+ * without a manual copy step.
+ *
+ * Injection listens on agent/pre-step and appends the gate to the FIRST
+ * model step that runs, once per session (guarded by the session's durable
+ * history). Session-start inbox injection was dropped: a blank-session preset
+ * switch (agentPreset.select -> recompose) can clear the inbox before the
+ * first step, losing the gate for the whole session. The pre-step decision is
+ * the durable path - anchored/bootstrap presets that strip first-step injected
+ * reminders (skill catalog, AGENTS.md, gate plugins) simply defer this message
+ * to the first step after their promotion, and the history guard re-injects it
+ * there. The default gate text is the dsh-native adaptation of
+ * `hooks/session-start-content.md`: behavior rules
+ * (1% Rule / Red Flags / Plan Verification Gate) stay in sync, while
+ * presentation is adapted to dsh's native skill catalog — no roster table
+ * (the model sees skills in its catalog) and no install instructions (those
+ * live in `.dsh/INSTALL.md`). Deployments override via Config.
+ *
+ * @module embedded-workbench-dsh
+ */
+
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import type { Session, UserMessage } from '@deepseek-ai/dsh-session'
+import type { HostCordisInspectProviderRegistration } from '@deepseek-ai/dsh-cordis-host-runner'
+import { FileSystemSkillProvider } from '@deepseek-ai/dsh-skill-filesystem'
+
+export const name = 'embedded-workbench'
+
+// Skills are contributed through the registry service, which dsh-base always
+// mounts before bundle rows such as this one apply.
+export const inject = ['skills']
+
+// Absolute path of the package's shipped skills directory. `lib/index.js`
+// lives one level below the package root, so `../skills` from the module URL
+// lands on `<package>/skills` regardless of where the package was installed.
+const SKILLS_DIR = fileURLToPath(new URL('../skills', import.meta.url))
+
+const GATE_PLUGIN_ID = 'embedded-workbench'
+
+const DEFAULT_GATE_CONTENT = `<EXTREMELY_IMPORTANT>
+Plugin embedded-workbench is active. You have embedded C/C++ firmware development skills — names and "Use when" triggers are in your skill catalog; load them with the skill tool. No custom agents in dsh: use the native subagent tooling for parallel work.
+
+**1% Rule**: If there is even a 1% chance a skill applies to your task, invoke it before responding. If the skill turns out to be wrong for the situation, discard it and move on. The cost of loading a skill is trivial compared to the cost of a preventable mistake.
+
+**Red Flags** — if you think any of these, STOP. You are rationalizing:
+
+| You think | Reality |
+|-----------|---------|
+| "This is just a quick fix" | Quick fixes break things. A 3-line design check costs 30 seconds. |
+| "I already understand this code" | You are looking at one file. The blast radius may span 5 modules. |
+| "The skill is overkill for this" | Simple things become complex. Check for skills. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can just read the file directly" | Skills have patterns and pitfalls you will not discover by reading. |
+| "I remember this skill content" | Skills evolve. Always load the current version. |
+| "I've explored enough, time to exit plan mode" | The exit_plan_mode tool is the verification gate. Have you loaded the logicprobe skill? Every plan must pass this gate before exit. |
+| "This plan is too simple for logicprobe" | The skill auto-classifies depth. You don't decide. |
+| "I already read the code, I know the file paths are correct" | Load the logicprobe skill, run Phase 0, append the "## Plan Verification" block. |
+
+**Plan Verification Gate**: Before calling exit_plan_mode (or presenting a plan for approval), either load the logicprobe skill (a separate plugin — if it is missing from your skill catalog, tell the user to install it) OR inform the user "此计划未经 logicprobe 验证，是否需要核查？" Silent skip is not an option.
+
+To load workflows and engineering policies: load the embedded-workbench skill.
+
+**Proactive features**: When you see state machines, protocol refactoring, behavioral claims ("always"/"never"), or multi-module tasks — suggest verification, adversarial probing, or parallel subagents BEFORE the user asks. Most users do not know these exist.
+</EXTREMELY_IMPORTANT>`
+
+export interface Config {
+  enabled: boolean
+  gateContent: string
+}
+
+export const Config = z.object({
+  enabled: z.boolean().default(true),
+  gateContent: z.string().default(DEFAULT_GATE_CONTENT),
+})
+
+function gateMessage(text: string): UserMessage {
+  return createUserMessage({
+    content: [{ type: 'text', text }],
+    // `form` omitted — an undeclared context is the documented default.
+    source: { kind: 'plugin', plugin: GATE_PLUGIN_ID },
+  })
+}
+
+/**
+ * Model-visible catalog entry (cordis_inspect_list / cordis_inspect_query):
+ * lets the model read this plugin's runtime status without guessing. Mirrors
+ * the registration pattern of the official dsh-tool-cordis host providers.
+ */
+function inspectProvider(config: Config): HostCordisInspectProviderRegistration {
+  return {
+    manifest: {
+      id: 'embedded-workbench',
+      description: 'Session-start gate injection for the Embedded Workbench toolbox — folds the 1% Rule / Red Flags / Plan Verification Gate text into the first model step of every agent session.',
+      methods: [
+        {
+          name: 'status',
+          description: 'Read whether the gate injection is active and how large the injected gate text is.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false,
+          },
+          outputSchema: {
+            type: 'object',
+            description: 'Gate-injection plugin status.',
+            properties: {
+              enabled: { type: 'boolean', description: 'Whether the gate folds into the first model step.' },
+              gateContentLength: { type: 'integer', description: 'Length in characters of the injected gate text.' },
+            },
+            required: ['enabled', 'gateContentLength'],
+            additionalProperties: false,
+          },
+        },
+      ],
+    },
+    query: async (method) => {
+      if (method === 'status') {
+        return {
+          enabled: config.enabled,
+          gateContentLength: config.gateContent.length,
+        }
+      }
+      return null
+    },
+  }
+}
+
+export function apply(ctx: Context, config: Config): void {
+  // Catalog visibility is optional: register only when the inspect registry
+  // service is mounted, so headless assemblies without it keep the gate
+  // injection working. The registry may be provided AFTER this row applies
+  // (base-bundle rows can mount later), so registration is retried on the
+  // first agent/session-start — by then the app is fully booted.
+  let providerRegistered = false
+  const registerProvider = (): void => {
+    if (providerRegistered) return
+    const inspect = ctx.get('cordisInspect')
+    if (inspect === undefined) return
+    try {
+      ctx.effect(() => inspect.register(inspectProvider(config)), 'embedded-workbench: inspect provider')
+      providerRegistered = true
+    } catch (err) {
+      console.warn('[embedded-workbench] inspect provider registration failed', err)
+    }
+  }
+  registerProvider()
+  // Ship the bundled skills through the registry: reuse the standard
+  // filesystem provider over this package's own `skills/` directory, so
+  // catalog discovery, frontmatter parsing, and SKILL.md loading behave
+  // exactly like project/user skills while the plugin stays self-contained.
+  // Registration lands in the global registry layer (this row mounts at the
+  // profile root), so every agent preset sees the skills. `registerProvider`
+  // returns the effect disposer; its teardown unregisters and invalidates.
+  ctx.skills.registerProvider((control) => {
+    return new FileSystemSkillProvider(ctx, control, {
+      providerName: 'embedded-workbench',
+      includeDefaultRoots: false,
+      customSkillDirs: [SKILLS_DIR],
+    })
+  })
+  if (!config.enabled) return
+  // Inject the gate once per session on the FIRST model step that runs,
+  // instead of at session-start: session-start injection lands in the agent's
+  // inbox, which a blank-session preset switch (agentPreset.select ->
+  // recompose) can clear before the first step - the gate would then be lost
+  // for the whole session. The pre-step decision is the durable path a
+  // first-step injection takes: the gate is appended to the first step's
+  // decision and enters session history there, so every later step (and a
+  // resume) skips it. Anchored/bootstrap presets that strip first-step
+  // injected reminders (skill catalog, AGENTS.md, gate plugins) simply defer
+  // this message to the first step after their promotion - the history guard
+  // re-injects it there, so the gate still lands exactly once per session.
+  ctx.on('agent/pre-step', async ({ agent }, next) => {
+    const decision = await next()
+    if (decision.kind === 'reject') return decision
+    registerProvider()
+    if (gateInHistory(agent.session)) return decision
+    return {
+      kind: 'enter',
+      messages: [...decision.messages, gateMessage(config.gateContent)],
+    }
+  })
+}
+
+/**
+ * Whether the gate already entered this session's durable history. The
+ * pre-step listener re-appends the gate until it does; once a step committed
+ * it, every later step (and a resume of a session that kept it) skips the
+ * injection. A session whose gate was dropped before any step ran (e.g. an
+ * inbox cleared by a blank-session preset switch) simply re-injects on the
+ * first step that runs.
+ */
+function gateInHistory(session: Session): boolean {
+  return session.events.some((event) => {
+    if (event.type !== 'user/message') return false
+    const source = event.data.source
+    return source.kind === 'plugin' && source.plugin === GATE_PLUGIN_ID
+  })
+}