@gordon.gan/specflow 1.4.2-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.2-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/dist/integrations/claude/adapter.js

@@ -69,6 +69,7 @@ async function inspectClaude(projectRoot) {
     const promptsDir = join(projectRoot, '.claude', 'specflow', 'prompts');
     const schemasDir = join(projectRoot, '.claude', 'specflow', 'schemas');
     const templatesDir = join(projectRoot, '.claude', 'specflow', 'templates');
+    const guidanceDir = join(projectRoot, '.claude', 'specflow', 'guidance');
     const supported = [];
     const skillContentsByCommand = {};
     for (const command of COMMAND_CATALOG) {
@@ -98,6 +99,7 @@ async function inspectClaude(projectRoot) {
             runtimePromptsDir: { exists: await directoryExists(promptsDir), hash: await hashDirectoryTree(promptsDir) },
             runtimeSchemasDir: { exists: await directoryExists(schemasDir), hash: await hashDirectoryTree(schemasDir) },
             runtimeTemplatesDir: { exists: await directoryExists(templatesDir), hash: await hashDirectoryTree(templatesDir) },
+            runtimeGuidanceDir: { exists: await directoryExists(guidanceDir), hash: await hashDirectoryTree(guidanceDir) },
         },
     };
 }

package/dist/integrations/codex/adapter.js

@@ -40,6 +40,7 @@ function renderCodexAgentsBlock() {
         '- Use artifacts under specflow/changes/<change>/ before coding',
         '- Workflow skills: $specflow-explore, $specflow-propose, $specflow-refine, $specflow-apply, $specflow-review, $specflow-test, $specflow-verify, $specflow-archive, $specflow-fix, $specflow-snap',
         '- Runtime prompts live under .agents/specflow/prompts/',
+        '- Guidance packs (non-IDE skills) live under .agents/specflow/guidance/',
         '',
     ].join('\n');
 }
@@ -96,6 +97,7 @@ async function inspectCodex(projectRoot) {
     const promptsDir = join(projectRoot, '.agents', 'specflow', 'prompts');
     const schemasDir = join(projectRoot, '.agents', 'specflow', 'schemas');
     const templatesDir = join(projectRoot, '.agents', 'specflow', 'templates');
+    const guidanceDir = join(projectRoot, '.agents', 'specflow', 'guidance');
     let agentsFileExists = false;
     try {
         const agentsContent = await fs.readFile(agentsFile, 'utf-8');
@@ -134,6 +136,7 @@ async function inspectCodex(projectRoot) {
             runtimePromptsDir: { exists: await directoryExists(promptsDir), hash: await hashDirectoryTree(promptsDir) },
             runtimeSchemasDir: { exists: await directoryExists(schemasDir), hash: await hashDirectoryTree(schemasDir) },
             runtimeTemplatesDir: { exists: await directoryExists(templatesDir), hash: await hashDirectoryTree(templatesDir) },
+            runtimeGuidanceDir: { exists: await directoryExists(guidanceDir), hash: await hashDirectoryTree(guidanceDir) },
         },
     };
 }

package/dist/integrations/cursor/adapter.js

@@ -89,6 +89,7 @@ async function inspectCursor(projectRoot) {
     const promptsDir = join(projectRoot, '.cursor', 'specflow', 'prompts');
     const schemasDir = join(projectRoot, '.cursor', 'specflow', 'schemas');
     const templatesDir = join(projectRoot, '.cursor', 'specflow', 'templates');
+    const guidanceDir = join(projectRoot, '.cursor', 'specflow', 'guidance');
     const supported = [];
     const skillContentsByCommand = {};
     for (const command of COMMAND_CATALOG) {
@@ -119,6 +120,7 @@ async function inspectCursor(projectRoot) {
             runtimePromptsDir: { exists: await directoryExists(promptsDir), hash: await hashDirectoryTree(promptsDir) },
             runtimeSchemasDir: { exists: await directoryExists(schemasDir), hash: await hashDirectoryTree(schemasDir) },
             runtimeTemplatesDir: { exists: await directoryExists(templatesDir), hash: await hashDirectoryTree(templatesDir) },
+            runtimeGuidanceDir: { exists: await directoryExists(guidanceDir), hash: await hashDirectoryTree(guidanceDir) },
         },
     };
 }

package/dist/integrations/shared/parity-comparator.js

@@ -4,6 +4,7 @@ import { CAPABILITY_MANIFEST, IDE_ASSET_MANIFEST } from './parity-manifest.js';
 const PARITY_COMPARABLE_ASSET_KEYS = [
     'runtimeSchemasDir',
     'runtimeTemplatesDir',
+    'runtimeGuidanceDir',
 ];
 export function validateReportAgainstManifest(report) {
     const deltas = [];

package/dist/integrations/shared/parity-manifest.js

@@ -42,6 +42,7 @@ export const IDE_ASSET_MANIFEST = [
             'runtimePromptsDir',
             'runtimeSchemasDir',
             'runtimeTemplatesDir',
+            'runtimeGuidanceDir',
         ],
     },
     {
@@ -53,6 +54,7 @@ export const IDE_ASSET_MANIFEST = [
             'runtimePromptsDir',
             'runtimeSchemasDir',
             'runtimeTemplatesDir',
+            'runtimeGuidanceDir',
         ],
     },
     {
@@ -63,6 +65,7 @@ export const IDE_ASSET_MANIFEST = [
             'runtimePromptsDir',
             'runtimeSchemasDir',
             'runtimeTemplatesDir',
+            'runtimeGuidanceDir',
         ],
     },
 ];

package/dist/integrations/shared/runtime-assets.d.ts

@@ -1,2 +1,15 @@
 import type { IdeTarget } from './types.js';
+export declare function ideRootDir(ide: IdeTarget): string;
+interface GuidancePackSpec {
+    readonly id: string;
+    readonly source: string;
+    readonly installAs: string;
+    readonly consumers?: readonly string[];
+}
+/**
+ * Loads guidance pack registry from skills/guidance-packs.yaml.
+ * Missing or empty registry → no packs (non-fatal).
+ */
+export declare function loadGuidancePacks(packageRoot: string): Promise<readonly GuidancePackSpec[]>;
 export declare function copyRuntimeAssets(packageRoot: string, projectRoot: string, ide: IdeTarget): Promise<readonly string[]>;
+export {};

package/dist/integrations/shared/runtime-assets.js

@@ -1,7 +1,9 @@
+import { promises as fs } from 'node:fs';
 import { join } from 'node:path';
+import yaml from 'js-yaml';
 import { copyDirRecursive, copyDirRecursiveRendered } from './asset-copy.js';
 import { renderIdeContent } from './skill-renderer.js';
-function ideRootDir(ide) {
+export function ideRootDir(ide) {
     if (ide === 'claude') {
         return '.claude';
     }
@@ -10,12 +12,48 @@ function ideRootDir(ide) {
     }
     return '.agents';
 }
+/**
+ * Loads guidance pack registry from skills/guidance-packs.yaml.
+ * Missing or empty registry → no packs (non-fatal).
+ */
+export async function loadGuidancePacks(packageRoot) {
+    const registryPath = join(packageRoot, 'skills', 'guidance-packs.yaml');
+    let content;
+    try {
+        content = await fs.readFile(registryPath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const parsed = yaml.load(content);
+    if (!parsed || !Array.isArray(parsed.packs)) {
+        return [];
+    }
+    return parsed.packs.filter((pack) => typeof pack?.id === 'string' &&
+        typeof pack?.source === 'string' &&
+        typeof pack?.installAs === 'string');
+}
+async function copyGuidancePacks(packageRoot, specflowRoot) {
+    const packs = await loadGuidancePacks(packageRoot);
+    for (const pack of packs) {
+        const src = join(packageRoot, ...pack.source.split('/'));
+        const dest = join(specflowRoot, ...pack.installAs.split('/'));
+        await copyDirRecursive(src, dest);
+    }
+}
 export async function copyRuntimeAssets(packageRoot, projectRoot, ide) {
-    const root = join(projectRoot, ideRootDir(ide), 'specflow');
+    const ideRoot = ideRootDir(ide);
+    const root = join(projectRoot, ideRoot, 'specflow');
     const promptsSrc = join(packageRoot, 'prompts');
     const promptsDest = join(root, 'prompts');
     await copyDirRecursiveRendered(promptsSrc, promptsDest, (content) => renderIdeContent(content, ide));
     await copyDirRecursive(join(packageRoot, 'schemas'), join(root, 'schemas'));
     await copyDirRecursive(join(packageRoot, 'templates'), join(root, 'templates'));
-    return [`${ideRootDir(ide)}/specflow/prompts`, `${ideRootDir(ide)}/specflow/schemas`, `${ideRootDir(ide)}/specflow/templates`];
+    await copyGuidancePacks(packageRoot, root);
+    return [
+        `${ideRoot}/specflow/prompts`,
+        `${ideRoot}/specflow/schemas`,
+        `${ideRoot}/specflow/templates`,
+        `${ideRoot}/specflow/guidance`,
+    ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.4.2-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,9 +1,9 @@
 # Approval · Database Guidance Router
 
-> Used by `/specflow:approval` when generating §4.4 (数据结构 / 数据模型).  
-> **本地技能**: `skills/database/`（本仓库长期维护）。  
-> **禁止**依赖远程 skill 仓库（禁止 `npx skills add` / clone / 运行时 fetch）。  
-> **Not** an MCP tool — on hit, `Read` local matched skill files; on miss, LLM-only §4.4.
+> **本地技能**: 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」。
 
 ---
 
@@ -28,18 +28,38 @@ Scan the **project under review** (change's repo root), not SpecFlow itself. Col
 **Multi-hit**: pick primary OLTP store for §4.4 (prefer `mysql` / `postgresql` / `oracle` over
 `redis` / `elasticsearch`). Mention secondary stores in §4.7/架构 if relevant.
 
-**Announce** after detection:
+---
+
+## 2. Resolve guidance root (path priority)
+
+Before reading pack files, resolve `guidanceRoot` for stack `<stack>`:
+
+| Priority | Path | When |
+|----------|------|------|
+| 1 | `.cursor/specflow/guidance/database/<stack>/` | Cursor IDE assets present |
+| 1 | `.claude/specflow/guidance/database/<stack>/` | Claude IDE assets present |
+| 1 | `.agents/specflow/guidance/database/<stack>/` | Codex IDE assets present |
+| 2 | `skills/database/<stack>/` | SpecFlow package / self-repo fallback (relative to SpecFlow package root) |
+| 3 | *(missing)* | `LLM-fallback` |
+
+If multiple IDE roots exist, prefer the IDE the user is running in; otherwise the first existing path among cursor → claude → agents.
+
+**Announce** after detection + resolve:
 
 ```text
 DB stack for approval: <mysql|postgresql|oracle|redis|elasticsearch|none>
-Guidance: skills/database/<stack>/SKILL.md | LLM-fallback
+Guidance: <.cursor|claude|agents>/specflow/guidance/database/<stack>/SKILL.md
+         | skills/database/<stack>/SKILL.md | LLM-fallback
 ```
 
 ---
 
-## 2. On hit — load **local** guidance (Read, do not invent, do not fetch)
+## 3. On hit — load **local** guidance (Read, do not invent, do not fetch)
 
-Base: `skills/database/<stack>/`（相对 SpecFlow 仓库根；离线可读）
+> 先完成 `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 |
 |-------|-----------|------------------------------|
@@ -49,31 +69,37 @@ Base: `skills/database/<stack>/`（相对 SpecFlow 仓库根；离线可读）
 | `redis` | `SKILL.md` | Only if change is cache/key design — **not** a substitute for relational DDL |
 | `elasticsearch` | `SKILL.md` | Only if change is index/mapping — **not** a substitute for relational DDL |
 
+Point to files **from the router entry** (no reference→reference chains).
+
 Apply guidance to §4.4 output:
 
 1. Prefer engine/charset/collation idioms from the local skill (MySQL: InnoDB + utf8mb4…).
 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 总则, e.g. `DB 技能: skills/database/mysql (本地)`.
+Cite in §4.4 总则 the **actual** paths used:
+- `项目约定: <path…> | 未发现`
+- `DB 技能: .cursor/specflow/guidance/database/mysql` 或 `skills/database/mysql (package fallback)` 或 `LLM-fallback`
 
 ---
 
-## 3. On miss — LLM fallback
+## 4. On miss — LLM fallback
 
-If `DB stack = none` (no durable store signals, or only unknown/custom DB):
+If `DB stack = none`, or stack set but **no** guidance root resolves:
 
 1. **Do not** force-load mysql/postgresql skills.
 2. Generate §4.4 with SpecFlow rules only (`generate.md` §4.4 + Quality Gates G3/G4).
 3. If design/tasks claim a DB but signals are absent → `WARNING` in §8:
    `design 声称落库但未检测到 DB 栈信号 — 已用 LLM 通用 DDL;建议 refine 标明引擎`.
-4. Pure CLI/config changes → keep `不涉及数据库变更(...)`.
+4. If stack detected but guidance files missing → `WARNING` in §8:
+   `dbStack=<stack> 但未找到 guidance/database — 已用 LLM-fallback;建议 specflow init --force-assets`.
+5. Pure CLI/config changes → keep `不涉及数据库变更(...)`.
 
 ---
 
-## 4. Why not remote skills / MCP tools?
+## 5. Why not remote skills / MCP / IDE skills?
 
-- **Remote**: approval must work offline and must not drift with upstream installs; maintain
-  `skills/database/` in this repo.
-- **MCP tools**: these packs are markdown guidance, not APIs; routing chooses which local
-  files to `Read`.
+- **Remote**: approval must work offline; maintain pack in this repo + init sync.
+- **MCP tools**: markdown guidance, not APIs; routing chooses which local files to `Read`.
+- **IDE skills**: packs must **not** appear under `.cursor/skills` / `.claude/skills` / `.agents/skills`
+  (noise + false discoverability). They live only under `{ide}/specflow/guidance/`.