@gordon.gan/specflow 1.1.1 → 1.2.0-beta.1

package/dist/core/store/registry.js

@@ -0,0 +1,128 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { acquireFileLock, releaseFileLock, writeFileAtomically, makeLockErrorFactory, } from '../file-state.js';
+import { StoreRegistrySchema, emptyRegistry, pathsReferToSameCheckout, StoreError, } from './foundation.js';
+function lockPathFor(registryPath) {
+    return `${registryPath}.lock`;
+}
+function makeRegistryLockError() {
+    return makeLockErrorFactory({
+        createSubject: 'the registry lock file',
+        busyMessage: 'Store registry is busy.',
+        code: 'registry_busy',
+        target: 'stores.registry',
+    });
+}
+export async function readRegistry(registryPath) {
+    try {
+        const content = await fs.readFile(registryPath, 'utf-8');
+        const parsed = yaml.load(content);
+        const result = StoreRegistrySchema.safeParse(parsed);
+        if (!result.success) {
+            throw new StoreError('Store registry is corrupt.', {
+                severity: 'error',
+                code: 'registry_corrupt',
+                message: 'Store registry failed schema validation.',
+                target: 'stores.registry',
+                fix: 'Repair or delete the registry file and re-register stores.',
+            });
+        }
+        return result.data;
+    }
+    catch (error) {
+        if (error instanceof StoreError) {
+            throw error;
+        }
+        if (error.code === 'ENOENT') {
+            return emptyRegistry();
+        }
+        throw error;
+    }
+}
+async function writeRegistry(registryPath, state) {
+    const content = yaml.dump(state, { lineWidth: -1, noRefs: true });
+    await writeFileAtomically(registryPath, content);
+}
+export async function updateRegistry(registryPath, updater) {
+    const lock = await acquireFileLock({
+        lockPath: lockPathFor(registryPath),
+        errorFor: makeRegistryLockError(),
+    });
+    try {
+        const current = await readRegistry(registryPath);
+        const next = updater(current);
+        const validated = StoreRegistrySchema.parse(next);
+        await writeRegistry(registryPath, validated);
+        return validated;
+    }
+    finally {
+        await releaseFileLock(lock, lockPathFor(registryPath));
+    }
+}
+export function findPathConflict(registry, targetPath, storeId, platform = process.platform) {
+    for (const [existingId, entry] of Object.entries(registry.stores)) {
+        if (existingId === storeId) {
+            continue;
+        }
+        if (pathsReferToSameCheckout(entry.backend.local_path, targetPath, platform)) {
+            return existingId;
+        }
+    }
+    return null;
+}
+export async function registerStoreEntry(registryPath, input) {
+    const canonicalPath = path.resolve(input.localPath);
+    let alreadyRegistered = false;
+    const registry = await updateRegistry(registryPath, (state) => {
+        const existing = state.stores[input.id];
+        if (existing) {
+            if (pathsReferToSameCheckout(existing.backend.local_path, canonicalPath)) {
+                alreadyRegistered = true;
+                return state;
+            }
+            throw new StoreError(`Store '${input.id}' is already registered at another path.`, {
+                severity: 'error',
+                code: 'store_id_conflict',
+                message: `Store '${input.id}' is already registered elsewhere.`,
+                target: `stores.${input.id}`,
+                fix: 'Unregister the existing checkout or choose another store ID.',
+            });
+        }
+        const aliasConflict = findPathConflict(state, canonicalPath, input.id);
+        if (aliasConflict) {
+            throw new StoreError(`Path already registered as '${aliasConflict}'.`, {
+                severity: 'error',
+                code: 'store_path_conflict',
+                message: `The checkout path is already registered under '${aliasConflict}'.`,
+                target: 'stores.registry',
+                fix: 'Use the existing registration or unregister the conflicting store first.',
+            });
+        }
+        return {
+            version: 1,
+            stores: {
+                ...state.stores,
+                [input.id]: {
+                    provenance: input.provenance,
+                    backend: {
+                        type: 'git',
+                        local_path: canonicalPath,
+                        ...(input.remote ? { remote: input.remote } : {}),
+                        ...(input.branch ? { branch: input.branch } : {}),
+                    },
+                },
+            },
+        };
+    });
+    return { registry, alreadyRegistered };
+}
+export async function unregisterStoreEntry(registryPath, storeId) {
+    return updateRegistry(registryPath, (state) => {
+        if (!state.stores[storeId]) {
+            return state;
+        }
+        const { [storeId]: _removed, ...rest } = state.stores;
+        return { version: 1, stores: rest };
+    });
+}

package/dist/core/working-set.d.ts

@@ -0,0 +1,30 @@
+import type { Diagnostic } from './diagnostics.js';
+export interface WorkingSetMember {
+    readonly storeId: string;
+    readonly path?: string;
+    readonly healthy: boolean;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly fetchRecipe?: string;
+}
+export interface WorkingSet {
+    readonly members: readonly WorkingSetMember[];
+}
+export declare function assembleWorkingSet(input: {
+    root: {
+        storeId: string;
+        path: string;
+        healthy: boolean;
+    };
+    references: Array<{
+        storeId: string;
+        healthy: boolean;
+        path?: string;
+        diagnostics: Diagnostic[];
+    }>;
+}): WorkingSet;
+export declare function buildWorkingSetCodeWorkspaceJson(workingSet: WorkingSet): {
+    folders: Array<{
+        name: string;
+        path: string;
+    }>;
+};

package/dist/core/working-set.js

@@ -0,0 +1,26 @@
+export function assembleWorkingSet(input) {
+    const members = [
+        {
+            storeId: input.root.storeId,
+            path: input.root.path,
+            healthy: input.root.healthy,
+            diagnostics: [],
+            fetchRecipe: `specflow context --store ${input.root.storeId}`,
+        },
+        ...input.references.map((ref) => ({
+            storeId: ref.storeId,
+            path: ref.healthy ? ref.path : undefined,
+            healthy: ref.healthy,
+            diagnostics: ref.diagnostics,
+            fetchRecipe: ref.healthy ? `specflow show <spec-id> --type spec --store ${ref.storeId}` : undefined,
+        })),
+    ];
+    return { members };
+}
+export function buildWorkingSetCodeWorkspaceJson(workingSet) {
+    return {
+        folders: workingSet.members
+            .filter((member) => member.healthy && member.path)
+            .map((member) => ({ name: member.storeId, path: member.path })),
+    };
+}

package/dist/core/worksets.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+export interface WorksetMember {
+    readonly name: string;
+    readonly path: string;
+}
+export interface Workset {
+    readonly name: string;
+    readonly members: readonly WorksetMember[];
+    readonly tool?: string;
+}
+declare const WorksetsStateSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    worksets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        members: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            path: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            path: string;
+            name: string;
+        }, {
+            path: string;
+            name: string;
+        }>, "many">;
+        tool: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        members: {
+            path: string;
+            name: string;
+        }[];
+        tool?: string | undefined;
+    }, {
+        name: string;
+        members: {
+            path: string;
+            name: string;
+        }[];
+        tool?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    worksets: {
+        name: string;
+        members: {
+            path: string;
+            name: string;
+        }[];
+        tool?: string | undefined;
+    }[];
+    version: 1;
+}, {
+    worksets: {
+        name: string;
+        members: {
+            path: string;
+            name: string;
+        }[];
+        tool?: string | undefined;
+    }[];
+    version: 1;
+}>;
+export type WorksetsState = z.infer<typeof WorksetsStateSchema>;
+export declare function validateWorksetName(name: string): void;
+export declare function validateWorksetMembers(members: readonly WorksetMember[]): void;
+export declare function readWorksetsState(statePath: string): Promise<WorksetsState>;
+export declare function updateWorksetsState(statePath: string, updater: (state: WorksetsState) => WorksetsState): Promise<WorksetsState>;
+export declare function withWorkset(state: WorksetsState, workset: Workset): WorksetsState;
+export declare function getWorksetCodeWorkspacePath(dataDir: string, name: string): string;
+export declare function defaultWorksetsStatePath(dataDir?: string): string;
+export declare function removeWorksetByName(statePath: string, name: string, dataDir: string): Promise<boolean>;
+export {};

package/dist/core/worksets.js

@@ -0,0 +1,134 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { z } from 'zod';
+import { acquireFileLock, releaseFileLock, writeFileAtomically, makeLockErrorFactory } from './file-state.js';
+import { getWorksetsStatePath } from './global-config.js';
+import { StoreError } from './store/foundation.js';
+const KEBAB_CASE_NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const WorksetMemberSchema = z.object({ name: z.string(), path: z.string() }).strict();
+const WorksetSchema = z
+    .object({
+    name: z.string(),
+    members: z.array(WorksetMemberSchema).min(1),
+    tool: z.string().optional(),
+})
+    .strict();
+const WorksetsStateSchema = z.object({
+    version: z.literal(1),
+    worksets: z.array(WorksetSchema),
+});
+function lockPathFor(statePath) {
+    return `${statePath}.lock`;
+}
+function makeWorksetLockError() {
+    return makeLockErrorFactory({
+        createSubject: 'the workset lock file',
+        busyMessage: 'Workset state is busy.',
+        code: 'workset_busy',
+        target: 'worksets.state',
+    });
+}
+export function validateWorksetName(name) {
+    if (!KEBAB_CASE_NAME.test(name)) {
+        throw new StoreError(`Invalid workset name '${name}'.`, {
+            severity: 'error',
+            code: 'invalid_workset_name',
+            message: 'Workset names must be kebab-case.',
+            target: 'workset.name',
+        });
+    }
+}
+export function validateWorksetMembers(members) {
+    if (members.length === 0) {
+        throw new StoreError('Workset must contain at least one member.', {
+            severity: 'error',
+            code: 'invalid_workset_members',
+            message: 'Worksets require at least one member.',
+            target: 'workset.members',
+        });
+    }
+    const labels = new Set();
+    for (const member of members) {
+        if (!path.isAbsolute(member.path)) {
+            throw new StoreError(`Member path must be absolute: ${member.path}`, {
+                severity: 'error',
+                code: 'invalid_workset_path',
+                message: 'Workset member paths must be absolute.',
+                target: `workset.members.${member.name}`,
+            });
+        }
+        if (labels.has(member.name)) {
+            throw new StoreError(`Duplicate workset member label '${member.name}'.`, {
+                severity: 'error',
+                code: 'duplicate_workset_member',
+                message: 'Workset member labels must be unique.',
+                target: `workset.members.${member.name}`,
+            });
+        }
+        labels.add(member.name);
+    }
+}
+export async function readWorksetsState(statePath) {
+    try {
+        const content = await fs.readFile(statePath, 'utf-8');
+        const parsed = yaml.load(content);
+        return WorksetsStateSchema.parse(parsed);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { version: 1, worksets: [] };
+        }
+        throw error;
+    }
+}
+async function writeWorksetsState(statePath, state) {
+    const content = yaml.dump(state, { lineWidth: -1, noRefs: true });
+    await writeFileAtomically(statePath, content);
+}
+export async function updateWorksetsState(statePath, updater) {
+    const lock = await acquireFileLock({
+        lockPath: lockPathFor(statePath),
+        errorFor: makeWorksetLockError(),
+    });
+    try {
+        const current = await readWorksetsState(statePath);
+        const next = WorksetsStateSchema.parse(updater(current));
+        await writeWorksetsState(statePath, next);
+        return next;
+    }
+    finally {
+        await releaseFileLock(lock, lockPathFor(statePath));
+    }
+}
+export function withWorkset(state, workset) {
+    validateWorksetName(workset.name);
+    validateWorksetMembers(workset.members);
+    const without = state.worksets.filter((entry) => entry.name !== workset.name);
+    return { version: 1, worksets: [...without, workset].sort((a, b) => a.name.localeCompare(b.name)) };
+}
+export function getWorksetCodeWorkspacePath(dataDir, name) {
+    return path.join(dataDir, 'worksets', `${name}.code-workspace`);
+}
+export function defaultWorksetsStatePath(dataDir) {
+    return getWorksetsStatePath(dataDir);
+}
+export async function removeWorksetByName(statePath, name, dataDir) {
+    let removed = false;
+    await updateWorksetsState(statePath, (state) => {
+        const exists = state.worksets.some((entry) => entry.name === name);
+        if (!exists) {
+            return state;
+        }
+        removed = true;
+        return {
+            version: 1,
+            worksets: state.worksets.filter((entry) => entry.name !== name),
+        };
+    });
+    if (removed) {
+        const workspacePath = getWorksetCodeWorkspacePath(dataDir, name);
+        await fs.rm(workspacePath, { force: true }).catch(() => undefined);
+    }
+    return removed;
+}

package/dist/integrations/shared/skill-renderer.d.ts

@@ -1,4 +1,10 @@
 import type { IdeTarget } from './types.js';
+import type { ReferencedStoresSection } from '../../core/artifact-graph/instruction-loader.js';
+export interface ReferenceGuidanceInput {
+    readonly referencedStores?: ReferencedStoresSection;
+}
+/** Renders identical reference guidance for every IDE target. */
+export declare function collectReferenceGuidance(input: ReferenceGuidanceInput): Record<IdeTarget, string>;
 export declare function renderIdeContent(content: string, ide: IdeTarget): string;
 /** @deprecated Use renderIdeContent */
 export declare const renderSkillContent: typeof renderIdeContent;

package/dist/integrations/shared/skill-renderer.js

@@ -1,4 +1,26 @@
 import { COMMAND_CATALOG } from './command-catalog.js';
+function formatReferenceBlock(section) {
+    if (!section || section.rendered.trim().length === 0) {
+        return '';
+    }
+    const lines = [
+        '## Referenced store index (read-only)',
+        section.rendered,
+    ];
+    if (section.truncated) {
+        lines.push('Index truncated. Use `specflow show <spec-id> --type spec --store <store-id>` to fetch full specs.');
+    }
+    return lines.join('\n');
+}
+/** Renders identical reference guidance for every IDE target. */
+export function collectReferenceGuidance(input) {
+    const block = formatReferenceBlock(input.referencedStores);
+    return {
+        claude: block,
+        cursor: block,
+        codex: block,
+    };
+}
 function runtimePrefix(ide) {
     if (ide === 'claude') {
         return '.claude/specflow/';

package/package.json

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

package/prompts/shared/artifact-language.md

@@ -0,0 +1,30 @@
+# Artifact Language Policy
+
+Before creating or rewriting any SpecFlow artifact:
+
+1. Read `specflow/config.yaml` from the active planning root.
+2. Resolve `artifacts.language`:
+   - `en` → write human-readable artifact content in English.
+   - `zh-CN` → write human-readable artifact content in Simplified Chinese.
+   - Missing → default to `en`.
+   - Invalid → report the invalid value and use `en`; do not invent another language.
+3. Apply the selected language consistently to narrative prose, requirement and scenario descriptions, design rationale, and task descriptions.
+
+## Protected Protocol
+
+Language selection never changes SpecFlow's machine-readable protocol. Keep these tokens exactly as written:
+
+- `## ADDED Requirements`
+- `## MODIFIED Requirements`
+- `## REMOVED Requirements`
+- `## RENAMED Requirements`
+- `### Requirement:`
+- `#### Scenario:`
+- `- **WHEN**`
+- `- **THEN**`
+- `FROM:`
+- `TO:`
+
+Also preserve capability IDs, change names, file paths, commands, code, symbols, and established technical identifiers.
+
+When modifying an existing requirement, preserve its exact requirement name if delta matching depends on that name. Do not translate historical artifacts automatically; the configured language applies prospectively to content created or intentionally rewritten in the current workflow.

package/skills/specflow-apply/SKILL.md

@@ -5,15 +5,6 @@ description: "Two-phase apply — task rewrite + subagent TDD execution"
 
 # SpecFlow: Apply
 
-## Invocation mode
-
-Inspect the current user invocation before any stage work:
-
-- **Default mode:** `/specflow:apply` preserves every existing user confirmation gate and the default interactive behavior.
-- **Yes mode:** `/specflow:apply --yes` records non-interactive confirmation mode for the current invocation only. It auto-accepts only successful acknowledgement gates; it never bypasses prerequisites, gap detection, failing verification, or a review `Block`.
-
-Report the selected mode once at the start of the session. Do not persist it to future invocations.
-
 > **HARD GATE (prerequisite)**: phase must be `refined`. Run /specflow:refine first if not.
 > **HARD GATE (Phase A)**: rewritten tasks.md must be user-confirmed before Phase B.
 > **HARD GATE (Phase B)**: each task must be reviewed (spec + code quality) and user-confirmed before next task.
@@ -27,6 +18,13 @@ Report the selected mode once at the start of the session. Do not persist it to
 - Existing `tasks.md` is present (coarse first-iteration from `/specflow:propose`, or a refine-updated version).
 - `specflow` CLI is available on PATH.
 
+## Artifact Language Setup
+
+Before Phase A rewrites `tasks.md`, read
+`.claude/specflow/prompts/shared/artifact-language.md` and resolve the active
+planning root's `specflow/config.yaml`. Apply the policy to rewritten task
+descriptions while preserving paths, commands, code, and symbols.
+
 ---
 
 ## Phase A: Task Rewrite
@@ -65,10 +63,7 @@ Present the audit summary to the user: per-group task count (coarse → atomic),
 
 ### Gate A: Rewrite Confirmation
 
-- **Default mode:** Present the rewritten `tasks.md` and ask the user to confirm the rewrite. Do NOT proceed to Phase B until the user explicitly confirms.
-- **Yes mode:** Present the rewrite audit and continue directly to Phase B after recording the rewrite as automatically accepted for this invocation.
-
-If Phase A reports a reorganization choice or a design gap, stop regardless of mode; `--yes` does not choose a reorganization or fill a missing design decision.
+Present the rewritten `tasks.md` to the user. **Ask the user to confirm the rewrite.** Do NOT proceed to Phase B until the user explicitly confirms.
 
 ---
 
@@ -120,26 +115,16 @@ ECC reviewer verdict routing:
 
 #### Gate B: Per-task Confirmation
 
-- **Default mode:** Present the task output and both review reports. Ask the user to confirm the task is complete. Do NOT proceed to the next task until confirmation is received.
-- **Yes mode:** Present the task output and both review reports. If spec review passes and code-quality review returns `Approve` or `Warning`, record the task as automatically accepted and start the next task without waiting.
+Present the task output and both review reports to the user. **Ask the user to confirm the task is complete.** Do NOT proceed to the next task until confirmation is received.
 
-If either review blocks, return to Stage B2a for the same task. `--yes` never advances past a blocked review.
+If the user rejects, return to Stage B2a for the same task.
 
 ### Stage B3: Phase Transition
 
-Once all tasks are confirmed in default mode or automatically accepted in yes mode:
+Once all tasks are confirmed:
 - Invoke `specflow change phase <name> --set apply` to transition the phase.
 - Summarize the build results and overall coverage.
-
-#### Yes-mode downstream sequence
-
-When yes mode reaches this point:
-1. Invoke `/specflow:review`. Stop if it reports a CRITICAL or HIGH finding.
-2. Invoke `/specflow:test` only after review has no CRITICAL/HIGH findings. Stop if tests cannot be made green.
-3. Invoke `/specflow:verify` only after test succeeds. Stop if verify returns `FAIL`.
-4. Report review, test, and verification evidence. Do NOT invoke `/specflow:archive` automatically; archive remains the user's manual choice.
-
-When default mode reaches this point, inform the user that they can now run `/specflow:review` or `/specflow:verify`.
+- Inform the user they can now run `/specflow:review` or `/specflow:verify`.
 
 ---
 

package/skills/specflow-explore/SKILL.md

@@ -33,6 +33,12 @@ Skip explore when you already know exactly what to build — run `/specflow:prop
 - `specflow/` exists (suggest `specflow init` if missing)
 - `specflow` CLI available on PATH
 
+## Artifact Language Setup
+
+Read `.claude/specflow/prompts/shared/artifact-language.md` and resolve the active
+planning root's `specflow/config.yaml` before writing or rewriting `explore.md`.
+Apply that policy to every artifact created by this workflow.
+
 ## Stage 1: Create or Reuse Change
 
 If no active change directory exists for this work:

package/skills/specflow-propose/SKILL.md

@@ -18,6 +18,12 @@ Treat every artifact here as "v1, to be iterated on" — depth matters, but so d
 - `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.
 - `specflow` CLI must be available on PATH.
 
+## Artifact Language Setup
+
+Read `.claude/specflow/prompts/shared/artifact-language.md` and resolve the active
+planning root's `specflow/config.yaml` before generating proposal, specs, design,
+or tasks. Reuse the resolved policy for all four artifacts.
+
 ## Stage 0: Explore Handoff (when explore.md exists)
 
 Before creating a new change or generating a proposal, check for an existing exploration artifact:

package/skills/specflow-refine/SKILL.md

@@ -26,6 +26,12 @@ emits a round diff summary.
 
 If any precondition fails, stop and instruct the user to run `/specflow:propose` first.
 
+## Artifact Language Setup
+
+Read `.claude/specflow/prompts/shared/artifact-language.md` and resolve the active
+planning root's `specflow/config.yaml` before refining any artifact. Preserve
+existing requirement names where delta matching requires exact identity.
+
 ## Stage 1: Pre-loop setup
 
 Read, in order:

package/skills/specflow-snap/SKILL.md

@@ -10,6 +10,12 @@ description: "Post-hoc change documentation from git diff"
 - Git repository must have uncommitted or recent committed changes to document.
 - `specflow` CLI must be available on PATH.
 
+## Artifact Language Setup
+
+Read `.claude/specflow/prompts/shared/artifact-language.md` and resolve the active
+planning root's `specflow/config.yaml` before synthesizing proposal, specs, or
+tasks. Reuse the resolved policy for every generated artifact.
+
 ## Stage 1: Analyze Changes
 
 Run `git diff` and `git log` to capture what changed.