@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/en/deyvin-subtask-scout/sub-task-scout.md

@@ -0,0 +1,115 @@
+# What is the Sub-task Scout
+
+> The scout closes the item explicitly deferred in the `deyvin-density` feature (2026-05-11). The `@deyvin` rubric at line 111 read: "Diagnosis ambiguous; needs survey of >5 files or tracing a runtime flow → Spawn sub-task scout (deferred to `deyvin-subtask-scout`; until shipped: pause and ask the user)." Now there's a primitive.
+
+---
+
+## The problem
+
+Without the scout, `@deyvin` had two bad options when a question required inspecting many files:
+
+1. **Read everything inline** — burns ≥10k tokens in the parent context, pollutes the agent's working memory, and forces the next turn to compete with stale survey content.
+2. **Hand off to `/architect` or pause** — overshoots the actual need (most surveys don't require architectural decisions) and breaks the conversation flow with a full agent switch.
+
+The scout resolves this: the parent agent keeps its context lean and receives a structured report of ~500 tokens instead of the raw files.
+
+---
+
+## How it works
+
+### Full lifecycle
+
+```
+User asks @deyvin something that triggers rubric line 111
+(survey of >5 files or runtime flow tracing)
+         │
+         ▼
+aioson scout:prep --question="..." --scope-paths="a.js,b.js" ...
+  └─ validates inputs
+  └─ checks caps (session, scope)
+  └─ generates standardized prompt for sub-agent
+  └─ returns { id, prompt, output_path, cap_remaining }
+         │
+         ▼
+@deyvin calls harness.sub-agent(prompt)
+  └─ sub-agent runs in ISOLATED context
+  └─ allowed tools: [Read, Grep]
+  └─ disallowed tools: [Bash, Edit, Write]   ← Nautilus pattern
+  └─ writes JSON to output_path
+         │
+         ▼
+aioson scout:validate --input=<output_path>
+  └─ validates JSON against OUTPUT_SCHEMA
+  └─ PASS → proceed
+  └─ FAIL → increments retry; @deyvin re-prompts (max 1 retry)
+         │
+         ▼
+aioson scout:commit --input=<output_path>
+  └─ persists to .aioson/runtime/scouts/{id}.json
+  └─ decrements cap_remaining
+  └─ emits telemetry action=committed
+         │
+         ▼
+@deyvin reads findings, confidence, recommendation
+  └─ folds into user-facing reply
+  └─ parent context grew ~500 tokens (just the report)
+     vs inline survey: ~10k+ tokens (raw file contents)
+```
+
+### The report (OutputSchema)
+
+| Field | Type | What it is |
+|---|---|---|
+| `id` | string | Unique scout identifier (`scout-{slug}-{date}-{rand6}`) |
+| `parent_agent` | string | Dispatching agent (`"deyvin"` in V1) |
+| `parent_session_id` | string | Parent session ID (for cap tracking) |
+| `parent_session_excerpt` | string (50-1000 chars) | **Required.** Why the scout was dispatched — essential for cold-load by future agents |
+| `feature_slug` | string \| null | Active feature, if any |
+| `question` | string | The original question |
+| `scope` | object | Files and directories to inspect |
+| `findings[]` | array | Each finding: `file`, `line`, `evidence` (max 200 chars), `relevance`, `explanation` (20-300 chars) |
+| `confidence` | `"high" \| "medium" \| "low"` | Sub-agent's self-assessment |
+| `recommendation` | string (30-1000 chars) | What the parent agent should do next |
+| `files_inspected[]` | string[] | Files actually read |
+| `status` | `"success" \| "partial" \| "no_findings" \| "error"` | Final state |
+| `completed_at` | ISO string | Completion timestamp |
+
+---
+
+## The 3 phases of the feature
+
+### Phase 1 — `core-engine`
+Pure module `src/sub-task-engine.js`: prompt template builder, hand-rolled JSON validators (zero new dependencies), cap state management, lifecycle state. No I/O — only what the CLI commands explicitly invoke.
+
+### Phase 2 — `cli-verbs`
+Three CLI verbs (`scout:prep`, `scout:validate`, `scout:commit`) + state with file-lock in `src/sub-task-state.js`. Config template `template/.aioson/config/scout-engine.json` (empty `{}`; defaults active). Sandbox path check: `scope_paths` outside the project root are rejected.
+
+### Phase 3 — `wiring-and-lifecycle`
+- `deyvin.md` (workspace + template byte-identical, 13611 bytes, under 15360 limit): new "Sub-task scout invocation" section with CLI path + CLI-less fallback per harness (Claude Code Agent tool, Codex MultiAgentV2, Gemini/OpenCode with `harness_unsupported` message)
+- `feature:close`: archival hook copies scouts with matching `feature_slug` to `.aioson/context/features/{slug}/scouts/`, appends bullet to dossier
+- `memory:summary`: "Scouts dispatched: N (top topics: ...)" row always present — visible in agent cold-load bootstrap
+- `doctor`: `scouts_directory_pruning` advisory check (orphaned scouts >90d); `--fix` deletes them; scouts with `feature_slug` are **never** pruned
+
+---
+
+## Security patterns
+
+**Nautilus pattern** — tool whitelist on sub-agent:
+- Allowed: `[Read, Grep]`
+- Disallowed: `[Bash, Edit, Write]`
+- Applied via prompt template; harnesses that support explicit tool configuration also receive the whitelist as a parameter
+
+**Path sandbox** — `scope_paths` outside the project `rootDir` are rejected with `error.code = 'path_outside_root'`
+
+**Cap discipline** — no scout can exceed the configured limits; exceeding returns exit 2 before dispatching the sub-agent
+
+**`parent_session_excerpt` required** — blocked at `scout:prep` if absent. This field ensures future agents reading the archived scout in cold-load can reconstruct intent without any conversation history.
+
+---
+
+## Continue reading
+
+- [How to use](./how-to-use.md) — concrete step-by-step flows
+- [CLI reference](./cli-commands.md) — full flags
+- [Diagrams](./diagrams.md) — visual flow
+- [Troubleshooting](./troubleshooting.md) — known issues

package/docs/en/deyvin-subtask-scout/troubleshooting.md

@@ -0,0 +1,184 @@
+# Troubleshooting — Sub-task Scout
+
+---
+
+## Cap exceeded (`cap_exceeded`)
+
+**Symptom:** `aioson scout:prep` returns exit 2 with `error.code = "cap_exceeded"`.
+
+**Why it happens:** the `parent_session_id` has already dispatched `max_scouts_per_session` scouts in this session (default: 3).
+
+**Solutions:**
+
+1. **Consolidate scouts** — combine related questions into a single scout with a wider scope.
+2. **New session** — start a new session (new `parent_session_id`); caps are per session, not per project.
+3. **Increase the limit** in the project:
+
+```json
+// .aioson/config/scout-engine.json
+{ "max_scouts_per_session": 5 }
+```
+
+If the `cap_exceeded` rate exceeds 5% in real usage, the defaults are too tight — adjust them.
+
+---
+
+## Scope too large (`scope_too_large`)
+
+**Symptom:** `aioson scout:prep` returns `error.code = "scope_too_large"`.
+
+**Why it happens:** `scope_paths` resolved to more than `max_files_in_scope` files (default: 20).
+
+**Solutions:**
+
+1. **Specify concrete files** instead of directories:
+   ```bash
+   # instead of:
+   --scope-paths="src/"
+   # use:
+   --scope-paths="src/commands/workflow-next.js,src/handoff-contract.js"
+   ```
+
+2. **Increase the limit** in the project:
+   ```json
+   { "max_files_in_scope": 30 }
+   ```
+
+> Directories in `scope_paths` expand only 1 level deep (direct children). `scope_globs` is deferred to V2.
+
+---
+
+## Malformed JSON from sub-agent (`schema_invalid`)
+
+**Symptom:** `aioson scout:validate` returns exit 2 with `error.code = "schema_invalid"`.
+
+**Why it happens:** the sub-agent didn't produce JSON valid against `OUTPUT_SCHEMA`. Possible causes:
+- Required field missing (`parent_session_excerpt`, `confidence`, `recommendation`)
+- `confidence` with invalid value (must be `high`, `medium`, or `low`)
+- `evidence` or `explanation` exceeding character limits (200 and 300 respectively)
+- Extra keys (schema has `additionalProperties: false`)
+
+**Solution:** re-prompt the sub-agent with the exact error:
+
+```
+Your previous output failed validation:
+- findings[0].evidence: required field missing
+- confidence: must be one of: high, medium, low
+
+Re-run and produce valid JSON per the schema.
+```
+
+You have 1 retry (`max_retries_on_malformed_json=1`). If the second attempt also fails, the scout persists with `status: "error"` and `@deyvin` must handle it manually (handoff or direct answer).
+
+---
+
+## Retry exhausted (`retry_exhausted`)
+
+**Symptom:** `aioson scout:validate` returns `error.code = "retry_exhausted"`.
+
+**Why it happens:** the sub-agent failed validation twice in a row (prep + 1 retry).
+
+**What to do:**
+
+1. The scout was persisted with `status: "error"` at `.aioson/runtime/scouts/{id}.json`.
+2. `@deyvin` informs the user and offers handoff to `/architect` or a direct best-effort answer.
+3. To increase retries: `{ "max_retries_on_malformed_json": 2 }` in config (rarely needed — if it happens frequently, the prompt template needs tightening).
+
+---
+
+## Harness without sub-agent support (`harness_unsupported`)
+
+**Symptom:** Gemini CLI or OpenCode don't natively support the Agent tool / sub-agent.
+
+**What happens:** `scout:prep` returns normally, but the harness emits `harness_unsupported` when trying to dispatch the sub-agent.
+
+**Solution:** use the CLI-less fallback embedded in `deyvin.md`. The "Sub-task scout invocation — CLI-less fallback" section describes how to build the prompt manually and dispatch it via the Claude Code Agent tool, or adapt it for the available harness.
+
+The fallback produces the same JSON report, but without caps, SQLite telemetry, or automatic archival.
+
+---
+
+## State file lock stuck
+
+**Symptom:** `aioson scout:prep` (or `scout:commit`) hangs for more than 30 seconds.
+
+**Why it happens:** `.aioson/runtime/scouts/.state.json.lock` exists with the PID of a dead process.
+
+**Solution:**
+
+```bash
+# Check if the PID is still alive
+cat .aioson/runtime/scouts/.state.json.lock
+# { "pid": 12345, "lockedAt": "2026-05-14T10:00:00.000Z" }
+
+# If the process no longer exists, remove manually:
+rm .aioson/runtime/scouts/.state.json.lock
+```
+
+The lock is automatically declared stale after 30s — on the next CLI operation it will be overwritten without intervention.
+
+---
+
+## `parent_session_excerpt` blocked
+
+**Symptom:** `aioson scout:prep` returns `error.code = "input_invalid"` with `field: "parent_session_excerpt"`.
+
+**Why it happens:** the field is required (cannot be omitted or under 50 chars).
+
+**Why it exists:** future agents reading the archived scout in cold-load need to reconstruct context without any conversation history. The `parent_session_excerpt` is the only field that explains the WHY.
+
+**Solution:** pass an informative excerpt from the parent session (50-1000 chars):
+
+```bash
+--parent-session-excerpt="User reported bug where workflow:next inherits featureSlug from previous handoffs; investigating loadOrCreateState in workflow-next.js"
+```
+
+---
+
+## Orphaned scouts accumulating in `.aioson/runtime/scouts/`
+
+**Symptom:** `aioson doctor .` reports advisory `scouts_directory_pruning` with old scouts without `feature_slug`.
+
+**What they are:** scouts dispatched without `--feature-slug` or from features already closed whose `feature_slug` doesn't match any feature in `features.md`.
+
+**Solution:**
+
+```bash
+# Preview which would be pruned
+aioson doctor . --json | grep scouts_directory_pruning
+
+# Prune (deletes orphaned scouts >90d; NEVER prunes scouts with feature_slug)
+aioson doctor . --fix
+```
+
+To manually preserve an orphaned scout before pruning (e.g., for future auditing), copy it outside the runtime directory or associate it with a feature:
+
+```bash
+cp .aioson/runtime/scouts/{id}.json .aioson/context/features/{slug}/scouts/
+```
+
+---
+
+## `aioson update` overwrites `scout-engine.json`
+
+**Symptom:** customizations in `.aioson/config/scout-engine.json` are lost after `aioson update`.
+
+**Status:** current installer behavior (M-01 follow-up — see also the same issue for `learning-loop.json`). The fix (smart merge) is planned as a MICRO feature.
+
+**Workaround:** back up before running `aioson update`:
+
+```bash
+cp .aioson/config/scout-engine.json /tmp/scout-engine-backup.json
+aioson update
+# restore customizations manually
+```
+
+---
+
+## `scope_globs` not implemented
+
+**Symptom:** `error.code = "globs_not_implemented_v1"` when using `--scope-globs`.
+
+**Why:** Node 18-21 has no native `fs.glob`; adding a glob dependency would break V1's zero-deps policy.
+
+**Workaround:** use `scope_paths` with explicit files or directories (1-level expansion). Globs will be supported in V2.

package/docs/integrations/apps-publish-marketplace.md

@@ -0,0 +1,94 @@
+# `aioson system:publish` — Publicar apps no marketplace
+
+Como devs publicam apps via CLI no aioson.com para que clientes possam
+instalar via aioson-play.
+
+---
+
+## Comando
+
+```bash
+aioson system:publish [dir] [opções]
+```
+
+`[dir]` é o caminho da pasta do app (default: `.`). A pasta precisa ter
+`system.json` (manifesto) + `package.json` na raiz.
+
+### Opções
+
+| Flag | Efeito |
+|------|--------|
+| `--private` | Visibilidade privada (default é `public` → FREE no aioson-com) |
+| `--paid` | Marca como pago (requer plano Jedi) |
+| `--invite="email1,email2,..."` | Emails autorizados a instalar quando privado |
+| `--dry-run` | Valida e mostra o que seria enviado, sem publicar |
+
+### Emails autorizados (privates)
+
+Aceita 2 formas, com flag tendo precedência sobre o manifest:
+
+```bash
+aioson system:publish ./meu-app --private \
+  --invite="cliente1@empresa.com, cliente2@empresa.com"
+```
+
+Ou declarado no `system.json`:
+
+```json
+{
+  "slug": "meu-app",
+  "name": "Meu App",
+  "version": "1.0.0",
+  "authorized_emails": ["cliente1@empresa.com", "cliente2@empresa.com"]
+}
+```
+
+A lista é normalizada (lowercase, trim, dedup, validação básica de `@`).
+
+---
+
+## Fluxo no servidor
+
+`POST https://aioson.com/api/store/systems/publish` recebe:
+
+```json
+{
+  "kind": "aioson.store.system",
+  "slug": "meu-app",
+  "version": "1.0.0",
+  "files": { "system.json": "...", "package.json": "...", "src/...": "..." },
+  "manifest": { ... },
+  "visibility": "private",
+  "paid": false,
+  "authorizedEmails": ["cliente1@empresa.com"],
+  "workspaceSlug": null
+}
+```
+
+Server-side (`storePublishSystem` em `aioson-com/lib/store.ts`):
+1. Cria/atualiza `System` (visibility mapeada para enum: `private`→PRIVATE,
+   `public`→FREE, `paid`→PAID)
+2. Cria nova `SystemVersion` com `manifestJson` + `filesJson` + `packageHash`
+3. Quando privado: sincroniza tabela `SystemInvitee` (delete-then-insert)
+4. Retorna `{ ok, slug, version, packageHash, inviteeCount, quarantined }`
+
+---
+
+## Como o cliente instala
+
+Pelo aioson-play instalado:
+
+1. Login com email autorizado
+2. HomePage → Loja
+3. App aparece (filtrado por `getMarketplaceForUser`: visibilidade + invitee)
+4. Click no card → `POST /api/store/systems/install` → `storeInstallSystem`
+   valida visibilidade + invitee → devolve files+manifest
+5. Aioson-play extrai em `apps/{slug}/`
+
+---
+
+## Doc relacionada
+
+- `aioson-com/docs/apps-publish-install-spec.md` — spec consolidada do flow
+- `aioson-play/docs/aioson-app-developer-guide.md` §9 — visão do dev de app
+- `aioson-play/docs/dev-link-install.md` — alternativa pra dev (symlink)

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

@@ -1,76 +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
+# 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