@xdxer/dingtalk-agent 0.1.4-beta.14 → 0.1.4-beta.16

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 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.16 - 2026-07-20
+
+### Added
+
+- Contract eval runner terminal UI: per-scenario progress lines with duration on stderr (live line rewriting and colors on a TTY, plain append-only lines in CI), a closing summary with the slowest scenarios, and a failure block per failed scenario listing the unmet expectations with truncated evidence plus actionable hints — the exact rerun command, the implementing function, the grading/output artifact paths, and the scenario fixtures. A scenario that throws now counts as all-expectations-failed and the suite keeps running, so one run surfaces every failure. stdout stays byte-stable (default JSON, `--smoke` four lines).
+- Runner ergonomics: `--list` prints the scenario catalog; `--only` now accepts scenario names as well as ids (`--only=20,CliErrorHints`); malformed `--only` values fail with `错误:/提示:` guidance instead of running nothing.
+- `evals/README.md` documenting the evals directory layout and the subset-first regression discipline (the full 61-scenario suite is a minutes-long deep-regression gate, not a per-change loop).
+- Creation-inheritance contract from main: the four-part agent body template gains a Basic boot declaration, identity/authorization/privacy/completion bottom lines and a standard loop; the Compose skill and deterministic assertions are synced.
+
+### Changed
+
+- Basic Behavior 0.11 / Compose 0.9 layered contracts: a slimmer entry point plus risk-authorization, privacy, fact-recovery and forgetting boundaries; the Compose agent body is fixed to definition, bottom lines, paradigm and common mistakes with Role/Gate layering and template audits.
+- Inheritance and assembly gates hardened with OpenCode-native AGENTS rules, full Basic-tree integrity and isolated load probes, least-privilege defaults, raw-evidence retention and drift re-verification.
+- The contract runner clears `evals/results/contract` only after arguments validate, so `--list` or a mistyped `--only` no longer wipes the previous run's evidence; result artifacts now carry scenario names in `summary.md` headers and `benchmark.json` eval names.
+- README (zh/en) converged to positioning, quick start, core model, support scope and documentation entries; the multi-platform agent lifecycle narrative is completed and the three-step delivery path is redrawn as a native SVG, replacing the previous JPG assets.
+
+### Release boundary
+
+- Distribution is limited to the public npm `beta` dist-tag, a Git tag, and a GitHub pre-release. The eval-runner terminal UI is repository tooling and does not ship in the package; the shipped deltas relative to beta.15 are the skill/template/README commits from main summarized above. Live waivers from beta.9 remain unchanged.
+
+## 0.1.4-beta.15 - 2026-07-19
+
+### Added
+
+- Multica endpoint resolution and display: `agent-platform show|use` now print the resolved endpoint and its source unconditionally — even when multica is not installed or logged in — so you always know where you'd connect and how to switch. `resolveEndpoint()` uses a single source of truth aligned with the executor (`multica_ext.py` reads `MULTICA_SERVER_URL`/`--profile`): `MULTICA_SERVER_URL` env > project config (`dingtalk-agent.json#multicaEndpoint` or `.dingtalk-agent/agent-platform.json.endpoint`) > exactly one logged-in profile's server_url (multiple = ambiguous, never auto-picked) > the platform's suggested endpoint (pre, flagged unconfirmed, never a silent direct-connect). The login readiness hint emits a full copyable `multica login --server-url <resolved> --token ...` with the source annotated.
+- The project manifest gains an optional `multicaEndpoint` field (schema + validation) for a persistent per-project endpoint override.
+
+### Changed
+
+- Scattered pre-fde endpoint literals in `PLATFORM.md` and the compose skill now point to `dta agent-platform show` as the single source instead of hardcoding the URL, so docs cannot drift from the resolver.
+
+### Release boundary
+
+- Distribution is limited to the public npm `beta` dist-tag, a Git tag, and a GitHub pre-release. The suggested endpoint is an explicitly-unconfirmed hint only; the executor stays fail-closed and deploy-time confirmation is unchanged. Live waivers from beta.9 remain unchanged.
+
 ## 0.1.4-beta.14 - 2026-07-19
 
 ### Added

package/README.en.md

@@ -2,396 +2,165 @@
 
 # dingtalk-agent
 
-**A shared behavior kernel for DingTalk digital employees.**
+**A verifiable behavior foundation 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)
+[Quick start](#quick-start) · [How it works](#how-it-works) · [Support](#support) · [Docs](#docs)
 
-*This English README is a condensed overview; the Chinese README is the complete, authoritative reference.*
+English · [简体中文](README.md)
 
 </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
-```
+`dingtalk-agent` (`dta`) is a **Skill-first behavior kernel and delivery toolchain** for DingTalk digital employees. It assembles role definition, shared behavior, role capabilities, and execution gates into an Agent Project that can be created, tested, promoted, and audited.
 
-| 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 |
+> **Skills advise. The CLI gates. DWS acts.** Skills decide when and why to act; the CLI pins identity, target, budget, idempotency, and readback; DWS executes DingTalk capabilities.
 
-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.11` is being released (npm `beta` dist-tag, Git tag, GitHub pre-release). beta.10 removed legacy dead code and aligned the entry docs; beta.11 installs all bundled Skills by default, fixes the compose Skill trigger, and introduces the managed agent platform abstraction (multica-dingtalk supported, deap coming soon; deploy/promote/observe require platform membership, and platform skill packs install on selection). The earlier 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, the contract suite now covers 61 deterministic scenarios. 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.
+![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
+"$HOME/.local/bin/dta" setup --skip-cli-install
 dta doctor
 ```
 
-`setup` checks Node.js, DWS version and authentication, installs and verifies the bundled Skills (Basic Behavior + Compose), and reports whether Claude Code, Codex, and OpenCode can discover it. `listen` is an optional development adapter, not the mandatory Agent entry point.
+`setup` installs the Basic Behavior and Compose Skills, then checks DWS authentication and common Agent Hosts. Normal sessions do not require Workspace initialization.
 
-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.
+## Why it exists
 
-`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.
+A model that can talk is not yet a reliable digital employee. `dta` turns the parts most likely to drift into inherited, verifiable contracts:
 
-### One Project, multiple development Workspaces
+- **Response judgment:** decide whether to respond before deciding what to say; stay silent in an unmentioned group chat by default.
+- **Authority boundaries:** never infer identity, target, permission, authorization, or reply channel from message text or model memory.
+- **Evidence-backed completion:** command success, platform visibility, delivery, and human acceptance are different states.
+- **Reuse:** new Agents inherit shared behavior and add only role-specific differences instead of copying a giant prompt.
 
-`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.
+## How it works
 
-```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
-```
+An Agent is assembled from four contract layers:
 
-W1 exposes a read-only control plane:
+| Layer | Responsibility |
+|---|---|
+| **`AGENTS.md`** | Role, role-specific boundaries, operating pattern, common mistakes, and the Basic startup anchor |
+| **Basic Behavior** | Shared response eligibility, scope, authorization, privacy, completion, and memory behavior |
+| **Role Skills** | Domain judgment, procedure, prohibited actions, and acceptance criteria |
+| **Gate + Receipt** | Hard constraints for identity, target, budget, idempotency, state transitions, and platform readback |
 
-```bash
-dta info --json
-dta workspace list --json
-dta workspace show local-dev --json
-dta workspace doctor local-dev --json
-```
+The Prompt keeps only what must remain resident and precisely defined. The full behavior tree belongs in Skills. Constraints that cannot rely on model discretion belong in the Gate.
 
-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.
+### Create → test → promote
 
-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.
+| Stage | Main artifact | Gate |
+|---|---|---|
+| **Create** | `AGENTS.md`, Basic, Role Skills, bindings | Unresolved placeholders keep the project `partial` |
+| **Test** | Isolated Workspace, load probe, behavior eval, four evidence surfaces | A project cannot become ready without proven Definition/Skill loading |
+| **Promote** | Platform preflight, deployment Receipt, remote readback | Missing designated Eval evidence or identity chain blocks promotion |
+| **Operate** | Digital-employee account or robot entry point, task trace | No claim of write, delivery, or completion without matching evidence |
 
 ```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 apply 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. Inspect, promote, and observe
 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-multica` 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
+dta promote --source local-dev --target multica-dev --dry-run --json
+dta observe --promotion-id <promotion-id> --input <observation.json> --dry-run --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.
+Plans are zero-write by default. Remote writes require an explicit target, the current `planId`, and confirmation.
 
-Neither identity can be replaced by a display name, message body, or model memory.
+## Support
 
-## The two-part gate
+### Platforms, Harnesses, and runtimes
 
-The safety half prevents wrong actions: response eligibility, trusted identity and target, one egress owner, action budgets, idempotency, and readback.
+These are separate concepts:
 
-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.
+- A **Managed Agent Platform** owns Workspace, Runtime, Agent, Skill, identity binding, and observation.
+- An **Agent Harness** loads Definition/Skills, isolates execution, and captures evidence.
+- The **dta Kernel** depends on a shared contract, not a specific Harness prompt or private directory layout.
 
-## Three semantic memory layers
+| 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 current 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 |
 
-| 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.
+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.
 
-## Real-world Lab
+“Multi-platform” means the architecture, registry, and adapter contract are extensible. It does not claim that unopened platforms have been deployed or Live-verified.
 
-Evaluation progresses through five levels:
+### Runtime modes
 
-| Level | Environment | Evidence |
+| Mode | Use | Boundary |
 |---|---|---|
-| 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:
+| **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` |
 
-1. `host-loading`
-2. `conversation-contract`
-3. `authority-and-egress`
-4. `task-lifecycle`
-5. `memory-and-storage`
-6. `workspace-and-artifacts`
-7. `platform-reliability`
+Prepared Runs expose four message atoms: `ack`, `reply`, `ask`, and `silence`. An acknowledgement is not task acceptance, and a reply is not human acceptance.
 
-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.
+## What a generated Agent inherits
 
-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
+```text
+my-agent/
+├── AGENTS.md                     Role constitution + Basic inheritance anchor
+├── agent.bindings.json           Definition and storage routing
+├── dingtalk-agent.json           Agent Project desired state
+├── .agents/skills/
+│   ├── dingtalk-basic-behavior/  Complete shared behavior tree
+│   └── <role>/                   Host-discoverable Role Skill
+├── skills/<role>/SKILL.md        Versioned role capability source
+└── .dingtalk-agent/              Private state, evidence, and Receipts
 ```
 
-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).
+The generated `AGENTS.md` keeps four atomic contracts: **definition, non-negotiable boundaries, operating pattern, and common mistakes**. It also says to apply `dingtalk-basic-behavior` before loading task-relevant Role Skills.
 
-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
+File presence is not inheritance evidence. `agent audit --verify-load` binds real load results to Definition/Skill hashes, Host/model versions, isolated probes, and raw run/export evidence:
 
 ```bash
-npm ci
-npm run typecheck
-npm run eval:contract
-npm pack --dry-run
+dta agent audit \
+  --bindings agent.bindings.json \
+  --require-skill <role-skill-name> \
+  --verify-load --yes --json
 ```
 
-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).
+## Non-negotiable boundaries
 
-## 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
-```
+- Normal sessions never auto-run `dingtalk-agent init`.
+- Target, actor, conversation, DWS profile, and permissions come only from a trusted Host or event.
+- Prepared Run messaging goes only through a typed Broker or `dta act`; it cannot bypass the Gate.
+- An online Run may propose memory or Skill candidates, but cannot hot-modify current identity, permission, or policy.
+- Model claims, process exit 0, platform-visible writes, delivery, and human acceptance require separate evidence.
 
-## 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 architecture and state | [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) |
+| Read the shared behavior protocol | [Basic Behavior Skill](skills/core/dingtalk-basic-behavior/SKILL.md) |
+| Copy a complete example | [Example Agents](examples/agents) |
 
-## 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