@jaimevalasek/aioson 1.6.0 → 1.7.2

package/docs/integrations/sdlc-genius-boundary.md

@@ -0,0 +1,76 @@
+# SDLC Genius — Integration Boundary
+
+> Created: 2026-04-02
+> Status: pre-pilot — defines what the app is allowed and not allowed to influence
+
+---
+
+## Boundary Rule
+
+**AIOSON artifacts drive work. SDLC Genius may react to GitHub changes. SDLC Genius does not mutate AIOSON source-of-truth artifacts directly.**
+
+---
+
+## What SDLC Genius Must NOT Own
+
+These artifacts are AIOSON's exclusive responsibility:
+
+| Artifact | Owner | Reason |
+|----------|-------|--------|
+| `prd-{slug}.md` | @product | Product decisions require human + agent deliberation |
+| `requirements-{slug}.md` | @analyst | Business rules require structured discovery |
+| `spec-{slug}.md` | @analyst / @dev | Feature memory and phase gates are AIOSON's execution state |
+| `architecture.md` | @architect | Architecture decisions require full project context |
+| `design-doc*.md` | @architect / @discovery-design-doc | Scope decisions are AIOSON artifacts |
+| `implementation-plan*.md` | @dev / @orchestrator | Execution sequencing belongs to AIOSON |
+| `.aioson/constitution.md` | User | Never externally modified |
+| `.aioson/rules/` | User / @dev | Project conventions are internal |
+
+SDLC Genius must never write to these files, even indirectly.
+
+---
+
+## What SDLC Genius May Own Well
+
+These are appropriate surfaces for a GitHub execution assistant:
+
+| Surface | Notes |
+|---------|-------|
+| PR review comments | Secondary signal — complements @qa, does not replace it |
+| Test generation suggestions | Must be reviewed by developer before accepting |
+| Documentation nudges | Flags stale docs, does not rewrite them |
+| GitHub workflow insights | Metrics and visibility in GitHub context |
+| Code quality signals | Language-level feedback that AIOSON agents do not produce |
+
+---
+
+## How to Interpret SDLC Genius Output
+
+When SDLC Genius comments on a PR:
+
+1. **Check if the comment is already covered by AIOSON artifacts** — if `requirements-{slug}.md` or `spec-{slug}.md` already addresses the point, SDLC Genius is confirming what AIOSON decided
+2. **If the comment contradicts a spec decision** — do not change the code; flag the contradiction to the user for a spec update
+3. **If the comment is about language-level quality** (naming, type safety, unused imports) — act directly without spec update
+4. **If the comment suggests a new requirement** — this is a spec change; route to @product or @analyst, not directly to @dev
+
+---
+
+## Conflict Resolution
+
+When SDLC Genius output conflicts with AIOSON artifacts:
+
+**AIOSON artifact wins.** Always.
+
+The spec is the single source of truth. SDLC Genius is a secondary signal.
+
+If a conflict repeats across multiple PRs, this is a signal that the spec may need updating — not that SDLC Genius is right.
+
+---
+
+## What Happens When the Pilot Ends
+
+After the pilot evaluation (Plan 70 Phase 5):
+
+- **Outcome A (adopt):** this boundary document becomes a standing operating note, promoted to `template/.aioson/docs/sdlc-genius-operating-mode.md`
+- **Outcome B (limited use):** this document is updated to reflect the narrower scope approved
+- **Outcome C (reject):** this document is archived; SDLC Genius is uninstalled

package/docs/integrations/sdlc-genius-eval-matrix.md

@@ -0,0 +1,75 @@
+# SDLC Genius — Evaluation Rubric
+
+> Created: 2026-04-02
+> Purpose: Measure pilot PR reviews against consistent criteria
+> Use: Fill one row per tested PR in `sdlc-genius-review-samples.md`
+
+---
+
+## Evaluation Axes
+
+For each PR where SDLC Genius commented, score each axis from 0 to 3:
+
+| Axis | 0 | 1 | 2 | 3 |
+|------|---|---|---|---|
+| **Relevance** | Comments are unrelated to the change | Partially related | Mostly related | Directly addresses the actual change |
+| **Signal** | No real bugs/risks caught | Low-value noise | Caught something worth reviewing | Caught a real bug or risk not found elsewhere |
+| **Duplication** | Repeats exactly what AIOSON/QA already enforced | Significant overlap | Some overlap | Adds information not in AIOSON artifacts |
+| **Actionability** | Developer cannot act without research | Possible but unclear | Actionable with context | Developer can act immediately |
+| **Traceability** | Cannot link to spec or requirements | Vague connection | Connects to requirements | Explicitly references behavior in spec |
+| **Noise risk** | Too many low-value comments per PR | Several noise comments | Occasional noise | Clean, focused output |
+
+**Score range per PR:** 0–18
+
+---
+
+## Score Interpretation
+
+| Total | Interpretation |
+|-------|---------------|
+| 15–18 | Excellent — strong signal, low noise, high actionability |
+| 10–14 | Good — useful but with improvements needed |
+| 5–9 | Marginal — some value but noise outweighs it in current state |
+| 0–4 | Poor — does not improve on AIOSON-only workflow |
+
+---
+
+## Comparison Against AIOSON Artifacts
+
+For each scored PR, also answer:
+
+| Question | Yes / Partial / No |
+|----------|-------------------|
+| Did SDLC Genius comment on something already in `requirements-{slug}.md`? | |
+| Did SDLC Genius comment on something already in `spec-{slug}.md`? | |
+| Did SDLC Genius catch something AIOSON artifacts missed? | |
+| Did SDLC Genius suggest a change that contradicts a spec decision? | |
+
+---
+
+## Noise Threshold
+
+If more than 30% of comments per PR are scored 0–1 on Relevance or Actionability, the PR is flagged as **noise-dominated**.
+
+A pilot with more than 2 noise-dominated PRs out of 5 tested = Outcome C (reject) unless tuning options exist and reduce noise significantly.
+
+---
+
+## Pilot Conclusion Criteria
+
+| Condition | Suggested Outcome |
+|-----------|------------------|
+| Average score ≥ 12 across 5+ PRs, no spec contradictions | Outcome A — Adopt |
+| Average score 7–11, useful in narrow scope (e.g., code quality only) | Outcome B — Limited use |
+| Average score < 7, OR repeated spec contradictions, OR noise-dominated | Outcome C — Reject |
+| Permissions too broad and cannot be scoped | Outcome C — Reject regardless of score |
+
+---
+
+## How to Use This Matrix
+
+1. Run the pilot PR (see Phase 2 of Plan 70)
+2. For each PR where SDLC Genius commented, score each axis
+3. Record in `sdlc-genius-review-samples.md` with the score, evidence, and comparison against AIOSON artifacts
+4. After 5+ PRs, sum up and apply the conclusion criteria above
+5. Write outcome in `plans/70.1-RESULT-sdlc-genius-pilot.md`

package/docs/integrations/sdlc-genius-install-checklist.md

@@ -0,0 +1,93 @@
+# SDLC Genius — Pilot Install and Rollback Checklist
+
+> Created: 2026-04-02
+> Status: template — fill in before installation
+> Purpose: Ensure the pilot is safe, scoped, and reversible before any installation
+
+---
+
+## Pre-Installation Gate
+
+Do NOT proceed with installation until ALL of the following are confirmed:
+
+- [ ] Plan 69 Phase 0 is complete (process-skill reference debt fixed)
+- [ ] `docs/integrations/sdlc-genius-boundary.md` is read and understood by the pilot owner
+- [ ] Public evaluation questions in `searchings/sdlc-genius-public-evaluation.md` are answered
+- [ ] Privacy policy at https://sof.to/privacy-policy has been reviewed
+- [ ] Pilot repo is chosen and is NOT a production-critical repo
+- [ ] At least one person knows how to uninstall the app
+
+---
+
+## Pilot Scope
+
+| Field | Value |
+|-------|-------|
+| Pilot repo | _(fill in)_ |
+| Installer name | _(fill in)_ |
+| Install date | _(fill in)_ |
+| Planned end date | _(fill in)_ |
+| Organization | _(fill in)_ |
+
+---
+
+## Permissions Review
+
+Before installation, verify and record the permissions the app requests:
+
+| Permission | Requested? | Acceptable? | Notes |
+|------------|-----------|-------------|-------|
+| Repository read (code) | _(confirm)_ | _(yes/no)_ | |
+| Repository write (pull requests) | _(confirm)_ | _(yes/no)_ | |
+| Repo limited to pilot repo only | _(confirm)_ | _(yes/no)_ | |
+| Org-wide access | _(confirm)_ | _(yes/no/reject)_ | Reject if org-wide and cannot scope |
+| Other permissions | _(list any)_ | _(yes/no)_ | |
+
+**If org-wide write access cannot be scoped to a single repo: DO NOT INSTALL.**
+
+---
+
+## Rollback Path
+
+| Step | Owner | Done? |
+|------|-------|-------|
+| Identify uninstall path in GitHub App settings | _(name)_ | [ ] |
+| Confirm the pilot repo reverts to normal after uninstall | _(name)_ | [ ] |
+| Identify who has permissions to uninstall | _(name)_ | [ ] |
+| Document uninstall steps here | _(fill in)_ | [ ] |
+
+Uninstall steps:
+```
+1. _(fill in after confirming from GitHub App settings)_
+2. 
+3. 
+```
+
+---
+
+## Safety Settings to Verify Before First PR
+
+- [ ] SDLC Genius comments are visible but not blocking (no required status checks set)
+- [ ] The app cannot merge PRs automatically
+- [ ] The app cannot push commits to the repo
+- [ ] A pilot owner has verified the first comment output before telling others to use it
+
+---
+
+## Rollback Owner
+
+| Role | Name |
+|------|------|
+| Pilot owner (decision to install) | _(fill in)_ |
+| Uninstall owner (authorized to remove) | _(fill in)_ |
+| Privacy review owner | _(fill in)_ |
+
+---
+
+## Post-Pilot Disposition
+
+At the end of the pilot, one of the following applies:
+
+- [ ] **Keep** — update boundary doc, promote to template
+- [ ] **Keep with limits** — update scope in boundary doc, document narrow use
+- [ ] **Remove** — uninstall, archive this checklist, record reason in `plans/70.1-RESULT-sdlc-genius-pilot.md`

package/docs/integrations/sdlc-genius-review-samples.md

@@ -0,0 +1,86 @@
+# SDLC Genius — Pilot Evidence Log
+
+> Created: 2026-04-02
+> Status: template — fill during pilot
+> Purpose: Record concrete PR review samples for final evaluation
+
+---
+
+## How to Use This File
+
+For each PR where SDLC Genius commented during the pilot:
+
+1. Copy one sample block below
+2. Fill in the PR details and SDLC Genius output
+3. Score each axis using the rubric in `sdlc-genius-eval-matrix.md`
+4. Record the comparison against AIOSON artifacts
+5. Write a 1-line decision: keep / tune / reject
+
+---
+
+## Sample Block Template
+
+```
+### PR #N — [short description of change]
+
+**Date:** YYYY-MM-DD
+**Repo:** [repo name]
+**Feature slug (if any):** [slug or none]
+
+**Most useful SDLC Genius comment:**
+> [paste comment]
+
+**Least useful SDLC Genius comment:**
+> [paste comment]
+
+**Total SDLC Genius comments on this PR:** N
+
+**Axis scores (0–3 each):**
+- Relevance:
+- Signal:
+- Duplication:
+- Actionability:
+- Traceability:
+- Noise risk:
+- **Total:** /18
+
+**AIOSON comparison:**
+- Did requirements-{slug}.md already cover the main SDLC Genius point? Yes / No / Partial
+- Did spec-{slug}.md already cover it? Yes / No / Partial
+- Did SDLC Genius catch something AIOSON missed? Yes / No
+- Did SDLC Genius contradict a spec decision? Yes / No — if yes, describe:
+
+**Decision:** keep / tune / reject
+**Reason:** [1 line]
+```
+
+---
+
+## PR Samples
+
+_(Empty — fill during pilot)_
+
+---
+
+## Running Totals
+
+| PR | Score | Noise-dominated? | Spec contradiction? |
+|----|-------|-----------------|---------------------|
+| #1 | /18 | | |
+| #2 | /18 | | |
+| #3 | /18 | | |
+| #4 | /18 | | |
+| #5 | /18 | | |
+| **Average** | /18 | | |
+
+---
+
+## Preliminary Conclusion
+
+_(Fill after 5+ PRs — apply criteria from `sdlc-genius-eval-matrix.md`)_
+
+- Average score: /18
+- Noise-dominated PRs: / tested
+- Spec contradictions: 
+- Suggested outcome: A / B / C
+- Next step: write `plans/70.1-RESULT-sdlc-genius-pilot.md`

package/docs/pt/README.md

@@ -25,6 +25,9 @@ Bem-vindo à documentação em português do AIOSON — um framework leve de age
 | [Cache de Contexto](./cache-de-contexto.md) | Salvar snapshots de contexto e restaurar entre sessões |
 | [Sandbox de Execução](./sandbox.md) | Executar comandos com timeout, redação de secrets e summarização de output |
 | [Agent Sharding](./agent-sharding.md) | Carregar apenas as seções relevantes de instruções de agente para uma tarefa específica |
+| [Spec & Learnings Pipeline](./spec-learnings-pipeline.md) | Sincronizar specs Markdown com o SQLite, exportar learnings para brains e acompanhar progresso de features |
+| [Devlog Pipeline](./devlog-pipeline.md) | Processar devlogs manuais dos agentes, sincronizar artifacts/learnings/verdict com o SQLite e exportar para brains |
+| [Hooks & Session Guard](./hooks-session-guard.md) | Visibilidade automática no dashboard para Claude Code, Antigravity e Codex — instalar hooks, session:guard e diagnóstico |
 
 ## Documentação em inglês
 

package/docs/pt/agentes.md

@@ -666,6 +666,7 @@ Duração típica: dias a semanas. Análise completa, paralelismo, backlog forma
 
 ## Veja também
 
+- [Fluxo de artefatos entre agentes](./fluxo-artefatos.md) — o que cada agente produz, o que @dev lê de fato e como o plano do Sheldon chega à implementação
 - [Cenários completos com exemplos práticos](./cenarios.md)
 - [Início rápido](./inicio-rapido.md)
 - [Guia do engenheiro: pair programming com IA](./guia-engineer.md)