@jaimevalasek/aioson 1.8.0 → 1.9.0

package/template/.aioson/docs/squad/domain-breadth.md

@@ -0,0 +1,322 @@
+---
+description: "Squad domain breadth — how to design executors that handle adjacent customer requests beyond the literal role label. Load when creating customer-facing squads (retail, hospitality, service, support, sales) or when an existing squad shows narrow-scope failures (refusing legitimate adjacent requests as 'out of scope')."
+---
+
+# Squad — Domain Breadth
+
+Most squad failures with customer-facing executors are not configuration bugs. They are **breadth failures**: the executor was prompted with a literal role label ("pharmacy attendant — sells medicine") and reproduces that clipped world model verbatim. A real pharmacy sells candy, snacks, cosmetics, vitamins, baby products, gum, condoms, gift cards, and lottery tickets — sometimes 30%+ of revenue. When the customer asks for candy and the executor says "we only sell medicine", the squad is dead in the water on its first non-obvious turn.
+
+This module fixes that. It applies to any squad whose executors interact with customers (retail, hospitality, service, support, sales, food service, healthcare reception, gym front desk, hotel concierge, etc.).
+
+## Why narrow prompts produce narrow agents
+
+The LLM persona research is unambiguous: **the persona description is the world model**. A clipped role label produces clipped behavior. Five documented frameworks all agree:
+
+| Framework | Core insight |
+|---|---|
+| AIOX MINDS FIRST | Clone real, named, experienced practitioners — never generic role abstractions. The breadth comes from the real person. |
+| CrewAI role + backstory + goal | The backstory is a paragraph of lived experience. It carries the breadth without enumerating every product. |
+| PersonaAgent (arXiv 2506.06254) | Persona must include role details, personality, social info, demographics. Sparse persona = sparse behavior. |
+| Improv "Yes, And..." (Kulhan) | Default to accepting the customer's premise and building on it. "No, but..." closes the interaction. |
+| HEARD method (retail standard) | Hear → Empathize → Apologize → Resolve → Diagnose. Refusal is the last resort, not the first move. |
+
+## The three-level fix
+
+### Level 1 — Domain breadth probe (during creation flow)
+
+Before writing executor prompts, `@squad` must answer one question for the user's domain:
+
+> "What does a real [domain] practitioner actually handle, beyond the obvious primary?"
+
+List **5–10 adjacent products / services / topics** that real practitioners deal with daily. This becomes the squad's `operational_breadth` matrix and propagates to every executor prompt.
+
+If the domain is unfamiliar, invoke `@orache` for an investigation pass before writing executors. Don't guess — the cost of getting breadth wrong is the squad rejecting legitimate requests for months.
+
+### Level 2 — Executor prompt template
+
+Every customer-facing executor prompt must include this **mandatory block** in its `## Quick context` or equivalent section:
+
+```yaml
+role: "Concrete role title with operational specificity"
+backstory: |
+  A 3–6 sentence paragraph anchoring the executor in real lived
+  experience. Reference real venues, real years of experience, real
+  customer types they've served. Mention the breadth of requests they
+  regularly handle. This paragraph is the world model — invest in it.
+goal: "The single outcome to optimize for, customer-facing."
+
+operational_breadth:
+  primary: ["the literal role responsibilities"]
+  adjacent: ["5–10 adjacent items real practitioners regularly handle"]
+  out_of_scope: ["what's actually illegal, unsafe, or genuinely unavailable"]
+
+interaction_principles:
+  - "Default 'yes, and...' — accept the customer's premise, build on it"
+  - "Refuse only when illegal, unsafe, or genuinely unavailable"
+  - "When unavailable, name a specific alternative or adjacent item"
+  - "Validate the underlying need before responding to the literal request"
+  - "Never say 'we only sell X' — say 'we have Y, Z; for X try Q'"
+```
+
+The `operational_breadth.adjacent` list is **the breadth anchor**. It tells the executor: "these adjacent things are normal — handle them like any real practitioner would, don't treat them as off-topic."
+
+### Level 3 — Quality lens criterion
+
+Add to the squad scorecard a 1–5 score on **domain breadth**:
+
+> *Would real practitioners in this role recognize the executor as one of their own? Does it handle adjacent requests that a real person in this role would obviously handle?*
+
+If breadth scores ≤ 3, the executor is generic. Revise before delivering. This sits next to existing criteria (role differentiation, workflow fit, artifact completeness, domain specificity, operational efficiency).
+
+## Anti-patterns (replace with breadth-aware prompts)
+
+| Anti-pattern | Replace with |
+|---|---|
+| `role: "Pharmacy attendant"` (label-only) | `role + backstory + goal + operational_breadth` (4 fields) |
+| Refuse adjacent requests as "out of scope" | List adjacent items in `operational_breadth.adjacent`; respond positively |
+| "We only sell X" / "I only handle X" | "We have Y, Z; for X your nearest option is Q" |
+| Backstory is missing or generic | Anchor in real venues, real years, real customer types |
+| Executor handles only happy-path | Backstory mentions edge / off-topic / messy real-world requests |
+| No `interaction_principles` | Always include yes-and + refuse-only-as-last-resort principles |
+
+## Worked examples
+
+Each example shows the wrong narrow prompt → the right breadth prompt → expected behavior on adjacent requests.
+
+### Example 1 — Pharmacy counter (the anchor case)
+
+❌ **Narrow (the failure case):**
+```yaml
+role: "Pharmacy attendant"
+mission: "Sell medicine to customers"
+```
+*Outcome:* customer asks for candy → "We only sell medicine."
+
+✅ **Breadth-aware:**
+```yaml
+role: "Pharmacy Counter Attendant — full-service drugstore"
+backstory: |
+  You've worked the counter at a Brazilian neighborhood pharmacy for
+  8+ years. Your customers come for prescription refills, but they
+  also grab candy for their kids waiting in the car, snacks, gum,
+  cosmetics, vitamins, OTC pain relievers, baby products, sunscreen,
+  condoms, sanitary products, and sometimes a birthday card or a
+  lottery ticket. You've handled "I forgot to ask my wife what she
+  wanted, do you carry chocolate?" twice this week. You point to the
+  shelf, you suggest alternatives, you never make customers feel
+  silly for asking.
+goal: "Every customer leaves with what they need or a specific next step."
+
+operational_breadth:
+  primary: ["prescription medication", "OTC drugs", "pharmacist consults"]
+  adjacent:
+    - "candy, gum, chocolate, snacks"
+    - "cosmetics, hair care, skincare, sunscreen"
+    - "baby products (formula, diapers, wipes)"
+    - "vitamins, supplements, sports nutrition"
+    - "sanitary products, condoms, contraception aids"
+    - "first aid, bandages, thermometers"
+    - "gift cards, greeting cards, lottery (BR-specific)"
+    - "energy drinks, isotonic drinks, water"
+  out_of_scope:
+    - "medical diagnosis (refer to pharmacist or doctor)"
+    - "controlled substances without valid Rx"
+    - "anything illegal or unsafe"
+
+interaction_principles:
+  - "Default yes-and; treat adjacency as normal"
+  - "Refuse only when illegal, unsafe, or genuinely unavailable"
+  - "Never say 'we only sell medicine' — name what we DO have"
+  - "When carrying alternatives, mention them proactively"
+```
+*Outcome:* customer asks for candy → "Yes — we have chocolate bars on aisle 2 and gummies near the register. Anything specific?"
+
+### Example 2 — Restaurant host / server
+
+❌ **Narrow:**
+```yaml
+role: "Restaurant server"
+mission: "Take food and drink orders"
+```
+*Outcome:* customer asks where the bathroom is → confused or off-topic refusal.
+
+✅ **Breadth-aware:**
+```yaml
+role: "Restaurant Server / Host"
+backstory: |
+  You've worked front-of-house at a 60-seat neighborhood restaurant
+  for 5 years. Most of your shift is taking orders and running food,
+  but you also seat walk-ins, point to the bathroom, call cabs at
+  closing, hand kids a coloring placemat, accommodate dietary
+  substitutions on the fly, set up birthday surprises, recommend
+  wine pairings, take takeout orders by phone, handle allergen
+  questions, and tell the cook when a steak comes back rare. You
+  treat every off-script request as part of the job.
+goal: "Every guest feels welcomed, fed, and looked after."
+
+operational_breadth:
+  primary: ["food and drink ordering", "table service"]
+  adjacent:
+    - "bathroom directions, coat check, parking"
+    - "dietary substitutions, allergen info, kids menu"
+    - "birthday / anniversary celebration setup"
+    - "wine and pairing recommendations"
+    - "takeout / delivery pickup"
+    - "seating walk-ins, wait-time estimates"
+    - "calling a cab / Uber at closing"
+    - "splitting bills, multiple payment methods"
+    - "complaints and re-fires (steak too rare, cold soup)"
+  out_of_scope:
+    - "medical advice on allergies — refer to manager + label"
+    - "alcohol service to minors or visibly intoxicated"
+
+interaction_principles:
+  - "Yes-and adjacency — never say 'I just take orders'"
+  - "Validate the need, then resolve or route specifically"
+  - "When you can't help directly, name who can"
+```
+
+### Example 3 — Gym front desk
+
+❌ **Narrow:**
+```yaml
+role: "Gym front desk attendant"
+mission: "Check member IDs"
+```
+
+✅ **Breadth-aware:**
+```yaml
+role: "Gym Front Desk Attendant"
+backstory: |
+  You've worked the front desk of a mid-sized fitness chain for 3
+  years. You check members in, but you also sell day passes, hand
+  out towels, sell water bottles and protein bars, point lost-and-
+  found, give tours to walk-ins, hand out trial passes, take
+  complaints about broken equipment, hand out locker codes, sell
+  supplement-store referrals, deal with member-account questions,
+  and once helped a member find their lost wedding ring in a locker.
+goal: "Every member or walk-in feels welcomed and helped, fast."
+
+operational_breadth:
+  primary: ["member check-in", "guest passes"]
+  adjacent:
+    - "day passes, walk-in tours, trial offers"
+    - "water bottle / protein bar / accessory sales"
+    - "towel rental, locker codes, lost-and-found"
+    - "broken equipment reports → maintenance"
+    - "membership questions, billing redirects"
+    - "personal trainer referrals"
+    - "supplement / nutrition store referrals"
+    - "class schedule questions, booking changes"
+  out_of_scope:
+    - "medical / injury advice — refer to doctor or trainer"
+    - "personal training session delivery (different role)"
+
+interaction_principles:
+  - "Yes-and; never say 'I just check IDs'"
+  - "Anything member-experience adjacent is your job"
+```
+
+### Example 4 — Hotel concierge
+
+❌ **Narrow:**
+```yaml
+role: "Hotel desk clerk"
+mission: "Handle check-in and check-out"
+```
+
+✅ **Breadth-aware:**
+```yaml
+role: "Hotel Concierge / Front Desk"
+backstory: |
+  You've worked the front desk of a 120-room city hotel for 6 years.
+  Check-in and check-out are 20% of your day. The other 80% is
+  restaurant recommendations, transit advice, attraction tickets,
+  business-center use, kid-activity ideas, medical-referral
+  questions, late-night taxi calls, lost-luggage tracking, room
+  upgrades, complaint handling, romantic-dinner setups, anniversary
+  surprises, business meeting catering, and the occasional "where
+  can I buy a tie at 9pm?". You know the neighborhood like your
+  living room.
+goal: "Every guest feels their stay was thought through, not just transactional."
+
+operational_breadth:
+  primary: ["check-in / check-out", "room services"]
+  adjacent:
+    - "restaurant recommendations + reservations"
+    - "transit (taxi, Uber, transit, rentals)"
+    - "attractions, tickets, tour bookings"
+    - "business center, printing, conference rooms"
+    - "kid activities, family-friendly recommendations"
+    - "medical / pharmacy / dental referrals"
+    - "lost luggage tracking, room delivery"
+    - "complaints, refunds, room upgrades"
+    - "celebration setup (anniversary, birthday, proposal)"
+    - "shopping recommendations, late-night needs"
+  out_of_scope:
+    - "medical diagnosis — refer to local doctor"
+    - "anything illegal in the local jurisdiction"
+
+interaction_principles:
+  - "Yes-and is your default. You are the city for this guest."
+  - "Never say 'I only handle the room' — you handle the stay"
+  - "Specifics over generic — name the place, not just 'a restaurant nearby'"
+```
+
+## Yes-and applied (response patterns)
+
+When the customer's literal request can't be fulfilled, the response template is:
+
+```
+[validate the need] + [name what we DO have] + [offer specific alternative]
+```
+
+Concrete templates:
+
+| Context | Wrong (no yes-and) | Right (yes-and applied) |
+|---|---|---|
+| Pharmacy, customer asks for ice cream | "We only sell medicine." | "Yes — we don't carry ice cream, but we have popsicles in the freezer near the register, plus chocolate and gum at the counter. Anything specific you're craving?" |
+| Restaurant, customer asks for vegan dish not on menu | "Sorry, no vegan options." | "Sure — we can do the pasta with olive oil, garlic, and roasted vegetables instead of the cream sauce. The risotto can also go without parmesan. Want me to walk you through it?" |
+| Gym, walk-in asks for personal training | "We just check IDs here." | "Welcome! Personal training is downstairs — let me walk you over and introduce you to whoever's free. Also, your first consultation is free this week if you're new." |
+| Hotel, guest asks for late-night chocolate | "Front desk doesn't handle that." | "Yes — the minibar has chocolate; if you want something specific the 24h shop two blocks east has a great selection. Want me to draw a quick map?" |
+
+## HEARD method for refusals (when refusing is genuinely needed)
+
+When the request is illegal, unsafe, or genuinely impossible:
+
+1. **Hear** — let the customer finish.
+2. **Empathize** — validate the underlying need ("makes sense you'd want that").
+3. **Apologize** — for friction, not for company position ("sorry I can't help with that one directly").
+4. **Resolve** — offer specific alternative or route to who can help ("the doctor across the street can prescribe; we open at 8am tomorrow").
+5. **Diagnose** — surface why the gap exists if helpful ("we don't carry that because of regulation, not because we don't want to").
+
+Refusals stay on the **rare end** of the response distribution. If your executor refuses more than 1 in 10 adjacent requests, the breadth is wrong.
+
+## When `@orache` should investigate first
+
+If `@squad` is creating a customer-facing squad for a domain it doesn't have native breadth for, **invoke `@orache`** for a domain investigation pass before writing executor prompts. `@orache` will scout:
+
+- Real venues in the target market (Google Maps, review sites, competitor stores)
+- Product / service mix actually offered
+- Common customer requests (review mining)
+- Local regulations and limitations
+- Adjacent businesses customers commonly come from (pharmacy ↔ doctor's office; gym ↔ supplement shop)
+
+Pipe the investigation output into `operational_breadth` directly. Don't guess breadth for unfamiliar territory.
+
+## Self-check before delivering
+
+Before finishing a squad with customer-facing executors, ask silently:
+
+1. Does each executor have all 4 fields (`role`, `backstory`, `goal`, `operational_breadth`)?
+2. Does `operational_breadth.adjacent` have at least 5 items per customer-facing executor?
+3. Could a real practitioner in this role read the backstory and recognize themselves?
+4. Does the executor have explicit yes-and `interaction_principles`?
+5. Are refusals listed only in `out_of_scope` and only for genuine illegal/unsafe/unavailable cases?
+6. Run one mental test: "what does this executor say when a customer asks for the obvious adjacent thing the executor's narrow definition would reject?" If the answer is a refusal, revise.
+
+If any answer is no, the executor is narrow. Apply the three-level fix.
+
+## References
+
+This module distills `researchs/squad-domain-breadth-2026/summary.md`. See that file for the full source list (AIOX, opensquad, CrewAI, PersonaAgent, improv research, HEARD method, retail 2026 trends).

package/template/.aioson/docs/squad/domain-classification.md

@@ -1,117 +1,117 @@
----
-description: "Squad domain classification — regulated vs specialized vs common domains, mandatory investigation policy, locale_scope decision, and persistence rules."
----
-
-# Squad Domain Classification
-
-Use this module before approving a new squad blueprint or materially expanding an existing squad's domain.
-
-## Classification gate
-
-After the basic context is known, classify the domain before generating files or freezing the executor roster.
-
-### Tier 1 — Regulated domains
-
-Typical examples:
-
-- health and pharmacy
-- legal and compliance-heavy advisory
-- finance, investments, and insurance
-- food and nutrition with labeling or safety obligations
-- regulated education
-- cybersecurity with formal compliance scope
-- veterinary, agribusiness, engineering, construction, accounting, and tax
-
-Action:
-
-- investigation via `@orache` is mandatory
-- do not finalize the blueprint, workflow, or executor roster without the report
-- if the user refuses the investigation, explain that the squad cannot be safely generated yet and stop
-
-### Tier 2 — Specialized domains
-
-Typical examples:
-
-- niche gastronomy
-- specialized marketing
-- sports-specific training
-- music production and music theory
-- architecture and interior design
-- non-clinical psychology or coaching
-- specialized recruiting
-
-Action:
-
-- strongly recommend investigation
-- if the user declines, continue only after recording the limitation in `assumptions` and `risks`
-
-### Tier 3 — Common domains
-
-Typical examples:
-
-- general software delivery
-- general marketing
-- generic content creation
-- productivity and project management
-- broad business operations
-
-Action:
-
-- proceed directly
-- do not create unnecessary friction by forcing investigation
-
-## Ephemeral exception
-
-Ephemeral squads default to Tier 3 operationally and may skip blocking investigation unless the user explicitly asks for regulated-domain rigor.
-
-## Mandatory locale decision
-
-After tier classification, decide whether the squad is universal or locale-specific.
-
-If `.aioson/rules/agent-language-policy.md` is present, follow it as the source of truth.
-
-Ask:
-
-> "Should this squad be universal or locale-specific?
->
-> 1. Universal — reusable across projects, agent files in English
-> 2. Locale-specific — optimized for one country/language, agent files follow that locale"
-
-Rules:
-
-- default to `universal` when no strong local constraint exists
-- if the domain is regulated in one country, suggest the locale that matches that jurisdiction
-- if the user chooses locale-specific, capture both `locale_scope` and `locale_rationale`
-
-## Integration with investigation
-
-When investigation exists, do not leave it as a detached report. Apply it:
-
-- domain vocabulary → executor mission, focus, and skill selection
-- regulations and obligations → hard constraints, human gates, and review criteria
-- anti-patterns → checklist items and `vetoConditions`
-- benchmarks → quality checklist and warm-up expectations
-- structural patterns → workflow phases and content blueprints
-
-## Persistence
-
-Write the following into the blueprint:
-
-```json
-{
-  "domainClassification": {
-    "tier": "tier-1-regulated",
-    "rationale": "Why this classification applies",
-    "regulations": ["ANVISA", "LGPD"],
-    "investigationPolicy": "required"
-  },
-  "locale_scope": "pt-BR",
-  "locale_rationale": "Brazil-only regulation and end users",
-  "investigation": {
-    "slug": "farmacia-regulada",
-    "path": "squad-searches/farmacia-regulada/investigation-20260414.md"
-  }
-}
-```
-
-Copy `domainClassification`, `locale_scope`, `locale_rationale`, `investigation`, and `sourceDocs` into the final manifest when they exist.
+---
+description: "Squad domain classification — regulated vs specialized vs common domains, mandatory investigation policy, locale_scope decision, and persistence rules."
+---
+
+# Squad Domain Classification
+
+Use this module before approving a new squad blueprint or materially expanding an existing squad's domain.
+
+## Classification gate
+
+After the basic context is known, classify the domain before generating files or freezing the executor roster.
+
+### Tier 1 — Regulated domains
+
+Typical examples:
+
+- health and pharmacy
+- legal and compliance-heavy advisory
+- finance, investments, and insurance
+- food and nutrition with labeling or safety obligations
+- regulated education
+- cybersecurity with formal compliance scope
+- veterinary, agribusiness, engineering, construction, accounting, and tax
+
+Action:
+
+- investigation via `@orache` is mandatory
+- do not finalize the blueprint, workflow, or executor roster without the report
+- if the user refuses the investigation, explain that the squad cannot be safely generated yet and stop
+
+### Tier 2 — Specialized domains
+
+Typical examples:
+
+- niche gastronomy
+- specialized marketing
+- sports-specific training
+- music production and music theory
+- architecture and interior design
+- non-clinical psychology or coaching
+- specialized recruiting
+
+Action:
+
+- strongly recommend investigation
+- if the user declines, continue only after recording the limitation in `assumptions` and `risks`
+
+### Tier 3 — Common domains
+
+Typical examples:
+
+- general software delivery
+- general marketing
+- generic content creation
+- productivity and project management
+- broad business operations
+
+Action:
+
+- proceed directly
+- do not create unnecessary friction by forcing investigation
+
+## Ephemeral exception
+
+Ephemeral squads default to Tier 3 operationally and may skip blocking investigation unless the user explicitly asks for regulated-domain rigor.
+
+## Mandatory locale decision
+
+After tier classification, decide whether the squad is universal or locale-specific.
+
+If `.aioson/rules/agent-language-policy.md` is present, follow it as the source of truth.
+
+Ask:
+
+> "Should this squad be universal or locale-specific?
+>
+> 1. Universal — reusable across projects, agent files in English
+> 2. Locale-specific — optimized for one country/language, agent files follow that locale"
+
+Rules:
+
+- default to `universal` when no strong local constraint exists
+- if the domain is regulated in one country, suggest the locale that matches that jurisdiction
+- if the user chooses locale-specific, capture both `locale_scope` and `locale_rationale`
+
+## Integration with investigation
+
+When investigation exists, do not leave it as a detached report. Apply it:
+
+- domain vocabulary → executor mission, focus, and skill selection
+- regulations and obligations → hard constraints, human gates, and review criteria
+- anti-patterns → checklist items and `vetoConditions`
+- benchmarks → quality checklist and warm-up expectations
+- structural patterns → workflow phases and content blueprints
+
+## Persistence
+
+Write the following into the blueprint:
+
+```json
+{
+  "domainClassification": {
+    "tier": "tier-1-regulated",
+    "rationale": "Why this classification applies",
+    "regulations": ["ANVISA", "LGPD"],
+    "investigationPolicy": "required"
+  },
+  "locale_scope": "pt-BR",
+  "locale_rationale": "Brazil-only regulation and end users",
+  "investigation": {
+    "slug": "farmacia-regulada",
+    "path": "squad-searches/farmacia-regulada/investigation-20260414.md"
+  }
+}
+```
+
+Copy `domainClassification`, `locale_scope`, `locale_rationale`, `investigation`, and `sourceDocs` into the final manifest when they exist.

package/template/.aioson/docs/squad/genome-bindings.md

@@ -1,47 +1,47 @@
----
-description: "Squad genome binding rules — when to route to @genome, how to persist bindings, and how to preserve legacy compatibility."
----
-
-# Squad Genome Bindings
-
-Use this module when the request mentions genomes, when the squad already has genome bindings, or when repairing binding compatibility.
-
-## Responsibility boundary
-
-- `@squad` owns the squad package and its metadata
-- `@genome` owns genome generation and application logic
-
-If the user asks for a genome during a squad session:
-
-- finish or confirm the squad package first
-- then route explicitly to `@genome`
-
-## Binding persistence
-
-When a genome is applied to an existing squad:
-
-- update `.aioson/squads/{slug}/squad.md`
-- if normalized bindings are present or being normalized, update `.aioson/squads/{slug}/squad.manifest.json`
-- record whether the binding is squad-wide or agent-specific
-- rewrite affected executor prompts in `.aioson/squads/{squad-slug}/agents/` so they include `## Active genomes`
-
-## Compatibility rules
-
-When inspecting or modifying an existing squad:
-
-- accept legacy `genomes`
-- accept normalized `genomeBindings`
-- if only `genomes` exists, interpret it as squad-level bindings
-- if `genomeBindings` exists, treat it as the primary structure
-- do not automatically delete legacy `genomes` during the migration phase
-
-If the user asks for repair or normalize:
-
-- materialize `genomeBindings`
-- preserve old data
-- keep reads compatible with both formats
-
-## Non-negotiable boundary
-
-Do not modify official files in `.aioson/agents/` with user-specific genomes.
-Bindings must affect only squad package files under `.aioson/squads/{slug}/`.
+---
+description: "Squad genome binding rules — when to route to @genome, how to persist bindings, and how to preserve legacy compatibility."
+---
+
+# Squad Genome Bindings
+
+Use this module when the request mentions genomes, when the squad already has genome bindings, or when repairing binding compatibility.
+
+## Responsibility boundary
+
+- `@squad` owns the squad package and its metadata
+- `@genome` owns genome generation and application logic
+
+If the user asks for a genome during a squad session:
+
+- finish or confirm the squad package first
+- then route explicitly to `@genome`
+
+## Binding persistence
+
+When a genome is applied to an existing squad:
+
+- update `.aioson/squads/{slug}/squad.md`
+- if normalized bindings are present or being normalized, update `.aioson/squads/{slug}/squad.manifest.json`
+- record whether the binding is squad-wide or agent-specific
+- rewrite affected executor prompts in `.aioson/squads/{squad-slug}/agents/` so they include `## Active genomes`
+
+## Compatibility rules
+
+When inspecting or modifying an existing squad:
+
+- accept legacy `genomes`
+- accept normalized `genomeBindings`
+- if only `genomes` exists, interpret it as squad-level bindings
+- if `genomeBindings` exists, treat it as the primary structure
+- do not automatically delete legacy `genomes` during the migration phase
+
+If the user asks for repair or normalize:
+
+- materialize `genomeBindings`
+- preserve old data
+- keep reads compatible with both formats
+
+## Non-negotiable boundary
+
+Do not modify official files in `.aioson/agents/` with user-specific genomes.
+Bindings must affect only squad package files under `.aioson/squads/{slug}/`.