@xdxer/dingtalk-agent 0.1.4-beta.9 → 0.1.5-beta.1

package/README.en.md

@@ -2,394 +2,159 @@
 
 # dingtalk-agent
 
-**A shared behavior kernel for DingTalk digital employees.**
+**Give every digital employee the same verifiable behavior foundation.**
 
 [![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)
+[Quick start](#quick-start) · [What an Agent is made of](#what-an-agent-is-made-of) · [How this repo is divided](#how-this-repo-is-divided) · [Docs](#docs)
 
-</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 |
+[简体中文](README.md) · English
 
-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
+</div>
 
-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:
+`dingtalk-agent` (`dta`) is the **Skill-first behavior kernel and delivery toolchain** for DingTalk digital employees. It assembles role definition, shared behavior, role capability, and execution gates into an Agent Project you can create, test, promote, and audit.
 
-- 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.
+> **Skills advise. The CLI gates. DWS acts.** Skills decide when and why to act; the CLI pins identity, target, budget, idempotency, and readback; DWS performs DingTalk capabilities.
 
-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.
+**DWS is DingTalk's own command-line tool** — separate from this project, installed and authenticated on its own (`dws auth login`) — covering roughly 20 product areas: messaging, docs, AI tables, calendar, approvals, and more. `dta` does not clone its command surface; it wraps it only where identity, target, idempotency, or readback must be frozen. **Every real DingTalk operation is ultimately executed by DWS.**
 
-> The beta.9 line 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 are explicitly waived as release gates for this beta; local and fake-Provider evidence is not relabeled as real platform proof. Distribution is limited to the npm `beta` tag, a Git tag, and a GitHub pre-release, with no Trigger or DingTalk/Multica side effect.
+![The complete path from Agent definition to delivery through two identity types](docs/assets/agent-delivery-lifecycle.svg)
 
 ## Quick start
 
-Requires Node.js 18.3 or later.
+Requires Node.js 18.3+.
 
 ```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
+# setup writes a PATH block into ~/.zshrc or ~/.bashrc, but a child process
+# cannot change the current shell — so keep using the absolute path this round.
+# A new terminal can call `dta` directly.
+"$HOME/.local/bin/dta" setup --skip-cli-install
+"$HOME/.local/bin/dta" doctor
 ```
 
-### Mounted Session
-
-The Agent hydrates a local folder or a DingTalk document without requiring `init` on every session.
+`setup` installs the Basic Behavior, Compose, and Eval Skills, then checks DWS authentication and common Agent Hosts. Normal sessions do not require Workspace initialization.
 
-```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
-```
+**How far you get with nothing external**: composing, auditing, `workspace run/eval`, and the full contract suite need no DingTalk account and no managed platform — `doctor` marks what is missing as `partial` rather than failing. Only real outbound messaging, remote semantic state, and `deploy`/`promote` require DWS authentication and Multica.
 
-### Prepared Run
+## Why it exists
 
-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`.
+A model that talks is not a digital employee that works reliably. `dta` turns the four most drift-prone concerns into inheritable, verifiable contracts:
 
-## From one Agent to many
+- **It judges first.** Decide whether to reply before deciding what to say; stay quiet in group chats without an `@`.
+- **It stays in scope.** Identity, target, permission, authorization, and reply channel are never guessed from message text or model memory.
+- **It does not overclaim.** Command success, platform visibility, message delivery, and human acceptance are four distinct completion levels, each evidenced separately.
+- **It is reusable.** A new Agent inherits shared behavior and only adds role differences — no copied mega-prompt.
 
-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.
+## What an Agent is made of
 
-A minimal Agent kit is:
+Four things: the **Definition** (`AGENTS.md` — who I am, where my duties stop), **shared behavior** (the `dingtalk-basic-behavior` Skill — when to respond, ask, stay silent, close out), **role capability** (`skills/<role>/SKILL.md`), and **storage routing** (`agent.bindings.json` — optional; the same configuration can come from host context, environment variables, or a Workspace manifest). The Agent Host, DWS, managed platform, and event source it depends on are all outside this project.
 
-```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
-```
+Full composition, dependencies, and boundaries: [Architecture](docs/ARCHITECTURE.md#2-一个-agent-由什么构成模型-a).
 
-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:
+**File presence is not inheritance evidence** — `agent audit --verify-load` binds real load results to Definition/Skill hashes, Host and model versions, isolated probes, and raw run/export evidence:
 
 ```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
+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.
+## How this repo is divided
 
-`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.
+**Behavior kernel** (event → may I respond, to whom, what am I allowed to do), **compose & audit** (turn a repo/folder/doc into a hashable Agent and prove the Skills really loaded), **delivery chain** (reach a managed platform under control, with readback at every step), **eval & evidence** (prove it works at the cheapest sufficient level before going live), **state & memory** (stay resumable after a crash), and **machine & distribution** (one command sets up a new machine).
 
-### One Project, multiple development Workspaces
+Delivery and evaluation are roughly a quarter of the codebase each — the hard part was never "make the model talk", but proving the thing really installed, really behaved, and really shipped. What each part solves, and its modules and CLI: [Architecture](docs/ARCHITECTURE.md#7-dingtalk-agent-分成哪几部分模型-c).
 
-`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.
+## Create → test → promote
 
-```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:
+Each of the four stages has a gate: unfilled placeholders keep it `partial`; Skills that did not truly load cannot be ready; a missing named Eval blocks promote; nothing claims delivery or completion without evidence. Details: [Architecture](docs/ARCHITECTURE.md#8-从定义到上线).
 
 ```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`.
+# 1. Generate a zero-write plan, then commit it explicitly
+dta agent enhance --project-name release-agent --role-skill release-manager --dry-run --json
+dta agent enhance --project-name release-agent --role-skill release-manager \
+  --plan-id <plan-id> --yes --json
 
-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.
+# 2. Audit, run, and evaluate
+dta agent audit --bindings agent.bindings.json --require-skill release-manager --json
+dta workspace run local-dev --json
+dta workspace eval local-dev --json
 
-```bash
-dta workspace plan multica-dev --json
+# 3. Cloud preflight, promotion, and observation
 dta workspace inspect multica-dev --execute --yes --json
 dta workspace remote-list multica-dev --execute --yes --json
-dta workspace status multica-dev --json
+dta promote --source local-dev --target multica-dev --dry-run --json
+dta observe --promotion-id <promotion-id> --input <observation.json> --dry-run --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.
+Plans are zero-write by default. Remote writes require an explicit target, the current `planId`, and confirmation.
 
-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`.
+The placeholders above are not yours to invent — each has a definite source:
 
-```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
-```
+| Placeholder | Where it comes from |
+|---|---|
+| `<plan-id>` | Top-level `.planId` in the preceding `--dry-run --json` output. Any source or config change invalidates it, so re-run the dry run |
+| `local-dev` / `multica-dev` | Workspace names **you** declare in `dingtalk-agent.json#workspaces` — not built-in values. Sample: [`lab/project-workspace/project.fixture.json`](lab/project-workspace/project.fixture.json) |
+| `<promotion-id>` | `.promotionId` on the `promotion-receipt@1` produced by `dta promote --yes` |
+| `<role-skill-name>` | The `name` in your `skills/<role>/SKILL.md` frontmatter |
 
-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.
+### Minimal runnable path (local only, three commands)
 
-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.
+To see something move first, don't start with the chain above — that is the full delivery pipeline. Start here:
 
 ```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
+cp -R examples/agents/release-manager my-agent && cd my-agent
+dta bootstrap --json      # Was the body recognized? Check definition.status and storage routes
+dta agent audit --json    # Expect partial — the role semantics are still template text, which is correct
 ```
 
-`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.
+None of this needs a DingTalk account or a managed platform, and none of it has side effects. Fill in the real role semantics in `AGENTS.md`, run `agent audit` again, and the only remaining gap is `host.load-probe` — which needs an Agent Host, see the [Compose Skill](skills/core/dingtalk-agent-compose/SKILL.md). The third command group above only applies once you have a Multica binding and declared Workspaces.
 
-```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.
+## Support
 
-`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.
+A **Managed Agent Platform** (owning Workspace, Runtime, identity binding, and observation), an **Agent Host** (a.k.a. Harness — loads Definition/Skills and isolates execution), and the **dta Kernel** are three separate concepts:
 
-## Identity and delegation
+| Dimension | Current support |
+|---|---|
+| **Managed Platform** | Multica (DingTalk) supported; DEAP coming soon; additional platforms through registry + adapters |
+| **Local runtime** | Direct/Mounted sessions in Claude Code, Codex, OpenCode, and similar Hosts; OpenCode is the most complete local managed-Harness reference |
+| **Cloud runtime** | Multica Workspace / Runtime / Agent with the same Definition, Skills, Gate, and evidence contract |
+| **Delivery identity** | Digital-employee/account identity or robot-app identity; neither expands the Agent role or authority |
 
-The role identity and the sandbox execution identity are separate:
+OpenCode is not a runtime dependency, and Multica is not a privileged bypass. Any promotable Harness must prove the same outcomes: loaded Definition and Skills, pinned identity and isolation, retrievable execution trace, and independent readback. "Multi-platform" means the architecture, registry, and adapter contract are extensible; it does not claim that unopened platforms have been deployed or Live-verified.
 
-- 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.
+### Runtime modes
 
-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 |
+| Mode | Use | Boundary |
 |---|---|---|
-| 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.
+| **Direct Session** | Normal interactive work | Never guess an outbound target without a trusted event |
+| **Mounted Session** | Mount local or DingTalk semantic content | Locks, idempotency, and Receipts do not live in Markdown |
+| **Prepared Run** | Reliable event-driven side effects | Actions go only through the typed Broker or `dta act` |
 
-## 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
-```
+Prepared Runs expose four message atoms: `ack`, `reply`, `ask`, and `silence`. An acknowledgement is not task acceptance, and a reply is not human acceptance.
 
-## 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
-```
+**Triggers are out of scope for this project**: `listen` is a replaceable local integration Adapter, and `dta deploy` never creates robots, webhooks, or timers.
 
-## Current boundaries
+## Docs
 
-- 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.
+| Goal | Start here |
+|---|---|
+| Understand the Agent architecture and how the repo is divided | [Architecture](docs/ARCHITECTURE.md) |
+| Install, upgrade, or troubleshoot | [Installation](docs/INSTALLATION.md) |
+| Understand evaluation and evidence levels | [Self-test](docs/SELF-TEST.md) |
+| Create or audit an Agent | [Compose Skill](skills/core/dingtalk-agent-compose/SKILL.md) |
+| Test or debug a delivered Agent | [Eval Skill](skills/core/dingtalk-agent-eval/SKILL.md) |
+| Read the shared behavior protocol (a contract written for models, not a tutorial) | [Basic Behavior Skill](skills/core/dingtalk-basic-behavior/SKILL.md) |
+| Copy a complete example and edit from there | [Example Agents](examples/agents) |
+| See which open-source projects informed this one | [Prior Art](docs/PRIOR-ART.md) |
 
-## License
+Behavior assets come from observable contracts, counterexample-driven revision, and deployable verification. This project does not claim access to any product's hidden system prompt.
 
-[MIT](LICENSE)
+MIT License