@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/en/active-learning-loop/how-to-use.md

@@ -0,0 +1,313 @@
+# How to use the Active Learning Loop
+
+> Concrete examples. Each section solves a real day-to-day need.
+
+---
+
+## 1. Search an existing learning
+
+You want to know if the project already has a learning about authentication before creating a new rule:
+
+```bash
+aioson memory:search "authentication"
+```
+
+Typical output:
+
+```
+3 results for "authentication" (BM25)
+
+[1] authn-refresh-token-ttl  (promoted)
+    Refresh tokens must have a 7-day max TTL per decision in auth-flow feature.
+    Evidence: 4 sessions
+
+[2] jwt-audience-check  (for_review)
+    Validate 'aud' claim on all endpoints. Found in 2 security-audit sessions.
+    Evidence: 2 sessions
+
+[3] oauth-state-param  (active)
+    State parameter required in OAuth flow to prevent CSRF.
+    Evidence: 3 sessions
+```
+
+Filter to promoted learnings only:
+
+```bash
+aioson memory:search "authentication" --surface=learnings --limit=10
+```
+
+Search rules as well:
+
+```bash
+aioson memory:search "authentication" --surface=all
+```
+
+Include archived entries (for historical audit):
+
+```bash
+aioson memory:search "authentication" --include-archived
+```
+
+JSON output (for scripts):
+
+```bash
+aioson memory:search "authentication" --json
+```
+
+```json
+{
+  "ok": true,
+  "query": "authentication",
+  "results": [
+    {
+      "id": "authn-refresh-token-ttl",
+      "title": "authn-refresh-token-ttl",
+      "status": "promoted",
+      "score": -2.14,
+      "snippet": "Refresh tokens must have a 7-day max TTL..."
+    }
+  ],
+  "total": 3
+}
+```
+
+**Note on search:** the query uses token-AND — each whitespace-separated word must appear in the document. `"JWT authentication"` finds documents containing both words, not necessarily the exact phrase. Operators like AND/OR/NOT are stripped — it's keyword search, not a query language.
+
+---
+
+## 2. Declare that an agent loaded a rule
+
+When you (or an agent you're writing) loads a rule at the start of a session, declare it to the telemetry system:
+
+```bash
+aioson context:load --target=rule:authn-rules --agent=dev
+```
+
+Load multiple rules at once (recommended — minimizes overhead):
+
+```bash
+aioson context:load --target=rule:authn-rules --agent=dev --batch="jwt-patterns,oauth-state,session-management"
+```
+
+Associate with a feature in progress:
+
+```bash
+aioson context:load --target=brain:sheldon-005 --agent=sheldon --feature=authn-flow
+```
+
+The command is tier-1 silent — no output by default. Use `--verbose` to confirm:
+
+```bash
+aioson context:load --target=rule:authn-rules --agent=dev --verbose
+# rule_loaded: authn-rules (agent: dev)
+```
+
+Use `--json` to integrate into scripts:
+
+```bash
+aioson context:load --target=rule:authn-rules --agent=dev --json
+# {"ok":true,"event":"rule_loaded","target":"authn-rules","agent":"dev"}
+```
+
+---
+
+## 3. What `feature:close` does now
+
+The existing flow remains unchanged — distillation is added at the end:
+
+```bash
+aioson feature:close --slug=authn-flow --verdict=PASS
+```
+
+Expected output (in addition to normal feature:close output):
+
+```
+[existing] Gate validation: OK
+[existing] Dossier finalized: .aioson/context/features/authn-flow/
+[existing] features.md updated: authn-flow → PASS
+
+ℹ [learning-loop] distillation: 2 promoted, 1 for review, 0 merge candidates
+```
+
+What happened behind the scenes:
+1. Read the PRD classification — SMALL, so it proceeded.
+2. Acquired the distillation lock in `evolution_log`.
+3. Ran `learning:auto-promote --feature=authn-flow` — 2 learnings crossed the threshold and became rules.
+4. 1 learning remained in `for_review` — not enough evidence yet.
+5. Recorded the result in `evolution_log` and emitted the notify.
+
+**Disable for one call:**
+
+```bash
+aioson feature:close --slug=authn-flow --verdict=PASS --no-distill
+```
+
+**MICRO project** — distillation is skipped automatically, no need for `--no-distill`:
+
+```
+[existing] Gate validation: OK
+...
+ℹ [learning-loop] skipped: MICRO classification
+```
+
+---
+
+## 4. Archive a stale rule
+
+The `doctor` reported staleness on the `legacy-session-cookies` rule. You want to archive it:
+
+```bash
+# Simulate first to see what would happen
+aioson memory:archive --id=rule:legacy-session-cookies --reason="replaced by JWT-based auth (feature authn-flow)" --dry-run
+```
+
+Dry-run output:
+
+```
+[dry-run] would archive:
+  source:  .aioson/rules/legacy-session-cookies.md
+  dest:    .aioson/rules/_archived/2026-05-14/legacy-session-cookies.md
+  reason:  replaced by JWT-based auth (feature authn-flow)
+  evolution_log: 1 entry to close, 1 entry to insert
+```
+
+If the dry-run looks correct, execute:
+
+```bash
+aioson memory:archive --id=rule:legacy-session-cookies --reason="replaced by JWT-based auth (feature authn-flow)"
+```
+
+Output:
+
+```
+⚠ [memory-archive] archiving rule:legacy-session-cookies — legacy-session-cookies.md
+archived: .aioson/rules/_archived/2026-05-14/legacy-session-cookies.md
+```
+
+Associate with a feature (optional but recommended for traceability):
+
+```bash
+aioson memory:archive --id=rule:legacy-session-cookies --reason="..." --feature=authn-flow
+```
+
+---
+
+## 5. Archive a learning or brain
+
+The same command works for all three types — `rule`, `learning`, and `brain`:
+
+```bash
+# Archive a learning
+aioson memory:archive --id=learning:jwt-draft-1 --reason="superseded by promoted version in authn-flow"
+
+# Archive a brain
+aioson memory:archive --id=brain:sheldon-003 --reason="version 003 replaced by sheldon-006"
+```
+
+---
+
+## 6. Restore an archived item
+
+You archived the `rate-limiting-rules` rule but realized it's still needed:
+
+```bash
+aioson memory:restore --id=rule:rate-limiting-rules
+```
+
+Output:
+
+```
+⚠ [memory-restore] restoring rule:rate-limiting-rules
+restored: .aioson/rules/rate-limiting-rules.md
+```
+
+With a reason (recommended for traceability):
+
+```bash
+aioson memory:restore --id=rule:rate-limiting-rules --reason="rule still needed — removal was premature"
+```
+
+Dry-run available too:
+
+```bash
+aioson memory:restore --id=rule:rate-limiting-rules --dry-run
+```
+
+---
+
+## 7. Check loop health via doctor
+
+```bash
+aioson doctor .
+```
+
+When the loop is healthy:
+
+```
+[OK] living-memory:rule_staleness
+[OK] living-memory:learning_orphans
+[OK] living-memory:distillation_lag
+```
+
+When there are issues:
+
+```
+[WARN] living-memory:rule_staleness (2 stale rules)
+  Rule 'legacy-session-cookies' has 0 rule_loaded events in last 7 features.
+  Rule 'old-rate-limit-policy' has 0 rule_loaded events in last 7 features.
+  Hint: consider archiving:
+    aioson memory:archive --id=rule:legacy-session-cookies --reason="..."
+    aioson memory:archive --id=rule:old-rate-limit-policy --reason="..."
+
+[WARN] living-memory:learning_orphans (1 orphan)
+  Learning 'jwt-expiry-pattern' was promoted but its target rule had no rule_loaded after promotion.
+  Hint: aioson memory:archive --id=learning:jwt-expiry-pattern --reason="..."
+
+[WARN] living-memory:distillation_lag
+  8 features closed, 5 auto_distillation events recorded.
+  Hint: Run `aioson feature:close --slug=<slug> --verdict=PASS` on pending features,
+        or check if distillation is failing silently (see evolution_log).
+```
+
+See [Doctor checks](./doctor-checks.md) for what each check means and how to act.
+
+---
+
+## 8. Inspect `evolution_log` directly
+
+For audit or troubleshooting, query the SQLite directly:
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "SELECT target_type, target_id, event_type, start_at, end_at, reason
+   FROM evolution_log
+   ORDER BY start_at DESC
+   LIMIT 10;"
+```
+
+Check for active distillation lock:
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "SELECT feature_slug, start_at, payload_json
+   FROM evolution_log
+   WHERE event_type='auto_distillation' AND end_at IS NULL;"
+```
+
+History for a specific rule:
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "SELECT event_type, start_at, end_at, reason, actor
+   FROM evolution_log
+   WHERE target_type='rule' AND target_id='authn-rules'
+   ORDER BY start_at;"
+```
+
+---
+
+## Continue reading
+
+- [CLI reference](./cli-commands.md) — all flags documented
+- [Doctor checks](./doctor-checks.md) — what the checks mean and how to act
+- [Troubleshooting](./troubleshooting.md) — known issues

package/docs/en/active-learning-loop/troubleshooting.md

@@ -0,0 +1,283 @@
+# Troubleshooting — Active Learning Loop
+
+> Each section: **symptom** → **diagnosis** → **fix**. Always start with `aioson doctor .` — it detects most issues.
+
+---
+
+## 1. Stuck distillation lock (`lock_held`)
+
+**Symptom:** `feature:close` returns with a "distillation already in progress" notify on every subsequent call for the same feature, even with no other process running. Or the distillation got stuck in a state where `end_at` was never set.
+
+**Diagnosis:** AIOSON crashed (SIGKILL, power loss, manual process kill) during distillation. The lock row in `evolution_log` was left with `end_at=NULL`, signaling "in progress", but there's no active process.
+
+Confirm:
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "SELECT rowid, feature_slug, event_type, start_at, end_at, payload_json
+   FROM evolution_log
+   WHERE event_type IN ('auto_distillation', 'distillation_failed')
+     AND end_at IS NULL;"
+```
+
+If `start_at` is far in the past and there's no active process, it's a stuck lock.
+
+**Fix (V1 — manual):**
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "UPDATE evolution_log
+   SET end_at=datetime('now'), payload_json=json_patch(payload_json, '{\"state\":\"unlocked_manually\"}')
+   WHERE feature_slug='<slug>'
+     AND event_type='auto_distillation'
+     AND end_at IS NULL;"
+```
+
+Replace `<slug>` with the slug of the feature with the stuck lock.
+
+Then verify:
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "SELECT feature_slug, end_at FROM evolution_log
+   WHERE event_type='auto_distillation' AND end_at IS NULL;"
+# should return 0 rows
+```
+
+You can now run `feature:close` again.
+
+**V2 trajectory:** the `aioson memory:unlock --feature=<slug>` command will automate this unlock. Until then, the manual fix above is the path.
+
+---
+
+## 2. MICRO projects — distillation and doctor checks absent
+
+**Symptom:** `feature:close --verdict=PASS` completes without any "distillation: N promoted" line. `aioson doctor .` does not show the three curation checks.
+
+**Diagnosis:** the project is classified as MICRO. This is the expected configuration — MICRO projects opt out of the entire loop:
+
+```json
+// .aioson/config/learning-loop.json
+{
+  "skip_on_classification": ["MICRO"]
+}
+```
+
+Also applies to individual features classified as MICRO in the PRD frontmatter:
+
+```yaml
+# .aioson/context/prd-my-feature.md
+---
+classification: MICRO
+---
+```
+
+**How to verify:**
+
+```bash
+# Check project classification
+grep -r "classification:" .aioson/context/project.context.md
+# or
+aioson doctor . --json | grep classification
+
+# Check a specific feature
+head -10 .aioson/context/prd-my-feature.md
+```
+
+**If you want to enable the loop on MICRO projects:**
+
+Edit `.aioson/config/learning-loop.json` and remove `"MICRO"` from `skip_on_classification`:
+
+```json
+{
+  "skip_on_classification": []
+}
+```
+
+Not recommended — MICRO projects generally don't have enough features for the loop to be useful. The minimum threshold of 5 features for the doctor checks probably won't be reached anyway.
+
+---
+
+## 3. `pattern:detect` not running — `merge_candidate_count` always 0
+
+**Symptom:** the distillation notify always shows `0 merge candidates`, even with many promoted learnings with similar content.
+
+**Diagnosis:** this is expected behavior in V1. The `feature:close` hook runs `learning:auto-promote` but does **not** run `pattern:detect`. The existing `pattern:detect` is squad-scoped and incompatible with feature scope. `merge_candidate_count` is always 0 in V1.
+
+This limitation is tracked for a follow-up. There is no direct workaround.
+
+**What you can do in the meantime:**
+
+If you want to manually detect patterns across promoted learnings:
+
+```bash
+aioson memory:search "your-term" --surface=learnings
+```
+
+And archive learnings that are clearly duplicates:
+
+```bash
+aioson memory:archive --id=learning:duplicate-learning --reason="identical content to learning:primary-learning"
+```
+
+---
+
+## 4. `aioson update` overwrites `learning-loop.json`
+
+**Symptom:** you customized `.aioson/config/learning-loop.json` (changed `timeout_ms`, `auto_promote_threshold`, etc.) and then ran `aioson update`. Your customizations were lost.
+
+**Diagnosis:** this is the current installer policy — `aioson update` overwrites `learning-loop.json` with the template values. It is a documented behavior to be fixed in a future version.
+
+**Workaround:**
+
+Before running `aioson update`, make a manual backup:
+
+```bash
+cp .aioson/config/learning-loop.json .aioson/config/learning-loop.json.bak
+```
+
+After `aioson update`, restore your customizations:
+
+```bash
+# Compare what changed
+diff .aioson/config/learning-loop.json .aioson/config/learning-loop.json.bak
+
+# Restore customized fields manually
+# Edit .aioson/config/learning-loop.json with your preferences
+```
+
+**Trajectory:** the installer will switch to merge-aware copy for this file, preserving user customizations. Until then, a manual backup before `aioson update` is necessary if you have customizations.
+
+---
+
+## 5. Distillation failing silently
+
+**Symptom:** `feature:close` runs and returns 0, but without the distillation notify, and `doctor` reports `distillation_lag`.
+
+**Diagnosis:** the distillation hook failed but swallowed the error (correct behavior — distillation is best-effort). The error was recorded in `evolution_log`.
+
+**Investigate:**
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "SELECT feature_slug, start_at, payload_json
+   FROM evolution_log
+   WHERE event_type='distillation_failed'
+   ORDER BY start_at DESC LIMIT 5;"
+```
+
+The `payload_json` contains `error_phase` and `error_message`:
+
+```json
+{
+  "state": "failed",
+  "error_phase": "auto-promote",
+  "error_message": "SQLITE_LOCKED: database is locked"
+}
+```
+
+Common causes by `error_phase`:
+
+| Phase | Typical cause |
+|---|---|
+| `auto-promote` | DB locked, `project_learnings` with invalid schema |
+| `timeout` | Distillation took more than `timeout_ms` (default: 5000) |
+| `lock-acquire` | INSERT lock failed — concurrency or DB corruption |
+
+**Common fixes:**
+
+- `SQLITE_LOCKED`: another process has the DB open. Close other terminals running AIOSON.
+- `timeout`: increase `timeout_ms` in `learning-loop.json` (e.g., `10000`).
+- DB corruption: `sqlite3 .aioson/runtime/aios.sqlite "PRAGMA integrity_check;"`.
+
+---
+
+## 6. `memory:archive` refused — `AIOSON_RUNTIME_HOOK=1`
+
+**Symptom:**
+
+```
+Error: memory:archive is a tier-2 human-only operation.
+  Cannot run with AIOSON_RUNTIME_HOOK=1 (automated hook context).
+```
+
+**Diagnosis:** you're trying to run `memory:archive` (or `memory:restore`) from inside an automated hook — a script that sets `AIOSON_RUNTIME_HOOK=1`. These commands are intentionally restricted to humans.
+
+**Fix:** run the command manually in the terminal, outside the hook context:
+
+```bash
+# Without AIOSON_RUNTIME_HOOK=1 in the environment
+aioson memory:archive --id=rule:my-rule --reason="..."
+```
+
+If you need an automated script to archive items, consider that this is a design problem — deliberate archival with a reason is a semantic operation that should be human-approved.
+
+---
+
+## 7. `memory:search` returns `query_unparseable`
+
+**Symptom:**
+
+```json
+{ "ok": false, "reason": "query_unparseable" }
+```
+
+**Diagnosis:** after stripping all FTS5 operator characters (`* ( ) ^ : + - "`), the query became empty or only whitespace.
+
+Examples of problematic queries:
+
+```bash
+aioson memory:search "***"        # all chars are operators
+aioson memory:search "+"          # pure operator
+aioson memory:search "(NOT)"      # parentheses + NOT stripped → empty
+```
+
+**Fix:** use ordinary words:
+
+```bash
+aioson memory:search "authentication"
+aioson memory:search "jwt refresh token"
+```
+
+---
+
+## 8. FTS5 out of sync — search not returning recent results
+
+**Symptom:** `memory:search` doesn't find a learning you know exists and is active.
+
+**Diagnosis:** the FTS5 triggers may have failed during a previous write (e.g., crash during INSERT into `project_learnings`). The FTS5 index fell out of sync with the base table.
+
+**Diagnose:**
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "SELECT COUNT(*) FROM project_learnings WHERE status != 'archived';"
+# vs
+sqlite3 .aioson/runtime/aios.sqlite \
+  "SELECT COUNT(*) FROM project_learnings_fts;"
+```
+
+If the counts diverge, the index is out of sync.
+
+**Fix — rebuild the index:**
+
+```bash
+sqlite3 .aioson/runtime/aios.sqlite \
+  "INSERT INTO project_learnings_fts(project_learnings_fts) VALUES('rebuild');"
+```
+
+The `rebuild` is a safe, idempotent FTS5 operation — it rebuilds the index from the base table.
+
+---
+
+## Quick diagnostic commands
+
+| Goal | Command |
+|---|---|
+| See all checks | `aioson doctor .` |
+| See active distillation locks | `sqlite3 .aioson/runtime/aios.sqlite "SELECT * FROM evolution_log WHERE end_at IS NULL;"` |
+| See recent distillations | `sqlite3 .aioson/runtime/aios.sqlite "SELECT feature_slug, event_type, start_at, end_at FROM evolution_log WHERE event_type LIKE '%distillation%' ORDER BY start_at DESC LIMIT 10;"` |
+| See distillation failures | `sqlite3 .aioson/runtime/aios.sqlite "SELECT feature_slug, payload_json FROM evolution_log WHERE event_type='distillation_failed';"` |
+| Check FTS5 sync | `sqlite3 .aioson/runtime/aios.sqlite "SELECT COUNT(*) FROM project_learnings; SELECT COUNT(*) FROM project_learnings_fts;"` |
+| Rebuild FTS5 | `sqlite3 .aioson/runtime/aios.sqlite "INSERT INTO project_learnings_fts(project_learnings_fts) VALUES('rebuild');"` |
+| Check DB integrity | `sqlite3 .aioson/runtime/aios.sqlite "PRAGMA integrity_check;"` |

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

@@ -0,0 +1,109 @@
+# Deyvin Sub-Task Scout — English guide
+
+> **Sub-task scout** is `@deyvin`'s structured diagnostic primitive. When a question requires inspecting more than 5 files or tracing a runtime flow, the agent doesn't read everything inline (burning parent context) — it dispatches a scout. The scout runs in isolated context, inspects the scope, and returns a JSON report with findings, confidence, and recommendation. The agent reads the report (~500 tokens) instead of the files (~10k+ tokens).
+
+This folder documents the full feature — 3 phases, 3 CLI verbs, 1 advisory check in doctor.
+
+---
+
+## What it's for
+
+- **Preserve parent agent context** — surveys of >5 files enter the parent context as a compact report, not raw file contents.
+- **Diagnostic traceability** — scouts are persisted in `.aioson/runtime/scouts/` and (after `feature:close`) archived to `.aioson/context/features/{slug}/scouts/`.
+- **CLI-less fallback** — `deyvin.md` carries a manual scout template for environments without the `aioson` binary.
+- **Cap discipline** — configurable limits prevent sub-task explosion: `max_scouts_per_session=3`, `max_files_in_scope=20`.
+
+---
+
+## Prerequisites
+
+- AIOSON installed (version that shipped this feature)
+- Harness with sub-agent support: Claude Code (Agent tool) or Codex (MultiAgentV2)
+- `.aioson/config/scout-engine.json` in the project (copied automatically by the installer as `{}`, defaults active)
+
+> **Gemini CLI / OpenCode:** emit `harness_unsupported` and automatically fall back to `deyvin.md`'s CLI-less inline flow. Full harness parity is V2.
+
+---
+
+## Reading guide
+
+### I want to understand what changed in @deyvin (10 min)
+1. [What is the sub-task scout](./sub-task-scout.md) — the problem, 3 phases, full lifecycle
+2. [Diagrams](./diagrams.md) — ASCII flow: `scout:prep` → sub-agent → `scout:validate` → `scout:commit`
+
+### I want to see @deyvin using a scout
+3. [How to use](./how-to-use.md) — happy path, invalid JSON recovery, cap exceeded
+
+### I want to configure or understand the limits
+4. [CLI reference](./cli-commands.md) — full flags for all 3 verbs (`scout:prep`, `scout:validate`, `scout:commit`)
+
+### Something went wrong / I want to adjust limits
+5. [Troubleshooting](./troubleshooting.md) — cap exceeded, malformed JSON, harness without sub-agent, orphaned scouts
+
+---
+
+## Canonical commands
+
+| Command | What it does | Tier | Doc |
+|---|---|---|---|
+| `aioson scout:prep --question="..." --scope-paths="..." --parent-agent=deyvin --parent-session-id=<id>` | Validates inputs, applies caps, generates standardized prompt for sub-agent | tier-1 silent | [CLI reference](./cli-commands.md) |
+| `aioson scout:validate --input=<path>` | Validates the JSON returned by the sub-agent against the output schema | tier-1 silent | [CLI reference](./cli-commands.md) |
+| `aioson scout:commit --input=<path>` | Persists the validated report, emits telemetry, decrements cap | tier-1 silent | [CLI reference](./cli-commands.md) |
+| `aioson doctor .` | Includes the `scouts_directory_pruning` advisory (orphaned scouts >90d) | tier-1 silent | [Troubleshooting](./troubleshooting.md) |
+
+---
+
+## Where artifacts live
+
+| Path | Role |
+|---|---|
+| `.aioson/runtime/scouts/{id}.json` | Active scout report (ephemeral; pruned by doctor after 90d if orphaned) |
+| `.aioson/runtime/scouts/.state.json` | Cap state per session_id; lock at `.state.json.lock` |
+| `.aioson/config/scout-engine.json` | Per-project configuration (override of defaults) |
+| `.aioson/context/features/{slug}/scouts/{id}.json` | Scout archived after `feature:close --verdict=PASS` |
+| `.aioson/context/features/{slug}/dossier.md` → `## Sub-task scouts` | Bullets of archived scouts (append-only, idempotent) |
+| `agent_events` (SQLite) | Telemetry: `event_type='sub_task'`, `action ∈ {prepared, validation_failed, retry_exhausted, committed, slow_completion, cap_exceeded}` |
+
+---
+
+## Configuration
+
+`.aioson/config/scout-engine.json` is copied as `{}` on first install — all defaults apply:
+
+| Field | Default | What it controls |
+|---|---|---|
+| `max_scouts_per_session` | 3 | Scouts per `parent_session_id` |
+| `max_files_in_scope` | 20 | Files in the `scope_paths` sum |
+| `max_retries_on_malformed_json` | 1 | Re-validations before `retry_exhausted` |
+| `max_depth` | 2 | Nested scout depth (1 sub-scout per scout) |
+| `prune_unattached_after_days` | 90 | Days before `doctor --fix` prunes scouts without `feature_slug` |
+| `slow_completion_warn_seconds` | 300 | Threshold for emitting `slow_completion` telemetry |
+
+Override example:
+
+```json
+{
+  "max_scouts_per_session": 5,
+  "max_files_in_scope": 30
+}
+```
+
+> Unknown keys are **rejected** (strict validation). Use only the fields above.
+
+---
+
+## Status
+
+The `deyvin-subtask-scout` feature was delivered in 3 phases:
+
+| Phase | Slug | Delivery | Status |
+|---|---|---|---|
+| 1 | `core-engine` | `src/sub-task-engine.js` + schemas + hand-rolled validator | PASS |
+| 2 | `cli-verbs` | `scout:prep` + `scout:validate` + `scout:commit` + state with file-lock | PASS |
+| 3 | `wiring-and-lifecycle` | `deyvin.md` updated (CLI + CLI-less), archival in `feature:close`, `memory:summary` row, doctor advisory | PASS |
+
+80 deterministic tests passing. QA approved.
+
+Specification artifacts (archived):
+- [PRD](../../.aioson/context/done/deyvin-subtask-scout/prd-deyvin-subtask-scout.md)
+- [Spec](../../.aioson/context/done/deyvin-subtask-scout/spec-deyvin-subtask-scout.md)