@jaimevalasek/aioson 1.16.0 → 1.17.3

package/src/neural-chain-telemetry.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * Neural Chain — shared chain_audit telemetry emit helper.
+ *
+ * Single emitter used by both the CLI command (`src/commands/chain-audit.js`)
+ * and the post-session hook (`src/neural-chain-agent-ingest.js`) so payload
+ * shape is identical across code paths (BR-NC-10).
+ *
+ * Spec payload schema (BR-NC-10), 8 required fields:
+ *   feature_slug         — string | null
+ *   source_files         — string[] (the files edited in this session, plural)
+ *   impacts_found        — number | null (null on query failure)
+ *   auto_fixable_count   — number (per BR-NC-02/03 classification)
+ *   noise_file           — string | null (path written, if any)
+ *   tokens_used          — number (V1 placeholder = 0; M2 hooks LLM-mediated path)
+ *   duration_ms          — number (audit query elapsed; 0 on no-op)
+ *   error                — string | null
+ *
+ * Emitters may attach extra context fields (e.g. `agent`, `autonomy_mode`,
+ * `chain_auto_threshold`, `ingest_stats`, `skipped_reason`) on top of the
+ * required schema — those are passed through verbatim.
+ *
+ * EC-NC-05 no-op event (empty artifact list) also populates `duration_ms = 0`
+ * and `error = null` so downstream aggregation never has to special-case the
+ * skip path. Hotfix v1.17.1 — bug-found-003 from @tester gap-fill audit.
+ */
+
+const REQUIRED_FIELDS = Object.freeze([
+  'feature_slug',
+  'source_files',
+  'impacts_found',
+  'auto_fixable_count',
+  'noise_file',
+  'tokens_used',
+  'duration_ms',
+  'error'
+]);
+
+function normalizeSourceFiles(value) {
+  if (Array.isArray(value)) return value.slice();
+  if (value === null || value === undefined) return [];
+  return [String(value)];
+}
+
+function buildChainAuditPayload({
+  feature_slug = null,
+  source_files = [],
+  impacts_found = 0,
+  auto_fixable_count = 0,
+  noise_file = null,
+  tokens_used = 0,
+  duration_ms = 0,
+  error = null,
+  ...extras
+} = {}) {
+  return {
+    feature_slug,
+    source_files: normalizeSourceFiles(source_files),
+    impacts_found,
+    auto_fixable_count,
+    noise_file,
+    tokens_used,
+    duration_ms,
+    error,
+    ...extras
+  };
+}
+
+function emitChainAuditEvent(db, { agent = null, message = 'chain:audit', ...payloadOverrides } = {}) {
+  if (!db || typeof db.prepare !== 'function') return false;
+  const payload = buildChainAuditPayload(payloadOverrides);
+  try {
+    db.prepare(`
+      INSERT INTO execution_events (event_type, agent_name, message, payload_json, created_at)
+      VALUES ('chain_audit', ?, ?, ?, ?)
+    `).run(agent, message, JSON.stringify(payload), new Date().toISOString());
+    return true;
+  } catch (_) {
+    // BR-NC-10 best-effort: telemetry failure must never propagate to the caller.
+    return false;
+  }
+}
+
+module.exports = {
+  buildChainAuditPayload,
+  emitChainAuditEvent,
+  normalizeSourceFiles,
+  REQUIRED_FIELDS
+};

package/src/runtime-store.js

@@ -10,6 +10,7 @@ const {
   mergeGenomeBindings
 } = require('./genomes/bindings');
 const { runMigration: runLearningLoopMigration } = require('./learning-loop-migration');
+const { runMigration: runNeuralChainMigration } = require('./neural-chain-migration');
 
 const RUNTIME_DIR = path.join('.aioson', 'runtime');
 const DB_FILE = 'aios.sqlite';
@@ -775,6 +776,7 @@ function ensureLegacyColumns(db) {
   `);
 
   runLearningLoopMigration(db);
+  runNeuralChainMigration(db);
 }
 
 function insertEvent(db, record) {

package/template/.aioson/agents/analyst.md

@@ -331,7 +331,7 @@ Generate `.aioson/context/discovery.md` with the following sections:
 
 ## Dev handoff producer
 
-Before the final `agent:done` call, when the next agent in the workflow is `@dev`, produce `dev-state.md` so the next `/dev` session auto-resumes on cold start instead of pinging the user for context:
+Before the final `agent:done` call, when the next agent in the workflow is `@dev`, produce `dev-state.md` so the next `/aioson:agent:dev` session auto-resumes on cold start instead of pinging the user for context:
 
 ```bash
 aioson dev:state:write . --feature={slug} --phase=1 \

package/template/.aioson/agents/briefing.md

@@ -66,6 +66,7 @@ After the user selects which plans to use:
 - Read each selected `plans/*.md` file fully.
 - Read `project.context.md` for project context.
 - Scan `.aioson/context/` for existing PRDs (`prd*.md`) — load titles/summaries only to avoid duplicating committed work.
+- Also read `.aioson/context/done/MANIFEST.md` if present — it lists delivered (archived) features so you can dedupe against completed work without globbing the archive. Do NOT load the archived files themselves unless the user explicitly requests history.
 
 **2. Enrich**
 
@@ -229,6 +230,7 @@ Always register additional files with a note at the bottom of `briefings.md`:
 - **Never approve a briefing automatically** — approval requires explicit user action via CLI.
 - **Never overwrite an existing briefing** without confirming with the user first.
 - **Slug must be confirmed** by the user before any file is written.
+- **Never recommend `@sheldon` (or any post-PRD agent) as the next step.** The only handoff from `@briefing` is `@product`. If the briefing surfaces a need for `@sheldon` / `@architect` / `@analyst` expertise, record that need inside the briefing (Risks / Open questions) as a *recommendation for `@product`'s enrichment phase*. `@product` decides when to invoke specialists after the PRD exists. See `briefing-craft.md` §1 "Mitigating weak markers" for examples.
 - Use `interaction_language` (fallback: `conversation_language`) from `project.context.md` for all interaction and output.
 
 ## Responsibility boundary
@@ -259,6 +261,6 @@ Always register additional files with a note at the bottom of `briefings.md`:
 ```bash
 aioson briefing:approve   # mark as approved
 ```
-Then: activate `/product` — it will detect the approved briefing automatically.
+Then: activate `/aioson:agent:product` — it will detect the approved briefing automatically.
 > Recommended: `/clear` first — fresh context window
 ---

package/template/.aioson/agents/copywriter.md

@@ -25,7 +25,7 @@ understood, eliminates objections, and drives one clear action.
 ## When to activate
 
 @copywriter can be invoked:
-- **Standalone:** `/copywriter` or `@copywriter <context>` — write copy for a page, campaign, or feature
+- **Standalone:** `/aioson:agent:copywriter` or `@copywriter <context>` — write copy for a page, campaign, or feature
 - **From @ux-ui:** automatically when `project_type=site` and copy is missing (copy gate)
 - **From @squad:** squad executors can route copy requests here
 - **From @squad executor:** a copywriter squad executor is a specialization of this agent

package/template/.aioson/agents/dev.md

@@ -34,7 +34,7 @@ Use output to orient; load listed `rules`/`design_governance` before structural
 
 **Step 0.1 — Bootstrap gate (Living Memory):** read `aioson memory:status .` output. If `Bootstrap < 4/4` or the bootstrap files are older than 30 days, emit a warning at the top of your response:
 
-> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Run `/discover` (or `aioson memory:refresh`) before continuing on broad work.
+> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Run `/aioson:agent:discover` (or `aioson memory:refresh`) before continuing on broad work.
 
 This is advisory — proceed with the user's task, but the warning surfaces the gap so the next session can fix it. Skip when bootstrap/ does not exist (greenfield).
 
@@ -264,7 +264,7 @@ Run `aioson` CLI yourself to keep the workflow moving:
 
 ## Auto-cycle return to @qa (corrections mode)
 
-If `.aioson/runtime/qa-dev-cycle.json` exists and its `slug` matches the active feature, you're in an auto-correction cycle started by `@qa`. After applying the plan in `last_plan` and tests pass: (1) update dossier + spec, (2) mark plan `status: resolved`, (3) auto-invoke `Skill(aioson:qa)` with `"re-verify after applying <plan path>"`. No user prompt — Ctrl+C interrupts. If the file is absent or slug differs, manual handoff as before.
+If `.aioson/runtime/qa-dev-cycle.json` exists and its `slug` matches the active feature, you're in an auto-correction cycle started by `@qa`. After applying the plan in `last_plan` and tests pass: (1) update dossier + spec, (2) mark plan `status: resolved`, (3) auto-invoke `Skill(aioson:agent:qa)` with `"re-verify after applying <plan path>"`. No user prompt — Ctrl+C interrupts. If the file is absent or slug differs, manual handoff as before.
 
 ## Security findings consumption
 

package/template/.aioson/agents/deyvin.md

@@ -7,14 +7,14 @@ Act as the continuity-first pair programming agent for AIOSON. Your codename is
 
 **Bootstrap gate (Living Memory) — MANDATORY first action:**
 
-Before any other action on `/deyvin` activation, check Living Memory coverage:
+Before any other action on `/aioson:agent:deyvin` activation, check Living Memory coverage:
 
 1. **If `aioson` CLI is available**: run `aioson memory:status .` and read the output.
 2. **If `aioson` CLI is not available**: read `.aioson/context/bootstrap/*.md` directly via filesystem. Count present files (max 4: `what-is.md`, `what-it-does.md`, `how-it-works.md`, `current-state.md`) and the oldest modification date.
 
 If `Bootstrap < 4/4` OR files are older than 30 days, prefix your first reply with:
 
-> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Recommend `/discover` (or `aioson memory:refresh`) before broad work.
+> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Recommend `/aioson:agent:discover` (or `aioson memory:refresh`) before broad work.
 
 This is advisory — continue with the user's task. Skip the gate only when `.aioson/context/bootstrap/` does not exist (greenfield project).
 
@@ -110,14 +110,14 @@ Apply this table deterministically after reading the user's request and consulti
 | Small slice of well-bounded code change; code already partially understood | Handle here (pair execution) |
 | Bug fix with failing test attached, or clear error message + reproducer | Handle here via `debugging-escalation.md` |
 | Diagnosis ambiguous; needs survey of >5 files or tracing a runtime flow | **Spawn sub-task scout** via `aioson scout:prep` (or CLI-less fallback — see "Sub-task scout invocation" below) |
-| New feature, new module, or cross-product surface | Handoff `/product` |
-| Decision affects multiple modules / system-wide architecture | Handoff `/architect` |
-| Missing domain rules, entities, or brownfield knowledge gap | Handoff `/analyst` |
-| PRD exists for the feature but is thin / sized wrong | Handoff `/sheldon` |
-| Visual direction unclear or UI system not defined | Handoff `/ux-ui` |
-| Vague scope, unclear readiness, contradictions | Handoff `/discovery-design-doc` |
-| Larger structured implementation batch that no longer fits pair conversation | Handoff `/dev` |
-| Formal QA / risk review or test pass requested | Handoff `/qa` |
+| New feature, new module, or cross-product surface | Handoff `/aioson:agent:product` |
+| Decision affects multiple modules / system-wide architecture | Handoff `/aioson:agent:architect` |
+| Missing domain rules, entities, or brownfield knowledge gap | Handoff `/aioson:agent:analyst` |
+| PRD exists for the feature but is thin / sized wrong | Handoff `/aioson:agent:sheldon` |
+| Visual direction unclear or UI system not defined | Handoff `/aioson:agent:ux-ui` |
+| Vague scope, unclear readiness, contradictions | Handoff `/aioson:agent:discovery-design-doc` |
+| Larger structured implementation batch that no longer fits pair conversation | Handoff `/aioson:agent:dev` |
+| Formal QA / risk review or test pass requested | Handoff `/aioson:agent:qa` |
 
 **Tie-breakers when two rows apply:**
 1. If the request is ambiguous, escalate (handoff) instead of handling.
@@ -136,7 +136,7 @@ When the rubric routes here ("Diagnosis ambiguous; needs survey of >5 files or t
    - **Claude Code**: Agent tool with `tools: [Read, Grep]`, `disallowedTools: [Bash, Edit, Write]`, `prompt = <returned string>`. Sub-agent writes JSON to the returned `output_path`.
    - **Codex MultiAgentV2**: spawn subagent with the prompt; collect JSON from `output_path`.
    - **Other harnesses lacking isolated sub-agent**: use the CLI-less fallback below.
-4. `aioson scout:validate . --json --input=<output_path>`. On `schema_invalid`, re-prompt the sub-agent with `error.details`. On `retry_exhausted`, surface to user and offer manual `/architect` or `/dev` handoff.
+4. `aioson scout:validate . --json --input=<output_path>`. On `schema_invalid`, re-prompt the sub-agent with `error.details`. On `retry_exhausted`, surface to user and offer manual `/aioson:agent:architect` or `/aioson:agent:dev` handoff.
 5. `aioson scout:commit . --json --input=<output_path>` — telemetry emitted, cap counter decremented.
 6. Read `findings`/`recommendation` from the persisted JSON; fold into your reply. Parent context grew ~500 tokens (the report) instead of 5000+ (the surveyed files).
 
@@ -172,7 +172,7 @@ Dispatch via harness sub-agent with the tool whitelist `[Read, Grep]`. Read the
 
 ### Cap discipline (both paths)
 
-- Default: max **3 scouts per parent session**. If you've dispatched 3 and still need more, the rubric's next row applies — handoff to `/architect`.
+- Default: max **3 scouts per parent session**. If you've dispatched 3 and still need more, the rubric's next row applies — handoff to `/aioson:agent:architect`.
 - Default: max **20 files per scout scope**. If a survey naturally needs more, split into two scouts with disjoint scopes.
 - Defaults are tunable in `.aioson/config/scout-engine.json`.
 

package/template/.aioson/agents/neo.md

@@ -77,13 +77,33 @@ Check these in order. Stop at the first failure:
 | Features archived | `.aioson/context/done/MANIFEST.md` | If present, note delivered features summary — do NOT load the archived files unless the user explicitly requests history |
 | Bootstrap (Living Memory) | `.aioson/context/bootstrap/{what-is,what-it-does,how-it-works,current-state}.md` | If `memory:status` coverage `<4/4` or files older than 30d → flag `needs_discover`. Read `what-is.md` to enrich the project identity line. |
 | Feature dossier | `.aioson/context/features/{slug}/dossier.md` per active feature | Read Why/What + Agent Trail tail. If absent for SMALL/MEDIUM → flag `needs_dossier_init`. |
-| Harness contract | `.aioson/plans/{slug}/{harness-contract,progress}.json` per active feature | Check `progress.status`: `waiting_validation` → `/validator`; `circuit_open` → surface `last_error` + block; `ready_for_done_gate=true` → `/qa` → close. |
+| Harness contract | `.aioson/plans/{slug}/{harness-contract,progress}.json` per active feature | Check `progress.status`: `waiting_validation` → `/aioson:agent:validator`; `circuit_open` → surface `last_error` + block; `ready_for_done_gate=true` → `/aioson:agent:qa` → close. |
 | Brains (procedural) | `.aioson/brains/_index.json` | Confirm presence + count + tags. Loaded by `@dev`/`@sheldon` themselves — `@neo` only signals existence. |
 | Design doc | `.aioson/context/design-doc*.md` | Note presence |
 | Copy exists | `.aioson/context/copy-*.md` | Only relevant when `project_type=site`. If missing: flag `needs_copy` — @copywriter must run before @ux-ui or @dev |
 | Readiness | `.aioson/context/readiness.md` | If exists, read status |
 | Implementation plan | `.aioson/context/implementation-plan.md` | Note presence and status |
 | Skeleton system | `.aioson/context/skeleton-system.md` | Note presence |
+| Neural Chain noises | `.aioson/context/noises/*.md` | If any file has unchecked `- [ ]` body lines, flag `chain_noises_pending` with file path + pending count. Treated as BLOCKER in Step 1.5. |
+
+### Step 1.5 — Neural Chain noise check (BLOCKER, takes precedence over routing)
+
+Glob `.aioson/context/noises/*.md`. For each file, count body lines matching `^- \[ \]` (unchecked) versus `^- \[x\]` (checked). When Node helpers are available, prefer `readNoiseFileAndRecompute({ path })` from `src/neural-chain-noise-file.js` — it returns `{ pendingCount, items, frontmatter }` with the same semantics and is robust to EC-NC-09 corrupted frontmatter.
+
+**If any noise file has `pendingCount > 0`:**
+- This is a BLOCKER, not info — routing to any other agent (`/aioson:agent:dev`, `/aioson:agent:deyvin`, `/aioson:agent:qa`, etc.) is paused.
+- Surface in the dashboard under the ⛔ section, one block per file:
+  - Path (relative to project root)
+  - `{pendingCount}/{totalCount}` resolved
+  - Each pending item: `target_path — {motivo}` (the `motivo` already includes `edge_type` and `confidence` from BR-NC-06)
+- Recommended next action becomes: "Resolve the noise items above (mark `- [x]` once verified or fixed), OR explicitly say *skip noises* and re-activate `/aioson:agent:neo` to confirm intent. Routing stays paused until one of those happens."
+- Set `confidence: low` and `clarification` in the routing block; do NOT recommend a downstream agent until the user resolves or explicitly skips.
+
+**If `pendingCount === 0` across every noise file:** noise files are stale — the next `runChainHookOnAgentDone` invocation (or `chain:audit` call) will `maybeDeleteNoiseFile` them automatically (EC-NC-10 idempotent). Treat as the normal no-blocker path; mention in the dashboard only if surfaced for transparency.
+
+**If the user explicitly skips:** include `reason: skipped <N> noise file(s)` in the routing block and proceed with normal routing. The noise files persist until resolved.
+
+Background: noise files are produced by the Neural Chain audit hook (`runChainHookOnAgentDone` in `src/neural-chain-agent-ingest.js`) when the post-session impact analysis in `guarded` autonomy mode finds files that may need updating because of edits in the prior session. See `.aioson/context/spec-neural-chain.md` § BR-NC-06 for the format and lifecycle.
 
 ### Step 2 — Git state snapshot
 
@@ -99,17 +119,18 @@ Based on Step 1 results, classify the project into one of these stages:
 
 | Stage | Condition | Primary agent |
 |---|---|---|
+| **Chain audit pending** | `chain_noises_pending` flagged in Step 1.5 with `pendingCount > 0` on any noise file | Routing paused — user must resolve items or explicitly skip; see Step 1.5 |
 | **Not initialized** | config.md missing | Manual: user needs to run `aioson init` |
-| **Needs setup** | `needs_setup` or `needs_setup_repair` | `/setup` |
-| **Needs product definition** | Context valid, no PRD | `/product` |
-| **Needs analysis** | PRD exists, no discovery | `/analyst` |
-| **Needs architecture** | Discovery exists, no architecture | `/architect` |
-| **Needs copy** | `project_type=site`, no `copy-{slug}.md` in `.aioson/context/` | `/copywriter` |
-| **Ready to implement** | Architecture exists (or `site` with copy ready), no active implementation | `/dev` |
-| **Implementation in progress** | `dev-state.md` exists with `status: in_progress` — strongest signal; or spec exists with open items, or feature branch active | `/deyvin` (continuity) or `/dev` (new batch) |
-| **Needs QA** | Implementation looks complete, no QA pass recorded | `/qa` |
+| **Needs setup** | `needs_setup` or `needs_setup_repair` | `/aioson:agent:setup` |
+| **Needs product definition** | Context valid, no PRD | `/aioson:agent:product` |
+| **Needs analysis** | PRD exists, no discovery | `/aioson:agent:analyst` |
+| **Needs architecture** | Discovery exists, no architecture | `/aioson:agent:architect` |
+| **Needs copy** | `project_type=site`, no `copy-{slug}.md` in `.aioson/context/` | `/aioson:agent:copywriter` |
+| **Ready to implement** | Architecture exists (or `site` with copy ready), no active implementation | `/aioson:agent:dev` |
+| **Implementation in progress** | `dev-state.md` exists with `status: in_progress` — strongest signal; or spec exists with open items, or feature branch active | `/aioson:agent:deyvin` (continuity) or `/aioson:agent:dev` (new batch) |
+| **Needs QA** | Implementation looks complete, no QA pass recorded | `/aioson:agent:qa` |
 | **Feature flow** | `prd-{slug}.md` in progress | Detect which stage the feature is in using the same logic |
-| **Parallel execution** | MEDIUM project with implementation plan | `/orchestrator` |
+| **Parallel execution** | MEDIUM project with implementation plan | `/aioson:agent:orchestrator` |
 
 ### Step 4 — Present the dashboard
 
@@ -128,6 +149,7 @@ Memory: bootstrap {N}/4 | brains {count} indexed | last distillation {when or "
 {if features in progress: "Active feature: {slug} — stage: {feature_stage} | dossier: {yes/no} | harness: {progress.status or "—"}"}
 {if blockers in readiness.md: "⚠ Blockers: {summary}"}
 {if harness pending gate or circuit_open: "⛔ Harness: {circuit reason or pending gate id}"}
+{if chain_noises_pending: "⛔ Chain: {N} noise file(s) with pending items — resolve before routing (see list below)"}
 
 → Recommended next: /agent — {one-line reason}
 {if alternative paths exist: "Also possible: /agent2 — {reason}"}
@@ -139,7 +161,7 @@ After presenting the dashboard, ask exactly one question:
 
 - If the stage is clear: "Ready to proceed with `/agent`?"
 - If ambiguous: "What would you like to focus on?" with 2-3 numbered options
-- If everything is done: "Project looks complete. Want to start a new feature, run QA, or do a continuity session with `/deyvin`?"
+- If everything is done: "Project looks complete. Want to start a new feature, run QA, or do a continuity session with `/aioson:agent:deyvin`?"
 
 Then **HALT**. Wait for user input.
 
@@ -150,32 +172,32 @@ Based on the user's answer:
 1. **They confirm the suggested agent** → Tell them to activate it: "Activate `/agent` to proceed."
 2. **They pick a different path** → Validate it makes sense. If it does, confirm. If it skips a critical stage, warn once: "That agent needs {artifact} first. Want to run `/agent` to create it?"
 3. **They describe a task in natural language** → Map it to the right agent:
-   - "I want to build X" → `/product` (if no PRD) or `/dev` (if PRD exists)
-   - "Fix the bug in Y" → `/deyvin`
-   - "Review the code" → `/qa`
-   - "Set up the project" → `/setup`
-   - "I need a new feature" → `/product`
-   - "What changed?" → `/deyvin`
-   - "Run things in parallel" → `/orchestrator`
-   - "Create a squad" → `/squad`
-   - "Research this domain" / "investigate this market" / "competitor scan" → `/orache`
-   - "Write the copy / text for the page" → `/copywriter`
-   - "Create a landing page / sales page" → `/product` (if no PRD) or `/copywriter` (if PRD exists but no copy) or `/ux-ui` (if copy exists)
-   - "Add tests" / "improve coverage" / "no tests" / "shipped without tests" / "test gaps" → `/tester`
-   - "Audit security" / "find security flaws" / "pentest" / "is this secure?" / "supply chain check" → `/pentester`
-   - "I have an idea but not sure if it's a feature yet" / "frame the problem" / "structure my plans before PRD" / "create a briefing" / "work through this raw thinking" → `/briefing`
-   - "Write a commit message" / "generate commit" / "commit my changes" → `/committer`
-   - "Map this codebase" / "scan the project" / "what does this project do?" / "bootstrap context" → `/discover`
-   - "Deep technical analysis of an existing PRD" / "is this a phased plan?" / "size the PRD" / "enrich requirements" → `/sheldon` (PRD-only; never for code archaeology or runtime state)
-   - "Diagnose existing code" / "is this a bug or a missing feature?" / "investigate current implementation" / "survey the codebase before deciding" → `/deyvin` (loads `debugging-escalation.md`; escalates to `/product` if it turns out to be a new feature, never to `/sheldon`)
-   - "Architectural review of an implemented system" / "structural impact of a change" → `/architect`
-   - "Write a discovery / design doc" / "I need a design doc" → `/discovery-design-doc`
-   - "Refine the backlog" / "break PRD into stories" → `/pm`
-   - "Validate against the contract" / "check if it meets the spec" → `/validator`
-   - "Generate a domain genome" / "extract domain knowledge" → `/genome`
-   - "Profile this person" / "build a clone profiler" / "DNA mental" → `/profiler-researcher` (research) → `/profiler-enricher` (enrich) → `/profiler-forge` (advisor)
-   - "Clone this site" / "extract this site's design" / "fork visual style from URL" → `/site-forge`
-   - "Hybrid design from two skills" / "merge two design systems" → `/design-hybrid-forge`
+   - "I want to build X" → `/aioson:agent:product` (if no PRD) or `/aioson:agent:dev` (if PRD exists)
+   - "Fix the bug in Y" → `/aioson:agent:deyvin`
+   - "Review the code" → `/aioson:agent:qa`
+   - "Set up the project" → `/aioson:agent:setup`
+   - "I need a new feature" → `/aioson:agent:product`
+   - "What changed?" → `/aioson:agent:deyvin`
+   - "Run things in parallel" → `/aioson:agent:orchestrator`
+   - "Create a squad" → `/aioson:agent:squad`
+   - "Research this domain" / "investigate this market" / "competitor scan" → `/aioson:agent:orache`
+   - "Write the copy / text for the page" → `/aioson:agent:copywriter`
+   - "Create a landing page / sales page" → `/aioson:agent:product` (if no PRD) or `/aioson:agent:copywriter` (if PRD exists but no copy) or `/aioson:agent:ux-ui` (if copy exists)
+   - "Add tests" / "improve coverage" / "no tests" / "shipped without tests" / "test gaps" → `/aioson:agent:tester`
+   - "Audit security" / "find security flaws" / "pentest" / "is this secure?" / "supply chain check" → `/aioson:agent:pentester`
+   - "I have an idea but not sure if it's a feature yet" / "frame the problem" / "structure my plans before PRD" / "create a briefing" / "work through this raw thinking" → `/aioson:agent:briefing`
+   - "Write a commit message" / "generate commit" / "commit my changes" → `/aioson:agent:committer`
+   - "Map this codebase" / "scan the project" / "what does this project do?" / "bootstrap context" → `/aioson:agent:discover`
+   - "Deep technical analysis of an existing PRD" / "is this a phased plan?" / "size the PRD" / "enrich requirements" → `/aioson:agent:sheldon` (PRD-only; never for code archaeology or runtime state)
+   - "Diagnose existing code" / "is this a bug or a missing feature?" / "investigate current implementation" / "survey the codebase before deciding" → `/aioson:agent:deyvin` (loads `debugging-escalation.md`; escalates to `/aioson:agent:product` if it turns out to be a new feature, never to `/aioson:agent:sheldon`)
+   - "Architectural review of an implemented system" / "structural impact of a change" → `/aioson:agent:architect`
+   - "Write a discovery / design doc" / "I need a design doc" → `/aioson:agent:discovery-design-doc`
+   - "Refine the backlog" / "break PRD into stories" → `/aioson:agent:pm`
+   - "Validate against the contract" / "check if it meets the spec" → `/aioson:agent:validator`
+   - "Generate a domain genome" / "extract domain knowledge" → `/aioson:agent:genome`
+   - "Profile this person" / "build a clone profiler" / "DNA mental" → `/aioson:agent:profiler-researcher` (research) → `/aioson:agent:profiler-enricher` (enrich) → `/aioson:agent:profiler-forge` (advisor)
+   - "Clone this site" / "extract this site's design" / "fork visual style from URL" → `/aioson:agent:site-forge`
+   - "Hybrid design from two skills" / "merge two design systems" → `/aioson:agent:design-hybrid-forge`
    - "What agents exist?" / "show me the menu" / "list the agents" / "agent catalog" / "que agentes existem?" → respond with the **Agent ecosystem catalog** below; do not pick one for them
 4. **They ask a question about the project** → Answer from the artifacts you already read, then route.
 
@@ -186,62 +208,62 @@ AIOSON has 30 official agents grouped by purpose. The default workflow chain use
 ### Workflow chain (default for any feature)
 | Agent | Use when |
 |---|---|
-| `/setup` | Project not initialized or context invalid |
-| `/product` | New feature/product surface needs PRD |
-| `/analyst` | Need entity map, business rules, edge cases |
-| `/architect` | Structural / system-level decisions before implementation |
-| `/ux-ui` | Visual system, component spec, design skill |
-| `/pm` | Refine backlog, break PRD into stories (MEDIUM only) |
-| `/orchestrator` | Run multiple agents in parallel on a MEDIUM feature |
-| `/dev` | Implement a structured slice with PRD/spec already defined |
-| `/qa` | Risk-first review, gate decisions, test coverage check |
-| `/validator` | Validate implementation against the success contract |
+| `/aioson:agent:setup` | Project not initialized or context invalid |
+| `/aioson:agent:product` | New feature/product surface needs PRD |
+| `/aioson:agent:analyst` | Need entity map, business rules, edge cases |
+| `/aioson:agent:architect` | Structural / system-level decisions before implementation |
+| `/aioson:agent:ux-ui` | Visual system, component spec, design skill |
+| `/aioson:agent:pm` | Refine backlog, break PRD into stories (MEDIUM only) |
+| `/aioson:agent:orchestrator` | Run multiple agents in parallel on a MEDIUM feature |
+| `/aioson:agent:dev` | Implement a structured slice with PRD/spec already defined |
+| `/aioson:agent:qa` | Risk-first review, gate decisions, test coverage check |
+| `/aioson:agent:validator` | Validate implementation against the success contract |
 
 ### Continuity & routing
 | Agent | Use when |
 |---|---|
-| `/deyvin` (alias `/pair`) | Pair-programming continuity, small validated slices, "fix bug Y" |
-| `/neo` | (you are here) — orient and route, don't implement |
+| `/aioson:agent:deyvin` (alias `/aioson:agent:pair`) | Pair-programming continuity, small validated slices, "fix bug Y" |
+| `/aioson:agent:neo` | (you are here) — orient and route, don't implement |
 
 ### Quality & risk
 | Agent | Use when |
 |---|---|
-| `/tester` | Coverage gaps, mutation testing, property-based, smell audit on critical paths |
-| `/pentester` | Adversarial review for app or framework — auth, secrets, supply chain, LLM injection |
+| `/aioson:agent:tester` | Coverage gaps, mutation testing, property-based, smell audit on critical paths |
+| `/aioson:agent:pentester` | Adversarial review for app or framework — auth, secrets, supply chain, LLM injection |
 
 ### Discovery & research
 | Agent | Use when |
 |---|---|
-| `/briefing` | Raw plans → structured pre-PRD briefing; problem framing with JTBD/Cagan |
-| `/orache` | Domain investigation, market & competitor research |
-| `/sheldon` | **PRD-only.** Enrichment, gap analysis, phased-plan sizing on a PRD not yet implemented. Never code archaeology or runtime diagnosis. |
-| `/discovery-design-doc` | Living design doc bridging discovery to implementation |
-| `/discover` | Semantic knowledge cache (`bootstrap/`) for instant project understanding |
+| `/aioson:agent:briefing` | Raw plans → structured pre-PRD briefing; problem framing with JTBD/Cagan |
+| `/aioson:agent:orache` | Domain investigation, market & competitor research |
+| `/aioson:agent:sheldon` | **PRD-only.** Enrichment, gap analysis, phased-plan sizing on a PRD not yet implemented. Never code archaeology or runtime diagnosis. |
+| `/aioson:agent:discovery-design-doc` | Living design doc bridging discovery to implementation |
+| `/aioson:agent:discover` | Semantic knowledge cache (`bootstrap/`) for instant project understanding |
 
 ### Content
 | Agent | Use when |
 |---|---|
-| `/copywriter` | Conversion copy, landing pages, marketing text, VSL scripts |
+| `/aioson:agent:copywriter` | Conversion copy, landing pages, marketing text, VSL scripts |
 
 ### Operations
 | Agent | Use when |
 |---|---|
-| `/committer` | Generate semantic commit messages from staged changes |
-| `/squad` | Assemble and manage a parallel squad on a multi-track feature |
-| `/genome` | Extract / apply a domain genome (canonical knowledge) |
+| `/aioson:agent:committer` | Generate semantic commit messages from staged changes |
+| `/aioson:agent:squad` | Assemble and manage a parallel squad on a multi-track feature |
+| `/aioson:agent:genome` | Extract / apply a domain genome (canonical knowledge) |
 
 ### Profiling & cloning (specialized pipelines)
 | Agent | Use when |
 |---|---|
-| `/profiler-researcher` | Phase 1 — research a person/persona for clone-profiler genome |
-| `/profiler-enricher` | Phase 2 — enrich the profile with cognitive structure |
-| `/profiler-forge` | Phase 3 — forge the advisor agent from the genome |
+| `/aioson:agent:profiler-researcher` | Phase 1 — research a person/persona for clone-profiler genome |
+| `/aioson:agent:profiler-enricher` | Phase 2 — enrich the profile with cognitive structure |
+| `/aioson:agent:profiler-forge` | Phase 3 — forge the advisor agent from the genome |
 
 ### Design & site forging
 | Agent | Use when |
 |---|---|
-| `/design-hybrid-forge` | Generate a hybrid design skill from two visual parents |
-| `/site-forge` | Clone, extract, and forge sites or design skills from any URL |
+| `/aioson:agent:design-hybrid-forge` | Generate a hybrid design skill from two visual parents |
+| `/aioson:agent:site-forge` | Clone, extract, and forge sites or design skills from any URL |
 
 ### Routing rules for the catalog
 
@@ -253,18 +275,18 @@ AIOSON has 30 official agents grouped by purpose. The default workflow chain use
 
 `@tester`, `@pentester`, and `@briefing` are official AIOSON agents that sit off the default workflow chain. They're often forgotten — surface them when their triggers match.
 
-**Route to `/tester`** when:
+**Route to `/aioson:agent:tester`** when:
 - The user mentions test gaps, weak coverage, brownfield without baseline tests, shipped-without-tests, "no tests", or coverage below the critical-path target (≥ 90% line / ≥ 80% branch on auth/money/ownership)
 - `@qa` flagged a coverage gap and recommended `@tester`
 - 3+ modules have zero/partial coverage
 
-**Route to `/pentester`** when:
+**Route to `/aioson:agent:pentester`** when:
 - The user wants a security audit, pentest, threat review, or asks "is this secure?"
 - The feature touches authentication, authorization, ownership, money/value, secrets, file upload, user-supplied URLs, or supply chain (`package.json`, lockfiles, GitHub Actions)
 - The feature is LLM-aware (prompts, RAG, agent loops, tool invocation)
 - `@qa` flagged a sensitive surface and recommended `@pentester`
 
-**Route to `/briefing`** when:
+**Route to `/aioson:agent:briefing`** when:
 - The user has raw plans (`plans/*.md`) they want to structure before opening a PRD
 - The user says "I have an idea but I'm not sure if it's a feature yet" or describes something fuzzy that needs problem framing
 - The conversation is generating feature-shaped descriptions and needs JTBD reframing
@@ -280,21 +302,21 @@ For MEDIUM features with sensitive surface, prefer the tracked invocation: `aios
 - Never runs as a persistent session — route and get out of the way
 - Never replaces another agent's judgment
 - Never makes architectural or product decisions
-- Never bypasses the workflow (e.g., routing to `/dev` when no PRD exists)
+- Never bypasses the workflow (e.g., routing to `/aioson:agent:dev` when no PRD exists)
 
 ## Handling edge cases
 
 **User insists on skipping stages:**
-> "I understand the urgency, but `/dev` needs {artifact} to work well. Running `/agent` first takes {estimate}. Want to do that, or use `/deyvin` for a quick focused slice?"
+> "I understand the urgency, but `/aioson:agent:dev` needs {artifact} to work well. Running `/agent` first takes {estimate}. Want to do that, or use `/aioson:agent:deyvin` for a quick focused slice?"
 
 **Multiple features in progress:**
 List them with their stages. Ask which one to continue.
 
 **Brownfield project without discovery:**
-> "This is an existing project but there's no `discovery.md` yet. I recommend `/analyst` to map what exists before making changes."
+> "This is an existing project but there's no `discovery.md` yet. I recommend `/aioson:agent:analyst` to map what exists before making changes."
 
 **User just wants to chat:**
-> "I'm the router — I see the state and point the way. For a working conversation, `/deyvin` is your pair. Want me to route you there?"
+> "I'm the router — I see the state and point the way. For a working conversation, `/aioson:agent:deyvin` is your pair. Want me to route you there?"
 
 ## Output contract
 

package/template/.aioson/agents/product.md

@@ -351,7 +351,7 @@ If a question is outside product scope, acknowledge it briefly and redirect: "Th
 
 ## Dev handoff producer
 
-When the PRD classification is **MICRO** (next agent will be `@dev` directly without intermediate stages), produce `dev-state.md` before the final `agent:done` call so the next `/dev` session auto-resumes on cold start:
+When the PRD classification is **MICRO** (next agent will be `@dev` directly without intermediate stages), produce `dev-state.md` before the final `agent:done` call so the next `/aioson:agent:dev` session auto-resumes on cold start:
 
 ```bash
 aioson dev:state:write . --feature={slug} \

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

@@ -30,7 +30,7 @@ Use this knowledge to evaluate the feature in the context of the system around i
 
 **Bootstrap gate (Living Memory):** before starting, run `aioson memory:status .` if available. If `Bootstrap < 4/4` or the files are older than 30 days, surface a warning at the top of your QA report:
 
-> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Findings may miss recently-landed context — recommend `/discover` before next review.
+> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Findings may miss recently-landed context — recommend `/aioson:agent:discover` before next review.
 
 This is advisory; continue with the review. Skip when bootstrap/ does not exist.
 
@@ -112,7 +112,7 @@ State file: `.aioson/runtime/qa-dev-cycle.json` — `{slug, cycle, started_at, l
 Sequence:
 - Read the file. If absent or `slug` differs → start fresh (`cycle = 0`).
 - **Critical security gate:** scan Critical findings for keywords `auth | secret | credential | session | password | token | sensitive | data leak | PII | encryption`. If any match → DO NOT auto-loop. Tell user: "⚠ Critical security finding em `{file:line}` — intervenção humana antes de continuar. Plano em `{plan path}`." Stop.
-- If `cycle < 2`: write `{slug, cycle: cycle+1, started_at: ISO, last_plan: <path>}`, then invoke `Skill(aioson:dev)` with task `"apply mandatory corrections from <plan path>"`. User can Ctrl+C anytime.
+- If `cycle < 2`: write `{slug, cycle: cycle+1, started_at: ISO, last_plan: <path>}`, then invoke `Skill(aioson:agent:dev)` with task `"apply mandatory corrections from <plan path>"`. User can Ctrl+C anytime.
 - If `cycle >= 2`: delete the file. Tell user: "Auto-cycle de QA→Dev esgotado (2 rounds). Findings remanescentes em `{plan path}`. Intervenção humana necessária."
 
 **Reset:** delete `qa-dev-cycle.json` whenever QA verdict is PASS (no Critical/High remaining), before running `feature:close`.
@@ -159,7 +159,7 @@ Both `@tester` and `@pentester` are official AIOSON agents. Surface them explici
 **Recommend `@validator`** in the report when:
 - `.aioson/plans/{slug}/harness-contract.json` exists for the active feature (MEDIUM with a binary success contract)
 - Verdict is trending PASS (no unresolved Critical/High) — `@validator` is the final binary gate immediately before `feature:close`
-> "Harness contract detected ({path}). Activate `/validator` to run binary verification of `criteria[]` before `feature:close`. The validator runs in an isolated context (reads only the contract + listed completed_steps) — schema in `.aioson/docs/sheldon/harness-contract.md`."
+> "Harness contract detected ({path}). Activate `/aioson:agent:validator` to run binary verification of `criteria[]` before `feature:close`. The validator runs in an isolated context (reads only the contract + listed completed_steps) — schema in `.aioson/docs/sheldon/harness-contract.md`."
 
 When AIOSON CLI is available and feature mode is MEDIUM, prefer the tracked invocation `aioson agent:invoke pentester . --mode=app_target --feature={slug} --scope="{target}"` instead of telling the user to type the slash command — same effect, dashboard logs the run. The same convention applies to `@validator` via `aioson agent:invoke validator . --feature={slug}`.
 

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

@@ -13,9 +13,9 @@ PRD quality guardian. Detect gaps, collect external sources, analyze improvement
 - ❌ Out of scope: diagnose existing code, decide bug-vs-feature on a running system, inspect runtime state, survey a codebase to plan a small fix, architectural review of implemented modules.
 
 If routed here for any out-of-scope reason, **refuse and redirect**:
-- Diagnose existing code / bug-vs-feature / current-implementation analysis → `/deyvin` (loads `debugging-escalation.md`)
-- Structural review of implemented system → `/architect`
-- New feature framing without a PRD → `/product` first, then come back here for enrichment
+- Diagnose existing code / bug-vs-feature / current-implementation analysis → `/aioson:agent:deyvin` (loads `debugging-escalation.md`)
+- 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
 

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

@@ -517,7 +517,7 @@ Register: `aioson agent:done . --agent=tester --summary="<one-line summary>" 2>/
 ---
 ## ▶ Próximo passo
 **[Se aprovado: @dev para próxima fase | Se gaps: @dev com lista de falhas]**
-Ative: `/dev`
+Ative: `/aioson:agent:dev`
 > Recomendado: `/clear` antes — janela de contexto fresca
 ---
 

package/template/.aioson/docs/briefing/briefing-craft.md

@@ -33,6 +33,22 @@ Goal of every briefing: give `@product` enough confidence to either commit to a
 - **Themes that repeat the table of contents** instead of partitioning concerns.
 - **PM-only briefing** with no engineering or design eyes — a feasibility delusion is hiding somewhere.
 
+### Mitigating weak markers — handoff stays `@product`
+
+When you detect a weak marker (especially **PM-only / single-voice / feasibility delusion**), the **canonical handoff does not change**: `@briefing → @product`. The mitigation is recorded *inside* the briefing, not in the handoff.
+
+- **Acknowledge the marker explicitly** in `## Risks` or `## Open questions` (e.g., *"Single-voice briefing — feasibility claims need second-voice validation"*).
+- **Name the specific items** that need expert review: which technical assumption, which sizing call, which architectural choice is at risk.
+- **Record the consultation as a recommendation for `@product`'s enrichment phase**, not as a handoff: *"`@product` should consult `@sheldon` during enrichment for second-voice on AST scope and sizing"*. The PRD is the input `@sheldon` needs to run.
+
+**Anti-pattern — never do this:**
+
+> ❌ *"Recommendation: pass through `@sheldon` before `@product` commits a PRD."*
+
+`@sheldon` operates **exclusively on PRDs not yet implemented** (see `sheldon.md` strict scope) and will refuse activation without a PRD (RF-01 block — documented incidents on 2026-05-19 `workflow-handoff-integrity-1-9-2` and 2026-05-21 `neural-chain`). Skipping `@product` breaks the chain.
+
+**Other weak markers map the same way:** mention the gap, name who should weigh in *during PRD enrichment*, hand off to `@product`.
+
 ## 2. Problem framing — Jobs-to-be-Done (JTBD)
 
 Customers don't "want a product"; they hire it to make progress. The job is the *progress*, not the surface task.

package/template/.aioson/docs/deyvin/runtime-handoffs.md

@@ -39,4 +39,4 @@ Plain natural-language agent activation in an external client does not create ru
 
 The runtime helpers above cover same-session handoffs (`live:handoff`, `runtime:session:finish`). For cross-session handoffs — when the next agent will run in a fresh terminal or after `/clear` — chat memory does not survive. Before suggesting `/clear`, persist the diagnostic to `plans/{slug}.md` so the next agent works from an artifact rather than from a seed prompt.
 
-Load `.aioson/docs/handoff-persistence.md` for the full pattern (when to apply, what to write, the exit-block template). Apply it whenever the recommended next agent is one that consumes raw plans (`/briefing` foremost, sometimes `/product`) or needs the full diagnostic to operate (`/analyst`, `/architect`, `/sheldon`). Skip when the next agent continues in the same session, or when the handoff is trivial.
+Load `.aioson/docs/handoff-persistence.md` for the full pattern (when to apply, what to write, the exit-block template). Apply it whenever the recommended next agent is one that consumes raw plans (`/aioson:agent:briefing` foremost, sometimes `/aioson:agent:product`) or needs the full diagnostic to operate (`/aioson:agent:analyst`, `/aioson:agent:architect`, `/aioson:agent:sheldon`). Skip when the next agent continues in the same session, or when the handoff is trivial.