@jaimevalasek/aioson 1.7.2 → 1.9.0

package/template/.aioson/agents/validator.md

@@ -0,0 +1,101 @@
+# Agent @validator
+
+> ⚡ **ACTIVATED** — You are now operating as @validator. Execute the instructions in this file immediately.
+
+> **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
+
+## Mission
+Act as the "Validator" in the Nautilus Pattern. Your sole responsibility is to verify whether the binary criteria defined in `harness-contract.json` have been met. You are the final gatekeeper before a feature is marked as `done`.
+
+## Project rules, docs & design governance
+
+These directories are optional. Check them silently — if absent or empty, continue without mentioning them.
+
+1. `.aioson/rules/` — if `.md` files exist, read YAML frontmatter:
+   - if `agents:` is absent or `[]` → load the rule as additional binary criteria
+   - if `agents:` includes `validator` → load the rule as additional binary criteria
+   - otherwise skip it
+2. `.aioson/design-docs/*.md` — load only when a contract criterion explicitly references structural governance.
+
+Rules and governance docs may *add* binary criteria but never override the explicit contract. They never expand the validator's sandbox — do not use them as an excuse to read other agents' artefacts.
+
+## Context restrictions (mandatory)
+To preserve impartiality and avoid continuity hallucinations, you operate in a **strict context sandbox**:
+
+1. **Read (only):**
+   - `.aioson/plans/{slug}/harness-contract.json` (the contract)
+   - `.aioson/plans/{slug}/progress.json` (current state)
+   - Files explicitly listed in `progress.json.completed_steps`
+   - Output of diagnostic tools (linters, test runners, compilers)
+2. **NEVER read:**
+   - Conversation history from other agents (`@dev`, `@analyst`, `@architect`)
+   - PRDs, requirements, or architecture docs (your focus is the binary contract, not product vision)
+   - Code from other features unrelated to the current contract
+3. **Behavior:**
+   - Never implement code. You only observe and report.
+   - Never suggest cosmetic refactors or improvements that are not in the contract.
+   - If a criterion fails, provide the exact technical reason (e.g., "File X not found" or "Syntax error on line Y").
+
+## Execution protocol (RF-VAL)
+
+### Step 1 — Load
+Locate `harness-contract.json` for the current feature. Identify criteria with `binary: true`.
+
+### Step 2 — Deterministic verification
+Run (or request execution of) local tools for each criterion:
+- `ls -l {path}` to check file existence.
+- `cat {path}` to validate patterns or content.
+- `npm test` or equivalent for execution criteria.
+
+### Step 3 — Semantic verification
+For criteria that require understanding (e.g., "API follows REST conventions"), analyze the delivered code strictly against what the contract requires — nothing more.
+
+### Step 4 — Verdict generation
+Your output must be **EXCLUSIVELY** a structured JSON object designed to be parsed by a machine. Do not add preambles or explanations outside the JSON.
+
+## Output format (JSON)
+
+```json
+{
+  "phase": {N},
+  "validation_at": "{ISO-8601}",
+  "results": [
+    {
+      "id": "{C1, C2...}",
+      "passed": {true|false},
+      "reason": {null | "technical error message"}
+    }
+  ],
+  "overall_score": {0 | 1},
+  "ready_for_done_gate": {true | false}
+}
+```
+
+- `overall_score`: `1` if ALL required criteria passed; `0` otherwise.
+- `ready_for_done_gate`: `true` if the feature can advance to `done` status.
+
+## Interaction
+After emitting the JSON, end the session immediately. You are a short-lived process.
+
+## Hard constraints
+- Use `interaction_language` (fallback: `conversation_language`) from project context for all user-facing communication. The JSON output itself stays in English (machine contract).
+- If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.
+
+## Dossier integration
+
+If `.aioson/context/features/{slug}/dossier.md` exists for the active feature, append the verdict to the Agent Trail after emitting the JSON:
+
+```bash
+aioson dossier:add-finding --section="Agent Trail" \
+  --content="Validator verdict: overall_score=<0|1>, ready_for_done_gate=<true|false>. Failures: <C-ids or 'none'>."
+```
+
+Skip silently when the dossier is absent — `progress.json` remains the canonical machine output.
+
+## Observability
+At session end, register: `aioson agent:done . --agent=validator --summary="Validated <slug> phase <N>: score=<0|1>, ready_for_done=<bool>" 2>/dev/null || true`
+
+---
+## ▶ Next step
+The result will be written to `progress.json` by the gateway. Hand back to `@dev` for correction, or proceed to feature closure.
+---

package/template/.aioson/brains/README.md

@@ -1,128 +1,132 @@
-# AIOSON Brains — Procedural Memory System
-
-> Inspired by: A-MEM (Zettelkasten networks), MemRL (quality-scored pattern extraction), Letta (OS-tiered loading), and retrieval-as-tool (agents call memory explicitly, not pre-injected).
-
-## What is this?
-
-Brains are **quality-scored pattern memory** — not event logs, not session history.  
-Each brain node answers: *"I've seen this before. Here's what works, what to avoid, and why."*
-
-Unlike RAG (retrieve-and-prepend), agents load only what's relevant, when it's relevant.
-
-## Loading strategy (tiered — OS-inspired)
-
-| Layer | File | When loaded | Token cost |
-|-------|------|-------------|------------|
-| Index | `_index.json` | Always, on activation | ~2KB |
-| Brain file | `agent/domain.brain.json` | Only when tags match the task | ~8–20KB |
-| Node detail | inside brain file | Read selectively by ID | negligible |
-
-**Rule:** Load `_index.json` first. If task tags match a brain's tag list, load that brain file. Use `query.js` for cross-referencing across multiple brains.
-
-## Brain node schema
-
-```json
-{
-  "id": "css-001",
-  "title": "Short name",
-  "tags": ["css", "hover", "animation"],
-  "q": 5,
-  "v": "EXCELLENT",
-  "s": "One-line summary of the pattern and why it works.",
-  "p": "code snippet or pseudocode",
-  "src": "source site or context",
-  "date": "YYYY-MM-DD",
-  "not": "what NOT to use instead — the anti-pattern this replaces",
-  "warn": "gotcha or edge case to watch out for",
-  "see": ["css-002", "css-007"]
-}
-```
-
-### Verdict values
-
-| Verdict | Meaning |
-|---------|---------|
-| `EXCELLENT` | Best-in-class — use by default |
-| `GOOD` | Solid choice — use when EXCELLENT variant isn't applicable |
-| `BEST_PRACTICE` | Mandatory baseline — always include |
-| `AVOID` | Anti-pattern — explicitly do NOT use this |
-| `BROKEN` | Known broken in current context |
-
-### Quality score (q)
-
-| Score | Meaning |
-|-------|---------|
-| 5 | Verified excellent — used in production, great result |
-| 4 | Verified good — used, worked well |
-| 3 | Theoretical — not yet validated in a real project |
-| 2 | Mixed results — use with caution |
-| 1 | Avoid — kept only for anti-pattern documentation |
-
-## Agent integration
-
-In your agent file, add a **Brain** section:
-
-```markdown
-## Brain (procedural memory)
-
-1. Load `.aioson/brains/_index.json` on activation.
-2. Identify relevant tags from the current task.
-3. Load matching brain files (from index `path` field).
-4. For patterns with q ≥ 4: apply as default approach.
-5. For nodes with v === "AVOID": never implement what's in `not` field.
-6. Use `see[]` to traverse linked nodes.
-
-Cross-reference query:
-  node .aioson/brains/scripts/query.js --tags <tags> --min-quality 4 --format compact
-
-After completing a project, record new learnings:
-  - Add nodes to the appropriate brain file
-  - Rate quality honestly (1-5)
-  - Update `_index.json` nodes count and updated date
-  - Add `see[]` links to related nodes (Zettelkasten web)
-```
-
-## Query script
-
-```bash
-# All EXCELLENT patterns about CSS animation
-node .aioson/brains/scripts/query.js --tags css,animation --verdict EXCELLENT --format compact
-
-# All anti-patterns (to know what NOT to do)
-node .aioson/brains/scripts/query.js --avoid --format compact
-
-# Best practices for site-forge cloning
-node .aioson/brains/scripts/query.js --agent site-forge --min-quality 4 --format compact
-
-# Get specific nodes by ID
-node .aioson/brains/scripts/query.js --id css-001,css-007,js-001
-
-# All patterns that match ALL these tags (AND)
-node .aioson/brains/scripts/query.js --tags css,hover,no-js --match all
-```
-
-## File structure
-
-```
-.aioson/brains/
-├── README.md                         # This file
-├── _index.json                       # Master index (always loaded, ~2KB)
-├── scripts/
-│   └── query.js                      # Cross-reference query script
-└── site-forge/
-    └── visual-patterns.brain.json    # CSS/animation/interaction patterns (14 nodes)
-```
-
-## Adding a new brain
-
-1. Create `agentname/domain.brain.json` following the node schema above
-2. Add an entry to `_index.json` with relevant tags, agent name, and path
-3. Annotate agents that should load it with the relevant tags in their Brain section
-
-## Design philosophy
-
-- **Procedural, not episodic** — "what works" not "what happened"
-- **Explicit anti-patterns** — `not` and `v:AVOID` nodes prevent regressions
-- **Zettelkasten web** — `see[]` links create traversable knowledge graphs
-- **Token-efficient** — index is tiny; brain files are loaded only when needed
-- **Agent-directed** — agents decide what to load, not an auto-injection system
+# AIOSON Brains — Procedural Memory System
+
+> Inspired by: A-MEM (Zettelkasten networks), MemRL (quality-scored pattern extraction), Letta (OS-tiered loading), and retrieval-as-tool (agents call memory explicitly, not pre-injected).
+
+## What is this?
+
+Brains are **quality-scored pattern memory** — not event logs, not session history.  
+Each brain node answers: *"I've seen this before. Here's what works, what to avoid, and why."*
+
+Unlike RAG (retrieve-and-prepend), agents load only what's relevant, when it's relevant.
+
+## Loading strategy (tiered — OS-inspired)
+
+| Layer | File | When loaded | Token cost |
+|-------|------|-------------|------------|
+| Index | `_index.json` | Always, on activation | ~2KB |
+| Brain file | `agent/domain.brain.json` | Only when tags match the task | ~8–20KB |
+| Node detail | inside brain file | Read selectively by ID | negligible |
+
+**Rule:** Load `_index.json` first. If task tags match a brain's tag list, load that brain file. Use `query.js` for cross-referencing across multiple brains.
+
+## Brain node schema
+
+```json
+{
+  "id": "css-001",
+  "title": "Short name",
+  "tags": ["css", "hover", "animation"],
+  "q": 5,
+  "v": "EXCELLENT",
+  "s": "One-line summary of the pattern and why it works.",
+  "p": "code snippet or pseudocode",
+  "src": "source site or context",
+  "date": "YYYY-MM-DD",
+  "not": "what NOT to use instead — the anti-pattern this replaces",
+  "warn": "gotcha or edge case to watch out for",
+  "see": ["css-002", "css-007"]
+}
+```
+
+### Verdict values
+
+| Verdict | Meaning |
+|---------|---------|
+| `EXCELLENT` | Best-in-class — use by default |
+| `GOOD` | Solid choice — use when EXCELLENT variant isn't applicable |
+| `BEST_PRACTICE` | Mandatory baseline — always include |
+| `AVOID` | Anti-pattern — explicitly do NOT use this |
+| `BROKEN` | Known broken in current context |
+
+### Quality score (q)
+
+| Score | Meaning |
+|-------|---------|
+| 5 | Verified excellent — used in production, great result |
+| 4 | Verified good — used, worked well |
+| 3 | Theoretical — not yet validated in a real project |
+| 2 | Mixed results — use with caution |
+| 1 | Avoid — kept only for anti-pattern documentation |
+
+## Agent integration
+
+In your agent file, add a **Brain** section:
+
+```markdown
+## Brain (procedural memory)
+
+1. Load `.aioson/brains/_index.json` on activation.
+2. Identify relevant tags from the current task.
+3. Load matching brain files (from index `path` field).
+4. For patterns with q ≥ 4: apply as default approach.
+5. For nodes with v === "AVOID": never implement what's in `not` field.
+6. Use `see[]` to traverse linked nodes.
+
+Cross-reference query:
+  node .aioson/brains/scripts/query.js --tags <tags> --min-quality 4 --format compact
+
+After completing a project, record new learnings:
+  - Add nodes to the appropriate brain file
+  - Rate quality honestly (1-5)
+  - Update `_index.json` nodes count and updated date
+  - Add `see[]` links to related nodes (Zettelkasten web)
+```
+
+## Query script
+
+```bash
+# All EXCELLENT patterns about CSS animation
+node .aioson/brains/scripts/query.js --tags css,animation --verdict EXCELLENT --format compact
+
+# All anti-patterns (to know what NOT to do)
+node .aioson/brains/scripts/query.js --avoid --format compact
+
+# Best practices for site-forge cloning
+node .aioson/brains/scripts/query.js --agent site-forge --min-quality 4 --format compact
+
+# Get specific nodes by ID
+node .aioson/brains/scripts/query.js --id css-001,css-007,js-001
+
+# All patterns that match ALL these tags (AND)
+node .aioson/brains/scripts/query.js --tags css,hover,no-js --match all
+```
+
+## File structure
+
+```
+.aioson/brains/
+├── README.md                              # This file
+├── _index.json                            # Master index (always loaded, ~2KB)
+├── scripts/
+│   └── query.js                           # Cross-reference query script
+├── dev/
+│   └── patterns.brain.json                # Implementation patterns for @dev (5 nodes)
+├── sheldon/
+│   └── architecture-decisions.brain.json  # Architecture decisions for @sheldon (5 nodes)
+└── site-forge/
+    └── visual-patterns.brain.json         # CSS/animation/interaction patterns (14 nodes)
+```
+
+## Adding a new brain
+
+1. Create `agentname/domain.brain.json` following the node schema above
+2. Add an entry to `_index.json` with relevant tags, agent name, and path
+3. Annotate agents that should load it with the relevant tags in their Brain section
+
+## Design philosophy
+
+- **Procedural, not episodic** — "what works" not "what happened"
+- **Explicit anti-patterns** — `not` and `v:AVOID` nodes prevent regressions
+- **Zettelkasten web** — `see[]` links create traversable knowledge graphs
+- **Token-efficient** — index is tiny; brain files are loaded only when needed
+- **Agent-directed** — agents decide what to load, not an auto-injection system

package/template/.aioson/brains/_index.json

@@ -1,16 +1,34 @@
-{
-  "v": 1,
-  "description": "AIOSON Brain Index — agent procedural memory (quality-scored patterns). Load this first, then load specific brain files only when relevant tags match.",
-  "loading_strategy": "tiered — this index is always loaded (~2KB); brain files loaded on-demand by tag match",
-  "brains": [
-    {
-      "id": "site-forge/visual-patterns",
-      "agents": ["site-forge"],
-      "tags": ["css", "animation", "cloning", "visual-effects", "hover", "scroll", "video", "font", "keyframes", "interaction"],
-      "desc": "CSS/animation/interaction patterns learned from real site cloning — quality-scored, anti-pattern aware",
-      "path": ".aioson/brains/site-forge/visual-patterns.brain.json",
-      "nodes": 14,
-      "updated": "2026-04-01"
-    }
-  ]
-}
+{
+  "v": 1,
+  "description": "AIOSON Brain Index — agent procedural memory (quality-scored patterns). Load this first, then load specific brain files only when relevant tags match.",
+  "loading_strategy": "tiered — this index is always loaded (~2KB); brain files loaded on-demand by tag match",
+  "brains": [
+    {
+      "id": "site-forge/visual-patterns",
+      "agents": ["site-forge"],
+      "tags": ["css", "animation", "cloning", "visual-effects", "hover", "scroll", "video", "font", "keyframes", "interaction"],
+      "desc": "CSS/animation/interaction patterns learned from real site cloning — quality-scored, anti-pattern aware",
+      "path": ".aioson/brains/site-forge/visual-patterns.brain.json",
+      "nodes": 14,
+      "updated": "2026-04-01"
+    },
+    {
+      "id": "dev/patterns",
+      "agents": ["dev", "deyvin", "pair"],
+      "tags": ["security", "shell", "injection", "git", "commit", "context", "bootstrap", "cache", "editing", "tooling", "process", "verification", "discipline", "node", "child-process"],
+      "desc": "Implementation patterns @dev defaults to — security, shell discipline, git mechanics, editing hygiene, validated-slice loop",
+      "path": ".aioson/brains/dev/patterns.brain.json",
+      "nodes": 5,
+      "updated": "2026-05-07"
+    },
+    {
+      "id": "sheldon/architecture-decisions",
+      "agents": ["sheldon", "architect"],
+      "tags": ["aioson", "template", "agents", "sync", "sdd", "classification", "process", "validator", "sandbox", "impartiality", "discovery", "architecture", "ordering", "cli", "integration", "telemetry"],
+      "desc": "Architecture and process decisions @sheldon defaults to — workspace/template parity, classification gates, validator sandbox, discovery-before-architecture, CLI-first integration",
+      "path": ".aioson/brains/sheldon/architecture-decisions.brain.json",
+      "nodes": 5,
+      "updated": "2026-05-07"
+    }
+  ]
+}

package/template/.aioson/brains/dev/patterns.brain.json

@@ -0,0 +1,79 @@
+{
+  "v": 1,
+  "agent": "dev",
+  "domain": "patterns",
+  "desc": "Implementation patterns @dev should default to. Quality-scored, anti-pattern aware. Seed nodes — extend with new q≥4 patterns after each significant slice.",
+  "updated": "2026-05-07",
+  "nodes": [
+    {
+      "id": "dev-001",
+      "title": "spawn with array args over execSync template literals",
+      "tags": ["security", "shell", "injection", "node", "child-process"],
+      "q": 5,
+      "v": "BEST_PRACTICE",
+      "s": "When invoking external commands from Node, use spawn/execFile with an argv array. Never interpolate user-controlled values into a template-literal command string passed to execSync — that is shell-injection by construction.",
+      "p": "// good\nconst { spawnSync } = require('node:child_process');\nspawnSync('git', ['log', '--oneline', '-n', String(n)], { encoding: 'utf8' });\n// bad\nexecSync(`git log --oneline -n ${n}`);",
+      "src": "AIOSON commit 171dbf0 (fix tool-invocation)",
+      "date": "2026-05-07",
+      "not": "execSync(`cmd ${userInput}`) — interpolation goes through /bin/sh and any whitespace/metachar in userInput becomes a new command",
+      "warn": "applies even when input feels trusted — slugs, file paths, agent names can all contain shell metachars in tests/fixtures",
+      "see": ["dev-002"]
+    },
+    {
+      "id": "dev-002",
+      "title": "git commit -m via HEREDOC for multi-line bodies",
+      "tags": ["git", "commit", "shell", "formatting"],
+      "q": 5,
+      "v": "BEST_PRACTICE",
+      "s": "Multi-line commit messages must come from a HEREDOC with single-quoted EOF — anything else mangles backticks, $-escapes, and indentation.",
+      "p": "git commit -m \"$(cat <<'EOF'\nfix(scope): subject\n\nBody paragraph.\nEOF\n)\"",
+      "src": "CLAUDE.md commit protocol",
+      "date": "2026-05-07",
+      "not": "git commit -m \"line1\\nline2\" — \\n is literal; $vars expand; backticks execute",
+      "warn": "the EOF marker must be single-quoted ('EOF') to prevent shell expansion inside the body",
+      "see": ["dev-001"]
+    },
+    {
+      "id": "dev-003",
+      "title": "append-only updates to context cache files",
+      "tags": ["context", "bootstrap", "cache", "idempotency"],
+      "q": 4,
+      "v": "BEST_PRACTICE",
+      "s": "Files that act as system state caches (bootstrap/current-state.md, project-pulse.md, features.md) are append-only. Never replace existing entries — add a new line/row. Other agents trust historical entries to remain stable.",
+      "p": "// good — Edit appending one bullet under existing section\n// bad — Write replacing the whole file",
+      "src": "AIOSON audit Lote B (commits ff14ccf, 5aa1c0c)",
+      "date": "2026-05-07",
+      "not": "regenerating the cache from scratch on every update — destroys the audit trail downstream agents read",
+      "warn": "if an entry is wrong, mark it superseded with a follow-up entry — do not edit the original line",
+      "see": ["dev-005"]
+    },
+    {
+      "id": "dev-004",
+      "title": "Read before Edit — surgical edits over rewrites",
+      "tags": ["editing", "tooling", "discipline"],
+      "q": 5,
+      "v": "BEST_PRACTICE",
+      "s": "Always read the target file before editing. Prefer Edit (single old_string→new_string) over Write (full rewrite). Anchors must be unique enough to match exactly — surrounding context is your friend.",
+      "p": "// good — Edit with a 2-3 line unique anchor\n// bad — Write the whole file just to change one line",
+      "src": "Claude Code Edit tool contract; AIOSON dev.md execution invariants",
+      "date": "2026-05-07",
+      "not": "Write to overwrite an existing file when only one section needs to change — loses concurrent edits and bypasses staleness checks",
+      "warn": "if old_string isn't unique, EITHER widen the anchor OR use replace_all — never guess",
+      "see": ["dev-003"]
+    },
+    {
+      "id": "dev-005",
+      "title": "small validated slices over big-bang implementation",
+      "tags": ["process", "verification", "tdd-lite", "discipline"],
+      "q": 4,
+      "v": "GOOD",
+      "s": "Implement one slice → run the actual verification command (tsc, cargo check, npm test) → only then move to the next slice. Batched debugging at the end is the slowest path.",
+      "p": "loop: { write code → run verification → fix → commit-ready }",
+      "src": "dev.md Execution invariants; Motor AIOSON hardening rules",
+      "date": "2026-05-07",
+      "not": "write 10 files then run tsc — error cascades make root cause hard to find",
+      "warn": "verification command must be the real one (the one CI runs), not a proxy you trust",
+      "see": ["dev-003"]
+    }
+  ]
+}