@jaimevalasek/aioson 1.8.0 → 1.9.0

package/docs/en/deyvin-subtask-scout/cli-commands.md

@@ -0,0 +1,248 @@
+# CLI Reference — Sub-task Scout
+
+> Three verbs. Each section covers the full contract: flags, behavior, exit codes, output examples.
+
+---
+
+## `aioson scout:prep`
+
+Prepares a scout: validates inputs, checks caps, generates the standardized sub-agent prompt.
+
+**Tier:** 1 (silent — no output by default; use `--json`)
+
+```
+aioson scout:prep [path]
+  --question="<text>"
+  --scope-paths="<path1>,<path2>"
+  --parent-agent=<name>
+  --parent-session-id=<id>
+  --parent-session-excerpt="<text>"
+  [--feature-slug=<slug>]
+  [--json]
+```
+
+### Flags
+
+| Flag | Required | Description |
+|---|---|---|
+| `--question="<text>"` | yes | Question the sub-agent must answer |
+| `--scope-paths="<paths>"` | yes (or `--scope-globs`¹) | Files and directories to inspect, comma-separated. Directories expand 1 level |
+| `--parent-agent=<name>` | yes | Dispatching agent. In V1, only `"deyvin"` is accepted |
+| `--parent-session-id=<id>` | yes | Parent session ID — used to track caps per session |
+| `--parent-session-excerpt="<text>"` | yes | Why the scout was dispatched (50-1000 chars). Blocked if absent — this is the cold-load comprehension field |
+| `--feature-slug=<slug>` | no | Associated feature (for automatic archival on `feature:close`) |
+| `--json` | no | JSON output (`{ ok, id, prompt, output_path, cap_remaining }`) |
+
+¹ `--scope-globs` is deferred to V2 (Node 18-21 has no built-in `fs.glob`). If passed, returns `error.code = "globs_not_implemented_v1"`.
+
+### Behavior
+
+1. Validates all required fields.
+2. Resolves `scope_paths`: relative → absolute, verifies they stay within `rootDir`.
+3. Checks caps: `max_scouts_per_session` and `max_files_in_scope`.
+4. Increments `scouts_in_session` in state file (with file-lock).
+5. Generates standardized prompt with question, scope, output schema, and tool whitelist (`[Read, Grep]` / `[Bash, Edit, Write]` disallowed).
+6. Returns `{ id, prompt, output_path, cap_remaining }`.
+
+### Exit codes
+
+| Code | When |
+|---|---|
+| 0 | Scout prepared successfully |
+| 2 | Invalid argument, cap exceeded, scope too large, path outside root |
+
+### Examples
+
+```bash
+# Basic with JSON
+aioson scout:prep \
+  --question="Where is the previous featureSlug not cleared in workflow:next?" \
+  --scope-paths="src/commands/workflow-next.js,src/handoff-contract.js" \
+  --parent-agent=deyvin \
+  --parent-session-id=sess-abc123 \
+  --parent-session-excerpt="User reported state inheritance bug; need to inspect loadOrCreateState logic" \
+  --json
+```
+
+```json
+{
+  "ok": true,
+  "id": "scout-2026-05-14-a3b7c1",
+  "prompt": "You are a read-only code survey sub-agent...",
+  "output_path": ".aioson/runtime/scouts/scout-2026-05-14-a3b7c1.json",
+  "cap_remaining": 2
+}
+```
+
+Cap error:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "cap_exceeded",
+    "message": "max_scouts_per_session=3 reached for parent_session_id=sess-abc123",
+    "remediation": "Override .aioson/config/scout-engine.json or open a new session"
+  }
+}
+```
+
+---
+
+## `aioson scout:validate`
+
+Validates the JSON returned by the sub-agent against the output schema. Tracks retries in the state file.
+
+**Tier:** 1 (silent)
+
+```
+aioson scout:validate [path] --input=<path-to-json> [--json]
+```
+
+### Flags
+
+| Flag | Required | Description |
+|---|---|---|
+| `--input=<path>` | yes | Path to the JSON file the sub-agent wrote |
+| `--json` | no | JSON output |
+
+### Behavior
+
+1. Reads the file at `--input`.
+2. Validates against `OUTPUT_SCHEMA` (strict: `additionalProperties: false`).
+3. Increments `retries_by_id[id]` in state file.
+4. If `retries_by_id[id] > max_retries_on_malformed_json` → returns `retry_exhausted` without testing the schema.
+
+### Output schema summary (what the sub-agent must produce)
+
+```json
+{
+  "id": "scout-{slug?}-{date}-{rand6}",
+  "parent_agent": "deyvin",
+  "parent_session_id": "sess-abc123",
+  "parent_session_excerpt": "...",
+  "feature_slug": null,
+  "question": "...",
+  "scope": { "paths": [...], "files_requested": [...] },
+  "findings": [
+    {
+      "file": "src/commands/workflow-next.js",
+      "line": 42,
+      "evidence": "loadOrCreateState checks featureSlug but does not reset on feature transition",
+      "relevance": "high",
+      "explanation": "..."
+    }
+  ],
+  "confidence": "high",
+  "recommendation": "...",
+  "files_inspected": [...],
+  "status": "success",
+  "completed_at": "2026-05-14T10:00:00.000Z"
+}
+```
+
+### Exit codes
+
+| Code | When |
+|---|---|
+| 0 | JSON valid against output schema |
+| 2 | Schema invalid, retry exhausted, file not found |
+
+### Examples
+
+```bash
+aioson scout:validate --input=.aioson/runtime/scouts/scout-2026-05-14-a3b7c1.json
+
+# With detailed JSON on failure:
+aioson scout:validate --input=... --json
+```
+
+Failure output:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "schema_invalid",
+    "details": [
+      { "field": "findings[0].evidence", "reason": "required field missing" },
+      { "field": "confidence", "reason": "must be one of: high, medium, low" }
+    ]
+  },
+  "retry_remaining": 1
+}
+```
+
+---
+
+## `aioson scout:commit`
+
+Persists the validated report, emits telemetry, decrements the cap counter.
+
+**Tier:** 1 (silent)
+
+```
+aioson scout:commit [path] --input=<path-to-json> [--json]
+```
+
+### Flags
+
+| Flag | Required | Description |
+|---|---|---|
+| `--input=<path>` | yes | Path to the validated JSON |
+| `--json` | no | JSON output |
+
+### Behavior
+
+1. Reads the file at `--input`.
+2. Checks if the `id` was already committed in this session (idempotent — re-commit is a no-op with `committed: false, reason: 'already_committed'`).
+3. Copies the file to `.aioson/runtime/scouts/{id}.json`.
+4. Emits `runtime:emit type=sub_task action=committed` to `agent_events`.
+5. Decrements `scouts_in_session` in state file (clamped to 0).
+6. Records `committed_ids[id] = true` in state file.
+
+> **Idempotency:** the sub-agent may write the report to `output_path` before `scout:commit` runs, so the file already exists at the target on first commit. The idempotency check uses `committed_ids` in state (not file presence) — this ensures the first commit always processes correctly.
+
+### Exit codes
+
+| Code | When |
+|---|---|
+| 0 | Committed successfully (or no-op if already committed) |
+| 1 | File not found, state lock failure, telemetry failure |
+
+### Examples
+
+```bash
+aioson scout:commit --input=.aioson/runtime/scouts/scout-2026-05-14-a3b7c1.json
+
+# With JSON:
+aioson scout:commit --input=... --json
+```
+
+```json
+{
+  "ok": true,
+  "committed": true,
+  "id": "scout-2026-05-14-a3b7c1",
+  "path": ".aioson/runtime/scouts/scout-2026-05-14-a3b7c1.json",
+  "cap_remaining": 1
+}
+```
+
+Re-commit (idempotent):
+
+```json
+{
+  "ok": true,
+  "committed": false,
+  "reason": "already_committed"
+}
+```
+
+---
+
+## Continue reading
+
+- [How to use](./how-to-use.md) — concrete flows
+- [Diagrams](./diagrams.md) — visual flow
+- [Troubleshooting](./troubleshooting.md) — known issues

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

@@ -0,0 +1,124 @@
+# Diagrams — Sub-task Scout
+
+---
+
+## Full dispatch flow
+
+```
+User asks @deyvin something that triggers rubric line 111
+(survey of >5 files or runtime flow tracing)
+         │
+         ▼
+┌─────────────────────────────────────────────────────────────┐
+│  aioson scout:prep                                          │
+│  ─────────────────                                          │
+│  1. Validates inputs (question, scope, excerpt required)   │
+│  2. Resolves scope_paths → absolute paths                   │
+│  3. Checks caps: scouts_in_session < max (3) ?             │
+│                  scope_size < max_files (20) ?              │
+│  4. Increments scouts_in_session in state file             │
+│  5. Generates prompt with tool whitelist [Read, Grep]      │
+│  6. Returns { id, prompt, output_path, cap_remaining }     │
+└──────────────────────────────┬──────────────────────────────┘
+                               │ exit 0
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│  harness.sub-agent(prompt)    ← ISOLATED CONTEXT           │
+│  ────────────────────────                                   │
+│  tools: [Read, Grep] ONLY                                   │
+│  disallowed: [Bash, Edit, Write]  ← Nautilus pattern       │
+│                                                             │
+│  sub-agent inspects scope_paths                             │
+│  writes JSON to output_path                                 │
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│  aioson scout:validate --input=<output_path>                │
+│  ───────────────────────────────────────────                │
+│  validates against OUTPUT_SCHEMA                            │
+│  updates retries_by_id in state                             │
+└──────────┬───────────────────────────────┬──────────────────┘
+           │ PASS (exit 0)                 │ FAIL (exit 2)
+           ▼                               ▼
+┌──────────────────────────┐   ┌───────────────────────────────┐
+│ aioson scout:commit      │   │ retry_remaining > 0?          │
+│ ────────────────────     │   │  yes → @deyvin re-prompts     │
+│ persists scout JSON      │   │  no → retry_exhausted         │
+│ decrements cap           │   │        status: "error"        │
+│ emits telemetry          │   │        @deyvin informs user   │
+└──────────┬───────────────┘   └───────────────────────────────┘
+           │
+           ▼
+┌──────────────────────────────────────────────────────────────┐
+│ @deyvin reads findings, confidence, recommendation           │
+│ folds into user-facing reply                                 │
+│                                                              │
+│ parent context grew: ~500 tokens (report)                   │
+│ vs inline survey:    ~10k+ tokens (raw files)               │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Archival on feature:close
+
+```
+aioson feature:close --slug=<s> --verdict=PASS
+         │
+         ▼
+ (hook in feature:close Phase 5)
+         │
+         ├─ scans .aioson/runtime/scouts/ for files with feature_slug=<s>
+         │
+         ├─ for each matching scout:
+         │    ├─ copies to .aioson/context/features/<s>/scouts/{id}.json
+         │    └─ appends bullet to dossier.md > ## Sub-task scouts (idempotent)
+         │
+         └─ emits telemetry type=sub_task action=archived_on_close
+         
+ (runtime copies remain in .aioson/runtime/scouts/ — pruned by doctor)
+```
+
+---
+
+## Pruning by doctor
+
+```
+aioson doctor . [--fix]
+         │
+         ├─ check: scouts_directory_pruning
+         │    ├─ reads .aioson/config/scout-engine.json → prune_unattached_after_days (default: 90)
+         │    ├─ lists .aioson/runtime/scouts/*.json
+         │    │    ├─ has feature_slug? → NEVER prune (cold-load memory)
+         │    │    └─ no feature_slug + age > threshold? → candidate
+         │    └─ without --fix: reports count as advisory WARN
+         │       with --fix: deletes candidates
+```
+
+---
+
+## State file and file-lock
+
+```
+.aioson/runtime/scouts/.state.json
+{
+  "sessions": {
+    "sess-abc123": {
+      "scouts_in_session": 2,      ← incremented on prep, decremented on commit
+      "retries_by_id": {
+        "scout-2026-05-14-a3b7c1": 0
+      },
+      "committed_ids": {
+        "scout-2026-05-14-a3b7c1": true
+      }
+    }
+  }
+}
+
+Lock: .aioson/runtime/scouts/.state.json.lock
+  ├─ content: { pid, lockedAt (ISO) }
+  ├─ stale if age > 30s
+  ├─ retry every 100ms, deadline 30s
+  └─ created on prep/commit/validate; removed after operation
+```

package/docs/en/deyvin-subtask-scout/how-to-use.md

@@ -0,0 +1,221 @@
+# How to use the Sub-task Scout
+
+> Concrete examples. `@deyvin` uses the scout automatically when rubric line 111 fires. This page shows what happens under the hood and how to intervene when needed.
+
+---
+
+## 1. Happy path — successful scout
+
+Scenario: the user asks `@deyvin` why `workflow:next` sometimes inherits completion records from a previous feature.
+
+`@deyvin` identifies that the answer requires inspecting multiple files and dispatches a scout:
+
+**Step 1 — Prepare the scout**
+
+```bash
+aioson scout:prep \
+  --question="Why does workflow:next inherit completion records from previous features?" \
+  --scope-paths="src/commands/workflow-next.js,src/handoff-contract.js" \
+  --parent-agent=deyvin \
+  --parent-session-id=sess-abc123 \
+  --parent-session-excerpt="User reported bug where workflow:next inherits previous featureSlug on new handoffs; need to inspect loadOrCreateState and handoff-contract to identify where the old featureSlug is not cleared" \
+  --feature-slug=current-feature
+```
+
+Output (`--json`):
+
+```json
+{
+  "ok": true,
+  "id": "scout-current-feature-2026-05-14-a3b7c1",
+  "prompt": "You are a read-only code survey sub-agent...\n[full prompt]",
+  "output_path": ".aioson/runtime/scouts/scout-current-feature-2026-05-14-a3b7c1.json",
+  "cap_remaining": 2
+}
+```
+
+**Step 2 — Call the sub-agent**
+
+`@deyvin` uses the harness's sub-agent capability (Claude Code `Agent` tool or Codex sub-agent) with the returned `prompt`. The sub-agent runs in isolated context, uses only `Read` and `Grep`, and writes the result to `output_path`.
+
+**Step 3 — Validate**
+
+```bash
+aioson scout:validate --input=.aioson/runtime/scouts/scout-current-feature-2026-05-14-a3b7c1.json
+```
+
+Exit 0 = PASS. The file is valid against the output schema.
+
+**Step 4 — Commit**
+
+```bash
+aioson scout:commit --input=.aioson/runtime/scouts/scout-current-feature-2026-05-14-a3b7c1.json
+```
+
+Scout persisted, cap decremented (2→1), telemetry emitted.
+
+**Step 5 — @deyvin reads and responds**
+
+`@deyvin` reads `findings`, `confidence`, and `recommendation` from the JSON and folds the answer into the user-facing reply. Parent context grew ~500 tokens instead of ~10k+.
+
+---
+
+## 2. Invalid JSON recovery
+
+The sub-agent returned malformed JSON (required field missing):
+
+```bash
+aioson scout:validate --input=.aioson/runtime/scouts/scout-abc.json
+# exit 2
+```
+
+Output:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "schema_invalid",
+    "details": [
+      { "field": "findings[0].evidence", "reason": "required field missing" },
+      { "field": "confidence", "reason": "must be one of: high, medium, low" }
+    ]
+  },
+  "retry_remaining": 1
+}
+```
+
+`@deyvin` re-prompts the sub-agent with the explicit validation failures. On second attempt, if PASS → commit. If FAIL again → `retry_exhausted`:
+
+```json
+{
+  "ok": false,
+  "error": { "code": "retry_exhausted" },
+  "retry_remaining": 0
+}
+```
+
+Scout persists with `status: "error"`. `@deyvin` informs the user and offers manual handoff to `/architect` if needed.
+
+---
+
+## 3. Cap exceeded
+
+The agent tries to dispatch a 4th scout in the same session, but the default is 3:
+
+```bash
+aioson scout:prep --question="..." --scope-paths="..." --parent-agent=deyvin --parent-session-id=sess-abc123 --parent-session-excerpt="..."
+# exit 2
+```
+
+Output:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "cap_exceeded",
+    "message": "max_scouts_per_session=3 reached for parent_session_id=sess-abc123",
+    "remediation": "Either fold scout findings into a single answer, or open a new session, or override .aioson/config/scout-engine.json"
+  }
+}
+```
+
+`@deyvin` surfaces the message and asks the user how to proceed: usually handoff to `/architect` if scouts keep multiplying.
+
+To increase the limit in the project:
+
+```json
+// .aioson/config/scout-engine.json
+{ "max_scouts_per_session": 5 }
+```
+
+---
+
+## 4. Scope too large
+
+```bash
+aioson scout:prep \
+  --question="..." \
+  --scope-paths="src/"  # directory with 30+ files
+  --parent-agent=deyvin \
+  --parent-session-id=sess-abc123 \
+  --parent-session-excerpt="..."
+# exit 2
+```
+
+Output:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "scope_too_large",
+    "message": "scope resolved to 34 files, max_files_in_scope=20",
+    "remediation": "Narrow scope_paths to specific files, or increase max_files_in_scope in scout-engine.json"
+  }
+}
+```
+
+Solution: specify concrete files instead of a directory, or adjust `max_files_in_scope` in config.
+
+> **Note:** directories in `scope_paths` expand only 1 level deep (direct children). `scope_globs` is deferred to V2.
+
+---
+
+## 5. View dispatched scouts in the project
+
+```bash
+aioson memory:summary .
+```
+
+Output (relevant row):
+
+```
+Scouts dispatched: 4 (top topics: "workflow state", "handoff contract")
+```
+
+To inspect directly:
+
+```bash
+ls .aioson/runtime/scouts/
+# scout-feature-a-2026-05-14-a1b2c3.json
+# scout-2026-05-13-x9y8z7.json
+# .state.json
+```
+
+---
+
+## 6. Using the CLI-less fallback (no `aioson` installed)
+
+In environments without the `aioson` binary (e.g., plain Claude Code without CLI configured), `@deyvin` uses the inline template from its prompt. The "Sub-task scout invocation — CLI-less fallback" section in `deyvin.md` describes how to build the prompt manually and inject it into the sub-agent via Agent tool.
+
+The fallback produces the same JSON report, but without:
+- Cap validation
+- SQLite telemetry
+- Automatic archival on `feature:close`
+
+---
+
+## 7. Verify archival after feature:close
+
+After `aioson feature:close --slug=my-feature --verdict=PASS`:
+
+```bash
+ls .aioson/context/features/my-feature/scouts/
+# scout-my-feature-2026-05-14-a1b2c3.json
+
+grep "Sub-task scouts" .aioson/context/features/my-feature/dossier.md
+# ## Sub-task scouts
+# - scout-my-feature-2026-05-14-a1b2c3: "Why does workflow:next inherit..."
+```
+
+The runtime copy remains in `.aioson/runtime/scouts/` and will be pruned by `doctor --fix` after 90 days. Scouts with a defined `feature_slug` are **never** pruned — cold-load memory preservation takes priority.
+
+---
+
+## Continue reading
+
+- [CLI reference](./cli-commands.md) — all flags documented
+- [Diagrams](./diagrams.md) — full visual flow
+- [Troubleshooting](./troubleshooting.md) — known issues