@gordon.gan/specflow 1.2.1-beta → 1.3.1-beta

package/README.md

@@ -8,17 +8,19 @@
 
 SpecFlow 把 **OpenSpec**（结构化需求规划）和 **Superpowers**（TDD、调试、代码审查等工程纪律）合并为一个工具：一个 CLI 负责确定性操作，一套跨 IDE 工作流技能负责 AI 编排，覆盖从探索需求到归档合并的完整生命周期。
 
-| 环境 | 命令形式 | 详细指南 |
-|------|----------|----------|
-| Claude Code | `/specflow:propose` 等斜杠命令 | 本文 |
-| Cursor | `specflow:propose` 等命令 | [Cursor 指南](./CURSOR_PACKAGING_AND_USAGE_GUIDE.md) |
-| OpenAI Codex | `$specflow-propose` 等技能 | [Codex 指南](./CODEX_PACKAGING_AND_USAGE_GUIDE.md) |
+| 场景 | 入口 | 详细指南 |
+|------|------|----------|
+| **单仓（默认）** | Claude `/specflow:*` · Cursor `specflow:*` · Codex `$specflow-*` | **本文**（含中文产物、`apply --yes`） |
+| Cursor 打包与安装 | Cursor 命令与资产 | [Cursor 指南](./CURSOR_PACKAGING_AND_USAGE_GUIDE.md) |
+| Codex 打包与安装 | Codex 技能与资产 | [Codex 指南](./CODEX_PACKAGING_AND_USAGE_GUIDE.md) |
 | 多语言 / Go Profile | SpecFlow + 语言专项 skills | [语言 Profile 指南](./LANGUAGE_PROFILE_USAGE_GUIDE.md) |
-| 多仓 / 前后端一体需求（**权威**） | Contract Hub + Spokes + 产物与 CLI | [多仓完整指南](./MULTI_REPO_GUIDE.md) |
-| 多仓原生能力（设计） | Store / References / Workset | [多仓技术方案](./MULTI_REPO_TECHNICAL_DESIGN.md) |
-| 多仓场景示例（TALOS） | contracts + api + web 实操路径 | [TALOS 多仓教程](./TALOS_MULTI_REPO_TUTORIAL.md) |
-| TALOS 公共需求详例 | 工作区邀请成员（Hub→BE→FE→联调） | [公共需求 Walkthrough](./docs/TALOS_SHARED_REQUIREMENT_WALKTHROUGH.md) |
-| 产物与作用 | explore / proposal / delta / design / tasks / 主 specs | [产物说明](./SPECFLOW_ARTIFACTS.md) |
+| 多仓（**权威**） | Contract Hub + Spokes | [多仓完整指南](./MULTI_REPO_GUIDE.md) |
+| 多仓技术方案 | Store / References / Workset | [多仓技术方案](./MULTI_REPO_TECHNICAL_DESIGN.md) |
+| 多仓场景示例（TALOS） | contracts + api + web | [TALOS 多仓教程](./TALOS_MULTI_REPO_TUTORIAL.md) |
+| TALOS 公共需求详例 | Hub→BE→FE→联调 | [公共需求 Walkthrough](./docs/TALOS_SHARED_REQUIREMENT_WALKTHROUGH.md) |
+| 产物与作用 | explore / proposal / delta / design / tasks | [产物说明](./SPECFLOW_ARTIFACTS.md) |
+
+未配置 `store` / `references` / `workflow.profile` 时，行为就是**单仓 SpecFlow**（`standalone`）；多仓为可选增强。
 
 ---
 
@@ -44,12 +46,16 @@ explore（可选）→ propose → refine → apply → review → test → veri
 | 能力 | 说明 |
 |------|------|
 | **结构化规划** | 一次 propose 产出 proposal、delta specs、design、tasks 四个 artifact |
+| **中文 / 英文产物** | `specflow init --artifact-language zh-CN`（别名 `zh`）写入 `artifacts.language`；叙述可中文，协议标记保持英文 |
 | **多轮精化** | refine 内部循环（≥2 轮），攻击性审查假设、边界与 scope |
 | **纪律化构建** | apply 先重写 tasks.md，再逐任务 TDD；design 有漏则回 refine |
+| **`apply --yes`** | 当前调用内自动放行成功确认门禁，构建成功后串行 review → test → verify；不绕过 Block / 失败，不自动 archive |
+| **语言感知审查** | apply 按 `go.mod` / `package.json` 等路由到 ECC reviewer（TS / Python / Go / Rust / Kotlin / Java） |
 | **双重验收** | verify 对照 delta specs 与主 specs 做回归检查 |
 | **变更归档** | archive 自动 merge delta、移入 archive、可做 git 分支清理 |
 | **跨 IDE 一致** | Claude / Cursor / Codex 共享同一套技能与 prompt，parity 可校验 |
 | **确定性 CLI** | 校验、合并、状态追踪、资产同步 — 不依赖 AI 猜 |
+| **可选语言 Profile** | SpecFlow 管流程门禁；Go/TS 等专项 skills 按仓库挂载，见 [语言 Profile 指南](./LANGUAGE_PROFILE_USAGE_GUIDE.md) |
 
 ---
 
@@ -67,6 +73,7 @@ explore（可选）→ propose → refine → apply → review → test → veri
 │  refine           ≥2 轮精化：挑战假设 / 新方案 / 探边界 / 质疑 scope     │
 │       ↓                                                                 │
 │  apply            Phase A 重写 tasks.md → Phase B 逐任务 TDD 执行         │
+│                   （可选 /specflow:apply --yes：少打断，成功后串行验收）   │
 │       ↓                                                                 │
 │  review → test → verify                                                 │
 │       ↓                                                                 │
@@ -117,7 +124,7 @@ npm install -g @gordon.gan/specflow
 npm install -g github:Gordon-Gan-Jiang/specflow
 
 # 验证
-specflow --version   # 以 npm / package.json 为准（开发中可见 1.2.0-beta）
+specflow --version   # 以 npm / package.json 为准（当前 1.3.1-beta）
 specflow --help
 ```
 
@@ -160,23 +167,45 @@ artifacts:
 
 ### 跑通第一个变更
 
-**需求已清晰：**
+**需求已清晰（交互确认，默认）：**
 
 ```
 /specflow:propose "给用户管理模块加批量导入"
 /specflow:refine
 /specflow:apply
+/specflow:review
+/specflow:test
 /specflow:verify
 /specflow:archive
 ```
 
-需要少打断确认时，可用 `/specflow:apply --yes`：自动接受成功的 Gate A/B 确认，并在构建成功后串行执行 review → test → verify；失败、Block、设计缺口仍会停下，且不会自动 archive。
+**少打断（`apply --yes`）：**
+
+```
+/specflow:propose "给用户管理模块加批量导入"
+/specflow:refine
+/specflow:apply --yes
+# 构建成功后自动串行：review → test → verify
+# 全部通过后你再手动：
+/specflow:archive
+```
+
+`/specflow:apply --yes` 只影响**当前这一次**调用：
+
+| 会自动做 | 不会自动做 / 仍会停下 |
+|----------|------------------------|
+| 接受成功的 Phase A 重写确认（Gate A） | 设计缺口、重组选项需人决策 |
+| 任务审查为 `Approve` / `Warning` 时进入下一任务 | 审查 `Block`、测试失败、前置 phase 不对 |
+| Phase B 成功后串行 review → test → verify | 自动 `/specflow:archive` |
+| | CRITICAL / HIGH review、test 红、verify `FAIL` 时中断序列 |
+
+Cursor：`specflow:apply --yes`；Codex：`$specflow-apply --yes`。
 
 **需求模糊：**
 
 ```
 /specflow:explore "不确定用 CSV 还是 Excel，也不清楚现有用户表结构"
-# 确认 explore.md 后：
+# 确认 explore.md 的 Status 为 confirmed 后：
 /specflow:propose
 /specflow:refine
 ...
@@ -248,14 +277,14 @@ specflow init
 | 命令 | 做什么 |
 |------|--------|
 | **explore** | 读代码、比方案、定边界；产出 `explore.md`，confirmed 后 handoff 到 propose |
-| **propose** | 一次产出 proposal、delta specs、design、tasks（第一轮深度思考，非占位骨架） |
+| **propose** | 一次产出 proposal、delta specs、design、tasks（第一轮深度思考，非占位骨架）；叙述语言跟 `artifacts.language` |
 | **refine** | 内部多轮循环（≥2 轮，AI 判断收敛）；可更新任意 artifact |
-| **apply** | Phase A 用 writing-plans 规则重写 tasks.md；Phase B subagent TDD 逐任务执行 |
+| **apply** | Phase A 重写 tasks.md；Phase B 按语言路由 ECC 审查 + TDD 逐任务执行；可选 `--yes` |
 | **review** | 代码审查，对照 specs 检查回归 |
 | **test** | 单元 + 集成 + E2E + 回归测试 |
-| **verify** | Pass 1：delta specs 验收；Pass 2：主 specs 回归（无基线时显式 skipped） |
-| **archive** | 归档变更、delta merge、git 分支清理；默认要求 phase=apply |
-| **fix** | 修 Bug 一条龙 |
+| **verify** | Pass 1：delta specs 验收；Pass 2：主 specs 回归（无基线时显式 skipped）；Web 另有安全 Pass |
+| **archive** | 归档变更、delta merge、git 分支清理；单仓默认要求 phase=`apply` |
+| **fix** | 修 Bug 一条龙（可加 `--urgent` 跳过审查） |
 | **snap** | 从 git 历史反推变更并归档 |
 
 > **v1.0.1 起命令已重命名**（对齐 OpenSpec 术语）：`plan→propose`、`build→apply`、`done→archive`。`.specflow.yaml` 的 phase 枚举同步为 `propose/refined/apply/archived`（读取时兼容旧值 `plan`/`built`）。
@@ -290,7 +319,46 @@ CLI 从当前目录**向上查找**项目根（识别 `specflow/config.yaml`）
 | 命令 | 说明 |
 |------|------|
 | `specflow validate <文件>` | 校验 spec 文件格式（WHEN/THEN scenario 等） |
-| `specflow instructions <artifact> <change>` | 查看某 artifact 的创建指令 |
+| `specflow instructions <artifact> <change>` | 查看某 artifact 的创建指令（含 `artifactLanguage` / `languageGuidance`） |
+
+---
+
+## 单仓常用能力速查
+
+### 产物语言（中文 / 英文）
+
+```bash
+specflow init --artifact-language zh-CN   # 推荐国内团队
+# 已有项目：直接改 specflow/config.yaml → artifacts.language（init 不覆盖已有 config）
+```
+
+| 会本地化 | 保持英文 / 不变 |
+|----------|-----------------|
+| Why / What、场景叙述、design 说明、tasks 描述 | `ADDED Requirements`、`WHEN` / `THEN`、`Requirement:` / `Scenario:` |
+| | Change ID、capability id、路径、命令、代码符号 |
+
+切换语言只影响**之后新建或主动重写**的内容，不会自动翻译历史产物。
+
+### `apply --yes`（非交互确认）
+
+```text
+/specflow:apply --yes
+```
+
+适合任务清单已确认、希望少打断连续落地的场景。质量门禁仍在：Block / 失败 / 设计缺口会停；通过后需你手动 archive。
+
+### 语言感知代码审查（内置）
+
+apply Phase B 在项目根检测语言信号（如 `go.mod`、`tsconfig.json`、`pyproject.toml`），选用对应 ECC reviewer；无匹配时用通用 reviewer。更深的语言惯用法可再挂 [语言 Profile](./LANGUAGE_PROFILE_USAGE_GUIDE.md)。
+
+### 升级与健康检查
+
+```bash
+npm install -g @gordon.gan/specflow@beta   # 或指定版本
+specflow sync --ide all
+specflow doctor --parity
+specflow parity-report
+```
 
 ---
 

package/dist/cli/commands/change-new.d.ts

@@ -4,6 +4,11 @@
  * Creates a new change directory with .specflow.yaml metadata.
  */
 import type { Command } from 'commander';
+import { type UpstreamSpecSource } from '../../core/upstream-spec.js';
+import type { StoreRegistry } from '../../core/store/foundation.js';
+export interface CreateChangeOptions {
+    readonly source?: UpstreamSpecSource;
+}
 /**
  * Creates a new change directory with initial metadata.
  *
@@ -11,7 +16,12 @@ import type { Command } from 'commander';
  * @param projectRoot - Absolute path to the project root
  * @throws When the name is invalid or the change already exists
  */
-export declare function createChange(name: string, projectRoot: string): Promise<void>;
+export declare function createChange(name: string, projectRoot: string, options?: CreateChangeOptions): Promise<void>;
+/**
+ * Creates a same-name implementation Spoke change bound to an archived
+ * baseline spec from the configured upstream store.
+ */
+export declare function createChangeFromSpec(specId: string, projectRoot: string, registry: StoreRegistry): Promise<void>;
 /**
  * Registers the `change new` subcommand with Commander.
  */

package/dist/cli/commands/change-new.js

@@ -6,6 +6,10 @@
 import { join } from 'node:path';
 import { validateChangeName, writeChangeMetadata } from '../../utils/change-utils.js';
 import { directoryExists } from '../../utils/file-system.js';
+import { requireProjectRoot } from '../../utils/project-root.js';
+import { resolveUpstreamSpec, } from '../../core/upstream-spec.js';
+import { readRegistry } from '../../core/store/registry.js';
+import { getStoreRegistryPath } from '../../core/global-config.js';
 import { addStoreOption, resolveRootFromCommandOptions } from '../shared/store-option.js';
 const CHANGES_REL_PATH = 'specflow/changes';
 /**
@@ -25,7 +29,7 @@ function todayDate() {
  * @param projectRoot - Absolute path to the project root
  * @throws When the name is invalid or the change already exists
  */
-export async function createChange(name, projectRoot) {
+export async function createChange(name, projectRoot, options = {}) {
     validateChangeName(name);
     const changeDir = join(projectRoot, CHANGES_REL_PATH, name);
     if (await directoryExists(changeDir)) {
@@ -35,17 +39,44 @@ export async function createChange(name, projectRoot) {
         schema: 'specflow',
         created: todayDate(),
         phase: 'propose',
+        ...(options.source ? { source: options.source } : {}),
     };
     await writeChangeMetadata(name, metadata, projectRoot);
 }
+/**
+ * Creates a same-name implementation Spoke change bound to an archived
+ * baseline spec from the configured upstream store.
+ */
+export async function createChangeFromSpec(specId, projectRoot, registry) {
+    validateChangeName(specId);
+    const resolved = await resolveUpstreamSpec(projectRoot, specId, registry);
+    await createChange(specId, projectRoot, { source: resolved.source });
+}
 /**
  * Registers the `change new` subcommand with Commander.
  */
 export function registerChangeNewCommand(changeCmd) {
     addStoreOption(changeCmd
-        .command('new <name>')
+        .command('new [name]')
         .description('Create a new change directory')
+        .option('--spec <id>', 'Create a same-name Spoke change from an upstream baseline spec')
         .action(async (name, opts) => {
+        if (opts.spec) {
+            if (name) {
+                throw new Error('Do not pass a change name with --spec; the change name is the spec ID.');
+            }
+            if (opts.store) {
+                throw new Error('--store cannot be combined with --spec; workflow.upstream selects the Hub.');
+            }
+            const projectRoot = requireProjectRoot();
+            const registry = await readRegistry(getStoreRegistryPath());
+            await createChangeFromSpec(opts.spec, projectRoot, registry);
+            console.info(`Created change from upstream spec: ${opts.spec}`);
+            return;
+        }
+        if (!name) {
+            throw new Error('Change name is required unless --spec <id> is provided.');
+        }
         const projectRoot = await resolveRootFromCommandOptions({ store: opts.store });
         await createChange(name, projectRoot);
         console.info(`Created change: ${name}`);

package/dist/cli/commands/init.d.ts

@@ -10,6 +10,8 @@ export interface InitResult {
 export interface InitOptions {
     readonly ide?: InitIdeTarget;
     readonly artifactLanguage?: string;
+    readonly workflowProfile?: string;
+    readonly workflowUpstream?: string;
     readonly forceAssets?: boolean;
     readonly parityStrict?: boolean;
 }

package/dist/cli/commands/init.js

@@ -8,8 +8,24 @@ import { appendManagedBlock } from '../../integrations/shared/marker-write.js';
 import { getRegeneratableIgnoreLines } from '../../integrations/shared/managed-assets.js';
 import { detectMigrationState } from '../../integrations/shared/migration-state.js';
 import { DEFAULT_ARTIFACT_LANGUAGE, requireArtifactLanguage, } from '../../core/artifact-language.js';
-function renderConfigYaml(artifactLanguage) {
+import { WORKFLOW_PROFILES, } from '../../core/project-config.js';
+import { KEBAB_CASE_STORE_ID } from '../../core/store/foundation.js';
+function requireWorkflowProfile(profile) {
+    if (WORKFLOW_PROFILES.includes(profile)) {
+        return profile;
+    }
+    throw new Error(`Unsupported workflow profile "${profile}". Supported values: ${WORKFLOW_PROFILES.join(', ')}.`);
+}
+function renderConfigYaml(artifactLanguage, workflowProfile, workflowUpstream) {
+    const workflowBlock = workflowProfile
+        ? `
+workflow:
+  profile: ${workflowProfile}${workflowUpstream ? `\n  upstream: ${workflowUpstream}` : ''}
+${workflowUpstream ? `\nreferences:\n  - ${workflowUpstream}` : ''}
+`
+        : '';
     return `schema: specflow
+${workflowBlock}
 
 artifacts:
   language: ${artifactLanguage}
@@ -38,8 +54,8 @@ async function createDirectoryStructure(projectRoot) {
         fs.mkdir(join(projectRoot, 'specflow', 'specs'), { recursive: true }),
     ]);
 }
-async function writeConfig(projectRoot, artifactLanguage) {
-    await fs.writeFile(join(projectRoot, 'specflow', 'config.yaml'), renderConfigYaml(artifactLanguage), 'utf-8');
+async function writeConfig(projectRoot, artifactLanguage, workflowProfile, workflowUpstream) {
+    await fs.writeFile(join(projectRoot, 'specflow', 'config.yaml'), renderConfigYaml(artifactLanguage, workflowProfile, workflowUpstream), 'utf-8');
 }
 async function pathExists(path) {
     try {
@@ -61,6 +77,22 @@ export async function initProject(projectRoot, packageRoot, options = {}) {
     const artifactLanguage = options.artifactLanguage === undefined
         ? DEFAULT_ARTIFACT_LANGUAGE
         : requireArtifactLanguage(options.artifactLanguage);
+    const workflowProfile = options.workflowProfile === undefined
+        ? undefined
+        : requireWorkflowProfile(options.workflowProfile);
+    const workflowUpstream = options.workflowUpstream;
+    if (workflowProfile === 'implementation-spoke' &&
+        workflowUpstream === undefined) {
+        throw new Error('The implementation-spoke workflow profile requires --upstream <store-id>.');
+    }
+    if (workflowUpstream !== undefined &&
+        !KEBAB_CASE_STORE_ID.test(workflowUpstream)) {
+        throw new Error('Workflow upstream must be a kebab-case store ID.');
+    }
+    if (workflowUpstream !== undefined &&
+        workflowProfile !== 'implementation-spoke') {
+        throw new Error('--upstream is only valid with --workflow-profile implementation-spoke.');
+    }
     const ide = options.ide ?? 'both';
     const forceAssets = options.forceAssets ?? false;
     const parityStrict = options.parityStrict ?? true;
@@ -69,7 +101,7 @@ export async function initProject(projectRoot, packageRoot, options = {}) {
     const migrationState = await detectMigrationState(projectRoot);
     if (!initialized) {
         await createDirectoryStructure(projectRoot);
-        await writeConfig(projectRoot, artifactLanguage);
+        await writeConfig(projectRoot, artifactLanguage, workflowProfile, workflowUpstream);
     }
     const languageEditMessage = options.artifactLanguage
         ? ' Edit specflow/config.yaml explicitly to change artifact language in an initialized project.'
@@ -115,6 +147,8 @@ export function registerInitCommand(program) {
         .description('Initialize a project with specflow directory structure and assets')
         .option('--ide <target>', 'Target IDE assets: claude | cursor | codex | both | all', 'both')
         .option('--artifact-language <language>', 'Artifact content language: en | zh-CN (alias: zh)')
+        .option('--workflow-profile <profile>', 'Workflow profile: standalone | contract-hub | implementation-spoke')
+        .option('--upstream <store-id>', 'Primary contract store for implementation-spoke projects')
         .option('--force-assets', 'Refresh managed IDE assets even when project is initialized')
         .option('--no-parity-strict', 'Disable strict parity validation after asset generation')
         .action(async (opts) => {
@@ -123,6 +157,8 @@ export function registerInitCommand(program) {
         const result = await initProject(projectRoot, packageRoot, {
             ide: opts.ide ?? 'both',
             artifactLanguage: opts.artifactLanguage,
+            workflowProfile: opts.workflowProfile,
+            workflowUpstream: opts.upstream,
             forceAssets: opts.forceAssets ?? false,
             parityStrict: opts.parityStrict ?? true,
         });

package/dist/core/archive.js

@@ -8,8 +8,10 @@
  */
 import { promises as fs } from 'node:fs';
 import { join, relative } from 'node:path';
+import yaml from 'js-yaml';
 import { validateSpec } from './validation/validator.js';
 import { applyDeltaSpec } from './specs-apply.js';
+import { parseProjectConfig } from './project-config.js';
 import { readChangeMetadata, writeChangeMetadata, } from '../utils/change-metadata.js';
 /**
  * Recursively list all `.md` files in a directory, returning paths relative to the base dir.
@@ -50,6 +52,15 @@ function todayDatePrefix() {
     const day = String(now.getDate()).padStart(2, '0');
     return `${year}-${month}-${day}`;
 }
+async function readWorkflowProfile(projectRoot) {
+    try {
+        const content = await fs.readFile(join(projectRoot, 'specflow', 'config.yaml'), 'utf-8');
+        return parseProjectConfig(yaml.load(content)).workflowProfile;
+    }
+    catch {
+        return 'standalone';
+    }
+}
 /**
  * Archive a completed change.
  *
@@ -72,19 +83,26 @@ export async function archiveChange(changeName, projectRoot, options = {}) {
     const changeDir = join(projectRoot, 'specflow', 'changes', changeName);
     const deltaSpecsDir = join(changeDir, 'specs');
     const mainSpecsDir = join(projectRoot, 'specflow', 'specs');
-    // 0. Phase gate: require phase=apply unless --force
+    // 0. Phase gate: contract Hubs may archive refined contracts; all other
+    // profiles retain the existing phase=apply requirement.
     const metadata = await readChangeMetadata(changeDir);
     const currentPhase = metadata?.phase;
-    if (currentPhase !== 'apply' && !options.force) {
+    const workflowProfile = await readWorkflowProfile(projectRoot);
+    const phaseAllowed = currentPhase === 'apply' ||
+        (workflowProfile === 'contract-hub' && currentPhase === 'refined');
+    if (!phaseAllowed && !options.force) {
         const phaseLabel = currentPhase ?? 'unknown';
+        const expectation = workflowProfile === 'contract-hub'
+            ? "expected 'refined' or 'apply'. Complete '/specflow:refine' first"
+            : "expected 'apply'. Complete '/specflow:apply' first";
         return {
             success: false,
             errors: [
-                `Cannot archive: change '${changeName}' is in phase '${phaseLabel}', expected 'apply'. Complete '/specflow:apply' first, or pass '--force' to archive anyway.`,
+                `Cannot archive: change '${changeName}' is in phase '${phaseLabel}', ${expectation}, or pass '--force' to archive anyway.`,
             ],
         };
     }
-    if (options.force && currentPhase !== 'apply') {
+    if (options.force && !phaseAllowed) {
         const phaseLabel = currentPhase ?? 'unknown';
         console.warn(`Warning: archiving "${changeName}" in phase ${phaseLabel} with --force. ` +
             `Consider running /specflow:apply first.`);

package/dist/core/artifact-graph/types.d.ts

@@ -77,7 +77,6 @@ export declare const SchemaYamlSchema: z.ZodObject<{
         tracks?: string | null | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    version: number;
     artifacts: {
         id: string;
         generates: string;
@@ -85,6 +84,7 @@ export declare const SchemaYamlSchema: z.ZodObject<{
         requires: string[];
         instruction?: string | undefined;
     }[];
+    version: number;
     name: string;
     apply?: {
         requires: string[];
@@ -93,7 +93,6 @@ export declare const SchemaYamlSchema: z.ZodObject<{
     } | undefined;
     description?: string | undefined;
 }, {
-    version: number;
     artifacts: {
         id: string;
         generates: string;
@@ -101,6 +100,7 @@ export declare const SchemaYamlSchema: z.ZodObject<{
         instruction?: string | undefined;
         requires?: string[] | undefined;
     }[];
+    version: number;
     name: string;
     apply?: {
         requires: string[];

package/dist/core/opener-launch.d.ts

@@ -1,3 +1,18 @@
+import { type SpawnSyncOptions } from 'node:child_process';
 import type { OpenerDefinition } from './openers.js';
+export interface OpenerSpawnPlan {
+    readonly command: string;
+    readonly args: string[];
+    readonly options: SpawnSyncOptions;
+}
+/**
+ * Build spawn argv for launching a workspace-file opener.
+ *
+ * On Windows, Cursor/VS Code ship as `*.cmd` shims. Node's spawn with
+ * `shell: false` cannot execute those directly (ENOENT). Follow Node's
+ * recommended pattern: `cmd.exe /d /s /c` with a single quoted command line
+ * and `windowsVerbatimArguments`, without enabling shell interpolation.
+ */
+export declare function buildOpenerSpawn(opener: OpenerDefinition, workspacePath: string, primaryPath: string, platform?: NodeJS.Platform, comSpec?: string): OpenerSpawnPlan;
 export declare function isOpenerAvailable(opener: OpenerDefinition): boolean;
 export declare function launchOpener(opener: OpenerDefinition, workspacePath: string, primaryPath: string): void;

package/dist/core/opener-launch.js

@@ -1,16 +1,47 @@
 import { spawnSync } from 'node:child_process';
+/**
+ * Build spawn argv for launching a workspace-file opener.
+ *
+ * On Windows, Cursor/VS Code ship as `*.cmd` shims. Node's spawn with
+ * `shell: false` cannot execute those directly (ENOENT). Follow Node's
+ * recommended pattern: `cmd.exe /d /s /c` with a single quoted command line
+ * and `windowsVerbatimArguments`, without enabling shell interpolation.
+ */
+export function buildOpenerSpawn(opener, workspacePath, primaryPath, platform = process.platform, comSpec = process.env.ComSpec || 'cmd.exe') {
+    const baseOptions = {
+        cwd: primaryPath,
+        shell: false,
+        stdio: 'inherit',
+    };
+    if (platform !== 'win32') {
+        return {
+            command: opener.command,
+            args: [workspacePath],
+            options: baseOptions,
+        };
+    }
+    // Escape " for cmd.exe by doubling; wrap each token so spaces are preserved.
+    const quote = (value) => `"${value.replace(/"/g, '""')}"`;
+    return {
+        command: comSpec,
+        args: ['/d', '/s', '/c', `${quote(opener.command)} ${quote(workspacePath)}`],
+        options: {
+            ...baseOptions,
+            windowsVerbatimArguments: true,
+        },
+    };
+}
 export function isOpenerAvailable(opener) {
+    // `where.exe` resolves .cmd/.bat shims the same way cmd does.
     const result = spawnSync(process.platform === 'win32' ? 'where' : 'which', [opener.command], {
         stdio: 'ignore',
+        shell: false,
     });
     return result.status === 0;
 }
 export function launchOpener(opener, workspacePath, primaryPath) {
-    const child = spawnSync(opener.command, [workspacePath], {
-        cwd: primaryPath,
-        shell: false,
-        stdio: 'inherit',
-    });
+    const plan = buildOpenerSpawn(opener, workspacePath, primaryPath);
+    const child = spawnSync(plan.command, plan.args, plan.options);
     if (child.error) {
         throw child.error;
     }

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

@@ -1,5 +1,7 @@
 import type { Diagnostic } from './diagnostics.js';
 import { type ArtifactLanguage } from './artifact-language.js';
+export declare const WORKFLOW_PROFILES: readonly ["standalone", "contract-hub", "implementation-spoke"];
+export type WorkflowProfile = (typeof WORKFLOW_PROFILES)[number];
 export interface NormalizedReference {
     readonly id: string;
     readonly remote?: string;
@@ -8,6 +10,8 @@ export interface ParsedProjectConfig {
     readonly schema: string;
     readonly context?: string;
     readonly artifactLanguage: ArtifactLanguage;
+    readonly workflowProfile: WorkflowProfile;
+    readonly workflowUpstream?: string;
     readonly store?: string;
     readonly references: readonly NormalizedReference[];
     readonly diagnostics: readonly Diagnostic[];

package/dist/core/project-config.js

@@ -1,6 +1,11 @@
 import { z } from 'zod';
 import { DEFAULT_ARTIFACT_LANGUAGE, isArtifactLanguage, } from './artifact-language.js';
 const KEBAB_CASE_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+export const WORKFLOW_PROFILES = [
+    'standalone',
+    'contract-hub',
+    'implementation-spoke',
+];
 const ReferenceObjectSchema = z
     .object({
     id: z.string().regex(KEBAB_CASE_ID),
@@ -22,6 +27,8 @@ export function parseProjectConfig(raw) {
     const schema = typeof record.schema === 'string' ? record.schema : 'specflow';
     const context = typeof record.context === 'string' ? record.context : undefined;
     let artifactLanguage = DEFAULT_ARTIFACT_LANGUAGE;
+    let workflowProfile = 'standalone';
+    let workflowUpstream;
     if (record.artifacts !== undefined) {
         const artifacts = typeof record.artifacts === 'object' &&
             record.artifacts !== null &&
@@ -90,10 +97,70 @@ export function parseProjectConfig(raw) {
             });
         }
     }
+    if (record.workflow !== undefined) {
+        const workflow = typeof record.workflow === 'object' &&
+            record.workflow !== null &&
+            !Array.isArray(record.workflow)
+            ? record.workflow
+            : undefined;
+        if (!workflow) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'invalid_workflow_config',
+                message: 'Project workflow configuration must be an object.',
+                target: 'config.workflow',
+                fix: 'Set workflow.profile to standalone, contract-hub, or implementation-spoke.',
+            });
+        }
+        else {
+            const configuredProfile = workflow.profile;
+            if (typeof configuredProfile === 'string' &&
+                WORKFLOW_PROFILES.includes(configuredProfile)) {
+                workflowProfile = configuredProfile;
+            }
+            else {
+                diagnostics.push({
+                    severity: 'error',
+                    code: 'invalid_workflow_profile',
+                    message: "Workflow profile must be one of: 'standalone', 'contract-hub', 'implementation-spoke'.",
+                    target: 'config.workflow.profile',
+                    fix: 'Choose a supported workflow profile.',
+                });
+            }
+            if (workflow.upstream !== undefined) {
+                if (typeof workflow.upstream === 'string' &&
+                    KEBAB_CASE_ID.test(workflow.upstream)) {
+                    workflowUpstream = workflow.upstream;
+                }
+                else {
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'invalid_workflow_upstream',
+                        message: 'Workflow upstream must be a kebab-case store ID.',
+                        target: 'config.workflow.upstream',
+                        fix: 'Set workflow.upstream to a referenced store ID.',
+                    });
+                }
+            }
+        }
+    }
+    if (workflowProfile === 'implementation-spoke' &&
+        workflowUpstream !== undefined &&
+        !references.some((reference) => reference.id === workflowUpstream)) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'workflow_upstream_not_referenced',
+            message: `Workflow upstream '${workflowUpstream}' must also be declared in references.`,
+            target: 'config.workflow.upstream',
+            fix: `Add '${workflowUpstream}' to specflow/config.yaml references.`,
+        });
+    }
     return {
         schema,
         context,
         artifactLanguage,
+        workflowProfile,
+        workflowUpstream,
         store,
         references,
         diagnostics,

package/dist/core/store/foundation.d.ts

@@ -6,12 +6,12 @@ export declare const StoreIdentitySchema: z.ZodObject<{
     id: z.ZodString;
     remote: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    version: 1;
     id: string;
+    version: 1;
     remote?: string | undefined;
 }, {
-    version: 1;
     id: string;
+    version: 1;
     remote?: string | undefined;
 }>;
 export type StoreIdentity = z.infer<typeof StoreIdentitySchema>;
@@ -105,6 +105,7 @@ export declare const StoreRegistrySchema: z.ZodObject<{
         };
     }>>;
 }, "strict", z.ZodTypeAny, {
+    version: 1;
     stores: Record<string, {
         provenance: "managed" | "external";
         backend: {
@@ -114,8 +115,8 @@ export declare const StoreRegistrySchema: z.ZodObject<{
             branch?: string | undefined;
         };
     }>;
-    version: 1;
 }, {
+    version: 1;
     stores: Record<string, {
         provenance: "managed" | "external";
         backend: {
@@ -125,7 +126,6 @@ export declare const StoreRegistrySchema: z.ZodObject<{
             branch?: string | undefined;
         };
     }>;
-    version: 1;
 }>;
 export type StoreRegistry = z.infer<typeof StoreRegistrySchema>;
 export type RegistryEntry = z.infer<typeof RegistryEntrySchema>;

package/dist/core/upstream-spec.d.ts

@@ -0,0 +1,14 @@
+import type { StoreRegistry } from './store/foundation.js';
+export interface UpstreamSpecSource {
+    readonly store: string;
+    readonly spec: string;
+    readonly digest: string;
+    readonly commit?: string;
+    readonly tag?: string;
+}
+export interface ResolvedUpstreamSpec {
+    readonly source: UpstreamSpecSource;
+    readonly content: string;
+    readonly path: string;
+}
+export declare function resolveUpstreamSpec(projectRoot: string, specId: string, registry: StoreRegistry): Promise<ResolvedUpstreamSpec>;

package/dist/core/upstream-spec.js

@@ -0,0 +1,74 @@
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+import { parseProjectConfig } from './project-config.js';
+function readGitValue(root, args) {
+    try {
+        const value = execFileSync('git', ['-C', root, ...args], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return value || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function resolveUpstreamSpec(projectRoot, specId, registry) {
+    const configPath = join(projectRoot, 'specflow', 'config.yaml');
+    let rawConfig;
+    try {
+        rawConfig = yaml.load(await fs.readFile(configPath, 'utf-8'));
+    }
+    catch {
+        throw new Error(`Cannot read Spoke configuration at ${configPath}.`);
+    }
+    const config = parseProjectConfig(rawConfig);
+    if (config.workflowProfile !== 'implementation-spoke') {
+        throw new Error("The --spec mode requires workflow.profile 'implementation-spoke'. " +
+            'Without --spec, use the existing single-repository flow.');
+    }
+    if (!config.workflowUpstream) {
+        throw new Error('The --spec mode requires workflow.upstream in specflow/config.yaml.');
+    }
+    const blockingDiagnostic = config.diagnostics.find((diagnostic) => diagnostic.severity === 'error');
+    if (blockingDiagnostic) {
+        throw new Error(blockingDiagnostic.message);
+    }
+    const storeId = config.workflowUpstream;
+    const store = registry.stores[storeId];
+    if (!store) {
+        throw new Error(`Upstream store '${storeId}' is not registered. ` +
+            `Run specflow store register <path> --id ${storeId} --yes.`);
+    }
+    const specPath = join(store.backend.local_path, 'specflow', 'specs', specId, 'spec.md');
+    let content;
+    try {
+        content = await fs.readFile(specPath, 'utf-8');
+    }
+    catch {
+        throw new Error(`Upstream spec '${specId}' was not found in store '${storeId}'. ` +
+            'The Hub must archive the spec before a Spoke can propose from it.');
+    }
+    const digest = `sha256:${createHash('sha256').update(content).digest('hex')}`;
+    const commit = readGitValue(store.backend.local_path, ['rev-parse', 'HEAD']);
+    const tag = readGitValue(store.backend.local_path, [
+        'describe',
+        '--tags',
+        '--exact-match',
+        'HEAD',
+    ]);
+    return {
+        source: {
+            store: storeId,
+            spec: specId,
+            digest,
+            ...(commit ? { commit } : {}),
+            ...(tag ? { tag } : {}),
+        },
+        content,
+        path: specPath,
+    };
+}

package/dist/core/worksets.d.ts

@@ -39,6 +39,7 @@ declare const WorksetsStateSchema: z.ZodObject<{
         tool?: string | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
+    version: 1;
     worksets: {
         name: string;
         members: {
@@ -47,8 +48,8 @@ declare const WorksetsStateSchema: z.ZodObject<{
         }[];
         tool?: string | undefined;
     }[];
-    version: 1;
 }, {
+    version: 1;
     worksets: {
         name: string;
         members: {
@@ -57,7 +58,6 @@ declare const WorksetsStateSchema: z.ZodObject<{
         }[];
         tool?: string | undefined;
     }[];
-    version: 1;
 }>;
 export type WorksetsState = z.infer<typeof WorksetsStateSchema>;
 export declare function validateWorksetName(name: string): void;

package/package.json

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

package/skills/specflow-archive/SKILL.md

@@ -9,13 +9,23 @@ description: "Archive change + merge specs + git branch cleanup"
 
 ## Prerequisites
 
-- An active change must exist with completed implementation.
+- An active change must exist.
 - `specflow` CLI must be available on PATH.
-- **Phase must be `apply`** in `.specflow.yaml`. This is set automatically when `/specflow:apply` Phase B completes. `specflow change archive` refuses to archive changes whose phase is not `apply` unless the caller passes `--force` explicitly. Do NOT pass `--force` from this skill — the flag is reserved for explicit user discretion. If archive fails with a phase check error, route the user back to `/specflow:apply` to complete the missing phase transition rather than forcing past the guard.
+- Read `specflow/config.yaml` and apply its workflow profile gate:
+  - Default, `workflow.profile: standalone`, and `implementation-spoke` require phase `apply`.
+  - `workflow.profile: contract-hub` permits phase `refined` or `apply`.
+- A contract Hub publishes validated contract/specification artifacts and does not require business implementation. Do not route a refined contract Hub through a fake `/specflow:apply`.
+- `specflow change archive` enforces these profile-aware gates. Do NOT pass `--force` from this skill; the flag remains reserved for explicit user discretion.
 
 ## Stage 1: Test Gate
 
-Run the project test suite for all affected modules. If implementation was done in a git worktree (common after `/specflow:apply`), run tests inside that worktree.
+For standalone and implementation Spoke projects, run the project test suite
+for all affected modules. If implementation was done in a git worktree (common
+after `/specflow:apply`), run tests inside that worktree.
+
+For a contract Hub archiving from `refined`, run SpecFlow validation for every
+delta spec and the repository's contract/schema tests. Business implementation
+tests are not required when the repository has no business implementation.
 
 If tests fail:
 - Report failures to the user.

package/skills/specflow-propose/SKILL.md

@@ -13,6 +13,53 @@ Propose is the **first-iteration deep-analysis pass**: in a single invocation it
 
 Treat every artifact here as "v1, to be iterated on" — depth matters, but so does moving through all four stages in one pass.
 
+## Invocation Modes
+
+### Existing single-repository flow (default)
+
+Without `--spec`, preserve the existing single-repository flow exactly:
+
+```text
+/specflow:propose <change-name>
+```
+
+Do not require workflow profiles, references, or an upstream store in this mode.
+
+### Upstream Spec mode (implementation Spoke)
+
+An implementation Spoke may derive a same-name local change from one archived
+Hub baseline spec:
+
+```text
+/specflow:propose --spec <spec-id>
+```
+
+`--spec` is explicit and takes exactly one kebab-case spec ID. In this mode:
+
+1. Read `specflow/config.yaml`.
+2. Require `workflow.profile: implementation-spoke`.
+3. Require `workflow.upstream` and require that store ID in `references`.
+4. Run `specflow change new --spec <spec-id>`. The CLI resolves the registered
+   upstream, requires `specflow/specs/<spec-id>/spec.md`, creates a same-name
+   local change, and records the source store/spec/digest plus Git commit/tag
+   when available.
+5. Run `specflow show <spec-id> --type spec --store <workflow.upstream>` and
+   read the complete baseline spec before generating artifacts.
+
+If the Hub has not archived the spec into its baseline `specs/` directory,
+stop. Do not read an active Hub change as a stable dependency.
+
+The Hub baseline spec is authoritative for cross-repository behavior, but all
+four generated artifacts belong to the current Spoke:
+
+- proposal: cite the source binding and limit impact to this repository;
+- delta specs: express only this repository's testable behavior;
+- design: describe this repository's implementation decisions;
+- tasks: contain only this repository's implementation work.
+
+Do not copy Hub proposal/design/tasks into the Spoke and do not redefine the
+cross-repository contract.
+
 ## Prerequisites
 
 - `specflow/specs/` directory should exist, indicating this is a specflow-initialized project. For a brand-new greenfield change with no existing specs, proceed — the prompt handles that case. If `specflow/` itself does not exist, suggest running `specflow init` first.
@@ -26,6 +73,10 @@ or tasks. Reuse the resolved policy for all four artifacts.
 
 ## Stage 0: Explore Handoff (when explore.md exists)
 
+In Upstream Spec mode, use the resolved Hub baseline spec as the requirements
+handoff and skip the local explore requirement. Otherwise follow the existing
+explore handoff below.
+
 Before creating a new change or generating a proposal, check for an existing exploration artifact:
 
 ```bash
@@ -53,7 +104,11 @@ ls specflow/changes/<name>/explore.md 2>/dev/null
 
 ## Stage 1: Create Change
 
-Run `specflow change new <name>` to initialize a new change directory.
+- Upstream Spec mode: if the same-name change does not exist, run
+  `specflow change new --spec <spec-id>`. If it already exists, read
+  `.specflow.yaml`, require its `source.store` and `source.spec` to match the
+  current configuration and argument, and resume without overwriting artifacts.
+- Existing single-repository flow: run `specflow change new <name>`.
 
 The CLI automatically sets `phase=propose` in `.specflow.yaml` on creation (no separate phase call needed here).
 
@@ -65,6 +120,9 @@ Read the file at `.claude/specflow/prompts/propose/proposal.md` and follow its i
 
 Generate the proposal document inside the change directory at `specflow/changes/<name>/proposal.md`.
 
+In Upstream Spec mode, the proposal MUST name the bound upstream store, spec,
+digest, and commit/tag when present in `.specflow.yaml`.
+
 ### Gate: Proposal Confirmation (HARD GATE)
 
 Present the proposal to the user.
@@ -77,6 +135,9 @@ Read the file at `.claude/specflow/prompts/propose/specs.md` and follow its inst
 
 Generate delta specs inside the change directory at `specflow/changes/<name>/specs/<capability>/spec.md`.
 
+In Upstream Spec mode, derive these scenarios from the Hub baseline while
+keeping only behavior testable in the current Spoke.
+
 ### Gate: Specs Confirmation (optional light gate)
 
 Briefly summarize the delta specs generated. Accept a quick acknowledgement from the user ("looks good" / "continue") and proceed. If the user raises substantive objections, pause and revise — otherwise continue directly to Stage 4. This is an optional checkpoint, not a full hard gate; deeper scrutiny will happen in `/specflow:refine`.