@loomhelm/multi-task-flow 0.0.0-stage → 0.2.6

package/toolkit/skills/global-port-manager/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: global-port-manager
+description: "Manage global per-worktree port leases."
+---
+
+# Global port manager
+
+Use this skill when you need to allocate, register, inspect, or release ports globally across projects/services, and need traceability for who is occupying which port.
+
+## Why this skill
+
+- One global source of truth for active leases: `${CODEX_HOME:-~/.codex}/state/port-registry/leases.tsv`
+- Concurrency-safe writes using file locks + atomic replace
+- Immediate cleanup for pid-backed stable leases when the process dies or the port stops LISTENing; legacy pid-less rows still use the `24h + port-not-listening` TTL rule
+- Compatible with worktree lifecycle hooks (`git-worktree`, `git-cleanup`)
+- Intended to gate all long-lived local services before they start listening on a port
+
+## Data model
+
+`leases.tsv` stores **active leases only** (rows are deleted on release).
+
+Columns (fixed order):
+
+- `scope_id`
+- `project`
+- `repo_root`
+- `branch`
+- `worktree_path`
+- `service`
+- `port`
+- `port_base`
+- `block_size`
+- `claimed_at`
+- `last_seen_at`
+- `agent_session`
+- `pid`
+
+Defaults:
+
+- automatic allocation uses stable scope-random candidate blocks at or above `10000`
+- `--start-base` is the lower bound for automatic `allocate` / `suggest` candidates; default is `10000`
+- block step is `10`
+- block size is `10`
+- stale lease TTL is `24h`
+
+`scope_id` rule:
+
+- Must be globally unique across repos/scopes.
+- Recommended deterministic format: `<project>--<repo_hash8>--<scope_slug>`.
+- `repo_hash8` should be derived from absolute repo root path SHA256 first 8 chars.
+- Do not use bare slugs like `pm-a` as `scope_id`.
+- A Ticket envelope may provide a resolved `port_scope_id`. Reuse it only when it follows this rule and matches the current task/repo facts; do not derive a new scope from an internal Codex-managed Worktree directory.
+
+## Script
+
+- Path: `skills/global-port-manager/scripts/port_registry.ts`
+- Production runtime: Bun 1.4.4 directly executes the original TS script through the packaged client (`skills run skills/global-port-manager/scripts/port_registry.ts <arguments>`). Node.js and compiled JS entrypoints are unsupported.
+- The raw TypeScript examples below use the same required Bun runtime.
+
+Common flags:
+
+- `--registry-dir` (optional): override registry root; default `${CODEX_HOME}/state/port-registry` when `CODEX_HOME` is set, otherwise `~/.codex/state/port-registry`
+- `--lock-timeout-sec` (default `10`)
+- `--ttl-hours` (default `24`)
+- `--json` for machine-readable output
+- Compatibility: `--workspace-id` is accepted as an alias of `--scope-id`
+
+### Allocate (recommended for new worktree/service)
+
+```bash
+bun --no-install "${LOOMHELM_TOOLKIT_ROOT:?set packaged toolkit root}/skills/global-port-manager/scripts/port_registry.ts" --json \
+  allocate \
+  --scope-id <id> \
+  --project <project> \
+  --repo-root <repo_root> \
+  --branch <branch> \
+  --worktree-path <path> \
+  --service <service>
+```
+
+Behavior:
+
+- Reuses existing lease for the same `scope_id + service`
+- Otherwise picks an available port from a deterministic, scope-randomized block order
+- New automatic leases default to ports at or above `10000`; explicit `register --port` keeps caller-provided port semantics
+- Runs GC before allocation
+
+### Register (explicit port)
+
+```bash
+bun --no-install "${LOOMHELM_TOOLKIT_ROOT:?set packaged toolkit root}/skills/global-port-manager/scripts/port_registry.ts" --json \
+  register \
+  --scope-id <id> \
+  --service <service> \
+  --port <port> \
+  --project <project> \
+  --repo-root <repo_root> \
+  --branch <branch> \
+  --worktree-path <path> \
+  [--pid <pid>] \
+  [--expected-pid <pid> | --expect-empty-pid] \
+  [--agent-session <session-id>]
+```
+
+Dashboard wrappers that own startup must use the registry's atomic claim-and-run path when available: it validates the preallocated empty-PID lease, rejects an existing PID or already-listening duplicate, holds the registry lock while the wrapper binds its listener, and records the wrapper PID only after the listener is confirmed. A wrapper must not emulate this with a separate `inspect` followed by `register`, because that can overwrite an active owner or expose a startup window to GC.
+
+### Heartbeat
+
+```bash
+bun --no-install "${LOOMHELM_TOOLKIT_ROOT:?set packaged toolkit root}/skills/global-port-manager/scripts/port_registry.ts" --json \
+  heartbeat --scope-id <id> --service <service> [--port <port>] [--pid <pid>] [--expected-pid <pid>] [--agent-session <session-id>]
+```
+
+### Inspect
+
+```bash
+bun --no-install "${LOOMHELM_TOOLKIT_ROOT:?set packaged toolkit root}/skills/global-port-manager/scripts/port_registry.ts" --json inspect
+bun --no-install "${LOOMHELM_TOOLKIT_ROOT:?set packaged toolkit root}/skills/global-port-manager/scripts/port_registry.ts" --json inspect --scope-id <id>
+bun --no-install "${LOOMHELM_TOOLKIT_ROOT:?set packaged toolkit root}/skills/global-port-manager/scripts/port_registry.ts" --json inspect --port <port>
+```
+
+### Release
+
+```bash
+bun --no-install "${LOOMHELM_TOOLKIT_ROOT:?set packaged toolkit root}/skills/global-port-manager/scripts/port_registry.ts" --json \
+  release-service --scope-id <id> --service <service>
+
+bun --no-install "${LOOMHELM_TOOLKIT_ROOT:?set packaged toolkit root}/skills/global-port-manager/scripts/port_registry.ts" --json \
+  release-scope --scope-id <id>
+```
+
+Compatibility:
+
+- `release-worktree` is accepted as an alias of `release-scope`.
+
+### GC
+
+```bash
+bun --no-install "${LOOMHELM_TOOLKIT_ROOT:?set packaged toolkit root}/skills/global-port-manager/scripts/port_registry.ts" --json gc
+```
+
+## Default contract for long-lived local services
+
+Use this order whenever an agent starts a local service that keeps listening on a port:
+
+1. Resolve a deterministic `scope_id` for the current repo/worktree.
+2. Determine whether the command or repo script has an explicit/default port.
+3. If a port is already known, run `inspect --port <port>` first to learn ownership before starting anything.
+4. If the known port is already leased by another scope or is currently LISTENing for another workspace, do not reuse it:
+   - report the owner/path evidence;
+   - allocate or register a different port for the current scope;
+   - inject that port into the command with env/flags.
+5. If no port is predetermined, run `allocate` before starting the service.
+6. Start the service only after the chosen port is leased to the current scope.
+7. For long-running sessions, refresh the lease with `heartbeat`; whenever the runtime exposes a stable `pid` or `agent_session`, keep those fields populated on the lease.
+8. Before sharing a local preview URL with the user, verify that the URL port matches the current lease or a repo-declared stable preview port owned by the current workspace.
+9. If the URL will appear in an owner-facing reply, require a Codex native background session to keep owning that service after the current turn, and populate `agent_session` on the lease whenever the runtime exposes it.
+
+The port manager owns lease allocation, atomic startup claim, inspection, heartbeat and release only. A service wrapper must atomically claim its preallocated lease before binding, reject an existing owner instead of treating its PID as transfer authorization, and pass its recorded port and expected PID when heartbeating or releasing so a replaced lease cannot be changed by the old process. `pid` remains the value to record; `expected-pid` is the ownership guard for subsequent lifecycle operations. The registry does not create, attach, retain or prove the liveness of a Codex native background session. The Agent must obtain that session from the host and may pass only the host-provided identifier; an `agent_session` value is provenance metadata, not proof that the host session exists. If the host exposes no supported background route, do not substitute a visible terminal or foreground exec and do not hand off the URL.
+
+## Live vs stable preview contract
+
+- `live exec preview`: current-turn-only validation surface backed by the active exec/native background session for the current scope; acceptable for internal browser verification, not for final localhost handoff.
+- `native background handoff preview`: preview runtime backed by the current lease plus an active Codex native background session for the current scope; required before giving the user a localhost URL that should survive past the current foreground exec step.
+- If a preview still depends on the lifetime of the current exec session, it is `live`, even if the port is leased correctly.
+- If `inspect/register/allocate/heartbeat/gc` discovers a pid-backed lease whose `pid` is dead or whose port is no longer listening, treat it as stale and let the registry self-heal instead of waiting for the 24h TTL.
+
+Repo scripts with built-in defaults do not bypass this contract. The default value is only an input to inspect/register/override, not permission to grab that port blindly.
+
+## Integration contract
+
+- `git-worktree` create: call `allocate` right after worktree creation.
+- Worktree-local service flows: call `allocate/register` before starting services and `heartbeat` during long-running sessions.
+- Any long-lived local service (`vite`, `next dev`, `storybook`, backend preview server, docs preview, local admin UI, etc.): call `inspect` on any known/default port first, then `allocate/register` before the process starts.
+- Local preview handoff: only share a localhost URL after confirming that the URL's port belongs to the current scope lease or to a repo-declared stable preview service started from the current workspace; owner-facing handoff must additionally prove that the service is still held by a Codex native background session rather than a foreground live exec. The host session is an Agent/host responsibility, not a port-manager responsibility.
+- `git-worktree` remove: call `release-scope` after successful removal.
+- `git-cleanup`: call `release-scope` whenever a PR/Wave/spec worktree is removed.
+- Native Codex task Worktrees keep their lease scope in the Ticket envelope. They may release a service lease when the task stops, but archive/removal of the Worktree itself remains with Codex native task lifecycle.
+
+## Guardrails
+
+- Never edit `leases.tsv` directly; always use the script.
+- Treat lock timeout or duplicate lease validation as blocking errors.
+- If `scope_id` cannot be derived reliably from path naming, ask the user before writing leases.
+- If `inspect` shows the port is owned by another scope/worktree, do not kill, reuse, or "take over" that port unless the user explicitly instructs you to do so.
+- If the current port owner cannot be mapped back to the current scope, treat the conflict as foreign and allocate another port.
+
+## Installed shared user services
+
+The explicitly installed multi-task-flow viewer uses a user service scope `multi-task-flow--user-<uid>` (isolated profiles append a root digest), without invented repository/worktree or `agent_session` provenance. Its install command selects and saves one high port and resolves the registry directory once. Every runtime registers that fixed port, claims/binds under the registry lock, records its actual PID, heartbeats, and releases with expected PID/port guards. Offline instances hold no active lease; conflict fails without renumbering or process takeover. User-level launchd supplies background ownership; the native Codex session requirement continues to apply to temporary previews.

package/toolkit/skills/global-port-manager/scripts/port_registry.ts

@@ -0,0 +1,4 @@
+import { runCompatibilityCli } from "../../bin/compatibility_cli";
+
+if (import.meta.main)
+  process.exitCode = await runCompatibilityCli("port_registry");

package/toolkit/skills/global-port-manager/scripts/test_port_registry.ts

@@ -0,0 +1 @@
+import "../../bin/tests/workspace/workspace.test.ts";

package/toolkit/skills/gui-escalation-gate/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: gui-escalation-gate
+description: "Route browser work to ego-browser by default and gate Chrome exceptions or Computer Use."
+---
+
+# Browser and GUI Routing Gate
+
+Use this skill when a task may need a Chrome exception, `chrome-devtools`, or Computer Use. Ordinary browser work should use `$ego-browser` directly.
+
+This skill keeps browser and GUI automation narrow, auditable, and aligned with the repository's default browser route.
+
+## Decision Ladder
+
+Evaluate lower-intrusion paths first:
+
+1. Files, source, logs, configs, manifests, local caches.
+2. Shell commands, project-native scripts, tests, builds, linters, formatters.
+3. MCP/API/source-of-truth tools for the target service.
+4. `$ego-browser` for rendered browser state.
+5. `chrome:control-chrome` or `chrome-devtools` only through their explicit exception gates.
+6. `Computer Use`.
+
+## Ego Browser Standard
+
+For ordinary browser work, use `$ego-browser` once the lower-intrusion paths cannot provide the required rendered state or interaction.
+
+1. Read and follow the selected `$ego-browser` skill before its first command.
+2. Use one Ego TaskSpace for the user goal, and keep its URL and interaction scope limited to that goal.
+3. Ask for explicit owner approval before any login, CAPTCHA, permission, state-changing input, submission, deletion, or real-program screenshot.
+
+An `$ego-browser` execution failure is not, by itself, a reason to fall back to Chrome control. Report the blocker, or use a Chrome exception only when its own gate is satisfied.
+
+## Chrome Control Exception Gate
+
+`chrome:control-chrome` is allowed only when:
+
+- The owner explicitly asks to use Chrome control; or
+- The task cannot be completed without the user's existing Chrome tabs, cookies, extensions, or authenticated session.
+
+Do not use Chrome control as a generic fallback after `$ego-browser` fails or is not directly available. When the exception depends on login state or a real screenshot, wait for the owner approval required by the task's risk.
+
+## DevTools Exception Gate
+
+The DevTools surface is a non-default exception path. It is allowed only when the owner explicitly asks for it or when a current-truth skill requires it for a narrow purpose such as structured page inspection, network/performance debugging, viewport emulation, or element-first visual evidence capture.
+
+When the DevTools exception path is used:
+
+- Reuse shared browser context by default.
+- Request `isolatedContext` only when shared context would distort results, create unacceptable auth side effects, or create unacceptable storage side effects.
+- Before the first isolated request, record `task_scope_id` and `isolation_reason` with `hazard=<result_distortion|auth_side_effect|storage_side_effect>` and `shared_context_failure=<why shared context is not acceptable>`.
+- Use at most one isolated context per `task_scope_id`; later pages for the same task must reuse it.
+- Block any attempt to create a second isolated context for the same `task_scope_id` unless the caller explicitly starts a new task scope.
+
+For ordinary page opening, local preview verification, or "open this in the browser" requests, use `$ego-browser`. DevTools is not a generic fallback after `$ego-browser` fails.
+
+## Allowed Routes
+
+`ego-browser` is the default route when at least one condition is true:
+
+- The task requires visible browser state or interaction that files, scripts, and source-of-truth tools cannot provide.
+- The user asks to open, inspect, test, or interact with a web page.
+- The task requires a local preview or a deterministic browser-validation surface.
+
+`Computer Use` is allowed only when at least one condition is true:
+
+- The user explicitly asked to control a desktop app.
+- The required target is a desktop app with no sufficient CLI, MCP, API, file, or browser-specific surface.
+- A lower-intrusion path has failed and the remaining task cannot be completed without desktop GUI control.
+
+For browser work, use `chrome:control-chrome` or `chrome-devtools` only with the explicit exception rationale above. Generic statements such as “当前线程里没有可调用的 ego-browser” do not authorize a Chrome fallback.
+
+The repo does not maintain a separate project-owned browser fallback. If `$ego-browser` is blocked and no explicit browser exception applies, report the blocker or evaluate Computer Use through this gate.
+
+## Required Pre-Use Disclosure
+
+Before using Computer Use, disclose this one-line gate result unless the user's current request explicitly named that exact tool:
+
+```text
+GUI escalation: tool=computer-use; reason=<why ego-browser and browser exceptions are insufficient>; target_scope=<page/app/window/capture scope>; risk=<none|click|input|submit|delete|permission|login-state|real-screenshot>
+```
+
+For a Chrome or DevTools exception, state the narrowly applicable reason before acting, for example:
+
+```text
+Browser exception: tool=chrome:control-chrome; reason=requires the user's existing authenticated Chrome session
+```
+
+If `risk` includes `submit`, `delete`, `permission`, `login-state`, or `real-screenshot`, wait for explicit user approval before acting.
+
+## Hard Blocks
+
+- Do not use Computer Use just because it is visible or enabled.
+- Do not use Computer Use only because the prompt says "open", "test", "view", "check", or "screenshot"; first determine whether `$ego-browser` satisfies the task.
+- Do not use `chrome:control-chrome` merely because `$ego-browser` is unavailable or has failed.
+- Do not offer `chrome-devtools` as the next step for an ordinary page-open task after `$ego-browser` fails.
+- Do not use `Computer Use` as a browser fallback while `$ego-browser` remains viable.
+- Do not treat a freshly launched Chrome/Chromium/`9222` debugging instance as valid evidence that the repo-owned DevTools Surface was available all along; that is `Synthetic DevTools Bootstrap`, and it is blocked by default.
+- Do not treat generic user wording like “在浏览器打开”“继续验证”“你自己看一下” as authorization to launch a fresh debugging browser instance.
+- Do not modify bundled plugin cache skill files to enforce this policy; they can be overwritten by plugin updates.
+- Do not capture fullscreen desktop or unrelated windows.
+
+## Output Contract
+
+When escalation is blocked, report which lower-intrusion path is still viable or which required browser blocker evidence is still missing, and continue with the safest viable path.
+
+When escalation is allowed, keep the target scope narrow and return to non-GUI tooling as soon as the GUI-only evidence or action is complete.

package/toolkit/skills/hardware-doc-ingest/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: hardware-doc-ingest
+description: "Ingest hardware PDFs into project docs."
+---
+
+# Hardware Doc Ingest
+
+## Overview
+
+Ingest vendor PDFs into a repo so the project has a durable, searchable Markdown copy (with local images), while still keeping the original PDF for fidelity.
+
+## Guardrails
+
+- Confirm whether the repo is public; do not commit redistributed vendor PDFs into public repos unless the user explicitly approves.
+- Avoid overwriting existing docs unless the user explicitly approves.
+- Treat the staged `.../<slug>.md` as a **generated, fidelity-critical artifact**:
+  - **DO NOT EDIT** the generated Markdown by hand (including “small fixes” / formatting).
+  - Put all project-specific notes, summaries, corrections, and decisions in a separate notes file next to it:
+    - Preferred (one folder per doc): `README.md`
+    - Flat layout fallback: `<slug>.README.md`
+  - If the generated Markdown needs to change, **re-run MinerU and re-ingest** (overwrite intentionally) so it stays traceable to the source PDF.
+- Keep docs timeless: do not add doc-level revision markers like “Draft/v1/初稿/修订记录”; rely on Git history instead.
+
+## Directory conventions (default)
+
+- Prefer an existing docs root: `docs/` (or `doc/` if that is what the repo uses).
+- Default targets (create if missing):
+  - `docs/datasheets/`
+  - `docs/manuals/`
+  - `docs/app-notes/`
+  - `docs/errata/`
+- Store as **generated artifacts** (immutable):
+  - `.../<slug>.pdf` (original, for fidelity)
+  - `.../<slug>.md` (generated, for reading/search — **DO NOT EDIT**)
+  - `.../<slug>.assets/` (images and any extracted artifacts)
+  - Optional: `.../<slug>.lock.json` (checksums + provenance; used to detect accidental edits)
+- Store as **human notes** (editable):
+  - Preferred (one folder per doc): `.../README.md` (project-specific summary, decisions, and remarks)
+  - Flat layout fallback: `.../<slug>.README.md`
+
+If your repo prefers “one folder per doc” (common), use:
+
+- `docs/<category>/<slug>/`
+  - `<slug>.pdf`, `<slug>.md`, `<slug>.assets/`, `<slug>.lock.json`, `README.md`
+
+If the repo already has a different convention (e.g., `docs/hardware/datasheets/`), follow it.
+
+## Workflow
+
+### 1) Confirm inputs (minimal questions)
+
+- Identify the **source**: local file path(s) and/or URL(s).
+- Identify the **doc type**: datasheet / reference manual / app note / errata.
+- Capture the **canonical identifiers** (when applicable): vendor, part number, doc title, revision/date.
+
+### 2) Decide destination paths
+
+- Pick the docs root (`docs/` preferred).
+- Choose the category folder based on doc type.
+- Choose a stable `<slug>`:
+  - Prefer `vendor-part-doc` (e.g., `st-stm32h743-datasheet`)
+  - Keep it filesystem-safe (lowercase, digits, hyphens)
+
+### 3) Convert with mineru (Markdown-first)
+
+- Convert using `mcp__mineru__parse_documents`:
+  - Use `enable_ocr=false` by default.
+  - Enable OCR only for scanned PDFs or when extraction quality is poor.
+- Record `extract_path` from the tool output; it contains:
+  - `full.md`
+  - `*_origin.pdf`
+  - optional `images/` folder and other metadata files
+
+### 4) Move outputs into the project and localize images
+
+- Use `scripts/ingest_mineru_extract.ts` to stage the mineru output into the target folder:
+  - Copy `*_origin.pdf` -> `<slug>.pdf`
+  - Copy `full.md` -> `<slug>.md`
+  - Copy `images/` -> `<slug>.assets/images/`
+  - Rewrite Markdown image links from `images/...` to `<slug>.assets/images/...`
+  - Write `<slug>.lock.json` and set generated artifacts to read-only on disk to prevent accidental edits (defaults on).
+  - Create a notes template alongside the generated artifacts (defaults on):
+    - `README.md` when using `--doc-subdir`
+    - `<slug>.README.md` when using a flat layout
+
+Example (flat layout):
+
+```bash
+bun --no-install "$LOOMHELM_TOOLKIT_ROOT/skills/hardware-doc-ingest/scripts/ingest_mineru_extract.ts" \
+  --extract-path "<mineru.extract_path>" \
+  --dest-dir "docs/datasheets" \
+  --slug "st-stm32h743-datasheet" \
+  --add-header \
+  --source-url "<source-url>" \
+  --vendor "ST" \
+  --part "STM32H743"
+```
+
+Example (one folder per doc, recommended):
+
+```bash
+bun --no-install "$LOOMHELM_TOOLKIT_ROOT/skills/hardware-doc-ingest/scripts/ingest_mineru_extract.ts" \
+  --extract-path "<mineru.extract_path>" \
+  --dest-dir "docs/datasheets" \
+  --doc-subdir "st-stm32h743-datasheet" \
+  --slug "st-stm32h743-datasheet"
+```
+
+Re-ingest / regenerate (explicit overwrite):
+
+```bash
+bun --no-install "$LOOMHELM_TOOLKIT_ROOT/skills/hardware-doc-ingest/scripts/ingest_mineru_extract.ts" \
+  --extract-path "<mineru.extract_path>" \
+  --dest-dir "docs/datasheets" \
+  --doc-subdir "st-stm32h743-datasheet" \
+  --slug "st-stm32h743-datasheet" \
+  --overwrite
+```
+
+### 5) Update the docs index
+
+- Prefer updating an existing docs index:
+  - `docs/README.md`, `docs/index.md`, or the repo’s established docs TOC
+- Add a short entry that links to Markdown first, PDF second:
+  - `[Title](docs/.../<slug>.md) ([PDF](docs/.../<slug>.pdf)) — 1–2 line note`
+
+If no docs index exists, create `docs/README.md` and add sections for Datasheets / Manuals / App Notes.
+
+### 6) Future usage: prefer Markdown
+
+When asked about the document contents later, read and cite from `.../<slug>.md` first; use the PDF as a fidelity fallback.
+
+**Never** “edit the datasheet” by changing `.../<slug>.md`. Put your notes in `README.md` (or `<slug>.README.md` for flat layout).
+
+Optional integrity check (useful in CI/pre-commit):
+
+```bash
+bun --no-install "$LOOMHELM_TOOLKIT_ROOT/skills/hardware-doc-ingest/scripts/verify_doc_locks.ts" docs/datasheets
+```
+
+## References (load only when needed)
+
+- Docs index format and examples: `references/docs-index-format.md`

package/toolkit/skills/hardware-doc-ingest/references/docs-index-format.md

@@ -0,0 +1,34 @@
+# Docs index format (hardware PDFs)
+
+Keep index files small and skimmable. Prefer linking to Markdown first, PDF second.
+
+## Recommended section structure
+
+If the repo does not already have a docs TOC, create `docs/README.md` with:
+
+```md
+# Docs
+
+## Datasheets
+
+- [ST STM32H743 Datasheet](datasheets/st-stm32h743-datasheet.md) ([PDF](datasheets/st-stm32h743-datasheet.pdf)) — MCU datasheet; use for pinout, electrical specs.
+
+## Manuals
+
+- [ST RM0433 Reference manual](manuals/st-rm0433-reference-manual.md) ([PDF](manuals/st-rm0433-reference-manual.pdf)) — Peripheral registers and programming model.
+
+## App notes
+
+- [ANxxxx: Foo](app-notes/st-anxxxx-foo.md) ([PDF](app-notes/st-anxxxx-foo.pdf)) — Implementation guidance; note any key constraints.
+
+## Errata
+
+- [ESxxxx: Bar](errata/st-esxxxx-bar.md) ([PDF](errata/st-esxxxx-bar.pdf)) — Known silicon issues; track applied workarounds.
+```
+
+## Entry checklist
+
+- Include vendor + part number (or board name) in the link title.
+- Link Markdown first; include a PDF link for fidelity.
+- Add a 1–2 line note that describes what the doc is _for_.
+- Avoid doc-level revision markers like “Draft/v1/终稿/修订记录”.

package/toolkit/skills/hardware-doc-ingest/scripts/ingest_mineru_extract.ts

@@ -0,0 +1,4 @@
+import { runCompatibilityCli } from "../../bin/compatibility_cli";
+
+if (import.meta.main)
+  process.exitCode = await runCompatibilityCli("ingest_mineru_extract");

package/toolkit/skills/hardware-doc-ingest/scripts/verify_doc_locks.ts

@@ -0,0 +1,4 @@
+import { runCompatibilityCli } from "../../bin/compatibility_cli";
+
+if (import.meta.main)
+  process.exitCode = await runCompatibilityCli("verify_doc_locks");

package/toolkit/skills/implement-only-flow/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: implement-only-flow
+description: "Plan implementation without delivery steps."
+---
+
+# Implement-only flow（仅实现流程）
+
+当主人明确选择 `implement-only / 仅实现` 时使用本 skill。
+
+## 目标
+
+- 产出“可直接实现”的决策完备规格。
+- 不进入交付流水线，不推进分支/提交/PR/合并。
+
+## 核心边界（必须）
+
+- 只做实现规格规划：目标、范围、关键技术决策、接口/数据流、失败场景、验收标准。
+- 禁止包含交付流程条款：分支策略、commit 规则、push、PR、checks/workflows、merge、post-merge cleanup。
+- 禁止在 `implement-only` 计划中引入 spec 创建/迁移/同步任务（如创建 `docs/specs/**`、`docs/plan -> docs/specs` 迁移、spec 同步工单）。
+- 允许说明“未来执行前的前置检查”，但不执行实现动作。
+
+## 实现前门禁（规则声明）
+
+- 任何后续进入实现动作的流程，必须先执行工作区脏区检查：`git status --porcelain`。
+- 检查命中脏区时，默认动作为“阻断并询问 1 个关键问题”；不得隐式继续。
+
+## 与 Plan Mode 协作
+
+- 在 Codex 内置 Plan Mode 中，若主人显式引用 `$dev-plan`，则按其输出契约生成 `<proposed_plan>`；若未显式引用，则保持官方原味 Plan Mode 结构，同时仍遵守本 skill 的实现边界。
+- 流程绑定时，`flow_type=implement-only` 必须绑定本 skill。
+
+## 最低输出要求
+
+- 通过 `Goals / Non-goals` 明确范围边界，不依赖单独的 `Scope & Boundaries` 模板章节。
+- 明确关键接口与数据流。
+- 明确异常/边界与回滚思路。
+- 明确可验证的验收标准。
+- 若需要标记未确认信息，把三态 `存在 / 不存在 / 未检查` 放进假设摘要或状态区；结论与说明部分保持自然中文。

package/toolkit/skills/kaisoumail-deployment-inventory/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: kaisoumail-deployment-inventory
+description: "Use when Codex needs to identify where KaisouMail is currently deployed, which public entrypoints and runtime resources are live, how current provider resources differ from repo config, or which control-plane page should be checked first during ops work. Treat the hosting provider as current verified state, not as a permanent project identity."
+---
+
+# KaisouMail Deployment Inventory
+
+## Quick start
+
+- Read `references/stable-identity.md` before writing owner-facing notes.
+- Read `references/current-topology.md` before making claims about the live deployment.
+- Treat the authenticated control plane and live runtime evidence as the source of truth for current hosting, bindings, public domains, and triggers.
+
+## Working rules
+
+- Use `KaisouMail` as the canonical project / product name.
+- Treat repo slugs, provider resource names, and hosting vendors as mutable implementation details.
+- Distinguish three layers in every ops note: canonical product name, current repo / resource names, current hosting provider.
+- Use `$ego-browser` for interactive verification. Keep an inspected page only when the user asks for it to remain open.
+- Never expose secret values from dashboards; secret names and non-secret resource identifiers are fine.
+
+## Incident flow
+
+1. Identify the current provider and public entrypoints from `references/current-topology.md`.
+2. Open the provider-specific control-plane page listed in that reference.
+3. Compare live resources with checked-in config only after the live state is clear.
+4. Report in this order when possible: outcome -> live evidence -> affected resources -> safe next step.
+
+## Updating the inventory
+
+- Update `references/current-topology.md` when hosting, resource names, domains, bindings, or operational entrypoints change.
+- Keep long-lived naming rules in `references/stable-identity.md`.
+- Keep provider-specific facts in the current-topology reference instead of baking them into the skill name or core instructions.
+
+## References
+
+- `references/stable-identity.md`
+- `references/current-topology.md`

package/toolkit/skills/kaisoumail-deployment-inventory/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "KaisouMail Deployment Inventory"
+  short_description: "Check live deployment inventory and drift"
+  default_prompt: "Use $kaisoumail-deployment-inventory to verify where KaisouMail is currently deployed and which live resources are attached."
+
+policy:
+  allow_implicit_invocation: false