open-wiki-spec 0.2.3 → 0.3.0

package/dist/cli/init/init-engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"init-engine.js","sourceRoot":"","sources":["../../../src/cli/init/init-engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init-engine.js","sourceRoot":"","sources":["../../../src/cli/init/init-engine.ts"],"names":[],"mappings":"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"}

package/dist/cli/init/meta-files.d.ts

@@ -4,6 +4,7 @@ export declare function createLogFile(wikiPath: string): void;
 export declare function createConventionsFile(wikiPath: string): void;
 /**
  * Append an entry to the vault operation log.
+ * Validates that the log path is inside the vault (rejects symlinks escaping the vault).
  */
-export declare function appendLogEntry(vaultPath: string, operation: string, target: string, agent?: string): void;
+export declare function appendLogEntry(wikiPath: string, operation: string, target: string, agent?: string, vaultRoot?: string): void;
 //# sourceMappingURL=meta-files.d.ts.map

package/dist/cli/init/meta-files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meta-files.d.ts","sourceRoot":"","sources":["../../../src/cli/init/meta-files.ts"],"names":[],"mappings":"AAQA,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAiCvD;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAgCtD;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAepD;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CA8C5D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAc,GACpB,IAAI,CAKN"}
+{"version":3,"file":"meta-files.d.ts","sourceRoot":"","sources":["../../../src/cli/init/meta-files.ts"],"names":[],"mappings":"AA2DA,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAiCvD;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAgCtD;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAepD;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CA8C5D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAc,EACrB,SAAS,CAAC,EAAE,MAAM,GACjB,IAAI,CA2GN"}

package/dist/cli/init/meta-files.js

@@ -4,6 +4,62 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 const SCHEMA_VERSION = '2026-04-06-v1';
+/**
+ * Block the current thread for `ms` milliseconds without spinning the event loop.
+ * Primary path uses `Atomics.wait` on a SharedArrayBuffer. If Atomics.wait is
+ * unavailable (very old Node or restricted sandbox), falls back to a blocking
+ * child_process.execSync sleep which is also O(ms) wall time. Only used as a
+ * last resort because it forks a subprocess.
+ */
+function blockingSleep(ms) {
+    try {
+        const sab = new SharedArrayBuffer(4);
+        Atomics.wait(new Int32Array(sab), 0, 0, ms);
+        return;
+    }
+    catch {
+        // Fall through to child_process fallback
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { execSync } = require('node:child_process');
+        // Use `sleep` on POSIX; on Windows use `timeout` which waits in seconds.
+        // We intentionally cap at one second of resolution loss to avoid fork
+        // overhead dominating the delay.
+        if (process.platform === 'win32') {
+            execSync(`timeout /T 1 /NOBREAK > NUL`, { stdio: 'ignore' });
+        }
+        else {
+            execSync(`sleep ${(ms / 1000).toFixed(3)}`, { stdio: 'ignore' });
+        }
+    }
+    catch {
+        // Last-resort: busy-wait as an absolute worst case. This should never
+        // execute in normal Node environments.
+        const end = Date.now() + ms;
+        while (Date.now() < end) { /* spin */ }
+    }
+}
+/**
+ * Atomic write: write to a temp file in the same directory, then rename.
+ * If the process crashes mid-write, only the temp file is left behind
+ * (and gets cleaned up by the next apply's recoverFromCrash()).
+ */
+function atomicWriteFile(filePath, content) {
+    const tmpPath = `${filePath}.ows-tmp-${process.pid}-${Date.now()}`;
+    try {
+        fs.writeFileSync(tmpPath, content, 'utf-8');
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        // Best-effort cleanup of temp file on write/rename failure
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
 export function createSchemaFile(wikiPath) {
     const content = `---
 type: meta
@@ -36,7 +92,7 @@ effective_date: "${formatDate(new Date())}"
 
 - None.
 `;
-    fs.writeFileSync(path.join(wikiPath, '00-meta', 'schema.md'), content);
+    atomicWriteFile(path.join(wikiPath, '00-meta', 'schema.md'), content);
 }
 export function createIndexFile(wikiPath) {
     const content = `---
@@ -69,7 +125,7 @@ This file is a manual entry point. Use \`ows list\` for the current vault conten
 
 ### Queries
 `;
-    fs.writeFileSync(path.join(wikiPath, '00-meta', 'index.md'), content);
+    atomicWriteFile(path.join(wikiPath, '00-meta', 'index.md'), content);
 }
 export function createLogFile(wikiPath) {
     const date = formatDate(new Date());
@@ -85,7 +141,7 @@ Chronological log of vault operations performed by \`ows\`.
 |------|-----------|--------|-------|
 | ${date} | init | vault | ows |
 `;
-    fs.writeFileSync(path.join(wikiPath, '00-meta', 'log.md'), content);
+    atomicWriteFile(path.join(wikiPath, '00-meta', 'log.md'), content);
 }
 export function createConventionsFile(wikiPath) {
     const content = `---
@@ -132,16 +188,119 @@ type: meta
 - Apply order: RENAMED -> REMOVED -> MODIFIED -> ADDED.
 - MODIFIED/REMOVED/RENAMED entries should include \`[base: <content_hash>]\`.
 `;
-    fs.writeFileSync(path.join(wikiPath, '00-meta', 'conventions.md'), content);
+    atomicWriteFile(path.join(wikiPath, '00-meta', 'conventions.md'), content);
 }
 /**
  * Append an entry to the vault operation log.
+ * Validates that the log path is inside the vault (rejects symlinks escaping the vault).
  */
-export function appendLogEntry(vaultPath, operation, target, agent = 'ows') {
-    const logPath = path.join(vaultPath, '00-meta', 'log.md');
+export function appendLogEntry(wikiPath, operation, target, agent = 'ows', vaultRoot) {
+    const logPath = path.join(wikiPath, '00-meta', 'log.md');
+    // Security: reject if log.md is a symlink pointing outside the vault
+    try {
+        const stat = fs.lstatSync(logPath);
+        if (stat.isSymbolicLink()) {
+            const realPath = fs.realpathSync.native(logPath);
+            const boundary = vaultRoot ?? path.dirname(wikiPath);
+            const realBoundary = fs.realpathSync.native(boundary);
+            if (!realPath.startsWith(realBoundary + path.sep) && realPath !== realBoundary) {
+                throw new Error(`log.md symlink escapes vault boundary: ${logPath}`);
+            }
+        }
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            // Re-throw security errors; only swallow "file doesn't exist yet"
+            if (err instanceof Error && err.message.includes('symlink escapes vault')) {
+                throw err;
+            }
+        }
+    }
+    // Sanitize markdown-table-breaking characters: pipe, newline, carriage return.
+    // This prevents log poisoning via crafted change IDs or targets.
+    const sanitize = (s) => s.replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ');
     const date = formatDate(new Date());
-    const entry = `| ${date} | ${operation} | ${target} | ${agent} |`;
-    fs.appendFileSync(logPath, '\n' + entry);
+    const entry = `| ${sanitize(date)} | ${sanitize(operation)} | ${sanitize(target)} | ${sanitize(agent)} |`;
+    // Serialize parallel appenders via an exclusive-create lock file.
+    // Two simultaneous `ows archive`/`ows apply` runs would otherwise race on
+    // `appendFileSync`. The lock is a per-vault mutex held only for the duration
+    // of this single append (ms). Stale locks are reclaimed by either:
+    //   - time-based TTL (older than 30s → abandoned)
+    //   - PID-based liveness (writer PID no longer exists → abandoned)
+    // The PID check is important because a crashed process leaves a fresh
+    // lock timestamp that the TTL alone would wait on for the full 30s.
+    const lockPath = path.join(wikiPath, '00-meta', 'log.md.lock');
+    const LOCK_STALE_MS = 30_000;
+    const MAX_RETRIES = 50;
+    let acquired = false;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        try {
+            const fd = fs.openSync(lockPath, 'wx');
+            fs.writeSync(fd, `${process.pid}|${Date.now()}`);
+            fs.closeSync(fd);
+            acquired = true;
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST') {
+                // Unexpected error (permissions, missing dir, etc.) — fall
+                // through to best-effort append without locking to avoid
+                // blocking the workflow. This preserves behavior on read-only
+                // or otherwise constrained filesystems.
+                break;
+            }
+            // Try to detect a stale lock (time OR dead-PID based)
+            try {
+                const lockContent = fs.readFileSync(lockPath, 'utf-8');
+                const [pidStr, ts] = lockContent.split('|');
+                const lockAge = Date.now() - Number(ts);
+                const staleByAge = Number.isFinite(lockAge) && lockAge > LOCK_STALE_MS;
+                let staleByPid = false;
+                const pid = Number(pidStr);
+                if (Number.isFinite(pid) && pid > 0 && pid !== process.pid) {
+                    try {
+                        // Signal 0 checks liveness without delivering a signal
+                        process.kill(pid, 0);
+                    }
+                    catch {
+                        staleByPid = true;
+                    }
+                }
+                if (staleByAge || staleByPid) {
+                    fs.unlinkSync(lockPath);
+                    continue;
+                }
+            }
+            catch {
+                // ignore
+            }
+            // Block the thread for ~10ms without spinning the event loop.
+            // Atomics.wait on a SharedArrayBuffer is a true blocking sleep in Node,
+            // unlike `while (Date.now() < x) {}` which burns CPU and starves timers.
+            blockingSleep(10);
+        }
+    }
+    // If acquisition failed after all retries, abort rather than append
+    // without the mutex. Previously we'd silently proceed and risk
+    // corrupting log.md with interleaved writes from parallel processes.
+    // The caller catches this and surfaces a clear error so the user
+    // can inspect the lock file.
+    if (!acquired && fs.existsSync(lockPath)) {
+        throw new Error(`Could not acquire log.md lock at ${lockPath} after ${MAX_RETRIES} retries. ` +
+            'Another process may be holding it. Inspect the lock file (contains pid|timestamp) ' +
+            'and delete it manually if you have confirmed the holder is dead.');
+    }
+    try {
+        fs.appendFileSync(logPath, '\n' + entry);
+    }
+    finally {
+        if (acquired) {
+            try {
+                fs.unlinkSync(lockPath);
+            }
+            catch { /* best-effort */ }
+        }
+    }
 }
 function formatDate(date) {
     const y = date.getFullYear();

package/dist/cli/init/meta-files.js.map

@@ -1 +1 @@
-{"version":3,"file":"meta-files.js","sourceRoot":"","sources":["../../../src/cli/init/meta-files.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,MAAM,cAAc,GAAG,eAAe,CAAC;AAEvC,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,OAAO,GAAG;;mBAEC,cAAc;mBACd,UAAU,CAAC,IAAI,IAAI,EAAE,CAAC;;;;;;;IAOrC,cAAc;;;;;;;;;;;;;;;;;;;;CAoBjB,CAAC;IACA,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,OAAO,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BjB,CAAC;IACA,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,CAAC,EAAE,OAAO,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG;;;;;;;;;;IAUd,IAAI;CACP,CAAC;IACA,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CjB,CAAC;IACA,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,gBAAgB,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAiB,EACjB,SAAiB,EACjB,MAAc,EACd,QAAgB,KAAK;IAErB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC1D,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,KAAK,IAAI,MAAM,SAAS,MAAM,MAAM,MAAM,KAAK,IAAI,CAAC;IAClE,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,GAAG,KAAK,CAAC,CAAC;AAC3C,CAAC;AAED,SAAS,UAAU,CAAC,IAAU;IAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IAC7B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACvD,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAClD,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"meta-files.js","sourceRoot":"","sources":["../../../src/cli/init/meta-files.ts"],"names":[],"mappings":"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"}

package/dist/cli/init/skill-generator.d.ts

@@ -6,6 +6,9 @@ export declare const WORKFLOW_SKILLS: Record<string, SkillDefinition>;
 export declare function generateSkillFile(skillDef: SkillDefinition): string;
 /**
  * Write all skill files to the Claude Code commands directory.
+ * If a user has customized an existing skill file (contents differ from the
+ * previously-generated version), back it up before overwriting so users
+ * never lose their customizations.
  */
 export declare function writeAllSkillFiles(projectPath: string): string[];
 //# sourceMappingURL=skill-generator.d.ts.map

package/dist/cli/init/skill-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-generator.d.ts","sourceRoot":"","sources":["../../../src/cli/init/skill-generator.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CA0wB3D,CAAC;AAEF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAQnE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAahE"}
+{"version":3,"file":"skill-generator.d.ts","sourceRoot":"","sources":["../../../src/cli/init/skill-generator.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CA+6B3D,CAAC;AAEF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAQnE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CA2BhE"}

package/dist/cli/init/skill-generator.js

@@ -207,6 +207,8 @@ Use this context to inform section writing (especially Why and Delta Summary).
 - \`--json\`: Output structured JSON result
 - \`--dry-run\`: Validate without writing any files (use this to preview)
 - \`--force-stale\`: Apply even when stale base fingerprints are detected
+- \`--no-auto-transition\`: Keep status as \`in_progress\` after writing (use when ADDED/MODIFIED markers need manual content before finalizing)
+- \`--no-log\`: Skip appending to \`wiki/00-meta/log.md\`
 
 **Steps**
 
@@ -238,6 +240,15 @@ Use this context to inform section writing (especially Why and Delta Summary).
    ---
 
 4. **Execute the apply (if confirmed)**
+
+   **CRITICAL: If the Change has ADDED or MODIFIED operations, use \`--no-auto-transition\` on the first apply** so the status stays in \`in_progress\` until you've filled in the marker contents. Example:
+   \`\`\`bash
+   # First apply: insert markers without transitioning to applied
+   ows apply <changeId> --no-auto-transition --json
+   \`\`\`
+   Without this flag, the change will transition to \`applied\` while the Feature note still contains unfilled \`<!-- ADDED ... -->\` marker comments, and \`ows verify\` will then report \`UNFILLED_APPLY_MARKER\` errors.
+
+   For changes with ONLY programmatic ops (RENAMED/REMOVED), a single plain apply is fine:
    \`\`\`bash
    ows apply <changeId> --json
    \`\`\`
@@ -252,7 +263,17 @@ Use this context to inform section writing (especially Why and Delta Summary).
    - **MODIFIED**: Inserts a \`<!-- MODIFIED by change: <changeId> -->\` marker after the requirement heading. The agent must then update the requirement text.
    - **ADDED**: Inserts a \`<!-- ADDED by change: <changeId>. Fill in normative statement (SHALL/MUST) and scenarios (WHEN/THEN). -->\` marker in the Requirements section. The agent must then write the new requirement content.
 
-5. **Show final state**
+5. **Fill marker contents (if using --no-auto-transition)**
+
+   Open each Feature note listed in \`result.modifiedFiles\`, find the \`<!-- ADDED ... -->\` and \`<!-- MODIFIED ... -->\` marker comments, and replace them with real requirement text (SHALL/MUST normative + WHEN/THEN scenarios). Then remove the marker comment itself.
+
+6. **Finalize apply**
+   \`\`\`bash
+   # Second apply: now that markers are filled, transition to applied
+   ows apply <changeId> --json
+   \`\`\`
+
+7. **Show final state**
    \`\`\`bash
    ows status <changeId>
    \`\`\`
@@ -703,6 +724,150 @@ In extend mode, existing seed notes are never overwritten. Use \`--skip-seed\` t
 - Never destroy existing vault content
 - Encourage the user to edit seed-context.md after init — it improves retrieval quality
 - Show warnings if any files were skipped`,
+    },
+    explore: {
+        name: 'ows-explore',
+        description: 'Enter exploration mode — investigate the codebase without implementing.',
+        instructions: `Enter thinking/exploration mode. Investigate the codebase, architecture, and existing behavior without making any code changes.
+
+**Input**: The argument after \`/ows-explore\` is a topic, question, or area to investigate (e.g., \`/ows-explore "how does the auth flow work?"\`).
+
+**Purpose**: This is a safe space to investigate before committing to any plan. Unlike \`/ows-propose\`, this does NOT create any vault notes or changes. Use this to build understanding before proposing work.
+
+**Steps**
+
+1. **Understand the investigation scope**
+
+   Parse the user's question and identify:
+   - What system/feature area is involved
+   - What kind of answer is needed (architecture overview, data flow, bug root cause, etc.)
+   - What files/modules are likely relevant
+
+2. **Search the vault for existing knowledge**
+   \`\`\`bash
+   ows query "<topic>" --json
+   \`\`\`
+   Check if the vault already has relevant Feature, System, Decision, or Query notes.
+
+3. **Explore the codebase**
+
+   Read code, trace call paths, examine data flows. Use whatever tools are available:
+   - File reading and search
+   - Symbol navigation
+   - Dependency tracing
+   - Architecture visualization (ASCII diagrams)
+
+4. **Document findings**
+
+   Present findings with:
+   - Architecture diagrams (ASCII) where helpful
+   - Key files and their roles
+   - Data flow descriptions
+   - Relevant existing vault notes
+   - Questions that remain unanswered
+
+5. **Suggest next steps**
+
+   Based on findings:
+   - "This is well-understood. No action needed."
+   - "Consider creating a Decision note to record this rationale."
+   - "This reveals work to do. Run \`/ows-propose\` to formalize it."
+   - "Save these findings as a Query note? Run \`ows query '<topic>' --save\`"
+
+**Rules**
+- **NO code changes** — this is read-only investigation
+- **NO vault modifications** — don't create notes (suggest it, but don't do it)
+- **Be thorough** — read actual code, don't guess from file names
+- **Visualize** — use ASCII diagrams for architecture, data flows, component relationships
+- **Connect to vault** — reference existing vault notes when relevant
+- **Capture for later** — if findings are substantial, suggest saving as a Query note`,
+    },
+    onboard: {
+        name: 'ows-onboard',
+        description: 'Guided tutorial for first-time open-wiki-spec users.',
+        instructions: `Guide a first-time user through a complete open-wiki-spec cycle using their actual codebase.
+
+**Purpose**: Help new users learn ows by doing — not by reading docs. Walk them through a real (small) cycle from propose to archive.
+
+**Steps**
+
+1. **Check vault state**
+   \`\`\`bash
+   ows list --json
+   ows verify --json
+   \`\`\`
+   Determine if the vault is freshly initialized or already has content.
+
+2. **Explain the vault structure**
+
+   Give a quick orientation:
+   \`\`\`
+   wiki/
+     00-meta/       — Vault metadata and conventions
+     01-sources/    — External references (PRDs, docs)
+     02-systems/    — System/component boundaries
+     03-features/   — Feature specifications (the "what is")
+     04-changes/    — Active work units (the "what's changing")
+     05-decisions/  — Design decisions and rationale
+     06-queries/    — Investigation notes
+     99-archive/    — Completed changes
+   \`\`\`
+
+3. **Pick a small real task**
+
+   Help the user identify a small, concrete task from their project:
+   - A simple feature addition
+   - A bug fix
+   - A small refactor
+
+   The task should be completable in ~15 minutes. Ask the user what they'd like to work on.
+
+4. **Walk through the full cycle**
+
+   Guide the user step by step (pausing for confirmation at each stage):
+
+   **a. Propose** (\`/ows-propose\`)
+   - Show how retrieval scans for existing work
+   - Explain the classification result
+   - Create the Feature + Change notes
+
+   **b. Fill sections** (\`/ows-continue\`)
+   - Help write the Why section
+   - Help write the Delta Summary
+   - Help write Tasks
+   - Help write Validation
+   - Show the proposed → planned transition
+
+   **c. Implement** (\`/ows-continue\`)
+   - Work through the tasks
+   - Show how tasks are tracked
+
+   **d. Apply** (\`/ows-apply\`)
+   - Show how the Feature note gets updated
+   - Explain the two-phase commit
+
+   **e. Verify** (\`/ows-verify\`)
+   - Run the 4-dimension check
+   - Explain what each dimension means
+
+   **f. Archive** (\`/ows-archive\`)
+   - Move the completed change
+   - Show the clean state
+
+5. **Wrap up**
+
+   Summarize what they learned:
+   - 6 note types and their purposes
+   - The lifecycle: propose → plan → implement → apply → verify → archive
+   - Key commands they'll use daily
+   - Where to find help (README, \`/ows-status\`, \`/ows-query\`)
+
+**Guardrails**
+- Pause after EACH major step for user confirmation
+- Keep explanations concise — show, don't lecture
+- Use the user's actual project, not hypothetical examples
+- If the user gets confused, simplify — don't add complexity
+- The goal is confidence, not completeness`,
     },
     migrate: {
         name: 'ows-migrate',
@@ -796,6 +961,9 @@ ${skillDef.instructions}
 }
 /**
  * Write all skill files to the Claude Code commands directory.
+ * If a user has customized an existing skill file (contents differ from the
+ * previously-generated version), back it up before overwriting so users
+ * never lose their customizations.
  */
 export function writeAllSkillFiles(projectPath) {
     const claudeDir = path.join(projectPath, '.claude', 'commands');
@@ -803,8 +971,21 @@ export function writeAllSkillFiles(projectPath) {
     const generated = [];
     for (const [workflowName, skillDef] of Object.entries(WORKFLOW_SKILLS)) {
         const skillPath = path.join(claudeDir, `ows-${workflowName}.md`);
-        const content = generateSkillFile(skillDef);
-        fs.writeFileSync(skillPath, content);
+        const newContent = generateSkillFile(skillDef);
+        // If file exists and differs from what we're about to write, back it up
+        if (fs.existsSync(skillPath)) {
+            try {
+                const existingContent = fs.readFileSync(skillPath, 'utf-8');
+                if (existingContent !== newContent) {
+                    const backupPath = `${skillPath}.bak`;
+                    fs.writeFileSync(backupPath, existingContent);
+                }
+            }
+            catch {
+                // Best-effort backup — don't block init if read fails
+            }
+        }
+        fs.writeFileSync(skillPath, newContent);
         generated.push(skillPath);
     }
     return generated;

package/dist/cli/init/skill-generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-generator.js","sourceRoot":"","sources":["../../../src/cli/init/skill-generator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skill-generator.js","sourceRoot":"","sources":["../../../src/cli/init/skill-generator.ts"],"names":[],"mappings":"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"}

package/dist/cli/json-envelope.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Envelope schema version. Bump on breaking changes to the envelope
+ * shape (adding fields is non-breaking; renaming/removing/semantic
+ * changes are breaking). Consumers pin against this to detect drift.
+ */
+export declare const ENVELOPE_VERSION = "1";
+/**
+ * Wrap a command's success payload in the standard CLI JSON envelope
+ * and return the serialized JSON string (pretty-printed).
+ *
+ * Usage:
+ *   console.log(jsonEnvelope('propose', result));
+ */
+export declare function jsonEnvelope(command: string, data: unknown): string;
+//# sourceMappingURL=json-envelope.d.ts.map

package/dist/cli/json-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-envelope.d.ts","sourceRoot":"","sources":["../../src/cli/json-envelope.ts"],"names":[],"mappings":"AAiBA;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAiDpC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CASnE"}

package/dist/cli/json-envelope.js

@@ -0,0 +1,86 @@
+/**
+ * Common JSON envelope for all CLI --json output.
+ *
+ * Every CLI command wraps its success payload in:
+ *   { ok: true, command: "<name>", version: "<pkg version>", data: <payload> }
+ *
+ * Error output is handled separately by handleCliError and keeps its
+ * existing { error: true, code, message } shape.
+ *
+ * Uses a JSON.stringify replacer (single-pass) to normalize Map instances
+ * to plain objects. This preserves native Date → toISOString() behavior
+ * and avoids the 2-pass cost of deep-cloning + stringify.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+/**
+ * Envelope schema version. Bump on breaking changes to the envelope
+ * shape (adding fields is non-breaking; renaming/removing/semantic
+ * changes are breaking). Consumers pin against this to detect drift.
+ */
+export const ENVELOPE_VERSION = '1';
+let _version;
+function getVersion() {
+    if (_version)
+        return _version;
+    try {
+        // ESM-safe: derive directory from import.meta.url
+        const thisDir = dirname(fileURLToPath(import.meta.url));
+        // Walk up from dist/cli/ (or src/cli/) to find package.json
+        let dir = thisDir;
+        for (let i = 0; i < 5; i++) {
+            const pkgPath = join(dir, 'package.json');
+            if (existsSync(pkgPath)) {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+                _version = pkg.version ?? 'unknown';
+                return _version;
+            }
+            dir = dirname(dir);
+        }
+    }
+    catch {
+        // fall through
+    }
+    _version = 'unknown';
+    return _version;
+}
+/**
+ * JSON.stringify replacer that converts Map → plain object and
+ * Set → array. Handles nested structures via the natural recursion
+ * of JSON.stringify — no manual deep-walk needed.
+ *
+ * Date, RegExp, and other built-ins are left to their default
+ * JSON.stringify behavior (Date → toISOString string, others → {}).
+ */
+function envelopeReplacer(_key, value) {
+    if (value instanceof Map) {
+        const obj = {};
+        for (const [k, v] of value) {
+            obj[String(k)] = v;
+        }
+        return obj;
+    }
+    if (value instanceof Set) {
+        return Array.from(value);
+    }
+    return value;
+}
+/**
+ * Wrap a command's success payload in the standard CLI JSON envelope
+ * and return the serialized JSON string (pretty-printed).
+ *
+ * Usage:
+ *   console.log(jsonEnvelope('propose', result));
+ */
+export function jsonEnvelope(command, data) {
+    const envelope = {
+        ok: true,
+        command,
+        envelope_version: ENVELOPE_VERSION,
+        version: getVersion(),
+        data,
+    };
+    return JSON.stringify(envelope, envelopeReplacer, 2);
+}
+//# sourceMappingURL=json-envelope.js.map

package/dist/cli/json-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-envelope.js","sourceRoot":"","sources":["../../src/cli/json-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC,IAAI,QAA4B,CAAC;AAEjC,SAAS,UAAU;IACjB,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,IAAI,CAAC;QACH,kDAAkD;QAClD,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACxD,4DAA4D;QAC5D,IAAI,GAAG,GAAG,OAAO,CAAC;QAClB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;YAC1C,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAyB,CAAC;gBAC/E,QAAQ,GAAG,GAAG,CAAC,OAAO,IAAI,SAAS,CAAC;gBACpC,OAAO,QAAQ,CAAC;YAClB,CAAC;YACD,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;IACD,QAAQ,GAAG,SAAS,CAAC;IACrB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,gBAAgB,CAAC,IAAY,EAAE,KAAc;IACpD,IAAI,KAAK,YAAY,GAAG,EAAE,CAAC;QACzB,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC;YAC3B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,KAAK,YAAY,GAAG,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,IAAa;IACzD,MAAM,QAAQ,GAAG;QACf,EAAE,EAAE,IAAa;QACjB,OAAO;QACP,gBAAgB,EAAE,gBAAgB;QAClC,OAAO,EAAE,UAAU,EAAE;QACrB,IAAI;KACL,CAAC;IACF,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC;AACvD,CAAC"}