nikos 0.1.0 → 0.2.0

package/README.md

@@ -38,10 +38,29 @@ scenario, with every command and the output you should see.
 | Claude Code | `/plugin install nikos --marketplace nikovijay/NikOS` |
 | Codex | `codex plugin marketplace add nikovijay/NikOS` |
 | Cursor | Add `https://github.com/nikovijay/NikOS` as a plugin marketplace |
+| Claude Desktop, or any app that runs MCP servers | `npx -y nikos mcp --dir <repo>` as a local MCP server: see [docs/install.md](docs/install.md#any-app-that-runs-mcp-servers) |
 
-Then ask your agent to plan or build a story: the `nikos-mode` skill takes it
-from there. The skills run the `nikos` command through `npx`, so there's
-nothing else to install. More in [docs/install.md](docs/install.md).
+Then talk to your agent: the `nikos-mode` skill takes it from there. The
+skills run the `nikos` command through `npx`, so there's nothing else to
+install. More in [docs/install.md](docs/install.md).
+
+## Talk to it
+
+You don't need to learn the commands. Your agent runs them and, after each
+request, says where things stand and offers a short menu of what to do next.
+Things you can say:
+
+- "Set up nikOS here", or "Map what this repo already does"
+- "Set nikOS up for our company" (a company plan every team joins)
+- "What should we build next?"
+- "Add a story: people can share a list with one other person"
+- "Build HT-3"
+- "Is release 1 ready to ship?"
+- "Show me the story map"
+
+When a story is done, your agent asks "Do you want to approve HT-3: Reorder
+tasks?". Your answer is the sign-off. It's recorded in
+`intent/approvals.yaml`, and your agent never approves on its own.
 
 ## The loop
 
@@ -54,8 +73,9 @@ npx -y nikos verify TC-1              # run the story: it fails until it's built
 npx -y nikos state set TC-1 done      # refused unless its scenarios pass
 ```
 
-With an agent, you only write the request ("add a story for X and build
-it"); the playbooks run these steps and stop at each point that needs you.
+That's what runs underneath. With an agent, you only make the request ("add
+a story for X and build it"); the playbooks run these steps and stop at each
+point that needs you.
 
 ## What lives in your repo
 
@@ -63,7 +83,9 @@ it"); the playbooks run these steps and stop at each point that needs you.
 intent/
 ├── constitution.md      who it's for, the problem, what proves it works
 ├── storymap.yaml        activities and steps, releases, and the order to build stories in
-├── state.yaml           each story's status: todo, in_progress, needs_rework, done
+├── state.yaml           each story's status: todo, in_progress, needs_rework, done, cancelled
+├── approvals.yaml       people's sign-offs on done stories (optional)
+│                        (or state/<ID>.yaml and approvals/<ID>.yaml, one per story)
 ├── decisions.md         why things are the way they are, append-only
 ├── features/            one .feature file per story; its scenarios are the criteria
 │   └── <activity>/<story>.feature
@@ -71,28 +93,42 @@ intent/
 ```
 
 Every file is plain text you can read, review and diff. The full format:
-[docs/format.md](docs/format.md). A worked example:
+[docs/format.md](docs/format.md). Tools that work with these files without a
+shell can use nikOS as a library: [docs/library.md](docs/library.md). A worked example:
 [examples/hello-todo](examples/hello-todo/intent).
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
+| `nikos start` | Set this repo up in one go: `intent/`, a scenario runner for its stack and CI for its host |
 | `nikos init` | Create `intent/` in this repo |
+| `nikos company init` | Write a company plan repo that departments and teams join ([docs/settings.md](docs/settings.md)) |
+| `nikos activity add "<title>"` | Add an activity to the story map |
 | `nikos validate` | Check `intent/` is well formed |
 | `nikos story add "<title>"` | Add a story to the map, state and a starter feature |
 | `nikos step add "<title>"` | Add a step under an activity |
-| `nikos release add\|rename\|move\|reorder` | Define releases and move stories between them, keeping feature tags in step |
+| `nikos release add\|rename\|move\|reorder\|remove` | Define releases and move stories between them, keeping feature tags in step |
+| `nikos release check <n>` | Say whether a release is ready to ship, and what's in the way |
 | `nikos clear <id>` | Check a story is ready to build |
 | `nikos plan new <id>` | Start the next version of a story's plan |
 | `nikos verify setup` | Add a Cucumber runner for this repo's stack |
+| `nikos ci setup` | Run validate and every story's scenarios on each PR (GitHub Actions) or merge request (GitLab CI) |
 | `nikos verify [id]` | Run a story's scenarios, or all of them |
-| `nikos state set <id> <status>` | Move a story; done only if its scenarios pass |
+| `nikos state set <id> <status>` | Move a story; done only if its scenarios pass; cancelled needs a reason |
+| `nikos approve <id>...` | Sign off done stories, in your terminal or (`--via chat`) by answering your agent (writes `intent/approvals.yaml`) |
 | `nikos next` | Print the next story to build |
+| `nikos migrate per-story` | Give each story its own state and approval file, so parallel branches never conflict |
+| `nikos suggest` | Where things stand, and a short menu of what to do next |
+| `nikos join <repo>` | Plan against a company or department plan and inherit its settings ([docs/settings.md](docs/settings.md)) |
+| `nikos settings` | The settings that apply here, and where each comes from |
+| `nikos doctor` | Check the repo is set up well, and what to do next |
+| `nikos tracker link\|record\|sync\|import` | Keep the story map and Jira, Linear, GitHub or GitLab issues in step, through the tracker's MCP |
 | `nikos show <id>` | Summarise a story: feature, status, plan, bets, decisions |
 | `nikos decide "<title>"` | Append a decision to `decisions.md` |
 | `nikos decisions "<q>"` | Quote the decisions about a topic or story |
 | `nikos map` | Write a read-only story map page |
+| `nikos export --format prd\|linear\|jira` | Write the story map as a PRD or a Linear or Jira import |
 
 ## Links
 

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -1,19 +1,30 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import { runValidate } from "./commands/validate.js";
 import { runPlan } from "./commands/plan.js";
 import { runInit } from "./commands/init.js";
 import { runClear } from "./commands/clear.js";
 import { runVerify } from "./commands/verify.js";
+import { runCi } from "./commands/ci.js";
 import { runNext } from "./commands/next.js";
 import { runState } from "./commands/state.js";
+import { runApprove } from "./commands/approve.js";
+import { runSuggest } from "./commands/suggest.js";
+import { runMcp } from "./mcp/server.js";
+import { runJoin, runSettings } from "./commands/join.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runMigrate } from "./commands/migrate.js";
+import { runTracker } from "./commands/tracker.js";
+import { runCompany, runStart } from "./commands/start.js";
 import { runDecide } from "./commands/decide.js";
 import { runShow } from "./commands/show.js";
 import { runDecisions } from "./commands/decisions.js";
 import { runStory } from "./commands/story.js";
-import { runStep } from "./commands/step.js";
+import { runActivity, runStep } from "./commands/step.js";
 import { runRelease } from "./commands/release.js";
 import { runVideo } from "./commands/video.js";
 import { runMap } from "./commands/map.js";
+import { runExport } from "./commands/export.js";
 import { runPlanning } from "./planning/cli.js";
 const commands = {
     init: runInit,
@@ -21,16 +32,29 @@ const commands = {
     plan: runPlan,
     clear: runClear,
     verify: runVerify,
+    ci: runCi,
     next: runNext,
     state: runState,
+    approve: runApprove,
+    suggest: runSuggest,
+    mcp: runMcp,
+    join: runJoin,
+    settings: runSettings,
+    doctor: runDoctor,
+    migrate: runMigrate,
+    tracker: runTracker,
+    start: runStart,
+    company: runCompany,
     decide: runDecide,
     show: runShow,
     decisions: runDecisions,
     story: runStory,
     step: runStep,
+    activity: runActivity,
     release: runRelease,
     video: runVideo,
     map: runMap,
+    export: runExport,
     planning: runPlanning,
 };
 const help = `nikos — spec-driven development for AI coding agents
@@ -38,31 +62,59 @@ const help = `nikos — spec-driven development for AI coding agents
 Usage: nikos <command> [options]
 
 Commands:
+  start            Set this repo up in one go: intent/, a scenario runner for its stack
+                   and CI for its host, each only if it's missing (--name, --key)
   init             Create intent/ in this repo (--name, --key)
   validate [dir]   Check the intent/ folder is well formed
   story add "<title>"  Add a story to the map, state and a starter feature
                    (--activity, --step, --release, --priority)
+  activity add "<title>"  Add an activity to the story map (--id)
   step add "<title>"   Add a step under an activity (--activity, --id)
   release add "<title>"  Add the next release (--goal)
   release rename <n>   Change a release's title or goal (--goal)
   release move <id> <n>  Move a story to another release, retagging its feature
   release reorder <n> <pos>  Move a release and renumber them all
+  release remove <n>   Remove an empty release and renumber the rest
+  release check <n>    Is a release ready to ship? (--run reruns its scenarios)
   plan new <id>    Start the next version of a story's plan
   clear <id>       Check a story is Lean and Executable before building
   verify setup     Set up a Cucumber runner for this repo's stack
   verify [id]      Run a story's scenarios (or all of them)
+  ci setup         Run validate and every story's scenarios on each PR or merge
+                   request (GitHub Actions or GitLab CI; --github, --gitlab)
   show <id>        Summarise a story: feature, status, plan, bets, decisions
   decisions "<q>"  Quote the decisions.md entries that mention a topic or story
   next             Print the next story to build
   state set <id> <status>  Move a story; done only if its scenarios pass
+                   (cancelled needs --reason)
+  approve <id>...  Sign off done stories: in your terminal, or --via chat when
+                   you've answered an agent's "Do you want to approve …?"
+  suggest          What to do next: where things stand and a short menu (--json, --brief)
+  company init     Write a company plan repo that departments and teams join
+                   (--name, --period, --departments, --repo, --host)
+  join <repo>      Plan against a company or department plan, and inherit its settings
+                   (--host gitlab.com, --url, --ref)
+  settings [set <key> <value>]  See the settings that apply here and where each comes
+                   from, or change one this repo is allowed to
+  doctor           Check this repo is set up well, and say what to do next (--offline)
+  migrate per-story  Give each story its own state and approval file, so parallel
+                   branches never conflict (migrate single-file goes back)
+  tracker link|record|sync|import  Keep the story map and a Jira, Linear, GitHub or GitLab
+                   tracker in step; the agent reads tickets through the tracker's MCP
+  mcp              Run nikOS as a local MCP server for Claude Desktop, Cursor, Codex and
+                   other apps (--dir <repo>)
   decide "<title>" Append a decision to decisions.md
                    (--why, --story, --category, --supersedes)
   video            Draft a video brief and storyboard from the done stories
                    (--out, default marketing/storymap-video)
   map              Write a read-only story map page (--out, default storymap.html)
+  export --format <prd|linear|jira>  The story map as a PRD or tracker import
+                   (--release, --out, --project-key)
   planning <cmd>   Bets, key results and the planning dashboard (nikos-planning pack;
                    run \`nikos planning help\`)
 
+  --version        Print the installed version
+
 Docs: https://nikos.tools`;
 async function main(argv) {
     const [cmd, ...rest] = argv;
@@ -70,6 +122,10 @@ async function main(argv) {
         console.log(help);
         return 0;
     }
+    if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+        console.log(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version);
+        return 0;
+    }
     const run = commands[cmd];
     if (!run) {
         console.error(`Unknown command '${cmd}'.\n\n${help}`);

package/dist/commands/approve.d.ts

@@ -0,0 +1,16 @@
+/** Who is approving: git's user.name, or the login name when git has none. */
+export declare function approver(dir: string): string;
+export interface ApproveResult {
+    story: string;
+    by: string;
+    on: string;
+}
+/** Check a story can be approved, rerun its scenarios, then record the approval. The terminal check lives in runApprove. */
+export type Via = "terminal" | "chat" | "app" | "tracker";
+export declare function approve(story: string, opts: {
+    dir?: string;
+    by: string;
+    date?: string;
+    via?: Via;
+}): ApproveResult;
+export declare function runApprove(args: string[]): Promise<number>;

package/dist/commands/approve.js

@@ -0,0 +1,120 @@
+// `nikos approve`: a person's sign-off on a done story, written to intent/approvals.yaml
+// (or intent/approvals/<ID>.yaml). Two
+// ways in, recorded as `via`:
+// - terminal: the person runs it and types the story id back. A coding agent runs commands
+//   without a terminal, so it can't take this route.
+// - chat: the agent asked "Do you want to approve …?" and the person answered Approve. The
+//   playbooks only allow it after that answer; `via: chat` shows it was given that way.
+// - app: nikos mcp asked the person through their app (MCP elicitation), so the model never
+//   saw the question or gave the answer.
+// - tracker: a person moved the story's ticket to a status mapped to approved (nikos tracker
+//   record), when tracker.approvals is on.
+// A repo can go further and protect approvals.yaml with CODEOWNERS, so every approval also
+// needs a review on GitHub or GitLab.
+// The approval holds while the story stays done, since the same done, with the same feature.
+import { spawnSync } from "node:child_process";
+import { userInfo } from "node:os";
+import { dirname } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { approvalLapse, doneMark, loadApprovals } from "../lib/approvals.js";
+import { noEntry, storyState, writeApproval } from "../lib/state-files.js";
+import { resolveSettings } from "../lib/settings.js";
+import { STORY_ID, findIntentDir, read, specHash } from "../lib/project.js";
+import { featureFor } from "./clear.js";
+import { StateError, failingScenarios } from "./state.js";
+import { verify } from "./verify.js";
+/** Who is approving: git's user.name, or the login name when git has none. */
+export function approver(dir) {
+    const git = spawnSync("git", ["config", "user.name"], { cwd: dir, encoding: "utf8" });
+    return git.stdout?.trim() || userInfo().username;
+}
+export function approve(story, opts) {
+    if (!STORY_ID.test(story))
+        throw new StateError(`'${story}' is not a story id (expected e.g. HT-1)`);
+    const intentDir = findIntentDir(opts.dir ?? process.cwd());
+    const settings = resolveSettings(dirname(intentDir));
+    const policy = settings["approval.policy"];
+    if (policy.value === "off")
+        throw new StateError(`Approvals are off here (approval.policy, set by ${policy.from})`);
+    const via = opts.via ?? "terminal";
+    const routes = settings["approval.routes"];
+    // A tracker approval counts when tracker.approvals is on; the other routes by approval.routes.
+    if (via === "tracker" && !settings["tracker.approvals"].value)
+        throw new StateError("Tracker approvals don't count here (tracker.approvals is off)");
+    if (via !== "tracker" && !routes.value.includes(via)) {
+        throw new StateError(`Approvals ${via === "app" ? "through the app" : via === "chat" ? "in chat" : "in a terminal"} don't count here: approval.routes is ${routes.value.join(", ")} (set by ${routes.from})`);
+    }
+    const entry = storyState(intentDir, story);
+    if (!entry)
+        throw new StateError(noEntry(intentDir, story));
+    if (entry.status !== "done")
+        throw new StateError(`${story} is ${entry.status}: only a done story can be approved`);
+    const feature = featureFor(story, dirname(intentDir));
+    const hash = feature ? specHash(read(feature)) : undefined;
+    if (!hash)
+        throw new StateError(`No feature file is tagged @${story}`);
+    if (entry.spec_hash && entry.spec_hash !== hash) {
+        throw new StateError(`${story}'s feature changed after it was done. Move it to needs_rework and through done again before approving`);
+    }
+    const existing = loadApprovals(intentDir)[story];
+    if (existing && !approvalLapse(existing, entry, hash))
+        throw new StateError(`${story} is already approved (by ${existing.by} on ${existing.on})`);
+    let run;
+    try {
+        run = verify(dirname(intentDir), story);
+    }
+    catch (err) {
+        throw new StateError(`${story} isn't approved: its scenarios couldn't run. ${err.message}`);
+    }
+    if (run.status !== 0) {
+        const failing = failingScenarios(run.output);
+        throw new StateError(`${story} isn't approved: its scenarios don't all pass${failing.length ? `:\n${failing.map((f) => `  ✗ ${f}`).join("\n")}` : ". See the runner output."}`);
+    }
+    const on = opts.date ?? new Date().toISOString().slice(0, 10);
+    writeApproval(intentDir, story, { by: opts.by, on, via, spec_hash: hash, done_at: doneMark(entry) });
+    return { story, by: opts.by, on };
+}
+export async function runApprove(args) {
+    const flag = (n) => {
+        const i = args.indexOf(`--${n}`);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const stories = args.filter((a, i) => !a.startsWith("--") && !(i > 0 && args[i - 1].startsWith("--")));
+    const dir = flag("dir") ?? process.cwd();
+    const via = flag("via") ?? "terminal";
+    if (!stories.length || (via !== "terminal" && via !== "chat")) {
+        console.error("Usage: nikos approve <story-id>... [--via chat] [--dir <path>]");
+        return 1;
+    }
+    const by = approver(dir);
+    if (via === "terminal") {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            console.error("✗ nikos approve only runs in an interactive terminal. In a chat with an agent, the agent asks \"Do you want to approve …?\" and records your answer with --via chat.");
+            return 1;
+        }
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            const want = stories.join(" ");
+            const typed = (await rl.question(`Approving ${want} as ${by}. Scenarios run again first.\nType ${want} to approve: `)).trim();
+            if (typed !== want) {
+                console.error("✗ Not approved: that wasn't the story id.");
+                return 1;
+            }
+        }
+        finally {
+            rl.close();
+        }
+    }
+    let failed = 0;
+    for (const story of stories) {
+        try {
+            approve(story, { dir, by, via });
+            console.log(`${story}: approved by ${by}${via === "chat" ? " in chat" : ""} (intent/approvals.yaml)`);
+        }
+        catch (err) {
+            console.error(`✗ ${err.message}`);
+            failed++;
+        }
+    }
+    return failed ? 1 : 0;
+}

package/dist/commands/ci.d.ts

@@ -0,0 +1,18 @@
+import { type Stack } from "../verify/detect.js";
+export type Host = "github" | "gitlab";
+/** github or gitlab, from the origin remote's url; undefined when it's neither or there's no remote. */
+export declare function detectHost(root: string): Host | undefined;
+export declare function githubWorkflow(stack: Stack, root: string): string;
+export declare function gitlabJob(stack: Stack, root: string): string;
+export interface CiResult {
+    host: Host;
+    created: string[];
+    skipped: string[];
+    /** Something the person (or their agent) still has to do by hand. */
+    todo?: string;
+}
+/** Write the pipeline for the repo's host and stack. Never overwrites a file. */
+export declare function setupCi(root: string, opts?: {
+    host?: Host;
+}): CiResult;
+export declare function runCi(args: string[]): number;

package/dist/commands/ci.js

@@ -0,0 +1,123 @@
+// `nikos ci setup`: run nikOS's checks on every pull request (GitHub) or merge request (GitLab).
+// The pipeline runs `nikos validate` and every story's scenarios with `nikos verify`, using the
+// nikos version that wrote it, so a red pipeline means the specs or the code broke, not nikos.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { detectStack } from "../verify/detect.js";
+const here = dirname(fileURLToPath(import.meta.url));
+const version = () => {
+    const pkg = [join(here, "../../package.json"), join(here, "../package.json")].find((p) => existsSync(p));
+    return JSON.parse(readFileSync(pkg, "utf8")).version;
+};
+/** github or gitlab, from the origin remote's url; undefined when it's neither or there's no remote. */
+export function detectHost(root) {
+    const url = spawnSync("git", ["remote", "get-url", "origin"], { cwd: root, encoding: "utf8" }).stdout?.trim() ?? "";
+    if (/github\.com[:/]/.test(url))
+        return "github";
+    if (/gitlab/i.test(url))
+        return "gitlab";
+    return undefined;
+}
+/** The shell steps that install the runner and run the checks, for a stack. */
+function steps(stack, root, nikos) {
+    const install = stack === "python"
+        ? [existsSync(join(root, "requirements.txt")) ? "pip install -r requirements.txt" : "", "pip install behave"].filter(Boolean)
+        : [existsSync(join(root, "package-lock.json")) ? "npm ci" : "npm install"];
+    return [...install, `npx -y ${nikos} validate`, `npx -y ${nikos} verify`];
+}
+export function githubWorkflow(stack, root) {
+    const nikos = `nikos@${version()}`;
+    const python = stack === "python" ? `      - uses: actions/setup-python@v5\n        with:\n          python-version: "3.12"\n` : "";
+    return `# Written by nikos ci setup: checks the specs in intent/ and runs every story's scenarios.
+name: nikos
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  nikos:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+${python}${steps(stack, root, nikos).map((s) => `      - run: ${s}`).join("\n")}
+`;
+}
+export function gitlabJob(stack, root) {
+    const nikos = `nikos@${version()}`;
+    // Python stories need node for nikos itself, so that image installs it.
+    const image = stack === "python" ? "python:3.12" : "node:22";
+    const setup = stack === "python" ? ["apt-get update -qq && apt-get install -y -qq nodejs npm"] : [];
+    return `# Written by nikos ci setup: checks the specs in intent/ and runs every story's scenarios.
+nikos:
+  image: ${image}
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  script:
+${[...setup, ...steps(stack, root, nikos)].map((s) => `    - ${s}`).join("\n")}
+`;
+}
+const GITLAB_JOB = ".gitlab/ci/nikos.yml";
+const INCLUDE = `include:\n  - local: ${GITLAB_JOB}\n`;
+/** Write the pipeline for the repo's host and stack. Never overwrites a file. */
+export function setupCi(root, opts = {}) {
+    const host = opts.host ?? detectHost(root);
+    if (!host)
+        throw new Error("Couldn't tell where this repo is hosted from its origin remote. Say which: --github or --gitlab");
+    const stack = detectStack(root);
+    if (!stack)
+        throw new Error("Couldn't tell the stack: no package.json, pyproject.toml or requirements.txt. Run nikos verify setup first.");
+    const created = [];
+    const skipped = [];
+    const write = (rel, text) => {
+        const path = join(root, rel);
+        if (existsSync(path))
+            return void skipped.push(rel);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, text);
+        created.push(rel);
+    };
+    if (host === "github") {
+        write(".github/workflows/nikos.yml", githubWorkflow(stack, root));
+        return { host, created, skipped };
+    }
+    // GitLab reads one .gitlab-ci.yml, so the job lives in its own file and is included from it.
+    write(GITLAB_JOB, gitlabJob(stack, root));
+    const main = join(root, ".gitlab-ci.yml");
+    if (!existsSync(main)) {
+        write(".gitlab-ci.yml", INCLUDE);
+        return { host, created, skipped };
+    }
+    const included = readFileSync(main, "utf8").includes(GITLAB_JOB);
+    return { host, created, skipped, todo: included ? undefined : `Add this to .gitlab-ci.yml:\n${INCLUDE}` };
+}
+export function runCi(args) {
+    const [sub, ...rest] = args;
+    if (sub !== "setup") {
+        console.error("Usage: nikos ci setup [--github | --gitlab] [--dir <path>]");
+        return 1;
+    }
+    const i = rest.indexOf("--dir");
+    const root = i >= 0 ? rest[i + 1] : process.cwd();
+    const host = rest.includes("--github") ? "github" : rest.includes("--gitlab") ? "gitlab" : undefined;
+    try {
+        const r = setupCi(root, { host });
+        if (r.created.length)
+            console.log(`Created:\n${r.created.map((f) => `  + ${f}`).join("\n")}`);
+        if (r.skipped.length)
+            console.log(`Skipped (already there):\n${r.skipped.map((f) => `  = ${f}`).join("\n")}`);
+        if (r.todo)
+            console.log(`\n${r.todo}`);
+        console.log(`\nEvery ${r.host === "github" ? "pull request" : "merge request"} now runs nikos validate and every story's scenarios.`);
+        return 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/commands/clear.d.ts

@@ -0,0 +1,14 @@
+export type CheckName = "Clear" | "Lean" | "Executable" | "Accurate" | "Responsible";
+export interface CheckResult {
+    check: CheckName;
+    /** `agent` means the check needs judgement, so the CLEAR skill decides it. */
+    status: "pass" | "fail" | "agent";
+    message: string;
+    fix?: string;
+}
+/** Run CLEAR's mechanical checks (Lean, Executable) on a feature file and report all five checks. */
+export declare function clear(text: string): CheckResult[];
+export declare function formatClear(results: CheckResult[]): string;
+/** Find the feature file that carries a story id. */
+export declare function featureFor(story: string, dir: string): string | undefined;
+export declare function runClear(args: string[]): number;

package/dist/commands/decide.d.ts

@@ -0,0 +1,11 @@
+export interface DecisionInput {
+    title: string;
+    why: string;
+    story?: string;
+    category?: string;
+    supersedes?: string;
+    date?: string;
+}
+/** Append a dated entry to decisions.md. Earlier entries are never touched. */
+export declare function decide(input: DecisionInput, dir: string): string;
+export declare function runDecide(args: string[]): number;

package/dist/commands/decide.js

@@ -1,4 +1,4 @@
-import { appendFileSync, existsSync } from "node:fs";
+import { store } from "../lib/store.js";
 import { join } from "node:path";
 import { STORY_ID, findIntentDir, read } from "../lib/project.js";
 import { formatResult, validate } from "./validate.js";
@@ -16,7 +16,7 @@ export function decide(input, dir) {
     if (!CATEGORIES.includes(category))
         throw new Error(`Category must be one of ${CATEGORIES.join(", ")}`);
     const path = join(findIntentDir(dir), "decisions.md");
-    if (!existsSync(path))
+    if (!store().exists(path))
         throw new Error("No intent/decisions.md. Run `nikos init` first.");
     const date = input.date ?? new Date().toISOString().slice(0, 10);
     const entry = [
@@ -29,7 +29,7 @@ export function decide(input, dir) {
     ].join("\n");
     const existing = read(path);
     const gap = existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
-    appendFileSync(path, gap + entry);
+    store().append(path, gap + entry);
     return entry;
 }
 export function runDecide(args) {

package/dist/commands/decisions.d.ts

@@ -0,0 +1,14 @@
+export interface DecisionEntry {
+    /** First and last line of the entry in decisions.md, 1-based. */
+    start: number;
+    end: number;
+    title: string;
+    text: string;
+}
+/** Every "## " entry in decisions.md, with its line range. HTML comments are skipped. */
+export declare function decisionEntries(dir: string): DecisionEntry[];
+export declare function queryTerms(query: string): string[];
+/** Entries that mention the query, best match first. Entries matching under half as many terms as the best are dropped. */
+export declare function findDecisions(query: string, dir: string): DecisionEntry[];
+export declare function formatDecisions(query: string, found: DecisionEntry[]): string;
+export declare function runDecisions(args: string[]): number;

package/dist/commands/decisions.js

@@ -1,11 +1,11 @@
-import { existsSync } from "node:fs";
+import { store } from "../lib/store.js";
 import { join } from "node:path";
 import { findIntentDir, read } from "../lib/project.js";
 const STOP = new Set(["the", "and", "for", "why", "did", "was", "were", "are", "you", "how", "what", "with", "this", "that", "not", "use", "using", "instead", "of", "we", "our", "decide", "decided", "choose", "chose", "rather", "than"]);
 /** Every "## " entry in decisions.md, with its line range. HTML comments are skipped. */
 export function decisionEntries(dir) {
     const path = join(findIntentDir(dir), "decisions.md");
-    if (!existsSync(path))
+    if (!store().exists(path))
         return [];
     const lines = read(path).split("\n");
     const entries = [];

package/dist/commands/doctor.d.ts

@@ -0,0 +1,11 @@
+export interface Check {
+    name: string;
+    status: "ok" | "warn" | "fail";
+    found: string;
+    /** What to do about it, when it isn't ok. */
+    next?: string;
+}
+export declare function doctor(root: string, opts?: {
+    offline?: boolean;
+}): Check[];
+export declare function runDoctor(args: string[]): number;