nova-spec 1.0.5 → 1.0.7

package/lib/cli.js

@@ -2,10 +2,13 @@
 
 const fs = require('fs');
 const path = require('path');
+const yaml = require('js-yaml');
 const { init } = require('./installer.js');
 const { sync } = require('./sync.js');
 const jira = require('./jira.js');
 
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
 async function run() {
   const command = process.argv[2];
 
@@ -39,8 +42,15 @@ function runSource(args) {
     console.error('Usage: nova-spec source <relative-path>');
     process.exit(2);
   }
-  const PACKAGE_ROOT = path.join(__dirname, '..');
-  const abs = path.join(PACKAGE_ROOT, relPath);
+
+  // Resolve and CONTAIN within PACKAGE_ROOT. Rejects ../ traversal so prompt
+  // injection through $ARGUMENTS can't read arbitrary files via /nova-diff.
+  const abs = path.resolve(PACKAGE_ROOT, relPath);
+  const rootWithSep = PACKAGE_ROOT + path.sep;
+  if (abs !== PACKAGE_ROOT && !abs.startsWith(rootWithSep)) {
+    console.error(`✗ Path escapes the nova-spec package: ${relPath}`);
+    process.exit(1);
+  }
   if (!fs.existsSync(abs)) {
     console.error(`✗ ${relPath} is not part of the nova-spec package.`);
     process.exit(1);
@@ -56,31 +66,34 @@ async function runJira(args) {
   }
 
   const config = readJiraConfig();
-  if (!config) {
-    console.error('  ✗ Jira not configured. Run `npx nova-spec init` and enable Jira.');
+  if (!config.ok) {
+    console.error(`  ✗ ${config.error}`);
+    if (config.hint) console.error(`     ${config.hint}`);
     process.exit(1);
   }
 
   try {
     let result;
+    const baseArgs = { url: config.url, email: config.email, token: config.token };
     if (subcmd === 'get') {
       if (!rest[0]) throw new Error('Usage: nova-spec jira get <TICKET>');
-      result = await jira.getIssueAsync({ ...config, ticket: rest[0] });
+      result = await jira.getIssueAsync({ ...baseArgs, ticket: rest[0] });
     } else if (subcmd === 'transitions') {
       if (!rest[0]) throw new Error('Usage: nova-spec jira transitions <TICKET>');
-      result = await jira.listTransitionsAsync({ ...config, ticket: rest[0] });
+      result = await jira.listTransitionsAsync({ ...baseArgs, ticket: rest[0] });
     } else if (subcmd === 'transition') {
       if (!rest[0] || !rest[1]) throw new Error('Usage: nova-spec jira transition <TICKET> <ID>');
-      result = await jira.transitionAsync({ ...config, ticket: rest[0], transitionId: rest[1] });
+      result = await jira.transitionAsync({ ...baseArgs, ticket: rest[0], transitionId: rest[1] });
     } else {
       throw new Error(`Unknown jira subcommand: ${subcmd}`);
     }
     if (result != null) console.log(JSON.stringify(result, null, 2));
   } catch (err) {
     if (err.status === 401) {
-      console.error('  ✗ Jira 401: invalid credentials. Regenerate JIRA_API_TOKEN.');
+      console.error('  ✗ Jira 401: invalid credentials. Regenerate JIRA_API_TOKEN at');
+      console.error('     https://id.atlassian.com/manage-profile/security/api-tokens');
     } else if (err.status === 404) {
-      console.error(`  ✗ Jira 404: ticket not found.`);
+      console.error(`  ✗ Jira 404: ${rest[0] || 'ticket'} not found.`);
     } else {
       console.error(`  ✗ ${err.message}`);
     }
@@ -89,13 +102,17 @@ async function runJira(args) {
 }
 
 async function runForge(args) {
-  const { detectForge, buildPrCommand, reviewTerm, checkCliAvailable } = require('./forge.js');
+  const { detectForge, buildPrCommand, reviewTerm, checkCliAvailable, pickCli } = require('./forge.js');
   const [subcmd, ...rest] = args;
 
   if (subcmd === 'detect') {
     const f = detectForge();
-    if (f) console.log(f);
-    else process.exit(1);
+    if (f) {
+      console.log(f);
+    } else {
+      console.error('✗ No git remote `origin` or unsupported forge.');
+      process.exit(1);
+    }
     return;
   }
 
@@ -107,6 +124,12 @@ async function runForge(args) {
       process.exit(2);
     }
     const cli = config.cli !== 'auto' ? config.cli : null;
+    const resolvedCli = pickCli(forge, cli);
+    if (resolvedCli && !checkCliAvailable(resolvedCli)) {
+      console.error(`  ✗ ${resolvedCli} is not installed or not on PATH.`);
+      console.error(`     Install: ${resolvedCli === 'gh' ? 'https://cli.github.com/' : 'https://gitlab.com/gitlab-org/cli'}`);
+      process.exit(127);
+    }
     const [title, body, base] = rest;
     if (!title || !body || !base) {
       console.error('Usage: nova-spec forge pr-command <title> <body> <base>');
@@ -127,50 +150,65 @@ async function runForge(args) {
   process.exit(2);
 }
 
-function readJiraConfig() {
+// Parse novaspec/config.yml into a plain JS object. Returns null if missing.
+// Returns null + warns if YAML is malformed (don't crash callers).
+function loadConfig() {
   const configPath = path.join(process.cwd(), 'novaspec', 'config.yml');
   if (!fs.existsSync(configPath)) return null;
-  const text = fs.readFileSync(configPath, 'utf8');
+  try {
+    return yaml.load(fs.readFileSync(configPath, 'utf8')) || {};
+  } catch (err) {
+    return { __parseError: err.message };
+  }
+}
+
+function readJiraConfig() {
+  const cfg = loadConfig();
+  if (!cfg) {
+    return { ok: false, error: 'novaspec/config.yml not found.', hint: 'Run: npx nova-spec init' };
+  }
+  if (cfg.__parseError) {
+    return { ok: false, error: `novaspec/config.yml has invalid YAML: ${cfg.__parseError}` };
+  }
 
-  const url = extractYamlScalar(text, 'jira', 'url');
-  const email = extractYamlScalar(text, 'jira', 'email');
-  let token = extractYamlScalar(text, 'jira', 'token');
+  const jiraCfg = cfg.jira || {};
+  const { url, email } = jiraCfg;
+  let token = jiraCfg.token;
 
-  if (token && /^\$\{[A-Z_]+\}$/.test(token)) {
-    const envName = token.slice(2, -1);
-    token = process.env[envName];
-  } else if (token === '${JIRA_API_TOKEN}' || !token) {
-    token = process.env.JIRA_API_TOKEN;
+  // Resolve ${ENV_VAR} reference
+  if (typeof token === 'string') {
+    const m = token.match(/^\$\{([A-Z_][A-Z0-9_]*)\}$/);
+    if (m) token = process.env[m[1]];
+  }
+  if (!token) token = process.env.JIRA_API_TOKEN;
+
+  if (!url || !email) {
+    return {
+      ok: false,
+      error: 'Jira not configured.',
+      hint: 'Set jira.url and jira.email in novaspec/config.yml, or run: npx nova-spec init',
+    };
+  }
+  if (!token) {
+    return {
+      ok: false,
+      error: 'JIRA_API_TOKEN env var is not set.',
+      hint: 'Export it in your shell rc. Get one at https://id.atlassian.com/manage-profile/security/api-tokens',
+    };
   }
 
-  if (!url || !email || !token) return null;
-  return { url, email, token };
+  return { ok: true, url, email, token };
 }
 
 function readForgeConfig() {
-  const configPath = path.join(process.cwd(), 'novaspec', 'config.yml');
+  const cfg = loadConfig();
   const defaults = { type: 'auto', cli: 'auto' };
-  if (!fs.existsSync(configPath)) return defaults;
-  const text = fs.readFileSync(configPath, 'utf8');
+  if (!cfg || cfg.__parseError) return defaults;
+  const forge = cfg.forge || {};
   return {
-    type: extractYamlScalar(text, 'forge', 'type') || 'auto',
-    cli: extractYamlScalar(text, 'forge', 'cli') || 'auto',
+    type: forge.type || 'auto',
+    cli: forge.cli || 'auto',
   };
 }
 
-function extractYamlScalar(text, parent, key) {
-  // Minimal YAML reader for `parent: \n  key: value` blocks. Strips quotes.
-  const re = new RegExp(`^${parent}:\\s*$([\\s\\S]*?)(?=^\\S|\\Z)`, 'm');
-  const block = text.match(re);
-  if (!block) return null;
-  const lineRe = new RegExp(`^\\s+${key}:\\s*(.*)$`, 'm');
-  const match = block[1].match(lineRe);
-  if (!match) return null;
-  let value = match[1].trim();
-  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-    value = value.slice(1, -1);
-  }
-  return value;
-}
-
-module.exports = { run };
+module.exports = { run, loadConfig, readJiraConfig, readForgeConfig };

package/lib/forge.js

@@ -2,20 +2,45 @@
 
 const { execSync } = require('child_process');
 
+function classifyRemote(remote) {
+  if (!remote) return null;
+  if (/github\.com[:/]/i.test(remote)) return 'github';
+  if (/gitlab[.-][\w.-]+[:/]|gitlab\.com[:/]/i.test(remote)) return 'gitlab';
+  if (/bitbucket\.org[:/]/i.test(remote)) return 'bitbucket';
+  return null;
+}
+
 function detectForge(cwd = process.cwd()) {
-  let remote = '';
+  // Try `origin` first (the common case).
   try {
-    remote = execSync('git remote get-url origin', { cwd, stdio: ['ignore', 'pipe', 'ignore'] })
+    const remote = execSync('git remote get-url origin', {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
       .toString()
       .trim();
+    const hit = classifyRemote(remote);
+    if (hit) return hit;
   } catch (_) {
-    return null;
+    // fall through to multi-remote scan
+  }
+
+  // Fallback: walk every remote URL. Useful for fork workflows where the
+  // primary remote is named `upstream` or `gh` instead of `origin`.
+  try {
+    const lines = execSync('git remote -v', { cwd, stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .split('\n');
+    for (const line of lines) {
+      const m = line.match(/^\S+\s+(\S+)\s+\((fetch|push)\)$/);
+      if (!m) continue;
+      const hit = classifyRemote(m[1]);
+      if (hit) return hit;
+    }
+  } catch (_) {
+    /* not a git repo or git not available */
   }
 
-  if (!remote) return null;
-  if (/github\.com[:/]/i.test(remote)) return 'github';
-  if (/gitlab[.-][\w.-]+[:/]|gitlab\.com[:/]/i.test(remote)) return 'gitlab';
-  if (/bitbucket\.org[:/]/i.test(remote)) return 'bitbucket';
   return null;
 }
 

package/lib/installer.js

@@ -8,6 +8,7 @@ const {
   buildHookCommand,
   HOOK_MARKER,
   MANIFEST_FILE,
+  writeAtomic,
 } = require('./sync.js');
 const { detectForge } = require('./forge.js');
 const { listTransitionsAsync } = require('./jira.js');
@@ -20,6 +21,33 @@ const CLAUDE_MD_SRC = path.join(PACKAGE_ROOT, 'CLAUDE.md');
 async function init() {
   console.log('\n  nova-spec installer\n  ───────────────────\n');
 
+  // Detect an existing installation in the current directory or globally.
+  // Re-running `init` from scratch would clobber the user's customizations,
+  // because the wizard path uses copyTree which doesn't hash-compare like
+  // sync does. So we refuse and route to sync instead.
+  const home = process.env.HOME || process.env.USERPROFILE;
+  const existingHere = fs.existsSync(path.join(process.cwd(), 'novaspec', MANIFEST_FILE));
+  const existingGlobal =
+    home && fs.existsSync(path.join(home, '.claude', 'novaspec', MANIFEST_FILE));
+
+  if (existingHere || existingGlobal) {
+    const where = existingHere ? `here (${process.cwd()})` : `globally (${home}/.claude)`;
+    console.log(`  ⚠ nova-spec is already installed ${where}.`);
+    console.log('     Running init again would overwrite local customizations.');
+    console.log();
+    const ok = await confirm({
+      message: 'Run `sync` instead (preserves your edits via hash-compare)?',
+      default: true,
+    });
+    if (!ok) {
+      console.log('  Cancelled. To reinstall from scratch, remove `novaspec/` manually first.');
+      return;
+    }
+    const { sync } = require('./sync.js');
+    await sync(existingHere ? process.cwd() : path.join(home, '.claude'));
+    return;
+  }
+
   const scope = await select({
     message: 'Where do you want to install nova-spec?',
     choices: [
@@ -29,7 +57,6 @@ async function init() {
     ],
   });
 
-  const home = process.env.HOME || process.env.USERPROFILE;
   if (scope === 'global' && !home) {
     console.error('  ✗ HOME / USERPROFILE not set; cannot resolve global install path.');
     process.exit(1);
@@ -99,7 +126,7 @@ async function init() {
 
   // Manifest reflects what we just shipped from the package.
   const manifest = generateManifest(PACKAGE_ROOT);
-  fs.writeFileSync(
+  writeAtomic(
     path.join(destDir, 'novaspec', MANIFEST_FILE),
     JSON.stringify(manifest, null, 2) + '\n',
   );
@@ -370,13 +397,13 @@ function writeClaudeSettings(claudeDir) {
     settings.hooks.SessionStart.push({ hooks: [novaHook] });
   }
 
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  writeAtomic(settingsPath, JSON.stringify(settings, null, 2) + '\n');
 }
 
 function writeOpenCodeSettings(opencodeDir) {
   const settingsPath = path.join(opencodeDir, 'settings.local.json');
   if (fs.existsSync(settingsPath)) return;
-  fs.writeFileSync(
+  writeAtomic(
     settingsPath,
     JSON.stringify(
       {
@@ -428,7 +455,7 @@ function writeConfig(destDir, { ticketSystem, jiraConfig, baseBranch, forgeType
     `    done: ${yamlString(jiraConfig.done_transition_id)}`,
   ].join('\n') + '\n';
 
-  fs.writeFileSync(configPath, content);
+  writeAtomic(configPath, content);
 }
 
 function ensureGitignore(destDir) {

package/lib/jira.js

@@ -31,6 +31,8 @@ function request({ url, method = 'GET', email, token, body = null }) {
       options.headers['Content-Type'] = 'application/json';
     }
 
+    options.timeout = 15000;
+
     const req = https.request(options, (res) => {
       let data = '';
       res.setEncoding('utf8');
@@ -38,7 +40,10 @@ function request({ url, method = 'GET', email, token, body = null }) {
       res.on('end', () => {
         const status = res.statusCode || 0;
         if (status >= 400) {
-          const error = new Error(`Jira HTTP ${status}: ${data || res.statusMessage}`);
+          // Never include the response body in the message — it can contain
+          // request metadata (echoed headers from misconfigured proxies / WAFs)
+          // that leaks Authorization. Surface only status + reason phrase.
+          const error = new Error(`Jira HTTP ${status}: ${res.statusMessage || 'request failed'}`);
           error.status = status;
           return reject(error);
         }
@@ -51,6 +56,9 @@ function request({ url, method = 'GET', email, token, body = null }) {
       });
     });
 
+    req.on('timeout', () => {
+      req.destroy(new Error('Jira request timed out (15s)'));
+    });
     req.on('error', (err) => reject(err));
     if (body) req.write(JSON.stringify(body));
     req.end();

package/lib/migrate-config.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const fs = require('fs');
+const { writeAtomic } = require('./sync.js');
 
 // Each migration is { from: 'X.Y', to: 'X.Y', apply: (text) => text }.
 // They run in order; each one transforms the YAML text. Idempotent — applying
@@ -26,10 +27,13 @@ const MIGRATIONS = [
     apply: (text) => {
       // Move done_transition_id under jira.transitions.done while keeping the
       // legacy key as fallback so older skills don't break mid-migration.
+      // The value capture is intentionally non-greedy and strips trailing
+      // whitespace + an optional inline `# comment` so users who hand-edited
+      // the file with annotations don't get their comment merged into the value.
       return text.replace(
-        /^(\s*)done_transition_id:\s*"?([^"\n]+)"?\s*$/m,
+        /^(\s*)done_transition_id:\s*"?([^"#\n]+?)"?\s*(?:#[^\n]*)?$/m,
         (_, indent, value) =>
-          `${indent}done_transition_id: "${value}"\n${indent}transitions:\n${indent}  done: "${value}"`,
+          `${indent}done_transition_id: "${value.trim()}"\n${indent}transitions:\n${indent}  done: "${value.trim()}"`,
       );
     },
   },
@@ -50,7 +54,7 @@ function migrateConfig(configPath) {
   }
 
   if (current !== original) {
-    fs.writeFileSync(configPath, current);
+    writeAtomic(configPath, current);
   }
 
   return { applied };

package/lib/sync.js

@@ -3,7 +3,6 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-const os = require('os');
 
 const MANIFEST_FILE = '.nova-manifest.json';
 const HOOK_MARKER = '# nova-spec auto-sync';
@@ -11,7 +10,29 @@ const FRAMEWORK_FILES = ['AGENTS.md', 'CLAUDE.md'];
 // Paths the user owns or that are auto-generated — never tracked or overwritten.
 const NEVER_TRACK = new Set(['novaspec/config.yml', `novaspec/${MANIFEST_FILE}`]);
 
+// Write content to a file via tmp + rename, so partial writes (SIGKILL,
+// disk-full mid-write) never leave a half-written file behind. Critical for
+// the manifest and settings.local.json — corrupted JSON there kills the
+// framework or the IDE startup.
+function writeAtomic(filePath, content) {
+  const tmp = `${filePath}.tmp.${process.pid}.${Date.now()}`;
+  fs.writeFileSync(tmp, content);
+  try {
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    throw err;
+  }
+}
+
 function hashFile(filePath) {
+  // Refuse to follow symlinks. If the user replaced a tracked file with a
+  // symlink, hash the link target STRING (not the resolved file) so the
+  // change is detected as "modified" and the framework leaves it alone.
+  const stat = fs.lstatSync(filePath);
+  if (stat.isSymbolicLink()) {
+    return crypto.createHash('sha256').update(fs.readlinkSync(filePath)).digest('hex');
+  }
   return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
 }
 
@@ -70,9 +91,18 @@ function readManifest(manifestPath) {
     const data = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
     return { files: data.files || {}, version: data.version };
   } catch (err) {
-    console.error(`  ✗ Could not parse ${manifestPath}: ${err.message}`);
-    console.error('     Aborting sync to avoid clobbering project state.');
-    process.exit(1);
+    // Corrupt manifest → back it up and continue with empty. Combined with the
+    // conservative sync rule (no previousShipped → SKIP), this preserves every
+    // local file. Replaces a hard process.exit that left users stuck.
+    const backup = `${manifestPath}.corrupt.${Date.now()}`;
+    try {
+      fs.renameSync(manifestPath, backup);
+      console.warn(`  ⚠ Manifest was corrupt; backed up to ${path.basename(backup)} and continuing.`);
+      console.warn('     Until the manifest is rebuilt, sync will skip every file that differs from the package.');
+    } catch (renameErr) {
+      console.warn(`  ⚠ Manifest is corrupt and could not be backed up: ${renameErr.message}`);
+    }
+    return { files: {} };
   }
 }
 
@@ -95,6 +125,11 @@ async function sync(destDir = process.cwd()) {
   const removed = [];
   const skippedRemoved = [];
 
+  // Migrate config.yml BEFORE writing the manifest, so a crash here doesn't
+  // leave the manifest claiming "new version applied" while config is stale.
+  const { migrateConfig } = require('./migrate-config.js');
+  migrateConfig(path.join(novaspecDest, 'config.yml'));
+
   // Update / create / skip files
   for (const [rel, srcAbs] of Object.entries(sources)) {
     const destAbs = path.join(destDir, rel);
@@ -111,9 +146,11 @@ async function sync(destDir = process.cwd()) {
     if (currentHash === newStockHash) continue; // already up to date
 
     const previousShipped = oldManifest.files[rel];
-    const isUntouched = !previousShipped || currentHash === previousShipped;
 
-    if (isUntouched) {
+    // Only overwrite when we KNOW the user didn't touch it: previousShipped
+    // must be recorded AND match the current disk hash. If the manifest is
+    // missing or doesn't mention this file, treat as user-owned and skip.
+    if (previousShipped && currentHash === previousShipped) {
       fs.copyFileSync(srcAbs, destAbs);
       updated.push(rel);
     } else {
@@ -145,11 +182,11 @@ async function sync(destDir = process.cwd()) {
   for (const rel of skippedRemoved) {
     if (oldManifest.files[rel]) newManifest.files[rel] = oldManifest.files[rel];
   }
-  fs.writeFileSync(manifestPath, JSON.stringify(newManifest, null, 2) + '\n');
+  writeAtomic(manifestPath, JSON.stringify(newManifest, null, 2) + '\n');
 
-  // Migrate config.yml (idempotent)
-  const { migrateConfig } = require('./migrate-config.js');
-  migrateConfig(path.join(novaspecDest, 'config.yml'));
+  // Refresh runtime dirs: re-link .claude/{commands,skills,agents} if a previous
+  // install on Windows fell back to copy. Idempotent — no-op when already linked.
+  refreshRuntimeLinks(destDir);
 
   // Refresh SessionStart hook in any installed runtime
   ensureSessionStartHook(destDir);
@@ -187,8 +224,10 @@ function printReport({ version, created, updated, skipped, removed, skippedRemov
 }
 
 function buildHookCommand() {
-  const logPath = path.join(os.homedir(), '.nova-spec.log');
-  return `npx nova-spec@latest sync >> ${logPath} 2>&1 || true ${HOOK_MARKER}`;
+  // Use $HOME so the shell resolves it at run time. Avoids baking the
+  // installer's home dir into the consumer's settings and survives paths
+  // with spaces / apostrophes (common on macOS and Windows usernames).
+  return `npx nova-spec@latest sync >> "$HOME/.nova-spec.log" 2>&1 || true ${HOOK_MARKER}`;
 }
 
 function ensureSessionStartHook(destDir) {
@@ -200,6 +239,12 @@ function ensureSessionStartHook(destDir) {
     path.join(destDir, '.opencode', 'settings.local.json'),
   ].filter(p => fs.existsSync(path.dirname(p)));
 
+  // Any hook command running `npx nova-spec[@<tag>] sync` is OURS, even if
+  // it doesn't carry the modern marker (older installs from before v1.0.2).
+  // Strip all of them and append one canonical entry — guaranteed dedupe.
+  const isNovaHook = (h) =>
+    h && typeof h.command === 'string' && /\bnpx\s+nova-spec(@\S+)?\s+sync\b/.test(h.command);
+
   for (const settingsPath of targets) {
     let settings = {};
     if (fs.existsSync(settingsPath)) {
@@ -215,24 +260,73 @@ function ensureSessionStartHook(destDir) {
     settings.hooks = settings.hooks || {};
     settings.hooks.SessionStart = settings.hooks.SessionStart || [];
 
-    let updated = false;
     for (const group of settings.hooks.SessionStart) {
-      group.hooks = group.hooks || [];
-      for (let i = 0; i < group.hooks.length; i++) {
-        if (group.hooks[i]?.command?.includes(HOOK_MARKER)) {
-          if (group.hooks[i].command !== hookCommand) {
-            group.hooks[i] = novaHook;
-          }
-          updated = true;
-        }
-      }
+      if (!Array.isArray(group.hooks)) continue;
+      group.hooks = group.hooks.filter((h) => !isNovaHook(h));
     }
+    // Drop groups whose hooks array is now empty
+    settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
+      (g) => Array.isArray(g.hooks) && g.hooks.length > 0,
+    );
+
+    settings.hooks.SessionStart.push({ hooks: [novaHook] });
 
-    if (!updated) {
-      settings.hooks.SessionStart.push({ hooks: [novaHook] });
+    writeAtomic(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  }
+}
+
+function refreshRuntimeLinks(destDir) {
+  // Re-establish symlinks under .claude/ and .opencode/ if a previous install
+  // copied them instead (Windows EPERM fallback). On systems where symlinks
+  // are permitted this is a no-op; on Windows without Developer Mode it
+  // refreshes the copy with the latest content.
+  const novaspecDir = path.join(destDir, 'novaspec');
+  if (!fs.existsSync(novaspecDir)) return;
+
+  const runtimeDirs = ['.claude', '.opencode']
+    .map((d) => path.join(destDir, d))
+    .filter((d) => fs.existsSync(d));
+
+  for (const rt of runtimeDirs) {
+    for (const name of ['commands', 'skills', 'agents']) {
+      const link = path.join(rt, name);
+      const target = path.relative(rt, path.join(novaspecDir, name));
+
+      let isLink = false;
+      try {
+        isLink = fs.lstatSync(link).isSymbolicLink();
+      } catch (_) {
+        /* doesn't exist — fall through to create */
+      }
+
+      if (isLink) continue; // already linked, nothing to do
+
+      // It's a directory of copied files (Windows fallback) or missing.
+      // Try to make it a symlink; if that fails, refresh the copy.
+      fs.rmSync(link, { recursive: true, force: true });
+      const symlinkType = process.platform === 'win32' ? 'junction' : null;
+      try {
+        if (symlinkType) fs.symlinkSync(target, link, symlinkType);
+        else fs.symlinkSync(target, link);
+      } catch (err) {
+        if (err.code === 'EPERM' || err.code === 'EACCES') {
+          copyTreeShallow(path.join(novaspecDir, name), link);
+        } else {
+          throw err;
+        }
+      }
     }
+  }
+}
 
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+function copyTreeShallow(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyTreeShallow(s, d);
+    else fs.copyFileSync(s, d);
   }
 }
 
@@ -243,6 +337,8 @@ module.exports = {
   buildHookCommand,
   readManifest,
   collectPackageFiles,
+  refreshRuntimeLinks,
+  writeAtomic,
   HOOK_MARKER,
   FRAMEWORK_FILES,
   MANIFEST_FILE,

package/novaspec/agents/context-loader.md

@@ -32,26 +32,36 @@ If `context/` doesn't exist, return:
 ```
 And stop.
 
-### 2. Read each service
+### 2. Read stack and conventions (always)
+
+Always read these two files when they exist (they're scaffolded by `npx nova-spec init`):
+- `context/stack.md` — tech stack + key dependencies
+- `context/conventions.md` — code style + patterns to follow / avoid
+
+If either is missing, note it as a gap but continue.
+
+### 3. Read each service
 
 For each service in `$ARGUMENTS`:
 - Read `context/services/<service>.md` if it exists.
 - If it doesn't exist, note it as a gap.
 
-### 3. Pick relevant decisions and gotchas
+### 4. Pick relevant decisions and gotchas
 
 - `ls context/decisions/` (no `-R`, doesn't enter `archived/`).
 - `ls context/gotchas/`.
 - Pick 3-5 files from each whose name is relevant to the ticket's scope or affected services. Don't force connections.
 - Read the chosen ones.
 
-### 4. Return summary
+### 5. Return summary
 
 Return exactly this structure, without extra text:
 
 ```
 ## Loaded context
 
+**Stack**: <✓ loaded | ✗ missing>
+**Conventions**: <✓ loaded | ✗ missing>
 **Services**: <list with ✓ if services/<svc>.md exists, ✗ otherwise>
 **Decisions read**: <list of files or "none">
 **Gotchas read**: <list of files or "none">

package/novaspec/agents/nova-review-agent.md

@@ -16,17 +16,40 @@ the user. Don't make commits. Don't modify code.
   - `context/changes/active/<ticket-id>/proposal.md`
   - `context/changes/active/<ticket-id>/tasks.md`
 - Read live decisions in `context/decisions/` (all relevant ones, **without entering `archived/`**)
-- Get the full diff by combining:
-  - Committed changes on the branch: `git diff <branch.base>...HEAD`
-  - Uncommitted changes (working tree + staged): `git diff HEAD`
-  - Read `novaspec/config.yml → branch.base` to determine the base branch (default: `main`)
-  - If both diffs are empty, warn: "⚠️ Empty diff: no changes on the branch or in the working tree."
+- Read `novaspec/config.yml → branch.base` to determine the base branch (default: `main`)
 
 If any artifact is missing, stop with:
 ```
 ⛔ Review aborted: missing <file>. Run the corresponding step first.
 ```
 
+### 1b. Run deterministic checks (BLOCKING)
+
+Before any LLM-based review, run the deterministic guardrail:
+
+```bash
+bash novaspec/guardrails/review-checks.sh <ticket-id> <base-branch>
+```
+
+This runs (in order): diff non-empty, all `## Files to touch` declared in
+`tasks.md` actually appear in the diff, `npm run lint` if defined, `npm test`
+if defined.
+
+If the script exits non-zero, **mark the verdict as `✗ Needs fixes`
+immediately** and write the script's output verbatim into `review.md` under
+a `## Pre-review checks` section. Do NOT proceed to the 4-axis LLM review —
+the verdict is already negative. Skip straight to Step 3 (write the report)
+then Step 4 (terminate).
+
+### 1c. Get the full diff
+
+Combine:
+- Committed changes on the branch: `git diff <branch.base>...HEAD`
+- Uncommitted changes (working tree + staged): `git diff HEAD`
+
+(If `review-checks.sh` already failed at "Diff non-empty", the verdict is
+already locked — skip the diff fetch.)
+
 ### 2. Review across 4 axes
 
 **Spec compliance**

package/novaspec/commands/nova-build.md

@@ -6,7 +6,7 @@ You execute `tasks.md` in order, task by task.
 
 ## Guardrail
 
-`checklist.md` → 1, 3 (branch-pattern, tasks-exist)
+`checklist.md` → 0, 1, 2, 3 (nova-installed, branch-pattern, proposal-exists, tasks-exist)
 
 ## Precondition
 
@@ -54,10 +54,19 @@ Show the user:
 **If tasks remain**: continue with the next one without asking permission.
 
 **Stop only if**:
-- There's a blocker (error, unhandled exception)
+- There's a blocker (error, unhandled exception, test fails you can't fix)
 - There's an open decision in the spec
 - You have a question only the user can answer
 
+**When you stop on a failed task**, before stopping:
+1. Mark the failing task in `tasks.md` as `- [!]` (instead of `- [x]` or `- [ ]`)
+2. Append a one-line note next to it explaining why
+3. Tell the user what failed and what they need to decide
+
+This way, when the user later re-runs `/nova-build`, the framework picks
+up at the failed task (not from the first `- [ ]` after it) and the user
+can see at a glance what blocked the flow.
+
 **If it was the last one**:
 > "All complete. Run `/nova-review`."
 

package/novaspec/commands/nova-diff.md

@@ -1,64 +1,80 @@
 ---
-description: Show differences between your custom override and the current core version
-argument-hint: <skill|command|agent name>
+description: Show what changed upstream for a framework file you've edited locally
+argument-hint: <relative-path-from-repo-root>
 ---
 
-You are a **read-only** command. Show what changed between the user's custom
-override and the upstream core version for `$ARGUMENTS`.
+You are a **read-only** command. You compare the user's local version of a
+framework file against the version shipped by the installed nova-spec
+package, so they can decide whether to merge upstream changes.
 
-## Steps
-
-### 1. Resolve paths
+## When this is invoked
 
-- Custom path: `novaspec/custom/<type>/$ARGUMENTS/` (check `skills/`, `commands/`, `agents/` in order)
-- Core path: `novaspec/<type>/$ARGUMENTS/`
+`npx nova-spec sync` reports files with local edits under the heading
+`⚠ N file(s) NOT updated (you have local edits)` and points the user at
+this command via:
 
-If the custom path doesn't exist:
 ```
-No custom override found for "$ARGUMENTS".
-Nothing to diff.
+→ /nova-diff <path>
 ```
-Stop here.
 
-### 2. Check manifest
+For example: `/nova-diff novaspec/templates/pr-body.md`.
+
+## Steps
+
+### 1. Resolve the path
 
-Read `novaspec/.nova-manifest.json`. Look for `$ARGUMENTS` in `outdated_customs`.
+`$ARGUMENTS` is a path relative to the repo root, e.g.
+`novaspec/templates/pr-body.md` or `AGENTS.md`.
 
-If not in `outdated_customs`:
+Verify the local file exists. If not:
 ```
-Your custom "$ARGUMENTS" matches the current core version.
-No upstream changes since your override was created.
+No local file at "<path>". Nothing to diff.
 ```
-Stop here.
+Stop.
 
-### 3. Show diff
+### 2. Locate the upstream (package) version
 
 Run:
+
 ```bash
-diff -u novaspec/<type>/$ARGUMENTS/SKILL.md novaspec/custom/<type>/$ARGUMENTS/SKILL.md
+npx nova-spec source "$ARGUMENTS"
 ```
 
-Present the diff clearly, highlighting:
-- Lines added in your custom version (your changes)
-- Lines changed in the new core version that your custom doesn't have
+This prints the absolute path to the file **inside the installed nova-spec
+package** (somewhere like `~/.npm/_npx/<hash>/node_modules/nova-spec/<path>`).
+Exit code 1 + `✗ ... is not part of the nova-spec package.` means the path
+is not a framework file — tell the user it isn't tracked by nova-spec.
+
+### 3. Show the diff
+
+```bash
+diff -u "<package-path>" "<local-path>"
+```
+
+Read both files and present the diff clearly:
+- Lines marked `+` in YOUR copy are your edits (keep these unless you want to revert).
+- Lines marked `+` in the package copy are upstream changes (consider merging).
 
 ### 4. Decision prompt
 
+Ask the user:
+
 ```
 Options:
-  [K] Keep your version — ignore upstream changes
-  [M] Merge manually — I'll open both files for you to edit
-  [R] Replace with core — discard your custom, use new core version
+  [K] Keep your version — ignore the upstream change (no-op)
+  [M] Merge manually — I'll print both paths so you can edit
+  [R] Replace with the package version — discard your local edits
 ```
 
-Wait for user selection.
+Wait for an explicit selection.
 
-- **[K]**: Update manifest to mark as reviewed. No file changes.
-- **[M]**: Show both file paths and remind user to run `/nova-sync` after merging.
-- **[R]**: Delete `novaspec/custom/<type>/$ARGUMENTS/` and confirm.
+- **[K]**: do nothing. Next `/nova-sync` will skip the file again with the same warning.
+- **[M]**: print both file paths and remind the user that after they merge, sync may still flag the file as edited (until its hash again matches the shipped version).
+- **[R]**: copy the package version over the local file. **Ask for confirmation before overwriting.** After replacement, the next sync will treat it as up to date.
 
 ## Rules
 
-- Never auto-apply changes.
-- Always wait for explicit user decision.
-- For [R], ask for confirmation before deleting.
+- Never auto-apply. Always wait for explicit selection.
+- For `[R]`, double-confirm before overwriting — destructive.
+- If the user passes a path that includes `..`, the `source` CLI will
+  refuse it. Trust that boundary check; don't try to bypass it.

package/novaspec/commands/nova-plan.md

@@ -6,7 +6,21 @@ You translate the spec into an executable plan and tasks.
 
 ## Guardrail
 
-`checklist.md` → 1, 2 (branch-pattern, proposal-exists)
+`checklist.md` → 0, 1, 2, 7 (nova-installed, branch-pattern, proposal-exists, proposal-closed)
+
+### Run guardrail #7 before drafting tasks
+
+```bash
+bash novaspec/guardrails/proposal-closed.sh <ticket-id>
+```
+
+This greps `proposal.md` for `TBD`, `TODO`, `FIXME`, `???`, `<placeholder>`,
+`[ ] decision`. If it exits non-zero, **stop immediately** with the script's
+output. Tell the user:
+
+> "Proposal has open markers. Re-run `/nova-spec` to close them before planning."
+
+Do NOT generate `tasks.md` from an unclosed proposal.
 
 ## Precondition
 

package/novaspec/commands/nova-review.md

@@ -6,7 +6,7 @@ Final reviewer before closing the ticket.
 
 ## Guardrail
 
-`checklist.md` → 1, 4 (branch-pattern, all-tasks-done)
+`checklist.md` → 0, 1, 2, 4 (nova-installed, branch-pattern, proposal-exists, all-tasks-done)
 
 ## Steps
 

package/novaspec/commands/nova-spec.md

@@ -6,7 +6,7 @@ You are responsible for generating the technical spec of the current ticket.
 
 ## Guardrail
 
-`checklist.md` → 1 (branch-pattern)
+`checklist.md` → 0, 1 (nova-installed, branch-pattern)
 
 ## Precondition
 

package/novaspec/commands/nova-start.md

@@ -1,5 +1,5 @@
 ---
-description: Start the nova-spec flow from a Jira ticket
+description: Start the nova-spec flow from a ticket
 argument-hint: <TICKET-ID>
 ---
 
@@ -10,17 +10,45 @@ The user has passed the ticket: **$ARGUMENTS**
 Your job is to set the stage before any spec or code is written.
 Don't implement anything. Don't propose a spec. Just orchestrate.
 
+## Guardrail
+
+`checklist.md` → 0 (nova-installed)
+
 ## Steps
 
 ### 1. Get the ticket
 
-Read `novaspec/config.yml` → `jira.skill`.
-- If it has a value, invoke that skill to fetch the ticket.
-- If it's empty or missing, ask the user to paste:
-  - title
-  - description
-  - acceptance criteria
-  - relevant comments
+Read `novaspec/config.yml` → `ticket_system`. It's one of:
+- `jira` — fetch the ticket from Jira via the `jira-integration` skill
+- `none` (or missing key) — no tracker; user pastes content
+
+#### If `ticket_system: jira`
+
+Validate `$ARGUMENTS` matches `[A-Z][A-Z0-9]+-[0-9]+` (e.g. `PROJ-123`).
+If not, refuse and ask for a properly-formatted ticket key.
+
+Invoke the `jira-integration` skill, which runs `npx nova-spec jira get <TICKET>`. Error handling by exit code:
+
+- **Exit 401** — invalid credentials. Tell the user:
+  > "Jira returned 401 Unauthorized. Regenerate your API token at https://id.atlassian.com/manage-profile/security/api-tokens and update `JIRA_API_TOKEN`."
+  Do NOT retry. Stop.
+- **Exit 404** — ticket not found:
+  > "Jira returned 404 for `<TICKET>`. Check the key and `jira.project` in `novaspec/config.yml`."
+  Stop.
+- **Network / timeout / other** — fall back to manual paste:
+  > "Couldn't reach Jira. Paste the ticket title, description, AC, and relevant comments and I'll continue."
+
+#### If `ticket_system: none` (or missing)
+
+Skip the ticket-key format check — `$ARGUMENTS` is a free-form identifier.
+
+Ask the user to paste:
+- title
+- description
+- acceptance criteria
+- relevant comments
+
+Don't make up ticket content.
 
 ### 2. Classify the ticket
 

package/novaspec/commands/nova-wrap.md

@@ -7,7 +7,7 @@ This is the step that feeds architectural memory.
 
 ## Guardrail
 
-`checklist.md` → 1, 5, 6 (branch-pattern, review-approved, old-decision-archived)
+`checklist.md` → 0, 1, 5, 6 (nova-installed, branch-pattern, review-approved, old-decision-archived)
 
 ## Precondition
 
@@ -52,15 +52,28 @@ Default: don't write. Most tickets don't generate a gotcha.
 Use the structure of `novaspec/templates/commit.md` as a template.
 If there are many changes, propose grouping into logical commits.
 
-### 6. Create PR
+### 6. Create PR / MR (forge-agnostic)
 
 Resolve the base branch the same way `/nova-start` does:
 - Read `branch.base` from `novaspec/config.yml`.
 - If the key is missing, try `develop`; if that doesn't exist either, ask
   the user and recommend setting `branch.base` in `novaspec/config.yml`.
 
-Create the PR with `gh pr create --base <resolved-base> --title "<title>"
---body "<description>"`.
+**Do NOT hardcode `gh`.** Ask the CLI to build the right command for the
+forge (`gh pr create ...` for GitHub, `glab mr create ...` for GitLab):
+
+```bash
+npx nova-spec forge pr-command "<TICKET-ID>: <title>" "<description>" "<base>"
+```
+
+The CLI also verifies the forge binary is installed; if it isn't, it exits
+with code 127 and a clear error. Show the user the command, get confirmation,
+then execute it.
+
+For user-facing messages use the right vocabulary (PR vs MR):
+```bash
+TERM=$(npx nova-spec forge term)
+```
 
 **Title**: `<TICKET-ID>: <title>`
 
@@ -68,7 +81,9 @@ Create the PR with `gh pr create --base <resolved-base> --title "<title>"
 
 ### 7. Close the ticket in Jira
 
-If `novaspec/config.yml` has `jira.skill` set, invoke the `jira-integration` skill to transition the ticket to "Done".
+If `novaspec/config.yml` has `jira.skill` set (and `ticket_system: jira`), invoke the `jira-integration` skill to transition the ticket to "Done".
+
+The transition ID to use is `jira.transitions.done` from `novaspec/config.yml`. If that key is missing, fall back to the legacy `jira.done_transition_id`. The skill (or `npx nova-spec jira transition <TICKET> <id>` directly) handles the API call.
 
 Confirm to the user: "Ticket <TICKET-ID> marked as Done in Jira ✓"
 

package/novaspec/config.example.yml

@@ -15,10 +15,18 @@ branch:
   ticket_case: upper    # upper | lower
   base: main            # base branch of the flow
 
+forge:
+  type: auto            # auto | github | gitlab | none
+  cli: auto             # auto | gh | glab
+
+ticket_system: jira     # jira | none
+
 jira:
-  skill: ""                        # set to "jira-integration" to enable Jira
+  skill: jira-integration            # set to "" to disable Jira
   url: https://your-workspace.atlassian.net
   project: PROJ
   email: you@example.com
-  token: ${JIRA_API_TOKEN}         # create at id.atlassian.com/manage-profile/security/api-tokens
-  done_transition_id: "41"         # find via GET /rest/api/3/issue/<TICKET>/transitions
+  token: ${JIRA_API_TOKEN}            # create at id.atlassian.com/manage-profile/security/api-tokens
+  done_transition_id: "41"            # legacy, kept for backward-compat fallback
+  transitions:
+    done: "41"                        # structured form — read first by /nova-wrap

package/novaspec/guardrails/checklist.md

@@ -1,10 +1,23 @@
 # Guardrails — Checklist
 
-**Execution order: 1 → 2 → 3 → 4 → 5 → 6**
+**Execution order: 0 → 1 → 2 → 7 → 3 → 4 → 5 → 6**
+
+## 0. nova-installed
+Verify nova-spec is properly installed in this project.
+- Run `bash novaspec/guardrails/nova-installed.sh`.
+- Checks that `novaspec/config.yml` and `context/` exist.
+- ⛔ **Stop.** Run `npx nova-spec init` first.
 
 ## 1. branch-pattern
 Verify the active ticket branch. Extract `<ticket-id>` from the current git branch.
-- Must follow the pattern `(feature|fix|arch)/<TICKET>-<slug>` from `novaspec/config.yml`.
+- Read `branch.types` from `novaspec/config.yml` to know which prefixes are
+  valid for this project. The defaults shipped by the installer are:
+  `feature, fix, arch, bugfix, hotfix, docs, refactor, chore`.
+- The branch must follow `<type>/<TICKET>-<slug>` where `<type>` is any of
+  the configured types (matched against the **values** in `branch.types`,
+  e.g. `documentation: docs` → `docs` is valid).
+- If `ticket_system: none` in config, the `<TICKET>` part can be any
+  identifier the user chose (no enforced format).
 - ⛔ **Stop.** Run `/nova-start <TICKET>` first.
 
 ## 2. proposal-exists
@@ -32,3 +45,9 @@ Verify the review was approved.
 Validate that superseded decisions are archived.
 - Files in `context/decisions/*.md` with `> Supersedes: X.md` imply that `X.md` lives in `context/decisions/archived/`, not at the root.
 - ⛔ **Stop.** Move the file to `archived/` with `git mv` and retry.
+
+## 7. proposal-closed
+Deterministic check: the proposal has no unresolved markers.
+- Run `bash novaspec/guardrails/proposal-closed.sh <ticket-id>`.
+- The script greps for `TBD`, `TODO`, `FIXME`, `???`, `<placeholder>`, `[ ] decision`.
+- ⛔ **Stop.** Re-run `/nova-spec` and close the open requirements before `/nova-plan`.

package/novaspec/skills/jira-integration/SKILL.md

@@ -1,96 +1,81 @@
 ---
 name: jira-integration
-description: Read and create tasks in Jira via the REST API. Uses the project's config.yml (`jira` section).
+description: Read and transition Jira tickets via the deterministic `npx nova-spec jira` CLI. The CLI handles auth so tokens never appear in shell commands.
 ---
 
 # Jira Integration
 
-Read and create issues in Jira using Atlassian's REST API v3.
+This skill is a thin wrapper around the `npx nova-spec jira` subcommand,
+which is a small Node-based HTTP client. **Never build `curl` calls by hand**
+— the CLI keeps the `JIRA_API_TOKEN` inside the Node process and never
+inlines it on a command line.
 
-## Required config in config.yml
+## Required config in `novaspec/config.yml`
 
 ```yaml
+ticket_system: jira
+
 jira:
   skill: jira-integration
-  url: https://your-org.atlassian.net   # no trailing slash
-  project: PROJ                          # default project key
-  email: you@email.com
-  token: ${JIRA_API_TOKEN}               # reference to env variable
-  done_transition_id: "41"               # find it via GET /rest/api/3/issue/<TICKET>/transitions
+  url: https://your-workspace.atlassian.net   # no trailing slash
+  project: PROJ                                # default project key
+  email: you@example.com                       # tied to the token
+  token: ${JIRA_API_TOKEN}                     # env-var reference
+  done_transition_id: "41"                     # legacy, kept for fallback
+  transitions:
+    done: "41"                                 # preferred form, used by /nova-wrap
 ```
 
 Get the token at: https://id.atlassian.com/manage-profile/security/api-tokens
 
-## How to use this skill
-
-When the user asks to read or create Jira tasks:
-
-1. **Read the config**: read the project's `config.yml` and extract the `jira` section.
-2. **Resolve the token**: if the value starts with `${`, read the corresponding env variable (e.g. `$JIRA_API_TOKEN`).
-3. **Build Basic Auth credentials**: `base64(email:token)`.
-4. **Call the API** with `curl` for the requested operation.
-
 ## Operations
 
 ### Read a ticket
 
 ```bash
-curl -s \
-  -H "Authorization: Basic <BASE64>" \
-  -H "Accept: application/json" \
-  "https://<url>/rest/api/3/issue/<TICKET_KEY>"
+npx nova-spec jira get <TICKET-KEY>
 ```
 
-Show the user: key, summary, status (status.name), description, assignee.
+Output is JSON. Extract: `key`, `fields.summary`, `fields.status.name`,
+`fields.description`, `fields.assignee.displayName`.
 
-### List tickets in a project (recent open ones)
+### List transitions for a ticket
 
 ```bash
-curl -s \
-  -H "Authorization: Basic <BASE64>" \
-  -H "Accept: application/json" \
-  "https://<url>/rest/api/3/search?jql=project=<PROJECT>+AND+statusCategory!=Done+ORDER+BY+created+DESC&maxResults=20&fields=summary,status,assignee,priority"
+npx nova-spec jira transitions <TICKET-KEY>
 ```
 
-### Create a ticket
+Use this when `transitions.done` is missing or wrong: it tells you which
+transitions are reachable from the current ticket status, and their IDs.
+
+### Transition a ticket (close as Done from `/nova-wrap`)
 
 ```bash
-curl -s -X POST \
-  -H "Authorization: Basic <BASE64>" \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json" \
-  "https://<url>/rest/api/3/issue" \
-  -d '{
-    "fields": {
-      "project": { "key": "<PROJECT>" },
-      "summary": "<TITLE>",
-      "description": {
-        "type": "doc", "version": 1,
-        "content": [{"type": "paragraph", "content": [{"type": "text", "text": "<DESCRIPTION>"}]}]
-      },
-      "issuetype": { "name": "<TYPE>" }
-    }
-  }'
+npx nova-spec jira transition <TICKET-KEY> <TRANSITION-ID>
 ```
 
-### Transition ticket to Done
+Read `<TRANSITION-ID>` from `novaspec/config.yml` → `jira.transitions.done`.
+Fall back to `jira.done_transition_id` if the structured form is missing.
 
-```bash
-AUTH=$(echo -n "<email>:<token>" | base64)
-curl -s -X POST \
-  -H "Authorization: Basic $AUTH" \
-  -H "Content-Type: application/json" \
-  "https://<url>/rest/api/3/issue/<TICKET-ID>/transitions" \
-  -d "{\"transition\": {\"id\": \"<done_transition_id>\"}}"
-```
+## Error handling
 
-Use `done_transition_id` from `config.yml`. To find your transition IDs:
-```bash
-curl -s -H "Authorization: Basic <BASE64>" "https://<url>/rest/api/3/issue/<ANY-TICKET>/transitions"
-```
+The CLI exits with:
+
+| Code | Meaning | What to do |
+|---|---|---|
+| 0   | Success | Continue |
+| 1   | Generic error (network, parse) | Surface the message; offer manual fallback |
+| 2   | Usage error (missing arg) | Fix the command and retry |
+| 401 | Invalid credentials | Tell user to regenerate `JIRA_API_TOKEN` — **do NOT retry** |
+| 404 | Ticket not found | Confirm the key with the user |
+
+When the CLI prints `✗ Jira 401`, never retry — credentials are wrong.
 
-## Notes
+## Rules
 
-- If `token` is not in config.yml, ask the user to set it.
-- If the project is not specified in the request, use the `project` from config.yml.
-- On HTTP errors (401, 403, 404), show Jira's error message but never expose the token.
+- **Never** paste the token into a `curl` command. The CLI reads it from
+  `JIRA_API_TOKEN` env var via the `${JIRA_API_TOKEN}` reference in `config.yml`.
+- If `JIRA_API_TOKEN` is missing, the CLI fails fast with `✗ JIRA_API_TOKEN env var is not set.`
+- For debugging only (and never with a real token visible), you can build
+  Basic Auth via `AUTH=$(printf '%s' "$JIRA_EMAIL:$JIRA_API_TOKEN" | base64)` —
+  but the CLI is always preferable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nova-spec",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Spec-Driven Development framework for Claude Code and OpenCode",
   "bin": {
     "nova-spec": "bin/nova-spec.js"
@@ -20,10 +20,14 @@
     "PHILOSOPHY.md"
   ],
   "scripts": {
-    "test": "node test/smoke.test.js"
+    "test": "node test/smoke.test.js",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "dependencies": {
-    "@inquirer/prompts": "^7.0.0"
+    "@inquirer/prompts": "^7.0.0",
+    "js-yaml": "^4.1.1"
   },
   "engines": {
     "node": ">=18"
@@ -40,5 +44,8 @@
     "spec-driven-development",
     "jira",
     "workflow"
-  ]
+  ],
+  "devDependencies": {
+    "vitepress": "^1.6.4"
+  }
 }