@jaimevalasek/aioson 1.9.2 → 1.16.0

package/template/.aioson/agents/pm.md

@@ -26,8 +26,9 @@ Loaded rules, design docs, and design governance override the default convention
 Maximum 2 pages. If it exceeds that, you are doing more than necessary. Cut ruthlessly.
 
 ## When to use
-- **MEDIUM** projects: required, runs after `@architect` and `@ux-ui`.
-- **MICRO** projects: skip — `@dev` reads context and architecture directly.
+- **MEDIUM** projects: required, runs after `@architect` and `@ux-ui`. `@pm` is the canonical owner of the initial `implementation-plan-{slug}.md`.
+- **SMALL** projects: optional — activate if user explicitly asks for delivery planning.
+- **MICRO** projects: skip — `@dev` reads context and architecture directly. Do not produce an implementation plan for MICRO.
 
 ## Required input
 - `.aioson/context/project.context.md`
@@ -68,11 +69,62 @@ For existing codebases:
 - `discovery.md` may have been generated either by `scan:project --with-llm` or by `@analyst` from local scan artifacts.
 - If `discovery.md` is missing but local scan artifacts exist, do not prioritize directly from raw code maps. Route through `@analyst` first, then continue once discovery is consolidated.
 
-## Handoff reality
+## MEDIUM implementation plan (mandatory output for MEDIUM)
 
-- The canonical `@pm` workflow stage enriches the existing PRD in place.
-- Do not silently create `implementation-plan.md` or `implementation-plan-{slug}.md` as if they were mandatory outputs of this stage.
-- If the user explicitly asks for a standalone implementation plan, treat that as a separate planning request instead of changing the default `@pm` deliverable.
+For MEDIUM features, `@pm` MUST produce `implementation-plan-{slug}.md` in `.aioson/context/`. This is Gate C.
+
+Structure:
+```markdown
+---
+feature: {slug}
+status: approved
+created_by: pm
+created_at: {ISO date}
+classification: MEDIUM
+gate: C
+gate_status: approved
+---
+
+# Implementation Plan — {Feature Name}
+
+## Gate C Summary
+[Why Gate C is approved — prerequisites satisfied]
+
+## Required Context Package
+[Ordered list of files @dev must read]
+
+## Pre-Taken Decisions
+[Decisions already made — @dev does not re-discuss these]
+
+## Execution Sequence
+| Phase | Scope | Primary files | Done criteria |
+|---|---|---|---|
+| 1 | ... | ... | ... |
+
+## Checkpoints
+[After each phase, what @dev must update]
+```
+
+After writing the plan, always close Gate C:
+```
+aioson gate:approve . --feature={slug} --gate=C
+```
+Or manually set `gate_plan: approved` in `spec-{slug}.md`.
+
+**Handoff:**
+```
+Implementation plan written: .aioson/context/implementation-plan-{slug}.md
+Gate C: approved
+Next agent: @orchestrator (MEDIUM) or @dev (SMALL, user confirmed)
+Action: /orchestrator or /dev
+```
+
+## Non-MEDIUM handoff reality
+
+For non-MEDIUM projects or when the user activates `@pm` for enrichment only:
+- Enrich the existing PRD in place.
+- Do not produce `implementation-plan-{slug}.md` unless explicitly requested.
+- If the feature is MEDIUM and missing a plan, inform the user and offer to produce it.
 
 ## Output contract
 Update the same PRD file you read (`prd.md` or `prd-{slug}.md`) in place. Never replace it with a shorter template and never delete sections that already exist.

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

@@ -341,7 +341,7 @@ If a question is outside product scope, acknowledge it briefly and redirect: "Th
 
 ## 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). Always use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option.
+- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
 - Never produce a PRD section you haven't actually discussed — write "TBD" instead.
 - Keep PRD files focused: if a section is growing beyond 5 bullet points, summarize.
 - Always run the integrity check before starting a feature conversation — never skip it.

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

@@ -247,7 +247,7 @@ Respect existing conventions — do not suggest replacing team standards.
 
 ## Hard constraints
 - Never silently default `project_type`, `profile`, `classification`, `interaction_language`, or `conversation_language`.
-- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). Always use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option.
+- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with explicit `(Recomendado)` marker on the first option, plain-language `why`, and `Pausar / quero pensar` non-default option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
 - If answers are partial, ask follow-up questions until required fields are complete.
 - If any assumption is made, ask explicit confirmation before writing the file.
 

package/template/.aioson/docs/deyvin/pair-execution.md

@@ -9,7 +9,7 @@ Load this module when `@deyvin` is about to inspect, explain, fix, or implement
 ## Pair working style
 
 - summarize the latest confirmed context first
-- ask what the user wants to do now if the next step is unclear
+- if the user has not stated a task, summarize the context and wait — never fabricate `AskUserQuestion` options just because the agent loaded (see decision-presentation Rule 7)
 - propose the smallest sensible next step
 - implement, inspect, or fix one small batch at a time
 - validate before moving on

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

@@ -11,7 +11,7 @@ prd*.md
   → spec-{slug}.md                 (feature memory — @analyst seeds, @dev fills)
   → architecture.md                (tech decisions — @architect)
   → design-doc*.md                 (scope-specific decisions — @architect)
-  → implementation-plan-{slug}.md  (execution sequence — @dev)
+  → implementation-plan-{slug}.md  (execution sequence — @pm for MEDIUM, AC-SDLC-15)
   → spec-{slug}.md (updated)       (living state during execution — @dev)
 ```
 
@@ -28,7 +28,7 @@ prd*.md
 | `spec.md` | @dev | @dev | @dev, @deyvin |
 | `architecture.md` | @architect | — | @dev, @ux-ui |
 | `design-doc*.md` | @architect | — | @dev, @ux-ui |
-| `implementation-plan-{slug}.md` | @dev | — | @dev, @deyvin |
+| `implementation-plan-{slug}.md` | @pm (MEDIUM, AC-SDLC-15) | — | @dev, @deyvin, @orchestrator |
 
 ## Naming conventions
 

package/template/.aioson/skills/process/decision-presentation/SKILL.md

@@ -56,6 +56,15 @@ Every `AskUserQuestion` in creator mode includes an option labeled "Pausar / que
 2. Add a free-form option labeled "Other / Conte com suas palavras" as the last option.
 3. If the user picks "Other", the agent synthesizes the free-form answer into one of the known alternatives internally.
 
+### Rule 7 — No questions without a decision to make
+
+Never emit `AskUserQuestion` (or numbered batches) just because an agent activated. A question requires a *real* decision the user must make — a fork the work cannot proceed past without their input. When an agent loads without a stated task and no active feature requires continuation:
+
+1. Provide a brief informational summary drawn from already-loaded context (active feature, last gate, blockers, next recommendation)
+2. Stop and wait for the user to direct
+
+Fabricated multi-choice questions waste attention, invite arbitrary implementation paths, and corrode trust in the framework.
+
 ## Loading order
 
 1. Agent kernel preflight loads this `SKILL.md`.

package/template/AGENTS.md

@@ -9,6 +9,29 @@ You operate as AIOSON — an AI development squad with specialized agents.
    - If present: read it before any action
 3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
 
+## Memory loading
+
+Default **ON** in v1.15.0+. Opt out via `AIOSON_OPERATOR_MEMORY=false`.
+
+When enabled (default):
+
+1. Read `~/.aioson/operators/{sha256(git-email)[0..16]}/MEMORY.md` if it exists.
+2. For decisions whose title or signal_type matches the current task description: lazy-load `decisions/{slug}.md` from the same identity directory.
+3. Apply each loaded decision without re-asking the user — they were captured precisely so this conversation does not repeat past decisions.
+4. If a project rule in `.aioson/rules/` conflicts with a loaded decision, the project rule wins. Surface the warning emitted by the operator-memory layer to stderr; do not silently override.
+
+If `AIOSON_OPERATOR_MEMORY=false` is set: skip silently. Backward compatible.
+
+## Memory capture
+
+While conversing, watch for the 4 standing-decision signals defined in `template/agents/_shared/memory-capture-directive.md` (authorization, exclusion, correction, confirmation 2x+). When you detect one, emit:
+
+```bash
+aioson op:capture --signal=<type> --quote="<verbatim>" --proposal="<paraphrase>" --source-agent=<self>
+```
+
+Capture is best-effort — do not crash, retry, or surface failures to the user. The storage layer enforces the 2x promotion threshold and emits the 1-line audit on promotion.
+
 ## How to invoke agents
 
 **Option 1 — @ file include (Codex v0.110+):**

package/template/CLAUDE.md

@@ -9,6 +9,29 @@ You operate as AIOSON.
    - If present: read it before any action
 3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
 
+## Memory loading
+
+Default **ON** in v1.15.0+. Opt out via `AIOSON_OPERATOR_MEMORY=false`.
+
+When enabled (default):
+
+1. Read `~/.aioson/operators/{sha256(git-email)[0..16]}/MEMORY.md` if it exists.
+2. For decisions whose title or signal_type matches the current task description: lazy-load `decisions/{slug}.md` from the same identity directory.
+3. Apply each loaded decision without re-asking the user — they were captured precisely so this conversation does not repeat past decisions.
+4. If a project rule in `.aioson/rules/` conflicts with a loaded decision, the project rule wins. Surface the warning emitted by the operator-memory layer to stderr; do not silently override.
+
+If `AIOSON_OPERATOR_MEMORY=false` is set: skip silently. Backward compatible.
+
+## Memory capture
+
+While conversing, watch for the 4 standing-decision signals defined in `template/agents/_shared/memory-capture-directive.md` (authorization, exclusion, correction, confirmation 2x+). When you detect one, emit:
+
+```bash
+aioson op:capture --signal=<type> --quote="<verbatim>" --proposal="<paraphrase>" --source-agent=<self>
+```
+
+Capture is best-effort — do not crash, retry, or surface failures to the user. The storage layer enforces the 2x promotion threshold and emits the 1-line audit on promotion.
+
 ## Agents
 - /setup -> `.aioson/agents/setup.md`
 - /discovery-design-doc -> `.aioson/agents/discovery-design-doc.md`

package/template/agents/_shared/memory-capture-directive.md

@@ -0,0 +1,115 @@
+---
+name: memory-capture-directive
+schema_version: "1.0"
+ships_with: operator-memory v1.13.0+
+purpose: "Versioned prompt template defining the 4 signal types that agents observe and emit aioson op:capture for. Source-of-truth for signal detection heuristics; wired into agent preflight by Phase 3 universal loading directive."
+---
+
+# Memory Capture Directive (operator-memory v1.13.0)
+
+> **Loaded by:** the universal loading directive in `template/CLAUDE.md` / `template/AGENTS.md` (Phase 3, v1.14.0). Phase 2 ships this file dormant — Phase 3 wires it in.
+>
+> **Versioned:** if signal taxonomy changes in V2, bump `schema_version` and update the loading directive's reference. PMD-02 commitment: divergence from AIOSON's deterministic principle is documented and bounded.
+
+## What to watch for
+
+While conversing with the user, watch their messages for **standing decisions** — preferences they want applied to *future* sessions, not just the current turn. There are exactly 4 signal types in V1.
+
+### 1. Authorization
+
+User grants ongoing permission for an action. Look for: `pode X sempre`, `from now on X`, `não precisa me perguntar X`, `vai fazendo X`, `confio em você pra X`, `daqui pra frente X`.
+
+**Examples that ARE authorization:**
+
+- "pode commitar autonomamente sempre que aprovar a fatia"
+- "from now on, use TypeScript by default in new files"
+- "não precisa me perguntar antes de rodar npm test, pode rodar direto"
+
+**Examples that are NOT (do not capture):**
+
+- "agora pode commitar" → context-bound to current task, not standing
+- "ok faz isso" → simple agreement, not authorization
+
+### 2. Exclusion
+
+User explicitly carves out an action that they keep manual / restricted. Look for: `X eu faço manual`, `X nunca autonomamente`, `não X automaticamente`, `X sempre comigo`, `me deixa fazer X`.
+
+**Examples that ARE exclusion:**
+
+- "npm publish eu sempre faço manualmente"
+- "git push para main nunca autonomamente"
+- "deploy de produção é sempre comigo"
+
+**Examples that are NOT:**
+
+- "agora não publica" → context-bound
+- "espera eu testar" → temporal, not standing
+
+### 3. Correction
+
+User explicitly tells you to stop doing something or change behavior going forward. Look for: `não faça X`, `pare de X`, `stop doing X`, `evita X`, `nunca X`, `prefiro X em vez de Y`.
+
+**Examples that ARE correction:**
+
+- "stop adding emojis to commit messages"
+- "não faça mais resumos no fim de cada resposta"
+- "prefiro respostas curtas em vez de longas"
+
+**Examples that are NOT (likely one-shot):**
+
+- "neste arquivo prefiro brevidade" → file-scoped
+- "agora vai com cuidado" → session-scoped
+
+### 4. Confirmation (2x+ threshold)
+
+User accepts the same non-obvious approach twice without pushback. The 2x threshold is enforced by the storage layer — the prompt directive only needs to emit `op:capture` whenever the pattern repeats; the 2nd-detection promotion is automatic.
+
+**Examples that ARE confirmation worth capturing:**
+
+- User accepts the same unusual architectural choice across 2 PRs without questioning it
+- User repeatedly says "perfect, keep doing X" for an approach that wasn't obvious
+
+**Examples that are NOT:**
+
+- Single acceptance ("ok") — wait for repetition
+- Acceptance of trivially-correct approaches — no signal value
+
+## How to emit
+
+When you detect any of the 4 signals, emit this exact CLI call (best-effort — if it fails, do NOT crash the session):
+
+```bash
+aioson op:capture \
+  --signal=<authorization|exclusion|correction|confirmation> \
+  --quote="<verbatim user message>" \
+  --proposal="<your paraphrase of the standing decision>" \
+  --source-agent=<your-agent-name>
+```
+
+**Field guidance:**
+
+- `--quote` — the EXACT user words (verbatim) that triggered detection. Used for audit; trimmed automatically.
+- `--proposal` — your one-sentence paraphrase in user-facing language. This becomes the slug seed + the decision body. Be concrete: "commit autônomo após approval explícito de slice" beats "user authorized commits".
+- `--source-agent` — your own agent name (`dev`, `deyvin`, `pm`, etc.) so the audit trail knows which agent observed the signal.
+
+## When NOT to capture (anti-patterns)
+
+Suppress capture in these cases — they create noise that drowns real signal:
+
+1. **Context-bound preferences** — "neste PR prefiro brevidade" (PR-scoped, not standing).
+2. **Negotiations / questions** — "será que dá pra commitar autonomo?" (asking, not deciding).
+3. **Routine agreements** — "ok", "sim", "vai" without specific scope (no signal).
+4. **Apologies / corrections of immediate output** — "isso ficou errado, refaz" (immediate, not standing).
+5. **Test sessions** — if `AIOSON_OPERATOR_ID=test-*` or `_anonymous`, the capture happens but no decisions promote to global memory (storage layer handles isolation).
+6. **Conflict with project rules** — if a decision would conflict with `.aioson/rules/*.md`, the storage layer will surface a warning at preflight; you still capture (the conflict is logged, not silently dropped).
+
+## Capture is best-effort
+
+If `aioson op:capture` exits non-zero (CLI unavailable, storage failure, etc.), DO NOT crash the session, retry, or surface the failure to the user. The capture is informational — failure here is non-critical. Continue with the conversation normally.
+
+The storage layer (Phase 2 v1.13.0 onwards) handles:
+
+- Deterministic slug derivation (same paraphrase → same slug)
+- Idempotent capture (re-detection updates `last_detected`, increments `detected_count`)
+- 2x threshold promotion (proposal → decision atomic transition)
+- Silent operation on first detection; 1-line audit on promotion