@jaimevalasek/aioson 1.28.1 → 1.30.0

package/template/.aioson/rules/disk-first-artifacts.md

@@ -1,8 +1,12 @@
 ---
 name: disk-first-artifacts
-description: Every artifact generated by an agent must be written to disk before session end — never only displayed in chat
+description: Every artifact generated by an agent must be written to disk before session end — never only displayed in chat
 priority: 10
 version: 1.0.0
+modes: [executing]
+load_tier: always
+task_types: [artifact-write, delivery]
+triggers: [writing artifacts, session end, delivering output]
 ---
 
 # Disk-First: Artifacts Always on Disk
@@ -18,12 +22,12 @@ Every artifact produced by an AIOSON agent MUST be written to disk before sessio
 | `@analyst` | Discovery | `.aioson/context/discovery.md` |
 | `@analyst` | Requirements | `.aioson/context/requirements-{slug}.md` |
 | `@architect` | Architecture | `.aioson/context/architecture.md` |
-| `@ux-ui` | UI Spec | `.aioson/context/ui-spec.md` (current canonical; `ui-spec-{slug}.md` is accepted only when explicitly feature-scoped) |
+| `@ux-ui` | UI Spec | `.aioson/context/ui-spec.md` (current canonical; `ui-spec-{slug}.md` is accepted only when explicitly feature-scoped) |
 | `@sheldon` | Manifest | `.aioson/plans/{slug}/manifest.md` |
-| `@pm` | Implementation Plan | `.aioson/context/implementation-plan-{slug}.md` |
-| `@dev` | Feature spec | `.aioson/context/spec-{slug}.md` |
-| `@dev` / `@deyvin` | Simple plan | `.aioson/context/simple-plans/{slug}.md` |
-| `@qa` | QA report | `.aioson/context/qa-report-{slug}.md` |
+| `@pm` | Implementation Plan | `.aioson/context/implementation-plan-{slug}.md` |
+| `@dev` | Feature spec | `.aioson/context/spec-{slug}.md` |
+| `@dev` / `@deyvin` | Simple plan | `.aioson/context/simple-plans/{slug}.md` |
+| `@qa` | QA report | `.aioson/context/qa-report-{slug}.md` |
 | `@squad` | Squad manifest | `.aioson/squads/{slug}/squad.manifest.json` |
 | `@squad` | Agent prompts | `.aioson/squads/{slug}/agents/{agent}.md` |
 
@@ -36,10 +40,10 @@ Every artifact produced by an AIOSON agent MUST be written to disk before sessio
 
 Exceptions: drafts shown mid-session for validation (before final save), artifacts explicitly cancelled by user.
 
-`project-pulse.md` must be updated at session end regardless of other artifacts.
+`.aioson/context/project-pulse.md` must be updated at session end regardless of other artifacts.
 
 ## On violation detected
 
 1. Write the artifact before closing — never defer to next session.
 2. If content was shown in chat, use it to write the file now.
-3. Update `project-pulse.md`.
+3. Update `.aioson/context/project-pulse.md`.

package/template/.aioson/rules/example-monetary-values.md

@@ -4,6 +4,10 @@ description: All monetary values must be stored as integer cents, never as float
 agents: [dev, architect, qa]
 priority: 5
 version: 1.0.0
+modes: [planning, executing]
+task_types: [payment, billing, pricing]
+load_tier: trigger
+triggers: [money, monetary values, price, pricing, currency, cents, payment, billing, checkout, invoice, refund]
 ---
 
 # Monetary Values Convention

package/template/.aioson/rules/implementation-structure-and-data-access.md

@@ -0,0 +1,50 @@
+---
+name: implementation-structure-and-data-access
+description: Build maintainable implementation slices with framework-first structure, small files, clear module boundaries, and data access kept out of presentation/control flow.
+priority: 8
+version: 1.0.0
+agents: [architect, dev, deyvin, qa, tester, pentester]
+modes: [planning, executing]
+task_types: [implementation-architecture, implementation, refactor, module-boundary, data-access, framework-implementation]
+load_tier: trigger
+triggers: [componentization, split module, folder structure, framework conventions, Laravel, controller, service layer, repository, query builder, database query, raw SQL, maintainability, files too large]
+paths: [app/**, src/**, lib/**, routes/**, database/**, tests/**, resources/**, config/**, template/**]
+---
+
+# Implementation Structure And Data Access
+
+Build code in small, maintainable units that fit the installed framework. Prefer the project's existing structure and the framework's official extension points before creating pure custom plumbing.
+
+## Framework-First Rule
+
+- Detect the installed framework from project context, package manifests, lockfiles, config files, and existing directories.
+- Use framework-native features before hand-rolled alternatives when they solve the same problem cleanly.
+- If a framework convention exists locally, follow the local convention first; if the project has no pattern yet, follow the framework convention.
+- Do not introduce a new architectural pattern when a nearby module already solves the same class of problem.
+
+## Componentization
+
+- Keep files focused on one responsibility. Split large files before adding unrelated behavior.
+- Put orchestration in services/actions/use-cases, not in controllers, route handlers, UI components, commands, or jobs.
+- Keep controllers and route handlers thin: validate input, call application logic, return a response.
+- Keep UI components focused on rendering and interaction state; move business rules and data access to the appropriate application layer.
+- Prefer cohesive folders/subfolders when a feature grows: requests, resources, actions/services, queries/repositories, policies, jobs, events/listeners, tests, and feature-local components where the framework supports them.
+- Add an abstraction only when it removes real duplication, clarifies a boundary, or matches an established local pattern.
+
+## Data Access Boundary
+
+- Do not expose raw SQL, query builders, ORM chains, or database filtering deep inside controllers, route handlers, UI components, views, jobs, or unrelated services.
+- Put data access in the framework-recommended place: model scopes, repositories, query objects, data mappers, service methods, or dedicated persistence modules depending on the stack.
+- Parameterize all queries. Never interpolate user input into SQL strings or query fragments.
+- Keep read queries and write transactions explicit. Use framework transaction helpers for multi-step writes.
+- For Laravel, prefer FormRequest for validation, Eloquent scopes or dedicated query classes for reusable filters, policies for authorization, resources for API shape, jobs for background work, and service/action classes for application workflows.
+- For non-Laravel stacks, translate the same boundary to the framework's idioms instead of copying Laravel folder names blindly.
+
+## Review Checklist
+
+- The implementation follows existing project/framework conventions.
+- Files stay small enough to scan and test.
+- Controllers, route handlers, UI components, and views do not contain persistence details.
+- Queries live in the proper data access layer and are parameterized.
+- Scan controllers, routes, views, and components for `DB::`, raw SQL, or long query-builder chains; move them to the data access layer.
+- New folders are justified by framework convention or repeated local structure.

package/template/.aioson/rules/output-brevity.md

@@ -3,6 +3,8 @@ name: output-brevity
 description: All agents must produce terse, direct output — no preambles, no trailing summaries, no narration of actions
 priority: 8
 version: 1.0.0
+modes: [planning, executing]
+load_tier: always
 ---
 
 # Output Brevity

package/template/.aioson/rules/prd-section-ownership.md

@@ -1,9 +1,14 @@
 ---
 name: prd-section-ownership
-description: Defines which agent owns each PRD section — other agents cannot modify sections they do not own
+description: Defines which agent owns each PRD section — other agents cannot modify sections they do not own
 priority: 9
 version: 1.0.0
 agents: [product, pm, analyst, architect, ux-ui, sheldon]
+modes: [planning, executing]
+task_types: [prd-edit, prd-enrichment]
+load_tier: trigger
+triggers: [prd, acceptance criteria, delivery phases, editing prd, enriching prd]
+paths: [.aioson/context/prd*.md]
 ---
 
 # PRD Section Ownership
@@ -14,16 +19,16 @@ agents: [product, pm, analyst, architect, ux-ui, sheldon]
 
 | PRD Section | Owner | Others may |
 |---|---|---|
-| `## Objective` | `@product` | Read only |
-| `## Problem` | `@product` | Read only |
-| `## Users And Personas` | `@product` | Read only |
-| `## Features` | `@product` | Read only |
-| `## Acceptance Criteria` | `@product` (structure) / `@pm` (enrichment) | `@analyst`, `@architect` add technical sub-items |
-| `## Delivery Phases` | `@pm` | Read only |
-| `## Technical Constraints` | `@architect` | Read only |
-| `## UX Considerations` | `@ux-ui` | Read only |
-| `## Risks` | `@pm` | `@analyst`, `@architect` add new risks only |
-| `## Registered Decisions` | `@sheldon` (project) / `@pm` (feature) | Read only |
+| `## Objective` | `@product` | Read only |
+| `## Problem` | `@product` | Read only |
+| `## Users And Personas` | `@product` | Read only |
+| `## Features` | `@product` | Read only |
+| `## Acceptance Criteria` | `@product` (structure) / `@pm` (enrichment) | `@analyst`, `@architect` add technical sub-items |
+| `## Delivery Phases` | `@pm` | Read only |
+| `## Technical Constraints` | `@architect` | Read only |
+| `## UX Considerations` | `@ux-ui` | Read only |
+| `## Risks` | `@pm` | `@analyst`, `@architect` add new risks only |
+| `## Registered Decisions` | `@sheldon` (project) / `@pm` (feature) | Read only |
 
 ## Modification rule
 
@@ -32,7 +37,7 @@ An agent may only modify sections it owns. Non-owners may only **add** a new sub
 ## Safe addition pattern
 
 ```markdown
-## Acceptance Criteria
+## Acceptance Criteria
 <!-- @product: owner of this section -->
 
 - CA-01: User can schedule an appointment

package/template/.aioson/rules/security-baseline.md

@@ -3,14 +3,19 @@ name: security-baseline
 description: Secure by Default baseline controls for technical agents
 priority: 10
 version: 1.0.0
-agents: [analyst, architect, dev, qa]
+agents: [analyst, architect, sheldon, dev, qa, tester, pentester]
+modes: [planning, executing]
+task_types: [security, auth, hardening]
+load_tier: trigger
+triggers: [security, auth, login, password, upload, secret, token, permission, ownership, rate limit, payment, multi-tenant, sanitize]
 ---
 
 # Security Baseline — Secure by Default
 
 > Implements `Article VII — Zero Trust by Default` of the AIOSON constitution.
-> Loaded by `@analyst`, `@architect`, `@dev`, and `@qa`. Other agents must not
-> load this rule — product, copy, design and orchestration scopes are out of band.
+> Loaded by technical and PRD-enrichment agents when security triggers fire:
+> `@analyst`, `@architect`, `@sheldon`, `@dev`, `@qa`, `@tester`, and
+> `@pentester`. Product, copy, design and orchestration scopes are out of band.
 
 This rule defines the minimum security baseline every technical agent must
 respect. It does **not** promise absolute security. It declares concrete

package/template/.aioson/rules/simple-plan-lane.md

@@ -1,9 +1,14 @@
 ---
 name: simple-plan-lane
-description: Lightweight implementation lane for bounded technical work that does not justify a PRD or full workflow.
+description: Lightweight implementation lane for bounded technical work that does not justify a PRD or full workflow, with an implementation intelligence checkpoint before coding.
 priority: 9
 version: 1.0.0
 agents: [dev, deyvin, qa, neo]
+modes: [planning, executing]
+task_types: [simple-plan, bounded-work, refactor]
+load_tier: trigger
+triggers: [simple plan, bounded technical work, small fix, refactor, polish, implementation intelligence]
+paths: [.aioson/context/simple-plans/**]
 ---
 
 # Simple Plan Lane
@@ -14,6 +19,14 @@ Canonical artifact:
 
 - `.aioson/context/simple-plans/{slug}.md`
 
+A simple plan is not valid as a bare TODO list. Before implementation it must record:
+
+- selected context/rules/docs or the CLI-less fallback evidence
+- the existing project/framework pattern to follow, or `none found`
+- framework leverage before custom code
+- structure and data boundary placement
+- useful options considered as `include now`, `defer`, or `escalate`
+
 Use this lane only when all conditions are true:
 
 - Objective fits in one sentence.
@@ -24,6 +37,7 @@ Use this lane only when all conditions are true:
 - The work does not touch auth, money, ownership, permissions, secrets, destructive deletion, or sensitive data storage.
 - Expected implementation is small and reviewable.
 - Done criteria and verification command can be written before coding.
+- Useful implementation options can be classified without changing product, UX, domain, architecture, or security ownership.
 
 Escalate instead:
 
@@ -32,6 +46,8 @@ Escalate instead:
 - `@architect` for cross-module architecture or structural decisions.
 - `@pentester` / `@qa` for sensitive surfaces or formal verification.
 
+If an option would widen behavior, UX, permissions, data sensitivity, architecture, integration scope, or verification ownership, do not implement it as part of the simple plan. Park it under `Useful options considered -> Escalate` and hand off.
+
 Lifecycle:
 
 - `draft` -> `in_progress` -> `done`, `paused`, or `abandoned`
@@ -40,9 +56,10 @@ Lifecycle:
 When `@dev` or `@deyvin` uses this lane:
 
 1. Write the simple plan to disk before implementation.
-2. Run `aioson dev:state:write . --feature={slug} --next="<first slice>" --context=simple-plan`.
-3. Implement in small slices.
-4. Run the listed verification.
-5. Update the simple plan status and session state before closing.
+2. Include `Context selected`, `Implementation intelligence`, and `Useful options considered` sections.
+3. Run `aioson dev:state:write . --feature={slug} --next="<first slice>" --context=simple-plan`.
+4. Implement in small slices, only including options classified as `include now`.
+5. Run the listed verification.
+6. Update the simple plan status and session state before closing.
 
 Detailed guide: `.aioson/docs/dev/simple-plan-lane.md`.

package/template/.aioson/rules/source-code-language-convention.md

@@ -0,0 +1,34 @@
+---
+name: source-code-language-convention
+description: Source code identifiers and generated implementation code use technical English; user-facing copy still follows the project language.
+priority: 8
+version: 1.0.0
+agents: [architect, dev, deyvin, qa, tester]
+modes: [planning, executing]
+task_types: [implementation, refactor, code-generation, naming, framework-implementation]
+load_tier: trigger
+triggers: [source code, code language, naming, variables, functions, classes, implement, refactor, Laravel, PHP, controller, service, repository, migration]
+paths: [app/**, src/**, lib/**, routes/**, database/**, tests/**, resources/**, config/**, template/**]
+---
+
+# Source Code Language Convention
+
+Source code is implementation interface. Write identifiers, filenames, classes, functions, variables, database artifacts, migrations, service names, comments that explain code behavior, and generated framework code in technical English.
+
+User-facing copy, documentation artifacts, PRDs, specs, CLI explanations, validation messages, and product text follow `interaction_language` from project context, falling back to `conversation_language`.
+
+## Required Behavior
+
+- Use English for source code identifiers: classes, methods, functions, variables, enums, constants, routes, migrations, factories, seeders, tests, services, jobs, events, listeners, policies, resources, repositories, query objects, and component names.
+- Before inventing names, inspect nearby code and follow the project's naming pattern.
+- If the project pattern is unclear, inspect `.aioson/context/bootstrap/how-it-works.md` and `.aioson/context/bootstrap/current-state.md` when selected by `context:select`; otherwise use the framework's official naming conventions.
+- Keep framework-generated names conventional. For Laravel, prefer standard names such as `OrderController`, `StoreOrderRequest`, `OrderPolicy`, `OrderResource`, `CreateOrdersTable`, and `OrderFactory`.
+- Do not translate technical identifiers into the conversation language. Avoid names like `PedidoController`, `criarUsuario`, `valorTotalEmCentavos`, or `servicoPagamento` in source code.
+- Domain terms with established local legal or regulatory meaning may appear in user-facing copy or comments that quote regulation, but code identifiers still need a clear English abstraction.
+
+## Review Checklist
+
+- New source files and identifiers are in English.
+- Names match the local framework and project pattern.
+- User-facing text remains in the project language.
+- No implementation layer uses translated variable, class, method, or migration names.

package/template/.aioson/rules/spec-level-ownership.md

@@ -1,9 +1,14 @@
 ---
 name: spec-level-ownership
-description: spec.md is project-level, spec-{slug}.md is feature-level — the two levels never mix
+description: spec.md is project-level, spec-{slug}.md is feature-level — the two levels never mix
 priority: 9
 version: 1.0.0
 agents: [dev, qa, pm, sheldon]
+modes: [planning, executing]
+task_types: [spec-write, spec-update]
+load_tier: trigger
+triggers: [spec, feature spec, project spec, updating spec, writing spec]
+paths: [.aioson/context/spec*.md]
 ---
 
 # Spec Ownership: Project vs Feature Level
@@ -19,16 +24,16 @@ Two distinct levels — never mix them.
 
 1. `spec.md` never receives feature-specific content → create `spec-{slug}.md` for that.
 2. `spec-{slug}.md` never receives project decisions → stack decisions go in `spec.md` or `architecture.md`.
-3. `spec-{slug}.md` is created by `@dev` at feature implementation start. One file per slug. Slug must match `prd-{slug}.md` and `implementation-plan-{slug}.md`.
-4. No `spec-{slug}.md` without a corresponding `prd-{slug}.md`.
-5. Simple-plan work does not require `spec-{slug}.md`; keep its scope and decisions in `.aioson/context/simple-plans/{slug}.md` unless the work expands into a real feature.
+3. `spec-{slug}.md` is created by `@dev` at feature implementation start. One file per slug. Slug must match `prd-{slug}.md` and `implementation-plan-{slug}.md`.
+4. No `spec-{slug}.md` without a corresponding `prd-{slug}.md`.
+5. Simple-plan work does not require `spec-{slug}.md`; keep its scope and decisions in `.aioson/context/simple-plans/{slug}.md` unless the work expands into a real feature.
 
 ## Mandatory structure: spec-{slug}.md
 
 ```markdown
 ---
 feature: {slug}
-status: in_progress | paused | done | abandoned
+status: in_progress | paused | done | abandoned
 phase_gates:
   requirements: approved | pending | skipped
   design: approved | pending | skipped

package/template/.aioson/rules/squad-driver-pattern.md

@@ -4,6 +4,11 @@ description: Territory boundaries and integration pattern for AIOSON squads —
 priority: 9
 version: 1.0.0
 agents: [dev, sheldon, pm, qa, architect]
+modes: [planning, executing]
+task_types: [squad-integration, driver]
+load_tier: trigger
+triggers: [squad, driver, embedding prompts, squad runner, llm call]
+paths: [.aioson/squads/**, src/services/**]
 ---
 
 # Squad Driver Pattern

package/template/.aioson/skills/process/aioson-spec-driven/references/artifact-map.md

@@ -8,12 +8,12 @@
 prd*.md
   → sheldon-enrichment-{slug}.md   (optional enrichment layer)
   → requirements-{slug}.md         (entities, rules, ACs — @analyst)
-  → spec-{slug}.md                 (feature memory — @analyst seeds, @dev fills)
-  → architecture.md                (tech decisions — @architect)
-  → ui-spec.md                     (UI/UX contract — @ux-ui when UI is in scope)
-  → design-doc*.md                 (scope-specific decisions — @architect)
-  → implementation-plan-{slug}.md  (execution sequence — @pm for MEDIUM, AC-SDLC-15)
-  → spec-{slug}.md (updated)       (living state during execution — @dev)
+  → spec-{slug}.md                 (feature memory — @analyst seeds, @dev fills)
+  → architecture.md                (tech decisions — @architect)
+  → ui-spec-{slug}.md              (UI/UX contract — @ux-ui when UI is in scope)
+  → design-doc*.md                 (scope-specific decisions — @architect)
+  → implementation-plan-{slug}.md  (execution sequence — @pm for MEDIUM, AC-SDLC-15)
+  → spec-{slug}.md (updated)       (living state during execution — @dev)
 ```
 
 ## Artifact ownership
@@ -22,32 +22,33 @@ prd*.md
 |----------|-----------|-------------|---------|
 | `prd.md` / `prd-{slug}.md` | @product | @sheldon (via sheldon-enrichment) | all downstream |
 | `sheldon-enrichment-{slug}.md` | @sheldon | @sheldon | @sheldon (re-entry), @analyst |
-| `sheldon-validation.md` | @sheldon | — | all agents before starting MEDIUM |
+| `sheldon-validation-{slug}.md` (project: `sheldon-validation.md`) | @sheldon (MEDIUM only) | — | downstream agents when present; `artifact:validate` surfaces it separately from enrichment |
 | `discovery.md` | @analyst | — | @architect, @dev |
 | `requirements-{slug}.md` | @analyst | — | @architect, @dev, @qa |
 | `spec-{slug}.md` | @analyst (skeleton) | @dev (execution state) | @dev, @deyvin, @qa |
 | `spec.md` | @dev | @dev | @dev, @deyvin |
-| `architecture.md` | @architect | — | @dev, @ux-ui |
-| `design-doc*.md` | @architect | — | @dev, @ux-ui |
-| `ui-spec.md` | @ux-ui | — | @dev only for UI/frontend implementation, @pm/@orchestrator when UI phases exist |
-| `implementation-plan-{slug}.md` | @pm (MEDIUM, AC-SDLC-15) | — | @dev, @deyvin, @orchestrator |
-
-## Dev context contract
-
-`@dev` should not activate with the entire artifact chain loaded. The final pre-dev agent writes `dev-state.md` with a short primary package, and `implementation-plan-{slug}.md` carries phase-triggered loads:
-
-- `requirements-{slug}.md` — data, rules, ACs, migrations, edge cases
-- `architecture.md` — module boundaries, integrations, security, cross-cutting concerns
-- `design-doc*.md` / `readiness*.md` — implementation paths, reuse decisions, readiness blockers
-- `ui-spec.md` — UI components, frontend routes, interaction states, visual QA
-- PRD / Sheldon enrichment — only for product ambiguity
+| `architecture.md` | @architect | — | @dev, @ux-ui |
+| `design-doc*.md` | @architect | — | @dev, @ux-ui |
+| `ui-spec-{slug}.md` (project: `ui-spec.md`) | @ux-ui | — | @dev only for UI/frontend implementation, @pm/@orchestrator when UI phases exist |
+| `implementation-plan-{slug}.md` | @pm (MEDIUM, AC-SDLC-15) | — | @dev, @deyvin, @orchestrator |
+
+## Dev context contract
+
+`@dev` should not activate with the entire artifact chain loaded. The final pre-dev agent writes `dev-state.md` with a short primary package, and `implementation-plan-{slug}.md` carries phase-triggered loads:
+
+- `requirements-{slug}.md` — data, rules, ACs, migrations, edge cases
+- `architecture.md` — module boundaries, integrations, security, cross-cutting concerns
+- `design-doc*.md` / `readiness*.md` — implementation paths, reuse decisions, readiness blockers
+- `ui-spec-{slug}.md` (project: `ui-spec.md`) — UI components, frontend routes, interaction states, visual QA
+- PRD / Sheldon enrichment — only for product ambiguity
 
 ## Naming conventions
 
-- Project-level artifacts: `prd.md`, `discovery.md`, `spec.md`, `architecture.md`, `ui-spec.md`
-- Feature-level artifacts: always use `{slug}` suffix — `prd-{slug}.md`, `requirements-{slug}.md`, `spec-{slug}.md`
+- Project-level artifacts: `prd.md`, `discovery.md`, `spec.md`, `architecture.md`
+- Feature-level artifacts: always use `{slug}` suffix — `prd-{slug}.md`, `requirements-{slug}.md`, `spec-{slug}.md`, `design-doc-{slug}.md`, `readiness-{slug}.md`, `scope-check-{slug}.md`, `ui-spec-{slug}.md`, `sheldon-enrichment-{slug}.md`, `sheldon-validation-{slug}.md`
 - Enrichment: `sheldon-enrichment.md` (project) or `sheldon-enrichment-{slug}.md` (feature)
 - Plans: `.aioson/plans/{slug}/manifest.md` + `plan-{slug-fase}.md` files
+- **Resolving `{slug}`:** agents must run `aioson feature:current .` (single source of truth — pulse `active_feature`, else the unique `in_progress` feature in `features.md`) before choosing an output path. A bare feature artifact path is a bug: it collides across features. Reserve bare names for genuine project-level work only.
 
 ## What NOT to create
 

package/template/.aioson/skills/process/aioson-spec-driven/references/classification-map.md

@@ -30,6 +30,10 @@
 
 **0–1 = MICRO / 2–3 = SMALL / 4–6 = MEDIUM**
 
+## Sensitive-surface floor
+
+Independent of the 0–6 score, a feature touching any sensitive surface — money/payments, auth, ownership/authz boundaries, uploads, external URLs/webhooks, secrets/credentials, or sensitive storage — has a **floor of SMALL** (never MICRO). `aioson classify` applies this deterministically and reports `floored: true` + `sensitive_surfaces`. The floor only raises the tier; an explicit `sensitive_surfaces: [..]` in the PRD frontmatter forces it when content detection misses.
+
 ## Gate behavior by classification
 
 - **MICRO**: gates are informational, never blocking. @dev may proceed without explicit approval.

package/template/.aioson/skills/process/aioson-spec-driven/references/dev.md

@@ -35,7 +35,7 @@ At session start, after reading `spec-{slug}.md`:
 3. If versions match: proceed normally
 
 Additionally, at session start for SMALL/MEDIUM:
-4. Check if any `AC-{slug}-{N}` from `requirements-{slug}.md` has a corresponding test file
+4. Run `aioson ac:test-audit . --feature={slug}` when a feature slug exists, or manually check that each `AC-*` from `requirements-{slug}.md` appears in a corresponding test file
 5. If coverage is < 50%:
    > "⚠ AC coverage is low ({N}/{M} ACs have tests). Consider writing missing tests before adding new behavior."
    This is informational, not blocking.
@@ -45,6 +45,6 @@ Additionally, at session start for SMALL/MEDIUM:
 - `spec-{slug}.md` must be updated at the end of every implementation session — see `maintenance-and-state.md` for format
 - Gate C from `approval-gates.md` means the implementation plan is locked — do not re-discuss pre-taken decisions
 - Treat `dev-state.md` as the primary activation package and `implementation-plan-{slug}.md` as the source for phase-triggered context loads
-- Gate D verification must happen before marking a phase complete — not just "I think it works"
+- Gate D verification must happen before marking a phase complete — not just "I think it works". The deterministic floor is `aioson ac:test-audit . --feature={slug}` plus the real test command.
 - If `phase_gates.plan` is `pending` and classification is SMALL/MEDIUM, suggest generating an implementation plan before proceeding
 - If `design-doc.md` or `readiness.md` is missing for SMALL/MEDIUM, route to `@discovery-design-doc` instead of coding first

package/template/.aioson/skills/process/aioson-spec-driven/references/qa.md

@@ -27,4 +27,4 @@
 - @qa is the external verifier of @dev's Gate D self-certification — "I think it works" from @dev is not evidence until @qa confirms
 - Gate D verification from `approval-gates.md` maps directly to @qa's adversarial probe protocol: truths = behavior tests, artifacts = file existence checks, key_links = wiring verification
 - For MEDIUM projects, @qa should verify that `spec_version` in `spec-{slug}.md` matches the version that @dev was working from — if not, flag as potential drift
-- AC coverage mapping in the QA report should use the same `AC-{slug}-{N}` format from `requirements-{slug}.md`
+- AC coverage mapping in the QA report should use the same `AC-*` format from `requirements-{slug}.md`; run `aioson ac:test-audit . --feature={slug}` and treat missing AC test evidence as Gate D blocked.

package/template/.aioson/skills/process/briefing-expansion-scout/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: briefing-expansion-scout
+description: "Briefing process skill for early feature expansion scouting. Use in @briefing or @briefing-refiner when an idea may have a rich surface and the user wants to explore whether it is worth pursuing before PRD: tools, workflows, generators, dashboards, editors, collaboration, automation, templates, media outputs, or Trello/CRM/Kanban-like systems."
+---
+
+# Briefing Expansion Scout
+
+Use this skill to explore possibilities before scope is committed. Do not turn ideas into PRD scope. Produce discussion material that helps the user or team decide whether the idea deserves product definition.
+
+## Load
+
+Read `.aioson/docs/feature-expansion-taxonomy.md` before writing the artifact.
+
+Also read existing expansion artifacts when present:
+
+- `.aioson/briefings/{slug}/expansion-scout.md`
+- `.aioson/context/features/{slug}/scope-expansion.md`
+- `.aioson/context/features/{slug}/expansion-audit.md`
+
+## Trigger Guard
+
+Run only when one is true:
+
+- user asks to explore, expand, evaluate, or pressure-test an idea
+- the idea has a rich surface: workflow, collaboration, editor/builder, generator, dashboard, automation, templates, media output, repeated operational use
+- briefing-refiner detects that an existing briefing feels too thin for team discussion
+
+If the idea is a tiny bugfix or a one-field CRUD addition, skip and say the normal briefing path is enough.
+
+## Output
+
+Write `.aioson/briefings/{slug}/expansion-scout.md`.
+
+Use this structure:
+
+```md
+# Expansion Scout - {Feature}
+
+## Why Scout
+- Trigger:
+- Prior expansion artifacts found:
+
+## Possibility Map
+| Lens | Useful possibilities | Why it matters | Risk |
+|---|---|---|---|
+
+## Likely MVP Shape
+- Core:
+- Recommended MVP:
+- Not enough evidence yet:
+
+## Discussion Questions
+- [decision-required] ...
+- [research-able] ...
+- [testable] ...
+
+## Do Not Pull Into MVP Yet
+- ...
+
+## Recommendation
+Proceed to product definition? yes / no / only after questions.
+```
+
+## Rules
+
+- Keep this artifact exploratory.
+- Mark assumptions explicitly.
+- Separate attractive ideas from useful ideas.
+- Prefer 3-7 high-signal possibilities over exhaustive lists.
+- Do not approve V2 ideas; park them.
+- Do not modify the PRD.
+

package/template/.aioson/skills/process/product-scope-expansion/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: product-scope-expansion
+description: "Product process skill for controlled scope expansion before writing or updating a PRD. Use in @product when a feature has a rich surface, when a briefing expansion scout exists, or when the user asks for a more complete MVP without turning the feature into an oversized V2."
+---
+
+# Product Scope Expansion
+
+Use this skill to convert product possibilities into an approvable scope. The output informs the PRD; it does not replace user approval.
+
+## Load
+
+Read `.aioson/docs/feature-expansion-taxonomy.md`.
+
+Read prior expansion artifacts when present:
+
+- `.aioson/briefings/{slug}/expansion-scout.md`
+- `.aioson/context/features/{slug}/scope-expansion.md`
+- `.aioson/context/features/{slug}/expansion-audit.md`
+
+## Ask Before Expanding
+
+When the feature is not obviously rich, ask a short choice:
+
+1. Continue with simple MVP
+2. Run recommended expansion
+3. Run full expansion, then cut back to MVP
+
+When a scout artifact exists or the user explicitly asks for richer product thinking, run the skill without re-asking unless expansion would materially change classification or timeline.
+
+## Output
+
+Write `.aioson/context/features/{slug}/scope-expansion.md`.
+
+Use this structure:
+
+```md
+# Scope Expansion - {Feature}
+
+## Inputs
+- PRD/briefing source:
+- Prior expansion artifacts:
+- User approval mode: simple / recommended / full
+
+## Scope Buckets
+| Bucket | Items | Why | Approval needed |
+|---|---|---|---|
+| Core | ... | ... | no |
+| Recommended MVP | ... | ... | maybe |
+| Optional V1 | ... | ... | yes |
+| Delight | ... | ... | yes |
+| V2 / Later | ... | ... | yes, future |
+| Cut List | ... | ... | no |
+
+## Recommended Product Shape
+- Include in PRD:
+- Keep as optional:
+- Explicitly defer:
+
+## Risks And Classification
+- Scope risk:
+- Delivery risk:
+- Classification impact:
+
+## Cheap / Native Implementation Ideas
+- ...
+```
+
+## PRD Incorporation Rules
+
+- Incorporate Core and approved Recommended MVP into the PRD.
+- Do not silently include Optional V1, Delight, or V2 items.
+- If expansion raises classification, surface that before finalizing.
+- Preserve "small project, small solution": a rich feature can still have a small first release.
+