@vpxa/aikit 0.1.360 → 0.1.362

package/scaffold/AUTOMATION-BOUNDARY-ANALYSIS.md

@@ -1,78 +0,0 @@
-# Automation Boundary Analysis (Reconciled)
-
-> **Status:** Corrected per architectural review (2026-06-28).
-> **Previous version:** Classified 7 actions as AUTOMATABLE with 80% token savings claims.
-> **Corrections:**
-> - `status({includePrelude: true})` is LLM-JUDGMENT, not automatable
-> - `search({query: "SESSION CHECKPOINT"})` is LLM-JUDGMENT — fixed query silently misses
-> - `check({})` / `test_run({})` are MIXED/SCOPED only — full-project runs too slow
-> - Token savings claims removed — not proven
->
-> See `docs/architecture/eventbus-hooks-developer-guide.md` for the full implementation guide.
-
----
-
-## Corrected Classification
-
-| Action | Correct Category | Reason |
-|--------|-----------------|--------|
-| `status({})` at session start | **Automatable signal** | Safe only when bounded (no includePrelude) and not used as dynamic instruction replacement |
-| `status({includePrelude: true})` | **LLM judgment** | Produces LLM-facing context; may be stale if hidden behind a hook |
-| `knowledge({action: "list"})` at session start | **Automatable signal with budget** | Safe only with strict result cap and no full-list injection |
-| `search({query: "SESSION CHECKPOINT"})` | **LLM judgment** | Fixed query can silently miss relevant checkpoints |
-| `search({query: "<task>"})` before code change | **LLM judgment** | Query requires task understanding |
-| `scope_map({task})` before code change | **LLM judgment** | Task description requires LLM synthesis |
-| `check({})` / `test_run({})` before commit | **Mixed, scoped only** | Full-project runs too slow; must pass `files` from `git diff` or user intent |
-| `blast_radius({changed_files})` before commit | **Mixed** | Call can be automated; output interpretation is LLM judgment |
-| Handoff/checkpoint content creation | **LLM judgment** | Requires summarizing decisions and next steps |
-| Writing a prepared handoff file | **Automatable** | File IO is deterministic after content exists |
-| Skill loading at session start | **LLM judgment with signal** | Hook can recommend; LLM must choose and follow skill protocol |
-| Context pressure check at session end | **Automatable signal** | Numeric comparison is deterministic |
-
----
-
-## Per-Automation Specification
-
-Each automated action must have:
-
-| Field | Required |
-|-------|----------|
-| Input source | ✔ — What triggers the automation |
-| Output budget | ✔ — Max tokens/characters produced |
-| Timeout | ✔ — Max execution time |
-| Failure mode | ✔ — Log, warn, or degrade (never silently fail) |
-| User-visible trace | ✔ — Agent sees automation output |
-
----
-
-## Per-LLM-Judgment Specification
-
-Each LLM-judgment action must have:
-
-| Field | Required |
-|-------|----------|
-| Why it cannot be automated | ✔ — Clear boundary reason |
-| What instructions must remain | ✔ — Exact instruction text |
-| How EventBus can assist (not replace) | ✔ — Signal, not decision |
-
----
-
-## What NOT to Automate
-
-These actions are explicitly rejected for automation:
-
-- Search query composition (requires task understanding)
-- Scope map task description (requires intent synthesis)
-- Handoff/checkpoint content creation (requires LLM synthesis)
-- Broad `check({})` / `test_run({})` without scope (too slow, may not match task)
-- Any action where the automation would hide its own failures from the LLM
-
----
-
-## Guiding Principles
-
-1. **Automate bounds, not decisions** — signals and file IO are safe; composition and synthesis are not
-2. **Every automation must be bounded** — max cost, max output, failure behavior, user-visible trace
-3. **No hidden behavior** — the LLM must know automation ran and see its output
-4. **LLM remains responsible for** — query composition, scope description, checkpoint/handoff synthesis, blast-radius interpretation, and validation choice when scope is unclear
-5. **Token savings require proof** — do not claim reduced instruction text until the removed instruction is proven safe to omit on that platform