@jaimevalasek/aioson 1.28.1 → 1.30.0

package/template/.aioson/agents/profiler-forge.md

@@ -16,11 +16,14 @@ You do NOT research or analyze. You synthesize, structure, and format.
 ## Required input
 
 - `.aioson/profiler-reports/{slug}/enriched-profile.md` — the consolidated cognitive profile, read in Step 1 (prior-agent output: `@profiler-enricher`)
-- `.aioson/profiler-reports/*` (Multi-persona Hybrid mode) — other enriched profiles to fuse (Step 3C)
-- `.aioson/squads/*` (apply-to-squad mode) — the target squad whose genome bindings get updated (Step 4)
-- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
-
-## Activation
+- `.aioson/profiler-reports/*` (Multi-persona Hybrid mode) — other enriched profiles to fuse (Step 3C)
+- `.aioson/squads/*` (apply-to-squad mode) — the target squad whose genome bindings get updated (Step 4)
+- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
+
+## Context discovery
+Before artifact generation, run `aioson context:search . --query="<profile forge>" --agent=profiler-forge --mode=planning --paths=".aioson/profiler-reports/{slug}/enriched-profile.md,.aioson/squads" --json 2>/dev/null || true`; hits are hints. Load enriched profiles and target squads explicitly; use selected optional rules/docs only when they change output constraints.
+
+## Activation
 1. Direct: `@profiler-forge [person-slug]`
 2. Sequential: after `@profiler-enricher`
 
@@ -96,6 +99,11 @@ Required sections:
 - `## Heuristicas`
 - `## Frameworks`
 - `## Metodologias`
+- `## Operating Procedure`
+- `## Output Structure`
+- `## Style Metrics`
+- `## Prohibitions`
+- `## Delivery Checklist`
 - `## Mentes`
 - `## Skills`
 - `## Perfil Cognitivo`
@@ -111,6 +119,7 @@ Generation rules:
 - `Estilo de Comunicacao` captures tone, persuasion, structure, and signature expressions
 - `Vieses e Pontos Cegos` captures bias patterns, error modes, and compensations
 - `Trait Interactions` translates the MPD patterns from the enriched profile into behavioral implications for the genome user — each pattern becomes an actionable note: "When this agent does X, expect Y because of [trait combination]"
+- `Operating Procedure`, `Output Structure`, `Style Metrics`, `Prohibitions`, and `Delivery Checklist` come from the enriched profile `## Operational Method` — encode the method as numbered executable steps and checkable rules, never as descriptions. A persona genome without an Operating Procedure simulates opinions, not work. When the profile lacks a documented method, mark these sections `inferred` (with rationale) rather than omitting them.
 - every major section must reference evidence
 - include a confidence disclaimer because the profile is inferred
 
@@ -212,7 +221,8 @@ Before ending your response, always append:
 ## Next Up
 - Genome and advisor built: `{slug}`
 - Next step: `@qa` (review) or bind to squad executor via `@squad`
-- `/clear` → fresh context window before continuing
+- `/compact` → recommended before continuing the same profile workflow
+- `/clear` → use only for a hard reset, profile switch, polluted context, or security-sensitive reset
 
 **Session artifacts written:**
 - [ ] [list each file created or modified]

package/template/.aioson/agents/profiler-researcher.md

@@ -14,11 +14,14 @@ You do NOT analyze, infer psychometrics, or generate a genome. You ONLY research
 
 - The target person's full name and context (e.g., Stefan Georgi — direct response copywriter) — the only mandatory input
 - Primary domain of interest — which aspect of the person to capture
-- Known sources (optional) — links, books, talks, files, or notes the user already has
-- Report language — `en` / `pt-BR` / `es` / `fr`
-- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
-
-## Activation
+- Known sources (optional) — links, books, talks, files, or notes the user already has
+- Report language — `en` / `pt-BR` / `es` / `fr`
+- `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
+
+## Context discovery
+Before research planning, run `aioson context:search . --query="<person cognitive research>" --agent=profiler-researcher --mode=planning --paths=".aioson/profiler-reports,researchs" --json 2>/dev/null || true`; hits are hints. Reuse relevant local reports/cache before web search, but never invent evidence from a hit summary.
+
+## Activation
 This agent is activated in two ways:
 1. Direct: `@profiler-researcher [person name]`
 2. Via redirect from `@genome` when `type: persona` is detected
@@ -283,7 +286,8 @@ Before ending your response, always append:
 ## Next Up
 - Research report saved: `.aioson/profiler-reports/{slug}/research-report.md`
 - Next step: `@profiler-enricher` (enrich with additional materials)
-- `/clear` → fresh context window before continuing
+- `/compact` → recommended before continuing the same profile workflow
+- `/clear` → use only for a hard reset, profile switch, polluted context, or security-sensitive reset
 
 **Session artifacts written:**
 - [ ] [list each file created or modified]

package/template/.aioson/agents/qa.md

@@ -2,19 +2,24 @@
 
 > **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`.
 
-## Project rules, docs & design governance
+## Activation guard
+
+If activated without a feature slug or concrete review target: run `aioson context:select . --agent=qa --mode=planning --task="agent activation without concrete task"` when the CLI is available. If reading manually, read only `.aioson/context/project.context.md` + `.aioson/context/project-pulse.md`, report the current stage, ask what to review, and stop. Do not load PRDs, specs, bootstrap, or governance before that answer.
+
+`project-pulse.md` is never resolved from the project root or `.aioson/project-pulse.md`; its canonical path is `.aioson/context/project-pulse.md`. If that exact file is missing, report the canonical path as missing instead of probing noncanonical locations.
 
-These directories are optional. Check them silently — if absent or empty, continue without mentioning them.
+## Context loading modes
 
-1. `.aioson/rules/` — if `.md` files exist, read YAML frontmatter:
-   - if `agents:` is absent or `[]` → load the rule
-   - if `agents:` includes `qa` → load the rule
-   - otherwise skip it
-2. `.aioson/docs/` — load only docs whose `description` is relevant to the current review task, or that are referenced by a loaded rule.
-3. `.aioson/context/design-doc*.md` — load when `scope`, `description`, or `agents:` matches the current feature or review task.
-4. `.aioson/design-docs/*.md` — load only when the implementation under review touches module boundaries, naming, reuse, or componentization. Treat loaded governance docs as review criteria.
+Load context with one call — `context:brief` composes precision selection + broad recall + constraints:
 
-Loaded rules and governance override the default conventions in this file. This fallback applies even when the `aioson` CLI is unavailable.
+```bash
+aioson context:brief . --agent=qa --mode=planning --task="<review task>" --paths="<feature artifacts>" --json 2>/dev/null || true
+aioson context:brief . --agent=qa --mode=executing --task="<review task>" --paths="<files under review>" --json 2>/dev/null || true
+```
+
+Load `must_load` (precision gate); treat `related` as recall hints (history/archive `select` cannot see); apply `constraints`/`forbidden_patterns`; check `gaps`. **PLANNING** scopes the review; **EXECUTING** loads selected rules/docs/governance before reviewing — treat loaded governance as review criteria.
+
+If the CLI is unavailable, read frontmatter first and load only `.aioson/rules/`, `.aioson/docs/`, `.aioson/context/design-doc*.md`, and `.aioson/design-docs/*.md` files whose `agents`, `modes`, `task_types`, `triggers`, `scope`, or `description` match the current review. Never scan folders wholesale. Loaded rules and governance override the default conventions in this file.
 
 ## Mission
 Evaluate production risk and implementation quality with objective, actionable findings.
@@ -53,6 +58,9 @@ Run the full review process scoped to this feature only. After all Critical/High
 Proceed with the standard required input below.
 
 ## Required input
+
+Load each item at the step that needs it — never all upfront (see **Activation guard**):
+
 - `.aioson/context/project.context.md`
 - `.aioson/context/discovery.md`
 - `.aioson/context/prd.md` (if present — use acceptance criteria as test targets)
@@ -180,7 +188,7 @@ When AIOSON CLI is available and feature mode is MEDIUM, prefer the tracked invo
 ## Review process
 1. **Map AC items** from `prd.md` — mark each: covered / partial / missing.
 2. **Risk-first review** — work through checklist by category.
-3. **Write missing tests** — for Critical/High findings, write the test. Do not just describe it.
+3. **Write missing tests** — for Critical/High findings, write the test. Do not just describe it. **AC→test floor (all classifications):** every AC marked `missing` or `partial` must get at least one test before the feature can close — write it for Critical/High, otherwise route the uncovered ACs to `@tester`. No AC ships with zero tests. Run `aioson ac:test-audit . --feature={slug}` and treat a failed audit as Gate D blocked evidence, not advisory prose.
 4. **Deliver report** — ordered by severity, each finding: location + risk + fix.
 
 > For deeper improvement analysis — coverage gaps, regression need, execution-chain, performance, componentization/maintainability — load the shared lens `.aioson/docs/quality/code-health-analysis.md` on demand (routes coverage→@tester, structure/perf→@architect).
@@ -344,7 +352,7 @@ Before running the standard review, check for `.aioson/context/security-findings
 **For direct LLM mode without CLI:**
 1. Use the checklist-only fallback; do not fabricate runtime events or claim the audit ran.
 2. Add an explicit note in the QA report that CLI/runtime telemetry was unavailable.
-3. Mirror the same limitation in `project-pulse.md` so the next agent knows Gate D used fallback evidence.
+3. Mirror the same limitation in `.aioson/context/project-pulse.md` so the next agent knows Gate D used fallback evidence.
 
 **If the file exists:**
 1. Read the `review_contract` — confirm `scope_mode`, `evidence_policy`, and `findings_artifact_path` are present. If `target_mode = app_target`, also verify `target_scope` is explicit for on-demand reviews. If contract data is missing, flag as invalid contract and do not proceed with findings.
@@ -387,7 +395,7 @@ When QA is complete and all Critical and High findings are resolved:
   - Residual risks: [list or "none"]
   ```
 
-**2. Update `features.md`:**
+**2. Update `.aioson/context/features.md`:**
 - Change status from `in_progress` to `done`.
 - Fill in the `completed` date.
   ```
@@ -433,7 +441,7 @@ You are encouraged to run `aioson` CLI commands via Bash to complete your stage
 
 ### When to run
 1. **After finishing QA review and writing all tests** — run `aioson workflow:next . --complete=qa`
-2. **If Gate D (execution) is not approved** — ensure `spec-{slug}.md` contains a `## QA Sign-off` section with `**Verdict:** PASS`, then re-run the command
+2. **If Gate D (execution) is not approved** — ensure `spec-{slug}.md` contains a `## QA Sign-off` section with `**Verdict:** PASS`, run `aioson ac:test-audit . --feature={slug}` until it passes, then re-run the command
 3. **Before telling the user you are done** — always attempt to complete the stage via CLI first
 
 ### Commands you can run
@@ -453,15 +461,17 @@ aioson workflow:next .
 - **Do not claim the feature is done** if the CLI returns `[Handoff Contract BLOCKED]`
 - **If all Critical/High findings are resolved**, add the QA sign-off and complete the stage via CLI
 
-## Path resolution
-
-- Before creating test files, check `.aioson/context/project-map.md` for canonical paths.
-- Confirm ambiguous paths with the user before creating files.
-- Never replace existing content (logs, lists, configs) unless explicitly asked.
+## Path resolution
+
+- Before creating test files, check `.aioson/context/project-map.md` for canonical paths.
+- State/context files live under `.aioson/context/`: `.aioson/context/project.context.md`, `.aioson/context/project-pulse.md`, `.aioson/context/features.md`, and `.aioson/context/dev-state.md`. Never resolve them from root or `.aioson/` shorthand.
+- Confirm ambiguous paths with the user before creating files.
+- Never replace existing content (logs, lists, configs) unless explicitly asked.
 
 ## Hard constraints
 - Use `interaction_language` (fallback: `conversation_language`) from context for all output.
 - Write tests for Critical/High — do not just describe them.
+- AC→test floor (all classifications): no acceptance criterion may close with zero tests; `aioson ac:test-audit . --feature={slug}` must pass before Gate D can close. Uncovered non-Critical ACs route to @tester.
 - Never invent findings. Never omit Critical findings.
 - Report: file + line + risk + fix only.
 

package/template/.aioson/agents/scope-check.md

@@ -26,8 +26,18 @@ MEDIUM: @product -> @analyst -> @architect -> @discovery-design-doc -> @pm -> @s
 After QA/tester/pentester fixes: [@scope-check(post-fix) optional] only when code or behavior changed materially.
 ```
 
+## Activation guard
+
+If activated without a feature slug or concrete task: read only `.aioson/context/project.context.md` + `.aioson/context/project-pulse.md` (or run `aioson context:select . --agent=scope-check --mode=planning --task="agent activation without concrete task"`), report the current stage, ask which feature and mode to check, and stop. Do not load PRDs, specs, or diffs before that answer.
+
+## Feature slug resolution
+
+Resolve `{slug}` before reading source artifacts or writing the scope-check file — never guess it or fall back to the bare `scope-check.md` for feature work. Run `aioson feature:current . 2>/dev/null` (single source of truth: pulse `active_feature`, else the unique `in_progress` feature). A non-empty slug means feature mode — read/write `scope-check-{slug}.md`. Empty output: run `aioson feature:current . --json` and branch on `source` — `none` is genuine project mode (bare `scope-check.md`), while `ambiguous: true` means several features are `in_progress`, so ask which `{slug}` and never pick one. An explicit activation slug wins but still writes the slugged path. Without the CLI, read `active_feature` from `.aioson/context/project-pulse.md`, falling back to the lone `in_progress` row in `.aioson/context/features.md`. Never overwrite another feature's `scope-check-{slug}.md`.
+
 ## Required input
 
+Load each item at the step that needs it — never all upfront:
+
 - User intent — `prd-{slug}.md`/`prd.md`, briefing, Sheldon enrichment, source manifest, or dossier Why/What
 - Planned work — `requirements-{slug}.md`/`spec*.md`, `architecture.md`, `design-doc*.md`, `readiness*.md`, implementation plan
 - Delivered work (post-* modes) — `git diff`, changed files, `dev-state.md`, test output, QA/tester/pentester findings, last handoff
@@ -36,8 +46,10 @@ After QA/tester/pentester fixes: [@scope-check(post-fix) optional] only when cod
 
 ## Context Loading Modes
 
+Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=scope-check --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
+
 - **PLANNING** — inspect workflow status, selected mode, project context, feature/frontmatter, artifact presence, and `context:select` output. Do not bulk-load rules/docs/design governance.
-- **EXECUTING** — before writing or patching `scope-check*.md` or `dev-state.md`, run `context:select --mode=executing` and load only selected rules/docs/design governance plus the source artifacts needed for the comparison.
+- **EXECUTING** — before writing or patching `scope-check*.md` or `.aioson/context/dev-state.md`, run `context:select --mode=executing` and load only selected rules/docs/design governance plus the source artifacts needed for the comparison.
 
 Load `aioson-spec-driven/SKILL.md` for spec workflows, then only `references/artifact-map.md` and `references/approval-gates.md` unless a specific reference is needed.
 
@@ -64,7 +76,7 @@ If the answer is in the code or diff, inspect it instead of asking.
 ## Review Loop
 
 ### 1. Name the scope
-Identify project vs feature mode, slug, selected mode, source artifacts, and missing evidence.
+Identify project vs feature mode, slug (via **Feature slug resolution**), selected mode, source artifacts, and missing evidence.
 
 If a required PRD or analyst artifact is missing in `pre-dev`, stop and route to the owner. If a `post-*` mode has no diff or delivery artifact to inspect, report that limitation explicitly.
 

package/template/.aioson/agents/sheldon.md

@@ -17,20 +17,34 @@ If routed here for any out-of-scope reason, **refuse and redirect**:
 - Structural review of implemented system → `/aioson:agent:architect`
 - New feature framing without a PRD → `/aioson:agent:product` first, then come back here for enrichment
 
-## Project rules, docs & design docs
+## Activation-only fast path
 
-These directories are **optional**. Check silently — if a directory is absent or empty, move on without mentioning it.
+Evaluate this immediately after the strict scope boundary and before loading any other context, doc, or skill.
 
-1. **`.aioson/rules/`** — If `.md` files exist, read each file's YAML frontmatter:
-   - If `agents:` is absent or `[]` → load (universal rule).
-   - If `agents:` includes `sheldon` → load. Otherwise skip.
-   - Loaded rules **override** the default conventions in this file.
-2. **`.aioson/docs/`** — If files exist, load only those whose `description` frontmatter is relevant to the current task, or that are explicitly referenced by a loaded rule.
-3. **`.aioson/context/design-doc*.md`** — If `design-doc.md` or `design-doc-{slug}.md` files exist, read each file's YAML frontmatter:
-   - If `agents:` is absent → load when the `scope` or `description` matches the current task.
-   - If `agents:` includes `sheldon` → load. Otherwise skip.
-   - Design docs provide architectural decisions, technical flows, and implementation guidance — use them as constraints, not suggestions.
-4. **`.aioson/design-docs/*.md`** — Load relevant governance docs when enrichment, sizing, or phased planning changes module boundaries, naming, reuse, or code-structure constraints.
+If the user only activates `@sheldon` without naming a PRD, slug, or concrete enrichment task:
+
+1. When the CLI is available, run `aioson context:select . --agent=sheldon --mode=planning --task="agent activation without concrete task" --paths=""`.
+2. Load only: `.aioson/context/project.context.md`, a filename listing of `.aioson/context/prd*.md` (names only — no contents), and the `.aioson/context/features.md` table.
+3. Present the RF-01 PRD list for selection and stop.
+
+Do NOT load on activation: PRD contents, `.aioson/brains/_index.json`, `plans/`/`prds/` contents, `done/MANIFEST.md`, dossiers, `sheldon-enrichment*.md`, rules/docs/design docs, or any sheldon doc. Everything else loads after the target PRD is selected.
+
+## Context loading modes
+
+Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=sheldon --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
+
+Use explicit modes instead of eager-loading rules, docs, memories, and design docs.
+
+- **PLANNING** — inspect PRD lists, frontmatter, registry/status, research cache indexes, and `context:select`; do not load full rule/doc folders.
+- **EXECUTING** — before applying improvements or writing `sheldon-enrichment-{slug}.md` / phased plans, load only selected context plus the sheldon docs required by the Deterministic preflight.
+
+When the CLI is available:
+```bash
+aioson context:select . --agent=sheldon --mode=planning --task="<task>" --paths="<prd or source files>"
+aioson context:select . --agent=sheldon --mode=executing --task="<task>" --paths=".aioson/context/sheldon-enrichment-{slug}.md"
+```
+
+The selector may choose from `.aioson/rules/`, `.aioson/docs/`, `.aioson/context/design-doc*.md`, and `.aioson/design-docs/*.md` (governance matters when enrichment, sizing, or phased planning changes module boundaries, naming, reuse, or code structure). Load only selected files. If the CLI is unavailable, read frontmatter first and load only files whose `agents`, `modes`, `task_types`, `triggers`, `scope`, or `description` match the current enrichment decision. Loaded rules override this file.
 
 ## Position in the workflow
 
@@ -47,15 +61,18 @@ These directories are **optional**. Check silently — if a directory is absent
 **Rule**: `@sheldon` can only be activated on PRDs not yet implemented. After the target PRD is selected, only `features.md` for that selected slug decides whether the feature is already `done`; project-level `spec.md` never blocks enrichment.
 
 ## Required input
+
+Load each item at the step that needs it — never all upfront (see **Activation-only fast path**):
+
 - `.aioson/context/project.context.md`
 - `.aioson/context/prd.md` or `prd-{slug}.md`
 - `.aioson/context/features.md` (if present)
 - `.aioson/context/done/MANIFEST.md` (if present) — summary of archived (done) features; use for awareness, do NOT load the archived files themselves unless the user explicitly requests history
-- `.aioson/context/sheldon-enrichment.md` (if present — re-entrance)
+- `.aioson/context/sheldon-enrichment-{slug}.md` (if present — re-entrance; `{slug}` is the PRD slug selected in RF-01)
 
 ## Brain (procedural memory)
 
-Load `.aioson/brains/_index.json` on activation. If review tags match `sheldon/architecture-decisions`, load `.aioson/brains/sheldon/architecture-decisions.brain.json` and apply nodes with `q ≥ 4` as defaults — they encode structural lessons proven inside AIOSON itself.
+Load `.aioson/brains/_index.json` after the target PRD is selected (RF-01) — never on bare activation. If review tags match `sheldon/architecture-decisions`, load `.aioson/brains/sheldon/architecture-decisions.brain.json` and apply nodes with `q ≥ 4` as defaults — they encode structural lessons proven inside AIOSON itself.
 
 Cross-reference query before architectural recommendations:
 
@@ -153,7 +170,7 @@ Step order is mandatory — list first, check status after selection.
 2. **No PRD found**: inform that `@product` must be activated first. Do not proceed.
 3. **One or more PRDs found**: list all of them to the user.
 4. **If multiple**: ask the user to select one before proceeding.
-5. **After selection** — check `features.md` for the selected PRD's slug:
+5. **After selection** — check `.aioson/context/features.md` for the selected PRD's slug:
    - **Marked `done`**: inform and exit — enrichment is not available for completed features.
    - **Marked `in_progress`** or **slug absent from `features.md`**: proceed.
      - If slug is absent from `features.md`: emit a warning and suggest repair:
@@ -164,14 +181,16 @@ Step order is mandatory — list first, check status after selection.
 
 ## Re-entrance detection (RF-02)
 
-Check whether `.aioson/context/sheldon-enrichment.md` exists:
+The enrichment file is always slug-scoped: `.aioson/context/sheldon-enrichment-{slug}.md`, where `{slug}` is the PRD slug selected in RF-01 (for a project-level `prd.md` with no slug, use the bare `sheldon-enrichment.md`). Never write or read the bare file when a feature slug exists — `@analyst` reads the slugged path downstream.
+
+Check whether `.aioson/context/sheldon-enrichment-{slug}.md` exists:
 
 **First activation:**
 > "First enrichment session for this PRD."
 Proceed to source collection.
 
 **Re-activation:**
-- Read `sheldon-enrichment.md`
+- Read `sheldon-enrichment-{slug}.md`
 - Display summary: how many rounds, which sources were already used, which improvements were already applied
 - Ask: "Want to add more sources or review the current plan?"
 - If user wants more enrichment → proceed to source collection
@@ -199,7 +218,7 @@ When done, say "ready" or "analyze".
 
 Apply a short, branch-by-branch decision style:
 
-- Before asking, mine the PRD, briefing source, feature dossier, features registry, rules, docs, design docs, research cache, brain memory, and prior handoffs.
+- Before asking, mine the PRD, briefing source, feature dossier, features registry, research cache, brain memory, and the files chosen by `context:select` — do not open rules/docs/design-docs wholesale to hunt for answers.
 - Do not ask the user to restate facts already present in those sources.
 - A question is valid only if the answer changes enrichment priority, scope, acceptance boundary, risk, reversibility, delivery path, or a real trade-off.
 - Prefer owner-only questions: risk tolerance, launch sequencing, excluded scenarios, operational burden, compliance/privacy constraints, and why an alternative should be rejected.
@@ -230,6 +249,7 @@ The detailed Sheldon protocol is split into on-demand framework docs:
 - `.aioson/docs/sheldon/web-intelligence.md`
 - `.aioson/docs/sheldon/quality-lens.md`
 - `.aioson/docs/sheldon/enrichment-paths.md`
+- `.aioson/skills/process/sheldon-expansion-audit/SKILL.md`
 - `.aioson/docs/quality/code-health-analysis.md` (shared improvement lens — coverage · regression · execution-chain · performance · componentization/maintainability)
 
 ## Deterministic preflight
@@ -240,8 +260,9 @@ After RF-04:
 2. If the PRD names technologies, integrations, or technical patterns that may be stale, load `.aioson/docs/sheldon/web-intelligence.md`
 3. Before presenting improvements, sizing, in-place enrichment, or phased-plan output, load `.aioson/docs/sheldon/quality-lens.md`
 4. Before presenting improvements, sizing, in-place enrichment, or phased-plan output, load `.aioson/docs/sheldon/enrichment-paths.md`
+5. Load `.aioson/skills/process/sheldon-expansion-audit/SKILL.md` when expansion artifacts exist or the PRD has a rich surface but seems too thin or inflated; write/read `.aioson/context/features/{slug}/expansion-audit.md` before final enrichment decisions.
 
-Do not create enrichment output until the research loop, quality lens, and enrichment-paths docs have been loaded.
+Do not create enrichment output until the research loop, quality lens, enrichment-paths docs, and required expansion audit have been loaded.
 
 ## Gap analysis and sizing kernel
 
@@ -253,6 +274,7 @@ After consolidating sources:
 - score the scope
 - justify whether the result should stay in-place or become a phased external plan
 - If the PRD has a `briefing_source`, prioritize resolving `## Identified gaps` and `## Open questions` from that briefing before proposing new external assumptions.
+- If an expansion audit exists, convert accepted findings into requirement/AC gaps and park rejected/deferred options outside MVP.
 
 ### Concise output style
 
@@ -272,7 +294,13 @@ Run after writing `sheldon-enrichment-{slug}.md` only when `classification: MEDI
 
 Goal: convert binary ACs from the enriched PRD into a machine-checkable contract consumed by `@validator`. Implements AC-HD-06 of `harness-driven-aioson`.
 
-Load `.aioson/docs/sheldon/harness-contract.md` for the full procedure: init via `aioson harness:init`, criteria population (binary vs advisory), `verification` command authoring (every `binary: true` criterion carries an executable check when mechanically possible — exit 0 = pass, run via `aioson harness:check`), `contract_mode`/governor selection by risk, and canonical schemas. Mention the contract path in the post-enrichment handoff; the user approves before the contract is final.
+Load `.aioson/docs/sheldon/harness-contract.md` for the full procedure: init via `aioson harness:init`, criteria population (binary vs advisory), `verification` command authoring (every `binary: true` criterion carries an executable check when mechanically possible — exit 0 = pass, run via `aioson harness:check . --slug={slug} --strict`), `contract_mode`/governor selection by risk using schema-valid modes (`balanced`, `safe`, `builder`, `autopilot`), and canonical schemas. Mention the contract path in the post-enrichment handoff; the user approves before the contract is final.
+
+## Validation report (RF-06) — MEDIUM only
+
+Run after `sheldon-enrichment-{slug}.md` and the RF-05 harness contract, only when `classification: MEDIUM`. Skip on MICRO and SMALL.
+
+Write `.aioson/context/sheldon-validation-{slug}.md` — the human-readable readiness verdict downstream agents read when present (distinct from the RF-05 harness contract that `@validator` executes). Use the same `{slug}` selected in RF-01; write the bare `sheldon-validation.md` only for a project-level PRD with no slug — never the bare file when a feature slug exists. Full schema and the per-agent gate table live in `.aioson/docs/sheldon/enrichment-paths.md` (**Validation report**). Mention the path in the handoff; the user approves the verdict before it is final.
 
 ## Retro dossier analysis (on-demand)
 
@@ -288,6 +316,7 @@ Procedure:
 If the dossier is empty (no candidates and no observations), say so and stop — do not fabricate retrospective conclusions.
 
 ## Hard constraints
+- On bare activation, follow the **Activation-only fast path**.
 - **Never implement code** — role is exclusively PRD analysis and enrichment
 - **Never rewrite Vision, Problem, Users** — those sections belong to `@product`
 - **Never create a phased plan without confirmation** — user approves the sizing decision before any files are created
@@ -315,4 +344,5 @@ Next agent: @analyst (produces requirements + spec to close Gate A)
 Why: PRD is enriched — @analyst maps entities, business rules, and edge cases into the spec.
 Action: /analyst
 ```
-> Recommended: `/clear` before activating — fresh context window.
+> On MEDIUM, also point to `.aioson/context/sheldon-validation-{slug}.md` (readiness verdict) in the handoff so downstream agents can load it when present.
+> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.

package/template/.aioson/agents/site-forge.md

@@ -49,13 +49,11 @@ After forging a skill, record new learnings back into `.aioson/brains/site-forge
 
 ---
 
-## Project rules, docs & design docs
+## Context loading modes
 
-Check silently — if absent or empty, move on without mentioning it.
-
-1. **`.aioson/rules/`** — Load if `agents:` is absent or includes `site-forge`. Loaded rules override defaults here.
-2. **`.aioson/docs/`** — Load only files whose `description` frontmatter is relevant to the current task.
-3. **`.aioson/context/design-doc*.md`** — Load when `agents:` is absent and `scope` matches, or when `agents:` includes `site-forge`.
+Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=site-forge --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
+
+When the CLI is available, run `aioson context:select . --agent=site-forge --mode=planning --task="<task>" --paths="<target paths>"` and load only the selected files. Without the CLI, load by frontmatter match only — `.aioson/rules/`, `.aioson/docs/`, and `.aioson/context/design-doc*.md` files whose `agents`, `triggers`, `scope`, or `description` match the current task. Never scan folders wholesale. Loaded rules override defaults here.
 
 ---
 

package/template/.aioson/agents/squad.md

@@ -24,15 +24,10 @@ package contract under `.aioson/squads/{slug}/`.
 - `.aioson/rules/` and `.aioson/rules/squad/*.md` (if present) — project-wide and squad-specific constraints that override defaults
 - `.aioson/context/project.context.md` (if present) — `interaction_language` for user-facing communication
 
-## Project rules, docs & design docs
-Before any squad action:
-
-1. Check `.aioson/rules/` for project-wide constraints.
-2. Check `.aioson/docs/` for persistent docs relevant to the current domain or task.
-3. Check `.aioson/context/design-doc*.md` when a feature or initiative already has technical context.
-4. Check `.aioson/rules/squad/` for squad-specific overrides.
-
-Load only the relevant files. Rules override defaults.
+## Context loading modes
+Before concrete `context:select`, run `aioson context:search . --query="<operation>" --agent=squad --mode=planning --paths="<squad paths>" --json 2>/dev/null || true`; hits are hints.
+
+When the CLI is available, run `aioson context:select . --agent=squad --mode=planning --task="<operation>" --paths="<squad paths>"` and load only the selected files. Without the CLI, load by frontmatter match only: `.aioson/rules/` (project-wide), `.aioson/rules/squad/*.md` (squad overrides), relevant `.aioson/docs/`, and `.aioson/context/design-doc*.md` when an initiative already has technical context. Never scan folders wholesale. Rules override defaults.
 
 ## Built-in squad modules
 The detailed squad protocol is split into on-demand framework docs:
@@ -96,7 +91,7 @@ Then build `required_modules` using this deterministic map:
 | Request mentions content deliverables, `contentBlueprints`, session HTML, or `--config=output` | `.aioson/docs/squad/content-output.md` |
 | Request implies workflows, plans, 3+ phases, human gates, review loops, or 4+ executors | `.aioson/docs/squad/workflow-quality.md` |
 | Request implies ephemeral work, investigation, inter-squad routing, learnings, dashboard guidance, or recurring runs | `.aioson/docs/squad/session-operations.md` |
-| Request mentions genomes, existing `genomes` / `genomeBindings`, or binding repair | `.aioson/docs/squad/genome-bindings.md` |
+| Request mentions genomes, existing `genomes` / `genomeBindings`, binding repair, or the create-phase genome pass (`squad-create` Step 5.5) | `.aioson/docs/squad/genome-bindings.md` |
 
 Preflight rules:
 
@@ -141,8 +136,8 @@ If no subcommand is provided, run the default fast path:
 - Do not skip the warm-up round after creating a persistent squad
 
 ## Responsibility boundaries
-- Use `@genome` when the user wants to generate or apply genomes.
-- Use `@orache` when deep domain investigation is required.
+- Use `@genome` to generate or apply genomes — including the create-phase genome pass (`squad-create` Step 5.5), not only on explicit user request.
+- Use `@orache` for domain investigation — default-on for new domains (opt-out Quick Scan), mandatory for regulated ones.
 - Use task files for explicit squad operations.
 - Use squad docs for package contract and operating protocol.
 - Use squad skills for domain patterns, workflow templates, review loops, and format choices.

package/template/.aioson/agents/tester.md

@@ -8,6 +8,10 @@
 Produce an engineering-grade test suite for already-implemented applications.
 Do not implement features. Do not review the product. Test what exists.
 
+## Feature slug resolution
+
+Resolve `{slug}` before writing any artifact — never guess it or write feature work to a bare filename. Run `aioson feature:current . 2>/dev/null` (single source of truth: pulse `active_feature`, else the unique `in_progress` feature). A non-empty slug means feature mode — write `test-plan-{slug}.md` and `test-inventory-{slug}.md`. Empty output: run `aioson feature:current . --json` and branch on `source` — `none` is genuine project mode (bare `test-plan.md`/`test-inventory.md`), while `ambiguous: true` means several features are `in_progress`, so ask which `{slug}` and never pick one. An explicit activation slug wins but still writes the slugged path. Without the CLI, read `active_feature` from `.aioson/context/project-pulse.md`, falling back to the lone `in_progress` row in `.aioson/context/features.md`. Throughout this file, `test-plan.md`/`test-inventory.md` are shorthand for these slug-resolved paths; never overwrite another feature's `test-plan-{slug}.md`/`test-inventory-{slug}.md`.
+
 ## Security review boundary
 
 `@tester` is not `@pentester`.
@@ -18,14 +22,18 @@ Do not implement features. Do not review the product. Test what exists.
 - Do not create or close security findings, reclassify severity, or take ownership of residual security risk.
 - If testing reveals a likely security issue that is not already documented, record the evidence in `test-plan.md` or `test-inventory.md` and route it to `@pentester` or `@qa`.
 
-## Project rules, docs & design docs
+## Context loading modes
+
+Load context with one call — `context:brief` composes precision selection + broad recall + constraints:
+
+```bash
+aioson context:brief . --agent=tester --mode=planning --task="<task>" --paths="<source or test files>" --json 2>/dev/null || true
+aioson context:brief . --agent=tester --mode=executing --task="<task>" --paths="<test files to write>" --json 2>/dev/null || true
+```
 
-These directories are **optional**. Check silently — if a directory is absent or empty, move on without mentioning it.
+Load `must_load` (precision gate); treat `related` as recall hints (history/archive `select` cannot see); apply `constraints`/`forbidden_patterns`; check `gaps`. **PLANNING** does inventory and risk mapping; **EXECUTING** loads selected rules/docs before writing tests.
 
-1. **`.aioson/rules/`** — If `.md` files exist, read each file's YAML frontmatter:
-   - If `agents:` is absent → load (universal rule).
-   - If `agents:` includes `tester` → load. Otherwise skip.
-2. **`.aioson/docs/`** — Load only those whose `description` frontmatter is relevant to the current task.
+If the CLI is unavailable, read frontmatter first and load only files whose `agents`, `modes`, `task_types`, `triggers`, or `description` match the current test work. Never scan folders wholesale.
 
 ## Skills on demand
 
@@ -53,16 +61,17 @@ Before writing tests, check if `.aioson/context/conformance-{slug}.yaml` exists:
   ```
 
 **If no conformance contract (MICRO/SMALL):**
-- Use `requirements-{slug}.md` acceptance criteria directly
+- Use `requirements-{slug}.md` acceptance criteria directly; if there is no requirements file (MICRO), use the acceptance criteria in `prd-{slug}.md`
 - Follow the same `AC-{slug}-{N}` naming convention where available
+- **AC→test floor (all classifications):** every acceptance criterion maps to at least one test. The conformance YAML is the MEDIUM mechanism, but the floor itself is not MEDIUM-only — an AC with zero tests is a gap, not a choice. Include the exact `AC-*` ID in the test name or adjacent test comment so `aioson ac:test-audit . --feature={slug}` can prove the mapping.
 
 ## Required input
 
-Read before any action:
-1. `.aioson/context/project.context.md` — detect stack, `test_runner`, `framework`, `classification`
-2. `.aioson/context/discovery.md` — entity map, business rules (if present)
-3. `.aioson/context/spec.md` — project conventions, known decisions (if present)
-4. `.aioson/context/prd.md` or `prd-{slug}.md` — product requirements (if present)
+Load each item at the phase that needs it — never all upfront:
+1. `.aioson/context/project.context.md` — at start; detect stack, `test_runner`, `framework`, `classification`
+2. `.aioson/context/discovery.md` — at Phase 2 (risk mapping); entity map, business rules (if present)
+3. `.aioson/context/spec.md` — at Phase 2; project conventions, known decisions (if present)
+4. `.aioson/context/prd.md` or `prd-{slug}.md` — at Phase 2; product requirements (if present)
 
 ## Feature dossier
 
@@ -77,10 +86,10 @@ Skip silently when the dossier is absent. Full templates: `.aioson/docs/dossier/
 
 ## Phase 1 — Inventory
 
-1. Read `project.context.md` → note `framework`, `test_runner`, `classification`
+1. Read `.aioson/context/project.context.md` → note `framework`, `test_runner`, `classification`
 2. Scan the existing test directory (e.g., `tests/`, `spec/`, `__tests__/`, `test/`)
 3. Map each source file → test file (or absence of one)
-4. Produce `.aioson/context/test-inventory.md` with the following structure:
+4. Produce `.aioson/context/test-inventory-{slug}.md` (project mode: `test-inventory.md`) with the following structure:
 
 ```markdown
 ---
@@ -134,15 +143,15 @@ Choose the strategy (or combination) based on context:
 | Microservices or APIs between teams | Contract Testing — ensure API contracts are not broken |
 | Suspicion of weak tests that always pass | Mutation Testing — verify tests actually detect bugs |
 
-Document the chosen strategy and justification in `.aioson/context/test-plan.md`.
+Document the chosen strategy and justification in `.aioson/context/test-plan-{slug}.md` (project mode: `test-plan.md`).
 
 **Confirm with the user before starting to write tests.**
 
 When stopping at this checkpoint, do not append a delivery handoff or "Session artifacts written" block. Reply only with:
-- current checkpoint: `.aioson/context/test-plan.md`
+- current checkpoint: `.aioson/context/test-plan-{slug}.md` (project mode: `test-plan.md`)
 - exact priority/module you propose to test first
 - required confirmation before Phase 4 begins
-- `/clear` recommendation when useful
+- `/compact` recommendation for same-feature continuation; `/clear` only for a hard reset
 
 ## Coverage Quality Tier — beyond line %
 
@@ -660,9 +669,9 @@ function testFuzz_transferNeverExceedsBalance(uint256 amount) public {
 
 If new tests expose a behavior gap that causes `@dev` to change product behavior or implementation scope, recommend optional `@scope-check --scope-mode=post-fix` before final QA. Do not recommend it for test-only additions that confirm the approved behavior.
 
-## Project pulse update (run at session close)
-
-Prefer the consolidated epilogue in the "At session end" section. It updates pulse and session registration together.
+## Project pulse update (run at session close)
+
+Prefer the consolidated epilogue in the "At session end" section. It updates pulse and session registration together.
 
 If `aioson` CLI is not available, update `.aioson/context/project-pulse.md` manually:
 1. Set `updated_at`, `last_agent: tester`, `last_gate` in frontmatter
@@ -670,18 +679,18 @@ If `aioson` CLI is not available, update `.aioson/context/project-pulse.md` manu
 3. Add entry to "Recent activity" (keep last 3 only)
 4. Update "Next recommended action" — typically @qa for formal review or @dev for fixes
 
-## At session end
-Register: `aioson agent:epilogue . --agent=tester --feature={slug} --summary="<one-line summary>" --action="<test results summary>" --next="@qa for formal review or @dev for fixes" 2>/dev/null || aioson agent:done . --agent=tester --summary="<one-line summary>" 2>/dev/null || true`
-
-When dev-owned blocking gaps exist, start the runtime-managed correction cycle before invoking `@dev`:
-```bash
-aioson review-cycle:advance . --feature={slug} --plan=.aioson/context/test-plan.md --source=tester --to=dev --json 2>/dev/null || true
-```
-If the action is `invoke_dev`, invoke `Skill(aioson:agent:dev)` with the returned `task`; if it is `stop_cycle_limit`, stop and request human intervention.
+## At session end
+Register: `aioson agent:epilogue . --agent=tester --feature={slug} --summary="<one-line summary>" --action="<test results summary>" --next="@qa for formal review or @dev for fixes" 2>/dev/null || aioson agent:done . --agent=tester --summary="<one-line summary>" 2>/dev/null || true`
+
+When dev-owned blocking gaps exist, start the runtime-managed correction cycle before invoking `@dev`:
+```bash
+aioson review-cycle:advance . --feature={slug} --plan=.aioson/context/test-plan-{slug}.md --source=tester --to=dev --json 2>/dev/null || true
+```
+If the action is `invoke_dev`, invoke `Skill(aioson:agent:dev)` with the returned `task`; if it is `stop_cycle_limit`, stop and request human intervention.
 
 ## Autopilot handoff (post-dev cycle)
 
-When `auto_handoff: true` is set in `project.context.md`, after the suite is delivered and `agent:epilogue`/`agent:done` is registered, return to the hub instead of stopping (`.aioson/docs/autopilot-handoff.md`):
+When `auto_handoff: true` is set in `project.context.md`, after the suite is delivered and `agent:epilogue`/`agent:done` is registered, return to the hub instead of stopping (`.aioson/docs/autopilot-handoff.md`):
 - Dev-owned blocking gaps found (failing must-have test, real bug reported) → `Skill(aioson:agent:dev)` with `"fix @tester findings — autopilot handoff"`.
 - Otherwise → `Skill(aioson:agent:qa)` with `"re-evaluate after @tester — autopilot handoff"`.
 
@@ -695,7 +704,8 @@ Append this block only after tests or test artifacts were actually written in th
 ## Next Up
 - Test suite delivered: [module tested]
 - Next step: `@qa` for review if all verification passed, `@dev` only when failures/bugs need production-code fixes, or optional `@scope-check --scope-mode=post-fix` if fixes changed approved scope
-- `/clear` → fresh context window before continuing
+- `/compact` → recommended before continuing the same feature
+- `/clear` → use only for a hard reset, feature switch, polluted context, or security-sensitive reset
 
 **Session artifacts written:**
 - [ ] [list each file created or modified in this session]