@novare-technologies/nvaid 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Novare SQE Armory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -31,6 +31,27 @@ nvaid init --owning-repo frontend        # preset the config's owning_repo
 nvaid init --yes                          # non-interactive (defaults to the AGENTS.md catch-all)
 ```
 
+## Upgrading
+
+Upgrading is **two steps**, because `nvaid update` re-syncs a repo to the version of the
+tool installed on your machine — it does not upgrade the tool itself:
+
+```bash
+# 1. upgrade the tool (once per machine, when a new version ships)
+npm i -g @novare-technologies/nvaid@latest
+
+# 2. re-sync each repo to the new version (run inside each repo)
+nvaid update
+```
+
+nvaid checks npm (at most once a day, cached, non-blocking) and prints a one-line nudge
+when a newer version is available — it never upgrades itself (the package manager owns the
+tool's lifecycle). Silence the check with `NVAID_NO_UPDATE_CHECK=1`.
+
+Note: `nvaid update` never touches hand-owned files (`config.yml`, `PROJECT-RULES.md`,
+`DESIGN-CODE-DICTIONARY.md`, `intents/`). If a new version adds a config field, add it to
+your `config.yml` by hand — the changelog will call these out.
+
 ## How it works
 
 - **Full skill set, no profiles.** `init` injects every skill into each selected agent. A

package/dist/cli.js

@@ -109,8 +109,8 @@ var NVAID_DIR_NAME = "nvaid";
 var CONFIG_FILE = "config.yml";
 var AIDLC_ROOT_TOKEN = "{{AIDLC_ROOT}}";
 async function nvaidVersion() {
-  const { readFile: readFile3 } = await import("fs/promises");
-  const pkg = JSON.parse(await readFile3(resolve(TEMPLATES_DIR, "..", "package.json"), "utf8"));
+  const { readFile: readFile4 } = await import("fs/promises");
+  const pkg = JSON.parse(await readFile4(resolve(TEMPLATES_DIR, "..", "package.json"), "utf8"));
   return pkg.version;
 }
 
@@ -270,8 +270,14 @@ function hasConfig(projectRoot) {
 async function readConfig(projectRoot) {
   const raw = await readFile2(configPath(projectRoot), "utf8");
   const parsed = parse(raw) ?? {};
+  const install = parsed.install ?? {};
   return {
     schema: parsed.schema ?? "nvaid/v1",
+    install: {
+      config: install.config === true,
+      project_rules: install.project_rules === true,
+      design_code_dictionary: install.design_code_dictionary === true
+    },
     project_name: parsed.project_name ?? "",
     owning_repo: parsed.owning_repo ?? "",
     tech_stack: { ...EMPTY_STACK, ...parsed.tech_stack ?? {} },
@@ -362,13 +368,14 @@ async function runInit(opts) {
   );
   p.outro(
     [
-      "Next, in your AI chat:",
+      "Next, in your AI chat \u2014 run this FIRST:",
+      "  /nvaid:install         scan the project, fill config.yml + PROJECT-RULES + dictionary",
+      "",
+      "The workflow commands are blocked until /nvaid:install completes:",
       '  /nvaid:intent "..."   draft the intent, then STOP for stakeholder approval',
       "  /nvaid:contracts       after approval \u2014 draft the per-role contracts",
       "  /nvaid:breakdown       cut into units (tagged by owning repo)",
-      "  /nvaid:apply           generate per-repo unit docs + branches",
-      "",
-      "Fill in nvaid/PROJECT-RULES.md and set owning_repo in nvaid/config.yml."
+      "  /nvaid:apply           generate per-repo unit docs + branches"
     ].join("\n")
   );
 }
@@ -453,9 +460,84 @@ async function runValidate() {
   return 0;
 }
 
+// src/updateNotifier.ts
+import { readFile as readFile3, writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
+import { homedir, tmpdir } from "os";
+import { join as join4 } from "path";
+import pc4 from "picocolors";
+var PKG = "@novare-technologies/nvaid";
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 1500;
+function cacheFile() {
+  const base = process.env.XDG_CACHE_HOME || join4(homedir(), ".cache");
+  return join4(base || tmpdir(), "nvaid", "update-check.json");
+}
+async function readCache() {
+  try {
+    return JSON.parse(await readFile3(cacheFile(), "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function writeCache(c) {
+  try {
+    const f = cacheFile();
+    await mkdir3(join4(f, ".."), { recursive: true });
+    await writeFile3(f, JSON.stringify(c), "utf8");
+  } catch {
+  }
+}
+async function fetchLatest() {
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+    const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, {
+      signal: ctrl.signal
+    });
+    clearTimeout(timer);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+}
+function isNewer(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10));
+  const pb = b.split(".").map((n) => parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x > y) return true;
+    if (x < y) return false;
+  }
+  return false;
+}
+async function notifyIfOutdated() {
+  if (process.env.NVAID_NO_UPDATE_CHECK) return;
+  const current = await nvaidVersion();
+  const cache = await readCache();
+  const now = Date.now();
+  let latest = null;
+  if (cache && now - cache.lastCheck < CHECK_INTERVAL_MS) {
+    latest = cache.latest;
+  } else {
+    latest = await fetchLatest();
+    if (latest) await writeCache({ lastCheck: now, latest });
+  }
+  if (!latest || !isNewer(latest, current)) return;
+  const line = (s) => process.stderr.write(s + "\n");
+  line("");
+  line(pc4.yellow(`  \u250C\u2500 nvaid update available \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`));
+  line(pc4.yellow("  \u2502 ") + `${pc4.dim(current)} \u2192 ${pc4.green(latest)}`);
+  line(pc4.yellow("  \u2502 ") + `run: ${pc4.cyan(`npm i -g ${PKG}@latest`)}`);
+  line(pc4.yellow("  \u2502 ") + pc4.dim(`then re-sync your repo: nvaid update`));
+  line(pc4.yellow(`  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`));
+}
+
 // src/cli.ts
 var program = new Command();
-program.name("nvaid").description("nvaid \u2014 install an AI-DLC skills + workflow toolkit into any coding agent").version("0.1.0");
+program.name("nvaid").description("nvaid \u2014 install an AI-DLC skills + workflow toolkit into any coding agent").version(await nvaidVersion());
 program.command("init").description("Onboard this repo: select coding agents, inject skills, create the nvaid/ folder").option("--agents <ids>", "comma-separated agent ids (skips the prompt)", (v) => v.split(",")).option("--owning-repo <tier>", "owning_repo value written to config.yml").option("--project-name <name>", "project_name value written to config.yml").option("-y, --yes", "accept defaults, no prompts (CI)").action(async (opts) => {
   await runInit({
     agents: opts.agents,
@@ -468,9 +550,13 @@ program.command("update").description("Re-sync agent files to the installed nvai
   await runUpdate();
 });
 program.command("validate").description("Fail if generated agent files are stale or hand-edited").action(async () => {
-  process.exit(await runValidate());
+  const code = await runValidate();
+  await notifyIfOutdated();
+  process.exit(code);
 });
-program.parseAsync().catch((err) => {
+program.parseAsync().then(async () => {
+  await notifyIfOutdated();
+}).catch((err) => {
   console.error(err instanceof Error ? err.message : err);
   process.exit(1);
 });

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@novare-technologies/nvaid",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "nvaid — one CLI that installs an AI-DLC skills-and-workflow toolkit into any coding agent, and houses intents, config, and the design-code dictionary in a single nvaid/ folder.",
   "type": "module",
   "bin": {
-    "nvaid": "./dist/cli.js"
+    "nvaid": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -39,10 +39,13 @@
     "yaml": "^2.4.0"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^22.0.0",
     "tsup": "^8.0.0",
     "tsx": "^4.7.0",
     "typescript": "^5.4.0",
-    "vitest": "^1.4.0"
+    "vitest": "^5.0.3"
+  },
+  "overrides": {
+    "esbuild": "^0.28.2"
   }
 }

package/templates/commands/apply.md

@@ -7,6 +7,14 @@ precondition: unit-breakdown approved (Decomposition-Approved gate green)
 
 # /nvaid:apply
 
+## ⛔ Precondition: nvaid install must be complete
+
+Read `nvaid/config.yml` and check the `install:` block. If `config`, `project_rules`, or
+`design_code_dictionary` is not `true` (or the file is missing), **STOP** and tell the
+user to run `/nvaid:install` first — name which flag(s) are false. Do not proceed until
+all three are true.
+
+
 Turn an **approved** unit-breakdown into construction-ready work: for each Unit, generate
 its design doc in the Owning Repo named by the breakdown, and open the construction branch
 per the `github` Skill.

package/templates/commands/breakdown.md

@@ -7,6 +7,14 @@ precondition: Contracts drafted (/nvaid:contracts has run)
 
 # /nvaid:breakdown
 
+## ⛔ Precondition: nvaid install must be complete
+
+Read `nvaid/config.yml` and check the `install:` block. If `config`, `project_rules`, or
+`design_code_dictionary` is not `true` (or the file is missing), **STOP** and tell the
+user to run `/nvaid:install` first — name which flag(s) are false. Do not proceed until
+all three are true.
+
+
 Produce `unit-breakdown.md` — the **Phase 5 output**, the decomposition of record,
 informed by the contracts from `/nvaid:contracts`. This runs **after** contracts, not
 before (the `unit-breakdown` Skill is Phase 5; the contract Skills are Phases 2–5).

package/templates/commands/contracts.md

@@ -7,6 +7,14 @@ precondition: Intent approved (Decomposition-Approved gate green)
 
 # /nvaid:contracts
 
+## ⛔ Precondition: nvaid install must be complete
+
+Read `nvaid/config.yml` and check the `install:` block. If `config`, `project_rules`, or
+`design_code_dictionary` is not `true` (or the file is missing), **STOP** and tell the
+user to run `/nvaid:install` first — name which flag(s) are false. Do not proceed until
+all three are true.
+
+
 Draft the Architecture Contracts for an **already-approved** Intent, running each role's
 contract Skill. The contracts are negotiated across Elaboration Phases 2–5 and **precede**
 the unit-breakdown (which is the Phase 5 output) — run `/nvaid:breakdown` after this.

package/templates/commands/install.md

@@ -0,0 +1,63 @@
+---
+command: nvaid:install
+summary: Scan the project and fill in the three required nvaid documents (config.yml, PROJECT-RULES.md, DESIGN-CODE-DICTIONARY.md). Must run before /nvaid:intent.
+stage: "nvaid onboarding — run once, first, before any workflow command"
+blocks: [nvaid:intent, nvaid:contracts, nvaid:breakdown, nvaid:apply]
+---
+
+# /nvaid:install
+
+The **first** command to run after `nvaid init`. `init` only drops empty templates; this
+skill makes nvaid actually usable by scanning the project and authoring the three required
+documents. **Every other nvaid workflow command is blocked until this completes** — running
+`/nvaid:intent` against unfilled templates would produce hollow, confidently-wrong output.
+
+## Why this is a skill, not a CLI step
+
+The CLI can detect facts (languages, frameworks from manifest files) but cannot author
+*judgment*: a project's guardrails, its design patterns, what breaks if a given module
+changes. That requires reading the actual code and reasoning about it — the agent's job,
+not a file-scan's. This skill does that reading. A human reviews before it's marked done
+(propose, don't dispose).
+
+## Steps
+
+1. **Scan the project.** Read manifest files (`package.json`, `pyproject.toml`, `go.mod`,
+   lockfiles), the directory structure, config, CI workflows, and a representative sample
+   of source to understand the stack, the architecture, and the conventions in use.
+
+2. **Fill `nvaid/config.yml`** — replace every `<placeholder>`:
+   - `project_name`, `owning_repo` (frontend | backend | platform | other — infer from the
+     code, confirm with the user if ambiguous).
+   - `tech_stack` — fill from what you actually found in the manifests, not assumptions.
+   - `architects` — these are sign-off identities you cannot infer from code. **Ask the
+     user** for the names; leave a role blank only if the user confirms it doesn't apply.
+   - `context` — the short, always-on constraints worth repeating to every agent.
+
+3. **Author `nvaid/PROJECT-RULES.md`** — replace the template skeleton with real content:
+   the approved stack and what's disallowed without an ADR, non-negotiable constraints,
+   data rules, coding standards, the quality gates CI actually runs, and known gaps.
+   Derive what you can from the code (e.g. the lint/test config that exists); for anything
+   that is a *decision* rather than a fact (what's allowed, what's off-limits), propose it
+   and flag it for the user to confirm — do not invent a guardrail the project hasn't made.
+
+4. **Author `nvaid/DESIGN-CODE-DICTIONARY.md`** — the technical README for the code:
+   the design patterns and conventions in use (with real file examples), and the component
+   map (concept → where it lives → what it depends on → what breaks if changed). This is
+   narrative derived from reading the code; §1 references `config.yml`'s `tech_stack`
+   rather than repeating it. Be honest in the "not yet mapped" section about coverage.
+
+5. **Human review.** Present all three for review. Per propose-don't-dispose, you draft;
+   a human confirms. Do not self-approve.
+
+6. **Flip the gate.** Only after the user confirms each document is genuinely filled (not
+   placeholder text), set the matching flag in `config.yml`'s `install:` block to `true`:
+   `config`, `project_rules`, `design_code_dictionary`. When all three are true, the
+   workflow commands unblock.
+
+## Boundaries
+
+- Facts come from the code; **decisions and sign-off identities come from the user** — ask,
+  don't fabricate.
+- Never set an `install:` flag to `true` on a document that still contains template
+  `<placeholder>` text or that the user hasn't confirmed.

package/templates/commands/intent.md

@@ -6,6 +6,21 @@ stage: "Fig. 2 Stage 1 — Intent captured, pre-Elaboration"
 
 # /nvaid:intent
 
+## ⛔ Precondition: nvaid install must be complete
+
+Before doing anything, read `nvaid/config.yml` and check the `install:` block. If
+`config`, `project_rules`, or `design_code_dictionary` is **not** `true` — or
+`nvaid/config.yml` doesn't exist — **STOP** and tell the user:
+
+> nvaid isn't fully installed in this project yet. Run `/nvaid:install` first — it scans
+> the project and fills in config.yml, PROJECT-RULES.md, and DESIGN-CODE-DICTIONARY.md.
+> Those documents are what this command relies on; drafting an Intent without them would
+> produce hollow output.
+
+Name which flag(s) are false. Do not proceed with any step below until all three are true.
+
+---
+
 Draft a new Intent from the user's description. Produce **only** `intent.md` — the
 business need, who it's for, success criteria, and scope boundaries — then **stop**.
 
@@ -18,9 +33,8 @@ limitation — propose, don't dispose.
 
 ## Steps
 
-1. Read this repo's `nvaid/PROJECT-RULES.md` (if present) for the project's operating
-   guardrails and approved stack. If it is still the unfilled template, proceed but note
-   that the project rules are not yet defined.
+1. Read this repo's `nvaid/PROJECT-RULES.md` for the project's operating guardrails and
+   approved stack (guaranteed authored, since the install gate above has passed).
 2. Write `nvaid/intents/<INTENT-ID>-<slug>/intent.md`: business need, who it's for,
    Intent-level success criteria (observable outcomes, not implementation), scope
    boundaries (name what's out of scope, don't silently drop it), and open questions for

package/templates/nvaid/config.yml

@@ -12,6 +12,19 @@
 
 schema: nvaid/v1
 
+# Installation gate. `nvaid init` scaffolds empty templates; the /nvaid:install SKILL
+# then scans the project and fills in all three required documents. The workflow commands
+# (/nvaid:intent, :contracts, :breakdown, :apply) are BLOCKED until install is complete —
+# running them against unfilled templates would produce hollow, confidently-wrong output.
+#
+# Each flag is set to true by /nvaid:install only once that document is genuinely filled
+# (not left as <placeholder> template text) and a human has confirmed it. The install is
+# "complete" when all three are true.
+install:
+  config: false              # project_name, owning_repo, tech_stack, architects all set
+  project_rules: false       # nvaid/PROJECT-RULES.md authored (not the template skeleton)
+  design_code_dictionary: false  # nvaid/DESIGN-CODE-DICTIONARY.md authored (not the skeleton)
+
 # A short name for this project/repo, used in generated artifact headers
 # (replaces the {{PROJECT_NAME}} placeholder in PROJECT-RULES.md and the dictionary).
 project_name: "<set-me>"
@@ -71,4 +84,4 @@ context: ""
 
 # nvaid version this repo was last generated against. `nvaid validate` compares the
 # installed CLI version to this and flags drift.
-generated_with: "0.1.0"
+generated_with: "0.2.1"