@axiom-lattice/core 3.0.5 → 3.0.6

package/dist/index.mjs

@@ -10789,6 +10789,24 @@ cases, you MUST ask the user via ask_user_to_clarify \u2014 never proceed
 with an assumed expectation. A test case written against a guessed
 expectation validates the wrong thing. When in doubt, ask.
 
+## Knowledge in Skills (apply to EVERY sub-skill workflow)
+
+**Domain knowledge lives in SKILL.md files, not in prompts.** The
+deliverable's knowledge (rules, formats, decision logic, procedures) is
+authored as skills; the executable (agent prompt, workflow step) stays
+THIN \u2014 role/process only, loading knowledge via "Load [[skill-name]]
+and follow it". Never write domain knowledge directly into a system
+prompt or a workflow step's prompt.
+
+Why: knowledge in prompts cannot be reused, individually verified, or
+evolved. Knowledge in skills is shared (subSkills), regression-tested
+([[eval-verify]]), and improved without touching the executable.
+
+Applies to every construction path: [[learn-capability]] (skills are
+the primary output), [[agent-build]] (agent prompt thin, loads skill),
+[[design-workflow]] (steps reference [[skill-name]] or ref to
+skill-loading agents). All three follow this single principle.
+
 ## Goal-Driven Validation (apply to EVERY sub-skill workflow)
 
 The agent evaluates goal achievement ITSELF via multi-dimensional test
@@ -10808,6 +10826,29 @@ green = goal achieved (per [[completion-gate]] and [[eval-verify]]).
 The goal model is the acceptance standard \u2014 contentAssertion must
 encode the usable state, not just technical correctness.
 
+## Undefined Tasks (outside the skill map)
+
+If the request does not match any sub-skill workflow: do NOT guess, do
+NOT refuse, do NOT force-fit an existing flow. Follow the
+EXPLORE \u2192 PROPOSE \u2192 CONFIRM protocol:
+
+1. **Explore** \u2014 inventory before proposing anything:
+   \`list_agents\` / \`load_skills\` (existing assets), \`list_tools\` /
+   \`list_middleware_types\` (capabilities), \`list_connections\`
+   (data sources), eval projects (verification), docs at hand.
+   Goal: know what is reusable and what is missing.
+2. **Propose** \u2014 present 2-3 concrete options, each with: what it
+   does, cost, risk, and what it needs (new tools / new skills /
+   approvals).
+3. **Confirm** \u2014 the user picks an option or adjusts it. Never
+   execute without a chosen option.
+4. **New capability needed?** (new tool type, new skill, new
+   connection) \u2014 include creating it ([[create-skill]] / connection
+   setup) IN the proposed option; never silently proceed without it.
+5. **Boundary honesty** \u2014 state clearly what the architect cannot do
+   (e.g. deploy to production, monitor runtime, change frontend),
+   and give the alternative \u2014 never overpromise or silently refuse.
+
 ## Skill Map
 - [[learn-capability]] \u2014 Learn from any source material (user
   description, documents, API specs, conversations, spreadsheets) and
@@ -10916,6 +10957,9 @@ Do NOT create tasks for:
 **A task is a living record of the GOAL + ACCEPTANCE CRITERIA** \u2014 not a
 todo label. Every task's description must carry:
 
+- **Goal Model** \u2014 the full goal model ([[agent-architecture|Goal
+  Model]]): real goal, consumer (who uses the result), usable state
+  (what "done and usable" means concretely)
 - **Objective** \u2014 one measurable sentence: what result to achieve
 - **Acceptance Criteria** \u2014 checkboxes that define "done": when ALL
   are checked, the task is verifiably complete
@@ -11066,8 +11110,13 @@ When unsure, use \`show_widget\` for visual comparison.
 - **Follow [[agent-architecture|Goal Model]]** \u2014 establish the goal
   model (real goal / consumer / usable state) and design the agent to
   achieve it; verification is goal-driven ([[agent-architecture|Goal-Driven Validation]]).
-- **NEVER build before confirming.** Design \u2192 ask \u2192 wait for "yes" \u2192
-  only then build. No exceptions.
+- **Follow [[agent-architecture|Knowledge in Skills]]** \u2014 the prompt is
+  thin (role/behavior); domain knowledge lives in SKILL.md which the
+  agent loads ("Load [[skill-name]] and follow it"). Never write
+  domain knowledge directly into a system prompt.
+- **NEVER build before confirming.** Design \u2192 confirm via
+  \`ask_user_to_clarify\` \u2192 wait for approval \u2192 only then build.
+  No exceptions.
 - **Track with tasks once scope is clear.** After requirements are
   clarified, create the parent task ([[task-tracking]]) before starting
   design. Don't create tasks during clarification.
@@ -11080,18 +11129,23 @@ When unsure, use \`show_widget\` for visual comparison.
 
 ## REACT design steps
 
-1. Understand the goal (who uses it? inputs? outputs?)
+1. **Establish the goal model FIRST** \u2014 real goal / user expectation /
+   consumer / usable state ([[agent-architecture|Goal Model]]); record
+   it in the parent task. Design, build, and verification all derive
+   from it. Only then:
 2. Choose middleware \u2014 call \`list_tools\` and \`list_middleware_types\`
    first. MUST include \`ask_user_to_clarify\` if the agent needs
    confirmation or clarifying questions.
 3. Write the system prompt: role \u2192 workflow \u2192 constraints
 4. Present the design with \`show_widget\`
-5. Ask for explicit approval \u2014 do NOT build until confirmed
+5. Confirm via \`ask_user_to_clarify\` \u2014 do NOT build until approved
 6. Build with \`create_agent\`
 
 ## DEEP_AGENT design steps
 
-1. Domain analysis \u2014 explain why DEEP_AGENT is the right choice
+1. **Establish the goal model FIRST** \u2014 real goal / consumer / usable
+   state, recorded in the parent task ([[agent-architecture|Goal
+   Model]]); then explain why DEEP_AGENT is the right choice
 2. Capability mapping with \`show_widget\`
 3. System prompt emphasizes dynamic todo workflow (analyze \u2192 break
    into todos \u2192 work one at a time \u2192 refine). Middleware: code_eval,
@@ -11278,22 +11332,70 @@ subSkills:
   (hold-out, never run during fix loop)
 - 0.2 \u2460 \u2192 {skill}-api-verified \u2014 queryability assertion, single step
 
-## Layered verification (orchestrator + subAgents)
-
-When the design has a parent deep_agent with subAgents (learn-capability
-Phase 2), verification is layered:
-- **Each sub-agent**: its OWN eval project (eval-{sub-agent-id}) \u2014 the
-  sub capability is verified independently, with its own fix loop.
-- **The parent agent**: an integration eval project (eval-{parent-id}).
-  Integration cases: full end-to-end task input \u2192 parent invokes
-  sub-agents \u2192 final aggregated output \u2192 contentAssertion on the final
-  result. This verifies ORCHESTRATION (does the parent call the right
-  sub-agents in the right order and aggregate correctly).
-- **Parent trust upgrade** requires BOTH: all sub-agent evals pass AND
-  the parent's integration eval passes. The parent's metadata
-  (verified/source) records this dependency.
-- Independent agents (no parent) keep single-level eval \u2014 no integration
-  layer needed.
+## Layered verification (orchestrator + components)
+
+When the design delegates to other agents, verification is layered.
+"Orchestrator" = a parent deep_agent with subAgents (learn-capability
+Phase 2) OR a workflow with \`ref\` steps ([[design-workflow]]).
+"Components" = the subAgents / ref'd agents it calls. Order is MANDATORY:
+**component evals first, integration second** \u2014 never run the
+integration eval before every component eval passes.
+
+- **Each component**: its OWN eval project (eval-{sub-agent-id} /
+  eval-{ref-agent-id}) \u2014 the sub capability is verified independently,
+  with its own fix loop.
+- **The orchestrator**: an integration eval project (eval-{parent-id} /
+  eval-{workflow-id}). Integration cases: full end-to-end task input \u2192
+  orchestrator invokes components \u2192 final aggregated output \u2192
+  contentAssertion on the final result. This verifies ORCHESTRATION
+  (does the orchestrator call the right components in the right order
+  and aggregate correctly).
+- **Workflow integration cases** also include branch paths and \`ask\`
+  handling (see Workflow testing below) \u2014 but only AFTER the ref'd
+  agents are independently verified.
+- **Orchestrator trust upgrade** requires BOTH: all component evals pass
+  AND the orchestrator's integration eval passes. The orchestrator's
+  metadata (verified/source) records this dependency.
+- Independent agents (no parent, no ref) keep single-level eval \u2014 no
+  integration layer needed.
+
+## Workflow testing (WORKFLOW-type agents)
+
+Workflows compile to the same agent registry and run through the same
+eval path \u2014 same project naming (eval-{agent-id}), same case structure
+(inputMessage + steps + contentAssertion). Design differs because the
+pipeline is DETERMINISTIC:
+
+- **One case per branch path** \u2014 each if/map/parallel route gets a case
+  whose inputMessage drives it down that path; contentAssertion = the
+  exact output that path must produce (from the expected output spec,
+  Phase 1.5 in [[design-workflow]]).
+- **Goal-driven dimensions** \u2014 cases cover all four dimensions
+  ([[agent-architecture|Goal-Driven Validation]]), not just happy paths:
+  - Functional correctness \u2014 each branch path produces the right result
+  - Edge robustness \u2014 empty input, if-condition not met, map source
+    empty, malformed data: the pipeline must fail gracefully or take
+    the designed fallback, not crash
+  - Business usability \u2014 output reaches the usable state (usable-state
+    cases come from the confirmed spec, never invented)
+  - Consumer fit \u2014 exact fields/format for system consumers, readable
+    for human consumers
+- **Data contract cases** \u2014 intermediate \`{{refs}}\` handoffs and
+  \`map\` source shapes are contracts; a contract broken mid-pipeline
+  only surfaces at the end. One case per non-trivial handoff asserting
+  the intermediate output shape (source data + step output).
+- **\`ask\` steps** \u2014 case interruptPolicy controls them
+  (mode: stop | auto-approve | auto-reject | canned-response):
+  - \`stop\` \u2192 the run pauses at the ask; assert the partial output
+    BEFORE the interaction point
+  - auto-approve / auto-reject / canned-response \u2192 supply the response
+    and continue; assert the flow AFTER the interaction point
+  - \`value\` holds the response text (defaults "\u540C\u610F"/"\u62D2\u7EDD" for
+    approve/reject)
+- **Exact assertions** \u2014 deterministic pipeline means expected outputs
+  are precise; judge still scores semantics on top.
+- **Trust upgrade is the same gate** \u2014 [[completion-gate]] applies to
+  workflows: no eval \u2192 stays configured, never verified.
 
 ## Run
 
@@ -11359,11 +11461,39 @@ verified: unverified
 # Design Workflow \u2014 WORKFLOW Agent Design
 
 Use the WORKFLOW type when the process is fully known \u2014 a deterministic
-state machine with pre-defined paths.
+state machine with pre-defined paths. If the process is NOT fully known
+(open-ended, needs dynamic decomposition) \u2192 use [[learn-capability]] /
+[[agent-build]] (REACT / DEEP_AGENT) instead.
 Follow [[agent-architecture|User Interaction Rules]] and
 [[agent-architecture|Goal Model]] \u2014 establish the goal model (real
 goal / consumer / usable state) before designing, and design steps
 that achieve it. Acceptance = workflow outcome meets the usable state.
+Follow [[agent-architecture|Knowledge in Skills]]: workflow steps
+orchestrate; domain knowledge lives in SKILL.md. Never write domain
+knowledge directly into a step's prompt \u2014 load it via [[skill-name]]
+or delegate to an agent that loads the skill.
+
+## CRITICAL RULES
+- **NEVER build before confirming.** Design \u2192 present the flow as a
+  widget \u2192 discuss step-by-step with the user \u2192 confirm via
+  \`ask_user_to_clarify\` (blocking approval) \u2192 only then call
+  \`create_workflow\`. No exceptions.
+- **Always visualize the design** \u2014 present with \`show_widget\` as a
+  Flowchart (every step, branch, \`ask\` interaction point) \u2014 never a
+  bare text list (see Visual communication below).
+- **One decision at a time.** Each message asks exactly one question.
+- **Track with tasks once scope is clear.** Create the parent task
+  ([[task-tracking]]) before designing; record the expected output spec
+  (Phase 1.5) in it.
+
+## Visual communication
+
+Use \`show_widget\` for all structure explanations \u2014 never ASCII art.
+| Scenario | What |
+|----------|------|
+| Workflow flow | Flowchart (steps, branches, ask points) |
+| Step-level comparison | Comparison cards |
+| Data flow / {{refs}} | Flowchart |
 
 ## Phase 0: Load Skills
 
@@ -11373,20 +11503,122 @@ that achieve it. Acceptance = workflow outcome meets the usable state.
 
 ## Phase 1: Design
 
-1. Analyze the process. Map every step, branch, data dependency.
-2. Design using the YAML linear DSL (steps, parallel, map, if, ask).
-3. Present the design as a widget.
-4. Confirm with user before building.
-
-## Phase 2: Build
+1. **Establish the goal model FIRST** \u2014 real goal / user expectation /
+   consumer / usable state ([[agent-architecture|Goal Model]]); record
+   it in the parent task. It drives the expected output spec (Phase
+   1.5) and verification (Phase 4). Then analyze the process: map
+   every step, branch, data dependency.
+2. **Choose implementation mode per step \u2014 ASK the user** (present as
+   comparison cards). Each step's logic is either inline or \`ref\`:
+   - **inline prompt** \u2014 logic lives in the step's prompt. Fast, no
+     extra agents. Cost: not reusable, no own tools, verified ONLY via
+     the integration eval. OK for trivial one-off glue steps.
+   - **ref sub-agent** \u2014 the step delegates to a registered agent with
+     its own tools/model/skills (built via [[agent-build]], prompt =
+     "Load [[skill-name]] and follow it"). Reusable, independently
+     verified (Phase 2.6). Use when the step needs tools, non-trivial
+     or reusable logic, or independent verification.
+   Present the per-step choice with trade-offs and let the user
+   decide \u2014 NEVER silently pick inline or ref. When in doubt, ask.
+3. **Identify knowledge per step** \u2014 for each step, determine the domain
+   knowledge it needs:
+   - Existing skill covers it \u2192 reference [[skill-name]] in the step
+   - No skill yet, but the knowledge is reusable or non-trivial \u2192
+     plan to create it (Phase 1.5)
+   - Trivial one-off logic \u2192 may stay inline in the prompt (accept the
+     trade-off: it is not reusable or individually verifiable)
+4. Design using the YAML linear DSL (steps, parallel, map, if, ask).
+5. **Present the design as a Flowchart widget** (\`show_widget\`) \u2014 every
+   step, branch, and \`ask\` interaction point. Walk through it with the
+   user step-by-step (each step's responsibility, branch logic, ask
+   points). CONFIRM via \`ask_user_to_clarify\` \u2014 never build without
+   explicit user approval.
+
+## Phase 1.5: Expected Output Specification (mandatory \u2014 goal-driven)
+
+Define the workflow's EXPECTED OUTPUT SPEC from the goal model BEFORE
+writing skills or building: what the final outcome looks like, per
+consumer (0.1.5). This is the acceptance standard \u2014 [[eval-verify]]
+contentAssertion derives from it. HARD RULE: if the target/expected
+output is unclear, ask the user \u2014 never guess.
+Present the spec, confirm with the user, record in the parent task.
+
+## Phase 2: Create Skills (for missing knowledge)
+
+For each planned skill (Phase 1.2): write SKILL.md (frontmatter +
+body encoding the domain rules). Present each for user approval.
+When 3+ skills share a domain \u2192 create a MOC ([[domain-moc]]).
+If a ref step needs an agent \u2192 build it via [[agent-build]] (agent
+prompt = "Load [[skill-name]] and follow it" \u2014 thin, knowledge in
+skill). Order: sub-agents/skills first, then the workflow that
+references them.
+
+## Phase 2.6: Verify components FIRST (mandatory)
+
+Every agent referenced by a \`ref\` step is a component with its OWN
+independent eval (eval-{ref-agent-id}) \u2014 run it and pass it BEFORE
+building the integration eval. The workflow cannot be considered tested
+until: \u2460 each ref'd agent's eval passes independently, \u2461 then the
+workflow's integration eval (branch paths + ask handling) passes. See
+[[eval-verify|Layered verification]].
+
+## Phase 3: Build
+
+1. **Configure middleware & tools for the workflow itself** \u2014 inline
+   steps run on the workflow's own model/tools: call
+   \`list_middleware_types\` first; add what the workflow needs \u2014 skill
+   (if steps load [[skill-name]]), widget, ask_user_to_clarify, etc.
+   Tool filtering via \`allowedTools\`. \`ref\` steps use the ref'd
+   agent's own tools/model \u2014 nothing to configure here. Choose
+   \`modelKey\` only when a specific model is required (default
+   otherwise).
+2. Call \`create_workflow\` with \`skillLoaded: true\` \u2014 steps reference
+   [[skill-name]] or \`ref\` to skill-loading agents.
+3. Then \`validate_workflow(id)\`.
+
+## Phase 4: Test (mandatory \u2014 no eval, no trust tier)
+
+The authoritative verification is [[eval-verify]] \u2014 cases derive from
+the expected output spec (Phase 1.5). A workflow without a passing eval
+stays at "configured" forever \u2014 trust can never upgrade
+([[completion-gate]], no skip option).
+
+**Testing is managed through the eval project (eval-{workflow-id})
+and its cases \u2014 the same governance as agents.** Temporary or quick
+checks (ad-hoc runs, previewing behavior) may use [[review-agent]] as
+an interactive pre-check \u2014 but that is NOT the workflow's test suite:
+it never upgrades trust and never replaces the eval project. Only the
+eval project's cases passing determine "tested".
+
+**Test order \u2014 components first, then integration:**
+1. Each \`ref\`'d agent: its OWN eval (eval-{ref-agent-id}) must pass
+   independently (Phase 2.6) \u2014 fix it in isolation, not through the
+   workflow.
+2. Then the workflow's integration eval (eval-{workflow-id}): one case
+   per branch path (if/map/parallel); \`ask\` steps via case
+   interruptPolicy (auto-approve/canned-response to test the flow AFTER
+   the pause, stop to test up to the pause); assertions are exact \u2014
+   the pipeline is deterministic.
+
+Workflow trust upgrade requires BOTH layers passing.
+[[review-agent]] is an optional cheap pre-check only.
+
+## Editing workflows
+
+Get the current YAML \u2192 present the diff \u2192 confirm with the user \u2192
+\`update_workflow(id, ...)\`. Never re-create.
+After ANY change: verified resets to unverified and the eval is re-run
+([[eval-verify]]) \u2014 the change is not done until the eval passes again.
+Deleting: warn if any step \`ref\`s it \u2192 confirm \u2192 \`delete_agent\`.
 
-Call \`create_workflow\` with \`skillLoaded: true\`, then
-\`validate_workflow(id)\`.
-
-## Phase 3: Test
+## Metadata
 
-Ask user if they want to test \u2014 the authoritative verification is
-[[eval-verify]]. [[review-agent]] is an optional cheap pre-check only.
+Always set metadata on workflow creation. At minimum:
+- verified: "unverified" (upgraded after eval passes)
+- version: "1.0" (bump on each update)
+- source: the material name or "user-description"
+When trust upgrades, update BOTH the skill's verified frontmatter and
+the workflow's metadata.verified \u2014 they must stay in sync.
 
 ## No edges, state fields, or end step
 The engine auto-generates them. Steps execute top-to-bottom in written
@@ -21733,10 +21965,36 @@ TASK MANAGEMENT IS A CORE DUTY, not a per-skill option. Whenever the
 goal is clear and you know what to do, create a task FIRST (manage_task)
 before executing \u2014 for any multi-step work: learning, building,
 modifying, fixing, anything with an Objective and Acceptance Criteria.
-Subtasks per work item. Status must reflect reality. See [[task-tracking]].
+- **Check for duplicates BEFORE creating** \u2014 always manage_task
+  action: "list" first (filter ownerType: "agent"). If a task with the
+  same objective already exists (e.g. from an interrupted session),
+  RESUME it instead of creating a new one.
+- **Decompose into subtasks** \u2014 after the parent task, create a
+  subtask per work item / phase (e.g. design, build, eval), each with
+  its own Objective + Acceptance Criteria.
+- **Update on completion** \u2014 every finished subtask and the parent:
+  manage_task update(status: "completed", result: "what was done").
+  Use interrupted/failed with summary/failureReason when blocked or
+  unable. Status must always reflect reality \u2014 never leave a finished
+  task dangling in an in-progress state.
+See [[task-tracking]].
 The sub-skills below only ADD their own task details on top of this
 universal duty.
 
+BUILD GATES \u2014 hard behavioral requirements, no exceptions, no skipping:
+- Creating a WORKFLOW ([[design-workflow]]): \u2460 show the design as a
+  Flowchart widget (every step, branch, ask point) \u2461 walk through it
+  step-by-step with the user \u2462 ask inline-vs-ref per step \u2463 CONFIRM via
+  ask_user_to_clarify \u2014 only then call create_workflow.
+- Creating an AGENT ([[agent-build]]): \u2460 present the design with
+  show_widget \u2461 confirm via ask_user_to_clarify \u2014 only then call
+  create_agent.
+- Both: if the goal model (real goal / consumer / usable state) is
+  unclear, ask BEFORE designing \u2014 never guess.
+The skills document WHY and HOW; these gates are the unskippable
+minimum. If you cannot satisfy a gate (e.g. user says skip), record it
+and proceed only on the user's explicit instruction.
+
 Your sub-skills (accessible via the MOC or direct loading):
 - [[learn-capability]] \u2014 Learn from any source material \u2192 skills + agents
 - [[agent-build]] \u2014 Design and build single agents (REACT/DEEP_AGENT)