@jaimevalasek/aioson 1.8.0 → 1.9.0

package/docs/en/{web3.md → 5-reference/web3.md}

@@ -1,54 +1,54 @@
-# Web3 Support
-
-AIOSON includes lightweight Web3 support for small and medium teams using JavaScript/TypeScript workflows.
-
-## Supported framework detection
-- Ethereum: `Hardhat`, `Foundry`, `Truffle`
-- Solana: `Anchor`, `Solana Web3`
-- Cardano: `Cardano` (Aiken and Cardano SDK dependency signals)
-
-## Context contract for dApps
-`project_type` accepts `dapp`, and setup can include:
-- `web3_enabled`
-- `web3_networks`
-- `contract_framework`
-- `wallet_provider`
-- `indexer`
-- `rpc_provider`
-
-## Setup examples
-```bash
-# Interactive
-aioson setup:context
-
-# Defaults with explicit Web3 options
-aioson setup:context . \
-  --defaults \
-  --project-type=dapp \
-  --framework=Hardhat \
-  --web3-enabled=true \
-  --web3-networks=ethereum \
-  --contract-framework=Hardhat \
-  --wallet-provider=wagmi \
-  --indexer="The Graph" \
-  --rpc-provider=Alchemy
-```
-
-## Web3 smoke checks
-```bash
-aioson test:smoke --web3=ethereum
-aioson test:smoke --web3=solana
-aioson test:smoke --web3=cardano
-```
-
-## Skills bundled in templates
-- Static:
-  - `web3-ethereum-patterns.md`
-  - `web3-solana-patterns.md`
-  - `web3-cardano-patterns.md`
-  - `web3-security-checklist.md`
-  - `node-typescript-patterns.md`
-- Dynamic:
-  - `ethereum-docs.md`
-  - `solana-docs.md`
-  - `cardano-docs.md`
+# Web3 Support
+
+AIOSON includes lightweight Web3 support for small and medium teams using JavaScript/TypeScript workflows.
+
+## Supported framework detection
+- Ethereum: `Hardhat`, `Foundry`, `Truffle`
+- Solana: `Anchor`, `Solana Web3`
+- Cardano: `Cardano` (Aiken and Cardano SDK dependency signals)
+
+## Context contract for dApps
+`project_type` accepts `dapp`, and setup can include:
+- `web3_enabled`
+- `web3_networks`
+- `contract_framework`
+- `wallet_provider`
+- `indexer`
+- `rpc_provider`
+
+## Setup examples
+```bash
+# Interactive
+aioson setup:context
+
+# Defaults with explicit Web3 options
+aioson setup:context . \
+  --defaults \
+  --project-type=dapp \
+  --framework=Hardhat \
+  --web3-enabled=true \
+  --web3-networks=ethereum \
+  --contract-framework=Hardhat \
+  --wallet-provider=wagmi \
+  --indexer="The Graph" \
+  --rpc-provider=Alchemy
+```
+
+## Web3 smoke checks
+```bash
+aioson test:smoke --web3=ethereum
+aioson test:smoke --web3=solana
+aioson test:smoke --web3=cardano
+```
+
+## Skills bundled in templates
+- Static:
+  - `web3-ethereum-patterns.md`
+  - `web3-solana-patterns.md`
+  - `web3-cardano-patterns.md`
+  - `web3-security-checklist.md`
+  - `node-typescript-patterns.md`
+- Dynamic:
+  - `ethereum-docs.md`
+  - `solana-docs.md`
+  - `cardano-docs.md`

package/docs/en/README.md

@@ -0,0 +1,115 @@
+# AIOSON Documentation — English
+
+> **AIOSON** is a framework that gives every AI session a **role**, a **protocol**, and a **lifecycle**.
+> Instead of one giant prompt trying to do everything, specialized agents take turns: each owns one slice (discover, plan, implement, test, review) and hands off cleanly to the next.
+
+This is the entry door to the English documentation. It is not an alphabetical index — it is a **map by trails**. Pick yours and follow it.
+
+---
+
+## Trails — pick yours
+
+### I'm new here, I want to understand AIOSON in 15 minutes
+1. [What is AIOSON](./1-understand/what-is-aioson.md) — simple analogy and what it solves
+2. [Why it exists](./1-understand/why-it-exists.md) — the prompt-monolith problem
+3. [Ecosystem map](./1-understand/ecosystem-map.md) — diagram of the agents
+4. [Glossary](./1-understand/glossary.md) — every term in one place
+
+### I want to use AIOSON now, on a project
+1. [First project from scratch](./2-start/first-project.md) — step by step, with real dialogues
+2. [On an existing project](./2-start/existing-project.md) — install + scan + first feature
+3. [Initial decisions](./2-start/initial-decisions.md) — MICRO, SMALL, or MEDIUM? Which AI client?
+
+### I want a recipe ready for my case
+
+**Canonical trails — how features reach the dev:**
+1. **[Full feature with @sheldon](./3-recipes/full-feature-with-sheldon.md)** — the main trail: `@product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa` (with optional gates from `@tester` and `@pentester`)
+2. [From idea to PRD via @briefing](./3-recipes/from-idea-to-prd-via-briefing.md) — when the idea is still vague
+3. [Continuity between sessions](./3-recipes/continuity-between-sessions.md) — feature dossier, dev-resume, drift detection
+
+**By scenario** — translation pending; the canonical PT versions are listed for reference:
+- External plans for @product *(coming soon — [PT](../pt/3-receitas/plans-externos-para-product.md))*
+- Landing page *(coming soon — [PT](../pt/3-receitas/landing-page.md))*
+- SaaS app from scratch *(coming soon — [PT](../pt/3-receitas/app-saas-do-zero.md))*
+- Integration in large codebase *(coming soon — [PT](../pt/3-receitas/integracao-em-codebase-grande.md))*
+- Large refactor *(coming soon — [PT](../pt/3-receitas/refatoracao-grande.md))*
+- Security audit *(coming soon — [PT](../pt/3-receitas/auditoria-seguranca.md))*
+- Publish on aioson.com *(coming soon — [PT](../pt/3-receitas/publicar-no-aioson-com.md))*
+- Clone site design *(coming soon — [PT](../pt/3-receitas/clonar-design-de-site.md))*
+
+See [3-recipes/README.md](./3-recipes/README.md) for the full list.
+
+### I want the technical reference for an agent or command
+- **[Agent cards (in progress)](./4-agents/README.md)** — stub today; full set is in [docs/pt/4-agentes/](../pt/4-agentes/README.md) (28 cards)
+- **[Technical reference](./5-reference/README.md)** — 11 docs migrated from the previous flat structure (CLI, MCP, parallel, QA browser, squad dashboard, web3, i18n, JSON schemas, release flow)
+
+### Highlights of `5-reference/`
+- [CLI reference](./5-reference/cli-reference.md) — every command in one place
+- [JSON schemas](./5-reference/json-schemas.md) — `--json` output contracts
+- [MCP guide](./5-reference/mcp.md) — Model Context Protocol setup
+- [Parallel orchestration](./5-reference/parallel.md) — multi-lane execution
+- [Browser QA](./5-reference/qa-browser.md) — Playwright-based smoke runs
+- [Squad Dashboard](./5-reference/squad-dashboard.md) — real-time monitoring panel
+- [Web3 guide](./5-reference/web3.md) — Hardhat/Foundry/Anchor support
+- [i18n](./5-reference/i18n.md) — localization layer
+- **[Active Learning Loop](./active-learning-loop/README.md)** — automatic distillation in `feature:close` + BM25 search over learnings + archive/restore with `evolution_log` + 3 new curation checks in doctor
+- **[Deyvin Sub-Task Scout](./deyvin-subtask-scout/README.md)** — `@deyvin`'s structured diagnostic primitive: `scout:prep/validate/commit`, isolated context, configurable caps, feature archival
+
+---
+
+## Quick glossary
+
+Terms that show up everywhere. Expanded version in [`1-understand/glossary.md`](./1-understand/glossary.md).
+
+| Term | What it is |
+|---|---|
+| **Agent** | A specialist persona (`@product`, `@dev`, `@qa`...) with its own prompt and rules |
+| **Squad** | A group of custom agents you build for a specific domain |
+| **Genome** | The "cognitive DNA" of a persona — used to build advisors with personality |
+| **Skill** | A pluggable instruction package (design system, process, domain knowledge) |
+| **Dossier** | A feature folder: spec, plan, decisions, status — everything in one place |
+| **Classification** | MICRO / SMALL / MEDIUM — defines how much process the project needs |
+| **Constitution** | 6 principles every agent respects — non-overridable |
+
+---
+
+## In three commands
+
+```bash
+# 1. Install on your machine (one time)
+npx @jaimevalasek/aioson init my-project
+
+# 2. Enter the project
+cd my-project
+
+# 3. Open your AI client (Claude Code, Codex, Gemini, OpenCode) and type:
+@setup
+```
+
+From there, the agents guide you. Details in [First project from scratch](./2-start/first-project.md).
+
+---
+
+## Other languages
+
+- **Portuguese (`docs/pt/`)** — the canonical reformed documentation: 81 active docs, 5 layers, ~92k words. Use it as a reference whenever an English doc has not been translated yet.
+- **Spanish, French** — not started.
+
+---
+
+## Status of this documentation
+
+This English portal is being **incrementally translated** from `docs/pt/`. The phased rollout is:
+
+**Phase 1 (Phased rollout, current)** — entry-door layers translated:
+- 1-understand (4 docs) ✓
+- 2-start (3 docs) ✓
+- 3-recipes (3 canonical trails + index) ✓
+- 5-reference (11 docs migrated from previous flat structure) ✓
+- 4-agents (stub README; full agent cards pending)
+
+**Phase 2 (next)** — remaining 8 scenario recipes in 3-recipes/.
+**Phase 3 (next)** — 28 agent cards in 4-agents/.
+**Phase 4 (next)** — remaining ~18 reference docs in 5-reference/ (feature-dossier, agent-chain-continuity, sdd-framework, live-sessions, secure-by-default, aioson-com-store, etc.).
+
+For anything not yet in English, the PT version is current and authoritative — the AIOSON behaviors, agent prompts, and CLI commands are language-agnostic.

package/docs/en/active-learning-loop/README.md

@@ -0,0 +1,117 @@
+# Active Learning Loop — English guide
+
+> **Active Learning Loop** is the cycle that closes the arc between AIOSON's existing learning primitives and the feature lifecycle. When a feature is closed with `feature:close --verdict=PASS`, the framework automatically triggers distillation: learnings are promoted to rules, `doctor` monitors curation gaps, and a human-approved archive flow keeps project memory organized.
+
+This folder documents the complete feature — 6 phases, 4 new CLI verbs, 3 new doctor checks.
+
+---
+
+## What it does
+
+- **Close the learning loop** — without Active Learning Loop, learnings accumulate in `project_learnings` but never become usable rules. This feature connects the two ends: `feature:close` → automatic distillation → rules ready for the next agent.
+- **Measure real rule usage** — agents declare "I loaded this rule" via `aioson context:load`. The doctor uses that signal to identify rules no one consults anymore.
+- **Search memory quickly** — `aioson memory:search` provides BM25 search over learnings, directly from the terminal.
+- **Archive with traceability** — `aioson memory:archive` moves obsolete rules/brains to `_archived/` with an append-only evolution log; `memory:restore` undoes it if needed.
+- **Surface curation gaps** — three new `doctor` checks (rule staleness, orphan learnings, distillation lag) generate actionable hints with ready-to-copy commands.
+
+---
+
+## Prerequisites
+
+- AIOSON installed (version that shipped this feature)
+- `.aioson/config/learning-loop.json` present in the project (copied automatically by the installer; see [Configuration](#configuration))
+- Project classified as SMALL or MEDIUM — MICRO projects opt out automatically (no distillation, no doctor checks)
+
+---
+
+## Reading guide
+
+### I want to understand what changed in my workflow (10 min)
+1. [What is the Active Learning Loop](./active-learning-loop.md) — the problem, the 6 phases, the complete flow
+2. [Diagrams](./diagrams.md) — ASCII flow of `feature:close` → distillation → `evolution_log` → `doctor`
+
+### I want to use it now
+3. [How to use](./how-to-use.md) — search a learning, archive a stale rule, what `feature:close` does now
+4. [CLI reference](./cli-commands.md) — all flags for the 4 new verbs
+
+### Something happened / I want to understand what the doctor is saying
+5. [Doctor checks](./doctor-checks.md) — what each of the 3 new checks means and how to act
+6. [Troubleshooting](./troubleshooting.md) — stuck lock, MICRO opt-out, `pattern:detect` deferred, `aioson update` overwrites config
+
+---
+
+## Canonical commands
+
+| Command | What it does | Tier | Doc |
+|---|---|---|---|
+| `aioson context:load --target=rule:<slug> --agent=<name>` | Records that an agent loaded a rule/brain | tier-1 silent | [CLI reference](./cli-commands.md) |
+| `aioson memory:search "<query>"` | BM25 search over learnings by keyword | tier-1 silent | [CLI reference](./cli-commands.md) |
+| `aioson memory:archive --id=rule:<slug> --reason="<text>"` | Archives a rule/learning/brain with evolution log | tier-2 notified | [CLI reference](./cli-commands.md) |
+| `aioson memory:restore --id=rule:<slug>` | Restores an archived item | tier-2 notified | [CLI reference](./cli-commands.md) |
+| `aioson feature:close --slug=X --verdict=PASS` | Closes feature + triggers automatic distillation (new) | tier-2 notified | [How to use](./how-to-use.md) |
+| `aioson doctor .` | Diagnostics, including 3 new curation checks | tier-1 silent | [Doctor checks](./doctor-checks.md) |
+
+---
+
+## Where artifacts live
+
+| Path | Role |
+|---|---|
+| `.aioson/config/learning-loop.json` | Per-project loop configuration (thresholds, opt-out, timeout) |
+| `.aioson/rules/_archived/YYYY-MM-DD/<slug>.md` | Archived rules with archival date |
+| `.aioson/brains/_archived/YYYY-MM-DD/<id>.brain.json` | Archived brains |
+| `.aioson/context/_archived/YYYY-MM-DD/<slug>.json` | Archived learnings |
+| `.aioson/runtime/aios.sqlite` → table `evolution_log` | Append-only log of all memory mutations |
+| `.aioson/runtime/aios.sqlite` → table `execution_events` | `rule_loaded` / `brain_loaded` events emitted by `context:load` |
+| `.aioson/runtime/aios.sqlite` → virtual table `project_learnings_fts` | FTS5 index over `project_learnings` (title + evidence) |
+
+---
+
+## Configuration
+
+`.aioson/config/learning-loop.json` is copied from the template on first install:
+
+```json
+{
+  "$schema": "https://aioson.dev/schemas/learning-loop.v1.json",
+  "enabled": true,
+  "skip_on_classification": ["MICRO"],
+  "execution_mode": "foreground",
+  "lock_strategy": "sqlite-row",
+  "auto_promote_threshold": 3,
+  "staleness_window_features_min": 5,
+  "timeout_ms": 5000
+}
+```
+
+| Field | Controls |
+|---|---|
+| `enabled` | Enables/disables the entire loop for the project |
+| `skip_on_classification` | Classifications that opt out automatically (default: `["MICRO"]`) |
+| `auto_promote_threshold` | How many evidence entries a learning needs to be automatically promoted |
+| `staleness_window_features_min` | Minimum closed features to calculate the staleness window |
+| `timeout_ms` | Foreground distillation timeout (default: 5000ms) |
+
+> **Warning:** `aioson update` currently **overwrites** this file (existing installer policy). Back up any customizations before running `aioson update`. See [Troubleshooting](./troubleshooting.md#aioson-update-overwrites-learning-loopjson).
+
+---
+
+## Status
+
+The `active-learning-loop` feature was delivered in 6 phases:
+
+| Phase | Slug | Delivery | Status |
+|---|---|---|---|
+| 1 | `telemetry-foundation` | CLI `context:load` + `rule_loaded`/`brain_loaded` events | PASS |
+| 2 | `memory-search-fts5` | CLI `memory:search` + FTS5 BM25 index | PASS |
+| 3 | `memory-archive-with-evolution-log` | CLI `memory:archive` + `memory:restore` + `evolution_log` | PASS |
+| 4 | `doctor-curation-checks` | 3 new checks: staleness, orphans, distillation lag | PASS |
+| 5 | `feature-close-distillation-hook` | Hook in `feature:close` + foreground distillation | PASS |
+| 6 | `inception-mirror-parity` | `src/` ↔ `template/src/` parity validation | PASS |
+
+112/112 deterministic tests passing. QA approved.
+
+Specification artifacts (archived):
+- [PRD](../../.aioson/context/done/active-learning-loop/prd-active-learning-loop.md)
+- [Spec](../../.aioson/context/done/active-learning-loop/spec-active-learning-loop.md)
+- [Architecture](../../.aioson/context/done/active-learning-loop/architecture-active-learning-loop.md)

package/docs/en/active-learning-loop/active-learning-loop.md

@@ -0,0 +1,117 @@
+# What is the Active Learning Loop
+
+## The problem
+
+AIOSON already knew how to learn. After each session, `project_learnings` accumulates observations: detected patterns, corrected errors, decisions made. But there was a gap: those learnings rarely became active rules. Distillation existed as a manual command that few people ran. Existing rules accumulated without anyone knowing which ones were still consulted.
+
+The practical result: after N features, the project's memory was full of learnings that never closed the loop — neither became usable rules nor were archived. The `doctor` had no visibility into the problem. Agents kept reading rules that nobody had validated in months.
+
+Active Learning Loop closes that arc.
+
+## What the feature does
+
+Four new surfaces, interconnected:
+
+**1. Load telemetry** — agents explicitly declare "I loaded this rule/brain" via `aioson context:load`. The CLI records a `rule_loaded` or `brain_loaded` event in `execution_events`. Silent, tier-1. The doctor uses that signal later.
+
+**2. Memory search** — `aioson memory:search "JWT authentication"` performs BM25 search over the title and evidence of all active learnings. No configuration, no embeddings, no LLM call — native SQLite FTS5.
+
+**3. Archive with traceability** — `aioson memory:archive --id=rule:my-rule --reason="replaced by X"` moves the physical file to `.aioson/rules/_archived/YYYY-MM-DD/` and writes a pair of rows to `evolution_log`: the previous active entry receives `end_at`, a new entry documents the reason. Append-only — history never changes. `memory:restore` reverses the process if needed.
+
+**4. Automatic distillation in `feature:close`** — when you close a feature with `--verdict=PASS`, the CLI runs `runDistillation()` in the foreground (5s timeout), promotes learnings that crossed the threshold, emits a notification with the summary, and records the result in `evolution_log`. If it fails for any reason, the `feature:close` exit code remains 0 — distillation is best-effort.
+
+## The 6 phases
+
+### Phase 1 — telemetry-foundation
+
+New CLI verb: `aioson context:load`. Agents call this command when they load a rule or brain at the start of a session. The event goes to `execution_events` as `rule_loaded` or `brain_loaded`, with payload: slug, agent, associated feature (optional).
+
+The verb supports `--batch="rule-a,rule-b,rule-c"` to minimize calls when an agent loads multiple rules at once.
+
+No visible change in agent behavior — it's silent telemetry. The value appears in phases 4 and 5.
+
+### Phase 2 — memory-search-fts5
+
+New verb: `aioson memory:search "<query>"`. Creates an FTS5 virtual table (`project_learnings_fts`) over `project_learnings`, synchronized via SQL triggers (INSERT/UPDATE/DELETE). BM25 ranking by default.
+
+Query sanitization: each token (whitespace-separated) becomes a quoted phrase ANDed with the others. FTS5 operator characters (`*()^:+-"`) are stripped. Queries that result in an empty string return `{ ok: false, reason: 'query_unparseable' }` without error. 500-character limit.
+
+Archived entries are excluded by default; `--include-archived` includes them.
+
+### Phase 3 — memory-archive-with-evolution-log
+
+Two new verbs: `memory:archive` and `memory:restore`.
+
+`memory:archive` is tier-2 (notified): emits `aioson notify --level=warn` before any mutation, moves the physical file to `_archived/YYYY-MM-DD/`, and writes two rows to `evolution_log` — `end_at` on the previous active entry, a new entry with the reason. The operation is atomic: if the DB write fails after the physical move, the file is restored (FS rollback).
+
+`--dry-run` simulates the entire operation without side effects.
+
+`memory:restore` reverses it: moves the file back, writes `event_type='restored'` to `evolution_log`.
+
+**Tier-2 human-only**: both `memory:archive` and `memory:restore` refuse execution when `AIOSON_RUNTIME_HOOK=1` is set (automated hook environment). These operations are intentionally restricted to humans.
+
+### Phase 4 — doctor-curation-checks
+
+Three new checks in `aioson doctor`, with `severity='warning'` (they do not block `ok=true`, but appear in `failedCount`):
+
+1. **`living-memory:rule_staleness`** — rules with zero `rule_loaded` events in the last N closed features. N = max(5, ceil(average days between last 5 features ÷ 7)).
+2. **`living-memory:learning_orphans`** — learnings with `status=promoted` whose target rule had no `rule_loaded` after the promotion. Indicates the generated rule was never used.
+3. **`living-memory:distillation_lag`** — 5+ features closed, but fewer `auto_distillation` events than closed features. The loop is not running as expected.
+
+Projects with MICRO classification opt out of all three checks.
+
+The hint for each check includes the ready-to-copy command: `aioson memory:archive --id=rule:<slug> --reason="..."`.
+
+### Phase 5 — feature-close-distillation-hook
+
+`aioson feature:close --slug=X --verdict=PASS` now calls `runDistillation(X)` after the dossier finalization step, before returning.
+
+The flow:
+1. Reads the PRD classification — if MICRO, emits notify and skips.
+2. Checks feature status in `features.md` — if `abandoned`, skips.
+3. Attempts to acquire the lock via INSERT into `evolution_log` (row with `end_at=NULL`). If an active row for the feature already exists, emits notify "already in progress" and exits with 0.
+4. Runs `learning:auto-promote --feature=X` with a 5s timeout.
+5. On completion: UPDATE of the lock row with `end_at=now()` and `payload.state='complete'`.
+6. Emits `aioson notify --level=info --topic=learning-loop --message="distillation: N promoted, M for review, K merge candidates"`.
+
+If `runDistillation` throws, the catch records `event_type='distillation_failed'` in `evolution_log` and swallows the error. `feature:close` returns 0 regardless.
+
+`--no-distill` disables the hook for the current call.
+
+### Phase 6 — inception-mirror-parity
+
+Infrastructure validation — no new user-facing surface. Ensures a project created with `aioson setup` inherits the same loop the AIOSON repository uses. `npm run sync:agents:preflight` was extended to detect drift in the 10 new files, autonomy-protocol entries, and `_archived/` placeholders.
+
+## How the pieces connect
+
+```
+Agent loads a rule
+  └─ aioson context:load --target=rule:authn --agent=dev
+        └─ records execution_events (rule_loaded)
+
+Agent works, feature closes
+  └─ aioson feature:close --slug=authn-flow --verdict=PASS
+        └─ runDistillation()
+              ├─ learning:auto-promote → promotes mature learnings
+              ├─ UPDATE evolution_log (distillation complete)
+              └─ notify "N promoted, M for review"
+
+Doctor checks periodically
+  └─ aioson doctor .
+        ├─ rule_staleness: rule 'authn' with no rule_loaded in 8 features
+        ├─ learning_orphans: learning 'jwt-expiry-pattern' promoted but rule never loaded
+        └─ distillation_lag: 7 features closed, 4 distillations recorded
+
+Human acts on hints
+  └─ aioson memory:archive --id=rule:authn --reason="obsolete after OAuth migration"
+        ├─ notify --level=warn (before mutation)
+        ├─ physical move: .aioson/rules/authn.md → .aioson/rules/_archived/2026-05-14/authn.md
+        └─ evolution_log: end_at on previous entry, new entry with reason
+```
+
+## Continue reading
+
+- [Diagrams](./diagrams.md) — detailed ASCII flow
+- [How to use](./how-to-use.md) — concrete examples
+- [CLI reference](./cli-commands.md) — all flags
+- [Doctor checks](./doctor-checks.md) — what each check means