@nathapp/nax 0.23.0 → 0.25.0

package/bin/nax.ts

@@ -62,6 +62,7 @@ import { generateCommand } from "../src/cli/generate";
 import { diagnose } from "../src/commands/diagnose";
 import { logsCommand } from "../src/commands/logs";
 import { precheckCommand } from "../src/commands/precheck";
+import { runsCommand } from "../src/commands/runs";
 import { unlockCommand } from "../src/commands/unlock";
 import { DEFAULT_CONFIG, findProjectDir, loadConfig, validateDirectory } from "../src/config";
 import { run } from "../src/execution";
@@ -685,7 +686,7 @@ program
   .option("-s, --story <id>", "Filter to specific story")
   .option("--level <level>", "Filter by log level (debug|info|warn|error)")
   .option("-l, --list", "List all runs in table format", false)
-  .option("-r, --run <timestamp>", "Select specific run by timestamp")
+  .option("-r, --run <runId>", "Select run by run ID from central registry (global)")
   .option("-j, --json", "Output raw JSONL", false)
   .action(async (options) => {
     let workdir: string;
@@ -773,7 +774,24 @@ program
   });
 
 // ── runs ─────────────────────────────────────────────
-const runs = program.command("runs").description("Manage and view run history");
+const runs = program
+  .command("runs")
+  .description("Show all registered runs from the central registry (~/.nax/runs/)")
+  .option("--project <name>", "Filter by project name")
+  .option("--last <N>", "Limit to N most recent runs (default: 20)")
+  .option("--status <status>", "Filter by status (running|completed|failed|crashed)")
+  .action(async (options) => {
+    try {
+      await runsCommand({
+        project: options.project,
+        last: options.last !== undefined ? Number.parseInt(options.last, 10) : undefined,
+        status: options.status,
+      });
+    } catch (err) {
+      console.error(chalk.red(`Error: ${(err as Error).message}`));
+      process.exit(1);
+    }
+  });
 
 runs
   .command("list")

package/docs/ROADMAP.md

@@ -118,34 +118,50 @@
 
 ---
 
-## v0.23.0 — Status File Consolidation
+## v0.23.0 — Status File Consolidation ✅
 
 **Theme:** Auto-write status.json to well-known paths, align readers, remove dead options
-**Status:** 🔄 In Progress (self-dev running, SFC-001 ✅)
+**Status:** ✅ Shipped (2026-03-07)
 **Spec:** [docs/specs/status-file-consolidation.md](specs/status-file-consolidation.md)
 **Pre-requisite for:** v0.24.0 (Central Run Registry)
 
 ### Stories
 - [x] ~~**SFC-001:** Auto-write project-level status — remove `--status-file` flag, always write to `<workdir>/nax/status.json`~~
-- [ ] **BUG-043:** Fix scoped test command construction + add `testScoped` config with `{{files}}` template
-- [ ] **BUG-044:** Log scoped and full-suite test commands at info level in verify stage
-- [ ] **SFC-002:** Write feature-level status on run end — copy final snapshot to `<workdir>/nax/features/<feature>/status.json`
-- [ ] **SFC-003:** Align status readers — `nax status` + `nax diagnose` read from correct paths
-- [ ] **SFC-004:** Clean up dead code — remove `--status-file` option, `.nax-status.json` references
+- [x] ~~**BUG-043:** Fix scoped test command construction + add `testScoped` config with `{{files}}` template~~
+- [x] ~~**BUG-044:** Log scoped and full-suite test commands at info level in verify stage~~
+- [x] ~~**SFC-002:** Write feature-level status on run end — copy final snapshot to `<workdir>/nax/features/<feature>/status.json`~~
+- [x] ~~**SFC-003:** Align status readers — `nax status` + `nax diagnose` read from correct paths~~
+- [x] ~~**SFC-004:** Clean up dead code — remove `--status-file` option, `.nax-status.json` references~~
 
 ---
 
-## v0.24.0 — Central Run Registry
+## v0.25.0 — Trigger Completion
 
-**Theme:** Global run index across all projects — single source of truth for all nax run history
+**Theme:** Wire all 8 unwired interaction triggers, 3 missing hook events, and add plugin integration tests
 **Status:** 🔲 Planned
+**Spec:** [docs/specs/trigger-completion.md](specs/trigger-completion.md)
+
+### Stories
+- [ ] **TC-001:** Wire `cost-exceeded` + `cost-warning` triggers — fire at 80%/100% of cost limit in sequential-executor.ts
+- [ ] **TC-002:** Wire `max-retries` trigger — fire on permanent story failure via `story:failed` event in wireInteraction
+- [ ] **TC-003:** Wire `security-review`, `merge-conflict`, `pre-merge` triggers — review rejection, git conflict detection, pre-completion gate
+- [ ] **TC-004:** Wire `story-ambiguity` + `review-gate` triggers — ambiguity keyword detection, per-story human checkpoint
+- [ ] **TC-005:** Wire missing hook events — `on-resume`, `on-session-end`, `on-error` to pipeline events
+- [ ] **TC-006:** Auto plugin + Telegram + Webhook integration tests — mock LLM/network, cover approve/reject/HMAC flows
+
+---
+
+## v0.24.0 — Central Run Registry ✅
+
+**Theme:** Global run index across all projects — single source of truth for all nax run history
+**Status:** ✅ Shipped (2026-03-07)
 **Spec:** [docs/specs/central-run-registry.md](specs/central-run-registry.md)
 
 ### Stories
-- [ ] **CRR-000:** `src/pipeline/subscribers/events-writer.ts` — `wireEventsWriter()`, writes lifecycle events to `~/.nax/events/<project>/events.jsonl` (machine-readable completion signal for watchdog/CI)
-- [ ] **CRR-001:** `src/pipeline/subscribers/registry.ts` — `wireRegistry()` subscriber, listens to `run:started`, writes `~/.nax/runs/<project>-<feature>-<runId>/meta.json` (path pointers only — no data duplication, no symlinks)
-- [ ] **CRR-002:** `src/commands/runs.ts` — `nax runs` CLI, reads `meta.json` → resolves live `status.json` from `statusPath`, displays table (project, feature, status, stories, duration, date). Filters: `--project`, `--last`, `--status`
-- [ ] **CRR-003:** `nax logs --run <runId>` — resolve run from global registry via `eventsDir`, stream logs from any directory
+- [x] ~~**CRR-000:** `src/pipeline/subscribers/events-writer.ts` — `wireEventsWriter()`, writes lifecycle events to `~/.nax/events/<project>/events.jsonl` (machine-readable completion signal for watchdog/CI)~~
+- [x] ~~**CRR-001:** `src/pipeline/subscribers/registry.ts` — `wireRegistry()` subscriber, listens to `run:started`, writes `~/.nax/runs/<project>-<feature>-<runId>/meta.json` (path pointers only — no data duplication, no symlinks)~~
+- [x] ~~**CRR-002:** `src/commands/runs.ts` — `nax runs` CLI, reads `meta.json` → resolves live `status.json` from `statusPath`, displays table (project, feature, status, stories, duration, date). Filters: `--project`, `--last`, `--status`~~
+- [x] ~~**CRR-003:** `nax logs --run <runId>` — resolve run from global registry via `eventsDir`, stream logs from any directory~~
 
 ---
 
@@ -223,6 +239,8 @@
 
 | Version | Theme | Date | Details |
 |:---|:---|:---|:---|
+| v0.24.0 | Central Run Registry | 2026-03-07 | CRR-000–003: events writer, registry, nax runs CLI, nax logs --run global resolution |
+| v0.23.0 | Status File Consolidation | 2026-03-07 | SFC-001–004: auto-write status.json, feature-level status, align readers, remove dead code; BUG-043/044: testScoped config + command logging |
 | v0.18.1 | Type Safety + CI Pipeline | 2026-03-03 | 60 TS errors + 12 lint errors fixed, GitLab CI green (1952/56/0) |
 | v0.22.2 | Routing Stability + SFC-001 | 2026-03-07 | BUG-040 floating outputPromise crash on LLM timeout retry; SFC-001 auto-write status.json |
 | v0.22.1 | Pipeline Re-Architecture | 2026-03-07 | VerificationOrchestrator, EventBus, new stages (rectify/autofix/regression/deferred-regression), post-run SSOT. 2264 pass |
@@ -287,8 +305,8 @@
 
 - [x] ~~**BUG-037:** Test output summary (verify stage) captures precheck boilerplate instead of actual `bun test` failure. Fixed: `.slice(-20)` tail — shipped in v0.22.1 (re-arch phase 2).~~
 - [x] ~~**BUG-038:** `smart-runner` over-matching when global defaults change. Fixed by FEAT-010 (v0.21.0) — per-attempt `storyGitRef` baseRef tracking; `git diff <baseRef>..HEAD` prevents cross-story file pollution.~~
-- [ ] **BUG-043:** Scoped test command appends files instead of replacing path — `runners.ts:scoped()` concatenates `scopedTestPaths` to full-suite command, resulting in `bun test test/ --timeout=60000 /path/to/file.ts` (runs everything). Fix: use `testScoped` config with `{{files}}` template, fall back to `buildSmartTestCommand()` heuristic. **Location:** `src/verification/runners.ts:scoped()`
-- [ ] **BUG-044:** Scoped/full-suite test commands not logged — no visibility into what command was actually executed during verify stage. Fix: log at info level before execution.
+- [x] ~~**BUG-043:** Scoped test command appends files instead of replacing path — `runners.ts:scoped()` concatenates `scopedTestPaths` to full-suite command, resulting in `bun test test/ --timeout=60000 /path/to/file.ts` (runs everything). Fix: use `testScoped` config with `{{files}}` template, fall back to `buildSmartTestCommand()` heuristic. **Location:** `src/verification/runners.ts:scoped()`
+- [x] ~~**BUG-044:** Scoped/full-suite test commands not logged — no visibility into what command was actually executed during verify stage. Fix: log at info level before execution.
 
 ### Features
 - [x] ~~`nax unlock` command~~

package/docs/specs/trigger-completion.md

@@ -0,0 +1,145 @@
+# Trigger Completion — Spec
+
+**Version:** v0.25.0
+**Status:** Planned
+
+---
+
+## Problem
+
+8 of 9 interaction trigger helpers (`checkCostExceeded`, `checkCostWarning`, `checkMaxRetries`, `checkSecurityReview`, `checkMergeConflict`, `checkPreMerge`, `checkStoryAmbiguity`, `checkReviewGate`) are implemented in `src/interaction/triggers.ts` and exported but **never called** from the pipeline.
+
+Only `human-review` is wired (via `wireInteraction` subscriber on `human-review:requested` event).
+
+Additionally, 3 hook events (`on-resume`, `on-session-end`, `on-error`) are defined in `HookEvent` but not wired to any pipeline event.
+
+---
+
+## Goal
+
+Wire all 8 remaining triggers to the correct pipeline decision points. Add 3 missing hook events. Add E2E/integration test coverage for the Telegram and auto plugins.
+
+---
+
+## Stories
+
+### TC-001: Wire `cost-exceeded` and `cost-warning` triggers
+
+**Location:** `src/execution/sequential-executor.ts`
+
+Currently at line 93, when `totalCost >= config.execution.costLimit`, the run exits with `"cost-limit"` — no interaction trigger is fired.
+
+**Fix:**
+- Before exiting on cost limit: call `checkCostExceeded({featureName, cost, limit}, config, interactionChain)`. If trigger returns `abort` or chain not available → exit as today. Pass `interactionChain` into `executeSequential` ctx (already present in `SequentialExecutionContext`).
+- Add a `cost-warning` threshold check: when `totalCost >= costLimit * 0.8` (configurable via `interaction.triggers.cost-warning.threshold`, default 0.8), fire `checkCostWarning`. Fire only once per run (track with a boolean flag). Fallback: `continue`.
+- Emit new `run:paused` event if trigger response is `escalate` (pause for human decision).
+- Add `CostExceededEvent` and `CostWarningEvent` to `PipelineEventBus` (or reuse `run:paused` with a `reason` field — preferred, avoids new event types).
+
+**Acceptance criteria:**
+- When cost hits 80% of limit, `cost-warning` trigger fires once and run continues (default fallback)
+- When cost hits 100% of limit, `cost-exceeded` trigger fires; abort kills the run, skip/continue allows proceeding past limit
+- When no interaction plugin is configured, behavior is identical to today (no-op)
+- Tests: unit test both thresholds with mock chain
+
+---
+
+### TC-002: Wire `max-retries` trigger
+
+**Location:** `src/execution/sequential-executor.ts` or `src/pipeline/pipeline-result-handler.ts`
+
+Currently when a story exhausts all tier escalations and is marked failed permanently (`markStoryFailed`), no trigger fires (except `human-review` which fires on `human-review:requested` event for a different condition).
+
+**Fix:**
+- In the story failure path (after all escalations exhausted), call `checkMaxRetries({featureName, storyId, iteration}, config, interactionChain)`.
+- Response `skip` = proceed (today's behavior), `abort` = halt entire run, `escalate` = retry story from scratch at top tier.
+- Wire via `story:failed` event in `wireInteraction` subscriber (add alongside `human-review:requested`).
+
+**Acceptance criteria:**
+- `max-retries` trigger fires when a story is permanently failed
+- `abort` response halts the run with exit reason `"interaction-abort"`
+- `skip` response is silent (today's behavior)
+- Tests: unit test with mock chain for all three fallbacks
+
+---
+
+### TC-003: Wire `security-review`, `merge-conflict`, `pre-merge` triggers
+
+**Location:** `src/pipeline/stages/review.ts` and `src/pipeline/stages/completion.ts` (post-story)
+
+- **`security-review`**: Fire after plugin reviewer (e.g. semgrep) rejects a story in `review.ts`. Currently returns `{ action: "fail" }`. Before failing permanently, call `checkSecurityReview`. Response `abort` = fail (today), `escalate` = retry with security context injected.
+- **`merge-conflict`**: Fire when git operations detect a merge conflict during story commit. Currently no merge-conflict detection exists — add detection in `src/execution/git.ts` (catch `CONFLICT` in git merge/rebase output) and call `checkMergeConflict`.
+- **`pre-merge`**: Fire after all stories pass but before the run is marked complete. Call `checkPreMerge({featureName, totalStories, cost}, config, interactionChain)` in `sequential-executor.ts` final block. Response `abort` = halt, `continue` = complete normally.
+
+**Acceptance criteria:**
+- `security-review` trigger fires when plugin reviewer rejects (not when lint/typecheck fails)
+- `merge-conflict` trigger fires when git detects CONFLICT markers
+- `pre-merge` trigger fires once after all stories pass, before run:completed
+- Tests: unit tests for each trigger point with mock chain
+
+---
+
+### TC-004: Wire `story-ambiguity` and `review-gate` triggers
+
+**Location:** `src/pipeline/stages/execution.ts`
+
+- **`story-ambiguity`**: Fire when agent session returns ambiguous/clarification-needed signal. Currently the agent exit codes and output are parsed in `execution.ts` — add a detection heuristic (e.g. agent output contains "unclear" / "ambiguous" / "need clarification" keywords, or a new `needsClarification` flag in agent result). Call `checkStoryAmbiguity` before escalating.
+- **`review-gate`**: Fire after `story:completed` as a human checkpoint gate (configurable, disabled by default). Wire via new `review-gate:requested` event emitted in completion stage when `interaction.triggers.review-gate.enabled = true`.
+
+**Acceptance criteria:**
+- `story-ambiguity` trigger fires when agent signals ambiguity (keyword detection)
+- `review-gate` trigger fires after each story passes when enabled
+- Both default to disabled in config (opt-in)
+- Tests: unit tests for ambiguity detection heuristic + trigger dispatch
+
+---
+
+### TC-005: Wire missing hook events (`on-resume`, `on-session-end`, `on-error`)
+
+**Location:** `src/pipeline/subscribers/hooks.ts`
+
+Three hook events are defined in `HookEvent` but never wired to pipeline events:
+
+- **`on-resume`**: Fire when a paused run resumes. Add `run:resumed` event to `PipelineEventBus`, emit it in `sequential-executor.ts` when resuming from pause state. Wire in `wireHooks`.
+- **`on-session-end`**: Fire when an individual agent session ends (pass or fail). Map to `story:completed` + `story:failed`. Wire in `wireHooks` on both events.
+- **`on-error`**: Fire on unhandled errors / crash. Emit in `crash-recovery.ts` crash handler. Wire in `wireHooks`.
+
+**Acceptance criteria:**
+- `on-resume` hook fires when a paused run is continued
+- `on-session-end` hook fires after every agent session (pass or fail)
+- `on-error` hook fires in crash handler before exit
+- Tests: extend existing `hooks.test.ts` with the three new events
+
+---
+
+### TC-006: Auto plugin integration tests
+
+**Location:** `test/integration/interaction/`
+
+The `AutoInteractionPlugin` (LLM-based) has zero test coverage. The Telegram and Webhook plugins have init/config tests but no send/receive flow tests.
+
+**Fix:**
+- `auto.test.ts` — mock the LLM call (`_deps` pattern), test: approve decision, reject decision, confidence below threshold falls back, `security-review` is never auto-approved.
+- Extend `interaction-plugins.test.ts` with Telegram send flow (mock `fetch`, verify message format + inline keyboard structure).
+- Extend with Webhook send flow (mock HTTP server, verify HMAC signature validation).
+
+**Acceptance criteria:**
+- Auto plugin: LLM approve/reject/confidence-fallback/security-review-block all covered
+- Telegram: message send format and inline keyboard structure verified
+- Webhook: HMAC verification tested (valid + tampered signatures)
+- All tests are unit/mock — no real network calls
+
+---
+
+## Out of Scope
+
+- Full E2E test with real Telegram bot (requires live credentials)
+- New trigger types beyond the 9 already defined
+- Interaction state persistence (pause/resume full flow) — separate feature
+
+---
+
+## Notes
+
+- All trigger calls must be best-effort guarded: if `interactionChain` is null/undefined, skip silently (today's behavior)
+- `interactionChain` is already threaded through `SequentialExecutionContext` — no new context changes needed for most stories
+- Config `interaction.triggers.<name>.enabled` must be `true` for any trigger to fire (`isTriggerEnabled` handles this)

package/nax/features/central-run-registry/prd.json

@@ -0,0 +1,105 @@
+{
+  "project": "nax",
+  "branchName": "feat/central-run-registry",
+  "feature": "central-run-registry",
+  "version": "0.24.0",
+  "description": "Global run index across all projects. Events file writer for machine-readable lifecycle events, registry subscriber that indexes every run to ~/.nax/runs/, nax runs CLI for cross-project run history, and nax logs --run <runId> for global log resolution.",
+  "userStories": [
+    {
+      "id": "CRR-000",
+      "title": "Events file writer subscriber",
+      "description": "New subscriber: src/pipeline/subscribers/events-writer.ts \u2014 wireEventsWriter(bus, project, feature, runId, workdir). Listens to run:started, story:started, story:completed, story:failed, run:completed, run:paused. Writes one JSON line per event to ~/.nax/events/<project>/events.jsonl (append mode). Each line: {\"ts\": ISO8601, \"event\": string, \"runId\": string, \"feature\": string, \"project\": string, \"storyId\"?: string, \"data\"?: object}. The run:completed event writes an 'on-complete' entry \u2014 the machine-readable signal that nax exited gracefully (fixes watchdog false crash reports). Best-effort: wrap all writes in try/catch, log warnings on failure, never throw or block the pipeline. Create ~/.nax/events/<project>/ on first write via mkdir recursive. Derive project name from path.basename(workdir). Wire in sequential-executor.ts alongside existing wireHooks/wireReporters/wireInteraction calls. Return UnsubscribeFn matching existing subscriber pattern.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "After a run, ~/.nax/events/<project>/events.jsonl exists with JSONL entries",
+        "Each line is valid JSON with ts, event, runId, feature, project fields",
+        "run:completed produces an entry with event=on-complete",
+        "story:started/completed/failed events include storyId",
+        "Write failure does not crash or block the nax run",
+        "Directory is created automatically on first write",
+        "wireEventsWriter is called in sequential-executor.ts",
+        "Returns UnsubscribeFn consistent with wireHooks/wireReporters pattern"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 2
+    },
+    {
+      "id": "CRR-001",
+      "title": "Registry writer subscriber",
+      "description": "New subscriber: src/pipeline/subscribers/registry.ts \u2014 wireRegistry(bus, project, feature, runId, workdir). Listens to run:started. On event, creates ~/.nax/runs/<project>-<feature>-<runId>/meta.json with fields: {runId, project, feature, workdir, statusPath: join(workdir, 'nax/features', feature, 'status.json'), eventsDir: join(workdir, 'nax/features', feature, 'runs'), registeredAt: ISO8601}. meta.json schema exported as MetaJson interface. Written once, never updated. Best-effort: try/catch + warn log, never throw/block. Create ~/.nax/runs/ directory on first call via mkdir recursive. Derive project from path.basename(workdir). Wire in sequential-executor.ts alongside wireEventsWriter. Return UnsubscribeFn.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "After run start, ~/.nax/runs/<project>-<feature>-<runId>/meta.json exists",
+        "meta.json contains runId, project, feature, workdir, statusPath, eventsDir, registeredAt",
+        "statusPath points to <workdir>/nax/features/<feature>/status.json",
+        "eventsDir points to <workdir>/nax/features/<feature>/runs",
+        "MetaJson interface is exported from the module",
+        "Write failure does not crash or block the nax run",
+        "wireRegistry is called in sequential-executor.ts"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 2
+    },
+    {
+      "id": "CRR-002",
+      "title": "nax runs CLI command",
+      "description": "New command: src/commands/runs.ts \u2014 runsCommand(options). Reads all ~/.nax/runs/*/meta.json, resolves each statusPath to read the live NaxStatusFile for current state. Displays a table sorted by registeredAt desc. Columns: RUN ID, PROJECT, FEATURE, STATUS, STORIES (passed/total), DURATION, DATE. Default limit: 20. Options: --project <name> (filter), --last <N> (limit), --status <running|completed|failed|crashed> (filter). If statusPath missing, show status as '[unavailable]'. Register in src/commands/index.ts and wire in bin/nax.ts CLI arg parser (match pattern of existing diagnose/logs/status commands). Use chalk for colored output. Green for completed, red for failed, yellow for running, dim for unavailable.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "nax runs displays a table of all registered runs sorted newest-first",
+        "nax runs --project <name> filters by project name",
+        "nax runs --last <N> limits output to N runs",
+        "nax runs --status <status> filters by run status",
+        "Runs with missing statusPath show '[unavailable]' status gracefully",
+        "Empty registry shows 'No runs found' message",
+        "Command is registered in CLI help output and bin/nax.ts"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [
+        "CRR-001"
+      ],
+      "tags": [],
+      "storyPoints": 3
+    },
+    {
+      "id": "CRR-003",
+      "title": "nax logs --run <runId> global resolution",
+      "description": "Enhance src/commands/logs.ts logsCommand: when --run <runId> is provided, scan ~/.nax/runs/*/meta.json for matching runId (exact or prefix match). Read eventsDir from meta.json, locate the JSONL log file in that directory (newest .jsonl file), then display using existing displayLogs/followLogs functions. Falls back to current behavior (local feature context) when --run is not specified. If runId not found in registry, throw error Run not found in registry: <runId>. If eventsDir or log file missing, show unavailable message. Update LogsOptions interface to accept run?: string. Update bin/nax.ts to pass --run option through.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "nax logs --run <runId> displays logs from the matching run regardless of cwd",
+        "Resolution uses ~/.nax/runs/*/meta.json to find eventsDir path",
+        "Unknown runId shows clear error message",
+        "Missing log files show unavailable message",
+        "Without --run flag, existing local behavior is unchanged",
+        "Partial runId matching works (prefix match on runId field)"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [
+        "CRR-001"
+      ],
+      "tags": [],
+      "storyPoints": 2
+    }
+  ]
+}

package/nax/features/trigger-completion/prd.json

@@ -0,0 +1,150 @@
+{
+  "project": "nax",
+  "branchName": "feat/trigger-completion",
+  "feature": "trigger-completion",
+  "version": "0.25.0",
+  "description": "Wire all 8 unwired interaction triggers to correct pipeline decision points, add 3 missing hook events, and add integration tests for auto/telegram/webhook plugins.",
+  "userStories": [
+    {
+      "id": "TC-001",
+      "title": "Wire cost-exceeded and cost-warning triggers",
+      "description": "In src/execution/sequential-executor.ts: (1) Before exiting on cost limit (line ~93), call checkCostExceeded({featureName: ctx.feature, cost: totalCost, limit: ctx.config.execution.costLimit}, ctx.config, ctx.interactionChain). Import checkCostExceeded from src/interaction/triggers.ts. If isTriggerEnabled(\"cost-exceeded\", config) is false or chain is null, keep today behavior. Trigger abort = exit \"cost-limit\". Trigger skip/continue = allow run to proceed past limit. (2) Add cost-warning: track a boolean warningSent=false. In the iteration loop, when totalCost >= costLimit * (interaction.triggers[\"cost-warning\"]?.threshold ?? 0.8) and !warningSent, call checkCostWarning({featureName, cost, limit}, config, interactionChain), set warningSent=true. isTriggerEnabled guards the call. Default fallback continue = proceed silently. Both calls must be best-effort: guard with if(interactionChain) check.",
+      "complexity": "medium",
+      "status": "passed",
+      "acceptanceCriteria": [
+        "When cost hits 80% of limit and cost-warning trigger is enabled, checkCostWarning fires once",
+        "Warning fires only once per run even if cost stays above threshold for multiple iterations",
+        "When cost hits 100% of limit and cost-exceeded is enabled, checkCostExceeded fires before exit",
+        "abort response exits with cost-limit reason; skip/continue allows run to proceed",
+        "When interaction plugin not configured, behavior is identical to today",
+        "Unit tests cover 80% threshold, 100% threshold, abort, skip, continue responses"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 2,
+      "passes": true
+    },
+    {
+      "id": "TC-002",
+      "title": "Wire max-retries trigger",
+      "description": "In src/pipeline/subscribers/interaction.ts, extend wireInteraction to also subscribe to story:failed event. When story:failed fires with countsTowardEscalation=true (permanent failure, all tiers exhausted), call executeTrigger(\"max-retries\", {featureName: ev.feature ?? \"\", storyId: ev.storyId, iteration: ev.attempts ?? 0}, config, interactionChain). Import StoryFailedEvent from event-bus. Guard with isTriggerEnabled(\"max-retries\", config) and interactionChain check. Response handling: abort = emit a new run:paused event with reason \"max-retries-abort\" (the executor checks this to halt); skip = default, proceed; escalate = not supported for this trigger, treat as skip. Note: the actual run halt on abort requires reading from a shared flag or emitting run:paused — simplest: log a warning and let the run continue (abort behavior can be enhanced later). For now, abort = warn log only.",
+      "complexity": "medium",
+      "status": "passed",
+      "acceptanceCriteria": [
+        "max-retries trigger fires when story:failed event has countsTowardEscalation=true",
+        "max-retries trigger does NOT fire when countsTowardEscalation=false",
+        "When trigger disabled or no chain, no-op",
+        "abort response logs a warning (full halt is future work)",
+        "Unit tests cover enabled/disabled, countsTowardEscalation true/false, all fallback responses"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 2,
+      "passes": true
+    },
+    {
+      "id": "TC-003",
+      "title": "Wire security-review, merge-conflict, and pre-merge triggers",
+      "description": "Three trigger wiring points: (1) security-review in src/pipeline/stages/review.ts: when plugin reviewer (semgrep etc) returns failure (the existing check at ~line 50 that returns action:fail for plugin reviewer rejection), before permanently failing, call checkSecurityReview({featureName, storyId: ctx.story.id}, ctx.config, ctx.interactionChain) if isTriggerEnabled and chain present. abort=fail (today), escalate=return {action:\"escalate\"}. Import from interaction. (2) merge-conflict: add conflict detection in src/execution/git.ts — after any git merge/rebase/commit operation, check if stdout/stderr contains \"CONFLICT\" or \"conflict\". If detected and isTriggerEnabled(\"merge-conflict\") and chain, call checkMergeConflict. Export a detectMergeConflict(output: string): boolean helper. (3) pre-merge in sequential-executor.ts: after all stories complete (isComplete(prd)=true) and before emitting run:completed, call checkPreMerge({featureName: ctx.feature, totalStories: prd.userStories.length, cost: totalCost}, ctx.config, ctx.interactionChain) if enabled. abort = exit without completing.",
+      "complexity": "medium",
+      "status": "passed",
+      "acceptanceCriteria": [
+        "security-review trigger fires when plugin reviewer rejects (not lint/typecheck)",
+        "security-review abort = story permanently fails; escalate = story retried",
+        "detectMergeConflict(output) returns true when CONFLICT present in git output",
+        "merge-conflict trigger fires when git conflict detected and trigger enabled",
+        "pre-merge trigger fires once after all stories pass, before run:completed",
+        "pre-merge abort exits run; continue = complete normally",
+        "Unit tests for each trigger point with mock chain"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 3,
+      "passes": true
+    },
+    {
+      "id": "TC-004",
+      "title": "Wire story-ambiguity and review-gate triggers",
+      "description": "Two opt-in triggers (disabled by default): (1) story-ambiguity in src/pipeline/stages/execution.ts: after agent session result is parsed, check if agent output contains ambiguity signals. Add helper isAmbiguousOutput(output: string): boolean that returns true if output contains any of: [\"unclear\", \"ambiguous\", \"need clarification\", \"please clarify\", \"which one\", \"not sure which\"]. If detected and isTriggerEnabled(\"story-ambiguity\", config) and interactionChain, call checkStoryAmbiguity({featureName, storyId: ctx.story.id, reason: \"Agent output suggests ambiguity\"}, config, ctx.interactionChain). abort = escalate story; continue = proceed as normal. (2) review-gate in src/pipeline/stages/completion.ts (or wherever story:completed is emitted): if isTriggerEnabled(\"review-gate\", config) and interactionChain, call checkReviewGate({featureName, storyId: ctx.story.id}, config, ctx.interactionChain) after story passes. abort = mark story as needing re-review (log warning, do not fail); continue = proceed. Both triggers default to disabled in config.",
+      "complexity": "medium",
+      "status": "passed",
+      "acceptanceCriteria": [
+        "isAmbiguousOutput() detects all 6 keyword phrases (case-insensitive)",
+        "story-ambiguity trigger fires when isAmbiguousOutput=true and trigger enabled",
+        "story-ambiguity is disabled by default (isTriggerEnabled returns false)",
+        "review-gate trigger fires after each story passes when enabled",
+        "review-gate is disabled by default",
+        "Unit tests for isAmbiguousOutput and both trigger dispatch paths"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 2,
+      "passes": true
+    },
+    {
+      "id": "TC-005",
+      "title": "Wire missing hook events: on-resume, on-session-end, on-error",
+      "description": "Three missing hook events to wire in src/pipeline/subscribers/hooks.ts: (1) on-resume: add RunResumedEvent {type:\"run:resumed\"; feature: string} to PipelineEventBus. Emit it in sequential-executor.ts when resuming from pause state (detect via interaction state or run:paused→run:resumed cycle). Wire bus.on(\"run:resumed\") → fireHook(hooks, \"on-resume\", ...) in wireHooks. (2) on-session-end: fire after every agent session ends (pass OR fail). Wire bus.on(\"story:completed\") AND bus.on(\"story:failed\") → fireHook(hooks, \"on-session-end\", hookCtx(feature, {storyId, status: passed?\"passed\":\"failed\"})). (3) on-error: emit a run:errored event in src/execution/crash-recovery.ts crash handler (unhandledRejection / SIGTERM / SIGINT handlers). Wire bus.on(\"run:errored\") → fireHook(hooks, \"on-error\", hookCtx(feature, {reason: signal/error})). Add RunErroredEvent type to event-bus. All three follow existing best-effort fire-and-forget pattern.",
+      "complexity": "medium",
+      "status": "passed",
+      "acceptanceCriteria": [
+        "RunResumedEvent type added to PipelineEventBus",
+        "on-resume hook fires when run:resumed event emitted",
+        "on-session-end hook fires after story:completed AND story:failed events",
+        "RunErroredEvent type added to PipelineEventBus",
+        "on-error hook fires in crash-recovery handlers (SIGTERM, SIGINT, unhandledRejection)",
+        "All three follow fire-and-forget pattern (no await, errors logged)",
+        "Extend hooks.test.ts with tests for all three new events"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 2,
+      "passes": true
+    },
+    {
+      "id": "TC-006",
+      "title": "Auto plugin and Telegram/Webhook plugin integration tests",
+      "description": "Add mock-based integration tests for the three untested plugins. File locations: test/unit/interaction/auto-plugin.test.ts, extend test/unit/interaction-plugins.test.ts. (1) AutoInteractionPlugin (_deps pattern): mock the LLM call via _deps.callLlm. Test: LLM returns approve → response.action=\"continue\"; LLM returns reject → response.action=\"abort\"; confidence < threshold → fallback to chain default; trigger=security-review → always rejects auto-approval (hardcoded block), returns chain default. Add _deps.callLlm to auto.ts if not present. (2) Telegram send flow: mock fetch globally in test. Verify send() POSTs to correct API URL with message text and inline keyboard buttons (approve/reject). Verify poll() parses callback_query correctly. (3) Webhook: mock an HTTP server using Bun.serve in test. Verify send() POSTs payload with correct Content-Type. Verify HMAC signature validation rejects tampered payload. All tests are pure unit/mock — no real network calls.",
+      "complexity": "medium",
+      "status": "passed",
+      "acceptanceCriteria": [
+        "AutoInteractionPlugin: approve, reject, low-confidence, security-review-block all tested",
+        "Auto plugin uses _deps pattern for LLM call (testable without real API)",
+        "Telegram send() verified to POST correct message structure with inline keyboard",
+        "Telegram poll() parses callback_query response correctly",
+        "Webhook send() verified with correct Content-Type and payload structure",
+        "Webhook HMAC validation: valid signature passes, tampered payload rejected",
+        "Zero real network calls in any test"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 2,
+      "passes": true
+    }
+  ],
+  "updatedAt": "2026-03-07T14:53:47.398Z"
+}

package/nax/features/trigger-completion/progress.txt

@@ -0,0 +1,7 @@
+[2026-03-07T14:04:48.521Z] TC-001 — PASSED — Wire cost-exceeded and cost-warning triggers — Cost: $1.1231
+[2026-03-07T14:11:47.185Z] TC-002 — PASSED — Wire max-retries trigger — Cost: $0.1029
+[2026-03-07T14:30:04.761Z] TC-003 — PASSED — Wire security-review, merge-conflict, and pre-merge triggers — Cost: $1.3628
+[2026-03-07T14:36:14.823Z] TC-004 — PASSED — Wire story-ambiguity and review-gate triggers — Cost: $0.0000
+[2026-03-07T14:38:01.345Z] TC-004 — PASSED — Wire story-ambiguity and review-gate triggers — Cost: $0.1019
+[2026-03-07T14:43:51.353Z] TC-005 — PASSED — Wire missing hook events: on-resume, on-session-end, on-error — Cost: $0.4284
+[2026-03-07T14:53:47.397Z] TC-006 — PASSED — Auto plugin and Telegram/Webhook plugin integration tests — Cost: $0.7347

package/nax/status.json

@@ -1,37 +1,27 @@
 {
   "version": 1,
   "run": {
-    "id": "run-2026-03-07T06-14-21-018Z",
-    "feature": "status-file-consolidation",
-    "startedAt": "2026-03-07T06:14:21.018Z",
-    "status": "crashed",
+    "id": "run-2026-03-07T13-49-17-400Z",
+    "feature": "trigger-completion",
+    "startedAt": "2026-03-07T13:49:17.400Z",
+    "status": "completed",
     "dryRun": false,
-    "pid": 217461,
-    "crashedAt": "2026-03-07T06:22:36.300Z",
-    "crashSignal": "SIGTERM"
+    "pid": 97007
   },
   "progress": {
-    "total": 4,
-    "passed": 0,
+    "total": 6,
+    "passed": 6,
     "failed": 0,
     "paused": 0,
     "blocked": 0,
-    "pending": 4
+    "pending": 0
   },
   "cost": {
-    "spent": 0,
-    "limit": 3
+    "spent": 3.85387425,
+    "limit": 8
   },
-  "current": {
-    "storyId": "SFC-002",
-    "title": "Write feature-level status on run end",
-    "complexity": "medium",
-    "tddStrategy": "test-after",
-    "model": "balanced",
-    "attempt": 1,
-    "phase": "routing"
-  },
-  "iterations": 0,
-  "updatedAt": "2026-03-07T06:22:36.300Z",
-  "durationMs": 495282
+  "current": null,
+  "iterations": 7,
+  "updatedAt": "2026-03-07T14:58:57.404Z",
+  "durationMs": 4180004
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.23.0",
-  "description": "AI Coding Agent Orchestrator — loops until done",
+  "version": "0.25.0",
+  "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {
     "nax": "./bin/nax.ts"

package/src/commands/index.ts

@@ -5,4 +5,5 @@
 export { resolveProject, type ResolveProjectOptions, type ResolvedProject } from "./common";
 export { logsCommand, type LogsOptions } from "./logs";
 export { precheckCommand, type PrecheckOptions } from "./precheck";
+export { runsCommand, type RunsOptions } from "./runs";
 export { unlockCommand, type UnlockOptions } from "./unlock";