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

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/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.0-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`.