synarcx 0.2.1 → 0.3.0

package/README.md

@@ -28,7 +28,7 @@ SynArcX makes your engineering decisions durable. The `constitution.md` is alway
 
 ## Why Not Just Use Another Spec Format?
 
-Spec formats describe *what* to build. 
+Spec formats describe *what* to build.
 
 SynArcX structures *how you get there*  from exploration to proposal to implementation, and helps keep AI-generated changes aligned with the evolving codebase at every stage, not just at planning time.
 
@@ -90,10 +90,9 @@ Then in your AI coding tool:
 1. `/syn:sync` — scan the project and generate the `constitution.md` (persistent project memory)
 2. `/syn:explore "your idea"` — think through the problem with your AI
 3. `/syn:propose "my-feature"` — create proposal, specs, design, and tasks in one step
-4. `/syn:clarify` — sharpen artifacts with targeted questions
-5. `/syn:analyze` — cross-artifact consistency check
-6. `/syn:apply` — implement the tasks
-7. `/syn:archive` — archive when done
+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
 
 For specific cases, use these instead of `/syn:explore`:
 
@@ -118,7 +117,7 @@ Session 1  ──►  Session 2  ──►  Session 3  ──►  Session N
 ```
 Session 1  ──►  constitution.md  ──►  Session 2  ──►  constitution.md  ──►  Session N
 ✓ correct          (updated)          ✓ correct         (updated)          ✓ correct
-      
+  
  		specs · architecture · intent preserved across every reset
 ```
 
@@ -127,14 +126,15 @@ Session 1  ──►  constitution.md  ──►  Session 2  ──►  constitu
 **The workflow:**
 
 ```
-sync ──────────────────────────────────────────────────► constitution
+sync ─────────────────────────────────────► constitution
 
 explore  ──┐
 debug    ──┤
-           ├──► propose ──► clarify ──► analyze ──► apply ──► archive
+           ├──► propose ──► clarify ──► apply ──► review
+           │             └── (auto-analyze) ──┘
 refactor ──┘
 
-quick ────────────────────────────────────────────────────────► apply
+quick ───────────────────────────────────────────► apply
 ```
 
 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.
@@ -191,25 +191,25 @@ Used inside your AI coding tool (Claude Code, Cursor, Cline, etc.):
 | `/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`  | Ask up to 5 targeted questions to sharpen artifacts                      |
-| `/syn:analyze`  | Cross-artifact consistency check across all change artifacts             |
+| `/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:archive`  | Archive a completed change and sync specs                                |
+| `/syn:review`   | Verify implementation, run sanity checks, and archive when clean         |
 
 ### CLI Commands
 
 Used in your terminal:
 
-| Command             | Description                                          |
-| ------------------- | ---------------------------------------------------- |
-| `synarcx init`    | Set up SynArcX workflow structure in your repository |
-| `synarcx sync`    | Regenerate `constitution.md`                       |
-| `synarcx explore` | Open explore session                                 |
-| `synarcx propose` | Create a structured change proposal                  |
-| `synarcx clarify` | Refine requirements into explicit specifications     |
-| `synarcx analyze` | Evaluate architecture impact and tradeoffs           |
-| `synarcx apply`   | Execute implementation tasks                         |
-| `synarcx quick`   | Fast-path execution for small changes                |
+| Command             | Description                                             |
+| ------------------- | ------------------------------------------------------- |
+| `synarcx init`    | Set up SynArcX workflow structure in your repository    |
+| `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 quick`   | Fast-path execution for small changes                   |
 
 ---
 
@@ -264,7 +264,7 @@ SynArcX is evolving toward an architecture-aware workflow system for long-runnin
 
 ## Status
 
-**v0.2.x** — core workflow stable (init, sync, propose, clarify, analyze, apply, archive, quick)
+**v0.3.x** — clarify+analyze merged, adaptive Q&A limit, quick command added
 
 Active development roadmap:
 

package/dist/core/shared/skill-generation.js

@@ -3,7 +3,7 @@
  *
  * Shared utilities for generating skill and command files.
  */
-import { getSynExploreSkillTemplate, getSynApplySkillTemplate, getSynArchiveSkillTemplate, getSynProposeSkillTemplate, getSynSyncSkillTemplate, getSynClarifySkillTemplate, getSynAnalyzeSkillTemplate, getSynDebugSkillTemplate, getSynRefactorSkillTemplate, getSynQuickSkillTemplate, getSynExploreCommandTemplate, getSynApplyCommandTemplate, getSynArchiveCommandTemplate, getSynProposeCommandTemplate, getSynSyncCommandTemplate, getSynClarifyCommandTemplate, getSynAnalyzeCommandTemplate, getSynDebugCommandTemplate, getSynRefactorCommandTemplate, getSynQuickCommandTemplate, } from '../templates/skill-templates.js';
+import { getSynExploreSkillTemplate, getSynApplySkillTemplate, getSynProposeSkillTemplate, getSynSyncSkillTemplate, getSynClarifySkillTemplate, getSynAnalyzeSkillTemplate, getSynDebugSkillTemplate, getSynRefactorSkillTemplate, getSynQuickSkillTemplate, getSynReviewSkillTemplate, getSynExploreCommandTemplate, getSynApplyCommandTemplate, getSynProposeCommandTemplate, getSynSyncCommandTemplate, getSynClarifyCommandTemplate, getSynAnalyzeCommandTemplate, getSynDebugCommandTemplate, getSynRefactorCommandTemplate, getSynQuickCommandTemplate, getSynReviewCommandTemplate, } from '../templates/skill-templates.js';
 /**
  * Gets skill templates with their directory names, optionally filtered by workflow IDs.
  *
@@ -13,7 +13,6 @@ export function getSkillTemplates(workflowFilter) {
     const all = [
         { template: getSynExploreSkillTemplate(), dirName: 'syn-explore', workflowId: 'explore' },
         { template: getSynApplySkillTemplate(), dirName: 'syn-apply', workflowId: 'apply' },
-        { template: getSynArchiveSkillTemplate(), dirName: 'syn-archive', workflowId: 'archive' },
         { template: getSynProposeSkillTemplate(), dirName: 'syn-propose', workflowId: 'propose' },
         { template: getSynSyncSkillTemplate(), dirName: 'syn-sync', workflowId: 'sync' },
         { template: getSynClarifySkillTemplate(), dirName: 'syn-clarify', workflowId: 'clarify' },
@@ -21,6 +20,7 @@ export function getSkillTemplates(workflowFilter) {
         { template: getSynDebugSkillTemplate(), dirName: 'syn-debug', workflowId: 'debug' },
         { template: getSynRefactorSkillTemplate(), dirName: 'syn-refactor', workflowId: 'refactor' },
         { template: getSynQuickSkillTemplate(), dirName: 'syn-quick', workflowId: 'quick' },
+        { template: getSynReviewSkillTemplate(), dirName: 'syn-review', workflowId: 'review' },
     ];
     if (!workflowFilter)
         return all;
@@ -36,7 +36,6 @@ export function getCommandTemplates(workflowFilter) {
     const all = [
         { template: getSynExploreCommandTemplate(), id: 'explore' },
         { template: getSynApplyCommandTemplate(), id: 'apply' },
-        { template: getSynArchiveCommandTemplate(), id: 'archive' },
         { template: getSynProposeCommandTemplate(), id: 'propose' },
         { template: getSynSyncCommandTemplate(), id: 'sync' },
         { template: getSynClarifyCommandTemplate(), id: 'clarify' },
@@ -44,6 +43,7 @@ export function getCommandTemplates(workflowFilter) {
         { template: getSynDebugCommandTemplate(), id: 'debug' },
         { template: getSynRefactorCommandTemplate(), id: 'refactor' },
         { template: getSynQuickCommandTemplate(), id: 'quick' },
+        { template: getSynReviewCommandTemplate(), id: 'review' },
     ];
     if (!workflowFilter)
         return all;

package/dist/core/shared/workflow-registry.d.ts

@@ -5,9 +5,6 @@ export declare const WORKFLOWS: readonly [{
 }, {
     readonly id: "apply";
     readonly skillDir: "syn-apply";
-}, {
-    readonly id: "archive";
-    readonly skillDir: "syn-archive";
 }, {
     readonly id: "propose";
     readonly skillDir: "syn-propose";
@@ -29,6 +26,9 @@ export declare const WORKFLOWS: readonly [{
 }, {
     readonly id: "quick";
     readonly skillDir: "syn-quick";
+}, {
+    readonly id: "review";
+    readonly skillDir: "syn-review";
 }];
 export declare const ALL_WORKFLOWS: readonly string[];
 export declare const CORE_WORKFLOWS: readonly string[];

package/dist/core/shared/workflow-registry.js

@@ -2,7 +2,6 @@ export const DEFAULT_SCHEMA = 'synarcx';
 export const WORKFLOWS = [
     { id: 'explore', skillDir: 'syn-explore' },
     { id: 'apply', skillDir: 'syn-apply' },
-    { id: 'archive', skillDir: 'syn-archive' },
     { id: 'propose', skillDir: 'syn-propose' },
     { id: 'sync', skillDir: 'syn-sync' },
     { id: 'clarify', skillDir: 'syn-clarify' },
@@ -10,6 +9,7 @@ export const WORKFLOWS = [
     { id: 'debug', skillDir: 'syn-debug' },
     { id: 'refactor', skillDir: 'syn-refactor' },
     { id: 'quick', skillDir: 'syn-quick' },
+    { id: 'review', skillDir: 'syn-review' },
 ];
 export const ALL_WORKFLOWS = WORKFLOWS.map(w => w.id);
 export const CORE_WORKFLOWS = [...ALL_WORKFLOWS];

package/dist/core/templates/skill-templates.d.ts

@@ -14,4 +14,5 @@ export { getSynAnalyzeSkillTemplate, getSynAnalyzeCommandTemplate } from './work
 export { getSynDebugSkillTemplate, getSynDebugCommandTemplate } from './workflows/debug.js';
 export { getSynRefactorSkillTemplate, getSynRefactorCommandTemplate } from './workflows/refactor.js';
 export { getSynQuickSkillTemplate, getSynQuickCommandTemplate } from './workflows/quick.js';
+export { getSynReviewSkillTemplate, getSynReviewCommandTemplate } from './workflows/review.js';
 //# sourceMappingURL=skill-templates.d.ts.map

package/dist/core/templates/skill-templates.js

@@ -13,4 +13,5 @@ export { getSynAnalyzeSkillTemplate, getSynAnalyzeCommandTemplate } from './work
 export { getSynDebugSkillTemplate, getSynDebugCommandTemplate } from './workflows/debug.js';
 export { getSynRefactorSkillTemplate, getSynRefactorCommandTemplate } from './workflows/refactor.js';
 export { getSynQuickSkillTemplate, getSynQuickCommandTemplate } from './workflows/quick.js';
+export { getSynReviewSkillTemplate, getSynReviewCommandTemplate } from './workflows/review.js';
 //# sourceMappingURL=skill-templates.js.map

package/dist/core/templates/workflows/apply-change.js

@@ -40,7 +40,7 @@ export function getSynApplySkillTemplate() {
 
    **Handle states:**
    - If \`state: "blocked"\` (missing artifacts): show message, suggest using syn:apply
-   - If \`state: "all_done"\`: congratulate, suggest archive
+   - If \`state: "all_done"\`: congratulate, suggest \`/syn:review\`
    - Otherwise: proceed to implementation
 
 4. **Read context files**
@@ -78,7 +78,7 @@ export function getSynApplySkillTemplate() {
    Display:
    - Tasks completed this session
    - Overall progress: "N/M tasks complete"
-   - If all done: suggest archive
+   - If all done: suggest \`/syn:review\`
    - If paused: explain why and wait for guidance
 
 **Output During Implementation**
@@ -109,7 +109,7 @@ Working on task 4/7: <task description>
 - [x] Task 2
 ...
 
-All tasks complete! Ready to archive this change.
+All tasks complete! Run \`/syn:review\` to verify the implementation.
 \`\`\`
 
 **Output On Pause (Issue Encountered)**
@@ -195,7 +195,7 @@ export function getSynApplyCommandTemplate() {
 
    **Handle states:**
    - If \`state: "blocked"\` (missing artifacts): show message, suggest using \`/syn:apply\`
-   - If \`state: "all_done"\`: congratulate, suggest archive
+   - If \`state: "all_done"\`: congratulate, suggest \`/syn:review\`
    - Otherwise: proceed to implementation
 
 4. **Read context files**
@@ -233,7 +233,7 @@ export function getSynApplyCommandTemplate() {
    Display:
    - Tasks completed this session
    - Overall progress: "N/M tasks complete"
-   - If all done: suggest archive
+   - If all done: suggest \`/syn:review\`
    - If paused: explain why and wait for guidance
 
 **Output During Implementation**
@@ -264,7 +264,7 @@ Working on task 4/7: <task description>
 - [x] Task 2
 ...
 
-All tasks complete! You can archive this change with \`/syn:archive\`.
+All tasks complete! Run \`/syn:review\` to verify the implementation.
 \`\`\`
 
 **Output On Pause (Issue Encountered)**

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

@@ -19,7 +19,7 @@ export function getSynClarifySkillTemplate() {
    - \`synspec/changes/<name>/specs/**/*.md\` (if exist)
    - \`synspec/changes/<name>/design.md\`
 
-3. **Generate up to 5 targeted questions**
+3. **Generate targeted questions (5 default, extendable for critical unknowns)**
    Focus on areas that are:
    - Ambiguous or underspecified
    - Missing edge cases
@@ -34,15 +34,25 @@ export function getSynClarifySkillTemplate() {
    - **Implementation**: Dependencies? Migration path?
    - **Testing**: How to verify?
 
+   "Critical" = a hole or contradiction that would produce broken or incorrect code if left unaddressed. Not "nice to know" or stylistic preferences.
+
 4. **Ask questions interactively**
    Use the **AskUserQuestion tool** (open-ended) to present each question.
    Present questions one at a time. Wait for each answer before moving to the next.
-   Maximum 5 questions per session.
+   Default maximum: 5 questions. If one or more critical unknowns remain after 5, present each remaining critical question with context and ask the user to confirm before continuing.
 
 5. **Encode answers back into artifacts**
    - Edit the relevant artifact in place (proposal.md, design.md, or specs)
    - Do NOT create new files
    - Show what was changed and why
+   - Note: tasks.md will be read during the auto-analyze step that follows
+
+6. **Auto-analyze: cross-artifact consistency checks**
+   - Read all artifacts including tasks.md
+   - Run 5 checks: terminology, scope, completeness, conflicts, traceability
+   - Fix up to 5 inconsistencies in place
+   - If a fix would contradict a Q&A answer, skip it (user answer wins)
+   - If zero issues found, report each check as "OK"
 
 ---
 
@@ -51,7 +61,8 @@ export function getSynClarifySkillTemplate() {
 After completing, summarize:
 - What was clarified
 - Which artifacts were updated
-- Next step: Run \`/syn:analyze\` to check consistency across artifacts`,
+- Consistency check results (each of 5 checks: OK or fix applied)
+- Next step: Run \`/syn:apply\` to start implementation`,
         license: 'MIT',
         compatibility: 'Requires synarcx CLI.',
         metadata: { author: 'synarcx', version: '0.1' },
@@ -78,7 +89,7 @@ export function getSynClarifyCommandTemplate() {
    - \`synspec/changes/<name>/specs/**/*.md\` (if exist)
    - \`synspec/changes/<name>/design.md\`
 
-3. **Generate up to 5 targeted questions**
+3. **Generate targeted questions (5 default, extendable for critical unknowns)**
    Focus on areas that are:
    - Ambiguous or underspecified
    - Missing edge cases
@@ -86,14 +97,24 @@ export function getSynClarifyCommandTemplate() {
    - Unstated assumptions
    - Missing acceptance criteria
 
+   "Critical" = a hole or contradiction that would produce broken or incorrect code if left unaddressed. Not "nice to know" or stylistic preferences.
+
 4. **Ask questions interactively**
    Present questions one at a time. Wait for each answer before moving to the next.
-   Maximum 5 questions per session.
+   Default maximum: 5 questions. If one or more critical unknowns remain after 5, present each remaining critical question with context and ask the user to confirm before continuing.
 
 5. **Encode answers back into artifacts**
    - Edit the relevant artifact in place (proposal.md, design.md, or specs)
    - Do NOT create new files
    - Show what was changed and why
+   - Note: tasks.md will be read during the auto-analyze step that follows
+
+6. **Auto-analyze: cross-artifact consistency checks**
+   - Read all artifacts including tasks.md
+   - Run 5 checks: terminology, scope, completeness, conflicts, traceability
+   - Fix up to 5 inconsistencies in place
+   - If a fix would contradict a Q&A answer, skip it (user answer wins)
+   - If zero issues found, report each check as "OK"
 
 ---
 
@@ -102,7 +123,8 @@ export function getSynClarifyCommandTemplate() {
 After completing, summarize:
 - What was clarified
 - Which artifacts were updated
-- Next step: Run \`/syn:analyze\` to check consistency across artifacts`
+- Consistency check results (each of 5 checks: OK or fix applied)
+- Next step: Run \`/syn:apply\` to start implementation`
     });
 }
 //# sourceMappingURL=clarify.js.map

package/dist/core/templates/workflows/review.d.ts

@@ -0,0 +1,4 @@
+import type { SkillTemplate, CommandTemplate } from '../types.js';
+export declare function getSynReviewSkillTemplate(): SkillTemplate;
+export declare function getSynReviewCommandTemplate(): CommandTemplate;
+//# sourceMappingURL=review.d.ts.map

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

@@ -0,0 +1,293 @@
+import { commandFromSkill } from '../types.js';
+export function getSynReviewSkillTemplate() {
+    return {
+        name: 'syn-review',
+        description: 'Quality gate that verifies implementation, runs sanity checks (test/lint/typecheck), and presents a three-way decision: archive, add more work, or start a new change.',
+        instructions: `Review a completed change — verify implementation, run sanity checks, and decide next steps.
+
+---
+
+## Steps
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run \`synarcx list --json\` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Reviewing change: <name>" and how to override (e.g., \`/syn:review <other>\`).
+
+2. **Check status**
+
+   \`\`\`bash
+   synarcx status --change "<name>" --json
+   \`\`\`
+
+   Parse the JSON to get \`schemaName\` and \`artifacts\` status.
+
+   **Verify artifact completion**: If all apply-required artifacts are not done, stop and tell the user to use \`/syn:propose\` or \`/syn:apply\` first.
+
+3. **Gate on task completion**
+
+   Read \`tasks.md\` and count checkboxes. If any tasks remain unchecked:
+   - Show progress: "N/M tasks complete"
+   - Do NOT run any checks
+   - Suggest: "/syn:apply to finish the remaining tasks, then run /syn:review again"
+   - Stop here
+
+4. **Collect change state**
+
+   - \`git diff --stat\` to get files changed, additions, deletions
+   - Read \`tasks.md\` for complete/incomplete counts
+
+5. **Discover and run sanity checks**
+
+   Probe the project for check commands. Discovery order:
+   1. Check \`package.json\` scripts for \`test\`, \`lint\`, \`typecheck\`
+   2. If \`Cargo.toml\` exists, check for \`cargo test\`
+   3. If no check commands found, skip with a note
+
+   For each discovered command, run it and capture:
+   - **Pass**: note the pass count
+   - **Fail**: capture error details, route to \`/syn:apply\`
+   - **Crash/error**: note "command crashed" with error message, do NOT block the fork
+
+   **Important**: For any failed check, capture only summary counts (pass/fail), not full logs — unless user asks for details.
+
+6. **Build the output**
+
+   **Structured summary first** (scanable at a glance):
+
+   \`\`\`
+   Tasks:     N/M  ✓
+   Files:     N changed (+A -D)
+   Tests:     N/N passed  ✓  (or "N failed" or "ERR — command crashed" or "skipped")
+   Lint:      0 errors  ✓   (or "N errors" or "ERR — command crashed" or "skipped")
+   Typecheck: clean  ✓      (or "N errors" or "ERR — command crashed" or "skipped")
+   \`\`\`
+
+   **Then a narrative paragraph** (context):
+
+   "Change <name> completed N of N tasks across N files (+A -D). All N tests pass, lint is clean, type checking passes. No issues detected."
+
+   Or for failures: "Change <name> completed N of N tasks. N tests failed, lint found N errors. Review the findings below."
+
+7. **Present the fork**
+
+   **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."
+
+   **If any checks failed** (dirty):
+
+   Show each finding with context and route to the correct command:
+
+   | Finding | Route |
+   |---|---|
+   | Test failures | /syn:apply — fix implementation |
+   | Lint errors | /syn:apply — fix implementation |
+   | Artifact inconsistency | /syn:analyze — reconcile |
+   | Unclear requirement | /syn:clarify — refine |
+   | Incomplete artifacts | /syn:analyze — complete artifacts |
+
+   List ALL findings in a single output. Let the user decide which to address first.
+
+   **Note**: /syn:quick bypasses review entirely. Quick is the low-risk fast path.
+
+8. **Archive inline** (when user picks option A)
+
+   - 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>/"
+
+---
+
+## Output (Clean)
+
+\`\`\`
+Tasks:     7/7  ✓
+Files:     5 changed (+124 -12)
+Tests:     42/42 passed  ✓
+Lint:      0 errors  ✓
+Typecheck: clean  ✓
+
+Change add-user-auth completed 7 of 7 tasks across 5 files (+124 -12). All 42 tests pass, lint is clean, type checking passes. No issues detected.
+
+This change is clean. What would you like to do?
+[A] Archive now    [B] Add more work    [C] Start a new change
+\`\`\`
+
+## Output (Dirty)
+
+\`\`\`
+Tasks:     7/7  ✓
+Files:     5 changed (+124 -12)
+Tests:     38/42 passed  ⚠  4 failing
+Lint:      3 errors  ⚠
+Typecheck: clean  ✓
+
+Change add-user-auth completed 7 of 7 tasks. 4 tests failing in auth.test.ts, lint found 3 style issues. Type checking passes.
+
+Findings:
+╳ 4 tests failing in auth.test.ts
+  → Try /syn:apply to fix the implementation
+
+╳ 3 lint errors in src/auth.ts
+  → Try /syn:apply to fix the implementation
+\`\`\`
+
+## Output (Tasks Incomplete — Gate)
+
+\`\`\`
+Tasks:     4/7 tasks complete
+
+This change still has 3 tasks remaining.
+→ Use /syn:apply to finish the remaining tasks, then run /syn:review again.
+\`\`\`
+
+## Output (Archived)
+
+\`\`\`
+## Archive Complete
+
+**Change:** <change-name>
+**Archived to:** synspec/changes/archive/YYYY-MM-DD-<name>/
+
+All tasks complete. All checks passed. 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)
+- 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
+- Quick bypasses review — do not suggest review to users who used /syn:quick`,
+        license: 'MIT',
+        compatibility: 'Requires synarcx CLI.',
+        metadata: { author: 'synarcx', version: '1.0' },
+    };
+}
+export function getSynReviewCommandTemplate() {
+    return commandFromSkill(getSynReviewSkillTemplate(), {
+        name: 'syn:review',
+        description: 'Review a completed change — verify implementation, run sanity checks, and decide next steps',
+        tags: ['workflow', 'review'],
+        content: `Review a completed change — verify implementation, run sanity checks, and decide next steps.
+
+---
+
+## Steps
+
+1. **Select the change**
+
+   If a name is provided (e.g., \`/syn:review add-auth\`), use it. Otherwise:
+   - Infer from conversation context
+   - Auto-select if only one active change exists
+   - If ambiguous, run \`synarcx list --json\` and prompt
+
+2. **Check status**
+
+   \`\`\`bash
+   synarcx status --change "<name>" --json
+   \`\`\`
+
+   Verify all apply-required artifacts are done. If not, stop.
+
+3. **Gate on task completion**
+
+   Read \`tasks.md\`. If any tasks remain unchecked:
+   - Show "N/M tasks complete"
+   - Suggest \`/syn:apply\` to finish
+   - Stop
+
+4. **Collect change state**
+   - \`git diff --stat\` for file summary
+   - Read tasks.md for progress
+
+5. **Discover and run sanity checks**
+
+   Probe \`package.json\` scripts for \`test\`, \`lint\`, \`typecheck\`. Fall back to known tools (cargo test, ruff, etc.). Omit if none found.
+
+   For each command: capture pass/fail/crash. Summary only, not full logs.
+
+6. **Build output**
+
+   Structured summary first:
+   \`\`\`
+   Tasks:     N/M  ✓
+   Files:     N changed (+A -D)
+   Tests:     N/N passed  ✓
+   Lint:      0 errors  ✓
+   Typecheck: clean  ✓
+   \`\`\`
+
+   Then narrative paragraph.
+
+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\`
+   - 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)
+
+   - 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
+
+---
+
+## Output (Clean)
+
+\`\`\`
+Tasks:     7/7  ✓
+Files:     5 changed (+124 -12)
+Tests:     42/42 passed  ✓
+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
+\`\`\`
+
+## Output (Dirty)
+
+\`\`\`
+Tasks:     7/7  ✓
+Files:     5 changed (+124 -12)
+Tests:     38/42 passed  ⚠
+Lint:      3 errors  ⚠
+
+Findings:
+╳ 4 tests failing → /syn:apply to fix
+╳ 3 lint errors → /syn:apply to fix
+\`\`\`
+
+## 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
+- Quick bypasses review — do not suggest review after /syn:quick`
+    });
+}
+//# sourceMappingURL=review.js.map

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

@@ -3,7 +3,49 @@ 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: `Generate or update the project constitution — a living document in \`synspec/constitution.md\` that captures validated project context.
+        instructions: `## Step 0: SynArcX Version Check (MUST run first)
+
+Do NOT read any project files yet. Run this version check first.
+
+### 0.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.
+
+Expected cache format:
+\`\`\`json
+{ "lastCheck": "2026-05-13", "latestVersion": "0.4.0" }
+\`\`\`
+
+If missing or malformed, treat as cache miss and continue.
+
+### 0.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\`.
+
+### 0.3 Get installed version
+
+Run \`synarcx --version\`. On failure: silently skip to 0.5.
+
+### 0.4 Compare and prompt
+
+Parse both as semver: split on \`.\`, parse each as integer, compare major→minor→patch. If npm version > installed:
+
+1. Print update banner.
+2. Use AskUserQuestion tool: "Update now?" with \`["Yes", "No"]\`.
+3. **Yes**: Run \`npm install -g synarcx@latest\`. On success: print "✓ SynArcX updated" + "Run \`synarcx update\` to refresh skill files." On failure: print error + manual command.
+4. **No**: Print manual command.
+
+If versions match, proceed silently.
+
+### 0.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]\`.
+
+---
+
+## Main Sync Flow
+
+Generate or update the project constitution — a living document in \`synspec/constitution.md\` that captures validated project context.
 
 **Input**: The user can specify a focus area, or just run the command to proceed through the validation flow.
 
@@ -108,7 +150,42 @@ 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: `Generate or update the project constitution — a living document in \`synspec/constitution.md\` that captures validated project context.
+        content: `## Step 0: SynArcX Version Check (MUST run first)
+
+Do NOT read any project files yet. Run this version check first.
+
+### 0.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
+
+Run \`npm view synarcx version\`. On failure, silently skip to 0.5, write cache with \`latestVersion: null\`.
+
+### 0.3 Get installed version
+
+Run \`synarcx --version\`. On failure, silently skip to 0.5.
+
+### 0.4 Compare and prompt
+
+Parse both as semver: split on \`.\`, parse each as integer, compare major→minor→patch. If npm version > installed:
+
+1. Print update banner.
+2. Use AskUserQuestion tool: "Update now?" with \`["Yes", "No"]\`.
+3. **Yes**: Run \`npm install -g synarcx@latest\`. On success: print success + "Run \`synarcx update\` to refresh skill files." On failure: print error + manual command.
+4. **No**: Print manual command.
+
+If versions match, proceed silently.
+
+### 0.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]\`.
+
+---
+
+## Main Sync Flow
+
+Generate or update the project constitution — a living document in \`synspec/constitution.md\` that captures validated project context.
 
 **Input**: The user can specify a focus area, or just run the command to proceed through the validation flow.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synarcx",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Structured engineering workflows for AI coding assistants — persistent project memory, spec-driven development, and architecture drift prevention across every session.",
   "keywords": [
     "ai-workflow",