From 6cc8833b2affc2ab0ec854226352912450ffb40e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=98=9F=E6=9C=88?= <xingyue@shazhou.work>
Date: Thu, 23 Apr 2026 15:00:07 +0800
Subject: [PATCH 1/2] chore: add cursor rules and annotate legitimate dynamic
 imports

- Add .cursor/rules/no-dynamic-import.mdc: ban dynamic import() in
  production code with documented exceptions
- Add .cursor/rules/gitea-access.mdc: tea CLI usage guide
- Add explanatory comments on the 2 legitimate dynamic imports in
  sense-runtime.ts and workflow-worker.ts
---
 .cursor/rules/gitea-access.mdc         | 38 ++++++++++++++++++++++++++
 .cursor/rules/no-dynamic-import.mdc    | 34 +++++++++++++++++++++++
 packages/daemon/src/sense-runtime.ts   |  1 +
 packages/daemon/src/workflow-worker.ts |  1 +
 4 files changed, 74 insertions(+)
 create mode 100644 .cursor/rules/gitea-access.mdc
 create mode 100644 .cursor/rules/no-dynamic-import.mdc

diff --git a/.cursor/rules/gitea-access.mdc b/.cursor/rules/gitea-access.mdc
new file mode 100644
index 0000000..3a5d925
--- /dev/null
+++ b/.cursor/rules/gitea-access.mdc
@@ -0,0 +1,38 @@
+---
+description: Gitea access for git.shazhou.work via tea CLI
+globs: "**/*"
+alwaysApply: false
+---
+
+# Gitea Access (git.shazhou.work)
+
+Use the `tea` CLI to interact with our self-hosted Gitea instance.
+Login is pre-configured (user: xingyue, default login: shazhou).
+
+## Commands
+
+```bash
+# List open issues (from within a repo)
+tea issues
+
+# Read a specific issue with comments
+tea issues 3
+
+# List all issues including closed
+tea issues --state all
+
+# Specify repo explicitly (when not in repo dir)
+tea issues --repo uncaged/nerve
+
+# List PRs
+tea pr
+
+# Create issue
+tea issues create --title "..." --body "..."
+```
+
+## When to use
+
+- When a task references a Gitea issue number, ALWAYS read the issue first to get full context
+- When starting work on a feature, check related open issues
+- `tea` auto-detects owner/repo from the current git remote
diff --git a/.cursor/rules/no-dynamic-import.mdc b/.cursor/rules/no-dynamic-import.mdc
new file mode 100644
index 0000000..5378994
--- /dev/null
+++ b/.cursor/rules/no-dynamic-import.mdc
@@ -0,0 +1,34 @@
+---
+description: Ban dynamic import() in production code — use static imports instead
+globs: packages/*/src/**/*.ts
+alwaysApply: true
+---
+
+# No Dynamic Import in Production Code
+
+## Rule
+
+Do NOT use `await import()` or dynamic `import()` expressions in production source code.
+Always use static top-level `import` statements.
+
+## Why
+
+- Static imports enable tree-shaking and bundler optimizations
+- They make dependencies explicit and discoverable at a glance
+- Dynamic imports of Node built-ins or project modules add unnecessary async overhead
+
+## Exceptions (must include a comment explaining why)
+
+1. **`sense-runtime.ts`** — loads user-authored sense modules whose paths are only known at runtime
+2. **`workflow-worker.ts`** — loads user-authored workflow modules whose paths are only known at runtime
+
+When suppressing, add a comment directly above:
+
+```ts
+// Dynamic import required: user module path resolved at runtime
+const mod = await import(senseIndexPath);
+```
+
+## Test Files
+
+Test files (`__tests__/**`) are exempt — dynamic import after `vi.mock()` is standard vitest practice.
diff --git a/packages/daemon/src/sense-runtime.ts b/packages/daemon/src/sense-runtime.ts
index 0b7021c..2baf01a 100644
--- a/packages/daemon/src/sense-runtime.ts
+++ b/packages/daemon/src/sense-runtime.ts
@@ -173,6 +173,7 @@ export async function loadComputeFn(senseIndexPath: string): Promise<Result<Comp
   let mod: unknown;
 
   try {
+    // Dynamic import required: user-authored sense module, path resolved at runtime
     mod = await import(senseIndexPath);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
diff --git a/packages/daemon/src/workflow-worker.ts b/packages/daemon/src/workflow-worker.ts
index e405900..93ab550 100644
--- a/packages/daemon/src/workflow-worker.ts
+++ b/packages/daemon/src/workflow-worker.ts
@@ -197,6 +197,7 @@ async function loadWorkflowDefinition(
     );
   }
 
+  // Dynamic import required: user-authored workflow module, path resolved at runtime
   const mod = await import(indexPath);
   const def: unknown = mod.default ?? mod;
 
-- 
2.43.0


From 9102c6698aa02b7da3a37bae43e0b28cefd8e5b1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=98=9F=E6=9C=88?= <xingyue@shazhou.work>
Date: Thu, 23 Apr 2026 15:03:14 +0800
Subject: [PATCH 2/2] chore: remove gitea-access rule from project (belongs in
 agent local skills)

---
 .cursor/rules/gitea-access.mdc | 38 ----------------------------------
 1 file changed, 38 deletions(-)
 delete mode 100644 .cursor/rules/gitea-access.mdc

diff --git a/.cursor/rules/gitea-access.mdc b/.cursor/rules/gitea-access.mdc
deleted file mode 100644
index 3a5d925..0000000
--- a/.cursor/rules/gitea-access.mdc
+++ /dev/null
@@ -1,38 +0,0 @@
----
-description: Gitea access for git.shazhou.work via tea CLI
-globs: "**/*"
-alwaysApply: false
----
-
-# Gitea Access (git.shazhou.work)
-
-Use the `tea` CLI to interact with our self-hosted Gitea instance.
-Login is pre-configured (user: xingyue, default login: shazhou).
-
-## Commands
-
-```bash
-# List open issues (from within a repo)
-tea issues
-
-# Read a specific issue with comments
-tea issues 3
-
-# List all issues including closed
-tea issues --state all
-
-# Specify repo explicitly (when not in repo dir)
-tea issues --repo uncaged/nerve
-
-# List PRs
-tea pr
-
-# Create issue
-tea issues create --title "..." --body "..."
-```
-
-## When to use
-
-- When a task references a Gitea issue number, ALWAYS read the issue first to get full context
-- When starting work on a feature, check related open issues
-- `tea` auto-detects owner/repo from the current git remote
-- 
2.43.0