@vpxa/aikit 0.1.309 → 0.1.311

package/scaffold/dist/definitions/bodies.mjs

@@ -70,7 +70,7 @@ Every \`runSubagent\` prompt includes all of:
 
 1. **Agent + Goal** — exact specialist name, testable acceptance criteria.
 2. **Files + Boundary** — target files, do-not-touch list.
-3. **Arch Context** — pick by token budget: efficient → \`stratum_card\`, normal → \`compact\`, full → \`digest\`. Default efficient.
+ 3. **Arch Context** — Pre-compress with AI Kit tools before including in prompt. pick by token budget: efficient → \`stratum_card\`, normal → \`compact\`, full → \`digest\`. Default efficient. **Never pass raw file contents — always compress first.** This eliminates subagent need for \`read_file\`.
 4. **Prior Knowledge** — \`knowledge({ action: "lesson", subAction: "list-lessons", topic: "<2-3 keywords>", minConfidence: 70 })\` + \`search({ query: "<task area>", category: "conventions", limit: 3 })\`. Include high-confidence results. Skip for Floor.
 5. **Artifacts Path** — active flow's run dir / artifacts path from \`flow({ action: 'status' })\`.
 6. **FORGE** — tier, task_id, evidence requirements. Reviewers add CRITICAL/HIGH claims into your task_id; never create their own.
@@ -83,10 +83,19 @@ Every \`runSubagent\` prompt includes all of:
 
 Always pass \`agentName\`. Missing/empty is a dispatch bug.
 
-## Context + Compression
-Use AI Kit compression: search/file_summary/compact/digest/stratum_card. read_file only for exact edit lines.
-After each batch: stash/knowledge summary with status, files, decisions, blockers. Never echo raw subagent output.
-Between phases: session_digest({ persist: true, focus: "<topic>" }). Carry only decisions, paths, blockers.
+## Context + Compression — AI Kit First (HARD RULE)
+
+**Always use AI Kit compression tools before reaching for \`read_file\`.**
+
+| Need | Use |
+|------|-----|
+| Assess scope before dispatch | \`file_summary\`, \`compact\`, \`stratum_card\` |
+| Pre-populate subagent with context | \`stratum_card\` (efficient), \`compact\` (normal), \`digest\` (full) |
+| Understand error during emergency | \`compact({ path, query })\` — never raw-read |
+| Between phases: compress state | \`session_digest({ persist: true, focus: "<topic>" })\` |
+| After batch: persist summary | \`knowledge({ action: 'remember', scope: 'flow', ... })\` |
+
+\`read_file\` is ONLY for exact edit lines. Or when diagnosing an emergency with \`git diff --stat\` + \`check({})\`. No exceptions for planning or discovery.
 
 ## Evidence + Validation
 Use forge_classify for tier. Standard+ creates one Orchestrator-owned evidence_map task_id; reviewers add CRITICAL/HIGH claims into it; only Orchestrator runs gate.
@@ -185,7 +194,7 @@ reindex after structural changes; produce_knowledge for durable updates; remembe
 ## Pre-Edit Checklist
 
 1. **Understand consumers** — \`graph({action:'find_nodes', name_pattern:'<target>'})\` → \`graph({action:'neighbors', node_id, direction:'incoming'})\`
-2. **Compress, don't raw-read** — \`file_summary\` then \`compact({ items: [{path, query}] })\` or \`compact({ref, query?})\`; \`read_file\` only for exact edit lines
+ 2. **Compress, don't raw-read (HARD RULE)** — If you catch yourself about to call \`read_file\`, stop. Use \`file_summary\` first, then \`compact({ items: [{path, query}] })\` or \`compact({ref, query?})\`. \`read_file\` is ONLY for exact line content before \`replace_string_in_file\` — never for exploration or understanding.
 3. **Snapshot risky edits** — \`checkpoint({action:'save', label:'pre-<scope>'})\` before cross-cutting changes
 4. **Estimate blast radius** — run \`blast_radius\` before and after shared/public symbol changes
 5. **TDD when tests exist** — failing test first, then minimum code

package/scaffold/dist/definitions/protocols.mjs

@@ -20,7 +20,7 @@ ${e===`<PROFILE>`?`**Profile:** Check your role → implementer | documenter | r
 ---`}function n(){return"\n## Evidence Citation Protocol (tier-aware)\n\nNo FORGE `task_id` → skip `evidence_map`; use `file:line` citations only.\nDo not create your own `task_id` or run the gate.\n\n| Tier | Your responsibility |\n|------|---------------------|\n| Floor | Findings with `file.ts#Lxx` citations. No `evidence_map`. |\n| Standard | Add 2-4 CRITICAL/HIGH findings with receipts. |\n| Critical | Add all CRITICAL/HIGH findings; tag contract/security claims with `safety_gate`. |\n\n**Every response MUST include:**\n- `**FORGE Task ID:** <task_id>` (passed in by Orchestrator, or state \"not provided\")\n- `**Tier applied:** Floor | Standard | Critical`\n- `**Findings:** <list>` with `file:line` receipts\n- Verdict: `APPROVED` | `CHANGES_REQUESTED` | `BLOCKED`\n\nDo NOT create a new `evidence_map`, run `evidence_map({action:'gate'})`, or add non-critical noise."}function r(...e){return e.filter(Boolean).join(`
 
 `)}function i({title:e=`Knowledge Recall`,intro:t,commands:n,followUp:i}={}){return r(`## Pre-Task: ${e} (MANDATORY)`,t,["```",...(Array.isArray(n)?n:[n]).filter(Boolean),"```"].join(`
-`),i)}function a(){return r(`## Post-Task: Capture Lesson`,`**HARD RULE:** Before DONE, capture 1-2 lessons unless change is pure config/formatting.`,'Quick capture:\n```\nknowledge({ action: "lesson", subAction: "create", context: "<what situation you faced>", insight: "<what principle the solution demonstrates>", evidence: "<file:line or commit that proves it>", confidence: 65 })\n```',"If recalled lesson was confirmed/invalid, use `confirm` or `contradict`.")}const o=r(`## Output Rules (HARD RULE)`,`**Plain text is allowed only when ALL are true:**`,` - Response is 1-2 short sentences.`,` - No table, list, checklist, plan, report, verdict, review, summary, progress, evidence map, or batch result is being returned.`,` - No user approval, mandatory stop, or choice is needed.`,"Follow the **Presentation Priority** (1st Inline Visual - `present({ schemaVersion: 1, title, blocks })` → 2nd Interactive - `present({ schemaVersion: 1, title, blocks, actions })` → 3rd Plain Text). Only tiny status/questions that pass the gate above → plain text (Priority 3). Prefer `present` for all others, especially summaries, comparisons, reports, task plans, verdicts, and progress."),s=r(`## AI Kit Recovery`,"If AI Kit tools are unavailable or missing, run `npx -y @vpxa/aikit@latest init --user`, then reload the client so the `aikit` MCP server and user instructions become available."),c={"code-agent-base":`# Code Agent - Shared Kernel
+`),i)}function a(){return r(`## Post-Task: Capture Lesson`,`**HARD RULE:** Before DONE, capture 1-2 lessons unless change is pure config/formatting.`,'Quick capture:\n```\nknowledge({ action: "lesson", subAction: "create", context: "<what situation you faced>", insight: "<what principle the solution demonstrates>", evidence: "<file:line or commit that proves it>", confidence: 65 })\n```',"If recalled lesson was confirmed/invalid, use `confirm` or `contradict`.")}const o=r(`## Output Rules (HARD RULE)`,`**Plain text is allowed only when ALL are true:**`,` - Response is 1-2 short sentences.`,` - No table, list, checklist, plan, report, verdict, review, summary, progress, evidence map, or batch result is being returned.`,` - No user approval, mandatory stop, or choice is needed.`,"Follow the **Presentation Priority** (1st Inline Visual - `present({ schemaVersion: 1, title, blocks })` → 2nd Interactive - `present({ schemaVersion: 1, title, blocks, actions })` → 3rd Plain Text). Only tiny status/questions that pass the gate above → plain text (Priority 3). Prefer `present` for all others, especially summaries, comparisons, reports, task plans, verdicts, and progress.");function s(){return"## Tool Preference — AI Kit First (HARD RULE)\n\n**Never start with `read_file`, `grep_search`, `semantic_search`, or `run_in_terminal`. AI Kit tools replace all of these.**\n\n| Need | Use | NEVER |\n|------|-----|-------|\n| Structure of a file | `file_summary({ path })` | `read_file` to \"understand\" it |\n| Find specific code | `compact({ path, query })` | `read_file` to search |\n| Multiple files | `digest({ sources, query })` | Multiple `read_file` calls |\n| Reuse previous output | `compact({ ref, query? })` with `enrich:true` | Re-reading same file |\n| Search codebase | `search({ query })` | `grep_search` / `semantic_search` |\n| Find a symbol | `symbol({ name })` | `grep_search` |\n| Trace data flow | `trace({ items: [{start, direction}] })` | Manual code tracing |\n| Module relationships | `graph({action:'neighbors', node_id})` | Manual import tracing |\n| Typecheck + lint | `check({})` | `run_in_terminal tsc` / biome |\n| Run tests | `test_run({})` | `run_in_terminal vitest` |\n| Impact analysis | `blast_radius({ changed_files })` | Manual caller tracing |\n| Complexity metrics | `measure({ path })` | Line counting / wc |\n| Web research | `web_search({ queries })` + `web_fetch({ urls })` | `fetch_webpage` |\n\n`read_file` is ONLY acceptable when you need exact line content FOR EDITING (before `replace_string_in_file`).\n\nEven then, use `file_summary` first to identify which lines to read."}const c=r(`## AI Kit Recovery`,"If AI Kit tools are unavailable or missing, run `npx -y @vpxa/aikit@latest init --user`, then reload the client so the `aikit` MCP server and user instructions become available."),l={"code-agent-base":`# Code Agent - Shared Kernel
 
 > Shared protocol for code-writing agents. Role files add only role-specific behavior.
 
@@ -40,14 +40,7 @@ ${e===`<PROFILE>`?`**Profile:** Check your role → implementer | documenter | r
 - Use terse style if requested by Orchestrator.
 - End with one status: \`DONE\` | \`DONE_WITH_CONCERNS\` | \`NEEDS_CONTEXT\` | \`BLOCKED\`.
 
-## Lookup Order
-1. Provided context / flow withdrawal.
-2. Onboard artifacts via \`compact({ items: [{path}] })\`.
-3. Scoped recall: \`search({ query })\`, lessons/conventions.
-4. Targeted tools: \`file_summary\`, \`compact\`, \`symbol\`, \`trace\`, \`graph\`, \`find\`.
-5. \`read_file\` only for exact edit lines.
-
-Use AI Kit tools before native IDE/shell equivalents.
+${s()}
 
 ## Protocol Coverage
 - conversation-compression: prefer provided compressed context; stash/remember concise findings before context changes; never paste raw long output.
@@ -96,6 +89,8 @@ Instructions use short names such as \`status\`, \`compact\`, \`search\`. Runtim
 
 ${t(`researcher`)}
 
+${s()}
+
 ## Method
 1. Start from Orchestrator question + provided context.
 2. Recall: \`search({ query })\` + relevant lessons/conventions.
@@ -124,6 +119,8 @@ Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
 
 ${t(`reviewer`)}
 
+${s()}
+
 ## Method
 1. Use provided diff/context first; run \`blast_radius\` when scope is unclear.
 2. Recall local patterns and review changed code against acceptance criteria.
@@ -154,6 +151,8 @@ Approve only with zero CRITICAL/HIGH findings.
 
 ${t(`reviewer`)}
 
+${s()}
+
 ## Method
 1. Use provided design/diff/context first.
 2. Check graph with \`graph({action:'find_nodes'})\` then \`graph({action:'neighbors', node_id})\`.
@@ -486,7 +485,7 @@ Reduces per-request token consumption by 40-70% (from ~85K to ~25-50K). Cache hi
 - ALWAYS deposit findings BEFORE compressing
 - Keep each step-summary under 2000 characters
 - If a step produced errors or blockers, include those verbatim (do not compress)
-- On completion: knowledge({action: flush, scope: flow:<run-id>})`},l={"execution-state":`# Execution State: {Task Title}
+- On completion: knowledge({action: flush, scope: flow:<run-id>})`},u={"execution-state":`# Execution State: {Task Title}
 
 **Status:** PLANNING | IN_PROGRESS | REVIEW | COMPLETED | BLOCKED
 **Started:** {timestamp}
@@ -538,4 +537,4 @@ Reduces per-request token consumption by 40-70% (from ~85K to ~25-50K). Cache hi
 
 ## Alternatives Considered
 {Other approaches evaluated and why they were rejected - keeps the "why not" alongside the "why"}
-`};export{s as AIKIT_INSTALL_HINT_SECTION,o as PLATFORM_OUTPUT_RULES_SECTION,c as PROTOCOLS,l as TEMPLATES,a as postTaskLesson,i as preTaskKnowledgeRecall};
+`};export{c as AIKIT_INSTALL_HINT_SECTION,o as PLATFORM_OUTPUT_RULES_SECTION,l as PROTOCOLS,u as TEMPLATES,s as aiKitToolPreference,a as postTaskLesson,i as preTaskKnowledgeRecall};