@gordon.gan/specflow 1.4.3-beta → 1.4.4-beta

package/README.md

@@ -126,7 +126,7 @@ npm install -g @gordon.gan/specflow
 npm install -g github:Gordon-Gan-Jiang/specflow
 
 # 验证
-specflow --version   # 以 npm / package.json 为准（当前 1.4.3-beta）
+specflow --version   # 以 npm / package.json 为准（当前 1.4.4-beta）
 specflow --help
 ```
 

package/dist/core/project-config.d.ts

@@ -6,6 +6,9 @@ export interface NormalizedReference {
     readonly id: string;
     readonly remote?: string;
 }
+export declare const CONVENTION_TOPICS: readonly ["architecture", "api", "database", "frontend"];
+export type ConventionTopic = (typeof CONVENTION_TOPICS)[number];
+export type ProjectConventions = Readonly<Partial<Record<ConventionTopic, readonly string[]>>>;
 export interface ParsedProjectConfig {
     readonly schema: string;
     readonly context?: string;
@@ -14,6 +17,7 @@ export interface ParsedProjectConfig {
     readonly workflowUpstream?: string;
     readonly store?: string;
     readonly references: readonly NormalizedReference[];
+    readonly conventions: ProjectConventions;
     readonly diagnostics: readonly Diagnostic[];
 }
 export declare function parseProjectConfig(raw: unknown): ParsedProjectConfig;

package/dist/core/project-config.js

@@ -12,6 +12,12 @@ const ReferenceObjectSchema = z
     remote: z.string().url().optional(),
 })
     .strict();
+export const CONVENTION_TOPICS = [
+    'architecture',
+    'api',
+    'database',
+    'frontend',
+];
 function referenceDiagnostic(message, target) {
     return {
         severity: 'warning',
@@ -155,6 +161,48 @@ export function parseProjectConfig(raw) {
             fix: `Add '${workflowUpstream}' to specflow/config.yaml references.`,
         });
     }
+    const conventions = {};
+    if (record.conventions !== undefined) {
+        const conventionsRaw = typeof record.conventions === 'object' &&
+            record.conventions !== null &&
+            !Array.isArray(record.conventions)
+            ? record.conventions
+            : undefined;
+        if (!conventionsRaw) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'invalid_conventions_config',
+                message: 'Project conventions must be an object of topic → path arrays.',
+                target: 'config.conventions',
+                fix: 'Use conventions.architecture|api|database|frontend: [relative/path.md].',
+            });
+        }
+        else {
+            for (const topic of CONVENTION_TOPICS) {
+                const value = conventionsRaw[topic];
+                if (value === undefined) {
+                    continue;
+                }
+                if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'invalid_conventions_topic',
+                        message: `conventions.${topic} must be an array of relative file path strings.`,
+                        target: `config.conventions.${topic}`,
+                        fix: `Set conventions.${topic} to e.g. ['docs/engineering/${topic}.md'].`,
+                    });
+                    continue;
+                }
+                const paths = value
+                    .map((item) => item.trim())
+                    .filter((item) => item.length > 0)
+                    .slice(0, 3);
+                if (paths.length > 0) {
+                    conventions[topic] = paths;
+                }
+            }
+        }
+    }
     return {
         schema,
         context,
@@ -163,6 +211,7 @@ export function parseProjectConfig(raw) {
         workflowUpstream,
         store,
         references,
+        conventions,
         diagnostics,
     };
 }

package/dist/core/project-conventions.d.ts

@@ -0,0 +1,15 @@
+import { type ConventionTopic, type ProjectConventions } from './project-config.js';
+export type IdeFlavor = 'cursor' | 'claude' | 'codex';
+/**
+ * Resolves project convention files for an approval topic.
+ * Priority: config conventions.<topic> → repo-neutral docs.
+ * IDE-specific rule/skill globs are documented for the agent to scan; this helper
+ * covers the deterministic, config + neutral paths used in tests and tooling.
+ */
+export declare function resolveProjectConventionPaths(input: {
+    readonly projectRoot: string;
+    readonly topic: ConventionTopic;
+    readonly conventions?: ProjectConventions;
+}): readonly string[];
+export declare function listConventionTopics(): readonly ConventionTopic[];
+export declare function neutralCandidatesFor(topic: ConventionTopic): readonly string[];

package/dist/core/project-conventions.js

@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CONVENTION_TOPICS, } from './project-config.js';
+const NEUTRAL_CANDIDATES = {
+    architecture: [
+        'docs/engineering/architecture.md',
+        '.specflow/conventions/architecture.md',
+        'ARCHITECTURE.md',
+    ],
+    api: [
+        'docs/api/guidelines.md',
+        'docs/engineering/api.md',
+        '.specflow/conventions/api.md',
+    ],
+    database: [
+        'docs/db/conventions.md',
+        'docs/engineering/database.md',
+        '.specflow/conventions/database.md',
+    ],
+    frontend: [
+        'docs/frontend/conventions.md',
+        'docs/frontend/patterns.md',
+        'docs/frontend/testing.md',
+        'docs/engineering/frontend.md',
+        '.specflow/conventions/frontend.md',
+        'agent_docs/tech_stack.md',
+        'agent_docs/code_patterns.md',
+        'agent_docs/testing.md',
+    ],
+};
+const MAX_FILES_PER_TOPIC = 3;
+function existingRelative(projectRoot, relativePaths) {
+    const found = [];
+    for (const relative of relativePaths) {
+        const normalized = relative.replace(/^\.\//, '').replace(/\\/g, '/');
+        if (!normalized || normalized.includes('..')) {
+            continue;
+        }
+        if (existsSync(join(projectRoot, ...normalized.split('/')))) {
+            found.push(normalized);
+        }
+        if (found.length >= MAX_FILES_PER_TOPIC) {
+            break;
+        }
+    }
+    return found;
+}
+/**
+ * Resolves project convention files for an approval topic.
+ * Priority: config conventions.<topic> → repo-neutral docs.
+ * IDE-specific rule/skill globs are documented for the agent to scan; this helper
+ * covers the deterministic, config + neutral paths used in tests and tooling.
+ */
+export function resolveProjectConventionPaths(input) {
+    const configured = input.conventions?.[input.topic];
+    if (configured && configured.length > 0) {
+        return existingRelative(input.projectRoot, configured.slice(0, MAX_FILES_PER_TOPIC));
+    }
+    return existingRelative(input.projectRoot, NEUTRAL_CANDIDATES[input.topic]);
+}
+export function listConventionTopics() {
+    return CONVENTION_TOPICS;
+}
+export function neutralCandidatesFor(topic) {
+    return NEUTRAL_CANDIDATES[topic];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.4.3-beta",
+  "version": "1.4.4-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [

package/prompts/approval/database-guidance.md

@@ -1,11 +1,9 @@
 # Approval · Database Guidance Router
 
-> Used by `/specflow:approval` when generating §4.4 (数据结构 / 数据模型).  
-> **Guidance pack**: `database`（见 `skills/guidance-packs.yaml` / `skills/GUIDANCE_PACKS.md`）。  
-> **业务仓落地**: `{ide}/specflow/guidance/database/`（`specflow init` 同步；**不是** IDE skill）。  
-> **禁止**依赖远程 skill 仓库（禁止 `npx skills add` / clone / 运行时 fetch）。  
-> **Not** an MCP tool — on hit, `Read` local matched skill files; on miss, LLM-only §4.4.  
-> **禁止**写成「invoke `/mysql` skill」——一律 `Read` 路径。
+> **本地技能**: SpecFlow pack 在 `{ide}/specflow/guidance/database/`(见 `skills/guidance-packs.yaml`)。  
+> **项目约定**: 写 §4.4 **之前**还须执行 `prompts/approval/project-conventions-guidance.md`(`topic=database`)。  
+> **优先级**: 项目约定 + 现网 DDL **>** 本文件 SpecFlow guidance **>** LLM-fallback。  
+> **禁止**依赖远程 skill 仓库; **Not** an MCP tool; 禁止「invoke `/mysql` skill」。
 
 ---
 
@@ -58,6 +56,9 @@ Guidance: <.cursor|claude|agents>/specflow/guidance/database/<stack>/SKILL.md
 
 ## 3. On hit — load **local** guidance (Read, do not invent, do not fetch)
 
+> 先完成 `project-conventions-guidance.md` 的 `topic=database` 解析并 Read 项目约定(若有)。  
+> 本表仅加载 **SpecFlow** guidance pack,用于补强 DDL 写法;不得覆盖项目禁令。
+
 Base = resolved `guidanceRoot` above. From that directory:
 
 | Stack | Must Read | Also Read when §4.4 needs it |
@@ -76,8 +77,9 @@ Apply guidance to §4.4 output:
 2. Prefer type/index gotchas from the skill (e.g. DECIMAL for money, no FLOAT amounts).
 3. Keep SpecFlow hard rules (ER, full CREATE TABLE, 本迭代用法, G3/G4) — skill **supplements**, does not replace.
 
-Cite in §4.4 总则 the **actual** path used, e.g.  
-`DB 技能: .cursor/specflow/guidance/database/mysql` 或 `skills/database/mysql (package fallback)`.
+Cite in §4.4 总则 the **actual** paths used:
+- `项目约定: <path…> | 未发现`
+- `DB 技能: .cursor/specflow/guidance/database/mysql` 或 `skills/database/mysql (package fallback)` 或 `LLM-fallback`
 
 ---
 

package/prompts/approval/frontend-guidance.md

@@ -0,0 +1,249 @@
+# Approval · Frontend Guidance Router
+
+> Used by `/specflow:approval` when the change touches **UI / 控制台 / 页面 / 组件**.  
+> **项目约定**: 写 **§4.6** 前必须执行 `project-conventions-guidance.md`(`topic=frontend`)，
+> **并**按本文件 §3 补扫 IDE skills / rules / 落地规约(组件、样式、表单、测试等)。  
+> **优先级**: 项目约定 + IDE skills/rules + 现网页面/组件/路由 **>** 本文件结构硬门槛 **>** LLM。  
+> **Not** an MCP tool; **禁止** `invoke /react` 之类 IDE skill 口号 —— 一律解析路径后 `Read`。  
+> 灵感对齐 vibe-coding Part3 Frontend（栈五元组 / 目录分层 / Visual Loop），**不**搬 MVP 访谈问卷。
+
+---
+
+## 1. Detect `uiInScope`
+
+Scan proposal / design / tasks / specs (and Tech Stack Intake answers) for UI signals:
+
+| Signal (any) | Meaning |
+|--------------|---------|
+| 控制台 / 前端 / UI / 页面 / 路由 / 组件 / 表单 / 弹窗 | UI work in scope |
+| `*.tsx` / `*.vue` / `*.svelte` / `pages/` / `app/` router paths in tasks | UI work in scope |
+| §2.2 前端行非「不涉及」 | UI work in scope |
+| Explicit「不涉及前端」+ no UI paths | `uiInScope=false` |
+
+**Announce**:
+
+```text
+UI in scope for approval: yes | no
+FE stack: <detected or user-confirmed or unknown>
+Project conventions (frontend): <paths…> | none
+IDE FE skills/rules: <paths…> | none
+```
+
+If `uiInScope=no` → omit entire §4.6 from `approval.md`(write one line under detailed design
+optional checklist only if needed: `不涉及前端/UI 变更`). Do **not** invent pages.
+
+---
+
+## 2. Detect frontend stack (signals)
+
+Project root / common app dirs (non-recursive first; optional `apps/*` / `web/` / `frontend/` one level):
+
+| Signal | Suggested FE |
+|--------|--------------|
+| `next` / `next.config.*` | Next.js |
+| `vite` + `react` | React + Vite |
+| `vue` / `nuxt` | Vue / Nuxt |
+| `svelte` / `@sveltejs/kit` | Svelte / SvelteKit |
+| `@angular/core` | Angular |
+| `react-native` / `expo` | React Native |
+| `tailwindcss` | Styling: Tailwind |
+| `zustand` / `@reduxjs/toolkit` / `pinia` / `jotai` | State hint |
+| `shadcn` / `@mui` / `antd` / `element-plus` | UI kit hint |
+
+Record a **五元组** for §2.2 / §4.6.1 (fill unknowns via Intake, never invent):
+
+1. **Framework** — e.g. React+TS / Next.js / Vue3  
+2. **Styling** — Tailwind / CSS Modules / 现网设计系统  
+3. **State** — Zustand / Redux / Pinia / 仅服务端状态 …  
+4. **UI kit** — shadcn / Ant Design / 公司组件库 / Custom  
+5. **FE testing** — Vitest+RTL / Playwright / Cypress / 项目现网命令  
+
+If `uiInScope=yes` and any of Framework / Styling / State is still unknown after artifacts +
+signals → **STOP** and ask (merge into Tech Stack Intake; do not invent):
+
+```text
+本变更含前端/UI，请补全前端技术选型（可写「沿用现网」）:
+1. Framework / 语言
+2. Styling / 设计系统
+3. 状态管理（client vs server state 偏好）
+4. UI 组件库（或公司内部库）
+5. 前端验证方式（单测 / 组件测 / E2E / browser 手测命令）
+6.（可选）若用 v0/Lovable 等 AI builder 起稿：导出与本地可构建计划
+```
+
+---
+
+## 3. Load implementation conventions (项目约定 + IDE skills/rules + 落地文档)
+
+> **目的**:§4.6 不是只选栈,还要让 apply 阶段能按**本仓真实落地规约**写页面/组件。  
+> **硬规则**:`uiInScope=yes` 时,起草 §4.6 **之前**必须完成本节;禁止跳过 IDE skills/rules 扫描。  
+> **预算**:合计最多 **Read 5 个文件**(配置路径优先占满预算;细节 reference 仅入口点名后再读,禁止链式跳转)。
+
+### 3.1 加载顺序(固定)
+
+1. **`project-conventions-guidance.md` `topic=frontend`**  
+   - 先 `specflow/config.yaml` → `conventions.frontend`  
+   - 再仓根中立 docs(见该路由 §2.2)  
+2. **IDE skills / rules / 记忆文件**(本会话 `activeIde` 优先,再 cursor → claude → agents 回退)  
+3. **落地向 agent/工程文档**(若尚未纳入预算)  
+4. **现网锚点**(Pass 6:路由/布局/API client,**仅读 design/tasks 点名的文件**)
+
+**Priority**: ① 项目约定 + IDE skills/rules + 现网 UI **>** ② §4.6 骨架 **>** ③ LLM。
+
+### 3.2 必须覆盖的「开发落地」主题(按需匹配文件)
+
+扫描/选取文件时,优先覆盖下列维度(有则 Read,无则在 §4.6.1 写「未发现」——**禁止臆造**):
+
+| 落地维度 | 写入 §4.6 何处 | 典型关键词 / 文件名线索 |
+|----------|----------------|-------------------------|
+| 目录与命名(components/features/pages) | 4.6.1 / 4.6.3 | `structure`, `folder`, `naming`, `feature-based` |
+| 组件边界与复用(ui vs features) | 4.6.3 | `component`, `design.?system`, `shadcn`, `storybook` |
+| 路由 / 信息架构 | 4.6.2 | `router`, `routing`, `app.?router`, `pages` |
+| 状态与数据获取 | 4.6.4 | `state`, `zustand`, `redux`, `react.?query`, `swr`, `pinia` |
+| 表单与校验 | 4.6.3 / 4.6.4 | `form`, `zod`, `yup`, `validation`, `rhf` |
+| API client / 错误呈现(Toast/Alert) | 4.6.3 / 4.6.4 + 挂 §4.5 | `api.?client`, `fetch`, `axios`, `toast`, `error.?boundary` |
+| 样式 / Token / 主题 | 4.6.1 / 4.6.5 | `tailwind`, `css`, `theme`, `token`, `styled` |
+| 无障碍 / 响应式 | 4.6.5 | `a11y`, `accessibility`, `responsive`, `breakpoint` |
+| i18n | 4.6.1 备注 / 4.6.3 | `i18n`, `locale`, `intl` |
+| 测试与 Visual Loop 命令 | 4.6.5 + §6 | `vitest`, `playwright`, `cypress`, `rtl`, `testing`, `e2e` |
+| Lint / format 禁令 | §2.1 约束 + 4.6.1 | `eslint`, `prettier`, `stylelint`, `biome` |
+
+### 3.3 IDE 扫描清单(解析路径后 Read,禁止 invoke)
+
+对每个命中路径:**先看文件名/frontmatter `name`/`description`/首段标题**,与上表关键词匹配再纳入预算。
+
+**Cursor**
+
+| 类型 | 路径模式 |
+|------|----------|
+| Rules | `.cursor/rules/**/*.mdc`(及 `.md`) |
+| Skills | `.cursor/skills/**/SKILL.md` |
+| 其它 | `.cursor/rules` 下与 FE 相关的聚合 rule |
+
+**Claude**
+
+| 类型 | 路径模式 |
+|------|----------|
+| Skills | `.claude/skills/**/SKILL.md` |
+| Rules | `.claude/rules/**/*` |
+| 记忆 | `CLAUDE.md` / `.claude/CLAUDE.md`(只抽取 FE 相关章节,勿整文件灌入上下文) |
+
+**Codex**
+
+| 类型 | 路径模式 |
+|------|----------|
+| Skills | `.agents/skills/**/SKILL.md` |
+| 记忆 | `AGENTS.md`(只抽取 FE 相关段落) |
+
+**仓根 / 中立落地文档(补充候选,与 conventions 路由合并去重)**
+
+| 路径 |
+|------|
+| `docs/frontend/**/*.md`(优先 `conventions.md` / `patterns.md` / `testing.md`) |
+| `docs/engineering/frontend.md` |
+| `.specflow/conventions/frontend.md` |
+| `agent_docs/tech_stack.md` |
+| `agent_docs/code_patterns.md` |
+| `agent_docs/testing.md` |
+| `REVIEW-CHECKLIST.md`(仅 UI/前端相关条目) |
+
+**关键词**(文件名 + 标题 + skill description,大小写不敏感):
+
+```text
+frontend|front-end|ui|ux|react|vue|next|nuxt|svelte|angular|
+tailwind|component|design-system|design system|css|style|
+router|routing|form|zod|state|zustand|redux|pinia|query|
+playwright|vitest|cypress|testing-library|a11y|accessibility|
+i18n|控制台|前端|页面|组件|样式|表单|路由
+```
+
+### 3.4 选取与冲突
+
+1. `conventions.frontend` 配置路径 **最先占用预算**。  
+2. 其次 activeIde 命中的 skill/rule(每类优先 1–2 个最相关)。  
+3. 再补仓根 `agent_docs/*` / `docs/frontend/*`。  
+4. 同主题多文件内容冲突 → **以 config / 仓根中立 docs 为准**,IDE skill 仅作补充;在 §4.6.1 注明。  
+5. 发现硬禁令(例:「禁止新建全局 CSS」「必须用公司 Button」)→ 写入 §2.1 与 §4.6,违反则 chat/`§8` WARNING。
+
+### 3.5 写入总则
+
+Cite in §4.6.1:
+
+| 项 | 填法 |
+|----|------|
+| 项目约定 | config + 中立 docs 路径,`; ` 分隔 / **未发现** |
+| IDE skills/rules | 实际 Read 的 skill/rule 路径 / **未发现** |
+| FE 栈 | 五元组摘要 \| 用户确认 \| 沿用现网 |
+
+Announce 示例:
+
+```text
+Project conventions (frontend): docs/frontend/conventions.md
+IDE FE skills/rules: .cursor/rules/frontend.mdc; .cursor/skills/ui-patterns/SKILL.md
+Conflict policy: project > IDE conventions > SpecFlow §4.6 skeleton > LLM
+```
+
+---
+
+## 4. §4.6 output contract (when `uiInScope=yes`)
+
+Follow `generate.md` §4.6 exactly. Outline hygiene:
+
+```text
+### 4.6 前端 / UI 设计
+├── #### 4.6.1 总则与本迭代结论
+├── #### 4.6.2 信息架构与路由
+├── #### 4.6.3 关键页面 / 组件详设
+│   └── ##### Page · <短名>   ← 每页仅此一级标题
+├── #### 4.6.4 状态与数据获取
+└── #### 4.6.5 视觉与验证回路
+```
+
+Labels such as「空态」「加载」「错误」「依赖接口」are `**bold**`, never extra headings.
+
+Apply loaded conventions into the body:
+
+- 目录/命名禁令 → 4.6.1「本迭代不涉及」与 4.6.3 组件边界  
+- 状态/表单/API client 模式 → 4.6.4(写「采用项目约定:<path>」)  
+- a11y/响应式/测试命令 → 4.6.5  
+- **禁止**把 skill 原文整段粘贴进 approval;用可读中文转述硬约束
+
+**Quality gates (UI path)**:
+
+| ID | Rule |
+|----|------|
+| **G5** | 必须有本迭代**页面/路由清单**(禁止只写「用 React」) |
+| **G6** | 每个关键 `Page · …` 至少覆盖 **空态 / 加载 / 错误** 之一,并标明依赖的 §4.5 `In` |
+
+**Visual Verification Loop** (write into §4.6.5 + feed §6 when useful):
+
+1. **Generate** — AI/人产出组件  
+2. **Render** — dev server 或 headless browser  
+3. **Inspect** — 截图 / 设计原则 / a11y 抽查  
+4. **Refine** — 修视觉与交互回归后再合入  
+
+Record exact `dev` / `test` / `browser` commands when known (from conventions / IDE skills / Intake).
+
+**Builder exit** (only if AI builder used): source ownership + local install/dev/test + secrets
+handling + exit plan — put under §4.6.1 备注 or §2.5 风险; do not pad marketing lists.
+
+---
+
+## 5. Cross-links
+
+- Pages that call APIs **must** reference §4.5 interface numbers (`I1…`).  
+- User journeys in §1.3 / Happy Path §4.2 should name the same pages.  
+- §3 architecture may show「控制台 / Web」box; details live in §4.6, not duplicated as
+  code-dump trees in §2.1.
+
+---
+
+## 6. On miss / fallback
+
+| Case | Action |
+|------|--------|
+| `uiInScope=no` | Omit §4.6 |
+| `uiInScope=yes`, no conventions / no IDE FE skills | Draft §4.6 with skeleton + Intake;`项目约定: 未发现`;`IDE skills/rules: 未发现`; chat 可 WARNING 建议补 `docs/frontend/conventions.md` 或 Cursor rule |
+| User refuses FE selection while UI required | `[待 refine 澄清: 前端技术选型]`; do not fabricate page trees |
+| Only API change, no UI | §4.5 only; §4.6 omitted |
+| IDE skill 与仓根约定冲突 | 仓根/config 优先;记 WARNING |