@njeybe/nativ 2.5.1 → 2.7.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 2.7.0
+
+### Added
+
+- **Design profiles.** The Design Profile in `.ai/ui_specs.md` picks `taste-v1` or `taste-v2`. Workers follow the chosen profile's rules before they build UI. Native mobile and terminal UI get no profile and follow only their own spec; an unset profile makes frontend workers escalate.
+- **Bundled taste-skill v1 and v2.** init and update install `.ai/design/taste/` with each version's `SKILL.md` and a short `DIGEST.md` that workers read first. Untouched copies refresh on update. Credit: Leonxlnx, MIT License, pinned at commit `717446e`.
+- **`nativ init --design`.** Choose the design profile when scaffolding a project.
+- **`nativ design check`.** Scans UI files with eight rules for emoji, em and en dashes, `h-screen`, scroll listeners, pure black, Google Fonts links, hand-rolled icons and custom cursors. Exits 1 on errors; warnings never fail. Supports `--profile` and `--json`.
+- **Frontend pre-flight.** The frontend guide runs `nativ design check` on the task's UI files before a worker finishes.
+- **Doctor findings.** `nativ doctor` reports the design profile (`specs:design-profile`) and the bundle (`design:taste-bundle`).
+
+### Changed
+
+- **Studio redesign.** Studio follows the taste-v1 design profile in a monochrome "Ink" direction. It has light and dark themes, and color is used only for status.
+- **New wordmark.** The nativ wordmark replaces the old letter logo and follows the theme.
+- **Phosphor icons.** Studio icons are now Phosphor (MIT). See Third-party notices in the README.
+- **Pulse strip.** A strip under the top bar shows milestone progress and running, blocked and decision counts on every page.
+- **Dispatch button.** The top bar has a "Dispatch `<next task>`" button.
+- **Inspector.** The console drawer is now a right-side inspector. On narrow screens it is a sheet.
+- **Home is a "now" page.** It shows decisions, running tasks, up next, milestone progress and recent activity.
+- **Tasks list.** Tasks defaults to a list grouped by milestone, with filters and a Board toggle.
+- **Team roster.** Team is a roster table.
+- **Worktrees.** Worktree changes open in the inspector.
+- **Restyled pages.** Flow, Benchmarks, Database and dialogs are restyled.
+
+### Removed
+
+- The `nativ` design profile and every nativ-authored design rule. `nativ init --design` and `--profile` accept only `taste-v1` or `taste-v2`; `nativ design check` exits 1 until a profile is set or passed.
+- The Anti-Generic Checklist (Web, Marketing pages, Mobile) from `ui_specs.md`, and the Transitions and Active state lines of its Accessibility section.
+- Frontend guide: Visual style, Anti-generic rules and Build-time details, plus the `nativ` fallback and the style and Marketing pages checks in Before you finish.
+- Flutter guide: Anti-generic rules.
+- Architect guides: the `nativ` profile choice, the Inter typeface rule and the Anti-Generic and Marketing pages checks.
+- Doctor finding `specs:marketing`.
+- `nativ update` does not change an existing project's `.ai/ui_specs.md`, so projects keep their own text. Their frontend workers escalate UI tasks until the architect fills the Design Profile.
+
+## 2.6.0
+
+### Improved: token usage and autonomy
+
+- **Leaner directives.** `AGENTS.md` (-17%), `CLAUDE.md` (-20%) and the worker and verifier agents are shorter. Subagents no longer re-read `AGENTS.md`, which already reaches them through `CLAUDE.md`. The human-communication rules now live in one place.
+- **Compact JSON.** `task next`, `task list` and `triage --json` print single-line JSON. `recommendedContractSlice` is a bare file list.
+- **Brief task list over MCP.** `nativ_task_list` returns a short summary per task; pass `full: true` for every field.
+- **Self-healing ladder.** `AGENTS.md` and `CLAUDE.md` tell agents to retry, patch additively, then run `nativ triage --all --apply --json`; only `REQUIRE_HUMAN_DECISION` items, destructive changes, credentials and repeated failures reach the human.
+- **Resumable sessions.** The SessionStart orientation lists blocked tasks and pending escalations.
+- **Budget guard.** `tests/test-token-budget.mjs` fails when an always-loaded file outgrows its token budget.
+
+### Added
+
+- **Self-healing guide.** `docs/self-healing.md` explains the hands-free loop end to end: claims, the escalation ladder, reclaiming stuck tasks and notifications.
+- **`nativ_validate` MCP tool.** A read-only contract check for MCP hosts that returns only the problems and a verdict, not every passing line.
+- **Notifications when nativ needs you.** A `notify` webhook (Slack, Discord, ntfy, any JSON endpoint) or command in `.nativ/config.json` is called when triage returns `REQUIRE_HUMAN_DECISION` or the circuit breaker blocks a task, once per escalation. Webhooks must be https. `nativ notify test` sends a sample. Failures are recorded, never fatal.
+- **`nativ_triage` MCP tool.** Hosts that only speak MCP can now run the self-healing step: it evaluates pending escalations (or one), applies sandbox-proven additive fixes, and returns the decision card for items a person must decide. The directives and session orientation point to it.
+
+### Fixed
+
+- **Tasks are claimed, not just started.** `task start` refuses a completed or blocked task and one whose dependencies are unfinished, and records `claimedBy` (`--agent` or `NATIV_AGENT_ID`) and `claimedAt`. Another agent cannot start a task with a fresh claim; a claim older than 4 hours can be taken over. Complete and block release the claim. A person can override with `--force`. `nativ_task_start` takes an optional `agent`.
+- **Stuck tasks recover.** `nativ task reclaim` (and `nativ_task_reclaim`) returns `in_progress` tasks with a claim older than 4 hours (`--older-than`) to pending, so a crashed agent no longer leaves a task stuck forever. `--dry-run` reports only. The SessionStart orientation lists stale tasks, and the self-healing ladder covers them.
+- **Provider calls survive network blips.** A network failure or a 5xx answer from Claude API or Gemini is now a `TRANSIENT` error, retried on the same provider twice (about 0.5s and 1s, with jitter) before the chain moves to the next provider. Rejected requests and timeouts are not retried.
+- **Shared JSON files are written safely.** Contract patches, `.nativ/config.json`, task unlocks, provider cooldowns and runner records now go through one atomic writer that retries Windows sharing violations; contract patches no longer fail silently on Windows. Config and unlock changes are read-modify-written under a lock, so parallel writers keep each other's keys, and a config file that does not parse is left untouched instead of being wiped. Studio reports a failed triage-config save instead of claiming success.
+- **Locks wait as long everywhere and leave no empty files.** The plan lock now waits about 5s like the other locks (it gave up after about 0.4s), and locking a file that does not exist no longer creates an empty one that JSON readers cannot parse.
+- **Unknown escalation types are refused.** `nativ task escalate --type` used to turn a typo into `architectural_ambiguity` silently; it now lists the valid types and writes nothing. The CLI and MCP share one list.
+- **`nativ init` writes the architect guide.** It copied a fixed list of eight guides and skipped `architect.md`; it now copies every guide in the templates. `nativ validate` checks the architect guide when present.
+- **Windows paths in `.mcp.json` count as machine-specific on every OS.** A `C:/...` command was treated as portable when setup ran on Linux or macOS.
+- **Continuous integration.** `.github/workflows/ci.yml` builds, checks the plugin sync and runs every suite on Ubuntu (Node 20 and 22) and Windows (Node 22) for pushes to `main` and `dev` and for pull requests. The test runner clears `CI` and the headless overrides for each suite, so tests behave the same on a laptop and in CI.
+- **SQLite on Node 20 explains itself.** SQLite support uses `node:sqlite`, which ships with Node.js 22.5+. On Node 20 the database commands and Studio now say so plainly instead of failing with an unknown-module error. The contract-generator tests no longer depend on `node --test` glob support, which Node 20 lacks.
+- **`npm test` runs every suite.** `tests/run-all.mjs` keeps going after a failure and lists every failed suite at the end.
+
 ## 2.5.1
 
 ### Fixed

package/README.md

@@ -26,6 +26,7 @@ cd your-project && nativ init    # scaffold .ai/ and the Claude Code configurati
 | | [Database](#database) | [Troubleshooting](#troubleshooting) |
 | | [Worktrees](#worktrees) | [For maintainers](#for-maintainers) |
 | | [Studio, tests and benchmarks](#studio-tests-and-benchmarks) | |
+| | | [Design profiles](#design-profiles) |
 
 ---
 
@@ -140,7 +141,8 @@ Every command takes an optional `[targetDir]` (default: the current directory) a
 
 | Command | What it does | Who |
 | :--- | :--- | :--- |
-| [`init`](#nativ-init) | Scaffold `.ai/` and the Claude Code configuration | You |
+| [`init`](#nativ-init) | Scaffold `.ai/` and the Claude Code configuration; `--design` picks a design profile | You |
+| [`design check`](#nativ-design-check) | Scan UI files for design-rule violations | You, Agent |
 | [`setup`](#nativ-setup) | Write or merge the Claude Code configuration | You |
 | [`profile`](#nativ-profile) | Inspect or switch ceremony profile (`prototype`, `solo`, `enterprise`) | You, Agent |
 | [`doctor`](#nativ-doctor) | Check the integration and the harness; `--fix` repairs | You, Agent (read-only) |
@@ -152,6 +154,7 @@ Every command takes an optional `[targetDir]` (default: the current directory) a
 | [`task list`](#nativ-task-list) / `tasks` | List tasks with filters | You, Agent |
 | [`task add`](#nativ-task-add) | Add a task | Architect |
 | [`task start`](#nativ-task-start) | Mark a task in progress | Agent |
+| [`task reclaim`](#nativ-task-reclaim) | Free tasks left in progress by a stopped agent | You, Agent |
 | [`task complete`](#nativ-task-complete) | Complete a task through the gatekeeper | Agent |
 | [`task block`](#nativ-task-block) | Block a task with a reason | Agent |
 | [`task escalate`](#nativ-task-escalate) | Escalate a contract gap to the architect | Agent |
@@ -162,6 +165,7 @@ Every command takes an optional `[targetDir]` (default: the current directory) a
 | [`learn list`](#nativ-learn-list) | List lessons | You, Agent |
 | [`learn approve` / `reject`](#nativ-learn-approve--reject) | Decide on a lesson | *You only* |
 | [`triage`](#nativ-triage) | Evaluate pending escalations; decision cards for you | You |
+| [`notify test`](#nativ-notify-test) | Check the webhook or command that tells you a decision is waiting | You |
 | [`db status` / `inspect` / `diff`](#nativ-db-status--inspect--diff) | Masked, structure-only database checks | You, Agent |
 | [`db sync`](#nativ-db-sync) | Copy a live schema into `.ai/db_schema.json` | *You only* |
 | [`worktree create` / `list` / `merge` / `remove`](#nativ-worktree) | Isolated worktrees for parallel tasks | You, Agent |
@@ -188,6 +192,20 @@ nativ init [targetDir] [-f, --force]
 | Option | Description |
 | :--- | :--- |
 | `-f, --force` | Overwrite existing specification and directive files |
+| `--design <taste-v1|taste-v2>` | Set the design profile in `.ai/ui_specs.md` and install the taste-skill bundle |
+
+#### `nativ design check`
+
+Scan UI source files for design-rule violations. Exits 1 on any error.
+
+```bash
+nativ design check [paths...] [--profile <id>] [--json]
+```
+
+| Option | Description |
+| :--- | :--- |
+| `--profile <id>` | `taste-v1` or `taste-v2`; default is the profile in `.ai/ui_specs.md`. With neither, the command exits 1 |
+| `--json` | Print findings as JSON |
 
 #### `nativ setup`
 
@@ -361,10 +379,18 @@ nativ task add "Appointment list" -a frontend --complexity standard \
 #### `nativ task start`
 
 ```bash
-nativ task start <taskId> [targetDir]
+nativ task start <taskId> [targetDir] [--agent <id>] [--force]
+```
+
+Claims the task, marks it `in_progress` and records the baseline the test-integrity guard compares against. The task must be pending and its dependencies completed; a blocked task goes through `nativ triage` first, and only a person can override with `--force`. The claim records `claimedBy` (`--agent` or `$NATIV_AGENT_ID`) and `claimedAt`, so a parallel agent cannot take a task another agent holds. Running `task start` again on your own task refreshes the claim; a claim older than 4 hours counts as abandoned.
+
+#### `nativ task reclaim`
+
+```bash
+nativ task reclaim [taskId] [targetDir] [--older-than <hours>] [--dry-run] [--json]
 ```
 
-Marks the task `in_progress` and records the baseline the test-integrity guard compares against.
+Puts `in_progress` tasks whose agent stopped (a crash or a closed session) back to `pending`. Without a task id it reclaims every claim older than `--older-than` hours (default 4). Tasks started before claims were recorded have no claim time; name them to reclaim them. A fresh claim is refused unless a person passes `--force`. The SessionStart orientation lists stale tasks. The previous agent may have left partial changes, so review the working tree before restarting.
 
 #### `nativ task complete`
 
@@ -517,7 +543,7 @@ If the lesson changed while you were reviewing it, nothing is decided and you ar
 
 ### Escalations and triage
 
-A worker that finds a contract gap escalates (`nativ task escalate`) and stops. The gap is then resolved by the architect, or first assessed by triage.
+A worker that finds a contract gap escalates (`nativ task escalate`) and stops. The gap is then resolved by the architect, or first assessed by triage. [docs/self-healing.md](docs/self-healing.md) walks through the whole hands-free loop: claims, retries, triage, reclaiming stuck tasks and notifications.
 
 #### `nativ triage`
 
@@ -536,6 +562,16 @@ nativ triage [escalationId] [targetDir] [options]
 
 When an escalation is settled, its resolution notes reach the next worker on that task as `priorEscalations`.
 
+#### `nativ notify test`
+
+nativ can tell you when it needs you: when triage returns `REQUIRE_HUMAN_DECISION`, and when the circuit breaker blocks a task. Each escalation is announced once. Add a webhook (Slack, Discord, ntfy or any JSON endpoint) or a local command to `.nativ/config.json`, which git ignores, so a webhook token stays on your machine:
+
+```json
+{ "notify": { "webhook": "https://hooks.slack.com/services/...", "events": ["human_decision", "circuit_breaker_tripped"] } }
+```
+
+The webhook receives JSON with `text` (Slack, ntfy), `content` (Discord), and the task, escalation, question, options and next step as fields. Webhooks must use `https://` (plain `http://` only to `localhost`). A `"command"` receives the same JSON on stdin and in `NATIV_NOTIFY_JSON`, e.g. `"command": "notify-send nativ \"$(jq -r .text)\""`. `nativ notify test` sends a sample; delivery failures never stop the workflow and are recorded in `.nativ/notify-state.json`.
+
 [Back to contents](#contents)
 
 ---
@@ -636,6 +672,29 @@ Run the MCP server over stdio. `setup` registers it; see [MCP server](#mcp-serve
 
 ---
 
+## Design profiles
+
+nativ can hold web UI work to a design profile. Pick one per web project; it is recorded in the
+Design Profile section of `.ai/ui_specs.md`.
+
+| Profile | Use for |
+| :--- | :--- |
+| `taste-v2` | Landing sites, portfolios, editorial pages and web redesigns |
+| `taste-v1` | Web apps, SaaS screens and dashboards |
+
+Native mobile (Flutter) and terminal UI get no profile. They follow only their own spec.
+
+Set it with `nativ init --design taste-v2` (or `taste-v1`), or let the architect pick one during
+planning. An unset profile is a spec gap: frontend workers escalate, and `nativ design check`
+exits 1 until a profile is set or passed with `--profile`. An architect must pick one. Init and update install the bundle in `.ai/design/taste/`: the
+LICENSE, SOURCE.md, and `v1/` and `v2/` folders, each with `SKILL.md` and a short `DIGEST.md`
+that workers read first. Run `nativ design check` to scan UI files for rule violations.
+
+Credit: the taste-skill prompts are by Leonxlnx, [github.com/Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill),
+MIT License, pinned at commit `717446e`.
+
+---
+
 ## Configuration
 
 ### `.nativ/config.json`
@@ -665,12 +724,15 @@ Written by `setup`; every key is optional.
 | `codeStyle.maxCommentLines` | `2` | Longest allowed comment block |
 | `providers` | see [Providers](#providers) | Provider order per role: `architect`, `pm`, `worker`, `verifier`, `triage` |
 | `models` | provider default | Model per provider |
+| `notify` | off | `webhook`, `command` and `events` for human notifications. See [`nativ notify test`](#nativ-notify-test) |
 
 ### Environment variables
 
 | Variable | Used for |
 | :--- | :--- |
 | `NATIV_ROLE` | Session role; `NATIV_ROLE=architect` lets a whole session write `.ai/` |
+| `NATIV_AGENT_ID` | Who claims a task on `task start`, so parallel agents never take the same task |
+| `NATIV_NOTIFY_WEBHOOK`, `NATIV_NOTIFY_COMMAND` | Override the `notify` webhook or command from `.nativ/config.json` |
 | `ANTHROPIC_API_KEY` | The `claude-api` provider and the Studio native runner |
 | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | The `gemini` provider |
 | `NATIV_DEV_DATABASE_URL`, `DEV_DATABASE_URL`, `DATABASE_URL` | Dev database for `nativ db`, checked in that order, read from your `.env*` files. MongoDB (`MONGODB_URI`) and Firestore variants work too, and names declared in `.env.example` are checked first |
@@ -777,7 +839,9 @@ Files nativ wrote carry a marker, so `update` and `doctor` can tell untouched fi
 | Tools | Purpose |
 | :--- | :--- |
 | `nativ_task_next`, `nativ_task_list`, `nativ_task_add` | Find and add work |
-| `nativ_task_start`, `nativ_task_complete`, `nativ_task_block` | Move a task through its lifecycle (complete always runs the gatekeeper) |
+| `nativ_task_start`, `nativ_task_complete`, `nativ_task_block`, `nativ_task_reclaim` | Move a task through its lifecycle (complete always runs the gatekeeper; reclaim frees stale claims) |
+| `nativ_validate` | Check the `.ai/` contracts, plan and role guides; returns only problems and a verdict |
+| `nativ_triage` | Self-heal: evaluate pending escalations, apply sandbox-proven safe fixes, return decision cards for the rest |
 | `nativ_task_escalate`, `nativ_task_propose_patch` | Escalate a gap or propose a governed patch |
 | `nativ_learn_propose` | Propose a lesson; you approve it in a terminal |
 | `nativ_verify`, `nativ_status`, `nativ_bench`, `nativ_test_gen` | Verification, progress, benchmarks, test generation |
@@ -882,3 +946,34 @@ npm run sync-plugin      # after changing a template or the setup generator; a t
 ## License
 
 MIT (c) JB Natividad. See [LICENSE](LICENSE).
+
+## Third-party notices
+
+- **Phosphor Icons** (`@phosphor-icons/core` 2.1.1) is vendored into Studio under the MIT license:
+
+  ```
+  MIT License
+
+  Copyright (c) 2023 Phosphor Icons
+
+  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.
+  ```
+
+- **taste-skill** by Leonxlnx (MIT). The bundled copy keeps its own LICENSE under
+  `templates/design/taste/`.

package/dist/commands/design-check.d.ts

@@ -0,0 +1,4 @@
+export declare function runDesignCheck(paths: string[] | undefined, options: {
+    profile?: string;
+    json?: boolean;
+}): void;

package/dist/commands/design-check.js

@@ -0,0 +1,76 @@
+import fs from 'fs';
+import path from 'path';
+import { DESIGN_PROFILES, SCAN_EXTENSIONS, checkText, readProfile, } from '../core/design-rules.js';
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.next', '.ai']);
+let jsonMode = false;
+function fail(msg) {
+    if (jsonMode)
+        console.log(JSON.stringify({ error: msg }));
+    else
+        console.error(msg);
+    process.exit(1);
+}
+function isScannable(name) {
+    if (/\.(test|spec)\./.test(name))
+        return false;
+    return SCAN_EXTENSIONS.includes(path.extname(name));
+}
+function collect(target, out) {
+    const stat = fs.statSync(target);
+    if (stat.isFile()) {
+        if (isScannable(path.basename(target)))
+            out.push(target);
+        return;
+    }
+    for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+        if (entry.isDirectory() && SKIP_DIRS.has(entry.name))
+            continue;
+        collect(path.join(target, entry.name), out);
+    }
+}
+function resolveProfile(opt, cwd) {
+    if (opt !== undefined) {
+        if (!DESIGN_PROFILES.includes(opt)) {
+            fail(`Unknown profile "${opt}". Use one of: ${DESIGN_PROFILES.join(', ')}`);
+        }
+        return opt;
+    }
+    const specs = path.join(cwd, '.ai', 'ui_specs.md');
+    const found = fs.existsSync(specs) ? readProfile(fs.readFileSync(specs, 'utf8')) : null;
+    if (found)
+        return found;
+    return fail('No design profile is set. Pass --profile taste-v1|taste-v2, or ask the architect '
+        + 'to fill the Design Profile in .ai/ui_specs.md.');
+}
+export function runDesignCheck(paths, options) {
+    jsonMode = !!options.json;
+    const cwd = process.cwd();
+    const profile = resolveProfile(options.profile, cwd);
+    const files = [];
+    for (const p of paths && paths.length ? paths : ['src']) {
+        const abs = path.resolve(cwd, p);
+        if (!fs.existsSync(abs))
+            fail(`Path not found: ${p}`);
+        collect(abs, files);
+    }
+    const findings = [];
+    for (const abs of files) {
+        const file = path.relative(cwd, abs).split(path.sep).join('/');
+        const text = fs.readFileSync(abs, 'utf8');
+        for (const f of checkText(text, path.extname(abs), profile))
+            findings.push({ file, ...f });
+    }
+    const errors = findings.filter((f) => f.severity === 'error').length;
+    const warnings = findings.length - errors;
+    if (options.json) {
+        const out = { profile, filesScanned: files.length, findings, errors, warnings };
+        console.log(JSON.stringify(out, null, 2));
+    }
+    else {
+        for (const f of findings) {
+            console.log(`${f.file}:${f.line}:${f.column}  ${f.rule}  ${f.message}`);
+        }
+        console.log(`${files.length} files scanned (${profile}): ${errors} errors, ${warnings} warnings`);
+    }
+    process.exit(errors > 0 ? 1 : 0);
+}

package/dist/commands/init.d.ts

@@ -1,3 +1,4 @@
 export declare function runInit(targetDirArg?: string, options?: {
     force?: boolean;
+    design?: string;
 }): Promise<void>;

package/dist/commands/init.js

@@ -1,11 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
 import pc from 'picocolors';
 import { detectProject } from '../scanner/detector.js';
 import { buildContextContent } from '../scanner/context-builder.js';
 import { runSetup, printSetupResult } from './setup.js';
 import { stampManaged } from '../core/setup-assets.js';
+import { DESIGN_PROFILES } from '../core/design-rules.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 function getTemplatesDir() {
@@ -16,7 +18,55 @@ function getTemplatesDir() {
     // Fallback for direct development: src/../templates
     return path.resolve(__dirname, '../templates');
 }
+// Sets the Profile line, and the Digest line for taste profiles, in the ui_specs template.
+function applyDesignProfile(spec, profile) {
+    let out = spec.replace(/^(- \*\*Profile:\*\*).*$/m, `$1 ${profile}`);
+    if (profile.startsWith('taste-')) {
+        const digest = `.ai/design/taste/${profile.slice('taste-'.length)}/DIGEST.md`;
+        out = out.replace(/^(- \*\*Digest:\*\*).*$/m, `$1 ${digest}`);
+    }
+    return out;
+}
+function listBundle(dir, base = dir, out = []) {
+    if (!fs.existsSync(dir))
+        return out;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory())
+            listBundle(full, base, out);
+        else
+            out.push(path.relative(base, full));
+    }
+    return out;
+}
+function installTasteBundle(templatesDir, aiDir, force) {
+    const src = path.join(templatesDir, 'design', 'taste');
+    const manifestPath = path.join(aiDir, 'design', 'taste', '.manifest.json');
+    let manifest = {};
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch { /* none yet */ }
+    for (const rel of listBundle(src)) {
+        const dest = path.join(aiDir, 'design', 'taste', rel);
+        if (fs.existsSync(dest) && !force)
+            continue;
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(path.join(src, rel), dest);
+        const text = fs.readFileSync(dest, 'utf8').replace(/\r/g, '');
+        manifest[rel.split(path.sep).join('/')] = createHash('sha256').update(text).digest('hex');
+    }
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+    console.log(pc.green('✔ Installed design bundle .ai/design/taste/'));
+}
 export async function runInit(targetDirArg, options = {}) {
+    if (options.design !== undefined && !DESIGN_PROFILES.includes(options.design)) {
+        const list = DESIGN_PROFILES.join(', ');
+        console.error(pc.red(`✖ Unknown design profile "${options.design}". Use one of: ${list}`));
+        process.exitCode = 1;
+        return;
+    }
     const targetDir = path.resolve(targetDirArg || process.cwd());
     const templatesDir = getTemplatesDir();
     console.log(pc.bold(pc.cyan('\nNativ: Initializing Multi-Tier Pipeline...')));
@@ -81,9 +131,11 @@ export async function runInit(targetDirArg, options = {}) {
     const uiTemplate = fs.readFileSync(path.join(templatesDir, 'dot-ai/ui_specs.md'), 'utf8');
     const uiPath = path.join(aiDir, 'ui_specs.md');
     if (!fs.existsSync(uiPath) || options.force) {
-        fs.writeFileSync(uiPath, uiTemplate, 'utf8');
+        const uiContent = options.design ? applyDesignProfile(uiTemplate, options.design) : uiTemplate;
+        fs.writeFileSync(uiPath, uiContent, 'utf8');
         console.log(pc.green('✔ Created .ai/ui_specs.md'));
     }
+    installTasteBundle(templatesDir, aiDir, options.force);
     // 7. Write .ai/master_plan.json
     const planTemplate = fs.readFileSync(path.join(templatesDir, 'dot-ai/master_plan.json'), 'utf8');
     const planContent = planTemplate
@@ -96,16 +148,8 @@ export async function runInit(targetDirArg, options = {}) {
         console.log(pc.green('✔ Created .ai/master_plan.json'));
     }
     // 7. Write Sub-agent specifications
-    const subagentFiles = [
-        'backend.md',
-        'frontend.md',
-        'database.md',
-        'qa-tester.md',
-        'flutter-developer.md',
-        'devops-agent.md',
-        'security-auditor.md',
-        'db-migration.md',
-    ];
+    const guidesDir = path.join(templatesDir, 'dot-ai/subagents');
+    const subagentFiles = fs.existsSync(guidesDir) ? fs.readdirSync(guidesDir).filter((f) => f.endsWith('.md')).sort() : [];
     for (const file of subagentFiles) {
         const src = path.join(templatesDir, 'dot-ai/subagents', file);
         const dest = path.join(subagentsDir, file);

package/dist/commands/notify.d.ts

@@ -0,0 +1,2 @@
+/** `nativ notify test`: sends a sample notification so a person can check the webhook or command works. */
+export declare function runNotifyTest(targetDirArg?: string): Promise<void>;

package/dist/commands/notify.js

@@ -0,0 +1,25 @@
+import pc from 'picocolors';
+import { resolveProjectRoot } from '../core/root-resolver.js';
+import { loadNotifyConfig, notifyHuman } from '../core/notify.js';
+/** `nativ notify test`: sends a sample notification so a person can check the webhook or command works. */
+export async function runNotifyTest(targetDirArg) {
+    const root = resolveProjectRoot(targetDirArg);
+    const config = loadNotifyConfig(root);
+    if (!config) {
+        console.log(pc.yellow('\nNotifications are off. Add to .nativ/config.json:'));
+        console.log(pc.white('  { "notify": { "webhook": "https://hooks.slack.com/services/..." } }'));
+        console.log(pc.dim('  or "command": "notify-send nativ \\"$(jq -r .text)\\"", or set NATIV_NOTIFY_WEBHOOK / NATIV_NOTIFY_COMMAND.\n'));
+        process.exitCode = 1;
+        return;
+    }
+    const result = await notifyHuman(root, { event: config.events[0], taskId: 'task-test', summary: 'This is a test notification from `nativ notify test`', question: 'Did it arrive?', options: ['Yes', 'No'] }, { force: true });
+    for (const e of result.errors)
+        console.error(pc.red(`✖ ${e}`));
+    if (result.sent) {
+        const via = [config.webhook && 'webhook', config.command && 'command'].filter(Boolean).join(' and ');
+        console.log(pc.green(`\n✔ Test notification sent via ${via}. Events: ${config.events.join(', ')}.\n`));
+    }
+    else {
+        process.exitCode = 1;
+    }
+}

package/dist/commands/session.d.ts

@@ -0,0 +1,22 @@
+import { SessionCheckpoint, SessionSummaryEntry } from '../core/session-memory.js';
+export interface SessionSaveOptions {
+    summary: string;
+    decision?: string[];
+    obstacle?: string[];
+    next?: string[];
+    activeFiles?: string;
+    task?: string;
+    role?: string;
+    sessionId?: string;
+    json?: boolean;
+}
+export interface SessionListOptions {
+    limit?: number;
+    json?: boolean;
+}
+export interface SessionGetOptions {
+    json?: boolean;
+}
+export declare function runSessionSave(targetDirArg?: string, options?: SessionSaveOptions): Promise<SessionCheckpoint>;
+export declare function runSessionList(targetDirArg?: string, options?: SessionListOptions): Promise<SessionSummaryEntry[]>;
+export declare function runSessionGet(sessionId?: string, targetDirArg?: string, options?: SessionGetOptions): Promise<SessionCheckpoint | null>;

package/dist/commands/session.js

@@ -0,0 +1,106 @@
+import path from 'node:path';
+import pc from 'picocolors';
+import { saveSessionCheckpoint, getLatestSession, getSession, listSessions, } from '../core/session-memory.js';
+export async function runSessionSave(targetDirArg, options = { summary: '' }) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    const files = options.activeFiles
+        ? options.activeFiles.split(',').map((f) => f.trim()).filter(Boolean)
+        : undefined;
+    const checkpoint = saveSessionCheckpoint(targetDir, {
+        sessionId: options.sessionId,
+        summary: options.summary,
+        decisions: options.decision,
+        obstacles: options.obstacle,
+        nextSteps: options.next,
+        activeFiles: files,
+        taskId: options.task,
+        role: options.role,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(checkpoint, null, 2));
+        return checkpoint;
+    }
+    console.log(pc.bold(pc.green(`\n✔ Saved Session Checkpoint: `)) + pc.yellow(`[${checkpoint.sessionId}]`));
+    console.log(pc.bold('  Summary:    ') + pc.white(checkpoint.summary));
+    if (checkpoint.taskId) {
+        console.log(pc.bold('  Task:       ') + pc.yellow(checkpoint.taskId));
+    }
+    if (checkpoint.role) {
+        console.log(pc.bold('  Role:       ') + pc.magenta(checkpoint.role));
+    }
+    if (checkpoint.decisions && checkpoint.decisions.length > 0) {
+        console.log(pc.bold('  Decisions:  ') + pc.dim(checkpoint.decisions.join(' | ')));
+    }
+    if (checkpoint.obstacles && checkpoint.obstacles.length > 0) {
+        console.log(pc.bold('  Obstacles:  ') + pc.red(checkpoint.obstacles.join(' | ')));
+    }
+    if (checkpoint.nextSteps && checkpoint.nextSteps.length > 0) {
+        console.log(pc.bold('  Next Steps: ') + pc.cyan(checkpoint.nextSteps.join(' | ')));
+    }
+    if (checkpoint.activeFiles && checkpoint.activeFiles.length > 0) {
+        console.log(pc.bold('  Files:      ') + pc.dim(checkpoint.activeFiles.join(', ')));
+    }
+    console.log();
+    return checkpoint;
+}
+export async function runSessionList(targetDirArg, options = {}) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    const sessions = listSessions(targetDir, options.limit || 10);
+    if (options.json) {
+        console.log(JSON.stringify(sessions, null, 2));
+        return sessions;
+    }
+    console.log(pc.bold(pc.cyan('\nSession Memory Checkpoints (.ai/memory/sessions/)')));
+    console.log(pc.dim(`Workspace: ${targetDir}\n`));
+    if (sessions.length === 0) {
+        console.log(pc.dim('  No saved sessions found.\n'));
+        console.log(pc.dim('  Save current progress with: ') + pc.white('nativ session save --summary "..."\n'));
+        return sessions;
+    }
+    for (const s of sessions) {
+        const roleTag = s.role ? pc.magenta(`[${s.role}] `) : '';
+        const taskTag = s.taskId ? pc.yellow(`[${s.taskId}] `) : '';
+        console.log(`  ${pc.bold(pc.yellow(s.sessionId))} ${pc.dim(s.timestamp)} ${roleTag}${taskTag}\n    ${pc.white(s.summary)}`);
+    }
+    console.log();
+    return sessions;
+}
+export async function runSessionGet(sessionId, targetDirArg, options = {}) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    const session = sessionId ? getSession(targetDir, sessionId) : getLatestSession(targetDir);
+    if (options.json) {
+        console.log(JSON.stringify(session, null, 2));
+        return session;
+    }
+    if (!session) {
+        console.log(pc.yellow(`\nNo session found${sessionId ? ` matching [${sessionId}]` : ''}.\n`));
+        return null;
+    }
+    console.log(pc.bold(pc.cyan(`\nSession Details: `)) + pc.yellow(`[${session.sessionId}]`));
+    console.log(pc.bold('  Timestamp:  ') + pc.dim(session.timestamp));
+    if (session.taskId)
+        console.log(pc.bold('  Task ID:    ') + pc.yellow(session.taskId));
+    if (session.role)
+        console.log(pc.bold('  Role:       ') + pc.magenta(session.role));
+    console.log(pc.bold('  Summary:    ') + pc.white(session.summary));
+    if (session.decisions && session.decisions.length > 0) {
+        console.log(pc.bold('\n  Key Decisions:'));
+        for (const d of session.decisions)
+            console.log(pc.dim('   • ') + pc.white(d));
+    }
+    if (session.obstacles && session.obstacles.length > 0) {
+        console.log(pc.bold('\n  Obstacles / Blockers:'));
+        for (const o of session.obstacles)
+            console.log(pc.red('   ✖ ') + pc.white(o));
+    }
+    if (session.nextSteps && session.nextSteps.length > 0) {
+        console.log(pc.bold('\n  Next Steps:'));
+        for (const n of session.nextSteps)
+            console.log(pc.cyan('   → ') + pc.white(n));
+    }
+    if (session.activeFiles && session.activeFiles.length > 0) {
+        console.log(pc.bold('\n  Active Files: ') + pc.dim(session.activeFiles.join(', ')));
+    }
+    console.log();
+    return session;
+}

package/dist/commands/task/task-add.js

@@ -148,7 +148,7 @@ export async function runTaskAdd(title, targetDirArg, options = {}) {
             plan.overallStatus = 'in_progress';
         const result = { task, milestoneId: milestone.id, milestoneName: milestone.name, createdMilestone, reopenedMilestone };
         if (options.json) {
-            console.log(JSON.stringify(result, null, 2));
+            console.log(JSON.stringify(result));
             return result;
         }
         const track = fastPath ? pc.magenta(' [fast path]') : '';