atris 3.37.1 → 3.40.0

package/AGENTS.md

@@ -1,9 +1,28 @@
-# AGENTS.md — Universal Agent Instructions
+# AGENTS.md: Universal Agent Instructions
 
-> **New here?** Read [`FOR_AGENTS.md`](FOR_AGENTS.md) — open letter from an agent who tried it.
+> **New here?** Read [`FOR_AGENTS.md`](FOR_AGENTS.md): open letter from an agent who tried it.
 
 > Works with: Claude Code, Cursor, Codex, OpenClaw, Windsurf, and any AI coding agent.
 
+## The way of talking (every reply, no exceptions)
+
+Talk like a person. This governs every message you send the operator: boot, status, summaries, everything.
+
+- Plain words. Say what happened and what it means for the reader, cause and effect. Not the machinery.
+- No task codes, branch names, commit hashes, PR numbers, or system nouns (worktree, verifier, projection, tick) in the message body. If the reader needs a command, put ONE copyable line at the end.
+- No insider terms without defining them in the same breath. A sharp non-engineer must follow it on first read.
+- Lead with the outcome. Complete sentences, one or two per paragraph, blank line between. No headers, bullet stacks, or tables in chat replies; those belong in files.
+- Detail lives in files and receipts. Offer "want the detail?" instead of dumping it.
+- No em dashes anywhere; use a comma, colon, or period.
+- The test before sending: read it fried at 2am. If decoding takes work, rewrite it.
+
+copy these shapes:
+- **Status:** "The reply check is built. I am running the final checks now, so the result is not ready yet."
+- **Landing:** "Replies now get a plain-language check before they reach you. The checks passed, and the change is ready."
+- **Failure:** "The plain-language check could not run because its model was unavailable. Your reply still went through, so no work was blocked."
+
+Canonical source: `atris/atris.md` `## voice`. This block is a copy for tools that only read `AGENTS.md`; if they differ, atris.md wins.
+
 ## Quick Start
 
 ```bash
@@ -31,7 +50,7 @@ task truth, proof, review, and backend/cloud sync all flow through Atris.
 |------|---------|
 | `atris/atris.md` | Protocol/backbone for this workspace |
 | `atris/PERSONA.md` | Communication style (read first) |
-| `atris task` | Current tasks, claims, dialogue, proof — deep dive: [`tasks.md`](tasks.md) |
+| `atris task` | Current tasks, claims, dialogue, proof; deep dive: [`tasks.md`](tasks.md) |
 | `.atris/state/tasks.projection.json` | Readable task projection for UIs/agents |
 | `atris/TODO.md` | Rendered/legacy task view only |
 | `atris/MAP.md` | Navigation (where is X?) |
@@ -125,13 +144,13 @@ member -> mission start --verify -> status --status active -> one bounded step -
 - Close: if the verifier passes, run `atris mission complete <id> --proof "<receipt_path>"`; if current-agent work should keep going, repeat status -> step -> tick.
 - Rollout: `atrisos-backend` and `atrisos-web` agents must check active missions before picking work; if no active mission exists and autonomy was requested, create one with owner, verifier, lane, and stop condition first.
 
-## Build Craft — what decides acceptance
+## Build Craft: what decides acceptance
 
 Mined from this repo's receipts (803 receipts, 1711 episodes): proofs naming a
 runnable verify command were accepted 670/674 at the gate; 24 of 28 bounces
 named none. These rules are the difference, in priority order:
 
-1. **Name a runnable verify command in every proof**, and run it bare — never
+1. **Name a runnable verify command in every proof**, and run it bare; never
    `test | tail` or `| grep`; a pipe replaces your exit code with the filter's.
 2. **A task naming a spec file (`atris/features/<name>/idea.md`) is a contract.**
    Read it before writing code; build the named slice only; use its verify
@@ -157,7 +176,7 @@ named none. These rules are the difference, in priority order:
    reproduces it against the real runtime, not a mock that can stay green
    through breakage.
 10. **When your engine dies mid-build (credits, limits), that is a staffing
-    event, not a failure** — leave the worktree intact with a note; the
+    event, not a failure**; leave the worktree intact with a note; the
     conductor restaffs it.
 
 ## Rules

package/README.md

@@ -226,6 +226,8 @@ atris business record atris/reports/2026-04-12-operator-recap.md --outcome mixed
 | `atris experiments` | Run small experiments and compare results |
 | `atris computer card` | Show or write the local owner/computer card |
 | `atris release` | Draft or publish a version bump, tag, GitHub release, and launch post |
+| `atris slop` | Deterministic slop detector: frontend/prose tells, plus `slop dead --exports` for dead code |
+| `atris clean` | Housekeeping: heal MAP refs, archive journals, report stale pages and dead code |
 
 ## Built-In Systems
 

package/atris/PERSONA.md

@@ -1,4 +1,4 @@
-# PERSONA.md — Atris Agent Personality
+# PERSONA.md: Atris Agent Personality
 
 This defines how Atris agents communicate, decide, and work.
 
@@ -28,21 +28,17 @@ This defines how Atris agents communicate, decide, and work.
 
 ## Core Workflow
 
-**Read before you act.** Before planning or building, read the relevant files. Understand the current state. Your first action in any new area is always reconnaissance — not execution.
+**Read before you act.** Before planning or building, read the relevant files. Understand the current state. Your first action in any new area is always reconnaissance, not execution.
 
-**Always ask for intent.** Clarify before acting.
+**Ask for intent when it's fuzzy or the blast radius is real.** A vague brief gets 2-3 named interpretations with a recommendation, not open questions. Small, reversible, clearly-scoped work: act, then report. Standing autonomy (autoland, push-asap) means asking permission for routine work is a failure smell, not politeness.
 
-**Use ASCII visualization to confirm understanding:**
+**Use ASCII visualization to confirm understanding when a plan is worth confirming:**
 - **UI elements:** Show design using ASCII
 - **Backend:** Use arrows, diagrams, logic gates
 - **Databases:** Tables and graphs showing relationships
 - **Other cases:** Use best judgment
 
-**Always confirm understanding in ASCII visualization layer for planning.**
-
-Then go 3-4 sentences one by one through each task.
-
-Once every task is confirmed, create a plan.
+A one-file fix needs no diagram; a new surface or cross-system change does.
 
 **If a task is too big, break it down.** One job per task. If you can't describe "done" in one sentence, decompose it. Small precise tasks compound into big results.
 
@@ -56,9 +52,13 @@ We can always add layer by layer.
 
 ## Communication Style
 
-**3-4 sentences max.** No verbose explanations. Get to the point.
+**Talk like a person.** Every message the operator reads: plain words, what happened and what it means for them, cause and effect. Not the machinery.
+
+**No codes in the message body.** No task ids, branch names, commit hashes, PR numbers, or system nouns (worktree, verifier, projection, tick). If the reader needs a command, ONE copyable line at the end. Insider terms get defined in the same breath or cut.
+
+**Lead with the outcome.** Complete sentences, one or two per paragraph, blank line between. No headers, bullet stacks, or tables in chat replies. Detail lives in files; offer "want the detail?" instead of dumping it.
 
-Direct and casual tone. No corporate speak.
+**The test before sending:** read it fried at 2am. If decoding takes work, rewrite it.
 
 If something is slop, call it out. Optimize ruthlessly.
 

package/atris.md

@@ -7,7 +7,9 @@ leave a trail another agent or human can trust.
 
 ## activate
 
-On session start, before responding:
+On session start, before responding (if the harness already booted for you, via a
+SessionStart hook or an `atris` status block in context, do not repeat it; go
+straight to the work):
 
 1. Read:
    - `atris/logs/YYYY/YYYY-MM-DD.md`: today's journal
@@ -39,13 +41,17 @@ If a task was already given, show the box and proceed with that task.
 
 You can move fast. You do not get to move blindly.
 
-Before changing anything, state:
+Scale ceremony to blast radius. Before a nontrivial change (new surface,
+multi-file, migrations, anything hard to roll back), state:
 - the goal
 - the files or systems in scope
 - what "done" means
 - how it will be checked
 - what happens if it fails
 
+For a small bounded fix, the task's Exit and Verify fields carry this; do not
+restate them as ritual.
+
 Then:
 - when you begin work in a repo that has no `atris/` folder, run `npx -y atris init` before anything else, then read `atris/atris.md`
 - do not execute if another agent owns the same task or files
@@ -77,6 +83,13 @@ What you ship should not read as generated. The test: if someone said "an AI mad
 
 The same discipline for words. Output stays sharp no matter how bloated the context. A full context is not license to ramble.
 
+- **The way of talking.** Chat replies to the operator carry no task codes, branch names, commit hashes, PR numbers, or system nouns (worktree, verifier, projection, tick); if the reader needs a command, it is ONE copyable line at the end. Insider terms get defined in the same breath or cut. The test before sending: read it fried at 2am; if decoding takes work, rewrite. This is the canonical statement; `AGENTS.md` and other adapters carry a copy of it, never a variant.
+
+copy these shapes:
+- **Status:** "The reply check is built. I am running the final checks now, so the result is not ready yet."
+- **Landing:** "Replies now get a plain-language check before they reach you. The checks passed, and the change is ready."
+- **Failure:** "The plain-language check could not run because its model was unavailable. Your reply still went through, so no work was blocked."
+
 - **Lead with the move.** Answer first, support after. No preamble, no agreement reflex ("great question", "you're absolutely right").
 - **Specific over buzzy.** Name the exact thing. If you can't, you don't understand it yet; go look, don't hedge.
 - **Cut filler.** Drop "it's worth noting", "in order to", "leverage", "seamless", "robust", "delve", stacked hedges, and em dashes. `atris slop` flags the prose tells (em-dash, hype-copy) too.
@@ -90,6 +103,8 @@ The same discipline for words. Output stays sharp no matter how bloated the cont
   - "Missions survive everything: one engine starts the work, another picks it up cold, a third lands it. Work is no longer tied to a chat window, a session, or a vendor."
   - "The system reports in plain English: one daily message with what landed, what waits on you, and who should own what's next. One person can supervise many projects."
 - **Fit the screen.** An operator-facing report shows three results, air between them, and holds the rest on ask. No scrolling: reading it is one glance, and the reader asks for more if they want more.
+- **Pace with whitespace.** Words for the operator arrive as complete sentences, one or two per paragraph, blank line between. The whitespace does the pacing, never fragments: fast to scan, still flowing.
+- **Assume attention is scarce and ambition is not.** The reader is at the end of a long day and still moving something big forward. Nothing may require held state (remembering step 2 while reading step 5), every surface ends in one obvious next action that starts in under a minute, and each glance should leave the reader one step closer. Engineers and non-engineers get the same plain sentence; precision stays one ask away, never in the way.
 - **Human surfaces are gated.** Anything rendered for the operator (brief, digest, boot) goes through the operator-voice translator and a deterministic jargon gate; raw ids, commands, paths, and test tallies never reach a page. A gate violation is a build error, not a style note.
 - **Interview the fuzz.** When the operator hands off a fuzzy build ("make me the best X", "yeah ok this is my thought, go make it"), do not ask open questions and do not dispatch as-is. Offer 2-3 named interpretations with a recommendation ("best could mean capture, resurfacing, or closure: I'd bet resurfacing, right?") so the operator confirms or corrects in five words. Repeat until the brief fits one screen (goal, why now, done-looks-like, open risks), show the brief, then dispatch. The interview lends the operator a structure to think in; the sharpened brief is what makes every downstream lap cheap.
 

package/ax

@@ -12,7 +12,8 @@ const permissionGrants = require(path.join(__dirname, 'lib', 'permission-grants.
 const { loadCredentials } = require('./utils/auth');
 const { apiRequestJson, getApiBaseUrl } = require('./utils/api');
 const missionRuntime = require('./lib/mission-runtime-loop');
-const { pickLane } = require('./lib/ax-auto-lane');
+const { loadOverrides, pickLane } = require('./lib/ax-auto-lane');
+const { buildToolResultBody } = require('./lib/tool-result-encode');
 
 const EXIT_WORDS = new Set(['exit', 'quit', ':q']);
 const BACKEND = {
@@ -957,16 +958,92 @@ function normalizeMode(mode) {
   return mode === 'fast' ? 'fast' : 'pro';
 }
 
+function autoPickLogPath(options = {}) {
+  return options.pickLogPath
+    || process.env.ATRIS_ROUTER_PICKS_PATH
+    || path.join(os.homedir(), '.atris', 'ax-auto-picks.jsonl');
+}
+
+function autoMessageWords(message) {
+  return new Set(String(message || '').toLowerCase().match(/[a-z0-9]+/g) || []);
+}
+
+function autoMessageOverlap(left, right) {
+  const leftWords = autoMessageWords(left);
+  const rightWords = autoMessageWords(right);
+  const union = new Set([...leftWords, ...rightWords]);
+  if (!union.size) return 0;
+  let shared = 0;
+  for (const word of leftWords) {
+    if (rightWords.has(word)) shared += 1;
+  }
+  return shared / union.size;
+}
+
+function appendRephrasedOutcome(message, logPath) {
+  try {
+    const rows = fs.readFileSync(logPath, 'utf8').split(/\r?\n/).filter((line) => line.trim());
+    let previous = null;
+    for (let index = rows.length - 1; index >= 0; index -= 1) {
+      try {
+        const row = JSON.parse(rows[index]);
+        if (row && row.pick_id && row.lane && row.message) {
+          previous = row;
+          break;
+        }
+      } catch (_) {
+        // Ignore malformed historical lines.
+      }
+    }
+    if (!previous) return;
+    const ageMs = Date.now() - Date.parse(previous.at);
+    if (ageMs < 0 || ageMs >= 10 * 60 * 1000) return;
+    if (autoMessageOverlap(previous.message, message) < 0.5) return;
+    fs.appendFileSync(logPath, `${JSON.stringify({
+      event: 'outcome',
+      pick_id: previous.pick_id,
+      outcome: 'rephrased',
+    })}\n`);
+  } catch (_) {
+    // Rephrase detection is best-effort and must never block a turn.
+  }
+}
+
 function appendAutoPick(message, picked, options = {}) {
+  const pick = { ...picked, pick_id: crypto.randomUUID() };
+  const logPath = autoPickLogPath(options);
+  Object.defineProperty(pick, '_logPath', { value: logPath, enumerable: false });
   try {
-    const dir = path.join(os.homedir(), '.atris');
-    fs.mkdirSync(dir, { recursive: true });
-    fs.appendFileSync(path.join(dir, 'ax-auto-picks.jsonl'), `${JSON.stringify({
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    appendRephrasedOutcome(message, logPath);
+    fs.appendFileSync(logPath, `${JSON.stringify({
       at: new Date().toISOString(),
-      lane: picked.lane,
-      reason: picked.reason,
+      pick_id: pick.pick_id,
+      lane: pick.lane,
+      reason: pick.reason,
+      message: String(message || ''),
       message_chars: String(message || '').length,
       print: Boolean(options.print),
+      ...(pick.override_id ? { override_id: pick.override_id } : {}),
+    })}\n`);
+  } catch (_) {
+    // Lane telemetry is best-effort and must never block a turn.
+  }
+  return pick;
+}
+
+function appendAutoOutcome(picked, result, options = {}) {
+  if (!picked || !picked.pick_id) return;
+  try {
+    const logPath = autoPickLogPath({ pickLogPath: options.pickLogPath || picked._logPath });
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    fs.appendFileSync(logPath, `${JSON.stringify({
+      event: 'outcome',
+      pick_id: picked.pick_id,
+      ok: Boolean(result && result.ok),
+      model: String((result && result.model) || modelForMode(picked.lane)),
+      duration_ms: Number((result && (result.duration_ms || result.durationMs)) || 0),
+      error: result && result.error ? String(result.error) : null,
     })}\n`);
   } catch (_) {
     // Lane telemetry is best-effort and must never block a turn.
@@ -974,8 +1051,10 @@ function appendAutoPick(message, picked, options = {}) {
 }
 
 function autoLaneForMessage(message, options = {}) {
-  const picked = pickLane(message);
-  appendAutoPick(message, picked, options);
+  const overrides = Array.isArray(options.overrides)
+    ? options.overrides
+    : loadOverrides(options.overridesPath);
+  const picked = appendAutoPick(message, pickLane(message, { overrides }), options);
   const errorOutput = options.errorOutput || process.stderr;
   errorOutput.write(`${picked.reason}\n`);
   return picked;
@@ -2793,7 +2872,7 @@ async function postTurn(message, options = {}) {
         if (options.business) {
           return options.business.postToolResult(callId, result, backendBaseUrl({ route: 'cloud' }));
         }
-        return postJson(BACKEND_API_TOOL_RESULT_PATH, { call_id: callId, result }, {
+        return postJson(BACKEND_API_TOOL_RESULT_PATH, buildToolResultBody(callId, result), {
           token,
           route: endpointRoute,
           timeoutMs: 30000,
@@ -3016,8 +3095,11 @@ async function runHeadlessTurn(message, options = {}) {
   const startedAt = Date.now();
   const sink = options.output || bufferedOutput();
   const turnFunction = options.turnFunction || turnFunctionForMode(mode);
-  const autoFields = options.autoLane && options.autoReason
-    ? { auto_lane: normalizeMode(options.autoLane), auto_reason: String(options.autoReason) }
+  const autoPick = options.autoPick || null;
+  const autoFields = autoPick
+    ? { auto_lane: normalizeMode(autoPick.lane), auto_reason: String(autoPick.reason) }
+    : options.autoLane && options.autoReason
+      ? { auto_lane: normalizeMode(options.autoLane), auto_reason: String(options.autoReason) }
     : {};
 
   try {
@@ -3030,15 +3112,17 @@ async function runHeadlessTurn(message, options = {}) {
       output: sink,
       showProgress: false,
     });
-    return {
+    const payload = {
       ok: true,
       model: modelForMode(mode),
       output: String((result && result.output) || '').trim(),
       durationMs: Number((result && result.durationMs) || 0) || (Date.now() - startedAt),
       ...autoFields,
     };
+    appendAutoOutcome(autoPick, payload);
+    return payload;
   } catch (error) {
-    return {
+    const payload = {
       ok: false,
       model: modelForMode(mode),
       output: '',
@@ -3046,6 +3130,8 @@ async function runHeadlessTurn(message, options = {}) {
       error: String((error && error.message) || error || 'headless turn failed'),
       ...autoFields,
     };
+    appendAutoOutcome(autoPick, payload);
+    return payload;
   }
 }
 
@@ -3125,11 +3211,16 @@ async function chat(options = {}) {
       return false;
     }
 
+    let autoPick = null;
     if (options.auto) {
-      mode = autoLaneForMessage(trimmed, {
+      autoPick = autoLaneForMessage(trimmed, {
         errorOutput: options.errorOutput,
         print: false,
-      }).lane;
+        overrides: options.overrides,
+        overridesPath: options.overridesPath,
+        pickLogPath: options.pickLogPath,
+      });
+      mode = autoPick.lane;
     }
 
     if (logger) logger.write(`${formatPrompt(mode)}${trimmed}\n`);
@@ -3230,22 +3321,38 @@ async function chat(options = {}) {
       lastCompactionNotice = compactedTurns;
       output.write(`${paint(`· context: ${compactedTurns} earlier turn${compactedTurns === 1 ? '' : 's'} compacted into a digest`, [ANSI.muted], output)}\n`);
     }
-    const result = await turnFunction(trimmed, {
-      mode,
-      cwd,
-      history,
-      input,
-      output,
-      route,
-      business: options.business,
-      verify: options.verify,
-      conversationId,
-      turnId,
-      approveBackendApi: options.approveBackendApi,
-      apiRequestJson: options.apiRequestJson,
-      loadCredentials: options.loadCredentials,
-      getApiBaseUrl: options.getApiBaseUrl,
-    });
+    let result;
+    try {
+      result = await turnFunction(trimmed, {
+        mode,
+        cwd,
+        history,
+        input,
+        output,
+        route,
+        business: options.business,
+        verify: options.verify,
+        conversationId,
+        turnId,
+        approveBackendApi: options.approveBackendApi,
+        apiRequestJson: options.apiRequestJson,
+        loadCredentials: options.loadCredentials,
+        getApiBaseUrl: options.getApiBaseUrl,
+      });
+      appendAutoOutcome(autoPick, {
+        ok: true,
+        model: modelForMode(mode),
+        durationMs: Number(result && result.durationMs) || (Date.now() - turnStartedAt),
+      });
+    } catch (error) {
+      appendAutoOutcome(autoPick, {
+        ok: false,
+        model: modelForMode(mode),
+        durationMs: Date.now() - turnStartedAt,
+        error: String((error && error.message) || error),
+      });
+      throw error;
+    }
     if (result.output && !result.output.endsWith('\n')) output.write('\n');
     const approvalExecution = normalizeMode(mode) === 'code-fast'
       ? null
@@ -4288,8 +4395,7 @@ async function main() {
           route: route === 'auto' ? undefined : route,
           business,
           verify,
-          autoLane: autoPick && autoPick.lane,
-          autoReason: autoPick && autoPick.reason,
+          autoPick,
         })
         : { ok: false, model: modelForMode(mode), output: '', durationMs: 0, error: 'missing prompt' };
       console.log(JSON.stringify(payload));
@@ -4305,7 +4411,23 @@ async function main() {
     console.log('');
     maybeWriteAtrisGoalBanner(process.stdout, process.cwd());
     const turnStartedAt = Date.now();
-    const result = await turnFunctionForMode(mode)(prompt, { mode, cwd: process.cwd(), route: route === 'auto' ? undefined : route, business, verify });
+    let result;
+    try {
+      result = await turnFunctionForMode(mode)(prompt, { mode, cwd: process.cwd(), route: route === 'auto' ? undefined : route, business, verify });
+      appendAutoOutcome(autoPick, {
+        ok: true,
+        model: modelForMode(mode),
+        durationMs: Number(result && result.durationMs) || (Date.now() - turnStartedAt),
+      });
+    } catch (error) {
+      appendAutoOutcome(autoPick, {
+        ok: false,
+        model: modelForMode(mode),
+        durationMs: Date.now() - turnStartedAt,
+        error: String((error && error.message) || error),
+      });
+      throw error;
+    }
     const receipt = receiptFromState(result);
     const approvalRequest = normalizeMode(mode) === 'code-fast' ? null : approvalRequestFromReceipt(receipt);
     const approvalRecord = approvalRequest
@@ -4338,6 +4460,10 @@ if (require.main === module) {
 }
 
 module.exports = {
+  appendAutoOutcome,
+  appendAutoPick,
+  autoLaneForMessage,
+  autoMessageOverlap,
   authToken,
   authUserId,
   approvalExecutionRequestFromReceipt,