@gordon.gan/specflow 1.0.1 → 1.1.0

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

@@ -39,7 +39,7 @@ export function registerChangeArchiveCommand(changeCmd) {
     changeCmd
         .command('archive <name>')
         .description('Archive a completed change')
-        .option('--force', 'Archive even if the change is not in phase=built')
+        .option('--force', 'Archive even if the change is not in phase=apply')
         .action(async (name, opts) => {
         const projectRoot = requireProjectRoot();
         const result = await archiveChangeCommand(name, projectRoot, {

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

@@ -34,7 +34,7 @@ export async function createChange(name, projectRoot) {
     const metadata = {
         schema: 'specflow',
         created: todayDate(),
-        phase: 'plan',
+        phase: 'propose',
     };
     await writeChangeMetadata(name, metadata, projectRoot);
 }

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

@@ -28,6 +28,6 @@ export declare function setPhase(name: string, phase: string, projectRoot: strin
  *
  * Usage:
  *   specflow change phase <name>            # print current phase
- *   specflow change phase <name> --set propose # update phase
+ *   specflow change phase <name> --set refined # update phase
  */
 export declare function registerChangePhaseCommand(changeCmd: Command): void;

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

@@ -3,13 +3,13 @@
  *
  * Read or update the lifecycle phase of a change.
  */
-import { CHANGE_PHASES, getChangeMetadata, updatePhase, } from '../../utils/change-utils.js';
+import { CHANGE_PHASES, getChangeMetadata, normalizeChangePhase, updatePhase, } from '../../utils/change-utils.js';
 import { requireProjectRoot } from '../../utils/project-root.js';
 /**
  * Returns true if the candidate value is a valid ChangePhase.
  */
-function isChangePhase(value) {
-    return CHANGE_PHASES.includes(value);
+function resolveChangePhase(value) {
+    return normalizeChangePhase(value);
 }
 /**
  * Reads the current phase of a change.
@@ -35,18 +35,19 @@ export async function getPhase(name, projectRoot) {
  * @throws When the phase is invalid or the change does not exist
  */
 export async function setPhase(name, phase, projectRoot) {
-    if (!isChangePhase(phase)) {
+    const resolved = resolveChangePhase(phase);
+    if (resolved === null) {
         const valid = CHANGE_PHASES.join(' | ');
         throw new Error(`Invalid phase "${phase}": expected one of ${valid}`);
     }
-    await updatePhase(name, phase, projectRoot);
+    await updatePhase(name, resolved, projectRoot);
 }
 /**
  * Registers the `change phase` subcommand with Commander.
  *
  * Usage:
  *   specflow change phase <name>            # print current phase
- *   specflow change phase <name> --set propose # update phase
+ *   specflow change phase <name> --set refined # update phase
  */
 export function registerChangePhaseCommand(changeCmd) {
     changeCmd

package/dist/core/archive.d.ts

@@ -13,7 +13,7 @@ export interface ArchiveResult {
 }
 export interface ArchiveOptions {
     /**
-     * If true, archive even when the change is not in phase=built.
+     * If true, archive even when the change is not in phase=apply.
      * A warning is emitted to stderr when force is applied.
      */
     readonly force?: boolean;
@@ -22,7 +22,7 @@ export interface ArchiveOptions {
  * Archive a completed change.
  *
  * Steps:
- * 0. Validate phase gate: require phase=built unless options.force is true
+ * 0. Validate phase gate: require phase=apply unless options.force is true
  * 1. Find all delta spec files in `specflow/changes/<name>/specs/`
  * 2. Validate each delta spec
  * 3. For each delta spec, find the corresponding main spec in `specflow/specs/`

package/dist/core/archive.js

@@ -54,7 +54,7 @@ function todayDatePrefix() {
  * Archive a completed change.
  *
  * Steps:
- * 0. Validate phase gate: require phase=built unless options.force is true
+ * 0. Validate phase gate: require phase=apply unless options.force is true
  * 1. Find all delta spec files in `specflow/changes/<name>/specs/`
  * 2. Validate each delta spec
  * 3. For each delta spec, find the corresponding main spec in `specflow/specs/`
@@ -72,19 +72,19 @@ 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=built unless --force
+    // 0. Phase gate: require phase=apply unless --force
     const metadata = await readChangeMetadata(changeDir);
     const currentPhase = metadata?.phase;
-    if (currentPhase !== 'built' && !options.force) {
+    if (currentPhase !== 'apply' && !options.force) {
         const phaseLabel = currentPhase ?? 'unknown';
         return {
             success: false,
             errors: [
-                `Cannot archive: change '${changeName}' is in phase '${phaseLabel}', expected 'built'. Complete '/specflow:apply' first, or pass '--force' to archive anyway.`,
+                `Cannot archive: change '${changeName}' is in phase '${phaseLabel}', expected 'apply'. Complete '/specflow:apply' first, or pass '--force' to archive anyway.`,
             ],
         };
     }
-    if (options.force && currentPhase !== 'built') {
+    if (options.force && currentPhase !== 'apply') {
         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

@@ -86,12 +86,12 @@ export declare const SchemaYamlSchema: z.ZodObject<{
         requires: string[];
         instruction?: string | undefined;
     }[];
-    description?: string | undefined;
     apply?: {
         requires: string[];
         instruction?: string | undefined;
         tracks?: string | null | undefined;
     } | undefined;
+    description?: string | undefined;
 }, {
     name: string;
     version: number;
@@ -102,12 +102,12 @@ export declare const SchemaYamlSchema: z.ZodObject<{
         instruction?: string | undefined;
         requires?: string[] | undefined;
     }[];
-    description?: string | undefined;
     apply?: {
         requires: string[];
         instruction?: string | undefined;
         tracks?: string | null | undefined;
     } | undefined;
+    description?: string | undefined;
 }>;
 /** A single artifact definition. */
 export type Artifact = z.infer<typeof ArtifactSchema>;

package/dist/integrations/claude/adapter.js

@@ -4,6 +4,7 @@ import { COMMAND_CATALOG } from '../shared/command-catalog.js';
 import { directoryExists, hashDirectoryTree } from '../shared/asset-hash.js';
 import { deriveCapabilityIds } from '../shared/capability-evidence.js';
 import { copyRuntimeAssets } from '../shared/runtime-assets.js';
+import { removeRetiredManagedAssets } from '../shared/retired-commands.js';
 import { renderIdeContent } from '../shared/skill-renderer.js';
 function extractSkillDescription(content, fallback) {
     const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
@@ -56,6 +57,7 @@ async function generateClaude(ctx) {
         await fs.writeFile(join(commandsDestDir, `${command.id}.md`), generateCommandAlias(command.id, description), 'utf-8');
     }
     const runtimePaths = await copyRuntimeAssets(packageRoot, projectRoot, 'claude');
+    await removeRetiredManagedAssets(projectRoot, 'claude');
     return {
         ide: 'claude',
         generatedPaths: ['.claude/skills', '.claude/commands/specflow', ...runtimePaths],

package/dist/integrations/codex/adapter.js

@@ -5,7 +5,9 @@ import { directoryExists, hashDirectoryTree, hashFile } from '../shared/asset-ha
 import { deriveCapabilityIds } from '../shared/capability-evidence.js';
 import { managedBlockPresent, upsertManagedBlock } from '../shared/marker-write.js';
 import { copyRuntimeAssets } from '../shared/runtime-assets.js';
+import { removeRetiredManagedAssets } from '../shared/retired-commands.js';
 import { renderIdeContent, validateSkillFrontmatter } from '../shared/skill-renderer.js';
+import { renderPhaseGateBullet } from '../shared/phase-context.js';
 const CODEX_AGENTS_MARKER_START = '# Added by specflow init (Codex context)';
 const CODEX_AGENTS_MARKER_END = '# End specflow init (Codex context)';
 function extractSkillDescription(content, fallback) {
@@ -33,7 +35,7 @@ function renderCodexAgentsBlock() {
     return [
         '# SpecFlow Codex Context',
         '',
-        '- Respect specflow phase gates: plan -> refined -> built -> archived',
+        renderPhaseGateBullet(),
         '- Never bypass CLI validation and archive checks',
         '- Use artifacts under specflow/changes/<change>/ before coding',
         '- Workflow skills: $specflow-explore, $specflow-propose, $specflow-refine, $specflow-apply, $specflow-review, $specflow-test, $specflow-verify, $specflow-archive, $specflow-fix, $specflow-snap',
@@ -82,6 +84,7 @@ async function generateCodex(ctx) {
     }
     const runtimePaths = await copyRuntimeAssets(packageRoot, projectRoot, 'codex');
     await upsertManagedBlock(join(projectRoot, 'AGENTS.md'), CODEX_AGENTS_MARKER_START, CODEX_AGENTS_MARKER_END, renderCodexAgentsBlock().split('\n'));
+    await removeRetiredManagedAssets(projectRoot, 'codex');
     return {
         ide: 'codex',
         generatedPaths: ['.agents/skills', 'AGENTS.md', ...runtimePaths],

package/dist/integrations/cursor/adapter.js

@@ -4,7 +4,9 @@ import { COMMAND_CATALOG } from '../shared/command-catalog.js';
 import { directoryExists, fileExists, hashDirectoryTree, hashFile } from '../shared/asset-hash.js';
 import { deriveCapabilityIds } from '../shared/capability-evidence.js';
 import { copyRuntimeAssets } from '../shared/runtime-assets.js';
+import { removeRetiredManagedAssets } from '../shared/retired-commands.js';
 import { renderIdeContent } from '../shared/skill-renderer.js';
+import { renderPhaseGateBullet } from '../shared/phase-context.js';
 function extractSkillDescription(content, fallback) {
     const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
     if (!frontmatterMatch) {
@@ -26,7 +28,7 @@ function renderCursorRule() {
     return [
         '# SpecFlow Cursor Context',
         '',
-        '- Respect specflow phase gates: propose -> refined -> built -> archived',
+        renderPhaseGateBullet(),
         '- Never bypass CLI validation and archive checks',
         '- Use artifacts under specflow/changes/<change>/ before coding',
         '',
@@ -69,6 +71,7 @@ async function generateCursor(ctx) {
     }
     await fs.writeFile(join(rulesDir, 'specflow-context.mdc'), renderCursorRule(), 'utf-8');
     const runtimePaths = await copyRuntimeAssets(packageRoot, projectRoot, 'cursor');
+    await removeRetiredManagedAssets(projectRoot, 'cursor');
     return {
         ide: 'cursor',
         generatedPaths: [

package/dist/integrations/shared/capability-evidence.js

@@ -1,6 +1,5 @@
 import { COMMAND_IDS } from './command-catalog.js';
 const MARKER_RULES = [
-    { id: 'sub.scan.planned_v03_notice', skill: 'scan', includes: ['[PLANNED v0.3]', 'NOT YET FUNCTIONAL'] },
     { id: 'sub.explore.conversation_first', skill: 'explore', includes: ['think-before-propose', 'Do NOT write proposal'] },
     { id: 'sub.explore.handoff_propose', skill: 'explore', includes: ['explore.md', 'handoff'] },
     { id: 'sub.explore.mid_change_reexplore', skill: 'explore', includes: ['Re-explore Mid-Change', 'stuck during'] },
@@ -17,7 +16,6 @@ const MARKER_RULES = [
     { id: 'sub.archive.archive_merge', skill: 'archive', includes: ['specflow change archive', 'delta specs into main specs'] },
     { id: 'sub.fix.urgent_mode', skill: 'fix', includes: ['--urgent', 'skip'] },
     { id: 'sub.snap.posthoc', skill: 'snap', includes: ['post-hoc', 'archive'] },
-    { id: 'failure.scan.not_implemented_guard', skill: 'scan', includes: ['do NOT attempt to run `specflow scan`'] },
     { id: 'failure.explore.proposal_exists_redirect', skill: 'explore', includes: ['explore is too late', 'refine'] },
     { id: 'failure.propose.explore_draft_gate', skill: 'propose', includes: ['Status: draft', 'REFUSE to proceed'] },
     { id: 'failure.apply.phase_gate', skill: 'apply', includes: ['HARD GATE (prerequisite)', 'phase is not `refined`, REFUSE'] },

package/dist/integrations/shared/command-catalog.js

@@ -1,5 +1,4 @@
 export const COMMAND_CATALOG = [
-    { id: 'scan', description: 'Brownfield project scanner via code-review-graph' },
     { id: 'explore', description: 'Think-before-propose exploration when requirements are fuzzy' },
     { id: 'propose', description: 'Create proposal and spec artifacts for a change' },
     { id: 'refine', description: 'Refine and iterate on spec artifacts' },

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

@@ -6,7 +6,6 @@ export const CAPABILITY_MANIFEST = [
         level: 'command',
         required: true,
     })),
-    { id: 'sub.scan.planned_v03_notice', commandId: 'scan', level: 'sub-capability', required: true },
     { id: 'sub.explore.conversation_first', commandId: 'explore', level: 'sub-capability', required: true },
     { id: 'sub.explore.handoff_propose', commandId: 'explore', level: 'sub-capability', required: true },
     { id: 'sub.explore.mid_change_reexplore', commandId: 'explore', level: 'sub-capability', required: true },
@@ -23,7 +22,6 @@ export const CAPABILITY_MANIFEST = [
     { id: 'sub.archive.archive_merge', commandId: 'archive', level: 'sub-capability', required: true },
     { id: 'sub.fix.urgent_mode', commandId: 'fix', level: 'sub-capability', required: true },
     { id: 'sub.snap.posthoc', commandId: 'snap', level: 'sub-capability', required: true },
-    { id: 'failure.scan.not_implemented_guard', commandId: 'scan', level: 'failure-path', required: true },
     { id: 'failure.explore.proposal_exists_redirect', commandId: 'explore', level: 'failure-path', required: true },
     { id: 'failure.propose.explore_draft_gate', commandId: 'propose', level: 'failure-path', required: true },
     { id: 'failure.apply.phase_gate', commandId: 'apply', level: 'failure-path', required: true },

package/dist/integrations/shared/phase-context.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Human-readable phase gate chain for IDE context blocks (AGENTS.md, Cursor rules).
+ * Must stay aligned with {@link CHANGE_PHASES}.
+ */
+export declare const PHASE_GATE_CHAIN: string;
+export declare function renderPhaseGateBullet(): string;

package/dist/integrations/shared/phase-context.js

@@ -0,0 +1,9 @@
+import { CHANGE_PHASES } from '../../utils/change-metadata.js';
+/**
+ * Human-readable phase gate chain for IDE context blocks (AGENTS.md, Cursor rules).
+ * Must stay aligned with {@link CHANGE_PHASES}.
+ */
+export const PHASE_GATE_CHAIN = CHANGE_PHASES.join(' -> ');
+export function renderPhaseGateBullet() {
+    return `- Respect specflow phase gates: ${PHASE_GATE_CHAIN}`;
+}

package/dist/integrations/shared/retired-commands.d.ts

@@ -0,0 +1,10 @@
+import type { IdeTarget } from './types.js';
+/**
+ * Command IDs removed from the public catalog (v1.0.1+ rename, v1.0.2 scan removal).
+ * Init/sync must delete these managed assets so upgraded projects do not keep stale skills.
+ */
+export declare const RETIRED_COMMAND_IDS: readonly ["plan", "build", "done", "scan"];
+/**
+ * Removes obsolete specflow command aliases and skills left from pre-v1.0.1 installs.
+ */
+export declare function removeRetiredManagedAssets(projectRoot: string, ide: IdeTarget): Promise<void>;

package/dist/integrations/shared/retired-commands.js

@@ -0,0 +1,42 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Command IDs removed from the public catalog (v1.0.1+ rename, v1.0.2 scan removal).
+ * Init/sync must delete these managed assets so upgraded projects do not keep stale skills.
+ */
+export const RETIRED_COMMAND_IDS = ['plan', 'build', 'done', 'scan'];
+async function removeIfExists(path) {
+    try {
+        await fs.rm(path, { recursive: true, force: true });
+    }
+    catch {
+        // ignore missing paths
+    }
+}
+/**
+ * Removes obsolete specflow command aliases and skills left from pre-v1.0.1 installs.
+ */
+export async function removeRetiredManagedAssets(projectRoot, ide) {
+    if (ide === 'claude') {
+        const commandsDir = join(projectRoot, '.claude', 'commands', 'specflow');
+        const skillsDir = join(projectRoot, '.claude', 'skills');
+        for (const id of RETIRED_COMMAND_IDS) {
+            await removeIfExists(join(commandsDir, `${id}.md`));
+            await removeIfExists(join(skillsDir, `specflow-${id}`));
+        }
+        return;
+    }
+    if (ide === 'cursor') {
+        const commandsDir = join(projectRoot, '.cursor', 'commands', 'specflow');
+        const skillsDir = join(projectRoot, '.cursor', 'skills');
+        for (const id of RETIRED_COMMAND_IDS) {
+            await removeIfExists(join(commandsDir, `${id}.md`));
+            await removeIfExists(join(skillsDir, `specflow-${id}`));
+        }
+        return;
+    }
+    const skillsDir = join(projectRoot, '.agents', 'skills');
+    for (const id of RETIRED_COMMAND_IDS) {
+        await removeIfExists(join(skillsDir, `specflow-${id}`));
+    }
+}

package/dist/utils/change-metadata.d.ts

@@ -1,12 +1,16 @@
 /**
  * All valid lifecycle phases a change can be in.
  *
- * - `plan`: Initial phase, created by `specflow change new`.
+ * Aligned with workflow command names (propose / refine / apply / archive).
+ *
+ * - `propose`: Initial phase, created by `specflow change new`.
  * - `refined`: After `/specflow:refine` iterative deep review completes.
- * - `built`: After `/specflow:apply` Phase B execution finishes.
+ * - `apply`: After `/specflow:apply` Phase B execution finishes.
  * - `archived`: Post-archive state; assigned automatically on successful archive.
  */
-export declare const CHANGE_PHASES: readonly ["plan", "refined", "built", "archived"];
+export declare const CHANGE_PHASES: readonly ["propose", "refined", "apply", "archived"];
+/** Legacy phase values from v1.0.x and earlier. */
+export declare const LEGACY_CHANGE_PHASES: readonly ["plan", "built"];
 /**
  * Union type of valid lifecycle phases.
  */
@@ -20,6 +24,10 @@ export interface ChangeMetadata {
     readonly phase?: ChangePhase;
     readonly [key: string]: unknown;
 }
+/**
+ * Normalizes a phase string for CLI input (accepts legacy aliases).
+ */
+export declare function normalizeChangePhase(phase: string): ChangePhase | null;
 /**
  * Reads change metadata from .specflow.yaml in the change directory.
  *

package/dist/utils/change-metadata.js

@@ -6,12 +6,28 @@ const METADATA_FILENAME = '.specflow.yaml';
 /**
  * All valid lifecycle phases a change can be in.
  *
- * - `plan`: Initial phase, created by `specflow change new`.
+ * Aligned with workflow command names (propose / refine / apply / archive).
+ *
+ * - `propose`: Initial phase, created by `specflow change new`.
  * - `refined`: After `/specflow:refine` iterative deep review completes.
- * - `built`: After `/specflow:apply` Phase B execution finishes.
+ * - `apply`: After `/specflow:apply` Phase B execution finishes.
  * - `archived`: Post-archive state; assigned automatically on successful archive.
  */
-export const CHANGE_PHASES = ['plan', 'refined', 'built', 'archived'];
+export const CHANGE_PHASES = ['propose', 'refined', 'apply', 'archived'];
+/** Legacy phase values from v1.0.x and earlier. */
+export const LEGACY_CHANGE_PHASES = ['plan', 'built'];
+function normalizePhaseValue(value) {
+    if (typeof value !== 'string') {
+        return value;
+    }
+    if (value === 'plan') {
+        return 'propose';
+    }
+    if (value === 'built') {
+        return 'apply';
+    }
+    return value;
+}
 /**
  * Zod schema for validating change metadata.
  *
@@ -22,9 +38,21 @@ const changeMetadataSchema = z
     .object({
     schema: z.string(),
     created: z.string(),
-    phase: z.enum(CHANGE_PHASES).optional(),
+    phase: z.preprocess(normalizePhaseValue, z.enum(CHANGE_PHASES).optional()),
 })
     .passthrough();
+/**
+ * Normalizes a phase string for CLI input (accepts legacy aliases).
+ */
+export function normalizeChangePhase(phase) {
+    const normalized = normalizePhaseValue(phase);
+    if (typeof normalized !== 'string') {
+        return null;
+    }
+    return CHANGE_PHASES.includes(normalized)
+        ? normalized
+        : null;
+}
 /**
  * Formats a Zod error into a user-friendly message.
  *
@@ -34,7 +62,7 @@ const changeMetadataSchema = z
 function formatZodError(error, metaPath) {
     const hasInvalidPhase = error.issues.some((issue) => issue.path[0] === 'phase' && issue.code === 'invalid_enum_value');
     if (hasInvalidPhase) {
-        return new Error('Invalid phase in metadata: expected one of plan|refined|built|archived');
+        return new Error('Invalid phase in metadata: expected one of propose|refined|apply|archived');
     }
     return new Error(`Invalid metadata format in ${metaPath}: ${error.message}`);
 }

package/dist/utils/change-utils.d.ts

@@ -1,5 +1,5 @@
 import type { ChangeMetadata, ChangePhase } from './change-metadata.js';
-export { CHANGE_PHASES } from './change-metadata.js';
+export { CHANGE_PHASES, normalizeChangePhase } from './change-metadata.js';
 export type { ChangePhase } from './change-metadata.js';
 /**
  * Validates that a change name uses only lowercase alphanumeric characters

package/dist/utils/change-utils.js

@@ -1,7 +1,7 @@
 import { promises as fs } from 'node:fs';
 import { join } from 'node:path';
 import { readChangeMetadata, writeChangeMetadata as writeMetaInternal } from './change-metadata.js';
-export { CHANGE_PHASES } from './change-metadata.js';
+export { CHANGE_PHASES, normalizeChangePhase } from './change-metadata.js';
 const CHANGES_REL_PATH = 'specflow/changes';
 const VALID_CHANGE_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [
@@ -60,9 +60,6 @@
     "js-yaml": "^4.1.0",
     "zod": "^3.24.4"
   },
-  "optionalDependencies": {
-    "code-review-graph": "github:tirth8205/code-review-graph"
-  },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.15.3",

package/prompts/apply/phase-a-plan.md

@@ -7,7 +7,7 @@
 ## Purpose Declaration
 
 **This prompt is for REWRITING an existing tasks.md into writing-plans precision.**
-**NOT for generating tasks.md from scratch.** The tasks.md already exists from the `plan` or `refine` phase. Your job is to take a coarse-grained first-iteration propose (or a refine-updated version of it) and transform each checkbox into a 2-5 minute atomic task that a fresh subagent can execute without additional context.
+**NOT for generating tasks.md from scratch.** The tasks.md already exists from the `propose` or `refine` phase. Your job is to take a coarse-grained first-iteration propose (or a refine-updated version of it) and transform each checkbox into a 2-5 minute atomic task that a fresh subagent can execute without additional context.
 
 **Announce at start:** "I'm using specflow:apply Phase A to rewrite the existing propose into writing-plans precision."
 

package/prompts/propose/design-draft.md

@@ -67,7 +67,7 @@ Signals that you've found a real decision:
 - "The naive approach is X, but it breaks when Z"
 - "The proposal implies X but there's a tension with Y"
 
-If during this first iteration you are genuinely uncertain about an option, **mark the decision `(plan-phase analysis, may revise in refine)`**. Honesty about uncertainty is better than false certainty — refine exists precisely to close these gaps. Do NOT use this marker as an escape hatch for every decision; use it only where you actually lack information.
+If during this first iteration you are genuinely uncertain about an option, **mark the decision `(propose-phase analysis, may revise in refine)`**. Honesty about uncertainty is better than false certainty — refine exists precisely to close these gaps. Do NOT use this marker as an escape hatch for every decision; use it only where you actually lack information.
 
 ### 4. Risks / Trade-offs
 
@@ -111,13 +111,13 @@ Save the document to:
 specflow/changes/<change-name>/design.md
 ```
 
-**Do NOT ask the user to confirm this draft at this stage.** The end-of-propose summary (handled by the orchestrating SKILL) will present all four plan-phase artifacts together for one cohesive user review. Write the best first-iteration design you can, save it, and move on to the next plan-phase artifact.
+**Do NOT ask the user to confirm this draft at this stage.** The end-of-propose summary (handled by the orchestrating SKILL) will present all four propose-phase artifacts together for one cohesive user review. Write the best first-iteration design you can, save it, and move on to the next propose-phase artifact.
 
 ## Remember
 
 - First iteration, not placeholder
 - Substance over structure — skip sections with "N/A" rather than fake-filling them
 - Reference example is a depth guide, not a copy target
-- Honest uncertainty > false certainty — use the `(plan-phase analysis, may revise in refine)` marker when genuinely uncertain
+- Honest uncertainty > false certainty — use the `(propose-phase analysis, may revise in refine)` marker when genuinely uncertain
 - No quantity gates — quality is judged by user review
-- No confirmation gate here — the SKILL handles overall plan-phase review
+- No confirmation gate here — the SKILL handles overall propose-phase review

package/prompts/propose/tasks-draft.md

@@ -112,7 +112,7 @@ Save the document to:
 specflow/changes/<change-name>/tasks.md
 ```
 
-**Do NOT ask the user to confirm this draft at this stage.** The orchestrating SKILL will present all plan-phase artifacts together at the end of the propose phase. Refine will challenge and restructure; Apply Phase A will rewrite to precision. Your job is to hand off a substantive first pass.
+**Do NOT ask the user to confirm this draft at this stage.** The orchestrating SKILL will present all propose-phase artifacts together at the end of the propose phase. Refine will challenge and restructure; Apply Phase A will rewrite to precision. Your job is to hand off a substantive first pass.
 
 ## Remember
 

package/prompts/reference/specflow/example-design.md

@@ -216,7 +216,7 @@ my-project/
 
 ### D7: Scan via code-review-graph
 
-**Choice**: `/specflow:scan` uses code-review-graph (npm dependency) to analyze codebase structure, then converts the analysis output into OpenSpec specs format.
+**Choice (deferred):** A future `/specflow:scan` may use code-review-graph to analyze codebase structure and convert output into OpenSpec specs format. Scan is **not shipped** in public releases; brownfield onboarding uses `/specflow:explore` or `/specflow:propose` instead.
 
 **Why**: Code analysis is a hard problem. Rather than building a custom AST parser for every language, leverage an existing tool that generates structured project knowledge. SpecFlow's value-add is converting that knowledge into actionable specs.
 

package/prompts/refine/brainstorm.md

@@ -4,7 +4,7 @@
 
 # Refine-Phase Brainstorming: Attacking Deep Review
 
-> This prompt is for **ATTACKING DEEP REVIEW** of plan-phase artifacts.
+> This prompt is for **ATTACKING DEEP REVIEW** of propose-phase artifacts.
 > NOT from-scratch brainstorming. The 4 artifacts (proposal, specs, design, tasks)
 > already exist and must be challenged, deepened, and possibly updated.
 
@@ -48,7 +48,7 @@ injected; steps 3–5 carry the discussion into artifacts; steps 6–8 close the
 
 ### Step 1 — Examine existing artifacts (inject Challenge Behavior #1)
 
-Re-read all 4 plan-phase artifacts with fresh eyes. This is not a summary exercise — look for
+Re-read all 4 propose-phase artifacts with fresh eyes. This is not a summary exercise — look for
 what the propose *did not* say. Explicitly INJECT **Challenge Behavior #1 (challenge plan's
 assumptions)** here: list assumptions the propose glossed over and explain why each matters. Each
 round MUST produce this list of challenged assumptions, even if shorter than the previous round.

package/schemas/specflow/schema.yaml

@@ -1,13 +1,8 @@
 name: specflow
 version: 3
-description: SpecFlow workflow — scan → explore → propose → refine → apply → review → test → verify → archive
+description: SpecFlow workflow — explore → propose → refine → apply → review → test → verify → archive
 
 artifacts:
-  - id: scan
-    generates: "specflow/specs/**/*.md"
-    description: Brownfield project scan - generates specs baseline
-    requires: []
-
   - id: explore
     generates: "explore.md"
     description: Pre-plan exploration - problem space, options, and recommended direction

package/skills/specflow-apply/SKILL.md

@@ -115,7 +115,7 @@ If the user rejects, return to Stage B2a for the same task.
 ### Stage B3: Phase Transition
 
 Once all tasks are confirmed:
-- Invoke `specflow change phase <name> --set built` to transition the phase.
+- Invoke `specflow change phase <name> --set apply` to transition the phase.
 - Summarize the build results and overall coverage.
 - Inform the user they can now run `/specflow:review` or `/specflow:verify`.
 
@@ -123,7 +123,7 @@ Once all tasks are confirmed:
 
 ## Phase Transition Notes
 
-- **On Phase B success**: phase → `built` (automatic via Stage B3 CLI call).
+- **On Phase B success**: phase → `apply` (automatic via Stage B3 CLI call).
 - **On Phase A gap halt (Outcome 3)**: phase remains `refined`. No transition. User runs `/specflow:refine` to close gaps, then re-runs `/specflow:apply`.
 - **On Phase A reorganization choice C**: phase remains `refined`. No transition. User edits groups manually, then re-runs `/specflow:apply`.
 - **On Phase B interruption or failing tests**: phase remains `refined`. User resumes Phase B later.

package/skills/specflow-archive/SKILL.md

@@ -11,7 +11,7 @@ description: "Archive change + merge specs + git branch cleanup"
 
 - An active change must exist with completed implementation.
 - `specflow` CLI must be available on PATH.
-- **Phase must be `built`** in `.specflow.yaml`. This is set automatically when `/specflow:apply` Phase B completes. `specflow change archive` refuses to archive changes whose phase is not `built` 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.
+- **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.
 
 ## Stage 1: Test Gate
 

package/skills/specflow-explore/SKILL.md

@@ -41,7 +41,7 @@ If no active change directory exists for this work:
 specflow change new <name>
 ```
 
-The CLI sets `phase=plan` in `.specflow.yaml`. Explore does not change phase — `explore.md` with `Status: confirmed` signals that exploration completed.
+The CLI sets `phase=propose` in `.specflow.yaml`. Explore does not change phase — `explore.md` with `Status: confirmed` signals that exploration completed.
 
 If `explore.md` already exists and is confirmed, suggest `/specflow:propose` instead of re-exploring unless the user wants to revise.
 

package/skills/specflow-fix/SKILL.md

@@ -61,9 +61,9 @@ If the fix addresses a genuinely new scenario that existing specs did not cover,
 
 ### Stage 7a: Mark Phase Built
 
-Before archive, invoke `specflow change phase fix-<desc> --set built` to mark the fix as built.
+Before archive, invoke `specflow change phase fix-<desc> --set apply` to mark the fix as apply-complete.
 
-Rationale: a fix change is created with `phase=plan` (same as any other change) but the fix flow covers the equivalent of the propose → refine → apply pipeline end-to-end inside Stages 3–6 (debug → TDD → review → verify). Archive rejects non-`built` phases unless `--force` is passed, so setting the phase explicitly here keeps the guard meaningful without needing `--force`.
+Rationale: a fix change is created with `phase=propose` (same as any other change) but the fix flow covers the equivalent of the propose → refine → apply pipeline end-to-end inside Stages 3–6 (debug → TDD → review → verify). Archive rejects non-`apply` phases unless `--force` is passed, so setting the phase explicitly here keeps the guard meaningful without needing `--force`.
 
 ### Stage 7b: Run Archive
 

package/skills/specflow-propose/SKILL.md

@@ -49,7 +49,7 @@ ls specflow/changes/<name>/explore.md 2>/dev/null
 
 Run `specflow change new <name>` to initialize a new change directory.
 
-The CLI automatically sets `phase=plan` in `.specflow.yaml` on creation (no separate phase call needed here).
+The CLI automatically sets `phase=propose` in `.specflow.yaml` on creation (no separate phase call needed here).
 
 ## Stage 2: Generate Proposal