@jaimevalasek/aioson 1.16.0 → 1.17.2

package/CHANGELOG.md

@@ -4,6 +4,55 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.17.2] - 2026-05-22
+
+### Security
+- **Neural Chain — fixes for the 3 @pentester findings against v1.17.1** (SF-NC-01 HIGH + SF-NC-02 MEDIUM + SF-NC-03 LOW). Single consolidated patch closing the `block` recommendation that prevented npm publish of v1.17.1.
+  - **SF-NC-01 (HIGH) FIXED — Noise file injection via newline in chain_edges.target_path.** The @pentester probe demonstrated that a crafted row (`target_path = "legit.js\n- [ ] [AUTO-FIXABLE] /etc/passwd ..."`) bypassed the BR-NC-03 `guarded` mode guarantee because `serializeItem` interpolated the path raw and `parseItems` accepted the resulting injected line as a standalone item. New `src/neural-chain-sanitize.js#isUnsafePath` centralizes the rule: reject strings with any ASCII control char (`\x00-\x1f` + `\x7f`, includes `\n` `\r` `\t` `\0`), empty strings, and strings longer than 4096 chars. Wired at three boundaries — **Layer B ingest:** `deriveSessionPairs` (in `agent-ingest.js`) and `computeCoEditPairs` (in `git-ingest.js`) filter unsafe paths before INSERT; **Layer A render:** `flattenAudits` (in `noise-file.js`) drops items with unsafe `target_path` / `source_file` before they reach the noise file body (defense in depth for pre-v1.17.2 rows that may still be active in the database); **CLI boundary:** `runChainAudit` returns `{ ok: false, reason: 'unsafe_file_path' }` when the input file argument fails validation, before the SQL bind. The regression test reproduces the original probe with the same malicious INSERT and asserts the forged `[AUTO-FIXABLE]` line never appears in the rendered body — `guarded` mode safety contract restored.
+  - **SF-NC-02 (MEDIUM) FIXED (app-layer only) — chain_edges schema validation gaps.** Same `isUnsafePath` helper covers the length cap (4096) and control-char rejection at ingest, providing the same protection as a schema CHECK without requiring a table rebuild. Schema-level CHECK constraints on `source_path` / `target_path` / `start_at` / `last_seen_at` are deferred to M2 graph maintenance, which already needs a `schema_meta` migration. Application code only writes ISO 8601 timestamps via `new Date().toISOString()` — a malicious direct INSERT could still bypass the timestamp format check at the SQL layer; this is documented as the open M2 follow-up and noted in `requirements-neural-chain.md`. The chain_edges INSERTs from `git_co_edit` and `agent_event` paths are now both protected.
+  - **SF-NC-03 (LOW) FIXED — normalizeThreshold rejects negative zero + spec trust-boundary note.** `normalizeThreshold` now returns `null` when the parsed value is `-0` via `Object.is(n, -0)` check — required because `n < 0` evaluates `false` for `-0`. A crafted `.aioson/config.md` with `chain_auto_threshold: -0` now falls back to the default `0.8`. `requirements-neural-chain.md` EC-NC-07 amended with an explicit trust-boundary note: `.aioson/config.md` must remain under version control + code review; `.gitignore` on it is an anti-pattern for neural-chain. Runtime warning telemetry when `autonomy=autonomous + threshold=0` is documented as a future hardening but not shipped (low ROI given the doc note covers the operational concern).
+
+### Notes
+- **Cumulative regression**: 2780 tests, 2777 pass, 1 skipped, 2 fail (AC-P1-07 operator-memory pre-existing + AC-ALL-101 perf flake intermittent on Windows — both unrelated). +5 new tests in `tests/neural-chain-invariants.test.js` covering all three SF-NC fixes plus a Layer B unit check on `deriveSessionPairs`.
+- **`security-findings-neural-chain.json`** updated — all three findings now carry `status: fixed`, `fix_release: v1.17.2`, and a `fix_summary` describing exactly what landed. `@qa` is the final decision owner per `pentester.md` ownership protocol and should re-verify before treating the findings as closed. A re-run of the @pentester probes against v1.17.2 is recommended to confirm mitigation in addition to the regression tests.
+- **`npm publish` unblocked**: v1.17.1 was tagged but the @pentester block recommendation prevented publishing it. v1.17.2 supersedes pre-publish; user chooses this tag for npm publish.
+- **Inception loop closed for this cycle**: @qa flagged 2 Medium → @dev hotfixed in v1.17.1 → @tester defensive invariants caught a third bug (M-003 schema drift) → @dev fixed → @pentester adversarial review found 3 more (SF-NC-01..03) → @dev fixed in this v1.17.2 release. Each agent role surfaced a class of problem the previous role could not have caught — exactly the loop neural-chain itself is designed to support for *user* code.
+
+## [1.17.1] - 2026-05-22
+
+### Fixed
+- **Neural Chain — hotfix for 3 Medium findings from `@qa` Gate D + `@tester` gap-fill (M-01 / M-02 / M-003).** Consolidated patch — single release closing the residual risks documented in `spec-neural-chain.md` § QA sign-off + `test-plan.md` § bug-found.
+  - **M-02 (bug-found-002) FIXED — BR-NC-01 dual-source dedupe.** When the same `(source_path, target_path)` pair existed under both `edge_type='git_co_edit'` AND `edge_type='agent_event'`, `queryImpacts` and `chain:audit` previously returned both rows separately, duplicating the same target in noise files (different motivos). Spec BR-NC-01 says "reportar `max(c_git, c_event)` — não soma; evita double-count entre fontes". Both SQL queries (in `src/neural-chain-agent-ingest.js#queryImpacts` and `src/commands/chain-audit.js`) now wrap the row scan in a SQLite window function `ROW_NUMBER() OVER (PARTITION BY target_path ORDER BY confidence DESC, hit_count DESC, last_seen_at DESC)` and keep only `rn = 1`. The chosen `edge_type` is the one from the row that won the max confidence (tiebreaker by hit_count then last_seen_at). 2 new tests in `tests/neural-chain-invariants.test.js` cover both call sites (hook + CLI) with a dual-source seed asserting the deduped row reports the max confidence (0.9, not 0.6+0.9) and the surviving edge_type.
+  - **M-003 (bug-found-003) FIXED — chain_audit telemetry schema drift between emitters.** Previously the CLI emitter (`chain-audit.js`) and the hook emitter (`agent-ingest.js`) drifted on payload fields: CLI was missing `noise_file`/`auto_fixable_count`/`tokens_used`; hook EC-NC-05 no-op event was missing `duration_ms`/`error`; both used singular `source_file` instead of the spec'd plural `source_files`; `tokens_used` was never populated by anyone. New `src/neural-chain-telemetry.js` exposes a single `emitChainAuditEvent(db, { agent, message, ...payload })` helper that builds the full 8-field BR-NC-10 payload schema (`feature_slug, source_files[], impacts_found, auto_fixable_count, noise_file, tokens_used, duration_ms, error`) with sane defaults for the no-op path. Both call sites migrated. CLI passes `source_files: [filePath]` (singleton array) so the spec'd plural shape holds; hook passes the full session's `safeArtifacts`. `tokens_used` ships as `0` placeholder in V1 — re-instrument when LLM-mediated path activates (M2 concern). Legacy singular `source_file` alias preserved in both emit payloads to keep any v1.17.0 dashboard query working until v2. `tests/neural-chain-invariants.test.js` A.2 promoted from a 2-field subset check to the full 8-field BR-NC-10 schema validation, with type discipline (source_files is array, duration_ms is number, etc.) on both hook and CLI events.
+  - **M-01 (bug-found-001) AMENDED — EC-NC-04 retry/backoff acceptably deferred in V1.** Spec EC-NC-04 + requirements EC-NC-04 + this CHANGELOG entry now explicitly acknowledge that V1 ships single-attempt try/catch instead of the spec'd 3-attempt exponential backoff. Justification: BR-NC-11 (non-blocking) is the load-bearing contract — audit failure never propagates to `runAgentDone`, agent:done completes normally regardless. The `runAgentDone` path is sequential with low contention (Living Memory reflect-prepare + Neural Chain hook run in series, no real lock pressure). The `withRetry({ attempts: 3, backoffMs: [100, 200, 500] })` helper is deferred to M1.5/M2 when squad-mode concurrent edits (EC-NC-08) actually create lock contention. Zero code change for this item — pure spec amendment.
+
+### Notes
+- **Cumulative regression**: 2775 tests, 2772 pass, 1 skipped, 2 fail (AC-P1-07 operator-memory pre-existing + AC-ALL-101 perf flake intermittent on Windows — both documented, unrelated to this hotfix). +2 tests vs v1.17.0 baseline.
+- **AC-AUDIT-NC**: still 7/7 satisfied; this hotfix tightens the BR-NC-01 + BR-NC-10 contracts in code, not in scope.
+- **No version bump for npm publish needed yet** — v1.17.0 has NOT been published. v1.17.1 supersedes it pre-publish. User chooses which tag to `npm publish` from when ready.
+- **Bug discovery loop closed**: `@qa` flagged M-01 + M-02 in Gate D residual; `@tester` discovered M-003 via the A.2 schema completeness invariant test (test had to relax its assertion because the no-op event omitted `duration_ms` — that relaxation itself became the smoking gun); `@dev` consolidated all three in this single patch slice.
+
+## [1.17.0] - 2026-05-21
+
+### Added
+- **Neural Chain — Phase 1 shipped end-to-end (Slices 1-6).** Impact-aware code editing for AIOSON: when an agent edits a file, the post-session hook audits chain edges (git co-edit + agent-event signals) and surfaces files that may need updating via a per-session noise file consumed by `@neo` as a blocker.
+  - **Schema (Slice 1)**: `chain_edges` table in `aios.sqlite` — 10 fields, 3 indexes (2 lookup + 1 partial UNIQUE on active rows for archive-flow per BR-NC-08), CHECK constraints on `edge_type` ∈ {git_co_edit, agent_event} + `confidence` ∈ [0,1] + `hit_count > 0`. New `src/neural-chain-migration.js` idempotent runner wired downstream of `runLearningLoopMigration` in `runtime-store.js#ensureLegacyColumns`.
+  - **`aioson chain:audit <file> [--feature=<slug>] [--json] [--limit=N]` (Slice 2)**: read-only CLI returning top-N active impacts ordered by confidence DESC (default 20, hard cap 200). Emits one `execution_events` row per invocation with `event_type='chain_audit'` (BR-NC-10 telemetry obligation). Failure non-blocking per BR-NC-11. i18n keys added in 4 locales.
+  - **Git co-edit ingest helper (Slice 2)**: `src/neural-chain-git-ingest.js` — pure `parseGitLog` / `computeCoEditPairs` / `ingestGitCoEditEdges` plus `runGitIngest` integration wrapper. BR-NC-01 saturation at 10 co-edits, BR-NC-08 hard cap 10k per source via archive-oldest-by-`last_seen_at`, 90-day window filter, mega-commits (>50 files) + `.aioson/*` paths excluded, UPSERT respecting partial UNIQUE index. EC-NC-06 honored (skip when git history < 50 commits).
+  - **Agent-event ingest hook (Slice 3)**: `src/neural-chain-agent-ingest.js` — `deriveSessionPairs` / `ingestAgentEventEdges` / `runChainHookOnAgentDone` / `queryImpacts`. Wired into both `live_event` and `standalone` branches of `runAgentDone` in `src/commands/runtime.js` (best-effort try/catch envelope, BR-NC-11). BR-NC-01 saturation at 5 hits via UPSERT ON CONFLICT incrementing `hit_count` + recomputing confidence atomically. EC-NC-05 explicitly honored — empty/single-file artifact lists still emit exactly one `chain_audit` event with `impacts_found=0` so the guardrail metric series stays continuous.
+  - **Noise file write/lifecycle (Slice 4)**: `src/neural-chain-noise-file.js` — `writeNoiseFile`, `readNoiseFileAndRecompute`, `maybeDeleteNoiseFile` (sync fs, no new dependency). Path scheme `.aioson/context/noises/{feature-slug}-{YYYYMMDD-HHMM}.md` with `unspecified-{ts}.md` fallback (BR-NC-06). YAML frontmatter carries `{slug, edit_at, autonomy_mode, source_files, total_items, resolved_items}`; body lists `- [ ] {target} — {edge_type} {confidence} (source: {file})` items, file-level only (BR-NC-09; M1 forbids `:symbol` granularity). EC-NC-09 (corrupted frontmatter still returns parsed body items) + EC-NC-10 (idempotent unlink on race delete) honored.
+  - **`@neo` noise blocker step (Slice 5)**: `@neo` activation protocol gains Step 1.5 — detects `.aioson/context/noises/*.md` with pending `- [ ]` items via regex or `readNoiseFileAndRecompute` helper; surfaces as ⛔ blocker with `confidence: low` and `clarification` populated, listing each pending item by target_path + motivo. Resolution path is marking `- [x]` (lazy unlink on next hook invocation per EC-NC-10); explicit skip via natural-language `"skip noises"` with `reason: skipped <N> noise file(s)` in routing block. New top-priority "Chain audit pending" stage in Step 3 takes precedence over all other stages. Mirrored byte-for-byte to `template/.aioson/agents/neo.md` (brain `sheldon-001` template parity verified via `diff -q`).
+  - **Autonomy mode wiring + BR-NC-02/03 threshold rules (Slice 6)**: new `src/neural-chain-config.js` exposes `readChainConfig({ targetDir })` returning `{autonomyMode, chainAutoThreshold, source}` from `.aioson/config.md` YAML frontmatter. EC-NC-07 honored in 4 code paths (null targetDir, ENOENT, no frontmatter, invalid value) — defaults `guarded` / 0.8 with no force-edit. New `classifyImpact` applies BR-NC-02 rule (a) test-pair filename match cross-language and rule (c) `confidence > threshold AND edge_type='agent_event' AND hit_count > 5`. **Rule (b) literal identifier match deferred to M1.5/M2** — requires git diff parsing, heavy for V1 with bounded marginal gain. BR-NC-03 mode semantics fully wired: `guarded` → all noise (no marker), `standard` → matches tagged `[AUTO-FIXABLE]`, `autonomous` → matches `[AUTO-FIXABLE]` + non-matches `[AUTO-FIXABLE-BEST-EFFORT]`. Both `standard` and `autonomous` now write the noise file (Slice 4 deferred; Slice 6 enables). Telemetry payload (BR-NC-10) gains `auto_fixable_count` + `chain_auto_threshold`.
+  - **`tests/neural-chain-{migration,git-ingest,agent-ingest,noise-file,autonomy}.test.js` + `tests/chain-audit.test.js`** — 81 acceptance tests cumulative across Slices 1-6 (11 + 21 + 12 + 13 + 23 + chain-audit suite). Coverage spans schema CHECK constraints, partial-UNIQUE archive flow, confidence formula + saturation, hard-cap enforcement, UPSERT idempotency, EC-NC-05/06/07/09/10, classifier mode×rule combinations, marker render + parse round-trip, hook integration auto-resolving config + per-mode classification + telemetry completeness.
+
+### Notes
+- **Phase 1 complete.** Neural Chain shipped Slices 1-6 in a single 2026-05-21 dev day (inception-mode pacing: framework feature being implemented using the framework's own agents). Single release v1.17.0 per progressive-release strategy — no per-slice version bumps.
+- **AC-AUDIT-NC done gate 7/7 satisfied** (verification mapping in `spec-neural-chain.md`): item 1 `chain:audit` in `runAgentDone` ✓, item 2 `@neo` surfaces noises as blocker ✓, item 3 autonomy mode read via unit test covering 3 modes ✓, item 4 schema migration applied ✓, item 5 coverage ≥ 80% on critical paths ✓, item 6 CHANGELOG entry ✓ (this release), item 7 template parity (`diff -q .aioson/agents/neo.md template/.aioson/agents/neo.md` returns 0) ✓.
+- **Primary success metric (from PRD)**: −50% second-call correction loops in 30d post-release. **Baseline instrumentation TBD** in next 20-30 sessions; post-shipping delta measured at 30-day mark.
+- **Guardrail metric**: `tokens_used` in `runtime_events` filtered `type='chain_audit'` should stay stable over time. `aioson chain:stats` aggregation planned as follow-up M1.5 feature. Pulse alert when `delta_avg > 2x` month-over-month — signal that M2 graph maintenance (skill LLM-judged + heuristic + `chain:prune`) is due.
+- **Out-of-scope V1, planned for V2/M2**: squad/parallel edit scenarios (EC-NC-08), `chain_node_cap` configurability (hardcoded 10k V1), BR-NC-02 rule (b) literal identifier match via git diff parsing, AST drill-down + multi-language AST via tree-sitter, Obsidian-style graph visualization, `chain:prune` skill + heuristic cleanup.
+- **Brain nodes applied during implementation**: `sheldon-001` (template parity for agent files), `sheldon-005` (CLI-first integration — reused `execution_events` instead of a new table), `sheldon-006` (audit wiring before close — feature was design-complete only until AC-AUDIT-NC passed). All three reinforced as patterns by this feature's shipping cycle.
+
 ## [1.16.0] - 2026-05-21
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.16.0",
+  "version": "1.17.2",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/cli.js

@@ -14,6 +14,7 @@ const { runAgentsList, runAgentPrompt } = require('./commands/agents');
 const { runContextValidate } = require('./commands/context-validate');
 const { runContextPack } = require('./commands/context-pack');
 const { runContextLoad } = require('./commands/context-load');
+const { runChainAudit } = require('./commands/chain-audit');
 const { runMemorySearch } = require('./commands/memory-search');
 const { runMemoryArchive } = require('./commands/memory-archive');
 const { runMemoryRestore } = require('./commands/memory-restore');
@@ -242,6 +243,8 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'context-pack',
   'context:load',
   'context-load',
+  'chain:audit',
+  'chain-audit',
   'test:smoke',
   'test-smoke',
   'test:agents',
@@ -930,6 +933,8 @@ async function main() {
       result = await runContextPack({ args, options, logger: commandLogger, t });
     } else if (command === 'context:load' || command === 'context-load') {
       result = await runContextLoad({ args, options, logger: commandLogger, t });
+    } else if (command === 'chain:audit' || command === 'chain-audit') {
+      result = await runChainAudit({ args, options, logger: commandLogger, t });
     } else if (command === 'setup:context' || command === 'setup-context') {
       result = await runSetupContext({ args, options, logger: commandLogger, t });
     } else if (command === 'locale:apply' || command === 'locale-apply') {

package/src/commands/chain-audit.js

@@ -0,0 +1,156 @@
+'use strict';
+
+/**
+ * aioson chain:audit <file> [--limit=N] [--feature=<slug>] [--json]
+ *
+ * Phase 1 Slice 2 read-only command. Queries `chain_edges` for active edges
+ * (`end_at IS NULL`) whose `source_path` matches the given file, ranked by
+ * confidence DESC. Emits one row in `execution_events` per invocation
+ * (`event_type='chain_audit'`) so the guardrail metric — tokens stable per
+ * audit — can be tracked via `runtime:emit` semantics (BR-NC-10).
+ *
+ * Failure mode (BR-NC-11): SQLite locked / read errors NEVER block the
+ * caller. The telemetry row is still emitted with `error` populated and the
+ * command returns `{ ok: true, impacts_found: 0, error: <msg> }`. Callers
+ * that block on the impact list see "no impacts" and proceed; @neo will
+ * surface "last audit failed" on its next activation by reading the latest
+ * chain_audit event.
+ */
+
+const path = require('node:path');
+const { openRuntimeDb } = require('../runtime-store');
+const { emitChainAuditEvent } = require('../neural-chain-telemetry');
+const { isUnsafePath, sanitizationReason } = require('../neural-chain-sanitize');
+
+const DEFAULT_LIMIT = 20;
+const HARD_LIMIT_CAP = 200;
+
+function normalizeLimit(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_LIMIT;
+  if (parsed > HARD_LIMIT_CAP) return HARD_LIMIT_CAP;
+  return Math.floor(parsed);
+}
+
+async function runChainAudit({ args, options = {}, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const json = Boolean(options.json);
+  const filePath = options.file || args[1];
+  const featureSlug = options.feature ? String(options.feature).trim() : null;
+  const limit = normalizeLimit(options.limit);
+
+  if (!filePath) {
+    const msg = (t && t('chain_audit.file_required')) ||
+      'chain:audit requires a file path. Usage: aioson chain:audit <file> [--limit=N] [--feature=<slug>] [--json]';
+    if (logger && typeof logger.log === 'function' && !json) logger.log(msg);
+    return { ok: false, reason: 'missing_file' };
+  }
+
+  // SF-NC-01/02 Layer B (CLI boundary) — reject unsafe file paths before
+  // they reach SQL bind (which is prepared and safe by itself) AND before
+  // they get rendered into the telemetry payload + logger output. Mirrors
+  // the ingest-side guard in agent-ingest.js#deriveSessionPairs.
+  const filePathReason = sanitizationReason(filePath);
+  if (filePathReason !== null) {
+    const msg = `chain:audit rejected unsafe file path (${filePathReason})`;
+    if (logger && typeof logger.log === 'function' && !json) logger.log(msg);
+    return { ok: false, reason: 'unsafe_file_path', rejection_reason: filePathReason };
+  }
+
+  let dbHandle;
+  try {
+    dbHandle = await openRuntimeDb(targetDir);
+  } catch (err) {
+    const errMsg = err && err.message ? err.message : String(err);
+    if (logger && typeof logger.log === 'function' && !json) {
+      logger.log((t && t('chain_audit.runtime_unavailable', { error: errMsg })) ||
+        `chain:audit runtime db unavailable: ${errMsg}`);
+    }
+    return { ok: false, reason: 'runtime_db_unavailable', error: errMsg };
+  }
+
+  const { db } = dbHandle;
+  const startedAt = Date.now();
+  let impacts = [];
+  let auditError = null;
+
+  try {
+    // BR-NC-01 — window function dedupes per target_path so dual-source edges
+    // (same (source,target) with both git_co_edit AND agent_event) report
+    // max(c_git, c_event) as a single row. Hotfix v1.17.1 — bug-found-002.
+    impacts = db.prepare(`
+      SELECT target_path, edge_type, confidence, hit_count, last_seen_at
+      FROM (
+        SELECT target_path, edge_type, confidence, hit_count, last_seen_at,
+               ROW_NUMBER() OVER (
+                 PARTITION BY target_path
+                 ORDER BY confidence DESC, hit_count DESC, last_seen_at DESC
+               ) AS rn
+        FROM chain_edges
+        WHERE source_path = ? AND end_at IS NULL
+      )
+      WHERE rn = 1
+      ORDER BY confidence DESC, hit_count DESC, last_seen_at DESC
+      LIMIT ?
+    `).all(filePath, limit);
+  } catch (err) {
+    auditError = err && err.message ? err.message : String(err);
+  }
+
+  const durationMs = Date.now() - startedAt;
+
+  emitChainAuditEvent(db, {
+    agent: null,
+    message: `chain:audit ${filePath} → ${auditError ? 'error' : `${impacts.length} impacts`}`,
+    feature_slug: featureSlug,
+    source_files: [filePath],
+    impacts_found: auditError ? null : impacts.length,
+    auto_fixable_count: 0,
+    noise_file: null,
+    tokens_used: 0,
+    duration_ms: durationMs,
+    error: auditError,
+    // Extra context fields
+    limit_applied: limit,
+    // Legacy singular alias preserved for backward-compat (removed v2)
+    source_file: filePath
+  });
+
+  if (auditError) {
+    const msg = (t && t('chain_audit.query_failed', { error: auditError })) ||
+      `chain:audit failed to query chain_edges: ${auditError}`;
+    if (logger && typeof logger.log === 'function' && !json) logger.log(msg);
+    // BR-NC-11: failure non-blocking — still return ok with impacts_found=0
+    return {
+      ok: true,
+      source_file: filePath,
+      impacts_found: 0,
+      duration_ms: durationMs,
+      impacts: [],
+      error: auditError
+    };
+  }
+
+  if (logger && typeof logger.log === 'function' && !json) {
+    if (impacts.length === 0) {
+      logger.log((t && t('chain_audit.no_impacts', { file: filePath, duration: durationMs })) ||
+        `chain:audit ${filePath} → no impacts detected (${durationMs}ms)`);
+    } else {
+      logger.log((t && t('chain_audit.results_header', { file: filePath, count: impacts.length, duration: durationMs })) ||
+        `chain:audit ${filePath} → ${impacts.length} impact(s) (${durationMs}ms):`);
+      for (const row of impacts) {
+        logger.log(`  ${row.target_path} [${row.edge_type}] confidence=${row.confidence.toFixed(2)} hits=${row.hit_count}`);
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    source_file: filePath,
+    impacts_found: impacts.length,
+    duration_ms: durationMs,
+    impacts
+  };
+}
+
+module.exports = { runChainAudit, DEFAULT_LIMIT, HARD_LIMIT_CAP };

package/src/commands/runtime.js

@@ -22,6 +22,7 @@ const { runAutoDelivery } = require('../delivery-runner');
 const { writeHandoff, buildRuntimeLogHandoff } = require('../session-handoff');
 const { backupAiosonDocs, isDocCreatingAgent } = require('../backup-local');
 const { runMemoryReflectPrepare } = require('./memory-reflect-prepare');
+const { runChainHookOnAgentDone } = require('../neural-chain-agent-ingest');
 
 const ALLOWED_LAYOUTS = new Set(['document', 'tabs', 'accordion', 'stack', 'mixed']);
 const DEFAULT_TEXT_FIELDS = ['content', 'text', 'body', 'lyrics', 'markdown'];
@@ -1238,6 +1239,19 @@ async function runAgentDone({ args, options = {}, logger, t }) {
         });
       } catch { /* ignore */ }
 
+      // Neural Chain: best-effort agent_event ingest + per-file audit telemetry.
+      // BR-NC-05 (per-session hook), BR-NC-10 (telemetry obligation), BR-NC-11
+      // (failure non-blocking), EC-NC-05 (no-edits skip path still emits event).
+      try {
+        runChainHookOnAgentDone({
+          db,
+          targetDir,
+          artifacts: artifactPaths,
+          agentName: normalizedAgent,
+          featureSlug: options.feature ? String(options.feature).trim() : null
+        });
+      } catch { /* ignore — never blocks agent_done */ }
+
       return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'live_event', runKey: session.runKey };
     }
 
@@ -1298,6 +1312,19 @@ async function runAgentDone({ args, options = {}, logger, t }) {
       });
     } catch { /* ignore */ }
 
+    // Neural Chain: best-effort agent_event ingest + per-file audit telemetry.
+    // BR-NC-05 (per-session hook), BR-NC-10 (telemetry obligation), BR-NC-11
+    // (failure non-blocking), EC-NC-05 (no-edits skip path still emits event).
+    try {
+      runChainHookOnAgentDone({
+        db,
+        targetDir,
+        artifacts: artifactPaths,
+        agentName: normalizedAgent,
+        featureSlug: options.feature ? String(options.feature).trim() : null
+      });
+    } catch { /* ignore — never blocks agent_done */ }
+
     return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'standalone', runKey, taskKey };
   } finally {
     db.close();

package/src/i18n/messages/en.js

@@ -26,6 +26,15 @@ module.exports = {
       'aioson context:pack [path] [--agent=<agent>] [--goal=<text>] [--module=<module-or-folder>] [--max-files=8] [--json] [--locale=en]',
     help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<name> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=en]',
+    help_chain_audit:
+      'aioson chain:audit <file> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=en]',
+    chain_audit: {
+      file_required: 'chain:audit requires a file path. Usage: aioson chain:audit <file> [--limit=N] [--feature=<slug>] [--json]',
+      runtime_unavailable: 'chain:audit runtime db unavailable: {error}',
+      query_failed: 'chain:audit failed to query chain_edges: {error}',
+      no_impacts: 'chain:audit {file} → no impacts detected ({duration}ms)',
+      results_header: 'chain:audit {file} → {count} impact(s) ({duration}ms):'
+    },
     context_load: {
       target_required: 'context:load requires --target=<rule|brain>:<slug>.',
       agent_required: 'context:load requires --agent=<name>.',

package/src/i18n/messages/es.js

@@ -27,6 +27,15 @@ module.exports = {
       'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-o-carpeta>] [--max-files=8] [--json] [--locale=es]',
     help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nombre> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=es]',
+    help_chain_audit:
+      'aioson chain:audit <archivo> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=es]',
+    chain_audit: {
+      file_required: 'chain:audit requiere una ruta de archivo. Uso: aioson chain:audit <archivo> [--limit=N] [--feature=<slug>] [--json]',
+      runtime_unavailable: 'chain:audit runtime db no disponible: {error}',
+      query_failed: 'chain:audit falló al consultar chain_edges: {error}',
+      no_impacts: 'chain:audit {file} → ningún impacto detectado ({duration}ms)',
+      results_header: 'chain:audit {file} → {count} impacto(s) ({duration}ms):'
+    },
     context_load: {
       target_required: 'context:load requiere --target=<rule|brain>:<slug>.',
       agent_required: 'context:load requiere --agent=<nombre>.',

package/src/i18n/messages/fr.js

@@ -27,6 +27,15 @@ module.exports = {
       'aioson context:pack [path] [--agent=<agent>] [--goal=<texte>] [--module=<module-ou-dossier>] [--max-files=8] [--json] [--locale=fr]',
     help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nom> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=fr]',
+    help_chain_audit:
+      'aioson chain:audit <fichier> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=fr]',
+    chain_audit: {
+      file_required: 'chain:audit exige un chemin de fichier. Usage : aioson chain:audit <fichier> [--limit=N] [--feature=<slug>] [--json]',
+      runtime_unavailable: 'chain:audit runtime db indisponible : {error}',
+      query_failed: 'chain:audit échec de la requête chain_edges : {error}',
+      no_impacts: 'chain:audit {file} → aucun impact détecté ({duration}ms)',
+      results_header: 'chain:audit {file} → {count} impact(s) ({duration}ms) :'
+    },
     context_load: {
       target_required: 'context:load exige --target=<rule|brain>:<slug>.',
       agent_required: 'context:load exige --agent=<nom>.',

package/src/i18n/messages/pt-BR.js

@@ -27,6 +27,15 @@ module.exports = {
       'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-ou-pasta>] [--max-files=8] [--json] [--locale=pt-BR]',
     help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nome> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=pt-BR]',
+    help_chain_audit:
+      'aioson chain:audit <arquivo> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=pt-BR]',
+    chain_audit: {
+      file_required: 'chain:audit exige um caminho de arquivo. Uso: aioson chain:audit <arquivo> [--limit=N] [--feature=<slug>] [--json]',
+      runtime_unavailable: 'chain:audit runtime db indisponível: {error}',
+      query_failed: 'chain:audit falhou ao consultar chain_edges: {error}',
+      no_impacts: 'chain:audit {file} → nenhum impacto detectado ({duration}ms)',
+      results_header: 'chain:audit {file} → {count} impacto(s) ({duration}ms):'
+    },
     context_load: {
       target_required: 'context:load exige --target=<rule|brain>:<slug>.',
       agent_required: 'context:load exige --agent=<nome>.',