@xdxer/dingtalk-agent 0.1.4-beta.1 → 0.1.4-beta.10

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to `@xdxer/dingtalk-agent` are documented here. The project follows semantic versioning; prerelease entries describe release candidates and do not imply that Live canaries or registry publication have completed.
+
+## 0.1.4-beta.10 - 2026-07-19
+
+### Removed
+
+- Legacy pre-kernel modules `src/boot.ts`, `src/duty.ts`, `src/kb.ts`, `src/runs.ts` and the unused `templates/ontology/` tree. They were dead code outside the current CLI, were already excluded from the published package, and `runs.ts` conflicted with the documented "Markdown is not a lock, idempotency store, or Receipt" boundary.
+- The `kb`/`duties`/`eval` fields from the default AgentConfig. Existing workspace configs keep unknown fields through passthrough normalization; no migration is required.
+
+### Changed
+
+- Entry documents now match repository reality: CLAUDE.md gains run-mode criteria, the eval-Skill reading path, and an annotated command list; README lists all five bundled Skills; the English README is marked as a condensed overview; SECURITY.md states the actually maintained dist-tag; the eval Skill's L1 wording matches the real `dta lab eval` plan/`--execute --yes` flow (Skill 0.5.1).
+
+### Release boundary
+
+- Distribution is limited to the public npm `beta` dist-tag. No robot, webhook, schedule, Trigger, or DingTalk/Multica side effect is created. The Live waivers recorded for beta.9 remain unchanged.
+
+## 0.1.4-beta.9 - 2026-07-19
+
+### Added
+
+- A general Agent kernel with frozen Agent Definitions, invocation context, employee response gates, durable Session/Run/Wait state, and host-verified completion evidence.
+- Three-layer semantic memory with local and DingTalk document/table routing, candidate review/publish flow, and cold-start recovery contracts.
+- Reusable Compose, Eval, Boot, and Deploy Skills plus two independently auditable example Agents.
+- A Provider-bound Agent Project model with isolated OpenCode and Multica Development Workspaces.
+- OpenCode managed create/run/eval with random Basic Skill load probes and Response/Filesystem/Workspace/Artifact evidence.
+- Multica read-only inspection, plan-bound Agent/Skill deployment, independent readback, load smoke, recovery, rollback, and retire contracts.
+- Policy-bound Promotion Receipts linking local Eval evidence to Multica deployment evidence, plus redacted review-only feedback candidates.
+- Deterministic release-readiness checks that install the generated tarball into an isolated HOME and exercise setup, doctor, bootstrap, eval planning, upgrade, and rollback planning without real DingTalk or Multica access.
+- Default-safe Phase 9 personal-event and Phase 11B remote-state Live runners with explicit resource authorization, fake-DWS contracts, independent readback, and gitignored raw evidence.
+- Plan-bound `dta agent enhance` for existing repositories, with operation-scoped backups, semantic config merging, hash readback, source-drift protection, and zero DingTalk/Trigger side effects.
+- A sanitized local dogfood record proving that an enhanced release-manager Agent reaches `ready` only after a real OpenCode/DeepSeek random Basic load probe.
+
+### Changed
+
+- Basic Behavior advanced to 0.10.0 with evidence-gated task completion. The recorded controlled-regression sample passed its safety and artifact gates, but does not prove a stable behavior-quality gain over 0.9.4.
+- Completion grading now detects contradictory positive claims while preserving negated, conditional, and corrected statements; effectiveness requires a predeclared multi-run policy instead of any single positive delta.
+- Agent audit now keeps generated body and Role Skill templates partial until identity, responsibilities, SOPs, and acceptance placeholders are replaced with real semantics.
+- The deterministic contract suite now covers 60 independent scenarios.
+
+### Live waivers and release boundary
+
+- The user explicitly waived real Multica apply/promotion, personal-event canary, and remote semantic-state Live as release gates for this beta. The release does not relabel local or fake-Provider evidence as real platform proof.
+- Distribution is limited to the public npm `beta` dist-tag, Git tag, and GitHub pre-release. It does not create a robot, webhook, schedule, Trigger, or DingTalk/Multica side effect.
+
+## 0.1.4-beta.8 - 2026-07-16
+
+- Published beta baseline preceding the general Agent kernel and Provider-bound Workspace series.

package/README.en.md

@@ -0,0 +1,397 @@
+<div align="center">
+
+# dingtalk-agent
+
+**A shared behavior kernel for DingTalk digital employees.**
+
+[![npm](https://img.shields.io/npm/v/%40xdxer%2Fdingtalk-agent?logo=npm&color=cb3837)](https://www.npmjs.com/package/@xdxer/dingtalk-agent)
+[![CI](https://github.com/D1-2004/dingtalk-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/D1-2004/dingtalk-agent/actions/workflows/ci.yml)
+[![Node.js](https://img.shields.io/node/v/%40xdxer%2Fdingtalk-agent)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/license-MIT-2ea44f)](LICENSE)
+
+English · [简体中文](README.md)
+
+*This English README is a condensed overview; the Chinese README is the complete, authoritative reference.*
+
+</div>
+
+## What it is
+
+**DWS gives an Agent DingTalk system calls. dingtalk-agent (`dta`) gives every Agent an inheritable, frozen, and verifiable employee behavior kernel.** It does not own event delivery and does not duplicate DingTalk APIs. Starting from a normalized invocation, it organizes the Agent definition, perception enrichment, response eligibility, Session/Run state, action gates, and effect evidence into a Skill-first container.
+
+```text
+Agent Host + dta Kernel + Agent Definition + Basic Behavior + Role Skills + DWS
+    = a DingTalk digital employee that can keep working
+```
+
+| Layer | Owns | Does not own |
+|---|---|---|
+| Agent Definition | Identity, responsibilities, service scope, Skills, resources, authority | Current Run state or IDs guessed from message text |
+| Basic + Role Skills | When to reply, ask, stay silent, and how to perform role work | Bypassing identity, target, or effect gates |
+| dta Kernel | Invocation, enrichment, Session/Run/Wait, Action Gate, Receipt | Models, universal event listeners, or a second DWS |
+| DWS | DingTalk messages, docs, tasks, calendars, tables, and other product operations | Deciding whether an employee should act and on whose behalf |
+
+Claude Code, Codex, OpenCode, and other Agent Hosts can use the same kernel. Trigger adapters, models, sandboxes, Role Skills, and storage providers remain replaceable.
+
+## Why it exists
+
+DWS is enough for occasional manual API operations. A digital employee that works over time also needs a maintained **body, state, and constrained action boundary**. Calling an API is not the same as behaving like a colleague. A reliable Agent must:
+
+- stay quiet in unmentioned group conversations and respond to direct messages or explicit mentions;
+- complete well-specified work directly and ask only one truly blocking question;
+- never guess recipients, identities, document IDs, or permissions from natural-language text;
+- acknowledge long work, wait for dependencies, and resume from a later event;
+- distinguish a command attempt, platform visibility, delivery, and human acceptance;
+- store task state, business memory, long-term knowledge, locks, and receipts in the right media.
+
+The boundary is: **Skills advise, the CLI enforces, and DWS executes.** Semantic judgment remains in Skills; invariants belong in code; DingTalk product operations stay in DWS.
+
+> `0.1.4-beta.9` is published on the public npm `beta` dist-tag with a matching Git tag and GitHub pre-release. It includes the Basic 0.10.0/0.9.4 model regression, host-issued Completion Evidence, remote semantic-state cold-start and Live-ready runners, the developer Golden Path, safe enhancement of existing Agent repositories, Provider-bound Workspace W1–W5, Completion-grader hardening, a Phase 9 personal-event Live-ready runner, and isolated installation acceptance, with 60 deterministic contracts. Phase 8's recorded sample passed the safety and artifact gates that existed at the time, but did not prove a stable model-quality gain for 0.10.0. Phase 15 adds fail-closed contradictory-claim detection and a predeclared effectiveness policy without rewriting historical scores. Real personal-event, remote-state, and Multica Live were explicitly waived as release gates for this beta; local and fake-Provider evidence is not relabeled as real platform proof, and no Trigger or DingTalk/Multica side effect was created.
+
+## Quick start
+
+Requires Node.js 18.3 or later.
+
+```bash
+npm install --global --prefix "$HOME/.local" \
+  --registry=https://registry.npmjs.org @xdxer/dingtalk-agent@beta
+"$HOME/.local/bin/dta" setup --skip-cli-install
+
+dta --version
+dta doctor
+```
+
+`setup` checks Node.js, DWS version and authentication, installs and verifies the Basic Behavior Skill, and reports whether Claude Code, Codex, and OpenCode can discover it. `listen` is an optional development adapter, not the mandatory Agent entry point.
+
+For a source release candidate, run the deterministic tarball acceptance:
+
+```bash
+npm run release:check
+```
+
+It creates a real npm tarball, installs it offline into a fresh HOME/prefix, and exercises setup, doctor, direct bootstrap, a plan-only lab eval, forced upgrade from the same tarball, and explicit rollback dry-run. It uses fake DWS and skills-installer binaries only; it sends no DingTalk message, accesses no Multica resource, creates no Trigger, and performs no npm publish, Tag, or GitHub Release.
+
+## Three runtime modes
+
+### Direct Session
+
+No initialized Workspace is required. The Agent behaves as a normal colleague but does not invent identity, memory, targets, or DingTalk authority.
+
+```bash
+dta bootstrap --json
+dta bootstrap --agent local-dir:/path/to/agent --json
+```
+
+### Mounted Session
+
+The Agent hydrates a local folder or a DingTalk document without requiring `init` on every session.
+
+```bash
+dta bootstrap \
+  --agent local-dir:/path/to/agent \
+  --skills local-dir:/path/to/agent/skills \
+  --memory local-md:MEMORY.md \
+  --knowledge 'dingtalk-doc:<node-or-url>' --json
+```
+
+### Prepared Run
+
+A trusted host freezes the Invocation, Definition, Skills, target, budgets, and allowed actions. Message effects can only pass through the typed Broker or `dta act`.
+
+## From one Agent to many
+
+Different employees should vary only in their Definition, Role Skills, field bindings, storage, and authority. They share Basic Behavior, Session/Run/Wait, the two-part gate, Receipt semantics, and the same Lab contract.
+
+A minimal Agent kit is:
+
+```text
+my-agent/
+├── AGENTS.md                  identity, responsibilities, deliverables, boundaries
+├── agent.bindings.json        Definition and semantic-storage routes
+├── opencode.json              Host loading contract
+├── .agents/skills/            Host-visible Skill exposure
+├── skills/<role>/SKILL.md     role-specific methods
+├── MEMORY.md                  reviewed semantic memory
+├── knowledge/INDEX.md         knowledge entry point
+└── .dingtalk-agent/artifacts/ independently verifiable deliverables
+```
+
+Use the bundled [`dingtalk-agent-compose`](skills/dingtalk-agent-compose/SKILL.md) Skill to audit and assemble a Git checkout or local folder as an Agent, optionally binding semantic state to DingTalk documents. Basic Behavior must be forced into every Host session; directory discovery alone is not proof that the Skill body was loaded.
+
+The recommended definition stays local and versioned: `AGENTS.md + Role Skills`. `agent.bindings@1` routes memory and knowledge either to local Markdown or dedicated DingTalk documents, while artifacts and private control state stay local. The shortest acceptance path is:
+
+```bash
+# Plan only: no local write, DWS access, or Trigger creation.
+dta agent enhance --project-name release-agent \
+  --role-skill release-manager --dry-run --json
+
+# Review operations/blockers/semanticReview, then use the current plan ID.
+dta agent enhance --project-name release-agent \
+  --role-skill release-manager \
+  --plan-id <current-plan-id> --yes --json
+
+dta bootstrap --bindings agent.bindings.json --json
+
+# Static only: no model and no DWS. Gaps return partial and exit code 2.
+dta agent audit --bindings agent.bindings.json \
+  --require-skill <role-skill-name> --json
+
+# Isolated OpenCode load probe; still no DingTalk access.
+dta agent audit --bindings agent.bindings.json \
+  --require-skill <role-skill-name> --verify-load --yes --json
+```
+
+This chain has been dogfooded once with `examples/agents/release-manager`. On OpenCode 1.17.14 and `deepseek/deepseek-chat`, the with-skill random probe loaded exactly 1/1, the without-skill control did not guess it 1/1, and the final audit moved from `partial` with only `host.load-probe` missing to `ready`. This proves that the assembly and load path works for that fixture; it does not prove domain-task quality or a stable behavior gain. See the [sanitized dogfood summary](evals/baselines/2026-07-17/agent-enhance-opencode-dogfood-summary.json).
+
+`agent enhance` merges rather than blindly overwriting an existing repository. Before updating an old file it creates an operation-scoped backup under `.dingtalk-agent/backups/agent-enhance/<operationId>/`, and a custom `stateDir` is added to `.gitignore`; a stale plan, source drift, invalid Role path, unknown OpenCode instruction entry, path escape, or symlink fails before replacement. Apply has local-file side effects only. Generated body and Role Skill templates intentionally remain `partial` until real identity, responsibilities, deliverables, refusal boundaries, domain SOPs, and acceptance criteria replace every placeholder. Thus a ready [`agent-enhancement-plan@1`](docs/schemas/agent-enhancement-plan.schema.json) means “safe to apply,” not “the Agent is ready”; [`agent-enhancement-receipt@1`](docs/schemas/agent-enhancement-receipt.schema.json) carries the follow-up audit gaps.
+
+`agent-audit@1` separates Definition, Storage, Host exposure, and actual loading. A remote memory/knowledge binding remains `partial` until an authorized storage evaluation proves identity, document type, hashes, independent readback, and model use and its report is supplied with `--remote-report`. Local cache presence is never remote proof; Wait, generation, idempotency, Receipts, and credentials remain in the host atomic store.
+
+### One Project, multiple development Workspaces
+
+`agent.bindings.json` describes the Agent body and storage routes. A root-level [`dingtalk-agent.json`](docs/schemas/project.schema.json) declares where the same Agent is developed. Each Development Workspace binds exactly one Host Provider, while memory, knowledge, and artifacts remain independent Storage bindings.
+
+```text
+Agent Project
+├── local-dev   ── Host: OpenCode ── Storage: local-md/local-dir
+├── multica-dev ── Host: Multica  ── Storage: dingtalk-doc/local-dir
+└── legacy-prepared ── read-only view of the existing workspace@1
+```
+
+W1 exposes a read-only control plane:
+
+```bash
+dta info --json
+dta workspace list --json
+dta workspace show local-dev --json
+dta workspace doctor local-dev --json
+```
+
+The CLI discovers the Project from any child directory and reports Provider configuration sources, `desiredHash/observedHash`, and [`workspace-state@1`](docs/schemas/workspace-state.schema.json). Doctor inspects only the named Workspace: a missing Multica installation cannot make `local-dev` fail, while Provider, source, managed bytes, or desired-state drift fails closed.
+
+OpenCode W2 adds a managed development environment. `create` is plan-only by default; `--yes` atomically materializes a gitignored copy and independently hashes it. `run/eval` use external temporary sandboxes. Provider state becomes `ready` only after the random Basic load probe, exported Session directory, and hard evidence gates pass.
+
+```bash
+dta workspace create local-dev --dry-run --json
+dta workspace create local-dev --yes --json
+dta workspace use local-dev --json
+dta workspace run local-dev --prompt-file prompt.md --execute --yes --json
+dta workspace eval local-dev --suite evals/core.json --runs 3 --execute --yes --json
+```
+
+`workspace run` is zero-tool. File and Artifact tools are available only through case-scoped eval permissions. W2 writes local managed Workspace, selection, state, and evidence, but never calls DWS. CI, evaluations, and future deploy flows must select the Workspace explicitly rather than rely on `current-workspace`.
+
+Multica W3 first exposes controlled remote reads. `plan` never starts Multica. After explicit confirmation, `inspect/remote-list` use the declared profile, Workspace ID, Runtime ID, and optional Agent ID to read auth, Workspace, Runtime, Agent, Skill catalog, and assignments. An existing Agent must be bound by `agentIdFrom` or trusted prior state and is never adopted by display name.
+
+```bash
+dta workspace plan multica-dev --json
+dta workspace inspect multica-dev --execute --yes --json
+dta workspace remote-list multica-dev --execute --yes --json
+dta workspace status multica-dev --json
+```
+
+Evidence retains only minimum resource facts and raw-output hashes; it excludes tokens, email, cleartext Server URLs, Agent instructions/runtime config, and Skill content. Identity, default Workspace, scope, stable IDs, Skill uniqueness, and evidence hashes all fail closed. A successful inspection leaves state at `verifying`: `readyForApply=true` only means W4 planning may start.
+
+W4 turns that trusted inspection into a plan-bound apply through `dta deploy`. Dry-run freezes the profile, Workspace, Runtime, Agent, Definition, complete Skill-tree hashes, and maximum forward/rollback write budgets; apply re-reads the same ID chain. Only the current `--plan-id` plus explicit `--yes` may create or update remote resources. The CLI synchronizes managed Boot, Basic, and Role Skill trees and the exact assignment, then uses a dedicated Issue to independently read the Skill tool trace and an exact JSON response. Both must pass before state can move from `verifying` to `ready`.
+
+```bash
+dta deploy --workspace multica-dev --dry-run --json
+dta deploy --workspace multica-dev --plan-id <plan-id> --yes --json
+dta deploy --workspace multica-dev --status --json
+dta deploy --workspace multica-dev --status --execute --yes --json
+dta deploy --workspace multica-dev --list --json
+dta deploy --workspace multica-dev --retire --dry-run --json
+dta deploy --workspace multica-dev --retire --plan-id <plan-id> --yes --json
+```
+
+A timed-out write persists its operation/Receipt and enters `reconciling`; status performs independent reads rather than retrying or rolling back an ambiguous action. If Agent create returned no ID, recovery reads candidates by stable ID and binds only one exact instructions/runtime fingerprint match, never a display name alone. Confirmed failures roll back only changes managed by the current operation. Retire archives the exact Agent without deleting Skills, Issues, semantic storage, or evidence history. Deploy never creates a robot, webhook, schedule, or other Trigger. The `dingtalk-agent-deploy` Skill only guides these stable CLI calls; it does not write through Multica directly or retain credentials.
+
+W5 links designated W2 Eval evidence to a W4 Receipt as an explicit Promotion chain. A policy freezes source/target Workspaces, suite, minimum runs, required cases, and evidence surfaces. Dry-run recomputes the Definition/Skill, managed Workspace, plan/suite/report, and deployment hashes without Provider calls. Only the current planId plus explicit confirmation may delegate to W4 deploy. The resulting Promotion Receipt binds source, Eval, the historical deployment Receipt, and the final observed hash.
+
+```bash
+dta promote --policy promotion-policy.json --route local-dev-to-multica-dev --dry-run --json
+dta promote --policy promotion-policy.json --route local-dev-to-multica-dev \
+  --plan-id <plan-id> --yes --json
+dta promote --status --promotion-id <promotion-id> --json
+dta promote --list --json
+```
+
+`observe` accepts only redacted feedback whose `observedHash` exactly matches a promoted Receipt. It writes one gitignored Eval candidate fixed as `proposed`, review-required, suite-ineligible, and unpublished. It never changes AGENTS.md, prompts, Basic/Role Skills, or Triggers.
+
+```bash
+dta observe --promotion-id <promotion-id> --input observation.json --dry-run --json
+dta observe --promotion-id <promotion-id> --input observation.json --yes --json
+```
+
+See the reusable two-Provider fixture at [`lab/project-workspace/project.fixture.json`](lab/project-workspace/project.fixture.json), the redacted read-only fixture at [`multica-readonly.fixture.json`](lab/project-workspace/multica-readonly.fixture.json), the W4 stateful fake data at [`multica-deploy.fixture.json`](lab/project-workspace/multica-deploy.fixture.json), and the W5 [`promotion-policy.fixture.json`](lab/project-workspace/promotion-policy.fixture.json). Manifests and state reject credential-like fields; `*From` fields preserve only `env:VAR` sources, never resolved values. The current contract proves local orchestration and fail-closed behavior; it does not claim that a real Multica Live apply or promotion has passed.
+
+## Employee task protocol
+
+![Employee task loop and completion gate](docs/architecture/task-completion-gate.svg)
+
+```text
+UNDERSTAND → CLARIFY → PLAN → EXECUTE → WAIT → VERIFY → COMPLETE
+```
+
+`CLARIFY` is a conditional branch, not a mandatory opening question. The Agent first forms an internal task contract—goal, deliverable, scope, observable done conditions, authority, and timing—then asks one question only when a gap blocks safe progress.
+
+`COMPLETE` is evidence-gated rather than self-declared. A cross-Run task must move from `working` to `verifying`; every `doneWhen` condition must map to a file check, Workspace/Artifact assertion, Action Receipt, independent platform readback, or human confirmation. A reply that says “created” is not evidence. The CLI rejects `working → completed` and any completed checkpoint without verification evidence.
+
+## Identity and delegation
+
+The role identity and the sandbox execution identity are separate:
+
+- the role identity says who the employee is, what it owns, whom it serves, and who delegated the work;
+- the execution identity is the trusted DWS profile used for platform effects;
+- if they represent the same subject, it is the Agent's own identity;
+- if they differ, the Definition must make the delegation explicit and the Action Gate must keep the delegated scope narrow.
+
+Neither identity can be replaced by a display name, message body, or model memory.
+
+## The two-part gate
+
+The safety half prevents wrong actions: response eligibility, trusted identity and target, one egress owner, action budgets, idempotency, and readback.
+
+The empathy half supplies context a colleague naturally has: quoted messages, recent conversation burst, attachments, readable identity, status, and interruption context. Enrichment improves decisions but never expands authority.
+
+## Three semantic memory layers
+
+| Layer | Typical medium | Content |
+|---|---|---|
+| L1 task memory | Session checkpoint | Current goal, progress, next step, wait condition, evidence |
+| L2 operational memory | AI table, task, calendar, business system | Structured and aggregatable working facts |
+| L3 long-term knowledge | DingTalk docs, knowledge base, wiki | Reviewed methods, stable facts, SOPs, lessons |
+
+Control state is separate: event dedupe, leases, generation, idempotency keys, budgets, Wait, and Receipts require an atomic host store. Markdown, DingTalk documents, and Git are not transaction or lock services.
+
+## Real-world Lab
+
+Evaluation progresses through five levels:
+
+| Level | Environment | Evidence |
+|---|---|---|
+| L0 | fixtures + real CLI | Contracts, state machines, target integrity, idempotency |
+| L1 | model shadow | Skill loading and behavioral gain, without DingTalk effects |
+| L2 | fake DWS + real Action Gate | Intent/Attempt/Receipt, readback, recovery |
+| L3 | dedicated robot connector | Real connection, Workspace, expression, delivery, teardown |
+| L4 | test colleague/group + personal event + dta Broker | Full envelope, identity, target, Wait/Resume, single egress |
+
+Live runs require dedicated resources, allowlists, unique markers, fixed budgets, independent platform readback, and exact teardown. A robot response does not prove the personal-event envelope or dta-owned egress.
+
+The [`personal-event-eval@1`](lab/schemas/personal-event-eval.schema.json) suite binds Basic + Role Skills, response eligibility, Wait/Resume, duplicate delivery, Perception, Receipts, and teardown into one evidence chain. Event capture remains external; dta does not create a subscription or trigger. The default command is plan-only. Execution requires both `liveAuthorized=yes` in the local suite and all CLI confirmations:
+
+```bash
+dta lab eval --engine personal-event \
+  --workspace <agent-workspace> \
+  --suite .dingtalk-agent/personal-event-live.local.json --json
+
+dta lab eval --engine personal-event \
+  --workspace <agent-workspace> \
+  --suite .dingtalk-agent/personal-event-live.local.json \
+  --execute --live --yes --json
+```
+
+See the placeholder [`personal-event-live.example.json`](lab/agent-eval/personal-event-live.example.json) and the sanitized local [`personal-event-live-readiness-summary.json`](evals/baselines/2026-07-17/personal-event-live-readiness-summary.json). Each reply must independently read back the exact body under the same message ID; a duplicate must reuse the original Run, Action, and Attempt with no new egress. The fake-DWS contract passes 8/8 scenarios, seven physical Runs, and five new outward effects, while rejecting a readback with the correct ID but rewritten body. That proves runner readiness, not a real personal-event delivery.
+
+```bash
+# OpenCode plan only
+dta lab eval --engine opencode \
+  --workspace lab/robot-eval/workspace \
+  --suite lab/robot-eval/suite.json --lanes stateless --runs 3 --json
+
+# Fixed model, isolated Workspace, no DingTalk side effects
+dta lab eval --engine opencode \
+  --workspace lab/robot-eval/workspace \
+  --suite lab/robot-eval/suite.json --lanes stateless --runs 3 \
+  --execute --yes --json
+```
+
+## Evaluation as a reusable Skill
+
+The bundled [`dingtalk-agent-eval`](skills/dingtalk-agent-eval/SKILL.md) Skill defines the complete workflow: identify the Definition, prove Basic Skill loading, select a stable scenario, isolate execution, collect multiple evidence surfaces, apply hard gates, and only then score quality.
+
+Scenarios are grouped by the condition they can break, not by date or role:
+
+1. `host-loading`
+2. `conversation-contract`
+3. `authority-and-egress`
+4. `task-lifecycle`
+5. `memory-and-storage`
+6. `workspace-and-artifacts`
+7. `platform-reliability`
+
+The repository catalog is [`lab/agent-eval/catalog.json`](lab/agent-eval/catalog.json). A reply is only one evidence surface. Cases can also require filesystem paths and contents, a valid Agent Workspace, artifact manifests and hashes, Receipts, or independent DWS readback. A failed load, safety, or integrity gate cannot be averaged away by a high quality score.
+
+Run the classic incident suite or select individual cases:
+
+```bash
+dta lab eval --engine opencode \
+  --workspace lab/agent-eval/workspace \
+  --suite lab/agent-eval/classic-failures.json \
+  --cases requester-only-authorization,workspace-artifact \
+  --runs 1 --execute --yes --json
+```
+
+The 2026-07-16 OpenCode 1.17.14 + DeepSeek development regression covers nine classic cases. Basic 0.9.4 passed its load gate. Eight cases passed in the full run; the only correct refusal missed a phrase-only grader and passed a targeted rerun after the grader changed to a bounded regex plus independent reason and exclusion checks. The artifact case allowed only `read/write/edit` and actually used only `write`; it passed all seven Workspace/Artifact/Filesystem postconditions and copied two hashed outputs into the evidence bundle. Writable sandboxes live under a system temporary root outside the repository; the runner canonicalizes and audits every tool path so OpenCode cannot resolve a relative write against a parent Git checkout. This is combined 9/9 passing evidence, not a claim of one statistically significant run. See the [sanitized multi-surface summary](evals/baselines/2026-07-16/opencode-multi-surface-summary.json).
+
+The same local `AGENTS.md + Skills` can be evaluated with local semantic state or with `memory` and `knowledge` hydrated from `dingtalk-doc:`:
+
+```bash
+cp lab/agent-eval/remote-state.example.json \
+  .dingtalk-agent/remote-state.local.json
+
+# Plan only: no DWS read and no model call
+dta lab eval --engine storage \
+  --workspace lab/agent-eval/remote-state-workspace \
+  --suite .dingtalk-agent/remote-state.local.json --json
+
+# Read two dedicated documents and evaluate OpenCode; --live adds one unique write probe
+dta lab eval --engine storage \
+  --workspace lab/agent-eval/remote-state-workspace \
+  --suite .dingtalk-agent/remote-state.local.json \
+  --execute --live --yes --json
+```
+
+The 2026-07-16 live DWS canary used two dedicated `adoc` documents. The local Definition was ready, Basic 0.9.4 was forced through OpenCode instructions, both remote/mount/cache/manifest hashes matched, and DeepSeek returned two remote-only probe values with zero tools. One append marker was verified exactly once through a full-document readback. Deterministic contracts also reject a wrong DWS identity, a non-adoc node, and post-bootstrap drift. The first byte-level marker check produced a false negative because DingTalk escaped Markdown punctuation; the runner now counts the normalized text stream and never treats a command response as proof. See the [sanitized remote-state summary](evals/baselines/2026-07-16/remote-state-live-summary.json).
+
+Remote Markdown remains semantic state; private control state stays in the host's atomic store. The evaluator does not infer permission to delete its dedicated test documents.
+
+## Development and verification
+
+```bash
+npm ci
+npm run typecheck
+npm run eval:contract
+npm pack --dry-run
+```
+
+The 60-case deterministic suite also covers `agent-bindings@1`, plan-bound enhancement with backups and semantic-placeholder gates, precise partial-to-ready repairs, OpenCode load evidence bound to the current Definition and Host exposure, two-process L1/L2/L3 remote semantic-state recovery, a default-safe Phase 11B Live runner, the Phase 9 personal-event evidence chain, fail-closed identity/type/drift/slot/cache checks, replication of a second isolated Role Agent without kernel changes, multi-Provider Project/Workspace isolation, Workspace-bound OpenCode materialization/run/eval, Multica W3–W5 orchestration, isolated npm-tarball readiness, negation-aware completion claims, and predeclared comparison policies. A passing comparison policy is a deterministic release gate, not statistical significance or proof of a stable model gain.
+
+See [Self-test and evolution](docs/SELF-TEST.md), [Architecture](docs/ARCHITECTURE.md), and the [implementation plan](docs/plans/2026-07-16/eval-test-skill-and-remote-state.md).
+
+## Project layout
+
+```text
+bin/                              CLI composition root
+src/                              TypeScript runtime
+skills/dingtalk-basic-behavior/   shared employee behavior
+skills/dingtalk-agent-compose/    Agent assembly and optimization
+skills/dingtalk-agent-eval/       scenario, evidence, and promotion method
+examples/agents/                  reusable role kits
+lab/                              catalogs, manifests, schemas, and runbooks
+evals/                            deterministic and model evaluations
+docs/                             architecture and decisions
+```
+
+## Current boundaries
+
+- Event listeners and schedulers are outside the kernel.
+- Workspace initialization is optional and never automatic per session.
+- dta does not duplicate the DWS command surface.
+- DingTalk documents do not store locks, idempotency, generation, or effect receipts.
+- Online Runs cannot hot-expand identity, authority, or enabled Skills.
+- `bootstrap` hydrates `dingtalk-doc` as a read-only snapshot; remote publication requires explicit authorization and readback.
+
+## License
+
+[MIT](LICENSE)