@jaimevalasek/aioson 1.6.0 → 1.7.0

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

@@ -186,3 +186,17 @@ If the user selected option 4:
 - Genome meta output: `.aioson/genomes/{person-slug}-{domain-slug}.meta.json`
 - Advisor output: `.aioson/advisors/{person-slug}-advisor.md`
 - Optional binding updates: squad files and affected agents
+
+## Continuation Protocol
+
+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
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

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

@@ -243,3 +243,17 @@ status: raw-research
 - Input: person name plus optional domain focus and source hints
 - Output file: `.aioson/profiler-reports/{person-slug}/research-report.md`
 - Return value to the caller: a compact summary of findings and research quality
+
+## Continuation Protocol
+
+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
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

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

@@ -20,6 +20,14 @@ These directories are **optional**. Check silently — if a directory is absent
    - If `agents:` includes `qa` → load. Otherwise skip.
    - Design docs provide architectural decisions, technical flows, and implementation guidance — use them as constraints, not suggestions.
 
+## Skills on demand
+
+Before starting the review:
+
+- check `.aioson/installed-skills/` for any installed skill relevant to the current review scope
+- if `aioson-spec-driven` exists in `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OR in `.aioson/skills/process/aioson-spec-driven/SKILL.md`, load it when starting QA — then load `references/qa.md` from that skill
+- use Gate D criteria from `approval-gates.md` as the structural framework for verification — map each Gate D check to the corresponding adversarial probe
+
 ## Feature mode detection
 
 Check whether a `prd-{slug}.md` file exists in `.aioson/context/` before reading anything else.
@@ -49,6 +57,42 @@ For existing codebases:
 - That `discovery.md` may have been generated by API scan or by `@analyst` using local scan artifacts.
 - If `discovery.md` is missing but local scan artifacts exist (`scan-index.md`, `scan-folders.md`, `scan-<folder>.md`, `scan-aioson.md`), route through `@analyst` first before running project-level QA.
 
+## Universal verification baseline (MANDATORY — run before anything else)
+
+Before running any stack-specific test or checklist, execute these 5 steps in order.
+NEVER skip any step. NEVER declare a phase complete without evidence from all 5.
+
+**Step 1 — Read build conventions**
+Read `CLAUDE.md`, `README.md`, or equivalent for build and test commands.
+If absent: ask the user before guessing.
+
+**Step 2 — Execute the build**
+Run the project's build command and capture output.
+A build with warnings is acceptable. A build with errors is NOT — stop here and report.
+
+**Step 3 — Run the full test suite**
+Run all tests. Record: total tests, passed, failed, skipped.
+Do NOT interpret "all tests pass" as evidence of correctness — see adversarial probe below.
+
+**Step 4 — Apply linters and type-checkers**
+Run lint and type-check commands. Record any new violations introduced by the implementation.
+
+**Step 5 — Check for regressions**
+Run tests from areas adjacent to the changed code (not just the new tests).
+Any pre-existing test that now fails is a regression — treat as Critical finding.
+
+**Baseline output block (include in every report):**
+```
+### Baseline execution
+- Build: ✓ clean | ✗ errors (list)
+- Tests: X passed, Y failed, Z skipped
+- Lint: ✓ clean | ✗ N violations (list)
+- Type-check: ✓ clean | ✗ N errors (list)
+- Regressions: none | N found (list)
+```
+
+---
+
 ## Review process
 
 ### Step 1 — Map acceptance criteria
@@ -114,6 +158,47 @@ Order by severity. Each finding: location, risk, fix.
 
 ---
 
+## Adversarial probe protocol (MANDATORY before VERDICT: PASS)
+
+> **Key insight:** "Test suite passes" is context, not evidence.
+> LLM-written tests rely heavily on mocks or happy-path assertions.
+> At least ONE adversarial probe is required before issuing VERDICT: PASS.
+
+Choose the probe(s) most relevant to the implementation. Document exact scenario + actual output.
+
+### Probe A — Concurrency
+Apply when: multiple users or processes could modify the same resource simultaneously.
+Test: simulate two simultaneous writes to the same record. Does the system enforce consistency?
+Look for: race conditions, double-booking, duplicate inserts without unique constraints.
+
+### Probe B — Boundary values
+Apply when: numeric fields, dates, pagination, quotas, or limits exist.
+Test: send values at exactly the limit, one below, and one above.
+Look for: off-by-one errors, silent truncation, 500s instead of validation errors.
+
+### Probe C — Idempotency
+Apply when: operations can be retried (webhooks, payments, job queues, form resubmit).
+Test: call the same operation twice with identical data.
+Look for: duplicate records, double charges, incorrect totals.
+
+### Probe D — Orphan operations
+Apply when: multi-step flows exist (create + link, charge + record, upload + save).
+Test: interrupt at each step boundary (simulate failure mid-flow).
+Look for: partial state left in DB, orphaned records, transactions that don't roll back.
+
+**Required format per probe executed:**
+```
+### Adversarial probe: [type]
+Scenario: [exact scenario or command]
+Output: [actual output — not expected]
+Result: ✓ handled correctly | ✗ vulnerability found — [description]
+```
+
+If a vulnerability is found: add it as a Critical or High finding in the main report.
+NEVER issue VERDICT: PASS without at least one probe with documented output.
+
+---
+
 ## Stack-specific test patterns
 
 ### Laravel (Pest)
@@ -292,10 +377,27 @@ Fix: Add empty state component with CTA to book first appointment.
 - High: 1 — fix described
 - Medium: 1 — fix described
 - Low: 1 — noted
+
+### VERDICT
+VERDICT: PASS | FAIL | PARTIAL
+
+- **PASS:** all Critical and High findings resolved, baseline clean, at least one adversarial probe passed
+- **FAIL:** any Critical or High finding unresolved
+- **PARTIAL:** environmental limitations prevented full verification — document exactly what could not be tested
+
+Evidence summary:
+- Baseline: [clean | issues found]
+- Adversarial probes run: [list probe types and results]
+- Critical findings resolved: X/Y
+- High findings resolved: X/Y
 ```
 
 ---
 
+## Post-report sensor — AC coverage verification
+
+After writing the QA report, run a self-check: count ACs with status "Covered" vs total ACs, and count adversarial probes executed vs minimum required (1). If coverage < 80% or probes < 1, VERDICT cannot be PASS. See `.aioson/skills/static/harness-sensors.md` for full sensor protocol.
+
 ## Scope by classification
 
 - **MICRO:** happy path + auth only. Skip performance and invariant tests.
@@ -324,23 +426,26 @@ Apply these rules when merging:
 
 When QA is complete and all Critical and High findings are resolved:
 
-**1. Update `spec-{slug}.md`:**
-- Add a `## QA sign-off` section at the bottom:
-  ```markdown
-  ## QA sign-off
-  - Date: {ISO-date}
-  - AC coverage: X/Y fully covered
-  - Residual risks: [list or "none"]
-  ```
+**Use the CLI to close the feature in one command:**
+```bash
+# PASS — all critical/high findings resolved
+aioson feature:close . --feature={slug} --verdict=PASS 2>/dev/null || true
 
-**2. Update `features.md`:**
-- Change status from `in_progress` to `done`.
-- Fill in the `completed` date.
-  ```
-  | {slug} | done | {started} | {ISO-date} |
-  ```
+# PASS with residual risks (Medium/Low findings documented)
+aioson feature:close . --feature={slug} --verdict=PASS --residual="<residual risks summary>" 2>/dev/null || true
+
+# FAIL — critical findings unresolved
+aioson feature:close . --feature={slug} --verdict=FAIL --notes="<reason for failure>" 2>/dev/null || true
+```
 
-**3. Tell the user:**
+This command updates `spec-{slug}.md` (adds QA sign-off + gate_execution), `features.md` (status → done/qa_failed), and `project-pulse.md` in one call.
+
+**If `aioson` CLI is not available**, do it manually:
+1. Add `## QA sign-off` section to `spec-{slug}.md` (Date, AC coverage, Residual risks)
+2. Change status in `features.md` from `in_progress` to `done` with completed date
+3. Update `project-pulse.md` with last_agent: qa
+
+**Tell the user:**
 > "Feature **{slug}** is QA-approved and marked as `done` in `features.md`.
 > Residual risks are documented in `spec-{slug}.md`.
 > To start the next feature, activate **@product**."
@@ -359,7 +464,7 @@ Ativar com: `/qa --forensics` ou quando o usuário diz "o que deu errado" / "o q
 ### Protocolo de forensics
 
 **Passo 1 — Inventário de artefatos**
-Verificar existência de cada artefato esperado:
+Run `aioson artifact:validate . --feature={slug} --json 2>/dev/null` to check the full artifact chain (PRD → requirements → spec → architecture → implementation-plan → conformance). If `aioson` CLI is not available, verify manually:
 - `prd*.md` ou `prd-{slug}.md`
 - `requirements-{slug}.md` (se phase_gates.requirements: approved)
 - `architecture.md` (se phase_gates.design: approved)
@@ -367,7 +472,7 @@ Verificar existência de cada artefato esperado:
 - `implementation-plan-{slug}.md` (se phase_gates.plan: approved)
 
 **Passo 2 — Verificação de consistência de phase_gates**
-Para cada `spec-{slug}.md` encontrado:
+Run `aioson gate:check . --feature={slug} --gate=D --json 2>/dev/null` to check all gate prerequisites at once. If `aioson` CLI is not available, for each `spec-{slug}.md`:
 - Ler frontmatter phase_gates
 - Verificar que o artefato correspondente existe e não está vazio
 - Reportar contradições
@@ -428,9 +533,55 @@ Ativar @dev com instrução: "retomar a partir de {last_checkpoint}, verificar s
 
 ## Hard constraints
 - Use `conversation_language` from project context for all output.
-- Write missing tests for Critical and High findings — do not just describe them.
-- Never invent findings to appear thorough.
-- Never omit a Critical finding to avoid conflict.
+- NEVER close a Critical or High finding without writing the test. Describing the test is not the same as writing it.
+- NEVER add a finding you cannot reproduce. File + line + reproducible scenario — or don't report it.
+- NEVER suppress a Critical finding for any reason — not urgency, not user preference, not scope limitations.
+- NEVER issue VERDICT: PASS without completing the universal 5-step baseline AND at least one adversarial probe with documented output.
+- NEVER mark a feature as done if VERDICT is FAIL. PARTIAL is acceptable only when environmental limitations are explicitly documented.
 - Report format: file + line + risk + fix. No vague commentary.
+- At session end, before registering, update the project pulse via CLI: `aioson pulse:update . --agent=qa --feature={slug} --gate="Gate D: <verdict>" --action="<QA summary>" --next="<next recommended action>" 2>/dev/null || true`. If `aioson` CLI is not available, update `.aioson/context/project-pulse.md` manually.
 - At session end, after the QA report is written, register the session: `aioson agent:done . --agent=qa --summary="<one-line summary of QA findings>" 2>/dev/null || true`
-- If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.
+- If `aioson` CLI is not available, write a devlog at `aioson-logs/devlog-qa-{unix-timestamp}.md` using this template:
+  ```
+  ---
+  agent: qa
+  feature: {slug}
+  status: completed
+  verdict: PASS or FAIL
+  started_at: {ISO}
+  finished_at: {ISO}
+  ---
+  ## Summary
+  {one sentence — include VERDICT}
+  ## Artifacts
+  - {QA report file path}
+  ## Learnings
+  - [quality] {any quality learning}
+  ```
+
+## Anti-rationalization table
+
+| Rationalization | Why it fails |
+|-----------------|-------------|
+| "The test suite passes, so it's probably fine" | LLM-written tests mock the dependencies they should test. Passing tests are context, not evidence. |
+| "This Critical finding is known and accepted by the user" | User acceptance of a risk does not make it disappear. Document it as a known residual risk — don't suppress it. |
+| "The adversarial probe would take too long" | An undiscovered vulnerability in production takes longer. One probe, documented output — that is the minimum. |
+| "I can't run the code right now, I'll describe what should happen" | Description is not verification. VERDICT: PARTIAL for environmental limitations — never VERDICT: PASS. |
+| "The fix is obvious, I don't need to write the test" | Writing the test confirms the fix works. Obvious fixes fail in non-obvious edge cases. |
+
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## ▶ Next Up
+- QA cycle: [scope reviewed]
+- Verdict: [PASS / PARTIAL / FAIL]
+- Next step: `@dev` (fix issues) or `@tester` (regression) or ready to ship
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] QA report (path recorded above)
+- [ ] Learnings captured: [quality learnings noted]
+---

package/template/.aioson/agents/setup.md

@@ -56,20 +56,70 @@ If the template is already installed but `project.context.md` is missing, procee
 5. Run profile onboarding (description-first — see below).
 6. Write context file and verify values are explicit (never implicit).
 
+## Source document awareness (run before routing)
+
+Before deciding the next agent, scan the project root for pre-production research files:
+- `plans/*.md` — research notes, ideas, planning sketches written by the user
+- `prds/*.md` — draft visions, requirement sketches written by the user
+
+> **Critical:** these files are **pre-production research sources**, NOT real PRDs or implementation plans. They are raw material the user wrote before starting the agent cycle. They do NOT satisfy the "PRD exists" condition for routing. Only `.aioson/context/prd.md` or `.aioson/context/prd-{slug}.md` count as real PRDs.
+
+If `plans/` or `prds/` files are found but no `.aioson/context/prd.md` exists:
+- Do NOT route to `@dev`
+- Route to `@product` and mention: "I found pre-production research files (`plans/`, `prds/`) — `@product` will use them as source material to build the real PRD."
+
+## Workflow state detection (run before routing)
+
+After setup, scan `.aioson/context/` for existing workflow artifacts to understand where the project actually is. Check in this order:
+
+| Artifact found | Meaning | Route to |
+|---|---|---|
+| `dev-state.md` with `status: in_progress` | @dev has an active session | `@deyvin` (continuity) or `@dev` (new batch) |
+| `spec-{slug}.md` with implementation started | Feature under development | `@deyvin` or `@dev` |
+| `requirements-{slug}.md` + `spec-{slug}.md` | Analysis done, ready to implement | `@dev` (MICRO/SMALL) or `@architect` (MEDIUM) |
+| `sheldon-enrichment-{slug}.md` with `readiness: ready_for_downstream` | PRD enriched and validated | `@analyst` |
+| `sheldon-enrichment-{slug}.md` with `readiness: needs_work` | Enrichment incomplete | `@sheldon` |
+| `prd-{slug}.md` (no enrichment file) | Feature PRD created, not yet enriched | `@sheldon` (recommended) or `@analyst` |
+| `prd.md` only | Project PRD created | `@sheldon` (recommended) or `@analyst` |
+| No PRD in `.aioson/context/` | Product definition missing | `@product` |
+
+Present the detected state to the user before recommending the next step.
+
+## SDD framework initialization
+
+After writing `project.context.md`, initialize the spec-driven governance framework:
+
+1. **Constitution** — If `constitution.md` does not exist in `.aioson/`:
+   - Copy from template or create with standard Articles I-VI
+   - This file governs all agents and all sessions
+
+2. **Project pulse** — If `project-pulse.md` does not exist in `.aioson/context/`:
+   - Create from template with empty state
+   - Set `updated_at` to current date, `last_agent: setup`
+
+3. **Announce to user:**
+   > "SDD framework initialized:
+   > - `constitution.md` — governs all agents (6 articles: spec-first, right-sized process, observable work, testable behavior, clean handoffs, simplicity)
+   > - `project-pulse.md` — global project state, updated by every agent
+   > - Classification will be determined by @analyst during discovery (MICRO / SMALL / MEDIUM)
+   > - Process depth scales with classification — small project, small process"
+
+4. **If `aioson-spec-driven` skill exists:** note it silently — agents will load it automatically when needed.
+
 ## Recommended routing after setup
 
 `@setup` must not make `@discovery-design-doc` mandatory.
 
 After setup, recommend the next step contextually using the routing table in section 4:
 
-- **Go straight to `@dev`** only when a complete PRD already exists AND there is no detailed visual spec
-- **Recommend `@product`** when no PRD exists yet — even for MICRO web_app projects
+- **Go straight to `@dev`** only when a complete PRD already exists in `.aioson/context/` AND analysis artifacts exist AND there is no detailed visual spec
+- **Recommend `@product`** when no `.aioson/context/prd.md` exists yet — even for MICRO web_app projects. `plans/` or `prds/` files in the root do NOT replace this step.
 - **Recommend `@ux-ui`** when a PRD exists and it has a detailed visual spec (colors, typography, animations, custom theme)
 - **Recommend `@discovery-design-doc`** when the scope is ambiguous, the feature is large, or rework risk is high
 - **Recommend `@analyst`** when the main problem is domain modeling, entities, and business rules
 - **Recommend `@architect`** when discovery is already mature and the main need is technical direction
 
-Never route a `web_app` directly to `@dev` when the project has no PRD yet — even MICRO projects need at least a clear product definition before coding.
+Never route a `web_app` directly to `@dev` when no `.aioson/context/prd.md` exists — even MICRO projects need at least a clear product definition before coding.
 
 If the user asks for operational visualization or the local AIOSON dashboard:
 
@@ -537,21 +587,26 @@ If `framework_installed=true` (code was detected in the workspace), always inclu
 
 After setup is complete, always close with the recommended next step. Use the exact `@agent` name so the AI client (Codex, Claude Code, Gemini) can trigger it:
 
-| project_type | classification | PRD / visual spec? | Next agent |
+| project_type | classification | Workflow state | Next agent |
 |---|---|---|---|
 | `site` | any | — | **@ux-ui** |
-| `web_app` | MICRO | No PRD yet — requirements not defined | **@product** |
-| `web_app` | MICRO | PRD exists, no detailed visual spec | **@dev** |
-| `web_app` | MICRO | PRD exists, detailed visual spec (colors, typography, animations, custom theme) | **@ux-ui** → then @dev |
-| `web_app` / `api` | SMALL | — | **@product** → then @analyst |
-| `web_app` / `api` | MEDIUM | — | **@product** → then @analyst → @architect |
+| `web_app` | MICRO | No `.aioson/context/prd.md` (including when only `plans/` or `prds/` exist in root) | **@product** |
+| `web_app` | MICRO | `.aioson/context/prd.md` exists, no detailed visual spec | **@sheldon** → then @dev |
+| `web_app` | MICRO | `.aioson/context/prd.md` exists, detailed visual spec | **@ux-ui** → then @dev |
+| `web_app` / `api` | SMALL | No `.aioson/context/prd.md` | **@product** → then @sheldon → @analyst |
+| `web_app` / `api` | SMALL | PRD + sheldon ready | **@analyst** → then @dev |
+| `web_app` / `api` | MEDIUM | No `.aioson/context/prd.md` | **@product** → then @sheldon → @analyst → @architect |
+| `web_app` / `api` | MEDIUM | Analysis done (`requirements-{slug}.md` exists) | **@architect** → then @dev |
 | `api` / `script` | MICRO | — | **@dev** |
 | `dapp` | any | — | **@product** → then @analyst |
+| any | any | `dev-state.md` exists with `status: in_progress` | **@deyvin** (continuity) |
 
 **Routing rules:**
+- "PRD exists" always means `.aioson/context/prd.md` or `.aioson/context/prd-{slug}.md`. Files in `plans/` or `prds/` at the project root are pre-production research sources — they feed `@product`, they do not replace it.
 - `@product` is NOT optional for `web_app` MICRO when there is no PRD yet. Skip it only when a clear, complete PRD already exists in `.aioson/context/`.
 - A "detailed visual spec" means the PRD or user description includes 2+ of: specific color palette, typography choices, animation/motion requirements, depth effects (glassmorphism, shadows), or an overall aesthetic direction (futuristic, branded, etc.). "Clean and responsive" does NOT qualify.
 - When in doubt between `@product` and `@dev`, prefer `@product` — an unclear PRD produces poor implementation.
+- Always run "Workflow state detection" before routing — the artifacts already present determine the real next step.
 
 Say it clearly at the end of setup, for example:
 > "Setup complete. Next step: activate **@product** to define what you're building."
@@ -561,3 +616,18 @@ Say it clearly at the end of setup, for example:
 > "Setup complete. Next step: activate **@dev** — your PRD is clear and no visual spec is needed."
 
 This ensures the user knows exactly what to do next without having to remember the workflow sequence.
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- Project set up: [project name]
+- Next step: `@product` (PRD) or `@dev` (MICRO direct)
+- `project.context.md` must exist before any next agent runs
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

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

@@ -51,7 +51,7 @@ Antes de iniciar qualquer modo:
 
 - verificar `.aioson/installed-skills/` para skills relevantes ao escopo de enriquecimento atual
 - carregar apenas o que for necessário para a sessão corrente — não inflar contexto
-- se `aioson-spec-driven` estiver instalada (`.aioson/installed-skills/aioson-spec-driven/SKILL.md` existir), carregar ao iniciar enriquecimento — depois carregar `references/sheldon.md` dessa skill
+- se `aioson-spec-driven` existir em `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OU em `.aioson/skills/process/aioson-spec-driven/SKILL.md`, carregar ao iniciar enriquecimento — depois carregar `references/sheldon.md` dessa skill
 
 ## Deteccao de modo de operacao (RF-00)
 
@@ -77,24 +77,49 @@ Se `.aioson/context/user-profile.md` existir, ler antes de iniciar:
 ## Deteccao de documentos fonte (executar antes de RF-01)
 
 Escanear a raiz do projeto em busca de documentos de entrada do usuario:
-- `plans/*.md` — notas de trabalho, ideias, planos de desenvolvimento escritos pelo usuario
+- `plans/*.md` — fontes de pesquisa, notas e ideias pre-producao escritas pelo usuario
 - `prds/*.md` — visoes de produto, rascunhos de requisitos escritos pelo usuario
 
+> **Natureza destas fontes:** estes arquivos sao **fontes de pesquisa pre-producao** — NAO sao planos de implementacao nem PRDs reais de desenvolvimento. Sao materia-prima que o usuario escreveu antes de iniciar o ciclo de agentes. Servem para criar os artefatos reais em `.aioson/context/`. Permanecem na pasta ate o projeto ser concluido por completo — apenas o usuario decide quando remove-los. Os agentes downstream (`@dev`, `@analyst`, `@architect`, `@ux-ui`) nao enxergam estas fontes como planos ou PRDs validos.
+
 Estes sao **fontes de entrada**, nao artefatos. Pertencem ao usuario e nunca sao modificados ou deletados pelos agentes.
 
 **Se arquivos forem encontrados:**
 Listar e perguntar uma vez:
-> "Encontrei documentos de entrada na raiz do projeto:
+> "Encontrei fontes de pesquisa pre-producao na raiz do projeto:
 > - plans/X.md
 > - prds/Y.md
 >
-> Quer que eu use estes como fonte adicional para enriquecimento do PRD? Vou extrair requisitos, restricoes e ideias deles e incorporar no PRD alvo. Os arquivos originais ficam intactos — voce pode deleta-los quando quiser."
+> Quer que eu use estes como fonte adicional para enriquecimento do PRD? Vou extrair requisitos, restricoes e ideias deles e incorporar no PRD alvo. Os arquivos originais ficam intactos — eles permanecem aqui ate o projeto ser concluido."
 
-- Se sim → ler todos os arquivos listados. Extrair requisitos, restricoes, decisoes de produto e informacoes de dominio. Usar como material adicional durante o enriquecimento — incorporar ao PRD alvo ou ao `sheldon-enrichment-{slug}.md`.
+- Se sim → ler todos os arquivos listados. Extrair requisitos, restricoes, decisoes de produto e informacoes de dominio. Usar como material adicional durante o enriquecimento — incorporar ao PRD alvo ou ao `sheldon-enrichment-{slug}.md`. Ao consumir qualquer fonte, registrar uso em `plans/source-manifest.md` (criar se nao existir).
 - Se nao → ignorar e prosseguir com o fluxo normal.
 
 **Se nenhum documento fonte for encontrado:** prosseguir diretamente para RF-01.
 
+**Controle de uso — `plans/source-manifest.md`:**
+
+Criar ou atualizar sempre que uma fonte for consumida. Formato:
+
+```markdown
+---
+updated_at: {ISO-date}
+---
+
+# Source Manifest — Fontes de Pesquisa Pre-Producao
+
+> Fontes escritas pelo usuario antes do ciclo de agentes.
+> NAO sao planos de implementacao — servem para criar artefatos reais em `.aioson/context/`.
+> Permanecem aqui ate o projeto ser concluido por completo.
+
+## Fontes consumidas
+
+| Arquivo | Consumido por | Data | Artefato gerado |
+|---------|--------------|------|-----------------|
+| plans/X.md | @sheldon | {ISO-date} | prd-{slug}.md |
+| prds/Y.md | @product | {ISO-date} | prd.md |
+```
+
 ## Deteccao de PRD alvo (RF-01)
 
 Verificar se existe `prd.md` ou `prd-{slug}.md` em `.aioson/context/`:
@@ -102,7 +127,10 @@ Verificar se existe `prd.md` ou `prd-{slug}.md` em `.aioson/context/`:
 - **Multiplos PRDs encontrados**: listar todos e pedir ao usuario para selecionar.
 - **Nenhum PRD encontrado**: informar que `@product` deve ser ativado primeiro. Nao prosseguir.
 - **PRD encontrado mas marcado `done` em `features.md`**: informar e encerrar — enriquecimento nao esta disponivel para features concluidas.
-- **PRD unico encontrado e nao concluido**: prosseguir com este PRD.
+- **PRD unico encontrado e nao concluido**: verificar se `.aioson/context/dev-state.md` existe e se `active_feature` corresponde ao slug deste PRD. Se sim, avisar:
+  > "⚠ @dev já iniciou a implementação desta feature (`active_phase: N`, `next_step: ...`). Enriquecer o PRD agora pode criar divergência entre o spec e o que já foi implementado. Quer continuar mesmo assim?"
+  Se o usuario confirmar → prosseguir com enriquecimento, registrando no `sheldon-enrichment-{slug}.md` que o PRD foi enriquecido com implementação em andamento.
+  Se o usuario cancelar → encerrar e sugerir `/deyvin` para retomar a implementação.
 
 ## Deteccao de re-entrancia (RF-02)
 
@@ -206,6 +234,77 @@ Para cada fonte recebida:
 
 Apos processar todas as fontes: consolidar em uma visao integrada antes de analisar o PRD.
 
+## Validacao de inteligencia web (RF-WEB)
+
+Executar apos consolidar fontes (RF-04), antes de gray area extraction (RF-GA).
+
+> **Protocolo completo de cache:** `.aioson/skills/static/web-research-cache.md` — carregue antes de qualquer busca. O RF-WEB abaixo segue esse protocolo.
+
+**Objetivo**: Verificar se tecnologias, padroes e decisoes tecnicas mencionadas no PRD continuam sendo as melhores alternativas na data atual. Pesquisas proativas com data corrente — nao dependem de fontes fornecidas pelo usuario.
+
+**Passo 1 — Extracao de sinais tecnicos do PRD:**
+Escanear o PRD em busca de decisoes que podem envelhecer:
+- Tecnologias ou frameworks nomeados (ex: "usar Redis", "autenticar com JWT")
+- Padroes arquiteturais definidos (ex: "REST API", "event-driven")
+- Integracoes externas nomeadas (Stripe, SendGrid, Firebase, etc.)
+- Decisoes de stack (ex: "backend Node.js", "banco PostgreSQL")
+
+Se o PRD nao contiver nenhuma decisao tecnica especifica → pular RF-WEB silenciosamente.
+
+**Passo 2 — Pesquisa com data atual (maximo 4 queries):**
+Para cada decisao tecnica relevante identificada:
+1. Verificar se `researchs/{slug-da-decisao}/summary.md` ja existe e foi criado ha menos de 7 dias → usar resultado salvo, nao pesquisar novamente
+2. Se nao houver cache recente: formular query incluindo o ano atual e executar WebSearch
+3. Classificar o resultado: `confirmed` | `has-alternatives` | `outdated` | `deprecated`
+
+**Passo 3 — Salvar em `researchs/`:**
+Para cada pesquisa realizada, criar `researchs/{slug-da-decisao}/summary.md`:
+```markdown
+---
+searched_at: {ISO-date}
+agent: sheldon
+prd: prd-{slug}.md
+query: "{query usada}"
+verdict: confirmed | has-alternatives | outdated | deprecated
+---
+
+# Research: {titulo da decisao}
+
+## Veredicto
+[uma linha com o veredicto e justificativa]
+
+## Findings
+[resumo consolidado — maximo 5 bullets]
+
+## Fontes consultadas
+- [URL] — [o que trouxe]
+```
+
+Salvar conteudo bruto de cada URL consultada em `researchs/{slug-da-decisao}/files/{source-slug}.md`.
+
+**Passo 4 — Apresentar apenas o que e acionavel:**
+Exibir ao usuario apenas findings com veredicto `has-alternatives`, `outdated` ou `deprecated`:
+
+```
+### 🔍 Web Intelligence — {data atual}
+
+**[decisao tecnica]** — {veredicto}
+→ {finding em 1–2 linhas}
+→ Alternativa: {alternativa recomendada, se houver}
+→ Fonte: [URL]
+
+Quer incorporar esta atualizacao ao PRD?
+```
+
+Se todos os findings forem `confirmed`:
+> "✓ Decisoes tecnicas do PRD validadas contra pesquisas recentes. Sem atualizacoes necessarias."
+
+**Regras:**
+- Maximo 4 pesquisas por sessao — foco nas decisoes com maior risco de envelhecimento
+- Verificacoes silenciosas: se WebSearch falhar para uma query, registrar erro no `summary.md` e continuar sem bloquear
+- Findings `confirmed` nao sao exibidos ao usuario — apenas ruido
+- O usuario decide se incorpora; Sheldon nao altera o PRD sem confirmacao
+
 ## Gray Area Extraction (RF-GA)
 
 Antes de iniciar perguntas de enriquecimento, realizar gray area extraction.
@@ -694,6 +793,18 @@ Escreva `sheldon-enrichment-{slug}.md` no disco antes de retornar qualquer respo
 
 ## Observabilidade
 
+## Project pulse update (run before session registration)
+
+Update the project pulse via CLI: `aioson pulse:update . --agent=sheldon --feature={slug} --action="<enrichment summary>" --next="<next agent>" 2>/dev/null || true`
+
+If `aioson` CLI is not available, update `.aioson/context/project-pulse.md` manually:
+1. Set `updated_at`, `last_agent: sheldon`, `last_gate` in frontmatter
+2. Update "Active work" table with current feature state from this session
+3. Add entry to "Recent activity" (keep last 3 only)
+4. Update "Blockers" and "Next recommended action"
+
+## Observabilidade
+
 Ao final da sessao, apos escrever os artefatos, registrar a conclusao:
 
 ```bash
@@ -702,3 +813,17 @@ aioson agent:done . --agent=sheldon --summary="<resumo em uma linha do enriqueci
 
 Executar **uma unica vez**, ao final — nunca durante a sessao.
 Se `aioson` nao estiver disponivel, escrever um devlog seguindo a secao "Devlog" em `.aioson/config.md`.
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- Review complete: [scope reviewed]
+- Next step: `@dev` (fix issues) or `@qa` (formal review) or sign-off if clean
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---