nova-spec 1.0.4 → 1.0.6

package/AGENTS.md

@@ -1,6 +1,6 @@
 # nova-spec — framework AGENTS.md
 
-> This repo uses CLAUDE.md as a stub → AGENTS.md is the instructions file.
+> This repo uses `CLAUDE.md` as a stub → `AGENTS.md` is the instructions file.
 
 This repo is the **nova-spec framework itself** — a Spec-Driven Development (SDD) system for Claude Code. It's designed to be installed into other projects.
 
@@ -8,6 +8,22 @@ This repo is the **nova-spec framework itself** — a Spec-Driven Development (S
 
 Framework that orchestrates ticket-to-PR workflow with 7 slash commands: `/nova-start` → `/nova-spec` → `/nova-plan` → `/nova-build` → `/nova-review` → `/nova-wrap` → `/nova-status`.
 
+## Installation (consumer repos)
+
+To install nova-spec into another repo, run:
+
+```bash
+npx nova-spec init
+```
+
+That leaves the repo usable without manual steps:
+
+- `AGENTS.md` and `CLAUDE.md` (shim that points to `AGENTS.md`)
+- `novaspec/` framework files
+- `.claude/` symlinks (and optionally `.opencode/`)
+- `context/` memory structure
+- `novaspec/config.yml` is **gitignored** (local per-repo configuration)
+
 ## Key commands
 
 - `/nova-start <TICKET>` — classify ticket, create branch, load context
@@ -52,8 +68,13 @@ At the start of every session, check if nova-spec has pending updates by running
 
 If `novaspec/.nova-manifest.json` exists and the installed version matches the latest, skip it silently. If there are updates or outdated custom overrides, report them to the user before proceeding.
 
-> **Claude Code** handles this automatically via a `SessionStart` hook in `.claude/settings.json`.
-> **OpenCode** relies on this instruction — always run `/nova-sync` at session start.
+This repo (and consumer repos) use `npx nova-spec sync` to update stock files **idempotently** without clobbering local edits.
+Sync records what was last shipped to the repo in `novaspec/.nova-manifest.json`, and only updates files that are still untouched locally.
+
+Hooks are maintained in:
+
+- `.claude/settings.local.json` (Claude Code)
+- `.opencode/settings.local.json` (OpenCode)
 
 ## Symlinks
 
@@ -66,6 +87,14 @@ This repo uses itself. When modifying nova-spec:
 2. Verify symlinks work: `ls -la .claude/`
 3. Run through a full ticket cycle
 
+## Tests
+
+Run the smoke test suite with:
+
+```bash
+npm test
+```
+
 ## Reference
 
 - Full docs: [README.md](./README.md)

package/CLAUDE.md

@@ -0,0 +1,3 @@
+AGENTS.md
+
+This repository uses `AGENTS.md` as the single source of truth for working instructions.

package/PHILOSOPHY.md

@@ -94,14 +94,14 @@ We accept living without features. We do not accept living with bloat. The cost
 
 ## Forking and customization
 
-**Today (known limitation).** The installer does `rm -rf novaspec/` and re-copies from source. Local edits to `novaspec/commands/`, `skills/`, `templates/`, or `agents/` are **lost on re-run**. The installer only preserves `novaspec/config.yml` (via backup) and the consumer's `context/`.
+**Today.** Updates are applied with `npx nova-spec sync`, which is idempotent and will not overwrite local edits to stock framework files. Sync records the last-shipped hashes in `novaspec/.nova-manifest.json` and:
 
-This contradicts principle 5. We acknowledge the gap. Two practical paths today:
+- Updates files that are still untouched locally
+- Skips files you edited and reports them so you can merge intentionally
 
-- **Team fork**: clone the nova-spec repo into your team's space, customize, install from your fork. Your fork is your `SCRIPT_DIR`.
-- **Manual updates**: don't re-run the installer; pull updates by hand and merge edits.
+This keeps the framework from being the reason you can't ship: your local edits remain yours.
 
-**Planned (not built).** A `team-overrides/` directory that survives re-installs. Until shipped, the fork is the answer. Do not pretend otherwise to consumers.
+If you need deeper customization, commit it in your repo (or fork nova-spec). When upstream changes touch files you customized, sync will intentionally refuse to overwrite them — you choose how to merge.
 
 ---
 

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

@@ -38,7 +38,9 @@ function buildPrCommand({ forge, cli, title, body, base }) {
     return `gh pr create --base ${q(base)} --title ${q(title)} --body ${q(body)}`;
   }
   if (forge === 'gitlab' || resolvedCli === 'glab') {
-    return `glab mr create --target-branch ${q(base)} --title ${q(title)} --description ${q(body)} --fill`;
+    // NOTE: Avoid `--fill` because it can trigger glab autofill/push behavior depending on user config.
+    // We always pass title/body explicitly, and we never implicitly push.
+    return `glab mr create --target-branch ${q(base)} --title ${q(title)} --description ${q(body)} --yes`;
   }
   throw new Error(`Unknown forge: ${forge}`);
 }

package/lib/installer.js

@@ -7,6 +7,7 @@ const {
   generateManifest,
   buildHookCommand,
   HOOK_MARKER,
+  MANIFEST_FILE,
 } = require('./sync.js');
 const { detectForge } = require('./forge.js');
 const { listTransitionsAsync } = require('./jira.js');
@@ -15,11 +16,37 @@ const PACKAGE_ROOT = path.join(__dirname, '..');
 const NOVASPEC_SRC = path.join(PACKAGE_ROOT, 'novaspec');
 const AGENTS_SRC = path.join(PACKAGE_ROOT, 'AGENTS.md');
 const CLAUDE_MD_SRC = path.join(PACKAGE_ROOT, 'CLAUDE.md');
-const MANIFEST_FILE = '.nova-manifest.json';
 
 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 +56,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);

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();
@@ -79,58 +87,6 @@ async function transitionAsync({ url, email, token, ticket, transitionId }) {
   });
 }
 
-function runCli() {
-  // CLI mode: node lib/jira.js <command> [args...]
-  const [, , cmd, ...args] = process.argv;
-  const { JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN } = process.env;
-
-  if (!JIRA_URL || !JIRA_EMAIL || !JIRA_API_TOKEN) {
-    console.error('Missing env vars: JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN');
-    process.exit(2);
-  }
-
-  const baseArgs = { url: JIRA_URL, email: JIRA_EMAIL, token: JIRA_API_TOKEN };
-  let promise;
-
-  switch (cmd) {
-    case 'get':
-      if (!args[0]) {
-        console.error('Usage: nova-jira get <TICKET>');
-        process.exit(2);
-      }
-      promise = getIssueAsync({ ...baseArgs, ticket: args[0] });
-      break;
-    case 'transitions':
-      if (!args[0]) {
-        console.error('Usage: nova-jira transitions <TICKET>');
-        process.exit(2);
-      }
-      promise = listTransitionsAsync({ ...baseArgs, ticket: args[0] });
-      break;
-    case 'transition':
-      if (!args[0] || !args[1]) {
-        console.error('Usage: nova-jira transition <TICKET> <TRANSITION_ID>');
-        process.exit(2);
-      }
-      promise = transitionAsync({ ...baseArgs, ticket: args[0], transitionId: args[1] });
-      break;
-    default:
-      console.error('Commands: get <TICKET> | transitions <TICKET> | transition <TICKET> <ID>');
-      process.exit(2);
-  }
-
-  promise
-    .then((r) => {
-      if (r != null) console.log(JSON.stringify(r, null, 2));
-    })
-    .catch((err) => {
-      console.error(err.message);
-      process.exit(err.status === 401 ? 401 : err.status === 404 ? 404 : 1);
-    });
-}
-
-if (require.main === module) runCli();
-
 module.exports = {
   getIssueAsync,
   listTransitionsAsync,

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';
@@ -111,9 +110,13 @@ 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.
+    // This preserves edits when the manifest is deleted/corrupt/merged-away,
+    // at the cost of needing /nova-diff to apply the new version.
+    if (previousShipped && currentHash === previousShipped) {
       fs.copyFileSync(srcAbs, destAbs);
       updated.push(rel);
     } else {
@@ -187,8 +190,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) {
@@ -245,4 +250,5 @@ module.exports = {
   collectPackageFiles,
   HOOK_MARKER,
   FRAMEWORK_FILES,
+  MANIFEST_FILE,
 };

package/novaspec/agents/context-loader.md

@@ -27,31 +27,41 @@ If `context/` doesn't exist, return:
 ## Loaded context
 **Services**: not documented (context/ missing)
 **Decisions**: none
-**Gaps**: context/ structure not initialized — run `npx nova-spec init`
+**Gaps**: context/ structure not initialized — run npx nova-spec init
 **Questions**: none
 ```
 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-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-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/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.4",
+  "version": "1.0.6",
   "description": "Spec-Driven Development framework for Claude Code and OpenCode",
   "bin": {
     "nova-spec": "bin/nova-spec.js"
@@ -15,14 +15,19 @@
     "novaspec/templates/",
     "novaspec/config.example.yml",
     "AGENTS.md",
+    "CLAUDE.md",
     "INSTALL.md",
     "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"
@@ -39,5 +44,8 @@
     "spec-driven-development",
     "jira",
     "workflow"
-  ]
+  ],
+  "devDependencies": {
+    "vitepress": "^1.6.4"
+  }
 }