atris 3.1.0 → 3.5.0

package/GETTING_STARTED.md

@@ -1,172 +1,106 @@
-# Getting Started with atrisDev
+# Getting Started with Atris
 
-Welcome! atrisDev gives you a high-quality AI development workflow that works with any coding agent.
+Atris turns any folder into a workspace that gets better over time. Integrates with any agent.
 
-## What Just Happened?
+## Install
 
-You ran `atris init` and got this folder structure:
-
-```
-atris/
-├── GETTING_STARTED.md (you are here!)
-├── atris.md (atrisDev protocol + specs)
-├── CLAUDE.md (tells agents to follow atrisDev)
-├── MAP.md (navigation - AI will generate)
-└── team/ (agent specs)
+```bash
+npm install -g atris
 ```
 
-## Quick Start (2 Steps)
-
-### Step 1: Run atris
+## Setup (1 minute)
 
 ```bash
-atris
+cd your-project
+atris init
 ```
 
-This loads your workspace context and activates the atrisDev protocol.
-
-### Step 2: Describe what you want
-
-In your coding agent (Claude Code, Cursor, Windsurf, etc.), just describe what you want to build:
+This creates an `atris/` folder with everything the system needs:
 
 ```
-"I want to add dark mode to the settings page"
-"Build a CSV export feature for the dashboard"
-"Refactor the auth system to use OAuth"
-```
-
-The agent will:
-0. (Optional) Explore with you conversationally (`atris brainstorm`)
-1. Show you an **atris visualization** (diagram of the plan)
-2. Wait for your approval
-3. Create `atris/features/[name]/idea.md` + `build.md` + `validate.md`
-4. Execute step by step
-5. Validate (fill in validate.md, harvest lessons if anything surprised you)
-
-💡 Tip: Use `atris brainstorm` if you're exploring options. Use `atris plan` when ready to build.
-
-**Total time: Start building immediately**
-
-## The atrisDev Protocol
-
-When agents see `atris/CLAUDE.md`, they automatically follow the atrisDev workflow. No manual setup needed.
-
-You can also run:
-
-```bash
-atris activate
+atris/
+├── MAP.md          navigation (file:line references)
+├── TODO.md         current work queue
+├── PERSONA.md      how the agent communicates
+├── lessons.md      what went wrong and what worked
+├── logs/           daily journal
+├── wiki/           durable knowledge
+└── team/           agent roles
 ```
 
-This shows today's journal, MAP.md, and TODO.md so you can browse and take notes offline. Authentication and agent selection are only required when you want to use `atris chat` with Atris cloud agents.
-
-## Try the autopilot loop (optional)
+## Your first goal
 
-Need a guided work session? Run:
+Tell atris what you want to build:
 
 ```bash
-atris autopilot
+atris log "add dark mode to the settings page"
 ```
 
-You'll pick a vision (from today's Inbox or a fresh idea), define success criteria, and then step through plan → do → review cycles. The CLI logs each iteration, and you can type `exit` at any prompt to stop.
+This lands in today's journal as an inbox item. The loop picks it up from there.
 
-## Launch a brainstorm (optional)
-
-Need help shaping an idea before it becomes a task? Run:
+## Run one tick
 
 ```bash
-atris brainstorm
+atris autopilot --auto --iterations=1
 ```
 
-Answer a couple quick questions, get a ready-to-send Claude Code conversation starter (context + ASCII cue), and choose whether to log the session summary and next steps.
-
-## What Each File Does
-
-### MAP.md
-Your system's navigation guide. Contains:
-- Quick reference index (grep-friendly shortcuts)
-- Feature map (where is feature X?)
-- Architecture map (where is concern Y?)
-- Critical files (high-impact areas)
-- Entry points
-
-**Use it:** When you need to find something fast or onboard new people
-
-### team/navigator.md
-Your "where is X?" expert. Ask it questions like:
-- "Where is the authentication logic?"
-- "Show me all API endpoints"
-- "Where do we handle file uploads?"
-
-Always cites MAP.md with exact file:line references.
-
-### team/executor.md
-Your task runner. Give it work like:
-- "Add authentication to the upload endpoint"
-- "Fix the bug in user registration"
-- "Refactor the payment flow"
-
-Reads MAP.md, plans execution with file:line references, executes step-by-step.
-
-### team/validator.md
-Your quality gatekeeper. Runs after changes to:
-- Check for breaking changes
-- Update MAP.md if structure changed
-- Run tests and type checks
-- Report risks
+The autopilot will:
+1. Read your inbox and pick a task
+2. Plan it
+3. Build it
+4. Review it
+5. Run the verify check (pass or fail, no opinions)
+6. Write a lesson if something went wrong
 
-### TODO.md
-Auto-generated task bank with:
-- Task complexity (Trivial → Epic)
-- Exact file:line references
-- Execution plans
-- Risk assessments
-- Dependencies
+One task. One commit. One result you can check.
 
-**Use it:** Pick tasks, assign to agents, track progress
+## Set a goal with an endgame
 
-## Using Your Agents
+For bigger work, set a goal and let the loop pursue it:
 
-Once the files are populated, you can interact with your agents:
+In your coding agent, say `/endgame` or describe where you want to end up. The system will:
+1. Pick a horizon (what does done look like?)
+2. Break it into verified tasks (each has a real check)
+3. Work through them one tick at a time
+4. Write a scorecard when the goal closes
+5. Use that scorecard to pick a better goal next time
 
-**Ask the navigator:**
-```
-@navigator where is the user authentication logic?
-```
+## Run the loop
 
-**Give tasks to the executor:**
-```
-@executor add rate limiting to the API (see TODO.md T-005)
+```bash
+atris autopilot --auto --iterations=5
 ```
 
-**Validate changes:**
-```
-@validator check if the recent auth changes are safe to merge
-```
+Or in your coding agent, say `/loop` to schedule it every 13 minutes.
 
-## Keeping Atris Updated
+The loop runs until the goal is done, then picks the next one from scorecards + inbox.
 
-When the Atris package updates with new features:
+## Key commands
 
-```bash
-cd /path/to/your/project
-atris update
+```
+atris init                 set up a new workspace
+atris activate             load context (MAP, TODO, journal)
+atris log                  add to today's journal
+atris autopilot            run one tick (plan, build, review, verify)
+atris status               where things stand
+atris clean                find broken refs, stale docs
+atris release --dry-run    preview a version bump
 ```
 
-This syncs your local `atris.md` and agent templates to the latest version. Re-run your AI agent to regenerate MAP.md with the new spec.
-
-## What's Next?
+## How it improves over time
 
-1. **Let your AI agent generate MAP.md** (Step 2 above if you haven't already)
-2. **Explore MAP.md** - Get familiar with your system's structure
-3. **Try the pre-built agents** - Ask navigator questions, run executor tasks
-4. **Pick a task** - Check TODO.md for quick wins
+Every tick:
+- A verify check runs. Pass or fail.
+- A reward gets scored from the result.
+- If something fails, a lesson is written.
 
-## Need Help?
+Every goal:
+- A scorecard records what shipped, what failed, and the total reward.
+- The next goal is picked based on what actually worked before.
 
-- **Full spec:** Read `atris.md` for technical details
-- **Issues:** https://github.com/atrislabs/atris/issues
-- **Docs:** https://github.com/atrislabs/atris
+The folder gets smarter. The agent doesn't change. The context around it does.
 
----
+## Need help?
 
-**Ready?** Open `atris.md` and paste it to your AI agent. Watch your system become fully instrumented for AI collaboration.
+- Issues: https://github.com/atrislabs/atris/issues
+- Source: https://github.com/atrislabs/atris

package/README.md

@@ -71,7 +71,7 @@ If you're still shaping the idea, use `atris brainstorm`. If you want Atris to k
 
 Core loop: `plan` -> `do` -> `review`
 
-Works with Claude Code, Cursor, Windsurf, Codex, GitHub Copilot, and other coding agents.
+Integrates with any agent.
 
 ## Business Workspaces
 
@@ -80,13 +80,28 @@ If you want a real business workspace, use the business command instead of raw `
 ```bash
 atris business init "BLOND:ISH" --owner-email joel@blondish.world
 cd ~/arena/atris-business/blondish
+atris business onboard --website https://blondish.world --contact "Joel Zimmerman" --note "artist-led brand and ticket sales"
 atris align --fix
 ```
 
-That creates the cloud business, writes `.atris/business.json`, and scaffolds the canonical local `atris/` workspace under `~/arena/atris-business/<slug>/`.
+That creates the cloud business, writes `.atris/business.json`, initializes `.atris/state/` for events, episodes, and scorecards, and scaffolds the local `atris/` workspace under `~/arena/atris-business/<slug>/` with starter team lanes, a default recap artifact, and a first-loop starter queue in `atris/TODO.md`.
+
+If you do not have a neat source pack yet, `atris business onboard` is the low-friction intake step: give it a website, a named human, a few notes, or even just run it in a folder with loose files, and it seeds raw intake, a starter brief, a first loop, a safe next action, and an operator one-pager for you.
+
+You can also use bare input:
+
+```bash
+atris business onboard https://example.com "founder-led b2b ops" ./notes.md
+```
 
 If you already have a folder full of source material, run it from there with `atris business init "BLOND:ISH" --here`.
 
+When the first recap is done, record it into the RL state logs:
+
+```bash
+atris business record atris/reports/2026-04-12-operator-recap.md --outcome mixed --metric "operator speed"
+```
+
 ## Core Commands
 
 | Command | Purpose |
@@ -102,7 +117,7 @@ If you already have a folder full of source material, run it from there with `at
 | `atris log` | Add inbox items to today's journal |
 | `atris status` | Show active work and completions |
 | `atris learn` | Manage structured learnings |
-| `atris ingest` | Fast local-first wiki ingest into `atris/wiki/` |
+| `atris ingest` | Stage raw evidence into `atris/context/` and compile into `atris/wiki/` |
 | `atris loop` | Refresh wiki health, stale/orphan signals, and next ingest candidates |
 | `atris wiki` | Full wiki namespace: ingest, query, lint, search, log, and loop |
 | `atris experiments` | Run Karpathy-style keep/revert packs |
@@ -111,6 +126,8 @@ If you already have a folder full of source material, run it from there with `at
 
 - `atris learn` stores structured project memory in `atris/learnings.jsonl`
 - `atris wiki` keeps repo memory in `atris/wiki/` by default, with `--cloud` when you want the remote workspace path
+- `atris ingest` now stages local source packs under `atris/context/_ingest/`, writes a manifest receipt, and refreshes `atris/wiki/STATUS.md` plus `log.md`
+- `atris wiki --private` uses `.atris/presidio/` for local-only sensitive notes and operating memory
 - `atris loop` refreshes `atris/wiki/STATUS.md` and `atris/wiki/log.md`, flags stale/orphan pages, and suggests the next ingest
 - `atris activate` loads the current wiki status so the next session starts with project memory, not just tasks
 - `atris experiments` runs Karpathy-style keep/revert loops in `atris/experiments/`
@@ -121,7 +138,7 @@ If you already have a folder full of source material, run it from there with `at
 Under the hood, Atris can keep score on real repo work.
 
 - Endgame tasks can carry a `Verify:` command, so work can end on a deterministic check instead of pure prose.
-- `atris autopilot` can run that check after review, record a reward in the journal, and append a scorecard when a horizon closes.
+- `atris autopilot` can run that check after review, record a reward in the journal, and append a local scorecard when a horizon closes.
 - Future horizon picks can weight against recent scorecards, so the loop learns from repo-local history without claiming model retraining.
 
 ## Benchmark Harness
@@ -178,6 +195,14 @@ atris skill link [--all]
 
 For Codex, copy any skill folder into `~/.codex/skills/`.
 
+## v3.2.0
+
+- **Staleness gate** — tasks tagged `[unverified]` are skipped at the moment of use, not pruned eagerly. Three-state model: actionable / unverified / deleted.
+- **Lesson gate** — `isLessonResolved` checks whether a lesson already shipped before proposing new horizons from it. Prevents the loop from re-solving solved problems.
+- **`atris release`** — new command: tags the version, bumps package.json, creates a GitHub release, and drafts a `/launch` post in one shot.
+- **Shell injection fix** — `checkStaleness` switched from `execSync` string interpolation to `execFileSync` with args arrays. Markdown-derived content (task titles, inbox items) no longer reaches a shell.
+- **Codex hardening** — `atris activate` and `atris` entry point detect Codex environments and write `AGENTS.md` so Codex sessions start with workspace context.
+
 ## Update
 
 ```bash

package/atris/GETTING_STARTED.md

@@ -1,172 +1,106 @@
-# Getting Started with atrisDev
+# Getting Started with Atris
 
-Welcome! atrisDev gives you a high-quality AI development workflow that works with any coding agent.
+Atris turns any folder into a workspace that gets better over time. Integrates with any agent.
 
-## What Just Happened?
+## Install
 
-You ran `atris init` and got this folder structure:
-
-```
-atris/
-├── GETTING_STARTED.md (you are here!)
-├── atris.md (atrisDev protocol + specs)
-├── CLAUDE.md (tells agents to follow atrisDev)
-├── MAP.md (navigation - AI will generate)
-└── team/ (agent specs)
+```bash
+npm install -g atris
 ```
 
-## Quick Start (2 Steps)
-
-### Step 1: Run atris
+## Setup (1 minute)
 
 ```bash
-atris
+cd your-project
+atris init
 ```
 
-This loads your workspace context and activates the atrisDev protocol.
-
-### Step 2: Describe what you want
-
-In your coding agent (Claude Code, Cursor, Windsurf, etc.), just describe what you want to build:
+This creates an `atris/` folder with everything the system needs:
 
 ```
-"I want to add dark mode to the settings page"
-"Build a CSV export feature for the dashboard"
-"Refactor the auth system to use OAuth"
-```
-
-The agent will:
-0. (Optional) Explore with you conversationally (`atris brainstorm`)
-1. Show you an **atris visualization** (diagram of the plan)
-2. Wait for your approval
-3. Create `atris/features/[name]/idea.md` + `build.md` + `validate.md`
-4. Execute step by step
-5. Validate (fill in validate.md, harvest lessons if anything surprised you)
-
-💡 Tip: Use `atris brainstorm` if you're exploring options. Use `atris plan` when ready to build.
-
-**Total time: Start building immediately**
-
-## The atrisDev Protocol
-
-When agents see `atris/CLAUDE.md`, they automatically follow the atrisDev workflow. No manual setup needed.
-
-You can also run:
-
-```bash
-atris activate
+atris/
+├── MAP.md          navigation (file:line references)
+├── TODO.md         current work queue
+├── PERSONA.md      how the agent communicates
+├── lessons.md      what went wrong and what worked
+├── logs/           daily journal
+├── wiki/           durable knowledge
+└── team/           agent roles
 ```
 
-This shows today's journal, MAP.md, and TODO.md so you can browse and take notes offline. Authentication and agent selection are only required when you want to use `atris chat` with Atris cloud agents.
-
-## Try the autopilot loop (optional)
+## Your first goal
 
-Need a guided work session? Run:
+Tell atris what you want to build:
 
 ```bash
-atris autopilot
+atris log "add dark mode to the settings page"
 ```
 
-You'll pick a vision (from today's Inbox or a fresh idea), define success criteria, and then step through plan → do → review cycles. The CLI logs each iteration, and you can type `exit` at any prompt to stop.
+This lands in today's journal as an inbox item. The loop picks it up from there.
 
-## Launch a brainstorm (optional)
-
-Need help shaping an idea before it becomes a task? Run:
+## Run one tick
 
 ```bash
-atris brainstorm
+atris autopilot --auto --iterations=1
 ```
 
-Answer a couple quick questions, get a ready-to-send Claude Code conversation starter (context + ASCII cue), and choose whether to log the session summary and next steps.
-
-## What Each File Does
-
-### MAP.md
-Your system's navigation guide. Contains:
-- Quick reference index (grep-friendly shortcuts)
-- Feature map (where is feature X?)
-- Architecture map (where is concern Y?)
-- Critical files (high-impact areas)
-- Entry points
-
-**Use it:** When you need to find something fast or onboard new people
-
-### team/navigator.md
-Your "where is X?" expert. Ask it questions like:
-- "Where is the authentication logic?"
-- "Show me all API endpoints"
-- "Where do we handle file uploads?"
-
-Always cites MAP.md with exact file:line references.
-
-### team/executor.md
-Your task runner. Give it work like:
-- "Add authentication to the upload endpoint"
-- "Fix the bug in user registration"
-- "Refactor the payment flow"
-
-Reads MAP.md, plans execution with file:line references, executes step-by-step.
-
-### team/validator.md
-Your quality gatekeeper. Runs after changes to:
-- Check for breaking changes
-- Update MAP.md if structure changed
-- Run tests and type checks
-- Report risks
+The autopilot will:
+1. Read your inbox and pick a task
+2. Plan it
+3. Build it
+4. Review it
+5. Run the verify check (pass or fail, no opinions)
+6. Write a lesson if something went wrong
 
-### TODO.md
-Auto-generated task bank with:
-- Task complexity (Trivial → Epic)
-- Exact file:line references
-- Execution plans
-- Risk assessments
-- Dependencies
+One task. One commit. One result you can check.
 
-**Use it:** Pick tasks, assign to agents, track progress
+## Set a goal with an endgame
 
-## Using Your Agents
+For bigger work, set a goal and let the loop pursue it:
 
-Once the files are populated, you can interact with your agents:
+In your coding agent, say `/endgame` or describe where you want to end up. The system will:
+1. Pick a horizon (what does done look like?)
+2. Break it into verified tasks (each has a real check)
+3. Work through them one tick at a time
+4. Write a scorecard when the goal closes
+5. Use that scorecard to pick a better goal next time
 
-**Ask the navigator:**
-```
-@navigator where is the user authentication logic?
-```
+## Run the loop
 
-**Give tasks to the executor:**
-```
-@executor add rate limiting to the API (see TODO.md T-005)
+```bash
+atris autopilot --auto --iterations=5
 ```
 
-**Validate changes:**
-```
-@validator check if the recent auth changes are safe to merge
-```
+Or in your coding agent, say `/loop` to schedule it every 13 minutes.
 
-## Keeping Atris Updated
+The loop runs until the goal is done, then picks the next one from scorecards + inbox.
 
-When the Atris package updates with new features:
+## Key commands
 
-```bash
-cd /path/to/your/project
-atris update
+```
+atris init                 set up a new workspace
+atris activate             load context (MAP, TODO, journal)
+atris log                  add to today's journal
+atris autopilot            run one tick (plan, build, review, verify)
+atris status               where things stand
+atris clean                find broken refs, stale docs
+atris release --dry-run    preview a version bump
 ```
 
-This syncs your local `atris.md` and agent templates to the latest version. Re-run your AI agent to regenerate MAP.md with the new spec.
-
-## What's Next?
+## How it improves over time
 
-1. **Let your AI agent generate MAP.md** (Step 2 above if you haven't already)
-2. **Explore MAP.md** - Get familiar with your system's structure
-3. **Try the pre-built agents** - Ask navigator questions, run executor tasks
-4. **Pick a task** - Check TODO.md for quick wins
+Every tick:
+- A verify check runs. Pass or fail.
+- A reward gets scored from the result.
+- If something fails, a lesson is written.
 
-## Need Help?
+Every goal:
+- A scorecard records what shipped, what failed, and the total reward.
+- The next goal is picked based on what actually worked before.
 
-- **Full spec:** Read `atris.md` for technical details
-- **Issues:** https://github.com/atrislabs/atris/issues
-- **Docs:** https://github.com/atrislabs/atris
+The folder gets smarter. The agent doesn't change. The context around it does.
 
----
+## Need help?
 
-**Ready?** Open `atris.md` and paste it to your AI agent. Watch your system become fully instrumented for AI collaboration.
+- Issues: https://github.com/atrislabs/atris/issues
+- Source: https://github.com/atrislabs/atris

package/atris/PERSONA.md

@@ -28,6 +28,8 @@ 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.
+
 **Always ask for intent.** Clarify before acting.
 
 **Use ASCII visualization to confirm understanding:**
@@ -42,7 +44,9 @@ Then go 3-4 sentences one by one through each task.
 
 Once every task is confirmed, create a plan.
 
-**Process:** Complete tasks in order of high reward, low risk first.
+**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.
+
+**Process:** Complete tasks in order of high reward, low risk first. Explore first, execute after.
 
 Always aim to be efficient and Pareto (80/20).