@jaimevalasek/aioson 1.7.2 → 1.9.0

package/template/.aioson/design-docs/componentization.md

@@ -0,0 +1,47 @@
+---
+description: "When and how to extract components, modules, and abstractions"
+scope: "governance"
+agents: []
+---
+
+# Componentization — Governance Rules
+
+> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+
+## When to extract
+
+Extract a component, module, or function when ANY of these is true:
+
+1. **Duplication** — the same logic appears in 2 or more different places
+2. **Size** — a file is approaching 300 lines of pure logic (excluding comments and blank lines)
+3. **Testability** — the piece of logic can be tested in isolation from the rest
+4. **Description** — the responsibility can be stated in one short, specific sentence
+
+## When to keep inline
+
+Keep logic inline when ALL of these are true:
+
+- Used in exactly one place
+- Under ~50 lines
+- Extracting it would create a file with a single trivial function
+- No second confirmed use case exists
+
+## Single responsibility
+
+- One file = one primary responsibility
+- Supporting helper functions for that primary responsibility may coexist in the same file
+- Helper functions used in 2+ files → move to a shared utility or dedicated module
+
+## Avoid premature abstraction
+
+- Do not create abstractions for hypothetical future requirements
+- Three similar-but-not-identical code blocks is not always a reason to abstract — wait for the pattern to stabilize
+- An abstraction that is harder to understand than the original code is a liability, not an asset
+- The right abstraction reveals intent. If the name cannot describe what it does in 3 words or fewer, reconsider.
+
+## Signals that an abstraction is wrong
+
+- The function needs many flags or mode switches to handle different callers
+- The caller has to know internal details to use it correctly
+- Tests for the abstraction are harder to read than tests for the original code
+- Removing the abstraction and inlining the logic would make the code clearer

package/template/.aioson/design-docs/file-size.md

@@ -0,0 +1,52 @@
+---
+description: "File size guidelines, alert thresholds, and split strategies"
+scope: "governance"
+agents: []
+---
+
+# File Size — Governance Rules
+
+> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+
+## Thresholds
+
+| Lines | Status | Action |
+|-------|--------|--------|
+| < 300 | Ideal | Continue normally |
+| 300–500 | Acceptable | Monitor growth; do not split preemptively |
+| > 500 | Alert | Propose split before writing more code |
+
+Lines are counted as pure logic — comments, blank lines, and closing braces do not count toward the threshold.
+
+## Alert protocol
+
+When estimating that a resulting file will exceed 500 lines:
+
+1. Emit the alert with the estimated line count and file path
+2. List 2–3 concrete extraction alternatives with real file paths
+3. `@dev`: wait for user confirmation before proceeding
+4. `@deyvin` pair mode: present alternatives and continue after 1 turn with no response
+
+The alert is never blocking — it is a pause to think, not an impediment.
+
+## Common split strategies
+
+| Situation | Split approach |
+|-----------|---------------|
+| Large command / controller | Extract business logic to a `service/` or `lib/` module |
+| Validation logic growing | Extract to `validate-{domain}.js` / `{domain}_validator.py` |
+| Formatting / serialization | Extract to `format-{domain}.js` or a dedicated serializer |
+| Mixed read/write concerns | Separate into a reader and a writer module |
+| Route file growing | Group into feature sub-routers |
+| Large test file | Split by domain or by test type (unit / integration / e2e) |
+| Large React component | Extract sub-components and move logic to a custom hook |
+| Large class with many methods | Extract related method groups into collaborator classes |
+
+## Exceptions
+
+These file types are exempt from the size guideline:
+
+- Internationalization / locale files (`messages.json`, `en.yml`, `pt-BR.ts`)
+- Test fixtures and factories
+- Auto-generated files (migrations with timestamps, GraphQL schemas, OpenAPI specs)
+- Configuration files with many entries (`routes.php`, `config/app.ts`, `webpack.config.js`)

package/template/.aioson/design-docs/folder-structure.md

@@ -0,0 +1,51 @@
+---
+description: "Universal folder organization rules — hierarchy, depth, naming, grouping"
+scope: "governance"
+agents: []
+---
+
+# Folder Structure — Governance Rules
+
+> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+
+## Depth
+
+- Maximum 3 levels of nesting before splitting into a separate module.
+- If you need a 4th level, the responsibility likely belongs in its own module or package.
+
+## Naming
+
+- **kebab-case** for all folder names: `user-auth/`, `squad-dashboard/`, `context-cache/`
+- **Singular** for a single entity or specific responsibility: `service/`, `command/`, `handler/`
+- **Plural** for collections of items of the same type: `services/`, `commands/`, `handlers/`
+- Never mix styles within the same directory level
+
+## Grouping strategy
+
+Prefer **domain-based grouping** over layer-based when the project grows beyond 5–6 modules:
+
+```
+src/
+  auth/         ← domain: everything related to authentication
+  billing/      ← domain: everything related to billing
+  shared/       ← cross-domain: utilities, types, helpers
+```
+
+Layer-based is valid for small projects or when the framework enforces it:
+
+```
+src/
+  controllers/  ← HTTP layer
+  services/     ← business logic
+  models/       ← data layer
+  utils/        ← shared helpers
+```
+
+Choose one strategy and stay consistent within the same project.
+
+## Anti-patterns
+
+- Never use generic folders: `misc/`, `stuff/`, `temp/`, `old/`, `helpers/`
+- Never leave unrelated files loose in `src/` root — every file belongs to a domain
+- Never create a folder with a single file (except `index.js` / `index.ts` as a public module entry point)
+- Never nest a folder that has the same semantic scope as its parent

package/template/.aioson/design-docs/naming.md

@@ -0,0 +1,54 @@
+---
+description: "Naming conventions for files, variables, functions, and classes"
+scope: "governance"
+agents: []
+---
+
+# Naming — Governance Rules
+
+> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+
+## Files
+
+- **kebab-case** for all source files: `user-auth.js`, `billing-service.ts`, `context-writer.py`
+- When inside a flat directory, use a domain prefix to group related files: `user-create.js`, `user-update.js`, `user-delete.js`
+- Avoid generic suffixes when the domain name already conveys the type: prefer `auth.js` over `auth-helper.js`
+- Test files mirror the source file name: `user-auth.test.js`, `billing_service_test.py`
+
+## Variables and constants
+
+| Type | JS / TS | Python / Ruby | Go / Rust |
+|------|---------|---------------|-----------|
+| Local variables | camelCase | snake_case | camelCase / snake_case |
+| Global constants | SCREAMING_SNAKE_CASE | SCREAMING_SNAKE_CASE | SCREAMING_SNAKE_CASE |
+| Environment variables | SCREAMING_SNAKE_CASE | SCREAMING_SNAKE_CASE | SCREAMING_SNAKE_CASE |
+
+## Functions and methods
+
+Pattern: **verb + noun** — describes what the function does and to what.
+
+Good: `loadUser()`, `parseManifest()`, `validateEmail()`, `sendInvoice()`, `buildQuery()`
+Avoid: `doUser()`, `process()`, `handle()` — too vague to understand intent
+Avoid: `userLoader()`, `manifestParser()` — noun-first reads as a class or object, not a function
+
+## Booleans
+
+Always use a prefix that makes the boolean read as a yes/no question:
+
+- `is` — state: `isReady`, `isEmpty`, `isAuthenticated`, `isValid`
+- `has` — possession: `hasErrors`, `hasChildren`, `hasPermission`
+- `should` — intent: `shouldRetry`, `shouldRedirect`, `shouldNotify`
+- `can` — capability: `canEdit`, `canDelete`, `canPublish`
+
+## Classes and components
+
+- **PascalCase**: `UserService`, `BillingController`, `AuthModal`, `InvoiceJob`
+- Singular: `User`, not `Users` — a class represents one entity, not a collection
+- React / Vue / Svelte components: same PascalCase rule, filename in kebab-case: `UserCard.tsx` → `user-card.tsx`
+
+## Avoid
+
+- Abbreviations unless they are industry-standard: `url`, `id`, `api`, `html`, `dto` are fine; `usrCtx`, `mngr`, `cfg`, `hlpr` are not
+- Single-letter variables except for loop indices (`i`, `j`, `k`) and math/geometry variables
+- Names that describe the type instead of the intent: `dataObject`, `listArray`, `stringValue`
+- Negative booleans: `isNotReady`, `hasNoErrors` — flip to positive: `isReady`, `isValid`

package/template/.aioson/docs/LAYERS.md

@@ -1,79 +1,89 @@
----
-description: "Guide to the three project memory layers: rules, docs, and design-docs — when to use each"
-agents: []
----
-
-# AIOSON Project Memory Layers
-
-Three directories accumulate project knowledge over time.
-Each has a different purpose and a different update cadence.
-
----
-
-## Layer 1 — `.aioson/rules/`
-
-**What it is:** behavioral overrides for agents.
-**Who writes it:** the user, or promoted from recurring @dev patterns.
-**When to use:** when you want to enforce a convention that overrides agent defaults — globally or for specific agents.
-**Cadence:** stable. Rules change rarely; only when a convention is proven wrong or superseded.
-
-Examples of good rules:
-- "All API routes must follow REST naming conventions in this project"
-- "Never use float for monetary values — use integer cents"
-- "The @dev agent must always write a migration for schema changes"
-
-See `rules/README.md` for format and frontmatter reference.
-
----
-
-## Layer 2 — `.aioson/docs/`
-
-**What it is:** domain knowledge and technical reference that agents load on demand.
-**Who writes it:** the user or @architect, based on real integration and domain complexity.
-**When to use:** when multiple agents across different features need the same external context — API behavior, third-party quirks, data model explanations, integration patterns.
-**Cadence:** updated when the referenced system changes, not after every feature.
-
-Examples of good docs:
-- `stripe-integration-context.md` — describes webhook event model, idempotency keys used
-- `auth-rbac-model.md` — explains the role/permission system as it stands in production
-- `legacy-api-behavior.md` — documents known quirks of an external API affecting multiple features
-
-See `docs/README.md` for format and naming conventions.
-
----
-
-## Layer 3 — `.aioson/context/design-doc*.md`
-
-**What it is:** living decision document for the current feature or project scope.
-**Who writes it:** @discovery-design-doc.
-**Who updates it:** @dev at feature close, @discovery-design-doc when resuming.
-**When to use:** automatically — one per feature (`design-doc-{slug}.md`) or one project-wide (`design-doc.md`).
-**Cadence:** updated at the end of each feature implementation session. Decisions are append-only — never deleted.
-
----
-
-## Decision Guide
-
-| Situation | Where it goes |
-|-----------|--------------|
-| Enforce a coding convention for this project | `rules/` |
-| Agents must always know about an external API behavior | `docs/` |
-| Document the scope and decisions for a specific feature | `design-doc-{slug}.md` |
-| Log a global project-wide architecture decision | `design-doc.md` |
-| Promote a recurring @dev pattern | `rules/` via @dev promotion |
-| Document an integration used by 3+ features | `docs/` |
-| Record what was decided during a single feature session | `design-doc-{slug}.md` (Decisions already made section) |
-
----
-
-## What NOT to put in these layers
-
-| Content | Where it actually belongs |
-|---------|--------------------------|
-| Feature requirements | `requirements-{slug}.md` |
-| PRD / product scope | `prd-{slug}.md` |
-| Execution sequence | `implementation-plan-{slug}.md` |
-| Current implementation state | `spec-{slug}.md` |
-| Project-wide context | `project.context.md` |
-| Domain entity map | `discovery.md` |
-| Technical architecture | `architecture.md` |
+---
+description: "Guide to the three project memory layers: rules, docs, and design-docs — when to use each"
+agents: []
+---
+
+# AIOSON Project Memory Layers
+
+Four directories accumulate project knowledge over time.
+Each has a different purpose and a different update cadence.
+
+---
+
+## Layer 1 — `.aioson/rules/`
+
+**What it is:** behavioral overrides for agents.
+**Who writes it:** the user, or promoted from recurring @dev patterns.
+**When to use:** when you want to enforce a convention that overrides agent defaults — globally or for specific agents.
+**Cadence:** stable. Rules change rarely; only when a convention is proven wrong or superseded.
+
+Examples of good rules:
+- "All API routes must follow REST naming conventions in this project"
+- "Never use float for monetary values — use integer cents"
+- "The @dev agent must always write a migration for schema changes"
+
+See `rules/README.md` for format and frontmatter reference.
+
+---
+
+## Layer 2 — `.aioson/docs/`
+
+**What it is:** domain knowledge and technical reference that agents load on demand.
+**Who writes it:** the user or @architect, based on real integration and domain complexity.
+**When to use:** when multiple agents across different features need the same external context — API behavior, third-party quirks, data model explanations, integration patterns.
+**Cadence:** updated when the referenced system changes, not after every feature.
+
+Examples of good docs:
+- `stripe-integration-context.md` — describes webhook event model, idempotency keys used
+- `auth-rbac-model.md` — explains the role/permission system as it stands in production
+- `legacy-api-behavior.md` — documents known quirks of an external API affecting multiple features
+
+See `docs/README.md` for format and naming conventions.
+
+---
+
+## Layer 3 — `.aioson/design-docs/`
+
+**What it is:** structural code governance: folder structure, componentization, reuse, naming, and file-size thresholds.
+**Who writes it:** installed by AIOSON, then edited by the project team when conventions change.
+**When to use:** before architectural structure decisions and before implementation that creates files, splits modules, introduces reusable code, or names APIs.
+**Cadence:** stable. These files are project-local and preserved on update.
+
+---
+
+## Layer 4 — `.aioson/context/design-doc*.md`
+
+**What it is:** living decision document for the current feature or project scope.
+**Who writes it:** @discovery-design-doc.
+**Who updates it:** @dev at feature close, @discovery-design-doc when resuming.
+**When to use:** automatically — one per feature (`design-doc-{slug}.md`) or one project-wide (`design-doc.md`).
+**Cadence:** updated at the end of each feature implementation session. Decisions are append-only — never deleted.
+
+---
+
+## Decision Guide
+
+| Situation | Where it goes |
+|-----------|--------------|
+| Enforce a coding convention for this project | `rules/` |
+| Agents must always know about an external API behavior | `docs/` |
+| Enforce structural code quality guidance | `design-docs/` |
+| Document the scope and decisions for a specific feature | `design-doc-{slug}.md` |
+| Log a global project-wide architecture decision | `design-doc.md` |
+| Promote a recurring @dev pattern | `rules/` via @dev promotion |
+| Document an integration used by 3+ features | `docs/` |
+| Record what was decided during a single feature session | `design-doc-{slug}.md` (Decisions already made section) |
+
+---
+
+## What NOT to put in these layers
+
+| Content | Where it actually belongs |
+|---------|--------------------------|
+| Feature requirements | `requirements-{slug}.md` |
+| PRD / product scope | `prd-{slug}.md` |
+| Execution sequence | `implementation-plan-{slug}.md` |
+| Current implementation state | `spec-{slug}.md` |
+| Project-wide context | `project.context.md` |
+| Domain entity map | `discovery.md` |
+| Technical architecture | `architecture.md` |

package/template/.aioson/docs/README.md

@@ -1,76 +1,76 @@
----
-description: "Guide to the docs layer: domain knowledge and technical reference for agents"
-agents: []
----
-
-# Project Docs
-
-Files in this directory are domain knowledge and technical reference that agents load on demand.
-
-Unlike `rules/` (which enforce conventions), docs explain **how something works** — external APIs, data models, integration patterns, legacy behavior, third-party quirks.
-
----
-
-## Frontmatter Format
-
-```yaml
----
-description: "Short description of what this doc covers — used by agents to decide relevance"
-scope: "global"       # or a feature slug if doc is scoped to one area
-agents: []            # empty = any agent may load; or restrict: [dev, architect]
----
-```
-
----
-
-## Field Reference
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `description` | yes | What this doc covers — agents use this to decide whether to load it |
-| `scope` | no | `global` (default) or a feature slug for narrow scope |
-| `agents` | no | If empty, any agent may load; if listed, only those agents load it |
-
----
-
-## Loading Behavior
-
-Agents load docs when the `description` frontmatter is relevant to the current task.
-An empty `agents:` field means any agent can load the doc.
-Docs are loaded in addition to the current context — not as replacements.
-
----
-
-## When to Create a Doc
-
-Create a doc when:
-- Two or more features need the same external context
-- An integration has non-obvious behavior that has caused bugs or would cause rework
-- A data model exists only in production and is not derivable from the codebase
-- A third-party API has quirks that affect how agents implement against it
-
-Do NOT create a doc for:
-- Feature-specific decisions (use `design-doc-{slug}.md` instead)
-- Project conventions (use `rules/` instead)
-- Current implementation state (use `spec-{slug}.md` instead)
-
----
-
-## Naming Convention
-
-Use kebab-case. Name the file after the system or concept, not the feature:
-
-| Good | Bad |
-|------|-----|
-| `stripe-webhook-behavior.md` | `billing-feature-notes.md` |
-| `auth-rbac-model.md` | `auth-stuff.md` |
-| `legacy-api-quirks.md` | `misc-notes.md` |
-| `email-delivery-constraints.md` | `sendgrid.md` (too generic) |
-
----
-
-## Example
-
-See `example-external-api-context.md` in this directory for a working template.
-
-For the layer separation guide (when to use `docs/` vs `rules/` vs `design-doc`), see `LAYERS.md`.
+---
+description: "Guide to the docs layer: domain knowledge and technical reference for agents"
+agents: []
+---
+
+# Project Docs
+
+Files in this directory are domain knowledge and technical reference that agents load on demand.
+
+Unlike `rules/` (which enforce conventions), docs explain **how something works** — external APIs, data models, integration patterns, legacy behavior, third-party quirks.
+
+---
+
+## Frontmatter Format
+
+```yaml
+---
+description: "Short description of what this doc covers — used by agents to decide relevance"
+scope: "global"       # or a feature slug if doc is scoped to one area
+agents: []            # empty = any agent may load; or restrict: [dev, architect]
+---
+```
+
+---
+
+## Field Reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | yes | What this doc covers — agents use this to decide whether to load it |
+| `scope` | no | `global` (default) or a feature slug for narrow scope |
+| `agents` | no | If empty, any agent may load; if listed, only those agents load it |
+
+---
+
+## Loading Behavior
+
+Agents load docs when the `description` frontmatter is relevant to the current task.
+An empty `agents:` field means any agent can load the doc.
+Docs are loaded in addition to the current context — not as replacements.
+
+---
+
+## When to Create a Doc
+
+Create a doc when:
+- Two or more features need the same external context
+- An integration has non-obvious behavior that has caused bugs or would cause rework
+- A data model exists only in production and is not derivable from the codebase
+- A third-party API has quirks that affect how agents implement against it
+
+Do NOT create a doc for:
+- Feature-specific decisions (use `design-doc-{slug}.md` instead)
+- Project conventions (use `rules/` instead)
+- Current implementation state (use `spec-{slug}.md` instead)
+
+---
+
+## Naming Convention
+
+Use kebab-case. Name the file after the system or concept, not the feature:
+
+| Good | Bad |
+|------|-----|
+| `stripe-webhook-behavior.md` | `billing-feature-notes.md` |
+| `auth-rbac-model.md` | `auth-stuff.md` |
+| `legacy-api-quirks.md` | `misc-notes.md` |
+| `email-delivery-constraints.md` | `sendgrid.md` (too generic) |
+
+---
+
+## Example
+
+See `example-external-api-context.md` in this directory for a working template.
+
+For the layer separation guide (when to use `docs/` vs `rules/` vs `design-doc`), see `LAYERS.md`.

package/template/.aioson/docs/autonomy-protocol.md

@@ -0,0 +1,80 @@
+---
+description: "Autonomy Contract: 3-tier permission model that drives native harness permissions and the `aioson notify` UX. Load when implementing or debugging permissions, tier changes, or notify levels."
+---
+
+# Autonomy Contract — 3-tier permission model
+
+> Living Memory uses **tiers** to declare *how* an action is allowed, not just whether. Each tool/harness derives its native allow-list from the tier(s) it can opt into.
+
+Canonical config: `.aioson/config/autonomy-protocol.json` (schema v1.1+).
+Generator: `src/permissions-generator.js`.
+Visual notifier: `aioson notify --level=info|warn|block`.
+
+## The three tiers
+
+| Tier | Intent | UX | Examples |
+|---|---|---|---|
+| `tier1_silent`   | Read-only and telemetry. Auto-execute, no notification.                | none           | `git status`, `aioson preflight`, `aioson context:health`, `agent:done` |
+| `tier2_notified` | Mutates AIOSON memory (`bootstrap/`, `features/`, `runtime/`). Auto-execute with **inline notify** (ℹ).         | `ℹ [topic] msg` | `memory:reflect-prepare`, `memory:reflect-commit`, `workflow:next`, `dossier:*` |
+| `tier3_blocking` | Irreversible or external (publish, push, npm registry). **Never** auto-executed; the CLI returns exit 2 and waits for a human. | `⛔ [topic] msg` | `git push *`, `npm publish *`, `cloud:publish:*`, `genome:publish` |
+
+A tool opts into tiers via `derived_from_tiers`:
+
+```json
+"claude": {
+  "mode": "trusted",
+  "derived_from_tiers": ["tier1_silent", "tier2_notified"],
+  "requires_tty": false
+}
+```
+
+**Hard invariant:** `tier3_blocking` is *never* materialized into a tool's native allow-list, even when listed in `derived_from_tiers`. Tier3 always requires explicit human action.
+
+## How the four harnesses receive it
+
+`aioson update` (or `aioson setup`) calls `permissions-generator` after copying the template. It reads the protocol and writes:
+
+| Harness | File | Format | Merge behaviour |
+|---|---|---|---|
+| Claude Code | `.claude/settings.json` | JSON (`permissions.allow[]`) | Merges with existing user entries (preserves customizations) |
+| Codex CLI | `.codex/permissions.json` | JSON | Overwrites (with backup) |
+| Gemini CLI | `.gemini/permissions.toml` | TOML | Overwrites (with backup) |
+| OpenCode | `.opencode/permissions.yaml` | YAML | Overwrites (with backup) |
+
+Previous versions are backed up under `.aioson/backups/{timestamp}/permissions/`.
+
+## How agents use `notify`
+
+Three levels, three prefixes, two exit codes:
+
+```bash
+aioson notify . --level=info  --topic=memory   --message="Updating bootstrap after src/routes/* change"
+aioson notify . --level=warn  --topic=bootstrap --message="Bootstrap stale 35 days — recommend /discover"
+aioson notify . --level=block --topic=git      --message="Push manual: git push origin main"
+```
+
+Internally `notify` calls `runtime:emit` (records in SQLite as event_type `notify_<level>`) and prints the prefixed line. `--level=block` sets `process.exitCode = 2` — callers can detect a halt without parsing output.
+
+## Where each piece lives
+
+- Engine that decides if reflection should fire: `src/memory-reflect-engine.js`
+- Notify renderer (pure): `src/notify-renderer.js`
+- Notify command: `src/commands/notify.js`
+- Generator: `src/permissions-generator.js`
+- Hook into install/update: `src/installer.js#installTemplate` (best-effort)
+- Hook into completion: `src/commands/workflow-next.js` (after `--complete=<agent>`)
+- Hook into direct mode: `src/commands/runtime.js#runAgentDone`
+
+## Backward compatibility
+
+- Projects with `autonomy-protocol.json` v1.0 continue to work — generator falls back to legacy `shell_whitelist` / `aioson_whitelist`.
+- Projects without `.aioson/context/bootstrap/` get a warning at agent Step 0 but are never blocked.
+- Tools without `derived_from_tiers` (legacy) use their per-tool whitelist directly.
+
+## Adding a new command to a tier
+
+1. Edit `template/.aioson/config/autonomy-protocol.json` and add the command under the appropriate `tiers.{tier}.aioson_commands`.
+2. Run `aioson update .` in any consuming project — generator regenerates the four native files.
+3. Update tests in `tests/permissions-generator.test.js` if the command should appear in / be excluded from the generated output.
+
+Never add to `tier3_blocking` for "convenience" — that tier is the safety boundary. If a command needs to be auto-approved, it belongs in tier1 or tier2.