0xray 4.0.34 → 4.0.35

package/dist/nucleus/delegation-gate.js

@@ -1,7 +1,7 @@
 /**
  * Multi-host delegation gate SSOT — pending-delegations + spawn todo enforcement.
  * Grok / Hermes / OpenCode adapters call evaluatePreToolGate via delegation-gate-runtime.
- * Constitution (11/29/69 + destructive shell) lives here. Grok may still extra-block Codex 2/7.
+ * Constitution (11/29/69/70 + destructive shell) lives here. Grok may still extra-block Codex 2/7.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -11,6 +11,7 @@ import { allPlanTodos, areSynthesisConsultTodosComplete, findRecentStalePlanArch
 import { getSynthesisDueReason, isSynthesisCheckpointDue, recordExecutionSlice, } from './synthesis.js';
 import { isSynthesisConsultTodoId, tryRecordSynthesisConsultReceipt, } from './synthesis-consult-receipt.js';
 import { resolveSpawnPlan, hasValidSpawnPlanContext } from './spawn-plan-resolution.js';
+import { probeFreshness } from './work-freshness.mjs';
 import { isUserAsidesEnabled, isUserAsideTodoId, loadActiveAsidePointer, loadActiveUserAside, } from './user-aside.js';
 import { validateAsideWorktreeCwd, } from './aside-worktree.js';
 import { ceremonyForProfile, resolveSuitProfile, spawnPlanModeForProfile, writeSuitSessionBoot, maybeHeatHostStation, } from './suit-temperament.js';
@@ -416,11 +417,21 @@ function collectWritePaths(toolInput) {
     }
     return paths;
 }
-/** Codex 11 / 29 / 69 + destructive shell — always on, all hosts that call this SSOT. */
+/** Codex 11 / 29 / 69 / 70 + destructive shell — always on, all hosts that call this SSOT. */
 export function evaluateConstitutionGate(toolName, toolInput, ctx) {
     const content = collectWriteContent(toolInput);
     const paths = collectWritePaths(toolInput);
     const writing = isWriteTool(toolName, ctx.host ?? 'generic');
+    if (writing) {
+        const freshness = probeFreshness(ctx.projectRoot);
+        if (freshness.stale) {
+            return {
+                allow: false,
+                reason: freshness.reason,
+                gate: 'codex-70',
+            };
+        }
+    }
     if (writing && ctx.features.no_new_surface !== false) {
         for (const p of paths) {
             const normalized = p.replace(/\\/g, '/');

package/dist/nucleus/work-freshness.mjs

@@ -0,0 +1,189 @@
+/**
+ * Codex 70. An edit waits until this copy is on the latest main
+ * and the package is not older than the published one.
+ * This repo is that package when package.json name is 0xray.
+ * The check is saved at session start. The edit gate reads the saved result.
+ * A temp directory inside a repo is not the workspace, so unit tests stay quiet.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export function compareVersions(left, right) {
+  const a = String(left).split('.').map((part) => parseInt(part, 10) || 0);
+  const b = String(right).split('.').map((part) => parseInt(part, 10) || 0);
+  const length = Math.max(a.length, b.length);
+  for (let i = 0; i < length; i += 1) {
+    const da = a[i] || 0;
+    const db = b[i] || 0;
+    if (da !== db) return da < db ? -1 : 1;
+  }
+  return 0;
+}
+
+export function decideFreshness(input) {
+  const behind = Number(input.behind) || 0;
+  if (behind > 0) {
+    const commits = behind === 1 ? '1 commit' : `${behind} commits`;
+    return {
+      stale: true,
+      reason: `Codex 70: this copy is ${commits} behind main. Update before you edit. Compare set-aside work to main before you throw it away.`,
+    };
+  }
+  const repoVersion = input.repoName === '0xray' ? input.repoVersion || null : null;
+  const worn = input.wornSuit || repoVersion;
+  const published = input.publishedSuit || null;
+  const target = published || repoVersion;
+  if (target && worn && compareVersions(worn, target) < 0) {
+    return {
+      stale: true,
+      reason: `Codex 70: package ${worn} is older than ${target}. Install the current one before you edit.`,
+    };
+  }
+  return { stale: false, reason: '' };
+}
+
+export function describeFreshness(input) {
+  const behind = Number(input.behind) || 0;
+  const parts = [behind > 0 ? `${behind} behind main` : 'up to date'];
+  if (input.wornSuit) parts.push(`package ${input.wornSuit}`);
+  if (input.publishedSuit) parts.push(`published ${input.publishedSuit}`);
+  const stashCount = Number(input.stashCount) || 0;
+  if (stashCount > 0) parts.push(`${stashCount} set aside, compare before drop`);
+  return `Fresh: ${parts.join('. ')}.`;
+}
+
+function run(cmd, args, cwd, timeout) {
+  return execFileSync(cmd, args, {
+    cwd,
+    encoding: 'utf8',
+    timeout,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+}
+
+function gitTop(cwd) {
+  try {
+    return run('git', ['rev-parse', '--show-toplevel'], cwd, 3000);
+  } catch {
+    return null;
+  }
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function wornSuitVersion(projectRoot, opts = {}) {
+  if (projectRoot) {
+    const local = readJson(join(projectRoot, 'node_modules', '0xray', 'package.json'));
+    if (local && local.version) return String(local.version);
+  }
+  const candidates = [
+    '/opt/homebrew/lib/node_modules/0xray/package.json',
+    '/usr/local/lib/node_modules/0xray/package.json',
+  ];
+  for (const file of candidates) {
+    const pkg = readJson(file);
+    if (pkg && pkg.version) return String(pkg.version);
+  }
+  if (!opts.liveGlobal) return null;
+  try {
+    const root = run('npm', ['root', '-g'], projectRoot || process.cwd(), 8000);
+    const pkg = readJson(join(root, '0xray', 'package.json'));
+    return pkg && pkg.version ? String(pkg.version) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readWorkSnapshot(projectRoot) {
+  const top = gitTop(projectRoot);
+  let behind = 0;
+  let stashCount = 0;
+  if (top && resolve(top) === resolve(projectRoot)) {
+    try {
+      behind = Number(run('git', ['rev-list', '--count', 'HEAD..origin/main'], projectRoot, 4000)) || 0;
+    } catch {
+      behind = 0;
+    }
+    try {
+      const list = run('git', ['stash', 'list'], projectRoot, 4000);
+      stashCount = list ? list.split('\n').filter(Boolean).length : 0;
+    } catch {
+      stashCount = 0;
+    }
+  }
+  const repo = readJson(join(projectRoot, 'package.json'));
+  const saved = readJson(join(projectRoot, '.xray', 'state', 'freshness.json'));
+  return {
+    behind,
+    stashCount,
+    repoName: repo && repo.name ? String(repo.name) : null,
+    repoVersion: repo && repo.version ? String(repo.version) : null,
+    wornSuit: wornSuitVersion(projectRoot),
+    publishedSuit: saved && saved.publishedSuit ? String(saved.publishedSuit) : null,
+  };
+}
+
+function freshnessFile(projectRoot) {
+  return join(projectRoot, '.xray', 'state', 'freshness.json');
+}
+
+export function readSavedFreshness(projectRoot) {
+  const saved = readJson(freshnessFile(projectRoot));
+  return saved ? describeFreshness(saved) : null;
+}
+
+export function probeFreshness(projectRoot) {
+  const saved = readJson(freshnessFile(projectRoot));
+  if (saved && saved.behind != null) return decideFreshness(saved);
+  return decideFreshness(readWorkSnapshot(projectRoot));
+}
+
+export function refreshFreshness(projectRoot) {
+  const top = gitTop(projectRoot);
+  if (top && resolve(top) === resolve(projectRoot)) {
+    try {
+      run('git', ['fetch', 'origin', '--prune'], projectRoot, 8000);
+    } catch {
+      /* offline fetch must not block the boot */
+    }
+  }
+  let publishedSuit = null;
+  try {
+    publishedSuit = run('npm', ['view', '0xray', 'version'], projectRoot, 8000);
+  } catch {
+    publishedSuit = null;
+  }
+  const snapshot = readWorkSnapshot(projectRoot);
+  if (publishedSuit) snapshot.publishedSuit = publishedSuit;
+  if (snapshot.repoName === '0xray' && snapshot.repoVersion) {
+    snapshot.wornSuit = snapshot.repoVersion;
+  } else {
+    const globalWorn = wornSuitVersion(projectRoot, { liveGlobal: true });
+    if (globalWorn) snapshot.wornSuit = globalWorn;
+  }
+  try {
+    const dir = join(projectRoot, '.xray', 'state');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(freshnessFile(projectRoot), `${JSON.stringify({
+      publishedSuit: snapshot.publishedSuit,
+      wornSuit: snapshot.wornSuit,
+      behind: snapshot.behind,
+      stashCount: snapshot.stashCount,
+      checkedAt: new Date().toISOString(),
+    }, null, 2)}\n`);
+  } catch {
+    /* the gate still reads git and the worn package */
+  }
+  return {
+    ...snapshot,
+    freshnessLine: describeFreshness(snapshot),
+  };
+}

package/dist/processors/implementations/agents-md-validation-processor.js

@@ -224,7 +224,7 @@ export class AgentsMdValidationProcessor {
                 "",
                 "## Codex",
                 "",
-                `0xRay enforces Universal Development Codex (69 terms) for systematic error prevention.`,
+                `0xRay enforces Universal Development Codex (70 terms) for systematic error prevention.`,
                 "",
             ].join("\n"),
             "## CLI Commands": [

package/docs-site/docs/plates/boot.md

@@ -20,6 +20,11 @@ sidebar_label: Boot
 ┌─────────────────────────────┼──────────────────────────────┐
 │ PROCESSING LAYER            v                              │
 │   ┌────────────────────────────────────────────────────┐  │
+│   │ memory monitoring                                  │  │
+│   │ setupMemoryMonitoring                              │  │
+│   └──────────────────────────┬─────────────────────────┘  │
+│                              v                            │
+│   ┌────────────────────────────────────────────────────┐  │
 │   │ load .xray config                                  │  │
 │   └──────────────────────────┬─────────────────────────┘  │
 │                              v                            │
@@ -33,12 +38,22 @@ sidebar_label: Boot
 │                              v                            │
 │   ┌────────────────────────────────────────────────────┐  │
 │   │ activateProcessors (PROCESSOR_DEFS)                │  │
-│   │ legacy boot list, then agents and plugins          │  │
+│   └──────────────────────────┬─────────────────────────┘  │
+│                              v                            │
+│   ┌────────────────────────────────────────────────────┐  │
+│   │ processor health                                   │  │
+│   │ validateProcessorHealth                            │  │
+│   └──────────────────────────┬─────────────────────────┘  │
+│                              v                            │
+│   ┌────────────────────────────────────────────────────┐  │
+│   │ agents and plugins                                 │  │
+│   │ loadRemainingAgents · initializePluginSystem       │  │
 │   └──────────────────────────┬─────────────────────────┘  │
 │                              v                            │
 │   ┌────────────────────────────────────────────────────┐  │
 │   │ enforcement · codex compliance                     │  │
-│   │ Dynamo governance integration                      │  │
+│   │ finalizeSecurityIntegration                        │  │
+│   │ governance init when that flag is not false        │  │
 │   └──────────────────────────┬─────────────────────────┘  │
 └──────────────────────────────┼────────────────────────────┘
                                v

package/docs-site/docs/plates/governance.md

@@ -5,7 +5,7 @@ sidebar_label: Governance
 
 # Governance
 
-A proposal is deliberated inside the suit, filtered by Dynamo Solar, then merged. The PreToolUse codex gate stands beside the vote.
+A proposal is deliberated inside the suit, filtered by Dynamo Solar, then merged. The vote is approve, reject, or needs_revision. The PreToolUse codex gate stands beside the vote.
 
 ```
 ┌────────────────────────────────────────────────────────────┐
@@ -44,7 +44,8 @@ A proposal is deliberated inside the suit, filtered by Dynamo Solar, then merged
 │ OUTPUT LAYER                 v                            │
 │   ┌──────────────────────┐      ┌──────────────────────┐ │
 │   │ vote                 │      │ codex decision       │ │
-│   │ approve / reject     │      │ allow / deny         │ │
+│   │ approve / reject /   │      │ allow / deny         │ │
+│   │ needs_revision       │      │                      │ │
 │   └──────────────────────┘      └──────────────────────┘ │
 └────────────────────────────────────────────────────────────┘
 ```

package/docs-site/docs/plates/index.md

@@ -23,6 +23,8 @@ Plates have a type. A domain model plate shows how named parts fit. A state flow
 
 [House](./house.md)
 
-## Not yet typed
+## Pipeline
 
 [Routing](./routing.md) · [Governance](./governance.md) · [Boot](./boot.md) · [Orchestration](./orchestration.md) · [Processor](./processor.md) · [Reporting](./reporting.md) · [Memory recall](./memory-recall.md)
+
+These seven are the lens planes. Each drawing is an input layer, a processing layer, and an output layer. Ground has no plate file.

package/docs-site/docs/plates/memory-recall.md

@@ -5,45 +5,36 @@ sidebar_label: Memory recall
 
 # Memory recall
 
-Speech becomes a lesson. Intent names one plate. Compact points at the station card. The card names the stamp. The stamp file is the schematic.
+Intent names one plate. Equal top scores recall nothing. A missing worn copy is stamped from the docs plate. An edited copy stays.
 
 ```
 ┌──────────────────────────────────────────────────────────────┐
 │ INPUT LAYER                                                  │
 │                                                              │
-│   ┌──────────────┐   ┌──────────────┐   ┌────────────────┐  │
-│   │ speech       │   │ intent       │   │ compact cut    │  │
-│   └──────┬───────┘   └──────┬───────┘   └───────┬────────┘  │
-└──────────┼──────────────────┼───────────────────┼───────────┘
-           v                  v                   v
-┌──────────┼──────────────────┼───────────────────┼───────────┐
-│ PROCESSING LAYER             │                   │           │
-│          v                  v                   v           │
-│   ┌──────────────┐   ┌──────────────┐   ┌────────────────┐ │
-│   │ speech grades│   │ intent       │   │ compact says   │ │
-│   │ to a lesson  │   │ recalls one  │   │ Read STATION.md│ │
-│   │ on a signal  │   │ plate        │   │                │ │
-│   └──────┬───────┘   └──────┬───────┘   └───────┬────────┘ │
-│          │                  │                   │          │
-│          │                  v                   │          │
-│          │     ┌────────────────────────────┐   │          │
-│          │     │ card keeps the short       │   │          │
-│          │     │ subsystem table            │   │          │
-│          │     │ card names Plate: <id>     │   │          │
-│          │     └─────────────┬──────────────┘   │          │
-└──────────┼───────────────────┼──────────────────┼──────────┘
-           v                   v                  v
-┌──────────┴───────────────────┴──────────────────┴──────────┐
-│ OUTPUT LAYER                                               │
-│                                                            │
-│   ┌────────────────────────────┐  ┌─────────────────────┐ │
-│   │ lesson on the signal       │  │ stamp file          │ │
-│   │ an episode of what happened│  │ the schematic       │ │
-│   └────────────────────────────┘  │ docs-site/docs/     │ │
-│                                   │ plates/<id>.md      │ │
-│                                   │ worn copy only when │ │
-│                                   │ .xray/state/plates/ │ │
-│                                   │ <id>.md is missing  │ │
-│                                   └─────────────────────┘ │
+│   ┌──────────────────────────────────────────────────────┐  │
+│   │ intent                                               │  │
+│   └──────────────────────────┬───────────────────────────┘  │
+└──────────────────────────────┼──────────────────────────────┘
+                               v
+┌──────────────────────────────┼──────────────────────────────┐
+│ PROCESSING LAYER             v                              │
+│   ┌──────────────────────────────────────────────────────┐  │
+│   │ score cues                                           │  │
+│   │ one winner loads that plate                          │  │
+│   │ a tie returns nothing                                │  │
+│   └──────────────────────────┬───────────────────────────┘  │
+│                              v                              │
+│   ┌──────────────────────────────────────────────────────┐  │
+│   │ stampPlateIfMissing                                  │  │
+│   │ writes .xray/state/plates only when that file        │  │
+│   │ is missing                                           │  │
+│   └──────────────────────────┬───────────────────────────┘  │
+└──────────────────────────────┼──────────────────────────────┘
+                               v
+┌──────────────────────────────┼──────────────────────────────┐
+│ OUTPUT LAYER                 v                              │
+│   ┌────────────────────┐        ┌────────────────────────┐ │
+│   │ plate line         │        │ stamp file             │ │
+│   └────────────────────┘        └────────────────────────┘ │
 └──────────────────────────────────────────────────────────────┘
 ```

package/docs-site/docs/plates/orchestration.md

@@ -5,51 +5,55 @@ sidebar_label: Orchestration
 
 # Orchestration
 
-Multi-step work is planned, run, and closed. Routing picks an agent. This plate is the coordination around that pick.
+Each tool is its own call. `spawnAside` opens around `orchestrate-task`, `analyze-complexity`, and `govern-and-apply`. `closeAside` runs when that call returns.
 
 ```
 ┌────────────────────────────────────────────────────────────┐
 │ INPUT LAYER                                                │
 │                                                            │
-│   ┌────────────────────────────────────────────────────┐  │
-│   │ tasks                                              │  │
-│   │ descriptions · dependencies · type                 │  │
-│   └──────────────────────────┬─────────────────────────┘  │
-└──────────────────────────────┼────────────────────────────┘
-                               v
-┌──────────────────────────────┼────────────────────────────┐
-│ PROCESSING LAYER             v                            │
-│   ┌────────────────────────────────────────────────────┐  │
-│   │ analyze-complexity                                 │  │
-│   │ ExecutionPlanner validates and plans               │  │
-│   └──────────────────────────┬─────────────────────────┘  │
-│                              v                            │
-│   ┌────────────────────────────────────────────────────┐  │
-│   │ orchestrate-task                                   │  │
-│   │ lead stays on the main thread                      │  │
-│   └──────────────────────────┬─────────────────────────┘  │
-│                              v                            │
-│   ┌────────────────────────────────────────────────────┐  │
-│   │ spawnAside                                         │  │
-│   │ on orchestrate-task, analyze-complexity,           │  │
-│   │ and govern-and-apply                               │  │
-│   │ observations from the three flows                  │  │
-│   └──────────────────────────┬─────────────────────────┘  │
-│                              v                            │
-│   ┌────────────────────────────────────────────────────┐  │
-│   │ confidence gate                                    │  │
-│   │ getTaskConfidence when Repertoire is worn          │  │
-│   └──────────────────────────┬─────────────────────────┘  │
-│                              v                            │
-│   ┌────────────────────────────────────────────────────┐  │
-│   │ closeAside                                         │  │
-│   └──────────────────────────┬─────────────────────────┘  │
+│   ┌──────────────────────┐      ┌──────────────────────┐  │
+│   │ tool name            │      │ arguments            │  │
+│   └──────────┬───────────┘      └──────────┬───────────┘  │
+└──────────────┼─────────────────────────────┼──────────────┘
+               v                             v
+┌──────────────┼─────────────────────────────┼──────────────┐
+│ PROCESSING LAYER                            │              │
+│              v                             v              │
+│   ┌────────────────────────────────────────────────────┐ │
+│   │ orchestrate-task                                   │ │
+│   │ spawnAside · handleOrchestrateTask · closeAside    │ │
+│   └──────────────────────────┬─────────────────────────┘ │
+│                              v                           │
+│   ┌────────────────────────────────────────────────────┐ │
+│   │ analyze-complexity                                 │ │
+│   │ a due synthesis checkpoint can return first        │ │
+│   │ spawnAside · handleAnalyzeComplexity · closeAside  │ │
+│   └──────────────────────────┬─────────────────────────┘ │
+│                              v                           │
+│   ┌────────────────────────────────────────────────────┐ │
+│   │ govern-and-apply                                   │ │
+│   │ a due synthesis checkpoint blocks first            │ │
+│   │ spawnAside · governExternalProposals · closeAside  │ │
+│   └──────────────────────────┬─────────────────────────┘ │
+│                              v                           │
+│   ┌────────────────────────────────────────────────────┐ │
+│   │ get-orchestration-status                           │ │
+│   └──────────────────────────┬─────────────────────────┘ │
+│                              v                           │
+│   ┌────────────────────────────────────────────────────┐ │
+│   │ cancel-orchestration                               │ │
+│   │ closeAside on a forced cancel or a matching session│ │
+│   └──────────────────────────┬─────────────────────────┘ │
+│                              v                           │
+│   ┌────────────────────────────────────────────────────┐ │
+│   │ optimize-orchestration                             │ │
+│   └──────────────────────────┬─────────────────────────┘ │
 └──────────────────────────────┼────────────────────────────┘
                                v
 ┌──────────────────────────────┼────────────────────────────┐
 │ OUTPUT LAYER                 v                            │
 │   ┌─────────────────────┐    ┌─────────────────────────┐ │
-│   │ execution result    │    │ aside observations      │ │
+│   │ tool result         │    │ aside id                │ │
 │   └─────────────────────┘    └─────────────────────────┘ │
 └────────────────────────────────────────────────────────────┘
 ```

package/docs-site/docs/plates/processor.md

@@ -5,42 +5,40 @@ sidebar_label: Processor
 
 # Processor
 
-Three pipelines run in parallel. A is the live suit. B is the legacy processor manager. C is mill, git, and CI. Nothing in A is an input to B or C.
+`ProcessorManager` runs the enabled pre processors, then the enabled post processors. Prompt text longer than 10 characters is checked inside the pre pass.
 
 ```
-┌────────────────────────────────────────────────────────────────────────┐
-│ INPUT LAYER                                                            │
-│                                                                        │
-│   ┌──────────────────┐  ┌──────────────────┐  ┌────────────────────┐  │
-│   │ tool / session   │  │ prompt text      │  │ commit / release   │  │
-│   └────────┬─────────┘  └────────┬─────────┘  └─────────┬──────────┘  │
-└────────────┼─────────────────────┼──────────────────────┼─────────────┘
-             v                     v                      v
-┌────────────┼─────────────────────┼──────────────────────┼─────────────┐
-│ PROCESSING LAYER   three parallel pipelines             │             │
-│            │                     │                      │             │
-│  ┌─────────┴──────────┐ ┌────────┴─────────┐ ┌──────────┴──────────┐ │
-│  │ A suit (live OS)   │ │ B legacy manager │ │ C mill / git / CI   │ │
-│  │                    │ │                  │ │                     │ │
-│  │ SessionStart       │ │ prompt-security  │ │ mint                │ │
-│  │        v           │ │        v         │ │        v            │ │
-│  │ PreToolUse         │ │ executePre       │ │ inspect             │ │
-│  │        v           │ │        v         │ │        v            │ │
-│  │ tool runs          │ │ work             │ │ pre-commit          │ │
-│  │        v           │ │        v         │ │        v            │ │
-│  │ PostToolUse        │ │ executePost      │ │ pre-push            │ │
-│  │        v           │ │                  │ │        v            │ │
-│  │ compact heat       │ │                  │ │ foundry release     │ │
-│  │                    │ │                  │ │        v            │ │
-│  │                    │ │                  │ │ CI quality → docs   │ │
-│  └─────────┬──────────┘ └────────┬─────────┘ └──────────┬──────────┘ │
-└────────────┼─────────────────────┼──────────────────────┼────────────┘
-             v                     v                      v
-┌────────────┴─────────────────────┴──────────────────────┴────────────┐
-│ OUTPUT LAYER                                                          │
-│                                                                       │
-│   ┌──────────────────┐  ┌──────────────────┐  ┌────────────────────┐ │
-│   │ allow / deny     │  │ processor result │  │ gate / tag         │ │
-│   └──────────────────┘  └──────────────────┘  └────────────────────┘ │
-└────────────────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────┐
+│ INPUT LAYER                                                  │
+│                                                              │
+│   ┌──────────────┐   ┌──────────────┐   ┌────────────────┐  │
+│   │ tool         │   │ args         │   │ operation      │  │
+│   └──────┬───────┘   └──────┬───────┘   └───────┬────────┘  │
+└──────────┼──────────────────┼───────────────────┼───────────┘
+           v                  v                   v
+┌──────────┼──────────────────┼───────────────────┼───────────┐
+│ PROCESSING LAYER             │                   │           │
+│          v                  v                   v           │
+│   ┌──────────────────────────────────────────────────────┐ │
+│   │ executePreProcessors                                 │ │
+│   │ prompt-security-validator when the prompt is longer  │ │
+│   │ than 10 characters                                   │ │
+│   │ enabled pre processors, by priority                  │ │
+│   └──────────────────────────┬───────────────────────────┘ │
+│                              v                             │
+│   ┌──────────────────────────────────────────────────────┐ │
+│   │ executePostProcessors                                │ │
+│   │ enabled post processors, by priority                 │ │
+│   │ a stagger waits out its minimum interval             │ │
+│   │ pre results are passed in                            │ │
+│   └──────────────────────────┬───────────────────────────┘ │
+└──────────────────────────────┼──────────────────────────────┘
+                               v
+┌──────────────────────────────┼──────────────────────────────┐
+│ OUTPUT LAYER                 v                              │
+│   ┌──────────────────────────┐   ┌───────────────────────┐ │
+│   │ pre result               │   │ post results          │ │
+│   │ success and results      │   │                       │ │
+│   └──────────────────────────┘   └───────────────────────┘ │
+└──────────────────────────────────────────────────────────────┘
 ```

package/docs-site/docs/plates/reporting.md

@@ -5,7 +5,7 @@ sidebar_label: Reporting
 
 # Reporting
 
-Logs become a report. Session start can also drop a schedule marker. The marker is a side output, not a second chain through the formatter.
+Logs become a report. A valid cache returns the formatted report and does not write the file again.
 
 ```
 ┌────────────────────────────────────────────────────────────┐
@@ -22,14 +22,9 @@ Logs become a report. Session start can also drop a schedule marker. The marker
 │   ┌────────────────────────────────────────────────────┐  │
 │   │ FrameworkReportingSystem                           │  │
 │   │ collect logs → metrics → formatReport              │  │
-│   │ cache a fresh report, then write the file          │  │
+│   │ cache the fresh report                             │  │
+│   │ write the file when outputPath is set              │  │
 │   └──────────────────────────┬─────────────────────────┘  │
-│                              │                            │
-│   ┌──────────────────────────┼─────────────────────────┐  │
-│   │ SessionStart marker      │                         │  │
-│   │ autonomous-reporting     │  side output            │  │
-│   │ scheduled flag           │                         │  │
-│   └──────────────────────────┼─────────────────────────┘  │
 └──────────────────────────────┼────────────────────────────┘
                                v
 ┌──────────────────────────────┼────────────────────────────┐