@jaimevalasek/aioson 1.28.1 → 1.30.0

package/template/.aioson/rules/README.md

@@ -16,8 +16,16 @@ description: One-line description of what this rule enforces
 agents: [dev, architect]   # omit to apply to ALL agents
 priority: 10               # optional: higher = loaded first (default: 0)
 version: 1.0.0
----
-```
+modes: [planning, executing]              # optional: restrict to a context:select mode
+task_types: [payment, billing]            # routing: matched against the current task
+load_tier: trigger                        # trigger (default) | always | justified
+triggers: [money, pricing, checkout]      # routing: keywords/phrases matched against the task
+aliases: [workspace, project]             # routing: user/domain terms that may mean this rule
+entities: [Workspace, Project]            # routing: domain objects, tables, services, modules
+retrieval_intents: [database, memory]      # routing: why this file should be discovered
+paths: [src/billing/**]                   # routing: matched against the files being touched
+---
+```
 
 ---
 
@@ -30,6 +38,14 @@ version: 1.0.0
 | `agents` | no | List of agent names. If absent → all agents load it |
 | `priority` | no | Loading order. Higher = loaded first. Default: 0 |
 | `version` | no | Semantic version for tracking changes |
+| `modes` | no | `planning`, `executing`, or both. If declared, the rule is only eligible in those modes |
+| `task_types` | no | Task categories matched against the `context:select` task description |
+| `load_tier` | no | `trigger` (default, loads on match), `always` (loads on every select), `justified` (higher match bar) |
+| `triggers` | no | Keywords or short verb phrases matched against the task (e.g. `creating files` matches "create a new file") |
+| `aliases` | no | Alternate user/domain terms that should recall this rule, e.g. `workspace` when the code entity is `project` |
+| `entities` | no | Domain objects, tables, services, modules, or concepts governed by the rule |
+| `retrieval_intents` | no | Discovery intent labels such as `planning`, `implementation`, `database`, `memory`, `feature`, `security`, or `testing` |
+| `paths` | no | Glob patterns matched against `--paths` (files about to be touched) |
 
 ---
 
@@ -41,6 +57,36 @@ version: 1.0.0
 - Rules are loaded silently — agents do not announce which rules were loaded
 - An agent named `dev` matches a rule with `agents: [dev]`
 
+### On-demand routing via context:select
+
+Agents load rules on demand through `aioson context:select`. A rule is selected when its
+metadata and semantic relevance score above the load threshold for the current task:
+`task_types`/`triggers` matches weigh most, `aliases`/`entities`/`retrieval_intents`
+help connect user language to project language, `paths` matches add when the touched
+files overlap, `description` adds a small boost, and semantic search over the rule body
+can recover relevant rules when the task wording does not exactly match the metadata.
+
+`aioson context:search` is the broad discovery layer. It indexes `.aioson/rules`,
+`.aioson/docs`, skills, context/bootstrap files, feature dossiers, plans, PRDs, and
+research summaries, then returns `must_read`, `should_read`, and `maybe` buckets. Its
+`--agent`, `--mode`, `--intent`, and `--source` flags are ranking boosts, not strict
+filters. Use `context:search` to discover candidates; use `context:select` as the final
+strict context package before loading files into an agent prompt.
+
+Semantic search is a recall aid, not a permission bypass. `agents`, `modes`,
+activation-only boundaries, and path/feature constraints still apply before a rule can
+be selected. A rule with only `agents` + `description` is still weakly routed and will be
+flagged by lint; either give it routing metadata (`task_types`, `triggers`, `paths`) or
+mark it `load_tier: always` when it is genuinely global (keep always-rules small).
+
+Check the health of your rules with:
+
+```bash
+aioson rules:lint .
+```
+
+It flags rules that are selector-invisible or missing required fields.
+
 ---
 
 ## When to Create a Rule

package/template/.aioson/rules/agent-language-policy.md

@@ -4,20 +4,25 @@ description: Agent files default to English for universal reuse. Locale-specific
 priority: 9
 version: 1.1.0
 agents: [squad, genome, orache, design-hybrid-forge, site-forge]
+modes: [planning, executing]
+task_types: [squad-creation, agent-generation, localization]
+load_tier: trigger
+triggers: [creating squads, generating agents, choosing language, locale scope, translating agents]
+paths: [.aioson/squads/**]
 ---
 
 # Agent Language Policy
 
-Agent files are instruction code. Default is English because it maximizes LLM reasoning quality, reduces token cost, and enables universal reuse. User-facing replies still follow the selected project language (`interaction_language`, fallback `conversation_language`). Locale-scoped generated squads may declare `locale_scope` when their own generated agent files must be locale-native.
+Agent files are instruction code. Default is English because it maximizes LLM reasoning quality, reduces token cost, and enables universal reuse. User-facing replies still follow the selected project language (`interaction_language`, fallback `conversation_language`). Locale-scoped generated squads may declare `locale_scope` when their own generated agent files must be locale-native.
 
 ## Language decision tree
 
 ```
-New or existing squad
-  ├── ephemeral: true → any language
-  └── ephemeral: false
-      ├── locale_scope: "universal" (or absent) → agent files in English
-      └── locale_scope: "{locale}" declared → generated squad agent files in that locale language
+New or existing squad
+  ├── ephemeral: true → any language
+  └── ephemeral: false
+      ├── locale_scope: "universal" (or absent) → agent files in English
+      └── locale_scope: "{locale}" declared → generated squad agent files in that locale language
 ```
 
 ## Declaring locale_scope
@@ -26,9 +31,9 @@ In `squad.manifest.json`:
 
 ```json
 {
-  "slug": "pharmacy-support",
-  "locale_scope": "pt-BR",
-  "locale_rationale": "Domain regulated by ANVISA; law, prescriptions, and customer interactions are exclusively Brazilian."
+  "slug": "pharmacy-support",
+  "locale_scope": "pt-BR",
+  "locale_rationale": "Domain regulated by ANVISA; law, prescriptions, and customer interactions are exclusively Brazilian."
 }
 ```
 
@@ -43,8 +48,8 @@ Valid values: `"universal"` (default) or any BCP-47 code: `"pt-BR"`, `"en-US"`,
 | No portability | Squad never reused in another country without full rewrite? |
 | Native domain reasoning | Technical domain richer in native language? |
 
-Justified: ANVISA pharmacy support, eSocial tax/payroll, Brazilian legal support, national support desk.
-Not justified: digital marketing, software development, YouTube creator, psychology/coaching.
+Justified: ANVISA pharmacy support, eSocial tax/payroll, Brazilian legal support, national support desk.
+Not justified: digital marketing, software development, YouTube creator, psychology/coaching.
 
 ## Rules by layer
 
@@ -68,16 +73,16 @@ Not justified: digital marketing, software development, YouTube creator, psychol
 | Agent output | Locale language |
 | Content docs | Locale language |
 
-## Mandatory Question During Squad Creation
-
-Before generating any generated squad file, ask in the selected project language:
-
-```
-Is this squad for one specific country/language, or should it be universal?
-
-1. Universal (English) — reusable in any project, publishable on aiosforge.com
-2. Specific locale — for example Brazil-only in Portuguese
-```
+## Mandatory Question During Squad Creation
+
+Before generating any generated squad file, ask in the selected project language:
+
+```
+Is this squad for one specific country/language, or should it be universal?
+
+1. Universal (English) — reusable in any project, publishable on aiosforge.com
+2. Specific locale — for example Brazil-only in Portuguese
+```
 
 If (2): request locale code. If unclear: infer from domain and confirm.
 

package/template/.aioson/rules/agent-structural-contract.md

@@ -1,158 +1,168 @@
----
-name: agent-structural-contract
-description: Structural contract every AIOSON agent must follow — mandatory sections, observability order, handoff pattern, and CLI command integrity
-priority: 5
-version: 1.0.0
----
-
-# Agent Structural Contract
-
-Every AIOSON agent file (`template/.aioson/agents/*.md`) must comply with this structural contract. Violations are caught by `@qa` during Gate D and by `@sheldon` during enrichment reviews.
-
-## 1. Language boundary (mandatory, line 3)
-
-Every agent MUST start with:
-
-```markdown
-> **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`.
-```
-
-## 2. Mandatory sections
-
-Every agent that interacts with the user MUST have these sections (order may vary):
-
-| Section | Purpose | Required for |
-|---|---|---|
-| `## Mission` | What the agent does in 1-2 lines | All agents |
-| `## Required input` | What files must be read before acting | All agents |
-| `## Hard constraints` | Non-negotiable rules | All agents |
-| Observability block | `agent:done` + `pulse:update` at session end | All agents |
-
-Agents that are part of the SDD workflow additionally MUST have:
-
-| Section | Purpose | Required for |
-|---|---|---|
-| Handoff section | Structured next-agent recommendation | briefing, product, sheldon, analyst, architect, pm, orchestrator |
-| `## Feature dossier` | Dossier read/write integration | product, sheldon, analyst, architect, pm, orchestrator |
-
-## 3. Observability command order (session end)
-
-At session end, commands MUST appear in this exact order. Missing steps are acceptable when marked N/A — wrong order is not.
-
-```
-1. gate:approve     (if this agent owns a gate — analyst=A, architect=B, pm=C, qa=D)
-2. op:capture       (if user confirmed decisions — product, sheldon, pm)
-3. pulse:update     (ALL agents — automated project-pulse update)
-4. agent:done       (ALL agents — ALWAYS LAST)
-```
-
-`runtime:emit` milestones happen DURING the session at strategic moments, NOT in the session-end block. Each agent should emit at least 2 milestones during execution.
-
-### Milestone timing per agent
-
-| Agent | Milestone 1 (emit during work) | Milestone 2 (emit during work) |
-|---|---|---|
-| @briefing | Briefing draft written | Briefing approved |
-| @product | PRD written | Feature registered in features.md |
-| @sheldon | Sizing decided | Enrichment applied |
-| @analyst | Requirements written | Spec skeleton created |
-| @architect | Architecture decided | Gate B check |
-| @pm | Implementation plan written | Gate C approved |
-| @orchestrator | Lanes initialized | Merge complete |
-| @dev | Slice started | Slice landed |
-| @qa | Review started | Verdict decided |
-
-## 4. Handoff contract
-
-Every workflow agent MUST end with a handoff block following this template:
-
-```markdown
-**Handoff message:**
-```
-[Artifact produced]: .aioson/context/[artifact].md
-[Gate status]: Gate [X]: [approved|pending]
-Next agent: @[name] ([condition or rationale])
-Action: /[agent-name]
-```
-> Recommended: `/clear` before activating — fresh context window.
-```
-
-Rules:
-- The handoff message MUST include at least: artifact path, next agent, and rationale.
-- `/clear` recommendation MUST be present.
-- Do NOT continue into the next agent's work — output only the handoff and stop.
-
-## 5. CLI error handling
-
-Best-effort `aioson` CLI commands in agent files MUST end with `2>/dev/null || true` to prevent optional telemetry or context helpers from breaking the session when the CLI is unavailable.
-
-```
-aioson <command> . --flag=value 2>/dev/null || true
-```
-
-Do not silence blocking commands whose result controls safety, routing, or user action. These commands must run normally, and the agent must inspect their result before continuing.
-
-Blocking examples:
-- `aioson git:guard`
-- `aioson commit:prepare`
-- `aioson gate:check`
-- `aioson preflight`
-- `aioson workflow:status`
-- `aioson context:validate`
-
-Best-effort examples:
-- `aioson runtime:emit`
-- `aioson pulse:update`
-- `aioson agent:done`
-- `aioson dossier:*`
-- `aioson memory:search`
-- `aioson context:search`
-- `aioson context:pack`
-
-Commands inside "Quick start" or "Prerequisites" sections are user-run examples and do not need the best-effort suffix.
-
-## 6. CLI flag integrity
-
-Agent files must reference CLI commands with correct flag names. When adding a new command reference:
-
-1. Check `src/commands/<command>.js` for the actual option names.
-2. Use `--flag=value` syntax (not positional arguments) for clarity.
-3. Never guess flags — verify against the source.
-
-Known correct signatures (reference table):
-
-| Command | Correct flags |
-|---|---|
-| `gate:approve` | `--feature=<slug> --gate=<A\|B\|C\|D>` |
-| `gate:check` | `--feature=<slug> --gate=<A\|B\|C\|D>` |
-| `pulse:update` | `--agent=<name> --feature=<slug> --action="<summary>" --next="<recommendation>"` |
-| `op:capture` | `--signal=<type> --quote="<verbatim>" --proposal="<paraphrase>" --source-agent=<name>` |
-| `brain:query` | `--tags=<csv> --min-quality=<n> --format=<compact\|json\|ids>` |
-| `artifact:validate` | `--feature=<slug>` (NOT `--spec=<file>`) |
-| `dossier:audit` | `--check=<template-parity\|coverage>` (NOT `--slug=<slug>`) |
-| `dossier:add-finding` | `--slug=<slug> --agent=<name> --section="<section>" --content="<text>"` |
-| `dossier:add-codemap` | `--slug=<slug> --file=<path> --role=<role> --coupling=<low\|medium\|high> --added-by=<agent>` |
-| `dossier:link-rule` | `--slug=<slug> --rule=<path> --reason="<text>"` |
-| `runtime:emit` | `--agent=<name> --type=<milestone\|gate_check> --summary="<text>"` |
-| `memory:search` | `--query="<text>"` |
-| `context:search` | `--query="<text>"` |
-| `preflight` | `--agent=<name> --feature=<slug>` |
-| `dev:state:write` | `--feature=<slug> --phase=<n> --next="<description>" --context=<tokens>`; supports `simple-plan` |
-
-## 7. Template-workspace parity
-
-Agent files in `template/.aioson/agents/` are the canonical source. Workspace files in `.aioson/agents/` are copies synced via `npm run sync:agents`.
-
-Rules:
-- Edits MUST be made in `template/` first, then synced to workspace.
-- After any agent edit session, verify parity with `diff template/.aioson/agents/<file> .aioson/agents/<file>`.
-- Drift between template and workspace is a bug — the template always wins.
-
-## On violation detected
-
-When an agent file violates this contract:
-
-1. **During @qa Gate D:** flag as a Medium finding with `recommended_owner: dev`.
-2. **During @sheldon enrichment:** flag in `sheldon-enrichment-{slug}.md` improvements list.
-3. **During @deyvin pair session:** fix inline if the touched file is already in scope.
-4. **Never block a feature** for structural violations alone — document and fix as follow-up.
+---
+name: agent-structural-contract
+description: Structural contract every AIOSON agent must follow — mandatory sections, observability order, handoff pattern, and CLI command integrity
+priority: 5
+version: 1.0.0
+modes: [planning, executing]
+task_types: [agent-contract, agent-authoring]
+load_tier: trigger
+guard: true
+triggers: [editing agent files, creating agents, agent prompt, handoff contract, observability block, milestone order]
+paths: [.aioson/agents/**, template/.aioson/agents/**, .aioson/squads/**]
+---
+
+# Agent Structural Contract
+
+Every AIOSON agent file (`template/.aioson/agents/*.md`) must comply with this structural contract. Violations are caught by `@qa` during Gate D and by `@sheldon` during enrichment reviews.
+
+## 1. Language boundary (mandatory, line 3)
+
+Every agent MUST start with:
+
+```markdown
+> **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`.
+```
+
+## 2. Mandatory sections
+
+Every agent that interacts with the user MUST have these sections (order may vary):
+
+| Section | Purpose | Required for |
+|---|---|---|
+| `## Mission` | What the agent does in 1-2 lines | All agents |
+| `## Required input` | What files must be read before acting | All agents |
+| `## Hard constraints` | Non-negotiable rules | All agents |
+| Observability block | `agent:done` + `pulse:update` at session end | All agents |
+
+Agents that are part of the SDD workflow additionally MUST have:
+
+| Section | Purpose | Required for |
+|---|---|---|
+| Handoff section | Structured next-agent recommendation | briefing, product, sheldon, analyst, architect, pm, orchestrator |
+| `## Feature dossier` | Dossier read/write integration | product, sheldon, analyst, architect, pm, orchestrator |
+
+## 3. Observability command order (session end)
+
+At session end, commands MUST appear in this exact order. Missing steps are acceptable when marked N/A — wrong order is not.
+
+```
+1. gate:approve     (if this agent owns a gate — analyst=A, architect=B, pm=C, qa=D)
+2. op:capture       (if user confirmed decisions — product, sheldon, pm)
+3. pulse:update     (ALL agents — automated project-pulse update)
+4. agent:done       (ALL agents — ALWAYS LAST)
+```
+
+`runtime:emit` milestones happen DURING the session at strategic moments, NOT in the session-end block. Each agent should emit at least 2 milestones during execution.
+
+### Milestone timing per agent
+
+| Agent | Milestone 1 (emit during work) | Milestone 2 (emit during work) |
+|---|---|---|
+| @briefing | Briefing draft written | Briefing approved |
+| @product | PRD written | Feature registered in `.aioson/context/features.md` |
+| @sheldon | Sizing decided | Enrichment applied |
+| @analyst | Requirements written | Spec skeleton created |
+| @architect | Architecture decided | Gate B check |
+| @pm | Implementation plan written | Gate C approved |
+| @orchestrator | Lanes initialized | Merge complete |
+| @dev | Slice started | Slice landed |
+| @qa | Review started | Verdict decided |
+
+## 4. Handoff contract
+
+Every workflow agent MUST end with a handoff block following this template:
+
+```markdown
+**Handoff message:**
+```
+[Artifact produced]: .aioson/context/[artifact].md
+[Gate status]: Gate [X]: [approved|pending]
+Next agent: @[name] ([condition or rationale])
+Action: /[agent-name]
+```
+> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+```
+
+Rules:
+- The handoff message MUST include at least: artifact path, next agent, and rationale.
+- `/compact` recommendation MUST be present for same-feature continuation.
+- `/clear` MUST be described only as a hard reset option.
+- Do NOT continue into the next agent's work — output only the handoff and stop.
+
+## 5. CLI error handling
+
+Best-effort `aioson` CLI commands in agent files MUST end with `2>/dev/null || true` to prevent optional telemetry or context helpers from breaking the session when the CLI is unavailable.
+
+```
+aioson <command> . --flag=value 2>/dev/null || true
+```
+
+Do not silence blocking commands whose result controls safety, routing, or user action. These commands must run normally, and the agent must inspect their result before continuing.
+
+Blocking examples:
+- `aioson git:guard`
+- `aioson commit:prepare`
+- `aioson gate:check`
+- `aioson preflight`
+- `aioson workflow:status`
+- `aioson context:validate`
+
+Best-effort examples:
+- `aioson runtime:emit`
+- `aioson pulse:update`
+- `aioson agent:done`
+- `aioson dossier:*`
+- `aioson memory:search`
+- `aioson context:search`
+- `aioson context:brief`
+- `aioson context:pack`
+
+Commands inside "Quick start" or "Prerequisites" sections are user-run examples and do not need the best-effort suffix.
+
+## 6. CLI flag integrity
+
+Agent files must reference CLI commands with correct flag names. When adding a new command reference:
+
+1. Check `src/commands/<command>.js` for the actual option names.
+2. Use `--flag=value` syntax (not positional arguments) for clarity.
+3. Never guess flags — verify against the source.
+
+Known correct signatures (reference table):
+
+| Command | Correct flags |
+|---|---|
+| `gate:approve` | `--feature=<slug> --gate=<A\|B\|C\|D>` |
+| `gate:check` | `--feature=<slug> --gate=<A\|B\|C\|D>` |
+| `pulse:update` | `--agent=<name> --feature=<slug> --action="<summary>" --next="<recommendation>"` |
+| `op:capture` | `--signal=<type> --quote="<verbatim>" --proposal="<paraphrase>" --source-agent=<name>` |
+| `brain:query` | `--tags=<csv> --min-quality=<n> --format=<compact\|json\|ids>` |
+| `artifact:validate` | `--feature=<slug>` (NOT `--spec=<file>`) |
+| `dossier:audit` | `--check=<template-parity\|coverage>` (NOT `--slug=<slug>`) |
+| `dossier:add-finding` | `--slug=<slug> --agent=<name> --section="<section>" --content="<text>"` |
+| `dossier:add-codemap` | `--slug=<slug> --file=<path> --role=<role> --coupling=<low\|medium\|high> --added-by=<agent>` |
+| `dossier:link-rule` | `--slug=<slug> --rule=<path> --reason="<text>"` |
+| `runtime:emit` | `--agent=<name> --type=<milestone\|gate_check> --summary="<text>"` |
+| `memory:search` | `--query="<text>"` |
+| `context:search` | `[path] --query="<text>" --agent=<name> --mode=<mode> --task="<text>" --paths=<csv> --intent=<csv>` |
+| `context:brief` | `[path] --agent=<name> --mode=<planning\|executing> --task="<text>" --paths=<csv> [--no-recall]` |
+| `context:index` | `[path] --force` |
+| `preflight` | `--agent=<name> --feature=<slug>` |
+| `dev:state:write` | `--feature=<slug> --phase=<n> --next="<description>" --context=<tokens>`; supports `simple-plan` |
+
+## 7. Template-workspace parity
+
+Agent files in `template/.aioson/agents/` are the canonical source. Workspace files in `.aioson/agents/` are copies synced via `npm run sync:agents`.
+
+Rules:
+- Edits MUST be made in `template/` first, then synced to workspace.
+- After any agent edit session, verify parity with `diff template/.aioson/agents/<file> .aioson/agents/<file>`.
+- Drift between template and workspace is a bug — the template always wins.
+
+## On violation detected
+
+When an agent file violates this contract:
+
+1. **During @qa Gate D:** flag as a Medium finding with `recommended_owner: dev`.
+2. **During @sheldon enrichment:** flag in `sheldon-enrichment-{slug}.md` improvements list.
+3. **During @deyvin pair session:** fix inline if the touched file is already in scope.
+4. **Never block a feature** for structural violations alone — document and fix as follow-up.

package/template/.aioson/rules/aioson-context-boundary.md

@@ -4,6 +4,12 @@ description: .aioson/context/ is Markdown-first with explicit machine-readable e
 priority: 10
 version: 1.0.0
 agents: [product, analyst, architect, ux-ui, pm, dev, qa, sheldon]
+modes: [executing]
+task_types: [artifact-write, file-creation]
+load_tier: trigger
+guard: true
+triggers: [writing artifacts, creating files, saving context, context artifact, machine-readable file]
+paths: [.aioson/context/**]
 ---
 
 # Context Boundary: .aioson/context/
@@ -44,7 +50,7 @@ project.context.md            ← setup
 discovery.md                  ← analyst
 requirements-{slug}.md        ← analyst
 architecture.md               ← architect
-ui-spec.md / ui-spec-{slug}.md ← ux-ui (`ui-spec.md` is the current canonical runtime artifact)
+ui-spec.md / ui-spec-{slug}.md ← ux-ui (`ui-spec.md` is the current canonical runtime artifact)
 prd.md / prd-{slug}.md        ← product
 spec-{slug}.md                ← dev
 implementation-plan-{slug}.md ← pm

package/template/.aioson/rules/canonical-path-contract.md

@@ -1,9 +1,15 @@
 ---
 name: canonical-path-contract
-description: Mandatory distinction between root plans/, .aioson/plans/{slug}/, docs/pt/, and implementation-plan. Every artifact-writing agent must consult this contract before creating files.
+description: Mandatory distinction between root plans/, .aioson/plans/{slug}/, docs/pt/, and implementation-plan. Every artifact-writing agent must consult this contract before creating files.
 priority: 10
 version: 1.0.0
 agents: []
+modes: [planning, executing]
+task_types: [artifact-write, file-creation, plan-write]
+load_tier: trigger
+guard: true
+triggers: [writing plans, creating files, saving artifacts, choosing paths, artifact destination]
+paths: [plans/**, .aioson/plans/**, .aioson/context/**, docs/**]
 ---
 
 # Canonical Path Contract
@@ -27,9 +33,9 @@ Every agent that creates or writes files MUST resolve the target path using this
 | PRD | `.aioson/context/prd-{slug}.md` | `@product` |
 | Requirements | `.aioson/context/requirements-{slug}.md` | `@analyst` |
 | Architecture | `.aioson/context/architecture.md` | `@architect` |
-| Spec (living memory) | `.aioson/context/spec-{slug}.md` | `@dev` |
-| Simple implementation plan | `.aioson/context/simple-plans/{slug}.md` | `@dev` / `@deyvin` |
-| QA report | `.aioson/context/qa-report-{slug}.md` | `@qa` |
+| Spec (living memory) | `.aioson/context/spec-{slug}.md` | `@dev` |
+| Simple implementation plan | `.aioson/context/simple-plans/{slug}.md` | `@dev` / `@deyvin` |
+| QA report | `.aioson/context/qa-report-{slug}.md` | `@qa` |
 
 ## Violation behaviors
 
@@ -44,9 +50,9 @@ Every agent that creates or writes files MUST resolve the target path using this
 |---|---|
 | "plans" or "plans folder" | Ask: root `plans/` (pre-production) or `.aioson/plans/{slug}/` (feature plan)? |
 | "docs" or "documentation" | Ask: `docs/` root (project docs) or `docs/pt/` (PT system docs) or `.aioson/docs/` (agent on-demand docs)? |
-| "context" | `.aioson/context/` (framework artifacts) |
-| "rules" | `.aioson/rules/` (agent rules) |
-
-## Simple plan distinction
-
-`simple-plans/{slug}.md` is not a PRD, not a Sheldon phased plan, and not a MEDIUM implementation plan. It is a lightweight implementation artifact for bounded technical work that `@dev` or `@deyvin` can execute directly under `.aioson/rules/simple-plan-lane.md`.
+| "context" | `.aioson/context/` (framework artifacts) |
+| "rules" | `.aioson/rules/` (agent rules) |
+
+## Simple plan distinction
+
+`simple-plans/{slug}.md` is not a PRD, not a Sheldon phased plan, and not a MEDIUM implementation plan. It is a lightweight implementation artifact for bounded technical work that `@dev` or `@deyvin` can execute directly under `.aioson/rules/simple-plan-lane.md`.

package/template/.aioson/rules/data-format-convention.md

@@ -3,6 +3,12 @@ name: data-format-convention
 description: Which file format to use when producing or consuming structured data — YAML for agent-readable reference data, Markdown for narrative, JSON for machine-consumed data
 priority: 8
 version: 1.0.0
+modes: [executing]
+task_types: [artifact-write, data-format]
+load_tier: trigger
+guard: true
+triggers: [choosing format, structured data, writing yaml, writing json, producing output, data file]
+paths: [output/**, .aioson/squads/**]
 ---
 
 # Data Format Convention
@@ -27,17 +33,17 @@ Use for: ICP profiles, persona profiles, audience segments, offer sheets, pricin
 
 **Example (`icp-primary.yaml`):**
 ```yaml
-profile:
-  name: "Agency-Dependent Founder"
-  description: "Business owner dependent on agencies or external developers"
-pain_points:
-  - Loss of control over the product
-  - Unpredictable delays and costs
-desired_outcome: "Autonomy and speed"
-buying_trigger: "Deadline approaching or delayed developer invoice arriving"
-messaging:
-  primary: "Take back control of your product"
-channels: [instagram, linkedin, youtube]
+profile:
+  name: "Agency-Dependent Founder"
+  description: "Business owner dependent on agencies or external developers"
+pain_points:
+  - Loss of control over the product
+  - Unpredictable delays and costs
+desired_outcome: "Autonomy and speed"
+buying_trigger: "Deadline approaching or delayed developer invoice arriving"
+messaging:
+  primary: "Take back control of your product"
+channels: [instagram, linkedin, youtube]
 ```
 
 ### Markdown — narrative for humans and linear agent reading