@nathapp/nax 0.18.1

package/docs/v0.10-global-config.md

@@ -0,0 +1,206 @@
+# v0.10 — Global + Project Config Layering
+
+**Status:** Draft  
+**Author:** Subrina  
+**Date:** 2026-03-03  
+**Base:** v0.9.3  
+**Issue:** #14  
+
+## Overview
+
+Introduce a global `~/.nax/` directory for user-wide defaults. Project-level `nax/` overrides global via deep merge. Hooks concatenate (global fires first, then project).
+
+## Motivation
+
+- Users repeat the same config across projects (model mappings, cost limits, hooks)
+- No way to set personal defaults without copy-pasting `nax/config.json`
+- Notification hooks (Telegram, Slack) are user-level, not project-level
+- Constitution rules often have a universal component ("always strict TypeScript") plus project-specific additions
+
+## Directory Structure
+
+```
+~/.nax/                          # Global (user-wide)
+  config.json                    # Global defaults
+  constitution.md                # Global coding standards
+  hooks/
+    on-complete.sh               # Fires after every run
+    on-error.sh                  # Fires on story failure
+    on-pause.sh                  # Fires when story pauses
+    on-start.sh                  # Fires when run starts
+
+<project>/nax/                   # Project (existing, unchanged)
+  config.json                    # Project overrides
+  constitution.md                # Project-specific rules
+  hooks/
+    on-complete.sh               # Project-specific hooks
+  features/
+    <feature>/prd.json
+```
+
+## Merge Strategy
+
+### Config: Deep Merge (project wins)
+
+```
+global config.json    +    project config.json    =    effective config
+─────────────────          ────────────────────         ────────────────
+{                          {                            {
+  "models": {                "models": {                  "models": {
+    "fast": "haiku",           "fast": "flash"              "fast": "flash",    ← project wins
+    "balanced": "sonnet",                                   "balanced": "sonnet", ← from global
+    "powerful": "opus"                                      "powerful": "opus"    ← from global
+  },                         },                           },
+  "execution": {             "execution": {               "execution": {
+    "costLimit": 5.0,          "costLimit": 2.0             "costLimit": 2.0,   ← project wins
+    "sessionTimeout": 600                                   "sessionTimeout": 600 ← from global
+  }                          }                            }
+}                          }                            }
+```
+
+Rules:
+- Objects are recursively merged; project values override global at the leaf level
+- Arrays are **replaced** (not concatenated) — e.g., `escalation.tierOrder` from project fully replaces global
+- `null` in project explicitly removes a global key
+- Missing sections in project inherit from global as-is
+
+### Hooks: Concatenate (global first, then project)
+
+```
+Effective hook execution order:
+  1. ~/.nax/hooks/on-complete.sh    (if exists)
+  2. <project>/nax/hooks/on-complete.sh  (if exists)
+```
+
+- Both fire independently — global hook failure does NOT block project hook
+- Each hook receives the same environment variables (run metadata, exit code, cost, etc.)
+- To skip global hooks for a project, set `"hooks": { "skipGlobal": true }` in project config
+
+### Constitution: Concatenate (global first, then project)
+
+```
+Effective constitution:
+  1. ~/.nax/constitution.md content
+  2. ---
+  3. <project>/nax/constitution.md content
+```
+
+- Global constitution prepended to project constitution with `---` separator
+- To skip global constitution, set `"constitution": { "skipGlobal": true }` in project config
+
+## Config Resolution Order
+
+```
+1. Built-in defaults (hardcoded in schema.ts)
+2. ~/.nax/config.json (global)
+3. <project>/nax/config.json (project)
+4. CLI flags (--cost-limit, --model, etc.) — highest priority
+```
+
+## Global Config Scope
+
+All existing config sections are valid at global level:
+
+| Section | Global Use Case |
+|:--------|:----------------|
+| `models` | Default model mappings (your API keys, preferred providers) |
+| `autoMode` | Default complexity→tier routing and escalation budgets |
+| `routing` | Preferred routing strategy (llm vs keyword) |
+| `execution` | Default cost limit, session timeout, verification timeout |
+| `quality` | Default stripEnvVars, forceExit |
+| `tdd` | Default session tiers, testWriterAllowedPaths |
+| `constitution` | Path (always relative to `~/.nax/`) |
+| `context` | Default test coverage detail level and token budget |
+| `acceptance` | Default enabled/disabled |
+| `hooks` | Global hook directory path |
+| `analyze` | Default LLM-enhanced analysis settings |
+
+## New Config Fields
+
+```typescript
+// Added to NaxConfig (or a new GlobalConfig extending it)
+interface HooksConfig {
+  /** Skip global hooks for this project */
+  skipGlobal?: boolean;
+  /** Hook directory path (default: "hooks/" relative to config dir) */
+  dir?: string;
+}
+
+interface ConstitutionConfig {
+  /** Path to constitution file (relative to config dir) */
+  path?: string;
+  /** Skip global constitution for this project */
+  skipGlobal?: boolean;
+}
+```
+
+## Implementation
+
+### File Structure
+
+```
+src/config/
+  schema.ts             # Add HooksConfig, ConstitutionConfig schemas
+  loader.ts             # Modify: load global → project → merge
+  merger.ts             # NEW: deep merge logic with concatenation rules
+  paths.ts              # NEW: resolve ~/.nax/ and project nax/ paths
+```
+
+### Key Functions
+
+```typescript
+// paths.ts
+export function globalConfigDir(): string;    // ~/.nax/
+export function projectConfigDir(): string;   // <cwd>/nax/
+
+// merger.ts
+export function mergeConfigs(global: Partial<NaxConfig>, project: Partial<NaxConfig>): NaxConfig;
+
+// loader.ts (modified)
+export async function loadConfig(options?: { projectDir?: string }): Promise<NaxConfig> {
+  const defaults = getDefaults();
+  const global = await loadConfigFile(globalConfigDir());
+  const project = await loadConfigFile(projectConfigDir(options?.projectDir));
+  return mergeConfigs(defaults, mergeConfigs(global, project));
+}
+```
+
+### `nax init --global`
+
+New flag to initialize `~/.nax/`:
+
+```bash
+nax init --global
+# Creates:
+#   ~/.nax/config.json (with commented examples)
+#   ~/.nax/constitution.md (empty template)
+#   ~/.nax/hooks/ (empty directory)
+```
+
+Existing `nax init` (without `--global`) continues to initialize project-level `nax/`.
+
+## User Stories
+
+| # | Title | Complexity | Est. LOC | Dependencies |
+|:--|:------|:-----------|:---------|:-------------|
+| US-001 | Config paths resolver (`~/.nax/` + project `nax/`) | simple | 40 | — |
+| US-002 | Deep merge utility with array-replace and null-remove semantics | simple | 60 | — |
+| US-003 | Update `loadConfig()` to load global → project → merge | medium | 80 | US-001, US-002 |
+| US-004 | Hook concatenation (global + project, independent execution) | medium | 100 | US-001, US-003 |
+| US-005 | Constitution concatenation with `skipGlobal` support | simple | 50 | US-001, US-003 |
+| US-006 | `nax init --global` command | simple | 60 | US-001 |
+| US-007 | Update Zod schema for HooksConfig and ConstitutionConfig | simple | 40 | — |
+
+## Design Decisions
+
+1. **Deep merge over section replace** — more intuitive; users only override what they change
+2. **Hooks concatenate, arrays replace** — hooks are additive (notification + CI); config arrays like `tierOrder` are intentional overrides
+3. **`skipGlobal` opt-out** — simple boolean rather than complex inheritance rules
+4. **Global first in concatenation** — global rules are "baseline", project adds specifics
+5. **`null` removes keys** — explicit opt-out mechanism for global defaults you don't want in a specific project
+6. **CLI flags beat everything** — one-off overrides without touching files
+7. **No `nax config show`** — defer to v0.11; users can check effective config via `nax prompts` audit
+
+---
+
+*Draft — pending William's review.*

package/docs/v0.10-plugin-system.md

@@ -0,0 +1,415 @@
+# v0.10 — Plugin System
+
+**Status:** Draft  
+**Author:** Subrina  
+**Date:** 2026-03-03  
+**Base:** v0.9.3  
+**Issue:** #14 (bundled with global config)  
+
+## Overview
+
+A lightweight plugin system that lets developers extend nax with custom optimizers, routing strategies, review checks, context providers, reporters, and agent adapters. Plugins are plain JS/TS modules that export a `NaxPlugin` object.
+
+## Motivation
+
+- Prompt optimization, routing, and review are already extensible in concept but hardcoded in practice
+- Users want to integrate external tools (LLMLingua, Jira, security scanners) without forking nax
+- nax has well-defined interfaces (`RoutingStrategy`, `AgentAdapter`, `ReviewConfig`) — plugins just need a standard way to register implementations
+- Global plugins (in `~/.nax/plugins/`) apply to all projects; project plugins override or add
+
+## Plugin Interface
+
+```typescript
+// src/plugins/types.ts
+
+/**
+ * Extension point types that plugins can provide.
+ */
+export type PluginType =
+  | "optimizer"
+  | "router"
+  | "agent"
+  | "reviewer"
+  | "context-provider"
+  | "reporter";
+
+/**
+ * A nax plugin module.
+ *
+ * Plugins export a single NaxPlugin object (default or named export).
+ * Each plugin declares which extension points it provides and supplies
+ * the corresponding implementations.
+ */
+export interface NaxPlugin {
+  /** Unique plugin name (e.g., "jira-context", "llmlingua-optimizer") */
+  name: string;
+
+  /** Plugin version (semver) */
+  version: string;
+
+  /** Which extension points this plugin provides */
+  provides: PluginType[];
+
+  /**
+   * Called once when plugin is loaded. Use for initialization,
+   * validating config, establishing connections, etc.
+   *
+   * @param config - Plugin-specific config from nax config.json
+   */
+  setup?(config: Record<string, unknown>): Promise<void>;
+
+  /**
+   * Called when the nax run ends (success or failure).
+   * Use for cleanup, closing connections, flushing buffers.
+   */
+  teardown?(): Promise<void>;
+
+  /**
+   * Extension implementations. Only the types listed in `provides`
+   * are required; others are ignored.
+   */
+  extensions: PluginExtensions;
+}
+
+export interface PluginExtensions {
+  /** Custom prompt optimizer */
+  optimizer?: IPromptOptimizer;
+
+  /** Custom routing strategy (inserted into the strategy chain) */
+  router?: RoutingStrategy;
+
+  /** Custom agent adapter (e.g., Codex, Gemini, Aider) */
+  agent?: AgentAdapter;
+
+  /** Custom review check (runs alongside built-in typecheck/lint/test) */
+  reviewer?: IReviewPlugin;
+
+  /** Custom context provider (injects external context into prompts) */
+  contextProvider?: IContextProvider;
+
+  /** Custom reporter (receives run events for dashboards, CI, etc.) */
+  reporter?: IReporter;
+}
+```
+
+## Extension Point Interfaces
+
+### IPromptOptimizer (existing from optimizer spec)
+
+```typescript
+// src/optimizer/types.ts (from v0.10-prompt-optimizer.md)
+export interface IPromptOptimizer {
+  name: string;
+  optimize(input: PromptOptimizerInput): Promise<PromptOptimizerResult>;
+}
+```
+
+### RoutingStrategy (existing)
+
+```typescript
+// src/routing/strategy.ts (already exists in v0.9.3)
+export interface RoutingStrategy {
+  readonly name: string;
+  route(story: UserStory, context: RoutingContext): RoutingDecision | null | Promise<RoutingDecision | null>;
+}
+```
+
+Plugin routers are inserted into the strategy chain **before** the built-in strategies. If a plugin router returns `null`, the chain continues to keyword/LLM/adaptive as normal.
+
+### AgentAdapter (existing)
+
+```typescript
+// src/agents/types.ts (already exists in v0.9.3)
+export interface AgentAdapter {
+  readonly name: string;
+  readonly displayName: string;
+  readonly binary: string;
+  readonly capabilities: AgentCapabilities;
+  isInstalled(): Promise<boolean>;
+  run(options: AgentRunOptions): Promise<AgentResult>;
+  buildCommand(options: AgentRunOptions): string[];
+  plan(options: PlanOptions): Promise<PlanResult>;
+  decompose(options: DecomposeOptions): Promise<DecomposeResult>;
+  runInteractive?(options: InteractiveRunOptions): PtyHandle;
+}
+```
+
+### IReviewPlugin (new)
+
+```typescript
+// src/plugins/types.ts
+export interface IReviewPlugin {
+  /** Check name (e.g., "security-scan", "license-check") */
+  name: string;
+
+  /** Human-readable description */
+  description: string;
+
+  /**
+   * Run the review check against the working directory.
+   *
+   * @param workdir - Project root directory
+   * @param changedFiles - Files modified by the agent in this story
+   * @returns Review check result
+   */
+  check(workdir: string, changedFiles: string[]): Promise<ReviewCheckResult>;
+}
+```
+
+Review plugins run **after** built-in checks (typecheck, lint, test). A plugin check failure follows the same escalation/retry logic as built-in failures.
+
+### IContextProvider (new)
+
+```typescript
+// src/plugins/types.ts
+export interface IContextProvider {
+  /** Provider name (e.g., "jira", "linear", "confluence") */
+  name: string;
+
+  /**
+   * Fetch external context relevant to a story.
+   *
+   * @param story - The user story being executed
+   * @param config - Plugin-specific config
+   * @returns Markdown content to inject into the agent prompt
+   */
+  getContext(story: UserStory): Promise<ContextProviderResult>;
+}
+
+export interface ContextProviderResult {
+  /** Markdown content to inject */
+  content: string;
+  /** Token estimate for budget tracking */
+  estimatedTokens: number;
+  /** Section label in the prompt (e.g., "Jira Context") */
+  label: string;
+}
+```
+
+Context provider output is appended to the built context **after** the context stage, within the remaining token budget. If the budget is exceeded, provider content is truncated with a warning.
+
+### IReporter (new)
+
+```typescript
+// src/plugins/types.ts
+export interface IReporter {
+  /** Reporter name */
+  name: string;
+
+  /** Called when a run starts */
+  onRunStart?(run: RunStartEvent): Promise<void>;
+
+  /** Called when a story completes (success or failure) */
+  onStoryComplete?(event: StoryCompleteEvent): Promise<void>;
+
+  /** Called when a run ends */
+  onRunEnd?(run: RunEndEvent): Promise<void>;
+}
+
+export interface RunStartEvent {
+  runId: string;
+  feature: string;
+  totalStories: number;
+  startTime: string;
+}
+
+export interface StoryCompleteEvent {
+  runId: string;
+  storyId: string;
+  status: "completed" | "failed" | "skipped" | "paused";
+  durationMs: number;
+  cost: number;
+  tier: string;
+  testStrategy: string;
+}
+
+export interface RunEndEvent {
+  runId: string;
+  totalDurationMs: number;
+  totalCost: number;
+  storySummary: {
+    completed: number;
+    failed: number;
+    skipped: number;
+    paused: number;
+  };
+}
+```
+
+Reporter methods are fire-and-forget — failures are logged but never block the pipeline.
+
+## Plugin Loading
+
+### Resolution Order
+
+```
+1. ~/.nax/plugins/*     (global plugins — apply to all projects)
+2. nax/plugins/*        (project plugins — override or add)
+3. config.json plugins  (explicit module paths)
+```
+
+### Config
+
+```json
+{
+  "plugins": [
+    {
+      "module": "./nax/plugins/my-security-scanner",
+      "config": { "severity": "high" }
+    },
+    {
+      "module": "@nathapp/nax-plugin-jira",
+      "config": { "baseUrl": "https://jira.example.com", "project": "NAX" }
+    },
+    {
+      "module": "~/custom-optimizer",
+      "config": {}
+    }
+  ]
+}
+```
+
+### Directory Convention
+
+Plugins in `~/.nax/plugins/` or `nax/plugins/` are auto-discovered (no config entry needed):
+
+```
+~/.nax/plugins/
+  telegram-reporter/
+    index.ts          # exports NaxPlugin
+    package.json      # optional, for dependencies
+  security-scan.ts    # single-file plugin
+```
+
+### Loader Logic
+
+```typescript
+// src/plugins/loader.ts
+
+/**
+ * Load and validate all plugins from global + project + config sources.
+ *
+ * 1. Scan ~/.nax/plugins/ (if exists)
+ * 2. Scan <project>/nax/plugins/ (if exists)
+ * 3. Load explicit modules from config.plugins[]
+ * 4. Validate each: must export name (string), version (string),
+ *    provides (PluginType[]), and matching extensions
+ * 5. Call setup() on each with its config
+ * 6. Return PluginRegistry
+ */
+export async function loadPlugins(
+  globalDir: string,
+  projectDir: string,
+  configPlugins: PluginConfigEntry[]
+): Promise<PluginRegistry>;
+```
+
+### Plugin Registry
+
+```typescript
+// src/plugins/registry.ts
+
+export class PluginRegistry {
+  /** All loaded plugins */
+  readonly plugins: ReadonlyArray<NaxPlugin>;
+
+  /** Get all optimizers (built-in + plugin) */
+  getOptimizers(): IPromptOptimizer[];
+
+  /** Get all routing strategies (plugin strategies, inserted before built-in) */
+  getRouters(): RoutingStrategy[];
+
+  /** Get agent adapter by name */
+  getAgent(name: string): AgentAdapter | undefined;
+
+  /** Get all review plugins */
+  getReviewers(): IReviewPlugin[];
+
+  /** Get all context providers */
+  getContextProviders(): IContextProvider[];
+
+  /** Get all reporters */
+  getReporters(): IReporter[];
+
+  /** Teardown all plugins */
+  async teardownAll(): Promise<void>;
+}
+```
+
+The registry is created once at run start and passed through the pipeline context.
+
+## Pipeline Integration
+
+```typescript
+// PipelineContext additions
+export interface PipelineContext {
+  // ... existing fields ...
+
+  /** Plugin registry (set by runner before pipeline starts) */
+  plugins?: PluginRegistry;
+}
+```
+
+### Where Plugins Hook In
+
+| Stage | Plugin Type | Integration |
+|:------|:-----------|:------------|
+| `routing` | `router` | Plugin strategies prepended to strategy chain |
+| `context` | `context-provider` | Provider content appended after built context |
+| `optimizer` (new) | `optimizer` | Plugin optimizer replaces or chains with built-in |
+| `execution` | `agent` | Plugin agent selected by `config.agent` name |
+| `review` | `reviewer` | Plugin checks run after built-in checks |
+| Pipeline runner | `reporter` | Events fired at run start, story complete, run end |
+
+## Conflict Resolution
+
+| Scenario | Behavior |
+|:---------|:---------|
+| Multiple optimizers | Only the **last** loaded optimizer is active (project overrides global). Log warning if multiple found. |
+| Multiple routers | All router plugins are chained (in load order, before built-in). First non-null decision wins. |
+| Multiple agents | All registered. Config `agent` field selects which one to use. Default: `claude-code`. |
+| Multiple reviewers | All run (additive). Each produces independent results. |
+| Multiple context providers | All run (additive). Combined output subject to token budget. |
+| Multiple reporters | All run (additive). Independent, fire-and-forget. |
+| Plugin name collision | Last loaded wins (project overrides global). Log warning. |
+
+## File Structure
+
+```
+src/plugins/
+  types.ts              # NaxPlugin, PluginType, extension interfaces
+  loader.ts             # loadPlugins() — discover, import, validate
+  registry.ts           # PluginRegistry class
+  validator.ts          # validatePlugin() — runtime type checks
+  index.ts              # Public API exports
+```
+
+## User Stories
+
+| # | Title | Complexity | Est. LOC | Dependencies |
+|:--|:------|:-----------|:---------|:-------------|
+| US-001 | Define NaxPlugin interface and all extension point types | simple | 120 | — |
+| US-002 | Plugin loader (directory scan + config modules + validation) | medium | 150 | US-001 |
+| US-003 | PluginRegistry with typed getters and teardown | medium | 100 | US-001 |
+| US-004 | Integrate plugin routers into routing strategy chain | simple | 50 | US-003 |
+| US-005 | Integrate plugin reviewers into review stage | simple | 50 | US-003 |
+| US-006 | Integrate context providers into context stage | medium | 80 | US-003 |
+| US-007 | Reporter event emission from pipeline runner | medium | 80 | US-003 |
+| US-008 | Add PluginRegistry to PipelineContext + runner initialization | simple | 40 | US-002, US-003 |
+| US-009 | `nax plugins list` CLI command (show loaded plugins) | simple | 50 | US-002 |
+
+## Design Decisions
+
+1. **Plain module exports over class registration** — plugins are just objects with a known shape. No decorators, no base classes, no framework lock-in.
+2. **Auto-discovery + explicit config** — directory convention for convenience, config entries for control. Both work together.
+3. **Last-loaded-wins for singular types** (optimizer, agent) — keeps it simple. No complex priority systems.
+4. **Additive for plural types** (reviewer, reporter, context-provider, router) — more plugins = more capability.
+5. **Fire-and-forget reporters** — never block the pipeline for reporting failures.
+6. **Reuse existing interfaces** — `RoutingStrategy` and `AgentAdapter` already exist. Plugins just provide new implementations via the same contracts.
+7. **Plugin config in nax config.json** — no separate plugin config files. Each plugin gets a `config` object passed to `setup()`.
+8. **No hot-reload** — plugins are loaded once at run start. Restart to pick up changes.
+9. **v0.10 implements loader + registry + optimizer integration** — other extension point integrations (router, reviewer, context, reporter) are wired but implementations are community-driven.
+
+---
+
+*Draft — pending William's review.*