@jaimevalasek/aioson 1.22.0 → 1.23.0

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

@@ -274,6 +274,19 @@ Goal: convert binary ACs from the enriched PRD into a machine-checkable contract
 
 Load `.aioson/docs/sheldon/harness-contract.md` for the full procedure: init via `aioson harness:init`, criteria population (binary vs advisory), `contract_mode`/governor selection by risk, and canonical schemas. Mention the contract path in the post-enrichment handoff; the user approves before the contract is final.
 
+## Retro dossier analysis (on-demand)
+
+Load this mode only when the user points you at a retrospective dossier produced by `aioson harness:retro` (`.aioson/context/retro/{slug}.md` or `window-last-{N}.md`). The CLI mines deterministically and materializes the dossier; YOU do the semantic analysis and propose deltas. The dossier is your evidence boundary.
+
+Procedure:
+1. Read the dossier. Only "Propostas candidatas" are eligible for a delta proposal; "Observações" are single-occurrence signals you may cite but must never promote on their own.
+2. Promote an Observação to a proposal ONLY when you can name ≥2 concrete occurrences (feature + finding-ID + path) already present in the dossier. Never invent occurrences the dossier does not list.
+3. Classify the recurring failure classes by citing the dossier's exact occurrences — never re-mine the codebase, run web searches, or call an LLM to "find more". The CLI already did the deterministic mining.
+4. Land accepted deltas EXCLUSIVELY in `.aioson/learnings/` (project gotchas/recipes) and `.aioson/rules/` (agent-loaded rules). Never edit code, specs, or other context files from this mode.
+5. Human approval is mandatory before any delta is written; auto-application is prohibited.
+
+If the dossier is empty (no candidates and no observations), say so and stop — do not fabricate retrospective conclusions.
+
 ## Hard constraints
 - **Never implement code** — role is exclusively PRD analysis and enrichment
 - **Never rewrite Vision, Problem, Users** — those sections belong to `@product`

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

@@ -181,6 +181,15 @@ Work module by module in priority order from the risk map:
 - If code under test has a real bug: report it in `test-plan.md`, do not fix silently
 - Do not modify production code (even small "just to make it testable" changes) — report untestable code instead
 
+**Large test logs — preview, not dump:** when a run emits a big log, redirect it to a file and read a preview + pointer instead of pasting the full output into context:
+
+```bash
+npm test > test-run.log 2>&1 || true
+aioson harness:preview test-run.log --max-bytes=8192
+```
+
+`harness:preview` is read-only (persist-first) and returns the first bytes plus a pointer to the full file. Open the full log only when the preview is insufficient.
+
 ## 4-Tier Verification Protocol (goal-backward)
 
 Verification starts from the goal - what the system must deliver - and works backward.
@@ -664,6 +673,14 @@ If `aioson` CLI is not available, update `.aioson/context/project-pulse.md` manu
 ## At session end
 Register: `aioson agent:done . --agent=tester --summary="<one-line summary>" 2>/dev/null || true`
 
+## Autopilot handoff (post-dev cycle)
+
+When `auto_handoff: true` is set in `project.context.md`, after the suite is delivered and `agent:done` is registered, return to the hub instead of stopping (`.aioson/docs/autopilot-handoff.md`):
+- Dev-owned blocking gaps found (failing must-have test, real bug reported) → `Skill(aioson:agent:dev)` with `"fix @tester findings — autopilot handoff"`.
+- Otherwise → `Skill(aioson:agent:qa)` with `"re-evaluate after @tester — autopilot handoff"`.
+
+Emit `Autopilot: @tester → invoking @<next> (Ctrl+C to interrupt)` first. Never auto-run `feature:close`. If `auto_handoff` is absent or `false`, hand off manually (recommend `@qa` or `@dev`).
+
 ## Continuation Protocol
 
 Append this block only after tests or test artifacts were actually written in the current session. Do not append it when waiting for user confirmation before Phase 4.

package/template/.aioson/agents/validator.md

@@ -103,6 +103,14 @@ Skip silently when the dossier is absent — `progress.json` remains the canonic
 ## Observability
 At session end, register: `aioson agent:done . --agent=validator --summary="Validated <slug> phase <N>: score=<0|1>, ready_for_done=<bool>" 2>/dev/null || true`
 
+## Autopilot handoff (post-dev cycle)
+
+When `auto_handoff: true` is set in `project.context.md`, after the verdict and `agent:done` (`.aioson/docs/autopilot-handoff.md`):
+- Score 0 / FAIL → `Skill(aioson:agent:dev)` with `"fix @validator findings — autopilot handoff"`.
+- Score 1 / PASS → **STOP**. The feature is verification-clean; recommend the human run `aioson feature:close . --feature={slug}`. **Never auto-run `feature:close`** — the close is the human gate.
+
+Emit `Autopilot: @validator → invoking @<next> (Ctrl+C to interrupt)` before invoking. If `auto_handoff` is absent or `false`, hand off manually.
+
 ---
 ## ▶ Next step
 The result will be written to `progress.json` by the gateway. Hand back to `@dev` for correction, or proceed to feature closure.

package/template/.aioson/docs/autopilot-handoff.md

@@ -1,46 +1,83 @@
----
-description: "Autopilot handoff protocol: automatic agent chaining from @analyst to the @dev handoff in the feature workflow, with deterministic routing and explicit stop conditions"
----
-
-# Autopilot handoff (analyst → dev)
-
-Opt-in protocol that removes manual handoff confirmations in the deterministic segment of the feature workflow. Participating agents: `@analyst`, `@scope-check`, `@architect`, `@discovery-design-doc`, and `@pm` (MEDIUM features only — it sits between `@discovery-design-doc` and pre-dev `@scope-check` to produce the implementation plan and close Gate C). Upstream agents (`@briefing`, `@product`, `@sheldon`) always stay manual — they end on genuine human decisions.
-
-## Activation
-
-Autopilot is active only when ALL are true:
-
-1. `project.context.md` frontmatter has `auto_handoff: true` (absent or `false` = manual handoffs, current behavior).
-2. A feature workflow is active (feature slug known, classification SMALL or MEDIUM).
-3. The current agent's own gate/verdict passed (see stop conditions).
-
-## Routing — deterministic, never LLM-chosen
-
-The next agent comes from the workflow state machine, not from model judgment:
-
-- CLI available: run `aioson workflow:next .` (inspect mode) and use the stage it reports, or the `next` field of `.aioson/context/workflow.state.json`.
-- CLI absent: follow the classification sequence in `.aioson/config.md` exactly.
-
-Never skip a stage, reorder, or pick an agent the state machine did not name.
-
-## Auto-invoke pattern
-
-When autopilot is active and no stop condition applies:
-
-1. Finish your own closing duties first (artifacts on disk, gate registration, `pulse:update`, `agent:done`).
-2. Emit a one-line transition notice: `Autopilot: @<current> done → invoking @<next> (Ctrl+C to interrupt)`.
-3. Invoke `Skill(aioson:agent:<next>)` with the task `"continue feature {slug} — autopilot handoff from @<current>"`. No user prompt — Ctrl+C interrupts.
-
-## Stop conditions — break the chain and emit the normal manual handoff
-
-1. **Next agent is `@dev`** — goal reached. Produce `dev-state.md` (dev handoff producer), emit the standard handoff message, and recommend `/clear` + a fresh chat for `@dev`. Never auto-invoke `@dev`.
-2. **Verdict not clean** — `@scope-check` status is anything other than `approved`/`patched` (`needs-*`, `blocked`): route per Handoff Rules, manually.
-3. **Gate or readiness blocked** — `@architect` Gate B blocked, `@discovery-design-doc` readiness = `blocked`, or `@pm` Gate C blocked: stop and route to the owner.
-4. **Context budget** — estimated context usage ≥ `context_warning_threshold` (`.aioson/config.md`): write the compaction checkpoint to `.aioson/context/last-handoff.json`, stop, and recommend `/clear`. The workflow resumes from `workflow.state.json` — the next session re-enters autopilot automatically.
-5. **Ambiguity** — workflow state unavailable AND classification/sequence ambiguous, or any real decision requires user input: stop and ask, manually.
-
-The user can interrupt at any time (Ctrl+C); autopilot never retries an interrupted invocation.
-
-## Rationale
-
-Industry-validated design (see `researchs/auto-handoff-pipeline-2026/summary.md`): deterministic routing beats LLM routing; human gates belong where they catch mistakes (pre-analyst and at @dev); every autonomous loop needs explicit exit conditions; per-hop context checkpointing is the load-bearing cost mitigation.
+---
+description: "Autopilot handoff protocol: automatic agent chaining across the feature workflow — the analyst→dev pre-dev chain and the post-dev review cycle (dev→qa→tester/pentester→validator) — with deterministic routing and explicit stop conditions. The chain never auto-runs feature:close/publish."
+---
+
+# Autopilot handoff (analyst → dev → review cycle)
+
+Opt-in protocol that removes manual handoff confirmations in the deterministic segments of the feature workflow. Two segments:
+
+1. **Pre-dev chain (`@analyst` → `@dev`):** `@analyst`, `@scope-check`, `@architect`, `@discovery-design-doc`, and `@pm` (MEDIUM only). Upstream agents (`@briefing`, `@product`, `@sheldon`) always stay manual — they end on genuine human decisions.
+2. **Post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` → `@validator`):** once a human starts `@dev`, the implementation and review agents chain automatically until the feature is ready to close. `@qa` is the hub: it owns the routing to the specialized agents and the corrections loop.
+
+## Activation
+
+Autopilot is active only when ALL are true:
+
+1. `project.context.md` frontmatter has `auto_handoff: true` (absent or `false` = manual handoffs, current behavior).
+2. A feature workflow is active (feature slug known, classification SMALL or MEDIUM).
+3. The current agent's own gate/verdict passed (see stop conditions).
+
+## Routing — deterministic, never LLM-chosen
+
+The next agent comes from the workflow state machine and on-disk evidence, not from model judgment:
+
+- CLI available: run `aioson workflow:next .` (inspect mode) and use the stage it reports, or the `next` field of `.aioson/context/workflow.state.json`.
+- CLI absent: follow the classification sequence in `.aioson/config.md` and the routing table below exactly.
+
+Never skip a stage, reorder, or pick an agent the state machine / routing table did not name.
+
+## Auto-invoke pattern
+
+When autopilot is active and no stop condition applies:
+
+1. Finish your own closing duties first (artifacts on disk, gate registration, dossier/spec updates, `pulse:update`, `agent:done`).
+2. Emit a one-line transition notice: `Autopilot: @<current> done → invoking @<next> (Ctrl+C to interrupt)`.
+3. Invoke `Skill(aioson:agent:<next>)` with the task `"continue feature {slug} — autopilot handoff from @<current>"`. No user prompt — Ctrl+C interrupts.
+
+## Segment 1 — pre-dev chain (`@analyst` → `@dev`)
+
+`@analyst` → `@scope-check` → `@architect` → `@discovery-design-doc` → (`@pm` on MEDIUM) → **STOP before `@dev`**.
+
+The pre-dev chain stops before the FIRST `@dev` activation. The human clears context (`/clear`) and starts implementation with a fresh budget — `@dev` is a heavy phase and benefits from a clean context window. Produce `dev-state.md` (the dev handoff producer), emit the standard handoff message, and recommend `/clear` + `/dev`. **Never auto-invoke the initial `@dev` entry.**
+
+## Segment 2 — post-dev review cycle (hub = `@qa`)
+
+Once a human starts `@dev` and it finishes, the chain resumes automatically. `@qa` is the hub; every specialized agent returns to it.
+
+Routing table (each row is followed only when autopilot is active and no stop condition applies):
+
+| Current | Condition | Auto-invoke |
+|---|---|---|
+| `@dev` (first pass) | tests green, gates clear, no open corrections cycle | `@qa` |
+| `@dev` (corrections) | corrections applied, tests green (`qa-dev-cycle.json` present) | `@qa` (re-verify) |
+| `@qa` | verdict **FAIL** (Critical/High) | `@dev` via the corrections auto-cycle (cap 2, security gate) |
+| `@qa` | verdict **PASS** + `@tester` trigger fires AND `@tester` not yet run clean | `@tester` |
+| `@qa` | verdict **PASS** + `@pentester` trigger fires AND `@pentester` not yet run clean | `@pentester` |
+| `@qa` | verdict **PASS** + harness contract present AND `@validator` not yet PASS | `@validator` |
+| `@qa` | verdict **PASS** + no pending trigger/contract | **STOP** — recommend the human run `aioson feature:close . --feature={slug}` |
+| `@tester` | surfaced dev-owned blocking gaps | `@dev` |
+| `@tester` | no dev-owned blocking gaps | `@qa` (re-evaluate / sign-off) |
+| `@pentester` | open `recommended_owner = dev` findings | `@dev` |
+| `@pentester` | no open dev-owned findings | `@qa` (re-evaluate / sign-off) |
+| `@validator` | PASS | **STOP** — recommend the human run `aioson feature:close` |
+| `@validator` | FAIL | `@dev` |
+
+**Trigger source for `@tester`/`@pentester`:** the existing `@qa` trigger logic (coverage gaps → `@tester`; sensitive surface auth/secrets/data/upload/external-URL/supply-chain → `@pentester`). The four agents are ALWAYS wired into the chain, but `@tester`/`@pentester` only EXECUTE when their trigger fires — otherwise `@qa` skips straight to the next routing row.
+
+**Re-entry guard (no infinite loops):** before auto-invoking a specialized agent, `@qa` checks on-disk evidence that it already ran clean this cycle (e.g. `security-findings-{slug}.json` clean → `@pentester` done; a tester coverage artifact present with no new gap → `@tester` done; `progress.json.ready_for_done_gate` / validator PASS recorded → `@validator` done). An agent that already returned clean is not re-invoked.
+
+## Stop conditions — break the chain and emit the normal manual handoff
+
+1. **`feature:close` / publish** — ALWAYS the human gate. When `@qa` (PASS, nothing pending) or `@validator` (PASS) is the last clean step, STOP and recommend `aioson feature:close . --feature={slug}`. Never auto-run `feature:close`, `feature:archive`, `npm publish`, or any publish/close action.
+2. **First `@dev` entry** — the pre-dev chain stops here (Segment 1). The human clears context and starts implementation.
+3. **Corrections cap reached** — the `@qa`↔`@dev` auto-cycle is bounded at 2 rounds (`qa-dev-cycle.json`); when exhausted, stop and escalate to the human.
+4. **Critical security finding** — the `@qa` corrections security gate (auth/secret/credential/session/password/token/PII/encryption keywords) blocks the auto-loop; stop and require human intervention.
+5. **Verdict not clean / gate or readiness blocked** — `@scope-check` not `approved`/`patched`, `@architect` Gate B blocked, `@discovery-design-doc` readiness `blocked`, `@pm` Gate C blocked, `@validator` FAIL with no safe corrections path: stop and route to the owner manually.
+6. **Context budget** — estimated usage ≥ `context_warning_threshold` (`.aioson/config.md`): write the compaction checkpoint to `.aioson/context/last-handoff.json`, stop, and recommend `/clear`. The workflow resumes from `workflow.state.json` — the next session re-enters autopilot automatically.
+7. **Ambiguity** — workflow state unavailable AND routing ambiguous, or any real decision requires user input: stop and ask, manually.
+
+The user can interrupt at any time (Ctrl+C); autopilot never retries an interrupted invocation.
+
+## Rationale
+
+Industry-validated design (see `researchs/auto-handoff-pipeline-2026/summary.md`): deterministic routing beats LLM routing; human gates belong where they catch mistakes — at the start of implementation (`@dev` entry: fresh context) and at the irreversible boundary (`feature:close`/publish). Every autonomous loop needs explicit exit conditions and bounds (the corrections cap, the re-entry guard); per-hop context checkpointing is the load-bearing cost mitigation.

package/template/.aioson/rules/aioson-context-boundary.md

@@ -28,10 +28,11 @@ Allowed machine-readable exceptions:
 | Project configuration | `.aioson/config.md` |
 | Conformance schema | `.aioson/context/conformance-{slug}.yaml` ← machine-readable exception |
 | Security findings | `.aioson/context/security-findings-{slug}.json` ← machine-readable exception |
-| Workflow handoff/runtime state | `.aioson/context/workflow.state.json`, `.aioson/context/handoff-protocol.json`, `.aioson/context/last-handoff.json` |
-| Parallel coordination machine files | `.aioson/context/parallel/*.json` |
-| Simple implementation plans | `.aioson/context/simple-plans/{slug}.md` |
-| Squad definitions | `.aioson/squads/{slug}/` |
+| Workflow handoff/runtime state | `.aioson/context/workflow.state.json`, `.aioson/context/handoff-protocol.json`, `.aioson/context/last-handoff.json` |
+| Parallel coordination machine files | `.aioson/context/parallel/*.json` |
+| Simple implementation plans | `.aioson/context/simple-plans/{slug}.md` |
+| Retrospective dossier | `.aioson/context/retro/{slug}.md` (or `window-last-{N}.md`) ← harness:retro |
+| Squad definitions | `.aioson/squads/{slug}/` |
 | Skill manifests | `.aioson/skills/{category}/{slug}/SKILL.md` |
 | Feature artifacts | `.aioson/context/{artifact}-{slug}.md` |
 | Project artifacts | `.aioson/context/{artifact}.md` |
@@ -46,10 +47,11 @@ architecture.md               ← architect
 ui-spec-{slug}.md             ← ux-ui
 prd.md / prd-{slug}.md        ← product
 spec-{slug}.md                ← dev
-implementation-plan-{slug}.md ← pm
-simple-plans/{slug}.md       ← dev / deyvin
-features.md                   ← product / pm
-project-pulse.md              ← all agents (update at session end)
+implementation-plan-{slug}.md ← pm
+simple-plans/{slug}.md       ← dev / deyvin
+retro/{slug}.md               ← harness:retro (retrospective dossier; window-last-{N}.md for windows)
+features.md                   ← product / pm
+project-pulse.md              ← all agents (update at session end)
 conformance-{slug}.yaml       ← conformance machine-readable exception
 security-findings-{slug}.json ← pentester/qa security findings exception
 workflow.state.json           ← workflow runtime exception

package/template/AGENTS.md

@@ -102,7 +102,7 @@ When running Codex directly (without `aioson workflow:next`), these rules apply:
 - For implementation requests (code changes, feature build, refactor, bugfix), default to workflow routing and execute via the next workflow stage agent (typically `@dev` after required upstream stages).
 - Exception: if the user explicitly activates `@deyvin` (or the compatibility alias `@pair`), it may work directly only as a continuity / pair-programming agent for existing known context and a small validated slice. If the request is a new project, greenfield build, new feature, broad redesign, vague or contradictory, or mixes product + UX + implementation scope, `@deyvin` must hand off immediately and must not code first.
 - Official workflow agents (`@setup`, `@product`, `@analyst`, `@scope-check`, `@architect`, `@ux-ui`, `@pm`, `@orchestrator`, `@dev`, `@qa`) must stay inside the workflow. Do not answer requests outside the current agent's scope.
-- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work. Single exception: when `auto_handoff: true` is set in `project.context.md`, the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping — never past the `@dev` handoff.
+- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work. Single exception: when `auto_handoff: true` is set in `project.context.md`, the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping. That chain stops before the first `@dev` activation (the human clears context and starts implementation) and resumes through the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their `@qa` triggers fire → `@validator`); it never auto-runs `feature:close`/publish — those require explicit human approval.
 - If `project.context.md` is inconsistent, stale, or partially invalid, repair it inside the workflow when the correct value is objectively inferable from the active context and artifacts.
 - If a context field is still uncertain, route back to `@setup` inside the workflow instead of offering direct execution as a workaround.
 - Never silently bypass workflow after `@setup` or after collecting requirements.

package/template/CLAUDE.md

@@ -103,7 +103,7 @@ When running Claude Code directly (without `aioson workflow:next`), these rules
 **Hard constraints — no exceptions:**
 - You MUST NEVER implement code, produce UI specs, write PRDs, or answer technical tasks outside an activated agent.
 - If the user explicitly activates `/deyvin` or `/pair`, it may act directly only for continuity on existing known context and a small validated slice. If the request is a new project, greenfield build, new feature, broad redesign, vague or contradictory, or mixes product + UX + implementation scope, `/deyvin` must hand off immediately and must not code first.
-- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work. Single exception: when `auto_handoff: true` is set in `project.context.md`, the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping — never past the `@dev` handoff.
+- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work. Single exception: when `auto_handoff: true` is set in `project.context.md`, the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping. That chain stops before the first `@dev` activation (the human clears context and starts implementation) and resumes through the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their `@qa` triggers fire → `@validator`); it never auto-runs `feature:close`/publish — those require explicit human approval.
 - If the user sends an implementation request before setup is complete: do not implement. Tell them to activate `/setup` first.
 - If the user insists on bypassing an agent stage: refuse and redirect. Urgency or complexity do not override this rule.