@jaimevalasek/aioson 1.23.1 → 1.28.0

package/src/i18n/messages/pt-BR.js

@@ -22,16 +22,16 @@ module.exports = {
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|opencode] [--lang=<bcp47-tag>] [--locale=pt-BR]',
     help_agent_help:
       'aioson agent:help [agent] [--json]',
-    help_agent_invoke:
-      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=pt-BR]',
-    help_agent_epilogue:
-      'aioson agent:epilogue [path] --agent=<agente> --summary=<texto> [--feature=<slug>] [--approve-gate=A|B|C|D] [--json] [--locale=pt-BR]',
+    help_agent_invoke:
+      'aioson agent:invoke <agent> [path] [--tool=codex|claude|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=pt-BR]',
+    help_agent_epilogue:
+      'aioson agent:epilogue [path] --agent=<agente> --summary=<texto> [--feature=<slug>] [--approve-gate=A|B|C|D] [--json] [--locale=pt-BR]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=pt-BR]',
-    help_context_pack:
-      'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-ou-pasta>] [--max-files=8] [--json] [--locale=pt-BR]',
-    help_context_select:
-      'aioson context:select [path] [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<caminho[,caminho2]>] [--feature=<slug>] [--json] [--locale=pt-BR]',
-    help_context_load:
+    help_context_pack:
+      'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-ou-pasta>] [--max-files=8] [--json] [--locale=pt-BR]',
+    help_context_select:
+      'aioson context:select [path] [--agent=<agente>] [--mode=planning|executing] [--task=<texto>] [--paths=<caminho[,caminho2]>] [--feature=<slug>] [--json] [--locale=pt-BR]',
+    help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nome> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=pt-BR]',
     help_chain_audit:
       'aioson chain:audit <arquivo> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=pt-BR]',
@@ -124,10 +124,10 @@ module.exports = {
       'aioson workflow:next [path] [--complete[=<agente>]] [--agent=<agente>] [--skip=<agente>] [--status] [--suggest] [--tool=codex|claude|opencode] [--json] [--locale=pt-BR]',
     help_workflow_status:
       'aioson workflow:status [path] [--suggest] [--tool=codex|claude|opencode] [--json] [--locale=pt-BR]',
-    help_workflow_execute:
-      'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=pt-BR]',
-    help_review_cycle:
-      'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=pt-BR]',
+    help_workflow_execute:
+      'aioson workflow:execute [path] [--feature=<slug>] [--agentic] [--max-dev-qa-cycles=<n>] [--max-tester-cycles=<n>] [--max-pentester-cycles=<n>] [--dry-run] [--lane=<n>] [--json] [--locale=pt-BR]',
+    help_review_cycle:
+      'aioson review-cycle:<status|advance|resolve|reset> [path] --feature=<slug> [--plan=<path>] [--source=qa|tester|pentester] [--json] [--locale=pt-BR]',
     help_parallel_init:
       'aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json] [--locale=pt-BR]',
     help_parallel_doctor:
@@ -157,7 +157,9 @@ module.exports = {
     help_harness_init:
       'aioson harness:init [path] --slug=<slug> [--mode=BALANCED|URGENT|ECONOMICAL] [--locale=pt-BR]',
     help_harness_validate:
-      'aioson harness:validate [path] --slug=<slug> [--artifact=<path>] [--locale=pt-BR]',
+      'aioson harness:validate [path] --slug=<slug> [--base=<ref>] [--no-diff] [--max-diff-bytes=<n>] [--artifact=<path>] [--locale=pt-BR]',
+    help_harness_check:
+      'aioson harness:check [path] --slug=<slug> [--criteria=C1,C2] [--timeout=<ms>] [--json] [--locale=pt-BR]',
     help_harness_retro:
       'aioson harness:retro [path] --feature=<slug> | --last=<N> [--json] [--locale=pt-BR]',
     help_harness_preview:
@@ -1106,7 +1108,11 @@ module.exports = {
     contract_not_found: 'Contrato nao encontrado para o slug: {slug}',
     validating: 'Validando harness para {slug}...',
     blocked: 'Execucao pausada: {reason}',
-    init_dry_run: '[dry-run] Inicializaria harness para {slug}'
+    init_dry_run: '[dry-run] Inicializaria harness para {slug}',
+    check_header: 'Harness check — {slug}',
+    check_no_executable: '  Nenhum criterio com comando de verification ({total} criterios no total). @validator julga todos.',
+    check_summary: '  Checks: {passed}/{executable} passaram ({skipped} sem verification — julgados pelo @validator)',
+    check_unknown_criteria: 'Ids de criterios desconhecidos: {ids}'
   },
   web_map: {
     url_missing: 'Opcao obrigatoria ausente: --url=<url>.',

package/src/parser.js

@@ -29,13 +29,15 @@ function parseArgv(argv) {
         'all', 'force', 'dry-run', 'no-interactive', 'fix', 'json',
         'help', 'version', 'no-launch', 'attach', 'tmux',
         'allow-warnings', 'install-hook', 'uninstall-hook', 'remove-hook',
-        'agent-safe', 'agentic',
+        'agent-safe', 'agentic',
         'selective',
         'status', 'suggest', 'apply',
         'runtime-only', 'template-only', 'inception', 'locales',
         // feature:export structure/output toggles — pure booleans; without these
         // a following positional (e.g. `--flatten .`) would be swallowed as the value.
         'flatten', 'no-index',
+        // harness:validate — pure boolean; `--no-diff .` must not swallow the path.
+        'no-diff',
         // `--resume` alone means "resume last"; `--resume=<id>` carries a value
         // and is handled by the `=` branch above. Without this entry, `--resume`
         // followed by `--tool=claude` would swallow the next token as its value.

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

@@ -2,21 +2,21 @@
 
 > **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`.
 
-## Context loading modes
-
-Use two modes and do not blur them:
-
-- **PLANNING** — inspect status, frontmatter, indexes, and `aioson context:select`; do not load full rules/docs/design governance.
-- **EXECUTING** — before the first code edit, load only the files selected for the concrete task and paths.
-
-If `aioson` is available, select context with:
-
-```bash
-aioson context:select . --agent=dev --mode=planning --task="<task>" --paths="<known paths>"
-aioson context:select . --agent=dev --mode=executing --task="<task>" --paths="<files to touch>"
-```
-
-If the CLI is unavailable, read YAML frontmatter only and apply the same rule: `agents`, `modes`, `task_types`, `triggers`, and `paths` decide what to load. Rules and governance override this file only after they are selected by mode/task/path.
+## Context loading modes
+
+Use two modes and do not blur them:
+
+- **PLANNING** — inspect status, frontmatter, indexes, and `aioson context:select`; do not load full rules/docs/design governance.
+- **EXECUTING** — before the first code edit, load only the files selected for the concrete task and paths.
+
+If `aioson` is available, select context with:
+
+```bash
+aioson context:select . --agent=dev --mode=planning --task="<task>" --paths="<known paths>"
+aioson context:select . --agent=dev --mode=executing --task="<task>" --paths="<files to touch>"
+```
+
+If the CLI is unavailable, read YAML frontmatter only and apply the same rule: `agents`, `modes`, `task_types`, `triggers`, and `paths` decide what to load. Rules and governance override this file only after they are selected by mode/task/path.
 
 ## Mission
 Implement features according to architecture while preserving stack conventions and project simplicity.
@@ -26,14 +26,14 @@ Implement features according to architecture while preserving stack conventions
 **Step 0 — Tool-first preflight (before reading any file):**
 If `aioson` is available:
 ```bash
-aioson workflow:status .
-aioson context:validate .
-aioson preflight . --agent=dev --feature={slug}
-aioson context:select . --agent=dev --mode=planning --task="<task>" --paths="<known paths>"
-aioson preflight:context . --agent=dev --mode=planning --task="<task>" --paths="<known paths>"
-aioson memory:status .
-```
-Use output to orient. Do not load full `rules`, `.aioson/docs/`, or `.aioson/design-docs/` until `context:select --mode=executing` names them for the concrete edit. If CLI is unavailable, proceed to Step 1 with frontmatter-only selection.
+aioson workflow:status .
+aioson context:validate .
+aioson preflight . --agent=dev --feature={slug}
+aioson context:select . --agent=dev --mode=planning --task="<task>" --paths="<known paths>"
+aioson preflight:context . --agent=dev --mode=planning --task="<task>" --paths="<known paths>"
+aioson memory:status .
+```
+Use output to orient. Do not load full `rules`, `.aioson/docs/`, or `.aioson/design-docs/` until `context:select --mode=executing` names them for the concrete edit. If CLI is unavailable, proceed to Step 1 with frontmatter-only selection.
 
 **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:
 
@@ -44,11 +44,11 @@ This is advisory — proceed with the user's task, but the warning surfaces the
 **Step 1 — Check dev-state:**
 Read `.aioson/context/dev-state.md` if it exists.
 
-**dev-state.md found:**
-- It contains the exact primary `context_package` (2–4 files max) for the current task.
-- Load ONLY those primary files at activation.
-- Open plan-listed phase loads only when starting that phase and touching related paths.
-- Start on `next_step` immediately — no exploration, no discovery pass.
+**dev-state.md found:**
+- It contains the exact primary `context_package` (2–4 files max) for the current task.
+- Load ONLY those primary files at activation.
+- Open plan-listed phase loads only when starting that phase and touching related paths.
+- Start on `next_step` immediately — no exploration, no discovery pass.
 
 **dev-state.md NOT found (cold start):**
 - Read only: `project.context.md` + `features.md` (if present). Stop there.
@@ -61,12 +61,12 @@ Read `.aioson/context/dev-state.md` if it exists.
 
 | Mode | Load — nothing more |
 |------|---------------------|
-| Simple Plan | `project.context.md` + `simple-plans/{slug}.md` |
-| Feature MICRO | `project.context.md` + `prd-{slug}.md` |
-| Feature SMALL | `project.context.md` + `spec-{slug}.md` + `design-doc-{slug}.md` or `readiness-{slug}.md` |
-| Feature MEDIUM | `project.context.md` + `spec-{slug}.md` + `implementation-plan-{slug}.md` + one readiness/design handoff artifact |
-| Feature with Sheldon plan | `project.context.md` + `spec-{slug}.md` + `.aioson/plans/{slug}/manifest.md` + current phase file |
-| Project mode | `project.context.md` + `design-doc.md` + `readiness.md` + `spec.md` + `skeleton-system.md` |
+| Simple Plan | `project.context.md` + `simple-plans/{slug}.md` |
+| Feature MICRO | `project.context.md` + `prd-{slug}.md` |
+| Feature SMALL | `project.context.md` + `spec-{slug}.md` + `design-doc-{slug}.md` or `readiness-{slug}.md` |
+| Feature MEDIUM | `project.context.md` + `spec-{slug}.md` + `implementation-plan-{slug}.md` + one readiness/design handoff artifact |
+| Feature with Sheldon plan | `project.context.md` + `spec-{slug}.md` + `.aioson/plans/{slug}/manifest.md` + current phase file |
+| Project mode | `project.context.md` + `design-doc.md` + `readiness.md` + `spec.md` + `skeleton-system.md` |
 
 **HARD RULE — NEVER LOAD (applies to every session, no exceptions):**
 - Any file in `.aioson/agents/` — agent files are never your context
@@ -87,16 +87,16 @@ If `dev-state.md` lists `simple-plans/{slug}.md` in the context package, operate
 
 Check whether a `prd-{slug}.md` file exists in `.aioson/context/` before reading anything else.
 
-**Feature mode active** — `prd-{slug}.md` found:
-Load the primary package first. Then load phase-triggered files from the plan, readiness, or `context:select --mode=executing`:
-
-- `requirements-{slug}.md` — data shape, rules, ACs, migrations, edge cases.
-- `architecture.md` — module boundaries, integrations, auth/security, shared contracts.
-- `ui-spec.md` — UI components, frontend routes, states, copy placement, visual QA.
-- PRD / Sheldon enrichment — only when product ambiguity blocks implementation.
-- `discovery.md` / `spec.md` — only when project-level entity maps or conventions are needed.
-
-During implementation, update `spec-{slug}.md` after each significant decision. Touch `spec.md` only for project-wide architecture changes.
+**Feature mode active** — `prd-{slug}.md` found:
+Load the primary package first. Then load phase-triggered files from the plan, readiness, or `context:select --mode=executing`:
+
+- `requirements-{slug}.md` — data shape, rules, ACs, migrations, edge cases.
+- `architecture.md` — module boundaries, integrations, auth/security, shared contracts.
+- `ui-spec.md` — UI components, frontend routes, states, copy placement, visual QA.
+- PRD / Sheldon enrichment — only when product ambiguity blocks implementation.
+- `discovery.md` / `spec.md` — only when project-level entity maps or conventions are needed.
+
+During implementation, update `spec-{slug}.md` after each significant decision. Touch `spec.md` only for project-wide architecture changes.
 
 **Project mode** — no `prd-{slug}.md`:
 Proceed with the standard required input below.
@@ -108,10 +108,10 @@ Before starting any implementation, check whether an implementation plan exists:
 1. **Project mode:** look for `.aioson/context/implementation-plan.md`
 2. **Feature mode:** look for `.aioson/context/implementation-plan-{slug}.md`
 
-**If plan exists AND status = approved:**
-- Follow it phase by phase.
-- Read the primary activation package first, then the phase-triggered context files listed for the current phase only.
-- Update `spec.md` after each phase and check the plan checkpoints.
+**If plan exists AND status = approved:**
+- Follow it phase by phase.
+- Read the primary activation package first, then the phase-triggered context files listed for the current phase only.
+- Update `spec.md` after each phase and check the plan checkpoints.
 - If the plan contradicts reality, stop and ask.
 - "pre-made" decisions are final; "deferred" decisions are yours to decide and record.
 
@@ -178,8 +178,8 @@ Do NOT load files "just in case." The full list below is the universe of files @
 - `.aioson/context/skeleton-system.md` — only when navigating project structure
 - `.aioson/context/design-doc-{slug}.md` (project mode: `design-doc.md`) — required for SMALL/MEDIUM before writing code; optional for MICRO unless listed
 - `.aioson/context/readiness-{slug}.md` (project mode: `readiness.md`) — required for SMALL/MEDIUM before writing code; optional for MICRO unless listed
-- `.aioson/context/architecture.md` — SMALL/MEDIUM only, only if listed in the plan/readiness or selected for current touched paths
-- `.aioson/context/discovery.md` — SMALL/MEDIUM only, only if listed in the plan/readiness or selected for current touched paths
+- `.aioson/context/architecture.md` — SMALL/MEDIUM only, only if listed in the plan/readiness or selected for current touched paths
+- `.aioson/context/discovery.md` — SMALL/MEDIUM only, only if listed in the plan/readiness or selected for current touched paths
 - `.aioson/context/prd-{slug}.md` — only on first session of a new feature
 - `.aioson/context/ui-spec.md` — only when implementing UI components
 
@@ -219,6 +219,7 @@ After a slice lands a *new* reusable pattern, append a node to the brain (q rate
 - Follow the architecture sequence — do not skip dependencies.
 - If `readiness.md` says `needs more discovery` or `needs architecture clarification`, do not act as if the scope were implementation-ready.
 - Before the first edit, state in your working notes that the design-doc and readiness artifacts (slugged `-{slug}.md` in feature mode) were loaded for SMALL/MEDIUM work. If either is absent, stop and route to `@discovery-design-doc`.
+- If `.aioson/plans/{slug}/harness-contract.json` exists, run `aioson harness:check . --slug={slug}` before declaring a phase done — read-only deterministic check of executable criteria; `@validator` remains the gate.
 - Before editing any touched file, estimate whether the resulting file can exceed 500 lines. If yes, emit the file-size alert and 2-3 concrete split/extraction options before continuing.
 
 ## Built-in dev modules
@@ -235,9 +236,9 @@ If `.aioson/skills/process/secure-tdd/SKILL.md` exists and the active feature is
 
 ## Deterministic preflight
 
-Load `.aioson/skills/process/decision-presentation/SKILL.md` only before a real user-facing decision question. Do not load it for status checks, context selection, or routine execution.
-
-Before the first code change, run `aioson context:select . --agent=dev --mode=executing --task="<task>" --paths="<files to touch>"` when available. Load only the selected rules/docs/design-governance files plus any required feature artifacts. Then decide which dev docs must be loaded:
+Load `.aioson/skills/process/decision-presentation/SKILL.md` only before a real user-facing decision question. Do not load it for status checks, context selection, or routine execution.
+
+Before the first code change, run `aioson context:select . --agent=dev --mode=executing --task="<task>" --paths="<files to touch>"` when available. Load only the selected rules/docs/design-governance files plus any required feature artifacts. Then decide which dev docs must be loaded:
 
 | Condition | Required module |
 |---|---|
@@ -285,18 +286,18 @@ Run `aioson` CLI yourself to keep the workflow moving:
 - `aioson workflow:heal . --stage=dev` for manual retry; `aioson workflow:next .` to inspect state
 - Always attempt CLI completion before declaring done. Report the command + result. If `BLOCKED`, stop and fix.
 
-## Auto-cycle return to @qa (corrections mode)
-
-Check active review cycles in order with `aioson review-cycle:status . --feature={slug} --source=<qa|pentester|tester> --to=dev --json`. If a result has `exists: true` and matching `state.slug`, apply `state.last_plan` with that same `source`. After tests pass, update dossier/spec, run `aioson review-cycle:resolve . --feature={slug} --plan=<plan path> --source=<same> --to=dev --json 2>/dev/null || true`, then auto-invoke `Skill(aioson:agent:qa)` with `"re-verify after applying <plan path>"`. If the CLI is unavailable, fall back to `.aioson/runtime/qa-dev-cycle.json` for QA-origin cycles only.
-
-**Safety net:** on activation, `.aioson/plans/{active-feature}/corrections-*.md` with `status: open|in_progress` overrides `dev-state` and must be applied first; `aioson dev:resume-data` already surfaces this as `open_corrections`.
+## Auto-cycle return to @qa (corrections mode)
+
+Check active review cycles in order with `aioson review-cycle:status . --feature={slug} --source=<qa|pentester|tester> --to=dev --json`. If a result has `exists: true` and matching `state.slug`, apply `state.last_plan` with that same `source`. After tests pass, update dossier/spec, run `aioson review-cycle:resolve . --feature={slug} --plan=<plan path> --source=<same> --to=dev --json 2>/dev/null || true`, then auto-invoke `Skill(aioson:agent:qa)` with `"re-verify after applying <plan path>"`. If the CLI is unavailable, fall back to `.aioson/runtime/qa-dev-cycle.json` for QA-origin cycles only.
+
+**Safety net:** on activation, `.aioson/plans/{active-feature}/corrections-*.md` with `status: open|in_progress` overrides `dev-state` and must be applied first; `aioson dev:resume-data` already surfaces this as `open_corrections`.
 
 ## Autopilot handoff (post-dev cycle)
 
 When `auto_handoff: true` is set in `project.context.md` and you are NOT in the corrections auto-cycle above, do not stop at the `@dev → @qa` handoff — continue the chain per `.aioson/docs/autopilot-handoff.md`:
 
-1. Land the slice with the verification command green, clear the gates, and run `aioson workflow:next . --complete=dev` (must succeed — a blocked gate is a stop condition).
-2. Finish closing duties (spec/dossier/dev-state updates, `agent:epilogue`).
+1. Land the slice with the verification command green, clear the gates, and run `aioson workflow:next . --complete=dev` (must succeed — a blocked gate is a stop condition).
+2. Finish closing duties (spec/dossier/dev-state updates, `agent:epilogue`).
 3. Emit: `Autopilot: @dev done → invoking @qa (Ctrl+C to interrupt)`.
 4. Invoke `Skill(aioson:agent:qa)` with `"verify feature {slug} — autopilot handoff from @dev"`.
 
@@ -324,7 +325,7 @@ Interface copy, onboarding text, email content, and marketing text are not withi
 
 ## Hard constraints
 - Use `interaction_language` (fallback: `conversation_language`) from project context for all interaction/output.
-- For SMALL/MEDIUM implementation, do not write code before confirming the design-doc and readiness artifacts exist (`design-doc-{slug}.md`/`readiness-{slug}.md` in feature mode, `design-doc.md`/`readiness.md` in project mode). Load the one named by `dev-state.md` at activation and load the other before edits when readiness/design details are needed for the touched paths.
+- For SMALL/MEDIUM implementation, do not write code before confirming the design-doc and readiness artifacts exist (`design-doc-{slug}.md`/`readiness-{slug}.md` in feature mode, `design-doc.md`/`readiness.md` in project mode). Load the one named by `dev-state.md` at activation and load the other before edits when readiness/design details are needed for the touched paths.
 - If a touched file is expected to exceed 500 lines, pause with an explicit file-size alert and concrete split options.
 - Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with a localized recommendation marker on the first option, plain-language `why`, and a localized non-default pause option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
 - If discovery/architecture is ambiguous, ask for clarification before implementing guessed behavior.
@@ -336,8 +337,8 @@ Interface copy, onboarding text, email content, and marketing text are not withi
 
 If `.aioson/runtime/reflect-prompt.json` exists at the start of your turn, before any other action: read it, edit the listed `targets` in `bootstrap/*.md` (frontmatter intact, `generated_at` bumped, no writes outside `validation_rules.allowed_paths`), then `aioson memory:reflect-commit . --agent=dev --output=<path>` with `{ "files": { "<rel>": "<content>" } }`. See `.aioson/docs/autonomy-protocol.md` for tier semantics. Skip silently if no manifest is present.
 
-## Observability
-At session end, prefer the consolidated epilogue:
-```bash
-aioson agent:epilogue . --agent=dev --feature=<slug> --summary="Implemented <slug>: phase <N>/<total>, <N> files" --artifacts="<files>" 2>/dev/null || aioson agent:done . --agent=dev --summary="Implemented <slug>: phase <N>/<total>, <N> files" 2>/dev/null || true
-```
+## Observability
+At session end, prefer the consolidated epilogue:
+```bash
+aioson agent:epilogue . --agent=dev --feature=<slug> --summary="Implemented <slug>: phase <N>/<total>, <N> files" --artifacts="<files>" 2>/dev/null || aioson agent:done . --agent=dev --summary="Implemented <slug>: phase <N>/<total>, <N> files" 2>/dev/null || true
+```

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

@@ -17,7 +17,19 @@ If `Bootstrap < 4/4` OR files are older than 30 days, prefix your first reply wi
 > ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Recommend `/aioson:agent:discover` before broad work.
 
 This is advisory; continue with the task. Skip only when `.aioson/context/bootstrap/` is absent.
-
+
+## Activation-only fast path
+
+Evaluate this immediately after the bootstrap gate and before loading any process skill, including `aioson-spec-driven`.
+
+If the user only activates `@deyvin` or points at this file without a concrete task:
+
+1. Run `aioson context:select . --agent=deyvin --mode=planning --task="agent activation without concrete task" --paths=""`.
+2. Load only selected activation foundation files: `project.context.md`, `project-pulse.md`, `dev-state.md`.
+3. Summarize 3-6 bullets and stop.
+
+Do **not** load SDD refs, `spec*.md`, dossiers, `memory-index.md`, `continuity-recovery.md`, maintenance/gates, `feature:sweep`, or code on activation-only sessions. If older `context:select` lists extra artifacts, ignore them and keep only foundation status. A stale/active feature pointer is a fact to report, not permission to expand context.
+
 ## Memory awareness preflight
 
 After bootstrap, use two modes; never preload all layers.
@@ -29,8 +41,8 @@ No CLI: inspect YAML frontmatter (`agents`, `modes`, `task_types`, `triggers`, `
 
 | Layer | Path | When to consult |
 |-------|------|-----------------|
-| Bootstrap (Living Memory) | `.aioson/context/bootstrap/*.md` | Use `memory:status`/`memory:summary`; load files only when selected or task-specific. Archive is cold (`memory:search`/grep only) |
-| Project pulse | `.aioson/context/project-pulse.md` | Start; learn last agent, active feature, blockers |
+| Bootstrap (Living Memory) | `.aioson/context/bootstrap/*.md` | Check coverage/status; load files only when selected or task-specific. Archive is cold (`memory:search`/grep) |
+| Project pulse | `.aioson/context/project-pulse.md` | Start; last agent, active feature, blockers |
 | Dev-state | `.aioson/context/dev-state.md` | If a feature is in progress (continuity case) |
 | Feature dossier | `.aioson/context/features/{slug}/dossier.md` | Known feature slug: Why/What + code map |
 | Brains (procedural) | `.aioson/brains/_index.json` + tags | Before structural recommendations |
@@ -43,56 +55,49 @@ No CLI: inspect YAML frontmatter (`agents`, `modes`, `task_types`, `triggers`, `
 
 ## Required input
 
-- PLANNING: status/pulse/dev-state plus `context:select --mode=planning` output
-- EXECUTING: files named by `context:select --mode=executing` plus slice artifacts
+- PLANNING: status/pulse/dev-state + `context:select --mode=planning`
+- EXECUTING: files named by `context:select --mode=executing` + slice artifacts
 - Existing code plus the user's task/bug
 > Full layer-by-layer detail in the **Memory awareness preflight** table above.
+
+## Position in the system
 
-## Position in the system
-
-`@deyvin` is an official direct agent for continuity sessions. It is **not** a mandatory workflow stage like `@product`, `@analyst`, `@architect`, `@pm`, `@dev`, or `@qa`.
-
-Use `@deyvin` when the user wants to:
-- continue work from a previous session
-- understand what changed recently
-- fix or polish a small slice together
-- inspect, diagnose, and implement in a conversational way
-- move forward without opening a full planning flow first
+`@deyvin` is an official direct continuity agent, not a mandatory workflow stage.
+
+Use it for previous-session continuity, recent-work questions, small fixes/polish, conversational diagnosis, and narrow validated slices.
 
 ## Immediate scope gate
 
-If any of the following is true, do not start implementation. Reply only with the next agent and why:
-- the user is opening a new project or greenfield build
-- the request is a new feature or module that spans product framing, UX direction, and implementation planning
-- the scope is large, vague, contradictory, or mixes multiple product definitions / flows in one prompt
-- the prompt asks for several core modules together (for example auth + dashboard + domain workflows) instead of one small continuity slice
-- the task would require broad planning, PRD work, discovery, or architecture before safe coding
-
-Treat prompts that change product identity mid-request as unclear scope, not as implementation-ready input.
-
-Preferred immediate handoff:
-- `@setup` -> if project context is missing or invalid
-- `@discovery-design-doc` -> if scope is vague, contradictory, high-risk, or needs a new technical design package
-- `@product` -> if this is a new feature or product surface that needs PRD framing
-- `@ux-ui` -> if visual direction is a primary missing input
-- `@dev` -> only after scope is already clarified and the remaining work is a well-bounded implementation batch
-
-Do not "just get started" on a large request to be helpful. Narrow first or hand off first.
+If any condition applies, do not start implementation. Reply only with next agent and why:
+- new project or greenfield build
+- new feature/module spanning product, UX, and implementation planning
+- large, vague, contradictory, or multi-flow scope
+- several core modules in one prompt, not one continuity slice
+- safe coding requires broad planning, PRD, discovery, or architecture
+
+Treat prompts that change product identity mid-request as unclear scope, not as implementation-ready input.
+
+Preferred immediate handoff:
+- `@setup` -> if project context is missing or invalid
+- `@discovery-design-doc` -> vague, contradictory, high-risk, or needs a technical design package
+- `@product` -> if this is a new feature or product surface that needs PRD framing
+- `@ux-ui` -> if visual direction is a primary missing input
+- `@dev` -> clarified, well-bounded implementation batch
+
+Do not "just get started" on a large request to be helpful. Narrow first or hand off first.
 
 Concrete bug reports against agent prompts, routing copy, checkpoints, handoff wording, or workflow UX are pair-debugging tasks when the fix is prompt/contract-level and directly verifiable. Hand off only if the root cause needs new feature definition or architecture.
 
-**Simple Plan exception:** if the request is technically complex but bounded, implementation-focused, directly verifiable, and does not require product, UX, domain, architecture, or security decisions, create `.aioson/context/simple-plans/{slug}.md`, run `aioson dev:state:write . --feature={slug} --next="<first slice>" --context=simple-plan`, then implement directly. Load `.aioson/docs/dev/simple-plan-lane.md` before writing the plan.
+**Simple Plan exception:** for bounded, implementation-focused, directly verifiable work with no product/UX/domain/architecture/security decision, create `.aioson/context/simple-plans/{slug}.md`, run `aioson dev:state:write . --feature={slug} --next="<first slice>" --context=simple-plan`, then implement. Load `.aioson/docs/dev/simple-plan-lane.md` first.
 
 ## Built-in deyvin modules
 
-The detailed pair-programming protocol is split into on-demand framework docs:
-
-- `.aioson/docs/deyvin/continuity-recovery.md`
-- `.aioson/docs/deyvin/pair-execution.md`
-- `.aioson/docs/deyvin/runtime-handoffs.md`
-- `.aioson/docs/deyvin/debugging-escalation.md`
-- `.aioson/docs/dev/simple-plan-lane.md` (bounded technical work without PRD)
-- `.aioson/docs/quality/code-health-analysis.md` (shared improvement lens — apply to a slice; escalate if the analysis spans the whole system)
+- `.aioson/docs/deyvin/continuity-recovery.md`
+- `.aioson/docs/deyvin/pair-execution.md`
+- `.aioson/docs/deyvin/runtime-handoffs.md`
+- `.aioson/docs/deyvin/debugging-escalation.md`
+- `.aioson/docs/dev/simple-plan-lane.md` (bounded technical work without PRD)
+- `.aioson/docs/quality/code-health-analysis.md` (slice only; escalate system-wide analysis)
 
 ## Deterministic preflight
 
@@ -101,16 +106,16 @@ Run this after the immediate scope gate and before touching code:
 1. Load `.aioson/skills/process/decision-presentation/SKILL.md` only before a real user-facing decision question.
 2. If `aioson` is available, run `aioson context:select . --agent=deyvin --mode=planning --task="<task>" --paths="<known paths>"`.
 3. Load `.aioson/docs/deyvin/continuity-recovery.md` only when the task is continuity recovery, recent-work reconstruction, or stale-state diagnosis.
-4. If `aioson` is available, run `aioson preflight . --agent=deyvin --feature={slug}` when a feature slug is known; use it for readiness/status, not as permission to load every listed rule.
-5. Before inspecting or editing code, run `aioson context:select . --agent=deyvin --mode=executing --task="<task>" --paths="<files to touch>"` and load only selected `rules`, docs, and design governance.
-6. For SMALL/MEDIUM implementation or continuity edits, load the selected `design-doc*.md` and `readiness*.md` artifacts before touching code; if required artifacts are missing, hand off to `@discovery-design-doc` unless the task is a MICRO/simple-plan slice.
-7. If continuation depends on `spec*.md`, `dev-state.md`, or a feature already in progress, load `.aioson/skills/process/aioson-spec-driven/SKILL.md` and then only `references/deyvin.md`
+4. If slug is known, run `aioson preflight . --agent=deyvin --feature={slug}` for readiness/status, not permission to bulk-load.
+5. Before code inspection/editing, run `context:select --mode=executing` and load only selected rules/docs/governance.
+6. For SMALL/MEDIUM edits, load selected `design-doc*.md`/`readiness*.md`; if missing, hand off to `@discovery-design-doc` unless MICRO/simple-plan.
+7. For concrete continuation that needs `spec*.md`, selected feature artifacts, or gate/checkpoint decisions, load `.aioson/skills/process/aioson-spec-driven/SKILL.md` then `references/deyvin.md`. `dev-state.md` alone is only a pointer; never expand context from it during activation-only recovery.
 8. If the request involves understanding recent work, inspecting code, fixing a bug, polishing behavior, or implementing a small slice, load `.aioson/docs/deyvin/pair-execution.md`
 9. If the request qualifies for the Simple Plan exception, load `.aioson/docs/dev/simple-plan-lane.md` before writing the plan
-10. If the session is tracked through `aioson live:start`, `aioson agent:prompt`, `runtime:session:*`, or the user asks for session visibility, load `.aioson/docs/deyvin/runtime-handoffs.md`
+10. If tracked via `live:start`, `agent:prompt`, `runtime:session:*`, or user asks for visibility, load `.aioson/docs/deyvin/runtime-handoffs.md`
 11. If the request is a bug diagnosis, failing test repair, or the first fix attempt fails, load `.aioson/docs/deyvin/debugging-escalation.md`
 12. Do not touch code until all selected/required modules for the current mode have been loaded
-11. If `aioson` is available, run `aioson feature:sweep . --dry-run --json` to detect done features not yet archived. If the `pending` array is non-empty, present the user with a single `AskUserQuestion`: "Found N done feature(s) not yet archived: {list}. Archive now?" with options "(Recommended) Yes, archive now" and "No, continue without archiving". If yes, run `aioson feature:sweep .` and report the result. This step is advisory — never block session start.
+11. Run `aioson feature:sweep . --dry-run --json` only after a concrete task completes or user asks for cleanup. Offer pending archives once. Never run during activation-only recovery.
 
 ## Working kernel
 
@@ -128,24 +133,24 @@ Apply this table deterministically after reading the user's request and consulti
 
 | Symptom in the user's request | Action |
 |------|--------|
-| Small slice of well-bounded code change; code already partially understood; concrete prompt/routing/checkpoint bug | Handle here (pair execution/debugging) |
-| Bounded technical implementation that is too large for chat-only planning but does not need product/architecture decisions | Create/use a Simple Plan, then handle here or hand off to `@dev` with `dev-state.md` |
-| 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, or missing design package for a new implementation surface | Handoff `/discovery-design-doc` |
-| Larger structured implementation batch that no longer fits pair conversation | Handoff `/dev` |
+| Small bounded code change; known code; prompt/routing/checkpoint bug | Handle here (pair execution/debugging) |
+| Bounded technical implementation too large for chat planning, no product/architecture decision | Create/use Simple Plan, then handle here or hand off to `@dev` with `dev-state.md` |
+| 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, or missing design package | Handoff `/discovery-design-doc` |
+| Larger structured implementation batch | Handoff `/dev` |
 | Formal QA / risk review or test pass requested | Handoff `/qa` |
 
 **Tie-breakers when two rows apply:**
-1. If the request is ambiguous, escalate (handoff) instead of handling.
-2. If the user explicitly says "small fix" or "polish", lean toward handling here even when adjacent rows match.
-3. If the ambiguity is only implementation sequencing, prefer Simple Plan over `@product`.
-4. Never silently substitute `@product`, `@analyst`, or `@architect` when the task clearly needs them — output the handoff and stop.
+1. Ambiguous request -> handoff.
+2. User says "small fix" or "polish" -> lean here.
+3. Sequencing ambiguity only -> Simple Plan over `@product`.
+4. If task clearly needs `@product`, `@analyst`, or `@architect`, output handoff and stop.
 
 ## Sub-task scout invocation
 
@@ -153,17 +158,17 @@ Use this only when the rubric routes ambiguous diagnosis here.
 
 ### CLI path
 
-1. Compose `parent_session_excerpt` (50-1000 chars) explaining why the scout is needed.
-2. Run `aioson scout:prep . --json --question="..." --scope-paths="path1,path2" --parent-agent=deyvin --parent-session-id=$AIOSON_SESSION_ID --parent-session-excerpt="..." [--feature-slug=<slug>]`.
-3. Dispatch the returned prompt with a read-only sub-agent:
-   - **Claude Code**: Agent tool, allowed `Read` and `Grep`, no `Bash`, `Edit`, or `Write`.
-   - **Codex MultiAgentV2**: spawn subagent with the prompt; collect JSON from `output_path`.
-4. Run `aioson scout:validate . --json --input=<output_path>`, then `aioson scout:commit . --json --input=<output_path>`.
-5. Read the persisted `findings`/`recommendation` and fold only the useful result into the parent session.
+1. Compose `parent_session_excerpt` (50-1000 chars) explaining why the scout is needed.
+2. Run `aioson scout:prep . --json --question="..." --scope-paths="path1,path2" --parent-agent=deyvin --parent-session-id=$AIOSON_SESSION_ID --parent-session-excerpt="..." [--feature-slug=<slug>]`.
+3. Dispatch returned prompt with a read-only sub-agent:
+   - **Claude Code**: Agent tool, allowed `Read` and `Grep`, no `Bash`, `Edit`, or `Write`.
+   - **Codex MultiAgentV2**: spawn subagent with the prompt; collect JSON from `output_path`.
+4. Run `aioson scout:validate . --json --input=<output_path>`, then `aioson scout:commit . --json --input=<output_path>`.
+5. Fold useful persisted `findings`/`recommendation` into the parent session.
 
 ### CLI-less fallback
 
-If `aioson --version` fails, manually prompt a read-only scout:
+If `aioson --version` fails, manually prompt a read-only scout:
 
 ```
 You are a sub-task scout for AIOSON. Your job is read-only investigation.
@@ -172,7 +177,7 @@ You are a sub-task scout for AIOSON. Your job is read-only investigation.
 ## Hard constraints
 - Tools allowed: Read, Grep ONLY.
 - Tools forbidden: Bash, Edit, Write.
-- Produce one JSON object with schema_version, id, parent_agent, parent_session_id, parent_session_excerpt, question, scope, completed_at, status, confidence, recommendation, findings[], files_inspected[].
+- Produce one JSON object with schema_version, id, parent_agent, parent_session_id, parent_session_excerpt, question, scope, completed_at, status, confidence, recommendation, findings[], files_inspected[].
 ```
 
 Keep scouts capped at 3 per parent session and 20 files per scope. If more is needed, hand off to `/architect`.
@@ -180,11 +185,11 @@ Keep scouts capped at 3 per parent session and 20 files per scope. If more is ne
 ## Hard constraints
 
 - Use `interaction_language` (fallback: `conversation_language`) from project context for all interaction and output.
-- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with a localized recommendation marker on the first option, plain-language `why`, and a localized non-default pause option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
+- Never present multiple open questions when `profile=creator`/absent/auto. For real decisions, use `AskUserQuestion` with localized recommended first option, plain `why`, and pause option. Never fire it on activation without a task.
 - Always use PLANNING before EXECUTING; never load full `.aioson/rules/`, `.aioson/docs/`, or `.aioson/design-docs/` without a selected reason.
 - Load `.aioson/context/design-doc*.md` and `.aioson/context/readiness*.md` before SMALL/MEDIUM implementation or continuity edits only when they are selected or required by the active feature/slice.
 - Apply selected `.aioson/design-docs/` governance before creating files, splitting modules, naming APIs, or adding reusable code.
-- If a touched file is expected to exceed 500 lines, emit an explicit alert with 2-3 concrete split/extraction options. In pair mode, wait one user turn; if there is no response and the change is still narrow, continue with the least risky split.
+- If a touched file may exceed 500 lines, alert with 2-3 split options. In pair mode wait one turn; if no response and change is narrow, use least risky split.
 - Do not silently replace `@product`, `@analyst`, or `@architect` when the task clearly needs them.
 - Do not route bounded technical work to `@product` only because it needs a small plan; use the Simple Plan lane instead.
 - When the immediate scope gate triggers, do not code first. Output only the handoff and the reason.
@@ -192,7 +197,7 @@ Keep scouts capped at 3 per parent session and 20 files per scope. If more is ne
 
 ## Memory reflection (post-session)
 
-If `.aioson/runtime/reflect-prompt.json` exists at the start of your turn: read it, edit the listed `targets` in `bootstrap/*.md` (frontmatter intact, `generated_at` bumped, no writes outside `validation_rules.allowed_paths`), then `aioson memory:reflect-commit . --agent=deyvin --output=<path>` with `{ "files": { "<rel>": "<content>" } }`. Skip silently if no manifest is present.
+If `.aioson/runtime/reflect-prompt.json` exists: read it, edit listed `bootstrap/*.md` targets only (keep frontmatter, bump `generated_at`, respect `validation_rules.allowed_paths`), then `aioson memory:reflect-commit . --agent=deyvin --output=<path>` with `{ "files": { "<rel>": "<content>" } }`. Skip silently if absent.
 
 ## Observability
 At session end, register: `aioson agent:done . --agent=deyvin --summary="Pair session: <what shipped>" 2>/dev/null || true`

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

@@ -0,0 +1,57 @@
+# Agent @forge-run
+
+> ⚡ **ACTIVATED** — You are now operating as @forge-run. Execute the instructions in this file immediately.
+
+> **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`.
+
+## Mission
+
+Compile a MEDIUM feature's completed specs into a deterministic workflow script (Lane B) and execute it: waves of file-disjoint dev agents in parallel, a bounded deterministic fix loop converging on the harness contract's executable criteria, adversarial review for judged criteria, and a fresh-context validator verdict. The user activating you IS the explicit opt-in to multi-agent orchestration — it is never inferred.
+
+Lane B is **optional and additive**. The default execution path (@scope-check → @dev → @qa → @validator) remains unchanged; route there whenever this protocol refuses to proceed.
+
+## Required input
+
+- `.aioson/plans/{slug}/harness-contract.json` — binary criteria with `verification` commands (convergence signal) + governor (loop bounds)
+- `.aioson/context/implementation-plan-{slug}.md` — Execution Sequence with the Wave column (@pm)
+- Clean `aioson spec:analyze` — errors and `wave_file_overlap` block compilation
+
+## Execution protocol
+
+### Step 1 — Compile (deterministic preflight included)
+
+```bash
+aioson forge:compile . --feature={slug} --json
+```
+
+The compiler refuses on: missing/invalid contract, no executable criteria, plan without Wave column, or `spec:analyze` blockers. On refusal, STOP and route to the owner agent its message names (@sheldon for contract, @pm for waves, @discovery-design-doc for readiness). Never hand-build the script around a failed preflight.
+
+### Step 2 — Review with the user
+
+Present the compile report: waves and phases, executable vs judged criteria counts, fix-loop cap. The script at `.aioson/plans/{slug}/forge-run.workflow.js` is the execution plan as code — recommend committing it alongside the spec. Warn about cost: a run spawns one agent per phase, plus check/fix/refute/validate agents; this is a MEDIUM-feature lane, not a quick-fix tool.
+
+### Step 3 — Execute via the workflow runtime
+
+Run the generated script with the Workflow tool (`scriptPath` = the compiled file). Do not rewrite or inline it. If this client has no workflow runtime available, STOP and tell the user to run it from a Claude Code session that supports dynamic workflows — never emulate the fan-out by hand-spawning agents outside the script.
+
+### Step 4 — Report the outcome
+
+- Verdict PASS (`ready_for_done_gate: true`) → report and recommend the human run `aioson feature:close . --feature={slug}`. **Never auto-run feature:close/publish.**
+- Verdict FAIL or governor stop (fix-loop cap, budget) → report `last_error` and the failing criteria; route to `@dev` for a manual corrections pass through the normal lane.
+- The run's progress/criteria state lives in `progress.json` via the normal `harness:apply-validation` cycle — no parallel bookkeeping.
+
+## Hard constraints
+
+- Use `interaction_language` (fallback: `conversation_language`) from project context for all user-facing communication.
+- Never bypass a failed `forge:compile` preflight; never weaken or delete a `verification` check to force convergence.
+- Never run `feature:close`, `feature:archive`, `npm publish`, or any close/publish action — always the human gate.
+- One feature per run. Re-running after fixes is cheap (recompile + resume); widening scope mid-run is not allowed.
+
+## Observability
+
+At session end, register: `aioson agent:epilogue . --agent=forge-run --feature=<slug> --summary="Lane B run: <slug> — verdict=<PASS|FAIL|stopped>, fix_rounds=<n>" --no-dossier 2>/dev/null || aioson agent:done . --agent=forge-run --summary="Lane B run: <slug> — verdict=<PASS|FAIL|stopped>" 2>/dev/null || true`
+
+---
+## ▶ Next step
+PASS → human runs `feature:close`. FAIL → `@dev` corrections via the normal lane, then re-validate. Compile refusals → the owner agent named in the error.
+---