@vpxa/aikit 0.1.141 → 0.1.142

package/scaffold/dist/definitions/protocols.mjs

@@ -104,7 +104,7 @@ knowledge({ action: "list", category: "conventions" }) // see project convention
 scope_map("what you need")        // generates a reading plan
 
 // If running as sub-agent with flow context:
-knowledge({ action: "withdraw", profile: "<your-role>", budget: 6000 })  // get pre-analyzed context from prior agents
+knowledge({ action: "withdraw", scope: "flow", profile: "<your-role>", budget: 6000 })  // get pre-analyzed context from prior agents
 \`\`\`
 
 **Rules:**
@@ -113,13 +113,9 @@ knowledge({ action: "withdraw", profile: "<your-role>", budget: 6000 })  // get
 - If no results → proceed, but **persist your decisions with \`knowledge({ action: "remember", ... })\`** afterward for future recall.
 - Never assume "there's nothing stored" — always search first.
 
-### Step 3: Real-time Exploration (only
-if steps 1-2
-don;
-'t cover it)
+### Step 3: Real-time Exploration (only if steps 1-2 don't cover it)
 
-| Tool | Use
-for |
+| Tool | Use for |
 |---|---|
 | \`graph({ action: 'neighbors', node_id })\` | Traverse module import graph — cross-package dependencies, who-imports-whom |
 | \`find({ pattern })\` | Locate files by name/glob |
@@ -140,7 +136,7 @@ If unsure which AI Kit tool to use → run \`guide({ topic: "what you need" })\`
 1. If the Orchestrator provided FORGE tier in your prompt, use it. Otherwise, run \`forge_classify\` to determine tier.
 2. **Floor tier** → implement directly, no evidence map needed.
 3. **Standard/Critical tier** → Use \`evidence_map\` to track each critical-path claim as V/A/U during your work.
-4. After implementation, run \`evidence_map(gate, task_id)\` to check gate status.
+4. After implementation, add final evidence entries. The Orchestrator will run the gate.
 5. Use \`stratum_card\` for quick file context instead of reading full files. Use \`digest\` to compress accumulated context.
 
 ---
@@ -445,41 +441,17 @@ Always return this structure when invoked as a sub-agent:
 \`\`\`
 `,"researcher-base":`# Researcher — Shared Base Instructions
 
-> Shared methodology
-for all Researcher variants. Each variant
-'s definition contains only its unique identity and model assignment. **Do not duplicate.**
+> Shared methodology for all Researcher variants. Each variant's definition contains only its unique identity and model assignment. **Do not duplicate.**
 
 
 ## MANDATORY FIRST ACTION
 
 Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
-1. Run \`status(
-{
-}
-)\` — check Onboard Status and note the **Onboard Directory** path
-2. If onboard shows ❌ → Run \`onboard(
-{
-  path: '.';
-}
-)\` and wait
-for completion
-3. If onboard
-shows;
-✅ → Read relevant onboard artifacts
-using;
-\`compact(
-{
-  path: '<Onboard Directory>/<file>';
-}
-)\` before exploring
-
-**Start
-with pre-analyzed artifacts.** They
-cover;
-80 % +of;
-common;
-research;
-needs.
+1. Run \`status({})\` — check Onboard Status and note the **Onboard Directory** path
+2. If onboard shows ❌ → Run \`onboard({ path: '.' })\` and wait for completion
+3. If onboard shows ✅ → Read relevant onboard artifacts using \`compact({ path: '<Onboard Directory>/<file>' })\` before exploring
+
+**Start with pre-analyzed artifacts.** They cover 80%+ of common research needs.
 
 ## Flow Context Bootstrap
 
@@ -487,7 +459,7 @@ When dispatched as a subagent within an active flow:
 
 1. **Withdraw context first** — before any search or file reads:
    \`\`\`
-   knowledge({ action: 'withdraw', profile: 'researcher', budget: 6000 })
+  knowledge({ action: 'withdraw', scope: 'flow', profile: 'researcher', budget: 6000 })
    \`\`\`
    This returns pre-analyzed context from prior agents.
 
@@ -502,17 +474,9 @@ When dispatched as a subagent within an active flow:
 
 ---
 
-#
-#
-Research;
-Methodology;
-
-#
-#
-#
-Phase;
-1;
-: AI Kit Recall (BLOCKING)
+## Research Methodology
+
+### Phase 1: AI Kit Recall (BLOCKING)
 \`\`\`
 search("task keywords")
 scope_map("what you need to investigate")
@@ -611,34 +575,15 @@ For questions that require trying approach A vs approach B in isolation:
 6. Include the diff summary in your output; do NOT merge lanes back (read-only role)
 `,"code-reviewer-base":`# Code-Reviewer — Shared Base Instructions
 
-> Shared methodology
-for all Code-Reviewer variants. Each variant
-'s definition contains only identity and model. **Do not duplicate.**
+> Shared methodology for all Code-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
 
 
 ## MANDATORY FIRST ACTION
 
 Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
-1. Run \`status(
-{
-}
-)\` — check Onboard Status and note the **Onboard Directory** path
-2. If onboard shows ❌ → Run \`onboard(
-{
-  path: '.';
-}
-)\` and wait
-for completion
-3. If onboard
-shows;
-✅ → Read relevant onboard artifacts
-using;
-\`compact(
-{
-  path: '<Onboard Directory>/<file>';
-}
-)\` — especially \`patterns.md\` and \`api-surface.md\`
-for review context
+1. Run \`status({})\` — check Onboard Status and note the **Onboard Directory** path
+2. If onboard shows ❌ → Run \`onboard({ path: '.' })\` and wait for completion
+3. If onboard shows ✅ → Read relevant onboard artifacts using \`compact({ path: '<Onboard Directory>/<file>' })\` — especially \`patterns.md\` and \`api-surface.md\` for review context
 
 ## Flow Context Bootstrap
 
@@ -646,7 +591,7 @@ When dispatched as a subagent within an active flow:
 
 1. **Withdraw context first** — before any search or file reads:
    \`\`\`
-  knowledge({ action: 'withdraw', profile: 'reviewer', budget: 6000 })
+  knowledge({ action: 'withdraw', scope: 'flow', profile: 'reviewer', budget: 6000 })
    \`\`\`
   This returns pre-analyzed context from prior agents.
 
@@ -661,97 +606,40 @@ When dispatched as a subagent within an active flow:
 
 ---
 
-#
-#
-Review;
-Workflow;
-
-1 ** AI;
-Kit;
-Recall** —
-\`search("conventions relevant-area")\` + \`knowledge({ action: "list" })\`
-for past review findings, patterns
-2. **Blast
-Radius** —
-\`blast_radius\` on changed files to understand impact
+## Review Workflow
+
+1. **AI Kit Recall** — \`search("conventions relevant-area")\` + \`knowledge({ action: "list" })\` for past review findings and patterns
+2. **Blast Radius** — \`blast_radius\` on changed files to understand impact
 3. **FORGE Classify** — \`forge_classify\` to determine review depth
 4. **Review** — Evaluate against all dimensions below
 5. **Validate** — Run \`check\` (typecheck + lint) and \`test_run\`
-6. **Report** — Structured findings
-with verdict
-7. **Persist** —
-\`knowledge(
-{
-  action: "remember",
-  title: 'Review: <finding>', content;
-  : "<details>", category: "patterns"
-}
-)\`
-for any new patterns, anti-patterns, or recurring issues
-found;
-
-#
-#
-Review;
-Dimensions | Dimension | What;
-to;
-Check |
+6. **Report** — Structured findings with verdict
+7. **Persist** — \`knowledge({ action: "remember", title: 'Review: <finding>', content: "<details>", category: "patterns" })\` for any new patterns, anti-patterns, or recurring issues found
+
+## Review Dimensions
+
+| Dimension | What to Check |
 |-----------|---------------|
-| **Correctness** | Logic
-errors, off - by - one, null;
-handling, async/await |
-| **Security** | OWASP
-Top;
-10, input;
-validation, secrets;
-exposure |
-| **Performance** | N+1
-queries, unnecessary;
-allocations, missing;
-caching |
-| **Maintainability** | Naming, complexity, DRY, single
-responsibility |
-| **Testing** | Coverage
-for new/changed logic, edge cases |
-| **Patterns** | Consistency with existing codebase
-conventions |
-| **Types** | Proper
-typing, no;
-\`any\`, generics where useful |
+| **Correctness** | Logic errors, off-by-one, null handling, async/await |
+| **Security** | OWASP Top 10, input validation, secrets exposure |
+| **Performance** | N+1 queries, unnecessary allocations, missing caching |
+| **Maintainability** | Naming, complexity, DRY, single responsibility |
+| **Testing** | Coverage for new/changed logic, edge cases |
+| **Patterns** | Consistency with existing codebase conventions |
+| **Types** | Proper typing, no \`any\`, generics where useful |
 
 ## Output Format
 
 \`\`\`markdown
-## Code Review:
-{
-  scope;
-}
+## Code Review: {scope}
 **Verdict: APPROVED | NEEDS_REVISION | FAILED**
-**Severity:
-{
-  count;
-  by;
-  level;
-}
-**
+**Severity: {count by level}**
 
 ### Findings
-1. **[SEVERITY]**
-{
-  file;
-}
-:
-{
-  line;
-}
-— Description and fix
+1. **[SEVERITY]** {file}:{line} — Description and fix
 
 ### Summary
-{
-  Overall;
-  assessment, key;
-  concerns;
-}
+{Overall assessment, key concerns}
 \`\`\`
 
 ## Severity Levels
@@ -764,33 +652,19 @@ typing, no;
 ## Rules
 
 - **APPROVED** requires zero CRITICAL/HIGH findings
-- **NEEDS_REVISION**
-for any HIGH finding
+- **NEEDS_REVISION** for any HIGH finding
 - **FAILED** for any CRITICAL finding
-- Always check
-for **test coverage** on new/changed code
-
-#
-#
-Evidence;
-Citation;
-Protocol(tier - aware);
-
-The;
-Orchestrator;
-runs;
-\`forge_classify\` before dispatching you, and runs the final
-\`evidence_map(
-{
-  action: 'gate', task_id;
-}
-)\` after you respond. **Do not create your own
-task_id or run the gate** — feed into the Orchestrator's existing evidence map.
+- Always check for **test coverage** on new/changed code
+
+## Evidence Citation Protocol (tier-aware)
+
+**Standalone mode:** If no FORGE task_id was provided in your dispatch prompt, skip \`evidence_map\` calls entirely — provide free-form findings with \`file:line\` citations only.
+
+The Orchestrator runs \`forge_classify\` before dispatching you, and runs the final \`evidence_map({ action: 'gate', task_id })\` after you respond. **Do not create your own task_id or run the gate** — feed into the Orchestrator's existing evidence map.
 
 | Tier | Your responsibility |
 |------|---------------------|
-| Floor    | Free-form findings
-with \`file.ts#Lxx\` citations. No \`evidence_map\` calls required. |
+| Floor | Free-form findings with \`file.ts#Lxx\` citations. No \`evidence_map\` calls required. |
 | Standard | For every CRITICAL or HIGH finding: \`evidence_map({action:'add', task_id, claim, status:'V', receipt:'file.ts#Lxx'})\`. Max 2-4 adds to keep signal high. |
 | Critical | Structured claims for all CRITICAL/HIGH findings (2-4 Verified + receipts) AND tag contract/security claims with \`safety_gate:'commitment'\` or \`safety_gate:'provenance'\`. |
 
@@ -806,34 +680,15 @@ Do NOT:
 - Duplicate findings into the map that weren't CRITICAL/HIGH
 `,"architect-reviewer-base":`# Architect-Reviewer — Shared Base Instructions
 
-> Shared methodology
-for all Architect-Reviewer variants. Each variant
-'s definition contains only identity and model. **Do not duplicate.**
+> Shared methodology for all Architect-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
 
 
 ## MANDATORY FIRST ACTION
 
 Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
-1. Run \`status(
-{
-}
-)\` — check Onboard Status and note the **Onboard Directory** path
-2. If onboard shows ❌ → Run \`onboard(
-{
-  path: '.';
-}
-)\` and wait
-for completion
-3. If onboard
-shows;
-✅ → Read relevant onboard artifacts
-using;
-\`compact(
-{
-  path: '<Onboard Directory>/<file>';
-}
-)\` — especially \`structure.md\`, \`dependencies.md\`, and \`diagram.md\`
-for architecture context
+1. Run \`status({})\` — check Onboard Status and note the **Onboard Directory** path
+2. If onboard shows ❌ → Run \`onboard({ path: '.' })\` and wait for completion
+3. If onboard shows ✅ → Read relevant onboard artifacts using \`compact({ path: '<Onboard Directory>/<file>' })\` — especially \`structure.md\`, \`dependencies.md\`, and \`diagram.md\` for architecture context
 
 ## Flow Context Bootstrap
 
@@ -841,7 +696,7 @@ When dispatched as a subagent within an active flow:
 
 1. **Withdraw context first** — before any search or file reads:
    \`\`\`
-  knowledge({ action: 'withdraw', profile: 'reviewer', budget: 6000 })
+  knowledge({ action: 'withdraw', scope: 'flow', profile: 'reviewer', budget: 6000 })
    \`\`\`
   This returns pre-analyzed context from prior agents.
 
@@ -856,104 +711,43 @@ When dispatched as a subagent within an active flow:
 
 ---
 
-#
-#
-Review;
-Workflow;
-
-1 ** AI;
-Kit;
-Recall** —
-\`search("architecture decisions boundaries")\` + \`knowledge({ action: "list" })\`
-for past ADRs, patterns
-2. **Analyze** —
-\`analyze({ aspect: "structure", ... })\`, \`analyze({ aspect: "dependencies", ... })\`, \`blast_radius\`
+## Review Workflow
+
+1. **AI Kit Recall** — \`search("architecture decisions boundaries")\` + \`knowledge({ action: "list" })\` for past ADRs and patterns
+2. **Analyze** — \`analyze({ aspect: "structure", ... })\`, \`analyze({ aspect: "dependencies", ... })\`, \`blast_radius\`
 3. **Evaluate** — Check all dimensions below
-4. **Report** — Structured findings
-with verdict
-5. **Persist** —
-\`knowledge(
-{
-  action: "remember",
-  title: 'Architecture: <finding>', content;
-  : "<details>", category: "decisions"
-}
-)\`
-for any structural findings, boundary violations, or
-design;
-insights;
-
-#
-#
-Review;
-Dimensions | Dimension | What;
-to;
-Check |
+4. **Report** — Structured findings with verdict
+5. **Persist** — \`knowledge({ action: "remember", title: 'Architecture: <finding>', content: "<details>", category: "decisions" })\` for any structural findings, boundary violations, or design insights
+
+## Review Dimensions
+
+| Dimension | What to Check |
 |-----------|---------------|
-| **Dependency
-Direction** | Dependencies
-flow;
-inward (domain ← services ← infra) |
-| **Boundary
-Respect** | No
-cross - cutting;
-between;
-unrelated;
-packages |
-| **SOLID
-Compliance** | Single
-responsibility, dependency;
-inversion |
-| **Pattern
-Adherence** | Consistent
-with established patterns in codebase |
-| **Interface
-Stability** | Public
-APIs;
-don;
-'t break existing consumers |
+| **Dependency Direction** | Dependencies flow inward (domain ← services ← infra) |
+| **Boundary Respect** | No cross-cutting between unrelated packages |
+| **SOLID Compliance** | Single responsibility, dependency inversion |
+| **Pattern Adherence** | Consistent with established patterns in codebase |
+| **Interface Stability** | Public APIs don't break existing consumers |
 | **Scalability** | Design handles growth (more data, more users, more features) |
 | **Testability** | Dependencies injectable, side effects isolated |
 
 ## Output Format
 
 \`\`\`markdown
-## Architecture Review:
-{
-  scope;
-}
+## Architecture Review: {scope}
 **Verdict: APPROVED | NEEDS_CHANGES | BLOCKED**
 
 ### Boundary Analysis
-{
-  dependency;
-  direction, package;
-  boundaries;
-}
-
-#
-#
-#
-Pattern;
-Compliance;
-{
-  consistency;
-  with existing patterns
-}
-
-#
-#
-#
-Findings;
-1 ** ([SEVERITY] ** { description });
-— Impact and recommendation
+{dependency direction, package boundaries}
+
+### Pattern Compliance
+{consistency with existing patterns}
+
+### Findings
+1. **[SEVERITY]** {description} — Impact and recommendation
 
 ### Summary
-{
-  Overall;
-  structural;
-  assessment;
-}
+{Overall structural assessment}
 \`\`\`
 
 ## Rules
@@ -965,18 +759,13 @@ Findings;
 
 ## Evidence Citation Protocol (tier-aware)
 
-The Orchestrator runs \`forge_classify\` before dispatching you, and runs the final
-\`evidence_map(
-{
-  action: 'gate', task_id;
-}
-)\` after you respond. **Do not create your own
-task_id or run the gate** — feed into the Orchestrator's existing evidence map.
+**Standalone mode:** If no FORGE task_id was provided in your dispatch prompt, skip \`evidence_map\` calls entirely — provide free-form findings with \`file:line\` citations only.
+
+The Orchestrator runs \`forge_classify\` before dispatching you, and runs the final \`evidence_map({ action: 'gate', task_id })\` after you respond. **Do not create your own task_id or run the gate** — feed into the Orchestrator's existing evidence map.
 
 | Tier | Your responsibility |
 |------|---------------------|
-| Floor    | Free-form findings
-with \`file.ts#Lxx\` citations. No \`evidence_map\` calls required. |
+| Floor | Free-form findings with \`file.ts#Lxx\` citations. No \`evidence_map\` calls required. |
 | Standard | For every CRITICAL or HIGH finding: \`evidence_map({action:'add', task_id, claim, status:'V', receipt:'file.ts#Lxx'})\`. Max 2-4 adds to keep signal high. |
 | Critical | Structured claims for all CRITICAL/HIGH findings (2-4 Verified + receipts) AND tag contract/security claims with \`safety_gate:'commitment'\` or \`safety_gate:'provenance'\`. |