synarcx 0.3.2 → 0.3.4

package/README.md

@@ -92,7 +92,7 @@ Then in your AI coding tool:
 3. `/syn:propose "my-feature"` — create proposal, specs, design, and tasks in one step
 4. `/syn:clarify` — sharpen artifacts with targeted questions + auto consistency check
 5. `/syn:apply` — implement the tasks
-6. `/syn:review` — verify implementation, run sanity checks, and archive when clean
+6. `/syn:review` — verify implementation, run sanity checks, then choose: archive (auto spec sync), add more work (scope-gated), or start a new change
 
 For specific cases, use these instead of `/syn:explore`:
 
@@ -126,22 +126,32 @@ Session 1  ──►  constitution.md  ──►  Session 2  ──►  constitu
 **The workflow:**
 
 ```
-sync ─────────────────────────────────────► constitution
-
-explore  ──┐
-debug    ──┤
-           ├──► propose ──► clarify ──► apply ──► review
-           │             └── (auto-analyze) ──┘
-refactor ──┘
-
-quick ───────────────────────────────────────────► apply
+quick ─────────────────────────────────────┐
+                                           │
+explore  ──┐                               │
+debug    ──┤                               ▼
+           ├───► propose ──► clarify ──► apply ──► review
+           │        ▲           ▲                     │
+refactor ──┘        │           │                     │
+                    │           │                     │
+                    │           │     ┌───────────────┼───────────────┐
+                    │           │     ▼               ▼               ▼
+                    │        add more work        new change       archive
+                    │                                 │               │
+                    └─────────────────────────────────┘               ▼
+sync ──────────────────────────────────────────────────────────► constitution
 ```
 
 Each step suggests the next — you decide when to advance. Works in Claude Code, Cursor, Cline, and any AI coding tool that supports slash commands.
 
-- `sync` generates the `constitution.md` — run once, re-run when the project shifts. Also runs a daily version check: if a newer synarcx is available, prompts to auto-update inline.
+- `sync` generates the `constitution.md` — run once, re-run when the project shifts. Also runs a daily version check (prompts to auto-update) and checks for pending spec syncs from recently archived changes.
 - `explore`, `debug`, and `refactor` are entry points that hand off to `propose`
 - `quick` skips the pipeline for small, low-risk changes
+- Run `synarcx update` in your terminal to refresh all skill and command files after installing a new version
+- `review` is a three-way fork:
+  - **Archive now**: auto-syncs delta specs to main spec via `buildUpdatedSpec()`, writes `.pending-sync.json` marker, moves to archive. If spec sync fails, the change is already safely in archive; retry on next sync run.
+  - **Add more work**: scope gate reads proposal capabilities + design goals/non-goals. In-scope → update artifacts, MUST `/syn:clarify` then `/syn:apply` then `/syn:review` again (loop). Out-of-scope → offer archive then route to `/syn:propose`.
+  - **Start a new change**: routes to `/syn:propose`.
 
 Each change gets its own folder under `synspec/changes/` with:
 
@@ -183,35 +193,35 @@ A typical `constitution.md` includes:
 
 Used inside your AI coding tool (Claude Code, Cursor, Cline, etc.):
 
-| Command           | Description                                                              |
-| ----------------- | ------------------------------------------------------------------------ |
-| `/syn:sync`     | Scan project, run guardrail Q&A, generate/update `constitution.md`. Auto-checks for synarcx updates once daily. |
-| `/syn:explore`  | Think through ideas, investigate problems, clarify requirements          |
-| `/syn:debug`    | Diagnose a known error (3-phase analysis), then prompts `/syn:propose` |
-| `/syn:refactor` | Map current vs target structure, then prompts `/syn:propose`           |
-| `/syn:quick`    | Fast-path for small low-risk changes — inline preview, confirm, apply   |
-| `/syn:propose`  | Create a new change with proposal, specs, design, and tasks              |
-| `/syn:clarify`  | Targeted Q&A (adaptive limit) + auto consistency checks in one command   |
-| `/syn:analyze`  | Standalone cross-artifact consistency check (auto-run by clarify)        |
-| `/syn:apply`    | Implement tasks from a change's task list                                |
-| `/syn:review`   | Verify implementation, run sanity checks, and archive when clean         |
+| Command           | Description                                                                                                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/syn:sync`     | Scan project, run guardrail Q&A, generate/update `constitution.md`. Checks pending spec syncs from archived changes first. Auto-checks for synarcx updates once daily. |
+| `/syn:explore`  | Think through ideas, investigate problems, clarify requirements                                                                                                          |
+| `/syn:debug`    | Diagnose a known error (3-phase analysis), then prompts `/syn:propose`                                                                                                 |
+| `/syn:refactor` | Map current vs target structure, then prompts `/syn:propose`                                                                                                           |
+| `/syn:quick`    | Fast-path for small low-risk changes — inline preview, confirm, apply                                                                                                   |
+| `/syn:propose`  | Create a new change with proposal, specs, design, and tasks                                                                                                              |
+| `/syn:clarify`  | Targeted Q&A (adaptive limit) + auto consistency checks in one command                                                                                                   |
+| `/syn:analyze`  | Standalone cross-artifact consistency check (auto-run by clarify)                                                                                                        |
+| `/syn:apply`    | Implement tasks from a change's task list                                                                                                                                |
+| `/syn:review`   | Verify implementation, run sanity checks, and three-way fork: archive (auto spec sync), add more work (scope gate), or start new change                                  |
 
 ### CLI Commands
 
 Used in your terminal:
 
-| Command             | Description                                             |
-| ------------------- | ------------------------------------------------------- |
-| `synarcx init`    | Set up SynArcX workflow structure in your repository    |
-| `synarcx update`  | Refresh skill and command files for all configured tools |
-| `synarcx sync`    | Regenerate `constitution.md`                          |
-| `synarcx explore` | Open explore session                                    |
-| `synarcx propose` | Create a structured change proposal                     |
-| `synarcx clarify` | Targeted Q&A (adaptive limit) + auto consistency checks |
-| `synarcx analyze` | Cross-artifact consistency check (standalone)           |
-| `synarcx apply`   | Execute implementation tasks                            |
+| Command             | Description                                                  |
+| ------------------- | ------------------------------------------------------------ |
+| `synarcx init`    | Set up SynArcX workflow structure in your repository         |
+| `synarcx update`  | Refresh skill and command files for all configured tools     |
+| `synarcx sync`    | Regenerate `constitution.md`                               |
+| `synarcx explore` | Open explore session                                         |
+| `synarcx propose` | Create a structured change proposal                          |
+| `synarcx clarify` | Targeted Q&A (adaptive limit) + auto consistency checks      |
+| `synarcx analyze` | Cross-artifact consistency check (standalone)                |
+| `synarcx apply`   | Execute implementation tasks                                 |
 | `synarcx review`  | Verify implementation, run sanity checks, archive when clean |
-| `synarcx quick`   | Fast-path execution for small changes                   |
+| `synarcx quick`   | Fast-path execution for small changes                        |
 
 ---
 
@@ -266,7 +276,7 @@ SynArcX is evolving toward an architecture-aware workflow system for long-runnin
 
 ## Status
 
-**v0.3.x** — `syn:review` added as the terminal quality gate (verify implementation, run sanity checks, three-way fork: archive, add work, or start fresh); seamless upgrade from v0.2.x (auto-migrates to `core` profile so new commands appear without any manual steps); clarify+analyze merged, adaptive Q&A limit, quick command, debug/refactor guardrail alignment
+**v0.3.x** — `syn:review` three-way fork (archive with auto spec sync, scope-gated add-more-work, or start new change); `syn:sync` extended with pending spec sync backstop for recently archived changes; archive writes `.pending-sync.json` marker consumed by sync; atomic spec writes prevent half-written corruption; retroactive fix for broken main spec format; seamless upgrade from v0.2.x (auto-migrates to `core` profile)
 
 Active development roadmap:
 

package/dist/core/config.js

@@ -4,32 +4,32 @@ export const SYNSPEC_MARKERS = {
     end: '<!-- SYNSPEC:END -->'
 };
 export const AI_TOOLS = [
-    { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer', skillsDir: '.amazonq' },
-    { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agent' },
-    { name: 'Auggie (Augment CLI)', value: 'auggie', available: true, successLabel: 'Auggie', skillsDir: '.augment' },
-    { name: 'Bob Shell', value: 'bob', available: true, successLabel: 'Bob Shell', skillsDir: '.bob' },
+    { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer', skillsDir: '.amazonq', hasCommands: true },
+    { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agent', hasCommands: true },
+    { name: 'Auggie (Augment CLI)', value: 'auggie', available: true, successLabel: 'Auggie', skillsDir: '.augment', hasCommands: true },
+    { name: 'Bob Shell', value: 'bob', available: true, successLabel: 'Bob Shell', skillsDir: '.bob', hasCommands: true },
     { name: 'Claude Code', value: 'claude', available: true, successLabel: 'Claude Code', skillsDir: '.claude', hasCommands: true },
-    { name: 'Cline', value: 'cline', available: true, successLabel: 'Cline', skillsDir: '.cline' },
-    { name: 'Codex', value: 'codex', available: true, successLabel: 'Codex', skillsDir: '.codex' },
-    { name: 'CodeBuddy Code (CLI)', value: 'codebuddy', available: true, successLabel: 'CodeBuddy Code', skillsDir: '.codebuddy' },
-    { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue (VS Code / JetBrains / Cli)', skillsDir: '.continue' },
-    { name: 'CoStrict', value: 'costrict', available: true, successLabel: 'CoStrict', skillsDir: '.cospec' },
-    { name: 'Crush', value: 'crush', available: true, successLabel: 'Crush', skillsDir: '.crush' },
-    { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor', skillsDir: '.cursor' },
-    { name: 'Factory Droid', value: 'factory', available: true, successLabel: 'Factory Droid', skillsDir: '.factory' },
-    { name: 'Gemini CLI', value: 'gemini', available: true, successLabel: 'Gemini CLI', skillsDir: '.gemini' },
-    { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot', skillsDir: '.github', detectionPaths: ['.github/copilot-instructions.md', '.github/instructions', '.github/workflows/copilot-setup-steps.yml', '.github/prompts', '.github/agents', '.github/skills', '.github/.mcp.json'] },
-    { name: 'iFlow', value: 'iflow', available: true, successLabel: 'iFlow', skillsDir: '.iflow' },
-    { name: 'Junie', value: 'junie', available: true, successLabel: 'Junie', skillsDir: '.junie' },
-    { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code', skillsDir: '.kilocode' },
-    { name: 'Kiro', value: 'kiro', available: true, successLabel: 'Kiro', skillsDir: '.kiro' },
+    { name: 'Cline', value: 'cline', available: true, successLabel: 'Cline', skillsDir: '.cline', hasCommands: true },
+    { name: 'Codex', value: 'codex', available: true, successLabel: 'Codex', skillsDir: '.codex', hasCommands: true },
+    { name: 'CodeBuddy Code (CLI)', value: 'codebuddy', available: true, successLabel: 'CodeBuddy Code', skillsDir: '.codebuddy', hasCommands: true },
+    { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue (VS Code / JetBrains / Cli)', skillsDir: '.continue', hasCommands: true },
+    { name: 'CoStrict', value: 'costrict', available: true, successLabel: 'CoStrict', skillsDir: '.cospec', hasCommands: true },
+    { name: 'Crush', value: 'crush', available: true, successLabel: 'Crush', skillsDir: '.crush', hasCommands: true },
+    { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor', skillsDir: '.cursor', hasCommands: true },
+    { name: 'Factory Droid', value: 'factory', available: true, successLabel: 'Factory Droid', skillsDir: '.factory', hasCommands: true },
+    { name: 'Gemini CLI', value: 'gemini', available: true, successLabel: 'Gemini CLI', skillsDir: '.gemini', hasCommands: true },
+    { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot', skillsDir: '.github', detectionPaths: ['.github/copilot-instructions.md', '.github/instructions', '.github/workflows/copilot-setup-steps.yml', '.github/prompts', '.github/agents', '.github/skills', '.github/.mcp.json'], hasCommands: true },
+    { name: 'iFlow', value: 'iflow', available: true, successLabel: 'iFlow', skillsDir: '.iflow', hasCommands: true },
+    { name: 'Junie', value: 'junie', available: true, successLabel: 'Junie', skillsDir: '.junie', hasCommands: true },
+    { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code', skillsDir: '.kilocode', hasCommands: true },
+    { name: 'Kiro', value: 'kiro', available: true, successLabel: 'Kiro', skillsDir: '.kiro', hasCommands: true },
     { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode', skillsDir: '.opencode', hasCommands: true },
-    { name: 'Pi', value: 'pi', available: true, successLabel: 'Pi', skillsDir: '.pi' },
-    { name: 'Qoder', value: 'qoder', available: true, successLabel: 'Qoder', skillsDir: '.qoder' },
-    { name: 'Lingma', value: 'lingma', available: true, successLabel: 'Lingma', skillsDir: '.lingma' },
-    { name: 'Qwen Code', value: 'qwen', available: true, successLabel: 'Qwen Code', skillsDir: '.qwen' },
-    { name: 'RooCode', value: 'roocode', available: true, successLabel: 'RooCode', skillsDir: '.roo' },
-    { name: 'Windsurf', value: 'windsurf', available: true, successLabel: 'Windsurf', skillsDir: '.windsurf' },
+    { name: 'Pi', value: 'pi', available: true, successLabel: 'Pi', skillsDir: '.pi', hasCommands: true },
+    { name: 'Qoder', value: 'qoder', available: true, successLabel: 'Qoder', skillsDir: '.qoder', hasCommands: true },
+    { name: 'Lingma', value: 'lingma', available: true, successLabel: 'Lingma', skillsDir: '.lingma', hasCommands: true },
+    { name: 'Qwen Code', value: 'qwen', available: true, successLabel: 'Qwen Code', skillsDir: '.qwen', hasCommands: true },
+    { name: 'RooCode', value: 'roocode', available: true, successLabel: 'RooCode', skillsDir: '.roo', hasCommands: true },
+    { name: 'Windsurf', value: 'windsurf', available: true, successLabel: 'Windsurf', skillsDir: '.windsurf', hasCommands: true },
     { name: 'AGENTS.md (works with Amp, VS Code, …)', value: 'agents', available: false, successLabel: 'your AGENTS.md-compatible assistant' }
 ];
 //# sourceMappingURL=config.js.map

package/dist/core/init.js

@@ -19,7 +19,7 @@ import { generateCommands, CommandAdapterRegistry, } from './command-generation/
 import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatCleanupSummary, formatDetectionSummary, } from './legacy-cleanup.js';
 import { getToolsWithSkillsDir, getToolStates, getSkillTemplates, getCommandContents, generateSkillContent, } from './shared/index.js';
 import { getGlobalConfig } from './global-config.js';
-import { getProfileWorkflows } from './profiles.js';
+import { getProfileWorkflows, syncNewCoreWorkflowsToCustomProfile } from './profiles.js';
 import { DEFAULT_SCHEMA } from './shared/workflow-registry.js';
 import { removeSkillDirs, removeCommandFiles } from './shared/artifact-cleanup.js';
 import { getAvailableTools } from './available-tools.js';
@@ -60,6 +60,9 @@ export class InitCommand {
         // Migration check: migrate existing projects to profile system (task 7.3)
         if (extendMode) {
             migrateIfNeeded(projectPath, detectedTools);
+            // Ensure custom-profile users receive any new commands added since their last init
+            // (e.g. syn:review added in 0.3.x). Runs after migration so the profile is settled.
+            syncNewCoreWorkflowsToCustomProfile(getGlobalConfig());
         }
         // Show animated welcome screen (interactive mode only)
         const canPrompt = this.canPromptInteractively();
@@ -381,8 +384,8 @@ export class InitCommand {
                     const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
                     removedSkillCount += await removeSkillDirs(skillsDir);
                 }
-                // Generate commands if delivery includes commands
-                if (shouldGenerateCommands) {
+                // Generate commands if delivery includes commands and tool supports them
+                if (shouldGenerateCommands && hasCommands) {
                     const adapter = CommandAdapterRegistry.get(tool.value);
                     if (adapter) {
                         const generatedCommands = generateCommands(commandContents, adapter);

package/dist/core/profiles.d.ts

@@ -4,12 +4,20 @@
  * Defines workflow profiles that control which workflows are installed.
  * Profiles determine WHICH workflows; delivery (in global config) determines HOW.
  */
-import type { Profile } from './global-config.js';
+import type { Profile, GlobalConfig } from './global-config.js';
 /**
  * Resolves which workflows should be active for a given profile configuration.
  *
  * - 'core' profile always returns CORE_WORKFLOWS
  * - 'custom' profile returns the provided customWorkflows, or empty array if not provided
  */
-export declare function getProfileWorkflows(profile: Profile, customWorkflows?: string[]): readonly string[];
+export declare function getProfileWorkflows(profile: Profile, customWorkflows?: readonly string[]): readonly string[];
+/**
+ * Ensures a 'custom' profile always contains all current ALL_WORKFLOWS entries.
+ * Called by both `synarcx init` and `synarcx update` so new commands (e.g. syn:review)
+ * are never silently dropped for users on a stale custom profile, regardless of which
+ * command they run after upgrading.
+ * No-op for 'core' profile (it derives its list from ALL_WORKFLOWS directly).
+ */
+export declare function syncNewCoreWorkflowsToCustomProfile(config: GlobalConfig): void;
 //# sourceMappingURL=profiles.d.ts.map

package/dist/core/profiles.js

@@ -4,7 +4,8 @@
  * Defines workflow profiles that control which workflows are installed.
  * Profiles determine WHICH workflows; delivery (in global config) determines HOW.
  */
-import { CORE_WORKFLOWS } from './shared/workflow-registry.js';
+import { saveGlobalConfig } from './global-config.js';
+import { ALL_WORKFLOWS, CORE_WORKFLOWS } from './shared/workflow-registry.js';
 /**
  * Resolves which workflows should be active for a given profile configuration.
  *
@@ -17,4 +18,22 @@ export function getProfileWorkflows(profile, customWorkflows) {
     }
     return CORE_WORKFLOWS;
 }
+/**
+ * Ensures a 'custom' profile always contains all current ALL_WORKFLOWS entries.
+ * Called by both `synarcx init` and `synarcx update` so new commands (e.g. syn:review)
+ * are never silently dropped for users on a stale custom profile, regardless of which
+ * command they run after upgrading.
+ * No-op for 'core' profile (it derives its list from ALL_WORKFLOWS directly).
+ */
+export function syncNewCoreWorkflowsToCustomProfile(config) {
+    if (config.profile !== 'custom')
+        return;
+    const current = config.workflows ?? [];
+    const currentSet = new Set(current);
+    const missing = ALL_WORKFLOWS.filter(w => !currentSet.has(w));
+    if (missing.length === 0)
+        return;
+    config.workflows = [...current, ...missing];
+    saveGlobalConfig(config);
+}
 //# sourceMappingURL=profiles.js.map

package/dist/core/shared/artifact-cleanup.js

@@ -19,6 +19,18 @@ export async function removeSkillDirs(skillsDir) {
             // Ignore errors
         }
     }
+    // Remove empty parent skills directory
+    try {
+        if (fs.existsSync(skillsDir)) {
+            const remaining = await fs.promises.readdir(skillsDir);
+            if (remaining.length === 0) {
+                await fs.promises.rmdir(skillsDir);
+            }
+        }
+    }
+    catch {
+        // Ignore errors
+    }
     return removed;
 }
 export async function removeUnselectedSkillDirs(skillsDir, desiredWorkflows) {

package/dist/core/specs-apply.js

@@ -270,7 +270,10 @@ export async function writeUpdatedSpec(update, rebuilt, counts) {
     // Create target directory if needed
     const targetDir = path.dirname(update.target);
     await fs.mkdir(targetDir, { recursive: true });
-    await fs.writeFile(update.target, rebuilt);
+    // Atomic write: write to .tmp then rename (prevents half-written files on crash)
+    const tmpPath = update.target + '.tmp';
+    await fs.writeFile(tmpPath, rebuilt);
+    await fs.rename(tmpPath, update.target);
     const specName = path.basename(path.dirname(update.target));
     console.log(`Applying changes to synspec/specs/${specName}/spec.md:`);
     if (counts.added)
@@ -347,10 +350,12 @@ export async function applySpecs(projectRoot, changeName, options = {}) {
     for (const p of prepared) {
         const capability = path.basename(path.dirname(p.update.target));
         if (!options.dryRun) {
-            // Write the updated spec
+            // Write the updated spec (atomic: .tmp + rename)
             const targetDir = path.dirname(p.update.target);
             await fs.mkdir(targetDir, { recursive: true });
-            await fs.writeFile(p.update.target, p.rebuilt);
+            const tmpPath = p.update.target + '.tmp';
+            await fs.writeFile(tmpPath, p.rebuilt);
+            await fs.rename(tmpPath, p.update.target);
             if (!options.silent) {
                 console.log(`Applying changes to synspec/specs/${capability}/spec.md:`);
                 if (p.counts.added)

package/dist/core/templates/workflows/review.js

@@ -77,15 +77,28 @@ export function getSynReviewSkillTemplate() {
 
    **If ALL checks pass** (clean):
 
-   Present three options:
-
-   | Option | Label | What happens | Next |
-   |---|---|---|---|
-   | A | Archive now | AI moves change to archive/ | Done |
-   | B | Add more work | AI appends new tasks, suggests refinement loop | /syn:clarify → /syn:analyze → /syn:apply |
-   | C | Start a new change | AI suggests creating a fresh change | /syn:propose |
-
-   **For option B (add more work)**: Ask the user what else is needed. If the new work fits within the existing change's scope (same capabilities, same specs, related code), append unchecked tasks to \`tasks.md\` and say: "Run /syn:clarify to refine the new requirements, then /syn:analyze, then /syn:apply." If the new work involves different capabilities, different specs, or unrelated code, tell the user: "This is outside this change's scope. Start a new change with /syn:propose instead."
+    Present three options:
+
+    | Option | Label | What happens | Next |
+    |---|---|---|---|
+    | A | Archive now | AI moves change to archive/ with auto spec sync | Done (specs merged to main) |
+    | B | Add more work | AI reads proposal+design for scope boundary, checks scope gate | Scope check → update or route |
+    | C | Start a new change | AI suggests creating a fresh change | /syn:propose |
+
+   **For option B (add more work)**: Use the scope gate protocol:
+
+   1. Read \`proposal.md\` capabilities section and \`design.md\` goals/non-goals to establish scope boundary
+   2. Ask the user what additional work is needed
+   3. **IN SCOPE** (same capabilities, same concern, no non-goal violation):
+      - Update \`proposal.md\` if scope description needs widening
+      - Update spec with ADDED requirements
+      - Update \`design.md\` if new technical decisions
+      - Append unchecked tasks to \`tasks.md\`
+      - MUST run \`/syn:clarify\` then \`/syn:apply\` — no skipping refinement, no escape hatch for trivial changes
+   4. **OUT OF SCOPE** (new capability, different concern, violates non-goal):
+      - Inform user: "This is outside the current change's scope."
+      - Offer: "Archive current change first?" — YES archives with spec sync, NO leaves active
+      - Route: "Start a new change with \`/syn:propose\`"
 
    **If any checks failed** (dirty):
 
@@ -103,13 +116,31 @@ export function getSynReviewSkillTemplate() {
 
    **Note**: /syn:quick bypasses review entirely. Quick is the low-risk fast path.
 
-8. **Archive inline** (when user picks option A)
+ 8. **Archive inline** (when user picks option A, or in Option B out-of-scope with "yes" to archive)
+
+    a. **Check for delta specs**: Look for any \`synspec/changes/<name>/specs/<capability>/spec.md\` files. If any exist, proceed with spec sync. If none exist (infrastructure, doc-only change), skip the marker and just do the directory move.
+
+    b. **Write marker** (only if delta specs exist):
+       - Create \`synspec/.pending-sync.json\` if it doesn't exist
+       - Add entry: \`{ change: "YYYY-MM-DD-<change-name>", archivedAt: "<ISO timestamp>", syncedAt: null }\`
+       - Use the full archive directory name (with date prefix) in the \`change\` field
+
+    c. **Move to archive**:
+       - Create \`synspec/changes/archive/\` if missing
+       - Target: \`YYYY-MM-DD-<change-name>\`
+       - If target already exists: fail with error, suggest renaming
+       - Move: \`mv synspec/changes/<name> synspec/changes/archive/YYYY-MM-DD-<name>\`
 
-   - Create \`synspec/changes/archive/\` if it doesn't exist
-   - Target name: \`YYYY-MM-DD-<change-name>\`
-   - If target already exists: fail with error, suggest renaming existing archive or using a different approach
-   - Move: \`mv synspec/changes/<name> synspec/changes/archive/YYYY-MM-DD-<name>\`
-   - Confirm: "Archived <change-name> to synspec/changes/archive/YYYY-MM-DD-<name>/"
+    d. **Sync specs** (only if delta specs existed):
+       - Call \`findSpecUpdates(archivePath, synspec/specs/)\` to discover delta specs
+       - For each delta: call \`buildUpdatedSpec()\`, write atomically (\`.tmp\` + rename)
+       - Show per-capability progress: "Syncing specs for <capability>: +N added, ~M modified"
+       - Update marker entry with \`syncedAt\` timestamp
+       - On failure: change is already safely archived, show error, marker stays \`null\` for backstop retry
+
+    e. **Confirm**:
+       - "Archived <change-name> to synspec/changes/archive/YYYY-MM-DD-<name>/"
+       - If specs were synced: "Specs synced: <capability>: +N ~M"
 
 ---
 
@@ -156,7 +187,7 @@ This change still has 3 tasks remaining.
 → Use /syn:apply to finish the remaining tasks, then run /syn:review again.
 \`\`\`
 
-## Output (Archived)
+## Output (Archived with Spec Sync)
 
 \`\`\`
 ## Archive Complete
@@ -164,16 +195,32 @@ This change still has 3 tasks remaining.
 **Change:** <change-name>
 **Archived to:** synspec/changes/archive/YYYY-MM-DD-<name>/
 
+Specs synced:
+  review-command: +2 added, ~1 modified
+
 All tasks complete. All checks passed. Change archived.
 \`\`\`
 
+## Output (Archived — No Delta Specs)
+
+\`\`\`
+## Archive Complete
+
+**Change:** <change-name>
+**Archived to:** synspec/changes/archive/YYYY-MM-DD-<name>/
+
+No delta specs to sync. Change archived.
+\`\`\`
+
 ## Guardrails
 - Do NOT run checks if tasks are incomplete — gate at step 3
 - Checks are read-only — do not modify project files during checks
-- Archive move is the only write operation (step 8)
+- Archive happens BEFORE spec sync — if sync fails, change is safely archived
 - Always list ALL findings at once, don't ask "fix one at a time"
 - For failed checks, show only summary counts unless user asks for details
-- If user picks "add more work," evaluate scope before appending tasks
+- If user picks "add more work," use scope gate protocol: read proposal capabilities + design goals/non-goals before acting
+- MUST run clarify after any in-scope expansion — no escape hatch for trivial changes
+- Out-of-scope work: offer to archive first, then route to \`/syn:propose\`
 - Quick bypasses review — do not suggest review to users who used /syn:quick`,
         license: 'MIT',
         compatibility: 'Requires synarcx CLI.',
@@ -236,24 +283,25 @@ export function getSynReviewCommandTemplate() {
 
    Then narrative paragraph.
 
-7. **Present the fork**
+ 7. **Present the fork**
 
    **If all checks pass:**
-   - Archive now → AI moves to archive/
-   - Add more work → AI appends tasks (scope-checked), suggests \`/syn:clarify\` → \`/syn:analyze\` → \`/syn:apply\`
+   - Archive now → write marker, move to archive, sync specs, update marker
+   - Add more work → scope gate: read proposal capabilities + design goals/non-goals. If in scope: update artifacts, MUST run \`/syn:clarify\` then \`/syn:apply\`. If out of scope: offer to archive first (with spec sync), route to \`/syn:propose\`.
    - Start a new change → \`/syn:propose\`
 
    **If issues found:**
    - Show each finding with route: \`/syn:apply\`, \`/syn:clarify\`, \`/syn:analyze\`
    - List all findings at once
 
-8. **Archive inline** (when user picks archive)
+ 8. **Archive inline** (when user picks archive)
 
-   - Create \`synspec/changes/archive/\` if missing
-   - Target: \`YYYY-MM-DD-<change-name>\`
-   - Fail if target exists
-   - Move: \`mv synspec/changes/<name> synspec/changes/archive/YYYY-MM-DD-<name>\`
-   - Confirm
+    a. Check for delta specs. If none, skip marker and just move.
+    b. Write \`synspec/.pending-sync.json\` with \`syncedAt: null\` using full \`YYYY-MM-DD-<name>\` as change field
+    c. Move: \`mv synspec/changes/<name> synspec/changes/archive/YYYY-MM-DD-<name>\`
+    d. Sync specs: \`findSpecUpdates(archivePath)\` → \`buildUpdatedSpec()\` → atomic write (\`.tmp\` + rename) → per-capability output
+    e. Update marker with \`syncedAt\` timestamp
+    f. On failure: archive is already moved, marker stays \`null\`, backstop retries on next sync
 
 ---
 
@@ -267,7 +315,7 @@ Lint:      0 errors  ✓
 Typecheck: clean  ✓
 
 All checks pass. What would you like to do?
-[A] Archive now    [B] Add more work    [C] Start a new change
+[A] Archive now (with spec sync)    [B] Add more work (scope-gated)    [C] Start a new change
 \`\`\`
 
 ## Output (Dirty)
@@ -286,7 +334,10 @@ Findings:
 ## Guardrails
 - Gate on task completion — no checks until all tasks are done
 - Summary only for failed checks (not full logs)
-- Scope-check before appending tasks
+- Scope gate for Option B: read proposal capabilities + design goals/non-goals before acting
+- In-scope expansion MUST run clarify then apply — no escape hatch
+- Out-of-scope work: offer archive first, then route to /syn:propose
+- Archive happens before spec sync — if sync fails, change is safely archived
 - Quick bypasses review — do not suggest review after /syn:quick`
     });
 }

package/dist/core/templates/workflows/sync.js

@@ -3,11 +3,47 @@ export function getSynSyncSkillTemplate() {
     return {
         name: 'syn-sync',
         description: 'Generate or update synspec/constitution.md with README validation, supporting file scan, guardrail Q&A, and structured constitution generation.',
-        instructions: `## Step 0: SynArcX Version Check (MUST run first)
+        instructions: `## Step 0: Pending Spec Sync Check (runs before version check)
 
-Do NOT read any project files yet. Run this version check first.
+Check for pending spec syncs from recently archived changes. This runs before the version check because it's a local filesystem operation and should not be blocked by network issues.
 
-### 0.1 Read the daily cache
+### 0.1 Read \`synspec/.pending-sync.json\`
+
+If the file doesn't exist, skip this step entirely (no pending syncs).
+
+Expected format:
+\`\`\`json
+{ "pending": [{ "change": "YYYY-MM-DD-<name>", "archivedAt": "<ISO>", "syncedAt": null }] }
+\`\`\`
+
+### 0.2 Process pending entries (FIFO order)
+
+For each entry where \`syncedAt\` is \`null\`:
+- Construct path: \`synspec/changes/archive/<change>/\`
+- Call \`findSpecUpdates(archivePath, synspec/specs/)\` to discover delta specs in the archived change
+- For each delta spec, call \`buildUpdatedSpec()\` to merge into main specs
+- Write rebuilt specs atomically (\`.tmp\` + rename to \`spec.md\`)
+- Show per-change output: "Synced specs from <change>: <capability>: +N ~M"
+- After each change processed, update its \`syncedAt\` field
+- If \`buildUpdatedSpec()\` throws: show error, leave \`syncedAt\` as \`null\` (retry next time)
+
+### 0.3 Clean up marker
+
+After all pending entries are processed:
+- If all entries have \`syncedAt\` set: delete \`synspec/.pending-sync.json\` entirely (clean slate)
+- If some entries failed (\`syncedAt\` still \`null\`): keep the marker, show which changes still need attention, and why
+
+### 0.4 Proceed to version check
+
+Once pending syncs are handled, proceed to Step 1.
+
+---
+
+## Step 1: SynArcX Version Check
+
+Do NOT read any project files yet. Run this version check after pending spec syncs are handled.
+
+### 1.1 Read the daily cache
 
 Read \`synspec/.version-cache.json\`. If \`lastCheck\` matches today's UTC date (YYYY-MM-DD), skip the version check entirely — proceed to "Main Sync Flow" below.
 
@@ -18,15 +54,15 @@ Expected cache format:
 
 If missing or malformed, treat as cache miss and continue.
 
-### 0.2 Fetch latest from npm
+### 1.2 Fetch latest from npm
 
-Run \`npm view synarcx version\`. On failure (no npm, no network, non-zero exit): silently skip to 0.5, write cache with \`latestVersion: null\`.
+Run \`npm view synarcx version\`. On failure (no npm, no network, non-zero exit): silently skip to 1.5, write cache with \`latestVersion: null\`.
 
-### 0.3 Get installed version
+### 1.3 Get installed version
 
-Run \`synarcx --version\`. On failure: silently skip to 0.5.
+Run \`synarcx --version\`. On failure: silently skip to 1.5.
 
-### 0.4 Compare and prompt
+### 1.4 Compare and prompt
 
 Parse both as semver: split on \`.\`, parse each as integer, compare major→minor→patch. If npm version > installed:
 
@@ -37,7 +73,7 @@ Parse both as semver: split on \`.\`, parse each as integer, compare major→min
 
 If versions match, proceed silently.
 
-### 0.5 Write cache
+### 1.5 Write cache
 
 Write \`synspec/.version-cache.json\` with today's UTC date and latest version (or \`null\` on failure). Use \`new Date().toISOString().split('T')[0]\`.
 
@@ -150,23 +186,31 @@ export function getSynSyncCommandTemplate() {
         name: 'syn:sync',
         description: 'Generate/update project constitution with README validation, guardrail Q&A, and constraint capture',
         tags: ['workflow', 'sync', 'project'],
-        content: `## Step 0: SynArcX Version Check (MUST run first)
+        content: `## Step 0: Pending Spec Sync Check (runs before version check)
+
+Check \`synspec/.pending-sync.json\`. If file missing, skip (no pending syncs). Expected format: \`{ "pending": [{ "change": "YYYY-MM-DD-<name>", "archivedAt": "<ISO>", "syncedAt": null }] }\`.
+
+For each entry with \`syncedAt: null\`: construct path \`synspec/changes/archive/<change>/\`, call \`findSpecUpdates()\` + \`buildUpdatedSpec()\`, write atomically (\`.tmp\` + rename), update \`syncedAt\`. On error: leave \`syncedAt: null\` for retry.
+
+After all processed: if all entries have \`syncedAt\`, delete marker file. If some still \`null\`, keep marker with error info. Then proceed.
+
+---
 
-Do NOT read any project files yet. Run this version check first.
+## Step 1: SynArcX Version Check
 
-### 0.1 Read the daily cache
+### 1.1 Read the daily cache
 
 Read \`synspec/.version-cache.json\`. If \`lastCheck\` matches today's UTC date (YYYY-MM-DD), skip to "Main Sync Flow" below. Expected format: \`{ "lastCheck": "2026-05-13", "latestVersion": "0.4.0" }\`.
 
-### 0.2 Fetch latest from npm
+### 1.2 Fetch latest from npm
 
-Run \`npm view synarcx version\`. On failure, silently skip to 0.5, write cache with \`latestVersion: null\`.
+Run \`npm view synarcx version\`. On failure, silently skip to 1.5, write cache with \`latestVersion: null\`.
 
-### 0.3 Get installed version
+### 1.3 Get installed version
 
-Run \`synarcx --version\`. On failure, silently skip to 0.5.
+Run \`synarcx --version\`. On failure, silently skip to 1.5.
 
-### 0.4 Compare and prompt
+### 1.4 Compare and prompt
 
 Parse both as semver: split on \`.\`, parse each as integer, compare major→minor→patch. If npm version > installed:
 
@@ -177,7 +221,7 @@ Parse both as semver: split on \`.\`, parse each as integer, compare major→min
 
 If versions match, proceed silently.
 
-### 0.5 Write cache
+### 1.5 Write cache
 
 Write \`synspec/.version-cache.json\` with today's UTC date and latest version (or \`null\` on failure). Use \`new Date().toISOString().split('T')[0]\`.
 

package/dist/core/update.d.ts

@@ -39,12 +39,11 @@ export declare class UpdateCommand {
      */
     private displayExtraWorkflowsNote;
     /**
-     * Ensures a 'custom' profile always contains all current ALL_WORKFLOWS entries.
      * Runs on every `synarcx update` so any newly introduced workflow (e.g. syn:review)
      * is automatically added to the saved custom workflow list rather than silently dropped.
-     * No-op for 'core' profile (it derives workflows from ALL_WORKFLOWS directly).
+     * Also prints a dim notice listing what was added.
      */
-    private syncNewCoreWorkflowsToCustomProfile;
+    private runSyncNewCoreWorkflowsToCustomProfile;
     /**
      * Suggest opting back into core when a custom profile still matches the old
      * pre-sync core set. Keep custom profiles user-owned; do not mutate them.

package/dist/core/update.js

@@ -15,8 +15,8 @@ import { generateCommands, CommandAdapterRegistry, } from './command-generation/
 import { getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, } from './shared/index.js';
 import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatCleanupSummary, formatDetectionSummary, getToolsFromLegacyArtifacts, } from './legacy-cleanup.js';
 import { isInteractive } from '../utils/interactive.js';
-import { getGlobalConfig, saveGlobalConfig } from './global-config.js';
-import { getProfileWorkflows } from './profiles.js';
+import { getGlobalConfig } from './global-config.js';
+import { getProfileWorkflows, syncNewCoreWorkflowsToCustomProfile } from './profiles.js';
 import { ALL_WORKFLOWS } from './shared/workflow-registry.js';
 import { removeSkillDirs, removeUnselectedSkillDirs, removeCommandFiles, removeUnselectedCommandFiles, } from './shared/artifact-cleanup.js';
 import { getAvailableTools } from './available-tools.js';
@@ -60,7 +60,7 @@ export class UpdateCommand {
         // 3b. For custom profiles, auto-merge any new ALL_WORKFLOWS entries that aren't
         // listed yet (e.g. 'syn:review' added in a new release). This prevents future
         // versions from silently dropping new commands for existing custom-profile users.
-        this.syncNewCoreWorkflowsToCustomProfile(globalConfig);
+        this.runSyncNewCoreWorkflowsToCustomProfile(globalConfig);
         // Re-read after potential mutation so desiredWorkflows is always current.
         const effectiveConfig = getGlobalConfig();
         const profileWorkflows = getProfileWorkflows(profile, effectiveConfig.workflows);
@@ -144,12 +144,12 @@ export class UpdateCommand {
                     }
                     removedDeselectedSkillCount += await removeUnselectedSkillDirs(skillsDir, desiredWorkflows);
                 }
-                // Delete skill directories if delivery is commands-only
-                if (!shouldGenerateSkills) {
+                // Delete skill directories if delivery is commands-only or tool uses commands
+                if (!shouldGenerateSkills || tool.hasCommands) {
                     removedSkillCount += await removeSkillDirs(skillsDir);
                 }
-                // Generate commands if delivery includes commands
-                if (shouldGenerateCommands) {
+                // Generate commands if delivery includes commands and tool supports them
+                if (shouldGenerateCommands && tool.hasCommands) {
                     const adapter = CommandAdapterRegistry.get(tool.value);
                     if (adapter) {
                         const generatedCommands = generateCommands(commandContents, adapter);
@@ -273,24 +273,21 @@ export class UpdateCommand {
         }
     }
     /**
-     * Ensures a 'custom' profile always contains all current ALL_WORKFLOWS entries.
      * Runs on every `synarcx update` so any newly introduced workflow (e.g. syn:review)
      * is automatically added to the saved custom workflow list rather than silently dropped.
-     * No-op for 'core' profile (it derives workflows from ALL_WORKFLOWS directly).
+     * Also prints a dim notice listing what was added.
      */
-    syncNewCoreWorkflowsToCustomProfile(config) {
-        if (config.profile !== 'custom')
-            return;
-        const current = config.workflows ?? [];
-        const currentSet = new Set(current);
-        const missing = ALL_WORKFLOWS.filter(w => !currentSet.has(w));
-        if (missing.length === 0)
-            return;
-        config.workflows = [...current, ...missing];
-        saveGlobalConfig(config);
-        const listed = missing.map(w => `/syn:${w}`).join(', ');
-        console.log(chalk.dim(`Auto-added new workflow(s) to your profile: ${listed}`));
-        console.log();
+    runSyncNewCoreWorkflowsToCustomProfile(config) {
+        const before = config.workflows ? [...config.workflows] : null;
+        syncNewCoreWorkflowsToCustomProfile(config);
+        const after = config.workflows ?? [];
+        const beforeSet = new Set(before ?? []);
+        const added = after.filter(w => !beforeSet.has(w));
+        if (added.length > 0) {
+            const listed = added.map(w => `/syn:${w}`).join(', ');
+            console.log(chalk.dim(`Auto-added new workflow(s) to your profile: ${listed}`));
+            console.log();
+        }
     }
     /**
      * Suggest opting back into core when a custom profile still matches the old

package/package.json

@@ -1,83 +1,87 @@
-{
-  "name": "synarcx",
-  "version": "0.3.2",
-  "description": "Structured engineering workflows for AI coding assistants — persistent project memory, spec-driven development, and architecture drift prevention across every session.",
-  "keywords": [
-    "ai-workflow",
-    "claude-code",
-    "cursor",
-    "spec-driven-development",
-    "ai-coding-assistant",
-    "architecture-drift",
-    "persistent-context",
-    "engineering-workflow",
-    "ai-coding-workflow",
-    "specification",
-    "claude-code-workflow",
-    "ai-context-management"
-  ],
-  "homepage": "https://github.com/funara/synarcx",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/funara/synarcx.git"
-  },
-  "license": "MIT",
-  "author": "Adhi Rahmadian",
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    }
-  },
-  "bin": {
-    "synarcx": "bin/synarcx.js"
-  },
-  "files": [
-    "dist",
-    "bin",
-    "schemas",
-    "scripts/postinstall.js",
-    "!dist/**/*.test.js",
-    "!dist/**/__tests__",
-    "!dist/**/*.map"
-  ],
-  "scripts": {
-    "lint": "eslint src/",
-    "build": "node build.js",
-    "dev": "tsc --watch",
-    "dev:cli": "pnpm build && node bin/synarcx.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "test:coverage": "vitest --coverage",
-    "test:postinstall": "node scripts/postinstall.js",
-    "prepare": "pnpm run build",
-    "postinstall": "node scripts/postinstall.js"
-  },
-  "engines": {
-    "node": ">=20.19.0"
-  },
-  "devDependencies": {
-    "@types/node": "^24.2.0",
-    "@vitest/ui": "^3.2.4",
-    "eslint": "^9.39.2",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.50.1",
-    "vitest": "^3.2.4"
-  },
-  "dependencies": {
-    "@inquirer/core": "^10.2.2",
-    "@inquirer/prompts": "^7.8.0",
-    "chalk": "^5.5.0",
-    "commander": "^14.0.0",
-    "cross-spawn": "7.0.6",
-    "fast-glob": "^3.3.3",
-    "ora": "^8.2.0",
-    "yaml": "^2.8.2",
-    "zod": "^4.0.17"
-  }
-}
+{
+  "name": "synarcx",
+  "version": "0.3.4",
+  "description": "Structured engineering workflows for AI coding assistants — persistent project memory, spec-driven development, and architecture drift prevention across every session.",
+  "keywords": [
+    "ai-workflow",
+    "claude-code",
+    "cursor",
+    "opencode",
+    "codex",
+    "gemini",
+    "spec-driven-development",
+    "ai-coding-assistant",
+    "architecture-drift",
+    "persistent-context",
+    "engineering-workflow",
+    "ai-coding-workflow",
+    "specification",
+    "claude-code-workflow",
+    "ai-context-management"
+  ],
+  "homepage": "https://github.com/funara/synarcx",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/funara/synarcx.git"
+  },
+  "license": "MIT",
+  "author": "Adhi Rahmadian",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "synarcx": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "schemas",
+    "scripts/postinstall.js",
+    "!dist/**/*.test.js",
+    "!dist/**/__tests__",
+    "!dist/**/*.map"
+  ],
+  "scripts": {
+    "lint": "eslint src/",
+    "build": "node build.js",
+    "dev": "tsc --watch",
+    "dev:cli": "pnpm build && node bin/synarcx.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:postinstall": "node scripts/postinstall.js",
+    "prepare": "pnpm run build",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.0",
+    "@vitest/ui": "^3.2.4",
+    "eslint": "^9.39.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.1",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@inquirer/core": "^10.2.2",
+    "@inquirer/prompts": "^7.8.0",
+    "chalk": "^5.5.0",
+    "commander": "^14.0.0",
+    "cross-spawn": "7.0.6",
+    "fast-glob": "^3.3.3",
+    "ora": "^8.2.0",
+    "synarcx": "link:",
+    "yaml": "^2.8.2",
+    "zod": "^4.0.17"
+  }
+}