@tangle-network/agent-runtime 0.295.4 → 0.297.2

package/skills/profile-authoring/references/research-directors.md

@@ -0,0 +1,48 @@
+# Research director authoring
+
+Use when creating one or more research directors, revising their profiles, or continuing a program with changed instructions or capabilities. The operator commissions the research and supplies sources, authority, and resources; directors choose and revise questions, methods, specialists, and topology.
+
+## Define the research responsibility
+
+Read the actual commission and prior artifacts before composing a profile. State the decision a result could change, the source material, accepted outcome classes, and the unresolved assumptions. A program name or “find novel research” leaves those decisions unspecified.
+
+Give each director a reason to exist: a distinct scientific question, method, competing hypothesis, or independent check. Require it to select domain skills and resources from the maintained catalog, explain that selection, and author its children's complete profiles. Reuse a profile unchanged when its responsibilities and capabilities fit; different names alone add no scientific diversity. A specialist's result must name how it changes the shared question.
+
+Put standing responsibility in the profile and the current question in the assignment. A continuation carries established results, failed routes, unresolved disagreements, and the next decision. Compare predecessor and successor profiles explicitly; preserve the earlier registration and use the execution owner's existing continuation or fork contract.
+
+## Give analysis a working execution path
+
+A request to reflect grants no tool, trace access, or model budget. Before launch, inspect the installed interfaces and connect the analysis required by the commission:
+
+| Need | Existing owner and path |
+| --- | --- |
+| Analyze a settled child's execution | Eval registry through Runtime `analystsFromRegistry`; explicitly grant the served `list_analysts` and `run_analyst` coordination tools. |
+| Author a new analysis question | `define_analyst`, when the registry was constructed with authoring and an authorized engine resolver. Definitions, model requests, evidence rules, and limits are data retained by Runtime. |
+| Run a native, subscription-backed analysis agent | Runtime `analyzeOnSettle: [{ kind, agent, directive, over?, to? }]` with a complete analyst `AgentProfile`. This uses the existing worker execution path, budget, identity, and finding delivery. |
+| Receive registry analysis automatically | Runtime `analyzeOnSettle` routes naming a configured lens. Select matching workers and the recipient; verify its `finding` events reach the director. |
+| Detect trouble during execution | Runtime `watchWorkers` with a backend that supplies live traces; directors inspect findings and choose interventions. `run_analyst` accepts settled workers only. |
+| Reassess retained runs | Runtime observation/corpus integration with Eval's registry, using the same retained evidence and analyst definitions. |
+
+Choose the analysis route the configured provider can execute. A native analyst profile uses worker execution; registry tools require an actual configured investigation engine. A provider chat client that rejects tool-bearing requests cannot serve a recursive tool-using analyst merely by selecting a model. Keep that capability gap explicit; use the native agent route when appropriate.
+
+Use the actual coordination names exposed by the chosen harness when authoring grants. Inspect the analyst menu: generic failure and efficiency summaries do not assess the commission's scientific claims. Select or author analyses for the particular uncertainty, with access to original artifacts and sources where the question requires them. A trace-only reviewer cannot establish physical validity or field novelty from a researcher's assertion.
+
+Choose the existing Eval investigation engine and lower-level driver appropriate to the evidence, including recursive analysis where supported. Record its model, definition version, tools, budget, evidence scope, and findings. Missing trace coverage, inaccessible artifacts, a failed analyst, and an unreviewed claim remain different outcomes. A finding is advice with cited evidence; independent acceptance remains outside the producing lineage.
+
+## Check the profile before scaling
+
+Compare authored instructions, effective profile, materialized resources, and served tools for the root and a representative child. Retain component sizes and exact versions from existing profile/trace summaries. Identify measured versus estimated tokens and unavailable harness context. Confirm the child received the full authoring skill and this reference when it can create research directors.
+
+Inspect one real analysis result and the director's response during the first authorized research work. It must cite the evidence and either change the work or explain why the finding does not justify a change. Delivery of a finding alone proves neither consumption nor improvement. Preserve blocked capabilities in the run record and fix their owning package; the operator's manual critique must not be credited to the director.
+
+## Keep research and execution assessable
+
+The director maintains a concise research account in the existing knowledge/artifact store throughout execution: the question, strongest supported answer, assumptions, reproducible evidence, prior art, disagreements, and next valuable experiment. It links individual claims to exact sources and independent checks. It separately explains execution choices, failure causes, wasted work, and proposed profile changes. These are research products; file counts and completed tasks do not substitute for them.
+
+Read measured counters from the existing trace projection. For judgments such as instruction compliance, skill application, reward hacking, or wasted effort, name the analyst, rubric, cited examples, reviewed population, exclusions, and uncertainty. Use calibrated judgments for acceptance; leave unreviewed populations unassessed. Distinguish repeated attempts, continuations, and independent trials.
+
+For every consequential endogenous or operator change, preserve who acted, why, the triggering evidence, before/after identities, and the affected execution or fork through existing records. Link knowledge revisions and profile changes to those records; record external deployment changes separately from authored research changes. Keep original evidence immutable. A missing event requires a capture fix, not a reconstructed claim of complete provenance.
+
+## Completion evidence
+
+A configured skill proves instructions were supplied. A captured tool call proves an action occurred. A reviewed artifact supports a claim. An improvement claim additionally requires the declared comparison. Report each level separately, with unknown outside acceptance unchanged.

package/skills/supervise/SKILL.md

@@ -23,6 +23,7 @@ The authored profile must explain its own ability to delegate; Runtime does not
 
 Before creating or changing any profile, follow [profile authoring](../profile-authoring/SKILL.md): the audience and its acceptance test, the probed proxy gap, the referee, the honest null, and the profile contract.
 The task names the concrete artifact and completion check; the profile names the method and granted capabilities.
+A research director also carries the [research authoring reference](../profile-authoring/references/research-directors.md); mount it with the skill and preserve its digest.
 
 ## Direct the work
 
@@ -31,10 +32,13 @@ The task names the concrete artifact and completion check; the profile names the
    Fill available capacity while distinct useful assignments remain.
 3. Pull settlements, findings, and questions with `await_event`.
    A bounded wait returning does not establish failure.
+   Use granted analysts on settled workers and inspect live detector findings when the configured backend supports them.
+   Record which finding changed an assignment, profile, claim, or check; give an evidence-backed reason for rejecting it.
 4. Inspect quiet or stalled workers with `observe_agent` before steering them.
    Correct an observed wrong path, missing requirement, or new evidence.
 5. Check each returned artifact before using it.
    Preserve failed attempts and change the profile or assignment when evidence supports another attempt.
+   Retain the actor, reason, cited evidence, prior profile digest, and successor identity through the existing change and execution records.
 6. After recovery, reconcile the journal, roster, settlements, questions, findings, and spend before creating replacements.
 
 Use `continuity: 'resume'` to continue the most recent settled worker with that profile name.
@@ -46,6 +50,8 @@ A quiet worker alone is not a reason to invent a deadline.
 ## Accept delivery
 
 Inspect the artifact and its independent completion result.
+For research, keep a readable account current: the question, what the evidence establishes, limitations, disputed claims, and the next consequential check.
+Link exact artifacts and separate the scientific result from execution critique and external acceptance.
 Preserve profile identities, assignment keys, parent-child links, continuations, costs, failures, and missing accounting.
 Worker prose cannot approve its own result.
 Use `submit_result` only when the attached check can validate this agent's artifact.