@gordon.gan/specflow 1.1.1 → 1.2.0-beta

package/README.md

@@ -13,6 +13,10 @@ SpecFlow 把 **OpenSpec**（结构化需求规划）和 **Superpowers**（TDD、
 | 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) |
+| 多语言 / Go Profile | SpecFlow + 语言专项 skills | [语言 Profile 指南](./LANGUAGE_PROFILE_USAGE_GUIDE.md) |
+| 多仓 / 前后端一体需求 | Contract Hub + Spokes + 产物说明 | [多仓完整指南](./MULTI_REPO_GUIDE.md) |
+| 多仓原生能力（设计） | Store / References / Workset | [多仓技术方案](./MULTI_REPO_TECHNICAL_DESIGN.md) |
+| 产物与作用 | explore / proposal / delta / design / tasks / 主 specs | [产物说明](./SPECFLOW_ARTIFACTS.md) |
 
 ---
 
@@ -269,6 +273,8 @@ CLI 从当前目录**向上查找**项目根（识别 `specflow/config.yaml`）
 
 ## 关键概念
 
+各产物职责、门禁与命令对照的完整说明见 [SPECFLOW_ARTIFACTS.md](./SPECFLOW_ARTIFACTS.md)。
+
 ### Specs — 唯一事实来源
 
 存放在 `specflow/specs/`，描述各 capability 的行为规格：

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

@@ -6,7 +6,7 @@
 import { join } from 'node:path';
 import * as fs from 'node:fs';
 import { archiveChange } from '../../core/archive.js';
-import { requireProjectRoot } from '../../utils/project-root.js';
+import { addStoreOption, resolveRootFromCommandOptions } from '../shared/store-option.js';
 /**
  * Archives a change, throwing on failure.
  *
@@ -36,15 +36,15 @@ export async function archiveChangeCommand(changeName, projectRoot, options = {}
  * Registers the `change archive` subcommand with Commander.
  */
 export function registerChangeArchiveCommand(changeCmd) {
-    changeCmd
+    addStoreOption(changeCmd
         .command('archive <name>')
         .description('Archive a completed change')
         .option('--force', 'Archive even if the change is not in phase=apply')
         .action(async (name, opts) => {
-        const projectRoot = requireProjectRoot();
+        const projectRoot = await resolveRootFromCommandOptions({ store: opts.store });
         const result = await archiveChangeCommand(name, projectRoot, {
             force: opts.force ?? false,
         });
         console.info(`Archived change "${name}" to ${result.archivePath}`);
-    });
+    }));
 }

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

@@ -6,7 +6,7 @@
 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 { addStoreOption, resolveRootFromCommandOptions } from '../shared/store-option.js';
 const CHANGES_REL_PATH = 'specflow/changes';
 /**
  * Returns today's date as YYYY-MM-DD string.
@@ -42,12 +42,12 @@ export async function createChange(name, projectRoot) {
  * Registers the `change new` subcommand with Commander.
  */
 export function registerChangeNewCommand(changeCmd) {
-    changeCmd
+    addStoreOption(changeCmd
         .command('new <name>')
         .description('Create a new change directory')
-        .action(async (name) => {
-        const projectRoot = requireProjectRoot();
+        .action(async (name, opts) => {
+        const projectRoot = await resolveRootFromCommandOptions({ store: opts.store });
         await createChange(name, projectRoot);
         console.info(`Created change: ${name}`);
-    });
+    }));
 }

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

@@ -4,7 +4,7 @@
  * Read or update the lifecycle phase of a change.
  */
 import { CHANGE_PHASES, getChangeMetadata, normalizeChangePhase, updatePhase, } from '../../utils/change-utils.js';
-import { requireProjectRoot } from '../../utils/project-root.js';
+import { addStoreOption, resolveRootFromCommandOptions } from '../shared/store-option.js';
 /**
  * Returns true if the candidate value is a valid ChangePhase.
  */
@@ -50,12 +50,12 @@ export async function setPhase(name, phase, projectRoot) {
  *   specflow change phase <name> --set refined # update phase
  */
 export function registerChangePhaseCommand(changeCmd) {
-    changeCmd
+    addStoreOption(changeCmd
         .command('phase <name>')
         .description('Show or set the lifecycle phase of a change')
         .option('--set <value>', 'Set the phase to the given value')
         .action(async (name, opts) => {
-        const projectRoot = requireProjectRoot();
+        const projectRoot = await resolveRootFromCommandOptions({ store: opts.store });
         if (opts.set !== undefined) {
             await setPhase(name, opts.set, projectRoot);
             console.info(`Change "${name}" phase set to ${opts.set}`);
@@ -63,5 +63,5 @@ export function registerChangePhaseCommand(changeCmd) {
         }
         const phase = await getPhase(name, projectRoot);
         console.info(phase ?? '(unset)');
-    });
+    }));
 }

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

@@ -9,8 +9,8 @@ import yaml from 'js-yaml';
 import { resolveSchema } from '../../core/artifact-graph/resolver.js';
 import { getCompletedArtifacts, getInProgressArtifacts } from '../../core/artifact-graph/state.js';
 import { formatStatus } from '../../core/artifact-graph/outputs.js';
-import { requireProjectRoot } from '../../utils/project-root.js';
 import { readChangeMetadata } from '../../utils/change-metadata.js';
+import { addStoreOption, resolveRootFromCommandOptions } from '../shared/store-option.js';
 /**
  * Reads the project config to determine the schema name.
  */
@@ -87,12 +87,12 @@ export function formatChangeStatus(status) {
  * Registers the `change status` subcommand with Commander.
  */
 export function registerChangeStatusCommand(changeCmd) {
-    changeCmd
+    addStoreOption(changeCmd
         .command('status <name>')
         .description('Show artifact status for a change')
         .option('--json', 'Output as JSON')
         .action(async (name, opts) => {
-        const projectRoot = requireProjectRoot();
+        const projectRoot = await resolveRootFromCommandOptions({ store: opts.store });
         const status = await getChangeStatus(name, projectRoot);
         if (opts.json) {
             console.info(JSON.stringify(status, null, 2));
@@ -100,5 +100,5 @@ export function registerChangeStatusCommand(changeCmd) {
         else {
             console.info(formatChangeStatus(status));
         }
-    });
+    }));
 }

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

@@ -0,0 +1,18 @@
+import type { Command } from 'commander';
+import { assembleWorkingSet } from '../../core/working-set.js';
+import type { Diagnostic } from '../../core/diagnostics.js';
+import { type RelationshipHealthResult } from '../../core/relationship-health.js';
+export interface ContextCommandOptions {
+    store?: string;
+    cwd?: string;
+    codeWorkspacePath?: string;
+    force?: boolean;
+    registryPath?: string;
+}
+export declare function runContextCommand(options?: ContextCommandOptions): Promise<{
+    workingSet: ReturnType<typeof assembleWorkingSet>;
+    workspacePath?: string;
+    status: readonly Diagnostic[];
+    relationships: RelationshipHealthResult;
+}>;
+export declare function registerContextCommand(program: Command): void;

package/dist/cli/commands/context.js

@@ -0,0 +1,125 @@
+import { promises as fs } from 'node:fs';
+import { readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { StoreError } from '../../core/store/foundation.js';
+import { buildWorkingSetCodeWorkspaceJson } from '../../core/working-set.js';
+import { assembleContextFromRoot } from '../../core/context-assembly.js';
+import { resolveCommandPlanningRoot, addStoreOption } from '../shared/store-option.js';
+import { readRegistry } from '../../core/store/registry.js';
+import { getStoreRegistryPath } from '../../core/global-config.js';
+import { parseProjectConfig } from '../../core/project-config.js';
+import { normalizeReferences } from '../../core/references.js';
+import { inspectRelationships, } from '../../core/relationship-health.js';
+export async function runContextCommand(options = {}) {
+    const registry = await readRegistry(options.registryPath ?? getStoreRegistryPath());
+    const resolved = await resolveCommandPlanningRoot({
+        cwd: options.cwd,
+        store: options.store,
+        registry,
+    });
+    const assembled = await assembleContextFromRoot(resolved, registry);
+    let projectConfig = parseProjectConfig({});
+    try {
+        const configPath = path.join(resolved.root, 'specflow', 'config.yaml');
+        projectConfig = parseProjectConfig(yaml.load(readFileSync(configPath, 'utf-8')));
+    }
+    catch {
+        // empty config when unavailable
+    }
+    const rootStoreId = resolved.storeId;
+    const references = normalizeReferences(projectConfig.references, rootStoreId);
+    const relationships = await inspectRelationships({
+        resolved,
+        references,
+        registry,
+        projectConfig,
+    });
+    if (!options.codeWorkspacePath) {
+        return {
+            workingSet: assembled.workingSet,
+            status: assembled.diagnostics,
+            relationships,
+        };
+    }
+    if (!options.force) {
+        try {
+            await fs.stat(options.codeWorkspacePath);
+            throw new StoreError('Workspace file already exists.', {
+                severity: 'error',
+                code: 'workspace_exists',
+                message: 'Refusing to overwrite an existing workspace file without --force.',
+                target: 'context.codeWorkspace',
+                fix: 'Pass --force to overwrite the file.',
+            });
+        }
+        catch (error) {
+            if (error instanceof StoreError) {
+                throw error;
+            }
+        }
+    }
+    const json = buildWorkingSetCodeWorkspaceJson(assembled.workingSet);
+    await fs.writeFile(options.codeWorkspacePath, JSON.stringify(json, null, 2) + '\n', 'utf-8');
+    return {
+        workingSet: assembled.workingSet,
+        workspacePath: options.codeWorkspacePath,
+        status: assembled.diagnostics,
+        relationships,
+    };
+}
+export function registerContextCommand(program) {
+    addStoreOption(program
+        .command('context')
+        .description('Show the derived working set for the resolved planning root')
+        .option('--code-workspace <path>', 'Write a VS Code workspace file for healthy members')
+        .option('--force', 'Overwrite an existing workspace file')
+        .option('--relationships', 'Include relationship health categories in human output')
+        .option('--json', 'Output as JSON')
+        .action(async (opts) => {
+        try {
+            const result = await runContextCommand({
+                store: opts.store,
+                codeWorkspacePath: opts.codeWorkspace,
+                force: opts.force,
+            });
+            const payload = {
+                working_set: result.workingSet,
+                workspace_path: result.workspacePath ?? null,
+                relationships: {
+                    root_health: result.relationships.rootHealth,
+                    selected_store_health: result.relationships.selectedStoreHealth,
+                    reference_health: result.relationships.referenceHealth,
+                    registry_health: result.relationships.registryHealth,
+                    pointer_health: result.relationships.pointerHealth,
+                    mutations_performed: result.relationships.mutationsPerformed,
+                },
+                status: result.status,
+            };
+            if (opts.json) {
+                console.log(JSON.stringify(payload, null, 2));
+            }
+            else {
+                console.log(JSON.stringify(payload.working_set, null, 2));
+                if (opts.relationships) {
+                    console.log(JSON.stringify(payload.relationships, null, 2));
+                }
+                for (const diagnostic of result.status) {
+                    console.error(`${diagnostic.severity}: ${diagnostic.message}`);
+                }
+            }
+        }
+        catch (error) {
+            const diagnostics = error instanceof StoreError
+                ? error.diagnostics
+                : [{ severity: 'error', code: 'context_error', message: String(error) }];
+            if (opts.json) {
+                console.log(JSON.stringify({ working_set: null, status: diagnostics }, null, 2));
+            }
+            else {
+                console.error(diagnostics.map((d) => d.message).join('\n'));
+            }
+            process.exit(1);
+        }
+    }));
+}

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

@@ -14,7 +14,10 @@ import type { ArtifactInstructions } from '../../core/artifact-graph/instruction
  * @returns The artifact instructions with dependencies and output path
  * @throws When the artifact or change is not found
  */
-export declare function getInstructions(artifactId: string, changeName: string, projectRoot: string): Promise<ArtifactInstructions>;
+export declare function getInstructions(artifactId: string, changeName: string, projectRoot: string, options?: {
+    store?: string;
+    cwd?: string;
+}): Promise<ArtifactInstructions>;
 /**
  * Registers the `instructions` command with Commander.
  */

package/dist/cli/commands/instructions.js

@@ -8,7 +8,12 @@ import * as fs from 'node:fs';
 import yaml from 'js-yaml';
 import { resolveSchema } from '../../core/artifact-graph/resolver.js';
 import { loadInstructions } from '../../core/artifact-graph/instruction-loader.js';
-import { requireProjectRoot } from '../../utils/project-root.js';
+import { addStoreOption, resolveCommandPlanningRoot } from '../shared/store-option.js';
+import { parseProjectConfig } from '../../core/project-config.js';
+import { buildReferencedStoreIndex } from '../../core/reference-index.js';
+import { readRegistry } from '../../core/store/registry.js';
+import { getStoreRegistryPath } from '../../core/global-config.js';
+import { collectReferenceGuidance } from '../../integrations/shared/skill-renderer.js';
 /**
  * Reads the project config to determine the schema name and optional context.
  */
@@ -18,13 +23,46 @@ function readProjectConfig(projectRoot) {
         const content = fs.readFileSync(configPath, 'utf-8');
         const parsed = yaml.load(content);
         const schemaName = typeof parsed?.schema === 'string' ? parsed.schema : 'specflow';
-        const config = { context: typeof parsed?.context === 'string' ? parsed.context : undefined };
-        return { schemaName, config };
+        const projectConfig = parseProjectConfig(parsed);
+        const config = {
+            context: projectConfig.context,
+            references: projectConfig.references,
+        };
+        return { schemaName, config: config };
     }
     catch {
         return { schemaName: 'specflow' };
     }
 }
+async function enrichInstructionConfig(projectRoot, options) {
+    const registry = await readRegistry(getStoreRegistryPath());
+    const resolved = await resolveCommandPlanningRoot({
+        cwd: options.cwd ?? projectRoot,
+        store: options.store,
+        registry,
+    });
+    const configPath = join(resolved.root, 'specflow', 'config.yaml');
+    let parsed = parseProjectConfig({});
+    try {
+        parsed = parseProjectConfig(yaml.load(fs.readFileSync(configPath, 'utf-8')));
+    }
+    catch {
+        // use empty config when project config is unavailable
+    }
+    const referencedStores = await buildReferencedStoreIndex({
+        references: parsed.references,
+        registry,
+        rootStoreId: resolved.storeId,
+    });
+    return {
+        context: parsed.context,
+        referencedStores,
+        rootProvenance: {
+            source: resolved.source,
+            storeId: resolved.storeId,
+        },
+    };
+}
 /**
  * Gets instructions for creating an artifact within a change.
  *
@@ -34,36 +72,47 @@ function readProjectConfig(projectRoot) {
  * @returns The artifact instructions with dependencies and output path
  * @throws When the artifact or change is not found
  */
-export async function getInstructions(artifactId, changeName, projectRoot) {
+export async function getInstructions(artifactId, changeName, projectRoot, options = {}) {
     const changeDir = join(projectRoot, 'specflow', 'changes', changeName);
     if (!fs.existsSync(changeDir)) {
         throw new Error(`Change "${changeName}" not found at ${changeDir}`);
     }
-    const { schemaName, config } = readProjectConfig(projectRoot);
+    const { schemaName } = readProjectConfig(projectRoot);
     const schema = resolveSchema(schemaName, projectRoot);
+    const config = await enrichInstructionConfig(projectRoot, options);
     return loadInstructions(artifactId, changeDir, schema, config);
 }
 /**
  * Registers the `instructions` command with Commander.
  */
 export function registerInstructionsCommand(program) {
-    program
+    addStoreOption(program
         .command('instructions <artifact-id> <change-name>')
         .description('Show instructions for creating an artifact')
         .option('--json', 'Output as JSON')
         .action(async (artifactId, changeName, opts) => {
-        const projectRoot = requireProjectRoot();
-        const instructions = await getInstructions(artifactId, changeName, projectRoot);
+        const registry = await readRegistry(getStoreRegistryPath());
+        const resolved = await resolveCommandPlanningRoot({ store: opts.store, registry });
+        const projectRoot = resolved.root;
+        const instructions = await getInstructions(artifactId, changeName, projectRoot, { store: opts.store });
         if (opts.json) {
             console.info(JSON.stringify(instructions, null, 2));
         }
         else {
             console.info(`Artifact: ${artifactId}`);
+            if (instructions.rootProvenance) {
+                console.info(`Planning root: ${instructions.rootProvenance.source}${instructions.rootProvenance.storeId ? ` (${instructions.rootProvenance.storeId})` : ''}`);
+            }
             console.info(`Generates: ${instructions.generates}`);
             console.info(`Description: ${instructions.description}`);
             if (instructions.instruction) {
                 console.info(`\nInstruction:\n${instructions.instruction}`);
             }
+            const referenceGuidance = collectReferenceGuidance({ referencedStores: instructions.referencedStores });
+            const guidance = referenceGuidance.claude;
+            if (guidance) {
+                console.info(`\n${guidance}`);
+            }
             if (instructions.dependencies.length > 0) {
                 console.info('\nDependencies:');
                 for (const dep of instructions.dependencies) {
@@ -71,5 +120,5 @@ export function registerInstructionsCommand(program) {
                 }
             }
         }
-    });
+    }));
 }

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

@@ -0,0 +1,22 @@
+import type { Diagnostic } from '../../core/diagnostics.js';
+export interface ShowSpecOptions {
+    specId: string;
+    type: 'spec';
+    storeId?: string;
+    cwd?: string;
+    json?: boolean;
+    fixtures?: {
+        content?: string;
+        root?: string;
+        storeId?: string;
+    };
+}
+export interface ShowSpecResult {
+    stdout: string;
+    stderr: string;
+    status: Diagnostic[];
+    exitCode: number;
+}
+export declare function runShowSpec(options: ShowSpecOptions): Promise<ShowSpecResult>;
+import type { Command } from 'commander';
+export declare function registerShowCommand(program: Command): void;

package/dist/cli/commands/show.js

@@ -0,0 +1,92 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { sortDiagnostics } from '../../core/diagnostics.js';
+import { resolveCommandPlanningRoot } from '../shared/store-option.js';
+export async function runShowSpec(options) {
+    let root = options.fixtures?.root;
+    let storeId = options.fixtures?.storeId ?? options.storeId;
+    let status = [];
+    if (root === undefined) {
+        const resolved = await resolveCommandPlanningRoot({
+            cwd: options.cwd,
+            store: options.storeId,
+        });
+        root = resolved.root;
+        storeId = resolved.storeId ?? options.storeId;
+        status = [...resolved.diagnostics];
+    }
+    const specPath = path.join(root, 'specflow', 'specs', options.specId, 'spec.md');
+    let content = options.fixtures?.content;
+    if (content === undefined) {
+        try {
+            content = await fs.readFile(specPath, 'utf-8');
+        }
+        catch {
+            return {
+                stdout: '',
+                stderr: `Spec '${options.specId}' not found.`,
+                status: sortDiagnostics([
+                    ...status,
+                    {
+                        severity: 'error',
+                        code: 'spec_not_found',
+                        message: `Spec '${options.specId}' not found.`,
+                        target: `specs.${options.specId}`,
+                    },
+                ]),
+                exitCode: 1,
+            };
+        }
+    }
+    if (options.json) {
+        return {
+            stdout: JSON.stringify({
+                id: options.specId,
+                type: options.type,
+                root,
+                store_id: storeId ?? null,
+                content,
+                status,
+            }, null, 2),
+            stderr: '',
+            status,
+            exitCode: 0,
+        };
+    }
+    const banner = storeId ? `Resolved store: ${storeId} (${root})\n` : `Resolved root: ${root}\n`;
+    return {
+        stdout: content,
+        stderr: banner,
+        status,
+        exitCode: 0,
+    };
+}
+import { addStoreOption } from '../shared/store-option.js';
+export function registerShowCommand(program) {
+    addStoreOption(program
+        .command('show <spec-id>')
+        .description('Show a baseline spec from the resolved planning root')
+        .option('--type <type>', 'Artifact type', 'spec')
+        .option('--json', 'Output as JSON')
+        .action(async (specId, opts) => {
+        const result = await runShowSpec({
+            specId,
+            type: opts.type === 'spec' ? 'spec' : 'spec',
+            storeId: opts.store,
+            json: opts.json,
+        });
+        if (result.stdout) {
+            process.stdout.write(result.stdout);
+            if (!result.stdout.endsWith('\n')) {
+                process.stdout.write('\n');
+            }
+        }
+        if (result.stderr) {
+            process.stderr.write(result.stderr);
+        }
+        if (result.exitCode !== 0 && opts.json) {
+            console.log(JSON.stringify({ status: result.status }, null, 2));
+        }
+        process.exit(result.exitCode);
+    }));
+}

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

@@ -0,0 +1,16 @@
+import type { Command } from 'commander';
+import { type Diagnostic } from '../../core/diagnostics.js';
+export interface StoreListOptions {
+    json?: boolean;
+    dataDir?: string;
+}
+export interface StoreListOutput {
+    stores: Array<{
+        id: string;
+        root: string;
+        provenance: string;
+    }>;
+    status: Diagnostic[];
+}
+export declare function runStoreList(options?: StoreListOptions): Promise<StoreListOutput>;
+export declare function registerStoreCommand(program: Command): void;