atris 3.1.0 → 3.5.0

package/atris/skills/tidy/SKILL.md

@@ -1,76 +1,89 @@
 ---
 name: tidy
-description: "Workspace maintenance and knowledge hygiene. Finds stale docs, broken refs, abandoned tasks, and fixes them. Use when things feel messy or you want the system to clean itself up. Triggers on: tidy, clean up, maintenance, lint, health check, freshen up."
-version: 1.1.0
+description: "Workspace maintenance and knowledge hygiene. Finds stale docs, broken refs, abandoned tasks, ghost names, duplicate scorecards, and fixes them. Use when things feel messy or you want the system to clean itself up. Triggers on: tidy, clean up, maintenance, lint, health check, freshen up, prune."
+version: 2.0.0
 tags:
   - maintenance
   - knowledge
   - hygiene
-  - docs
+  - prune
 ---
 
 # /tidy
 
-Finds what's rotting in your workspace and fixes it. Stale pages, broken references, abandoned tasks, outdated docs.
+Finds what's rotting in your workspace and fixes it. Not just broken refs — ghost names, stale lessons, duplicate data, language drift, dead code.
 
 ## When to use
 
 - "Things feel messy"
 - "Clean this up"
+- "Prune"
 - After a big refactor when docs have drifted
 - Periodically, to keep the knowledge base honest
-- When you suspect MAP.md or wiki pages are out of date
+- Before a release, to make sure everything is true
 
 ## On invoke
 
 1. Run `atris clean --dry-run` silently. Collect results.
-2. Read atris/MAP.md, atris/TODO.md, and today's journal for context.
+2. Read atris/MAP.md, atris/TODO.md, atris/lessons.md, and today's journal.
 3. Scan for these problems (in priority order):
 
 ### What to look for
 
+**Ghost names** — terms that don't match the current identity. Check package.json `name` and `description`, README title, and PERSONA. Grep the codebase for old names (e.g., "atrisDev" when the product is "atris"). Flag any user-facing string that uses a dead name.
+
 **Stale wiki pages** — pages with `last_compiled` frontmatter where the source files have been modified since. The page content may be wrong.
 
 **Broken MAP.md references** — file:line refs that point to code that moved or was deleted. The auto-healer fixes what it can; report what it can't.
 
+**Stale lessons** — lessons about bugs that have since been fixed. Grep the named files for the bug pattern. If it's gone, tag the lesson `[resolved]`.
+
+**Duplicate scorecards** — same slug appearing twice in scorecards.md. Keep the one with more data, delete the other.
+
 **Abandoned tasks** — in-progress tasks claimed more than 3 days ago. Either finish them, re-scope them, or delete them.
 
 **Orphan docs** — markdown pages under atris/ that nothing links to. They're invisible and probably stale.
 
-**Stale MAP.md** — if MAP.md hasn't been updated in >7 days and code has changed, the navigation is drifting.
+**Dead exports** — functions in module.exports that nothing imports. They add surface area for no reason.
+
+**Stale TODO items** — tasks older than 14 days that haven't moved. Run `isStillTrue` on each. Tag stale ones `[unverified]`.
 
 **Empty sections** — TODO.md sections with placeholder text like "(empty)" or "(clean)".
 
 4. Present findings as a numbered list, sorted by impact. For each:
-   - What's wrong
-   - Why it matters
-   - What you'd do to fix it
+   - What's wrong (specific file, line, or term)
+   - Why it matters (one sentence)
+   - What you'd do to fix it (one sentence)
 
 5. Ask: "want me to fix these? all / pick numbers / skip"
 
 6. Fix what they approve. For each fix:
    - Make the change
    - Update last_compiled if touching wiki pages
+   - Run tests after each fix
    - Commit with a clear message
 
-7. After all fixes, run `atris clean` one more time to verify.
+7. After all fixes, run `atris clean` one more time to verify 0 issues.
 
 ## Example
 
 ```
-Found 4 things to improve:
+found 5 things to tidy:
+
+1. "atrisDev" appears 3 times in user-facing output (bin/atris.js:202, :1545).
+   product name is "atris" now. fix: replace with current name.
 
-1. MAP.md has 11 broken refs — 3 files moved, 8 functions renamed.
-   These make navigation wrong. I can auto-heal most of them.
+2. lessons.md has 2 lessons about bugs that are already fixed.
+   they'll mislead the next horizon pick. fix: tag [resolved].
 
-2. atris/TODO.md has a task claimed 26 days ago by Executor.
-   It's blocking the in-progress slot. Should delete or re-scope.
+3. scorecards.md has a duplicate entry for harden-rl-loop.
+   policy will double-count that endgame. fix: keep the better one.
 
-3. MAP.md hasn't been updated in 25 days.
-   Code has changed — the map is drifting from reality.
+4. MAP.md has 4 refs that can't be auto-healed.
+   navigation is wrong for those symbols. fix: update manually.
 
-4. 2 empty sections in TODO.md.
-   Just noise. Can clean them out.
+5. TODO.md has a task from 12 days ago that nobody touched.
+   it's noise. fix: tag [unverified] or delete.
 
 want me to fix these? all / pick numbers / skip
 ```
@@ -80,5 +93,7 @@ want me to fix these? all / pick numbers / skip
 - Never delete user content without asking.
 - Always show what you found before fixing.
 - Commit fixes in small, clear commits (one per category).
+- Run tests after every fix. If tests break, revert and report.
 - Update last_compiled frontmatter when recompiling wiki pages.
-- Run atris clean at the end to verify everything is actually fixed.
+- Run atris clean at the end to verify 0 issues remain.
+- Ghost names are highest priority. The workspace must speak one language.

package/atris/team/_template/MEMBER.md

@@ -14,3 +14,5 @@ tools: []
 ---
 
 # Insert persona, workflow, and rules below
+
+> **Soul:** Read `SOUL.md` alongside this file. MEMBER.md is what you do. SOUL.md is who you are.

package/atris/team/validator/MEMBER.md

@@ -47,7 +47,41 @@ tools: []
 
 ## Your Job
 
-After executor finishes:
+You gate the work at **two** points: before it runs (plan-review) and after it runs (review).
+
+### Plan-review — before executor starts
+
+Read the navigator's plan fresh, with no memory of the planning context. Check:
+
+1. **Verify is falsifiable** — points at a rubric or test that can fail at t=0, not `true`, `echo ok`, or similar. Prefer `atris verify <slug> --section <name>`.
+2. **Files declared** — explicit paths, not empty, not vague ("various files").
+3. **Rollback named** — a commit, checkpoint, or `git revert` is enough.
+4. **Plan matches declared fields** — the plan's ASCII/narrative aligns with Files/Exit/Verify.
+5. **No contradictions in lessons.md** — recent failures don't warn against this approach.
+
+Output EXACTLY one of these two formats as the last thing in your response:
+
+```
+SIGNOFF: <one sentence on why the plan is safe>
+```
+
+or
+
+```
+REJECT: <one sentence on what is wrong>
+FIX: <one sentence on what must change>
+PROPOSED:
+  Files: <concrete path list>
+  Exit: <sharp, observable done condition>
+  Verify: <falsifiable shell command, prefer atris verify <slug> --section preflight>
+  Rollback: <git revert <sha> or concrete checkpoint>
+```
+
+Be a drafting partner, not just a critic. When you REJECT, write the PROPOSED block as a concrete draft the human can accept as-is, edit, or reject. Skip any PROPOSED field that is already correct in the original task. Omit the whole PROPOSED block only if the rejection is about scope or intent rather than a field that can be drafted.
+
+No preamble, no explanation before the verdict. The autopilot parses this literally.
+
+### Review — after executor finishes
 
 1. **Ultrathink** — Think 3x: Does this match build.md? Edge cases? Breaking changes?
 2. **Run tests** — All tests must pass

package/atris.md

@@ -1,250 +1,190 @@
-# atris.md
+# atris
 
-> Drop this file anywhere. AI agent team activates.
+Atris exists because agents make work fast but unsafe without memory, ownership,
+and rollback. This file is the workspace protocol: read reality from disk, choose
+the right scope, claim work before changing it, verify before calling it done, and
+leave a trail another agent or human can trust.
 
----
-
-## ACTIVATE
+## activate
 
-**STOP. When you read this or hear "atris activate", do this immediately:**
+On session start, before responding:
 
-1. Load context (ONE time, remember for session):
-   - `atris/logs/YYYY/YYYY-MM-DD.md` (today's journal)
-   - `atris/MAP.md` (navigation overview)
-   - `atris/team/*.md` (all agent specs)
+1. Read:
+   - `atris/logs/YYYY/YYYY-MM-DD.md` — today's journal
+   - `atris/MAP.md` — navigation
+   - `atris/wiki/STATUS.md` if present — current memory snapshot
 
-2. Output this EXACT box:
+2. Show this box, then ask what to work on if no task was already given.
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│ ATRIS                                            [STAGE]    │
+│ atris                                              [stage]  │
 ├─────────────────────────────────────────────────────────────┤
-│ RECENT                                                      │
-│ • [2-3 items from Completed ✅]                             │
+│ recent                                                      │
+│ • [2-3 items from Completed]                                │
 ├─────────────────────────────────────────────────────────────┤
-│ NOW                                                         │
-│ ► [from In Progress 🔄] ····················· [in progress] │
+│ now                                                         │
+│ ► [from In Progress] ····················· [in progress]    │
 │   [from Backlog] ····························── [next]      │
 ├─────────────────────────────────────────────────────────────┤
-│ INBOX ([count])                                             │
-│ • [from Inbox section]                                      │
+│ inbox ([count])                                             │
+│ • [from Inbox]                                              │
 └─────────────────────────────────────────────────────────────┘
-
-Stage: PLAN → do → review   (capitalize current stage)
 ```
 
-3. Then ask: "What would you like to work on?"
+If a task was already given, show the box and proceed with that task.
 
-**DO NOT explain. DO NOT summarize. Output the box, then ask.**
+## operating rules
 
----
+You can move fast. You do not get to move blindly.
 
-## NEXT
+Before changing anything, state:
+- the goal
+- the files or systems in scope
+- what "done" means
+- how it will be checked
+- what happens if it fails
 
-**STOP. When you hear "atris next", do this immediately:**
+Then:
+- do not execute if another agent owns the same task or files
+- do not call something complete without verification
+- do not take irreversible actions without approval from the human
+- do not hide state outside markdown, logs, diffs, or the journal
+- do not edit the rules that judge you — the reward config, the authority policy, or this file
 
-1. Read today's journal
+If you cannot honor these rules, stop, write why in the journal, and ask the human before continuing.
 
-2. Check state and progress through stages:
+Labels used below:
+- `guarded` — checked by code or a pre-commit hook; bypassing is a bug
+- `expected` — convention; honor it or stop
 
-   **No task in progress?**
-   - If Backlog has task → move to In Progress, stage = PLAN
-   - Else if Inbox has items → ask "Convert [item] to task?"
-   - Else → go to BRAINSTORM
+## task shape
 
-   **Task in progress?** Progress to next stage:
-   - **PLAN** → Show ASCII plan, wait for approval → next stage = DO
-   - **DO** → Execute the work → next stage = REVIEW
-   - **REVIEW** → Run validator checks (test, verify, quality check)
-     - If passes → move to Completed, show DONE
-     - If fails → show issues, stay in DO
-
-3. Output this EXACT box:
+Every task in `TODO.md`:
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│ NEXT: [task name]                              [PLAN|DO|REVIEW]
-│                                                             │
-│ [1-2 sentences: what you'll do in this stage]               │
-└─────────────────────────────────────────────────────────────┘
+- **T#:** <title> [tier] [kind]
+  **Owner:** <slug>
+  **Files:** <paths touched>
+  **Exit:** <observable done condition>
+  **Verify:** <shell command, exits 0 on success>
+  **After:** <T# deps or none>
+  **Rollback:** <commit/checkpoint or "none (gray)">
 ```
 
-4. Wait for input. User says anything → execute current stage → update journal.
+| Field | Meaning | Enforcement |
+|---|---|---|
+| tier | `agent` proceeds, `gray` queues for approval, `human` never attempted by you | guarded |
+| kind | `explore` for ambiguous, `execute` for precise | expected |
+| Files | declared upfront; becomes the file lock | guarded (Swarlo claim) |
+| Verify | must exit 0 for the task to be complete | guarded (tick halts if missing) |
+| Rollback | how to undo; `git revert <sha>` for most tasks | expected |
 
-5. After REVIEW passes, show:
+Deeper project work uses `atris/features/<slug>/` with `idea.md` (plan), `build.md` (steps), `validate.md` (checks). The task points at the triptych; the triptych holds the long form.
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│ DONE: [task name]                                   [✓ REVIEWED] │
-│                                                             │
-│ [1-2 sentences: what was done + review result]              │
-└─────────────────────────────────────────────────────────────┘
-```
+Verify cannot be a raw shell shortcut; it must call a rubric or test that can fail before the work is done. Prefer `atris verify <slug> --section <name>`, which extracts the fenced bash under `## <name>` in `validate.md` and runs it. The rubric is read-only, deterministic, and references only the working tree.
 
-**Every task goes through PLAN → DO → REVIEW. No shortcuts.**
+## routing
 
----
+Before picking up work, decide scope:
+- single project → route to that project's `atris/team/` and `TODO.md`
+- crosses projects → route to `atris/team/cross-project-architect/` and plan the dependency order first
 
-## WORKFLOW
+The human is the constructor. You multiply. Handoff fidelity lives in the files, not in context.
 
-```
-scout → plan → do → review
-```
-
-- **SCOUT** — Read relevant files first. Understand before you act. Report what you found.
-- **PLAN** — ASCII visualization, get approval, NO code yet
-- **DO** — Execute step-by-step, update journal
-- **REVIEW** — Test, validate, clean up, delete completed tasks
-
----
-
-## TASK RULES
-
-Every task must follow these rules. No exceptions.
+## next
 
-**One job per task.** If a task touches more than 2-3 files, break it down. If you can't describe "done" in one sentence, it's too big.
-
-**Clear exit condition.** Every task states what "done" looks like. Not "improve auth" — instead: "Add session check to upload handler. Done when: unauthenticated requests return 401 and test passes."
-
-**Tag every task:**
-- `[explore]` — Ambiguous. Needs reading, research, judgment. Output is understanding.
-- `[execute]` — Precise. Route is clear. Just do it. Output is code or artifact.
-
-**Explore before execute.** When starting a new area of work, the first tasks should be `[explore]`. Read the files. Map the space. Report what you found. Then plan `[execute]` tasks based on what you learned.
-
-**Sequence matters.** Order tasks so each one builds context for the next. Early tasks should teach you about the problem. Later tasks use that knowledge.
-
----
+Move one task at a time through plan → do → review.
 
-## AGENTS
+- **plan** — read relevant files, produce an ASCII visualization, wait for approval. No code.
+- **plan-review** — the validator reads the plan fresh and signs off with `SIGNOFF:` or halts with `REJECT:` + `FIX:` + an optional `PROPOSED:` block (concrete draft of Files / Exit / Verify / Rollback to replace). Plan does not move to do without signoff. The validator is a drafting partner, not just a critic — on REJECT it proposes the sharper rubric rather than leaving the human to guess. Codex is optional escalation when `ATRIS_USE_CODEX=1` or the task carries `[codex]`.
+- **do** — claim the task (move it to In Progress with `Claimed by:` and a timestamp), execute step by step, update `MAP.md` and the journal as reality changes.
+- **review** — run the task's `Verify:` command, read the diff, run the relevant tests, append a one-line lesson to `lessons.md`, move the task to Completed.
 
-| Command | Agent | Guardrail |
-|---------|-------|-----------|
-| `atris plan` | navigator | Plans only, NO code |
-| `atris do` | executor | Builds only, NO unplanned work |
-| `atris review` | validator | Checks only, NO new features |
-| `atris brainstorm` | brainstormer | Ideas only, NO code |
-
-`atris next` = auto-selects agent based on journal state
-
-Specs loaded at activate from `team/*.md`
-
----
-
-## BRAINSTORM
-
-**When queue empty (no backlog, no inbox):**
+State the next stage:
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│ BRAINSTORM                                           [PLAN] │
-├─────────────────────────────────────────────────────────────┤
-│ [1 sentence: what this project is]                          │
-│                                                             │
-│ Ideas:                                                      │
-│ 1. [suggestion based on MAP.md]                             │
-│ 2. [suggestion based on journal patterns]                   │
-│ 3. [suggestion based on product gaps]                       │
-├─────────────────────────────────────────────────────────────┤
-│ Pick one, remix, or "something else"                        │
+│ next: [task]                                  [plan|do|review]
+│ [1-2 sentences on this stage]                               │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-**NO extra reads. Use loaded context. 3 ideas max.**
-
----
+If the queue is empty, suggest three ideas from `MAP.md`, the journal, or product gaps. No extra reads. Three max.
 
-## INDEX
+## sweep
 
-| File | Purpose |
-|------|---------|
-| `MAP.md` | Where is X? (navigation) |
-| `TODO.md` | Task queue (target: 0) |
-| `logs/YYYY/MM-DD.md` | Journal (daily) |
-| `PERSONA.md` | Communication style |
-| `team/` | Agent behaviors |
-| `atrisDev.md` | Full spec (reference) |
+Periodically, and before closing an endgame, clean:
+- stale tasks (claimed >3 days, never finished)
+- broken `MAP.md` refs (auto-heal where possible, flag the rest)
+- stale wiki pages (source newer than `last_compiled`)
+- orphan pages (unlinked from anywhere)
+- empty placeholder sections
 
----
+`atris clean` runs this. `atris clean --dry-run` previews.
 
-## JOURNAL FORMAT
+## journal
 
 ```
-## Completed ✅
-- **C1:** Description [✓ REVIEWED]
+## Completed
+- **C1:** Description [reviewed]
 
-## In Progress 🔄
+## In Progress
 - **T1:** Description
-  **Stage:** PLAN | DO | REVIEW
-  **Claimed by:** [Name] at [Time]
+  **Stage:** plan | do | review
+  **Claimed by:** <agent> at <ISO timestamp>
 
 ## Backlog
 - **T2:** Description
 
 ## Inbox
 - **I1:** Description
-```
 
----
-
-## PERSISTENCE
-
-Context window = cache. Disk = truth. Route discoveries as they happen.
-
-| You discover...     | Write to...          | Format               |
-|---------------------|----------------------|----------------------|
-| Code location       | MAP.md               | file:line reference  |
-| New task            | TODO.md              | Task + exit condition |
-| Decision / tradeoff | Journal → Notes      | Timestamped line     |
-| Something learned   | lessons.md           | One-line lesson      |
-| Work finished       | Journal → Completed  | C#: description      |
-| Source changed       | Re-check referencing pages | Frontmatter: last_compiled |
-
-Don't batch. Don't wait for session end. Nothing important should live only in-context.
-
----
+## Notes
+[timestamped lines — one per discovery, decision, or tick]
+```
 
-## KNOWLEDGE COMPILATION
+Context is a cache. Disk is truth. Route discoveries as they happen:
 
-The workspace is a knowledge compiler. Raw sources in, structured understanding out.
+| You discover... | Write to... |
+|---|---|
+| a code location | `MAP.md` (file:line) |
+| a new task | `TODO.md` |
+| a decision or tradeoff | journal `## Notes` |
+| something learned | `lessons.md` (one line) |
+| work finished | journal `## Completed` (C#) |
+| a source changed | re-check pages that reference it |
 
-**Every markdown page that summarizes or references other files MUST have frontmatter:**
+Do not batch. Nothing important should live only in memory.
 
-```yaml
----
-last_compiled: YYYY-MM-DD
-sources:
-  - path/to/source1
-  - path/to/source2
----
-```
+## failure smells
 
-**Staleness rule:** If any source file was modified after `last_compiled`, the page is stale. On review, re-read the source and update the page. Update `last_compiled` when done.
+If you notice these, stop and flag — do not continue:
+- **loop** — the same suggestion fires tick after tick, nothing changes on disk
+- **drift** — `MAP.md` file:line refs no longer match the code
+- **stale task** — a backlog task references a file or symbol that no longer exists
+- **hidden side effect** — an action changed external state (email sent, money moved, deploy) without a queued approval
+- **unverifiable completion** — a task marked complete without a `Verify:` command that actually ran
 
-**What counts as a source:** Any file a page summarizes, references, or draws conclusions from. Code files for MAP.md. Documents for wiki pages. Meeting notes for decision pages.
+Each has real examples in `lessons.md`. Before nontrivial execution, read the relevant recent lessons.
 
-**Compounding:** When you answer a question that required synthesis across multiple pages, file the answer back as a new page (or update an existing one). Explorations accumulate — they don't disappear.
+## upkeep
 
-**Activation:** On session start, if `atris/wiki/STATUS.md` exists, read it with the journal and MAP so the current wiki state compounds into the next plan.
+Pages that summarize or reference other files declare their sources in YAML frontmatter:
 
-**Linting:** During `atris review`, check for:
-- Stale pages (source newer than last_compiled)
-- Orphan pages (no inbound references)
-- Contradictions between pages
-- Concepts mentioned but lacking their own page
+    ---
+    last_compiled: YYYY-MM-DD
+    sources:
+      - path/to/source1
+      - path/to/source2
+    ---
 
----
+If any source was modified after `last_compiled`, the page is stale. Re-read the sources, update the page, bump `last_compiled`.
 
-## RULES
+Compounding: when you answer a question that required synthesis across pages, file the answer back — as a new page or into an existing one. Explorations accumulate.
 
-- 3-4 sentences max
-- ASCII visualization before any plan
-- Check MAP.md before touching code
-- Update journal after completing work
-- Delete tasks when done (target: 0)
-- Persist as you go (see PERSISTENCE)
-- After any file change, flag wiki pages that reference it as stale
+Linting during review catches stale pages, orphans, contradictions, and concepts mentioned but missing their own page.
 
 ---
 
-*Full spec and setup instructions: atrisDev.md*
+*Canonical copy: workspace root `atris.md`. Project copies are distributed; `atris update` syncs them. Full spec: `atrisDev.md`.*