@xdxer/dingtalk-agent 0.1.5-beta.1 → 0.1.5-beta.11

package/CHANGELOG.md

@@ -2,6 +2,215 @@
 
 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.5-beta.11 - 2026-07-25
+
+A one-fix release, and the fix is a boundary that was being checked with the wrong instrument: string comparison cannot prove that a directory belongs to the host. The state-directory contract now has exactly one owner, and both the receipt store and the candidate store read it instead of keeping private copies. Ships on the `beta` dist-tag; `latest` stays at 0.1.4. Merged as PR #54.
+
+### Fixed
+
+- **A symlink inside the agent root let prepared no-op receipts be written outside it (closes #52).** #47 correctly widened the prepared write boundary from the literal `.dingtalk-agent` to "anywhere in the agent root", but it compared `resolve()` strings only. A directory symlink inside the root pointing outside it therefore passed containment, and `mkdirSync`/the atomic write then followed that link: `recordMemoryNoop(root, claim, {stateDir: '.state-link'})` returned a lexical path under the root while `realpath` landed in a directory the host does not own — which is exactly the deployment fact #42 rests authenticity on ("the state directory is host-owned"), so a lexical check can prove neither ownership nor containment. The stateDir contract now has a single owner (`src/state-dir.ts`): lexical containment, stateDir may not equal the root (the bindings "separate private directory" rule), and the realpath of the existing prefix — plus a re-check after the directory is created, covering nested segments and swap races — must stay inside the agent root; a dangling symlink fails closed instead of surfacing as `ENOENT`. `loadAgentBindings` and the prepared candidate store read that same contract instead of keeping private copies (candidate writes were escapable the same way). Legitimate `.agent-private` setups keep issuing and tracing; `../outside-root`, a root-internal symlink to the outside (as stateDir or as its nested `memory/`), and `stateDir='.'` are all refused, and scenario #75 asserts the outside directories stay receipt-free.
+
+## 0.1.5-beta.10 - 2026-07-25
+
+The registry-and-receipts wave: every "the declaration says X" now has a reader on the other side that can prove or refute it. Completion predicates became referenced registry entries with a readback-verified marker; the memory save-decision leaves a typed, forgery-hardened trace; and three review rounds on this very wave (#35/#38/#39, #42, #45/#46/#47) were folded back in before shipping. Ships on the `beta` dist-tag; `latest` stays at 0.1.4. Merged as PRs #34, #36, #37, #41, #43, #44, #48, #49.
+
+### Added
+
+- **predicateRef readback contract (advances #40).** The `[dta-completion-predicate] <id>` marker emitted into autopilot descriptions was written by `dta schedule plan` and then trusted blindly — no consumer parsed it back, so a platform that dropped or rewrote the description would leave declaration and runtime silently disagreeing, which is the exact failure the registry exists to prevent. The marker now has exactly one parser definition, mirrored across languages (`parseCompletionPredicateMarker` in `src/schedule-plan.ts`, `parse_predicate_marker` in `multica_ext.py`; conflicting markers are a loud `conflict`, never a pick-one). `autopilot-create` performs an independent GET readback after create and compares markers — the create response may merely echo the request, so only the readback counts; missing/rewritten marker exits non-zero with `predicateRef: {declared, remote, verified:false, reason}` instead of reporting the deploy as done. `autopilot-list`/`autopilot-get` annotate parsed `predicateRef` for reconcile. New local `predicate-resolve --manifest dingtalk-agent.json (--id | --description)` resolves a predicate from the same manifest the declaration lives in (no platform credentials needed; unregistered id / conflicting markers exit non-zero) — an operator-side tool for now: runtime reachability (manifest and resolver delivered into the target runtime, invoked per schedule run) is NOT wired and is tracked as a repo-side blocker in #46, distinct from the platform gap. Scenario #70's fake server models the echo-vs-store split and pins drop/mangle/resolve negatives plus TS/Python parser agreement. The remaining half of #40 — per-run host receipts freezing the predicateRef — needs platform capability that does not exist: ledgered as MUL-011 with fixed-upstream criteria (ops skill 0.4.0, compose 0.16.2).
+
+### Fixed
+
+- **Marker validation ran after the non-idempotent create, and malformed markers skipped verification entirely (closes #45).** `autopilot-create` POSTed first and judged the declared marker afterwards, so a locally-detectable conflict still left an orphan autopilot on the platform; and a marker line whose id was empty or ill-formed (`[dta-completion-predicate] Bad_ID`) parsed as "no marker", silently skipping the entire readback verification — the same fail-open shape as #39. The parser (both mirrors) now has a `malformed` state (a marker-intent line with an invalid id never degrades to `none`), `autopilot-create` validates the declared description before any API call and refuses conflict/malformed with zero writes, the readback reason vocabulary gains `remote-marker-malformed`, and `predicate-resolve`'s `--id`/`--description` are mutually exclusive (two sources of truth in one invocation is the exact fork the registry exists to kill). Scenario #70 asserts the POST counter stays flat across refused creates, malformed exits non-zero, and the dual-source resolve is rejected.
+- **Docs claimed the manifest travels with `skill-push`; it does not (advances #46).** The #40 delivery stated the project manifest reaches the runtime workspace with the skill payload — wrong: `skill-push` uploads only the skill directory, the target runtime is not guaranteed to carry `multica_ext.py`, and nothing invokes the resolver per schedule run. The ops and compose docs now state plainly that `predicate-resolve` is an operator-side tool against the local checkout and that runtime reachability is an open repo-side blocker (#46) — separate from the platform-capability gap MUL-011 (ops skill 0.4.1, compose 0.16.3).
+- **Prepared no-op receipts rejected legitimate custom private state directories (closes #47).** The prepared-mode write root was hardcoded to the literal `.dingtalk-agent`, but the bindings/enhance contract explicitly allows an agent to keep its host-managed private state elsewhere in the agent root (e.g. `.agent-private`) — with such a configuration the receipt could not be issued at all and operators saw `no-trace`, misreading "incompatible configuration" as "the step never ran". The boundary is now what it always meant: the state dir must live inside the agent root (escapes still refuse); scenario #75 pins the custom-stateDir prepared path end-to-end plus the escape rejection.
+- **No-op receipts could be forged through both "trusted" entrances (closes #42).** The receipt hash is a keyless integrity digest, not a host signature — any caller who can write the state directory can recompute it — yet `readReceipt` accepted a hand-written file missing `$schema`/`id`/`issuer` as long as its hash was self-consistent (making `trace` answer `ran-empty` for a step that never ran), and `DTA_RUN` pointed at any project-relative directory with a three-field `run.json` was accepted as a "trusted Prepared Run". Reading is now a strict structural contract: exact field set, schema constant, enum/grammar checks, issuer-mode invariants (`prepared` requires `runId` matching the `run:<runId>` occurrence; `direct` requires empty issuer fields), integrity hash, and the receipt id re-derived from `(step, scopeId, occurrence)` and required to match the filename — any violation fails loudly and never counts toward `ran-empty`. The prepared issuer resolves only through the canonical Session tree (`DTA_SESSION` under the configured session root, run under that session's `runs/`, `run.sessionId`/`contextId` cross-checked), mirroring the task-checkpoint discipline. Docs stop calling the digest a signature and state the actual trust boundary: authenticity rests on the state directory being host-owned. Scenario #75 gains the four adversarial negatives (forged partial file, id/filename mismatch, out-of-tree `DTA_RUN`, run↔session identity drift); basic-behavior 0.14.1.
+- **Predicate gate fail-open edges (closes #39) and its human interface (closes #38).** Two malformed inputs slipped past the new completion-predicate gate as "legacy free text": an explicit empty registry (`"predicates": {}`) was collapsed into "no registry declared", and `predicate:` with an empty/invalid id lost its prefix and was judged as free text — both exited 0 and produced apply commands without the predicate marker. Declaring a registry — including an explicitly empty one — now means the project is in reference mode (free-text `completion` blocks), and completion parsing is three-state (free text / valid `predicate:<id>` / malformed reference): any `predicate:` prefix whose id is empty or ill-formed blocks outright instead of degrading. The human interface now fails as closed as the exit code: `schedule show` renders `completionRefIssues` and derives its green summary line from the same `scheduleBlockers` source as the exit code (a new blocker class can never again print green over exit 2), and a blocked `schedule plan` hides the copy-pasteable `autopilot-create` commands and the "执行" guidance entirely. Scenario #74 gains both fail-open negatives plus CLI-level assertions (exit 2, no green line, no executable command).
+- **Expected-negative probes no longer pollute stderr with top-level `[FAIL]` (closes #35).** `dws.die()` printed `[FAIL]` unconditionally before throwing, so a passing eval scenario that intentionally exercises failure paths (#73 prints five of them) showed failure banners on stderr — exactly the surface CI log greps and release gates read. `die` now only throws; diagnosis belongs to the final consumer (the CLI top-level catch prints `错误: <msg>`, an uncaught throw still crashes loudly with the message). #73 asserts that a caught negative probe keeps its full error text while writing nothing to stderr.
+
+### Added
+
+- **Typed no-op / nothing-to-save receipts (closes #25).** `dta-basic-behavior` demanded that a save-decision which found nothing worth keeping still leave a trace, but never defined where it goes, what it looks like or how to read it back — so agents invented ad-hoc logs and operators still could not tell "ran and judged empty" from "never ran". The host now issues a signed, typed receipt (`src/memory/noop-receipt.ts`, `memory-noop-receipt@1`) under `.dingtalk-agent/memory/noop-receipts/`. Identity is `(step, scopeId, occurrence)`: a Prepared Run's occurrence is derived from trusted run state (`run:<runId>` — an anchor claimed in the body is not accepted), Direct mode must name an explicit event anchor or is refused. Replays are idempotent against the existing receipt; a conflicting claim for the same occurrence fails loudly instead of silently overwriting. The redaction line holds structurally: `reason` is an enum, free-text fields are rejected at validation, and the considered content may only enter as a sha256 digest. New CLI surface `dta memory noop record|list|trace`; `trace --scope --occurrence` answers the operational question directly — `ran-empty` (receipt found) vs `no-trace` (exit code 3). Contract scenario #75 (core tier) pins issuance, idempotency, conflict, validation refusals and both trace verdicts; the basic-behavior reference now points at the typed contract instead of "invent a log" (0.14.0).
+- **Completion-predicate registry (closes #24).** A free-text `completion` predicate is a sentence the runtime model can be talked out of ("already ran today"), and the declared copy and the runtime copy (autopilot description) were hand-maintained twins that silently forked — a real incident ran 30 hours on diverged predicates with no alarm. The manifest gains a top-level `predicates` registry (kebab-case id → `{description` required`, source}`), `completion` references it as `predicate:<id>`, and both sides now carry the *same id*: the schedule plan entry exposes `completionPredicate` and the generated autopilot apply command appends a `[dta-completion-predicate] <id>` marker to the description, so the platform-side readback can be matched against the declaration. Gating is progressive: a reference to an unregistered id blocks; once a registry is declared, free-text `completion` blocks too (all-in); legacy projects without a registry keep working and get a `unregisteredCompletion` migration nudge instead of a wall. The registry lives in the manifest JSON itself, so the Python engine (`multica_ext.py`) reads the same file and the same ids — no second predicate source. Contract scenario #74 (core tier) pins all four states plus registry validation (bad id / empty description / unknown key throw at manifest load). Compose skill's drive-and-schedules reference documents the registry and the cross-language contract (0.16.0).
+- **Read-completeness seal for AI-table reads (closes #23).** Completeness can no longer be inferred from a response body — the platform emits page-aligned truncated prefixes that still claim `hasMore:false`, and `records:null` is a version-dependent truncation/soft-timeout signal. `recordsRead` makes completeness a typed state decided by *how* the read was performed: enumeration is always `unproven` (`hasMore:false` is not evidence), `proven` has exactly two sources — recordId-bounded reads and `proveByCountLedger` cross-checks against an independent ledger (mismatch dies; `records:null` may not participate) — and `records:null` folds to `unproven('records-null')` instead of `[]`, never to "the table is empty". `queryAiTableRecords` now returns `{records, completeness}`; operational-memory key/scope lookups stop loudly on `window-full` and `records-null` instead of treating an unread table as an absent record (which would have minted duplicates). Contract scenario #73 (core tier) pins the matrix, including the indistinguishability of a complete read and a page-aligned truncation.
+
+## 0.1.5-beta.9 - 2026-07-25
+
+Fixes for the blockers recorded across three real acceptance sessions (2026-07-23/24, the `~/xdx/blockers` corpus). The common shape: fail-closed held the line, but the judge read the wrong evidence, the error named the wrong cause, or the locked state had no clean way out. Ships on the `beta` dist-tag; `latest` stays at 0.1.4. Merged as PRs #21, #27, #29, #30, #31, #32.
+
+### Fixed
+
+- **The load-smoke judge could structurally never reach `ready` on a cloud runtime.** It hardcoded the tool names `skill`/`write`/`bash` and required *every* tool_use to match a whitelist, while Multica cloud runtimes surface skill loads as `read_file` ("Loading skill '<name>'") and commands as `terminal` — a smoke that actually succeeded on the platform (all skills loaded, exact JSON posted) was judged `failed` with `loadedSkills: []`. Trace reading now goes through per-runtime-provider vocabularies (`src/multica-runtime-vocabulary.ts`), skill loads are proven by positive evidence (the host-generated `**Skill loaded**` tool_result, or the vocabulary's skill tool_use — model text never counts), and the response is taken from the Issue's own comments first, which no tool rename can break. The `.every(whitelist)` negative gate is gone: one extra harmless tool no longer kills a healthy trace (that had already caused two production false negatives); only dws — as a tool name or shelled out in a command — stays fatal, with a named `smoke.forbidden-tool:dws` failure. Unknown tool names are recorded in `smoke.unrecognizedTools` instead of judged.
+- **Cold-sandbox deploys systematically failed their first smoke.** Pushed skills take minutes to materialize into a runtime sandbox, and deploy fired the smoke immediately, reporting `Skill not found` with no way to tell "not ready yet" from "really broken" — the exact wrong signal that sent one acceptance session off rewriting the agent and swapping templates. A terminal smoke whose trace shows skill-not-found wording is now classified `skills-not-visible`: the receipt converges to `verifying` (not `failed`), apply retries with a bounded, budgeted mention inside the smoke window, and `deploy --status --execute --yes` performs one controlled retry — honestly reported as `remoteWrite: true` / `sideEffect: multica-read-write`.
+- **Switching runtimes deadlocked deploy and retire together.** `scope.agent-binding-mismatch` blocked apply *and* the retire that would have resolved it; the only way out was editing the env back to the old runtime id by hand. Runtime drift is now an inspection diff (`agent.runtime-drift`), not a hard failure: plain apply is still refused (no silent agent migration), `--retire` proceeds (archiving is convergence, not a write to protect), and the new `deploy --rebind-runtime` migrates explicitly — plan-gated, with `previousRuntimeId` baked into the planId and `rebind: {from,to}` on the receipt.
+- **`MULTICA_AGENT_ID` in the environment made every dta call report "Not authenticated. Run 'multica login'".** The multica CLI treats that variable as an agent-identity switch; dta passed the whole process env through, so a manifest envRef with that natural-looking name deadlocked second deploys behind a message pointing at login (one session lost 20+ minutes to it). dta now strips the reserved variable from every provider subprocess (values still resolve from the raw env first), records the removal in `envSanitized`, and `workspace doctor` warns when a manifest ref collides with a reserved name. The fixture example is renamed off the reserved name.
+- **Deploying onto a hermes runtime "succeeded" and then every skill load failed with zero warning.** dta never checked the runtime's provider kind, and the server default for new FC runtimes is hermes — where workspace skills are never visible. Inspection now fails closed (`scope.runtime-provider-unsupported`, expected/actual in the detail) before any remote write when the target runtime's provider has no registered trace vocabulary.
+- **Failures named the enum and hid the facts.** `scope.profile-workspace-mismatch` didn't say which workspace the profile pointed at; provider CLI stderr was hashed and discarded, so "calls all passed yet not authenticated" was undiagnosable without reading source. Scope/auth/binding failures now carry structured `failureDetails` (`code`/`expected`/`actual`/`hint` — IDs and enums only, the redaction contract is untouched), renderers print them, and a failing provider call's stderr is streamed to dta's own stderr in the moment while evidence files keep storing only hashes. Plan-invalidation errors explain the actual rule: don't run `inspect` between dry-run and apply.
+- **`deploy --status` without `--execute` looked like the smoke fields were all null.** It returns the receipt frozen at apply time — for a `verifying` deploy that's the pending snapshot. The report now says so (`receiptFrozen`, `smokeStale`) and hands over the exact refresh command in `nextAction`; the human renderer prints the smoke block and the hint instead of leaving the fields to be misread as a broken readback.
+
+### Added
+
+- Contract coverage for all of the above in #53/#54: cloud-vocabulary smoke with noise commands, hermes fail-closed, reserved-env sanitization on both the inspect and deploy write paths (the fake multica replicates the Go CLI's identity-switch semantics), skills-not-visible retry/convergence/recovery, frozen-status fields, rebind end-to-end (including stale-plan smuggling refusal) and retire-under-drift. The fake provider gained deterministic increasing run timestamps, an issue-comment store with `issue comment list`, cloud and cloud-spoof trace vocabulary modes, a bounded skill-not-found mode, and an async-run-creation mode (`DTA_FAKE_MULTICA_RUN_DELAY_READS`).
+- **ops skill (`dta-ops-multica` 0.3.0, BREAKING)**: `runtime-create-fc` now injects `--provider opencode` by default — the server default is hermes, where workspace skills structurally never load; template auto-pick filters `waiting` and, with several ready candidates, fails closed listing them by `created_at`. `agent-check` **removes the single `healthy` boolean** (it reported green while users could not reach the agent at all) in favor of `infrastructureHealthy` + `userReady` with `reasons[]`, a single `nextAction`, and a `userReadyCaveat` naming the upstream blind spot (installations don't read back effective `allow_unbound`). `dingtalk-account-begin`/`-unbind` carry the server-enforced `binding_mode` (body vs query — the asymmetric wire contract is pinned in comments); `dingtalk-bind` without `--allow-unbound` now says on stderr that unbound senders (the owner included) will only get a binding prompt. PLATFORM.md's false claim that `autopilot-create` stdout carries a non-JSON prefix is corrected (it is pure JSON; the real hazard — non-idempotent create — stays). `multica_ext.py` gains its first automated regression: a fake HTTP server that records every request (#70).
+- **scaffold / schedule**: `workspace create` now atomically creates the declared artifacts directory (with `.gitkeep`), so a fresh project's first `workspace doctor` passes instead of failing on the scaffold's own omission; output states explicitly that only the local manifest was written — no remote Multica resources. Schedule planning shares deploy's exact agent-binding fallback (`multicaAgentIdSource`): a declared `agentIdFrom` env ref wins, otherwise the agent ID saved to workspace state by the first deploy is used verbatim — the golden path no longer demands hand-wiring (#71 pins deploy/schedule consistency). First agent creation prints how the ID will be reused; `agent.unbound-name-candidates` renders the candidate IDs it always had in JSON.
+- **gates**: `agent audit --verify-load` failures now carry a `failureSummary` (probe exitCode/durationMs/answer-match per failing surface) surfaced into the check summary and human output, and probe-execution-class failures get one fresh-session re-confirmation — recorded in `verification.attempts` with `passedOnAttempt`, so a flaky pass is visible instead of unexplainable (`--strict-single-run` opts out; static failures never retry). `check-skill-versions` closes the `git mv` blind spot: rename detection re-attaches the new directory to its old baseline (pure renames require a bump too — the directory name is the flat-namespace interface), with a frontmatter-name fallback for low-similarity rewrites (#72).
+- **docs**: `docs/UPSTREAM-REQUIREMENTS.md` — the ledger of the 14 gaps this repo cannot fix (MUL-001..009 / DWS-001..005) with per-item evidence grades, workarounds and fixed-upstream criteria; the compose skill's drive-and-schedules reference gains the capability-vs-delivery-policy boundary (delivery targets and recipients live in the schedule wake prompt, never in `SKILL.md`).
+
+An adversarial review pass on the first cut of this change confirmed and fixed six defects before release: load *attempts* counted as load *evidence* (a failed cold-sandbox load emits the same "Loading skill" tool_use as a successful one — attempts now only feed race classification, and the `**Skill loaded**` banner is only trusted from skill-capable tools' results, so a `terminal` echo cannot forge it); the mention retry loop judged the stale terminal run and could fire duplicate mentions (a new run now counts as arrived only when the latest taskId changes, and the loop stops rather than re-mentions when none appears); a transient failure of the retry *or* first-enqueue-recovery comment escalated into a full rollback of an already-verified deployment (both now just end the attempt and leave the receipt at `verifying`); the dws command scan missed `/usr/bin/dws`, quoted and backticked forms (now tokenized with basename matching, and the tool-name denylist is case-insensitive and segment-based so `mcp__dws__send` counts); and the reserved-env strip list gains `MULTICA_SERVER_URL` and `MULTICA_TOKEN` — a stray pre-prod URL or token in the shell must never retarget a named-profile deploy.
+
+## 0.1.5-beta.8 - 2026-07-23
+
+Follow-up to the beta.7 rename, from watching a real machine take the upgrade: the four core skills migrated cleanly, the two platform skills sat untouched and unannounced. The three defects below are the same shape — "clean up" was not carried through to the end. Ships on the `beta` dist-tag; `latest` stays at 0.1.4.
+
+### Fixed
+
+- Renamed platform skills were stranded, not migrated. `skill install` / `upgrade` only install `BUNDLED_SKILL_NAMES` (the four core skills), so the "replacement must exist before deleting the old copy" gate correctly declined to touch `dingtalk-agent-deploy-multica` and `multica-external` — but nothing ever installed their replacements either, leaving those machines permanently on pre-rename copies with no notice. Stale-copy handling is now a real migration: a legacy skill that is present but whose replacement is not installed gets the replacement installed first, then the old copy removed. This only ever acts on skills the machine already had, so it preserves existing capability rather than adding anything.
+- Dangling exposure symlinks survived cleanup. `~/.agents/skills/<name>` is deleted before `~/.claude/skills/<name>`, which leaves the latter pointing at nothing — and `rmSync` stats the *target*, so `force: true` swallowed the resulting `ENOENT` as "already gone" and left the link in place. The skill therefore stayed visible to Claude Code and was re-reported on every pass. Symlinks are now removed with `unlinkSync`.
+- `dingtalk-agent-boot-multica`, removed from the package back in 0.1.5-beta.2, was still installed on machines and still exposed to Hosts through its `~/.claude/skills` symlink. Withdrawn skills now have their own removal list; unlike a rename they have no replacement to gate on, so they are simply deleted.
+
+### Migration
+
+`dta upgrade` once more. A machine that took beta.7 has its platform skills carried to the new names on the next `skill install` / `upgrade`, and every removed copy is printed by name — the operation is never silent.
+
+## 0.1.5-beta.7 - 2026-07-23
+
+**BREAKING.** All six first-party skills move to a `dta-` prefix. The names were previously drawn from three unrelated grammars (`dingtalk-*`, `dingtalk-agent-*`, and a bare `multica-external` with no first-party signal at all), and they all land in `~/.agents/skills/<name>/` — a flat namespace shared with Claude Code, Codex, and OpenCode that this repository does not own. The prefix puts the package owner in the first segment. Ships on the `beta` dist-tag; `latest` stays at 0.1.4.
+
+### Changed
+
+- Renamed, with directories, frontmatter `name`, the platform registry, and `package.json#files` all moved together: `dingtalk-basic-behavior` → `dta-basic-behavior`, `dingtalk-agent-compose` → `dta-agent-compose`, `dingtalk-agent-eval` → `dta-agent-eval`, `dingtalk-people-group-memory` → `dta-people-group-memory`, `dingtalk-agent-deploy-multica` → `dta-deploy-multica`, `multica-external` → `dta-ops-multica`.
+- Two naming grammars are now stated and enforced: core skills are `dta-<domain>`, platform skills are `dta-<role>-<platform>` where `<role>` equals the role in the `src/agent-platform.ts` registry. The old `ops` role carried the name `multica-external`, so the filesystem and the registry disagreed about what that skill was; they no longer can.
+- `skill install` / `skill upgrade` (and therefore `setup`) delete the pre-rename copies from `~/.agents/skills` and `~/.claude/skills` after the new names are in place. A renamed skill is not a second skill — leaving both installed means two nearly identical descriptions are visible to every Host at once, and which one triggers is undefined. Removal is limited to names registered in `LEGACY_SKILL_RENAMES` and to this package's own two install locations; current-name copies and third-party skills are untouched, and repeating the operation is a no-op.
+- An Agent Project manifest that still declares the old Basic name in `agent.skills` is accepted and counts as declaring Basic, but the name is **not** normalized: path resolution keeps following the declared name, because the directory checked into the user's repository still carries it. This is the one place `dta` cannot migrate on the user's behalf.
+
+### Added
+
+- `check:docs` gains a fourth finding kind, `legacy-skill-name`: any pre-rename name appearing anywhere in the repository fails the check. The allowlist is explicit and short — historical evidence that must not be rewritten (`CHANGELOG.md`, `evals/baselines/`, the dated `docs/roadmap/` studies) plus the migration machinery that has to spell the old names out loud. A one-time sweep cleans the present; only a standing gate keeps it clean.
+- Contract scenarios #67–#69 cover the pruning of stale copies, manifest tolerance for the old Basic name, and self-consistency of the naming grammar (prefix, directory basename = frontmatter `name` = registry name, platform role/suffix shape, complete rename ledger, and `package.json#files` coverage). All three run in-process and add no measurable time to the core suite.
+
+### Fixed
+
+- `dta doctor` output is re-laid out (PR #20). Three concrete defects, not cosmetics: the `⚠️` summary and its `detail` printed the same platform-skill drift twice; `detail` joined four canonical paths and the drift string with ` | ` into a 200+ character line that always wrapped; and three separator styles (`·`, `;`, `|`) coexisted with no column aligned. The cause was that the renderer only ever received pre-joined sentences, so `DoctorCheck` now carries structured `value` / `items` fields (additive — existing `--json` assertions are untouched) and the printer lays out one fact per line with indented details, aligned by `displayWidth`. The three client checks and the `hosts` section are merged into one block instead of stating the same thing twice. Status glyphs stay `✅`/`⚠️`/`❌`: colour may be added, but the glyphs that carry the meaning are part of the stable stdout interface.
+- `dta doctor` pointed at a command that could not fix the problem it reported. On platform-skill drift it suggested `skill upgrade`, which only iterates `BUNDLED_SKILL_NAMES` and never touches a platform skill; on an `ahead` copy it omitted `--allow-downgrade`, which `upgradeGlobalSkill` requires before it will overwrite. Repair commands are now generated per skill from `canonical.state`, and the `outdated` / `modified` / `ahead` states are spelled out in words rather than printed as bare identifiers.
+- `package-lock.json` is realigned to `0.1.5-beta.7`; the manifest had been bumped without it.
+- `check:docs` walked into directories that `.gitignore` had already declared as not-repository-content: `.claude/worktrees/` (full working copies of other branches) and `.dingtalk-agent/` (runtime state). The markdown count had silently grown from 88 to 773, and the new `legacy-skill-name` gate then failed on pre-rename names sitting in someone else's branch — making `release:check` unpassable on any machine that has a worktree. The walker now derives its skip set from `.gitignore`'s directory entries instead of keeping a second hardcoded list.
+- `lab/robot-eval/suite.json` pinned `dta-basic-behavior@0.12.0` while the skill's `metadata.version` had moved to 0.13.0, so the robot-pool scenario's version-sync assertion failed.
+- `npm run release:check` now builds first. The contract runner imports 17 modules from `dist/` at load time, so the gate only ever worked when `dist/` happened to be current — any newly added source file turned the whole release gate into an opaque `ERR_MODULE_NOT_FOUND` before a single check ran.
+
+### Migration
+
+Existing installs need `dta upgrade` (or `dta skill upgrade`) once; it installs the new names and removes the old copies in the same run. Beyond this repository, three steps are **not** automated: push the renamed platform skills to the Multica workspace and delete the old-named server-side entries (`bootstrap.sh` pulls by name, so both present means pulling the wrong one), and redeploy any deployed Agent whose instructions reference the old Basic name.
+
+## 0.1.5-beta.6 - 2026-07-23
+
+The CLI's output layer becomes a human/machine dual channel: a person at a terminal gets colour, hierarchy and step-by-step progress, while an Agent capturing stdout through a Bash tool reads text with **not a single ANSI escape** in it (PR #17). Ships on the `beta` dist-tag; `latest` stays at 0.1.4.
+
+### Added
+
+- `src/tui.ts`, a zero-dependency output layer built on two deliberately independent switches. The **colour axis** follows `NO_COLOR` / `NODE_DISABLE_COLORS` / `CLICOLOR` / `TERM=dumb`; the **motion axis** (`\r` redraw, cursor control, column alignment) follows `stream.isTTY` and nothing else. `NO_COLOR` therefore strips colour while leaving the layout skeleton byte-for-byte intact — the same rule half the spinner libraries in the ecosystem get wrong.
+- `StepReporter`: one event stream, two renderers. On a TTY the in-progress line is redrawn in place and collapses into a single terminal fact (`[2/7] 安装 … ✔ (2.1MB, 0.3s)`); off a TTY it emits one line per step with a greppable leading status word and zero control characters. `dta upgrade` now reports its seven natural phases instead of going silent for up to 338 seconds.
+- `dta upgrade --check` (resolve the target without installing, `dingtalk-agent/upgrade-check@1`), `--yes`, and `--help`. `--color` / `--no-color` / `--color=<auto|always|never>` are accepted globally: they are stripped from `argv` before dispatch, so a single site replaces edits to 23 strict-mode `parseArgs` blocks. Two contract scenarios (`DualChannelOutput`, `ConfirmSettles`) pin the invariants in the default `core` tier.
+
+### Changed
+
+- **Environment variables can now only turn colour off, never on.** `FORCE_COLOR=1` / `CLICOLOR_FORCE=1` no longer force colour into a pipe; the only way to colourise non-TTY output is an explicit `--color` on the command line. This deliberately departs from the npm-ecosystem convention, because dta's non-TTY reader is primarily an Agent: an inherited `FORCE_COLOR` would turn escape sequences into model-visible noise, and the leak is invisible to a human on a colour terminal. `TERM` / `COLORTERM` are likewise not treated as enabling signals — they survive into the Agent's environment untouched.
+- Every human-facing printer, `fail()`, the help screens and `dta schedule` route through the theme. **The text and line structure are unchanged byte-for-byte**: semantics still ride on the existing `✅`/`⚠️`/`❌`/`PASS`/`FAIL` glyphs and `key=value` structure, so colour remains a discardable decoration and all existing output assertions keep matching. `--json` bypasses the theme structurally rather than "deciding not to colour", and `dta --version` stays bare — it is the machine-parsed object of dta's own self-upgrade chain.
+- The interactive confirmation on `dta upgrade` appears only when stdin is a TTY. Pipes, CI and Agent invocations keep the previous "run it and it installs" behaviour, so `scripts/release-readiness.mjs` and the contract evals needed no changes.
+
+### Fixed
+
+- `displayWidth` mis-measured the very glyphs dta prints: `✅` (U+2705) and `❌` (U+274C) counted as one column each because they sit outside the East-Asian-Wide ranges and need `Emoji_Presentation` to be identified. The replacement derives its 62 ranges from a per-code-point sweep and adds zero-width marks (`Mn`/`Me`/`Cf`, but not the spacing `Mc`), emoji modifiers, text-presentation pictographs that are themselves Wide, and lone regional indicators. It now agrees with `string-width@8` across all 260,096 code points in `0x0..0x3FFFF`.
+- The upgrade confirmation could not settle when a TTY's input stream ended: `readline`'s `question()` promise never resolves in that case, so the process exited silently with no error and no non-zero code. It now races the prompt against the `close` event, and both interruption paths decline rather than inheriting the non-interactive default.
+- `npm run release:check` now builds first. The contract runner imports 16 modules from `dist/` at load time, so the gate only ever worked when `dist/` happened to be current; the first newly added source file turned the whole release gate into an opaque `ERR_MODULE_NOT_FOUND` before a single check ran. `eval:contract` already built — `release:check` did not.
+- `dta upgrade --version <older> --force` announced "已是最新版本" and then downgraded anyway; the check result now carries `relation` (`upgrade`/`same`/`downgrade`) instead of a single `outdated` flag. The interactive path also pins the exact resolved version as the install source, closing the window in which a moving registry tag could install one version while the run verified against another.
+
+## 0.1.5-beta.5 - 2026-07-23
+
+Long-term memory becomes a bundled standard capability: any DingTalk Agent can maintain living profiles for the **people** and **conversations (groups/DMs)** it works with over time, storage-decoupled behind a port so the model layer never touches a specific medium (PR #13). Ships on the `beta` dist-tag; `latest` stays at 0.1.4.
+
+### Added
+
+- `dingtalk-people-group-memory` joins the default bundle (`BUNDLED_SKILL_NAMES`). It is fully inert until storage is bound — zero writes, zero probes, and it must not claim "I remembered" — so bundling it by default has no side effect; binding is deferred to when the user actually asks. The skill is a three-layer design: `model.md` (Person/Conversation/Fact/Watermark, medium-agnostic — verifiably zero DingTalk vocabulary), `event-ingest.md` (message/todo/doc events → Facts, `evidenceId`-keyed idempotency), and `storage-port.md` (10 operations + 8 capability bits) with adapters for `dingtalk-doc` (narrative) and `aitable` (registry), plus a `local-md` contract.
+- Section `kind` split (`narrative` vs `registry`): prose profiles live in DingTalk docs (read-whole, human-readable), while indexes/watermarks/tombstones live in AI Tables (query-by-key, real pagination, no 340-line truncation wall). The same model-layer operations route to either medium purely by capability bits — swapping the registry medium collapses a whole class of doc-only pathologies.
+- `consolidation.md`: the one-year answer for append-only raw — monthly digests, a bounded O(1) working set, `working-on` decay, derived-section curation, and count-based completeness (write-side row counts reconciled on read, since the production medium truncates silently).
+- `config-binding.md` + `guided-setup.md`: the user-configured storage address lives in `agent.bindings.json#memory` (`dingtalk-doc:<adoc-node>`) or `DTA_MEMORY_STORAGE`, resolved by the existing bootstrap `select()` chain — never hardcoded in the skill. A seven-step guided-creation flow walks a user from nothing to a valid, parse-verified adoc binding record. `COMPLETENESS.md` states honestly what is delivered (guided single-agent read/write, proven on real dws) versus contract-only (full autonomy, multi-agent, one-year compaction).
+- The compose Skill gains a "long-term memory" section: bundled, no assembly-time action beyond writing a seed into the body if already bound; binding must happen under the runtime identity, not the developer identity.
+
+### Changed
+
+- `dta --help` merges the `info` / `workspace doctor` / `schedule show` read-only-diagnostics into one line, keeping the default help at ≤20 lines after the driving layer (beta.4) added its `schedule` entry.
+
+### Fixed
+
+- `package.json#files`, the release-readiness required-skill list, and the `#20`/`#28` contract fixtures are updated for the four-skill default bundle; `package-lock.json` is realigned to the package version (beta.4 had bumped the manifest but not the lock).
+
+## 0.1.5-beta.4 - 2026-07-23
+
+Driving layer: the recurring drives that wake a digital employee become a version-controlled, provider-mapped declaration instead of imperative platform state, plus a smoke-whitelist bare-filename fix that had blocked live deployment (PR #16). Ships on the `beta` dist-tag; `latest` stays at 0.1.4.
+
+### Added
+
+- Agent Projects declare their internalized cron in `dingtalk-agent.json#schedules`: a provider-neutral list (`name`, `cron`, `timezone`, `mode` of `ephemeral`/`work-item`, plus governance metadata `wake`/`completion`/`unit`/`evidence`/`supervision`). The manifest validator rejects non-5-field crons, `@macro` forms, unknown modes and duplicate names; `dta info` reads them back. The project source hash covers only definition + skills, so declaring or editing schedules never perturbs the deployment hash.
+- `dta schedule show` lists the declared drives with each rhythm's data-derived completion predicate and statically checks that no two share a cron minute field (the precondition for collision-safe outward delivery). `dta schedule plan --workspace <name>` maps the declaration to a provider-specific reconcile plan — Multica to `autopilot` create commands (`ephemeral`→`run_only`, `work-item`→`create_issue`); an unsupported provider fails closed and records the declared rhythms as a gap rather than silently downgrading. Both are pure and network-free.
+- `docs/schemas/project.schema.json` gains the `schedules` definition; the compose Skill's `drive-and-schedules.md` is the authoring method: an internalized cron is a level-triggered reconciler (state decides the work and the done), not an edge-triggered dispatcher, and every rhythm must answer five questions with a data-derived completion predicate at its heart.
+
+### Changed
+
+- Architecture §3.1 makes driving an explicitly modeled layer: dingtalk-agent implements no trigger, but owns the driving contract — declare which rhythms an employee needs, verify per-provider capability at deploy time, and hold the behavior contract a tick must satisfy. Compose, Basic Behavior and the platform packages carry the three platform-independent constraints (timers are unreliable so completion is "did it happen", outward ticks have no lock so they must not share a minute, and the Agent never self-installs or hot-edits its own alarm).
+- The multica-external ops Skill reconciles autopilots from `dta schedule plan` rather than hand-authoring them: list live first, create only what is missing, and never blind-create — `autopilot-create` is not idempotent and duplicates cause duplicate outward sends.
+
+### Fixed
+
+- The Multica load-smoke whitelist accepted `./result.md` and absolute workdir paths but rejected the same file referenced by a bare name (`result.md`) — which is exactly how the platform Agent writes it — so a smoke that loaded all Skills and produced the correct structured response still reported `providerReady=false` and blocked deployment. Only exact basenames are now accepted (`foo/result.md` and `../result.md` still fail closed); a contract fixture reproduces the bare-name trace and the assertion was verified to go red when the fix is reverted.
+
+## 0.1.5-beta.3 - 2026-07-22
+
+Agent delivery-package single-source layout and Multica Issue-Adapter receipt compatibility (PR #11). Ships on the `beta` dist-tag; `latest` stays at 0.1.4.
+
+### Changed
+
+- Compose 0.13.2 keeps deployed `agent/AGENTS.md` role-only: shared behavior cases propagate through the versioned Basic directory tree instead of being copied into each Agent definition.
+- Basic Behavior 0.12.0 adds a general batch-side-effect boundary distilled from a supervised DingTalk forwarding incident and the Aily behavior audit: when correctness depends on pagination, stable person-content binding, reconciliation or crash recovery, the Agent must upgrade from a model-driven tool loop to a frozen effect list plus deterministic runner and durable receipts. Without that runtime it may preview or run an explicitly supervised bounded batch, but cannot claim unattended execution. Repository guidance now also defines how future cases progress from evidence to one owner, a lean Skill entry, decision-family references, deterministic fixtures and versioned deployment without copying shared rules into each Agent.
+- Agent delivery packages now have a single source of truth: new projects generate `agent/AGENTS.md` and `agent/skills/`, and Host exposure is materialized only into temporary isolated workspaces instead of being committed alongside the source. The project manifest gains `skillsRoot`; explicit paths and the legacy root layout keep working.
+- Basic Behavior 0.11.11 makes IM history file-identifier recovery mandatory: rich-message recovery follows a fixed readback-before-gap-judgment order, and a fileId present in a history file card must go through `drive info`/read-only download instead of the Agent claiming it cannot read the file. A deterministic history-file-card fixture locks the behavior.
+- Golden Path and load-evidence fixtures moved to the `agent/AGENTS.md` + `agent/skills` single-source layout; load evidence now verifies resolved instructions against the trusted `definitionInstruction` exactly, while the legacy implicit root-`AGENTS.md` rule remains accepted.
+
+### Fixed
+
+- The Multica deployment load-smoke gate no longer misjudges the platform's constrained Issue-Adapter receipts as arbitrary Shell. It accepts the combined here-doc write/comment/cleanup control-plane command only when content, filename and target Issue all match exactly, extracts the response evidence from that command, adds `result.md` to the approved result filenames (alongside `reply.md`/`result.json`), and allows `rm`/`rm -f` cleanup only for those three whitelisted files. DWS, network and any other Shell use still fail closed.
+- Contract scenario 54's injected-timeout legs used a 1-second per-call provider budget, which a loaded machine could exhaust on an innocent preflight read (each fake-provider call spawns a Node process) before ever reaching the write the timeout was injected on — the pre-release `--full` run failed exactly this way while the isolated rerun passed. The runtime behaved correctly (read timeout → fail closed before any remote write); the eval budgets were raised to 4 seconds with the simulated hang raised to 8, and scenario 54's expectation texts in `evals.json` were reordered to match the runner's check order, which had drifted and mislabeled the failing assertion.
+
+## 0.1.5-beta.2 - 2026-07-21
+
+Multica native-Skill refactor and DingTalk IM context recovery (PR #9, #10). Ships on the `beta` dist-tag; `latest` stays at 0.1.4.
+
+### Changed
+
+- Basic Behavior 0.11.10 makes DWS original-message recovery an executable priority gate: when the Host gives current actor/title/text/time but omits a rich-message href or quote, the Agent must run the bounded `chat search` → `message list` verification path before any local `find`/`glob`/`ls`; an empty workspace can no longer stand in for DingTalk IM evidence.
+- Basic Behavior 0.11.9 closes DingTalk IM context recovery without coupling to a managed platform: when the Host projection is incomplete, DWS may recover the current conversation's raw Markdown href, file IDs and `quotedMessage`, but a title-based group candidate becomes trusted only after the current actor/text/time trigger is independently matched; ambiguous candidates fail closed.
+- Basic Behavior 0.11.8 treats a stable DingTalk node URL/file ID in the current trusted message as the object to read: ordinary files are classified with `drive info`, downloaded read-only, and never replaced by Issue, workspace or old-task filename searches.
+- Basic Behavior 0.11.7 makes previous-file recovery mandatory when a trusted conversation is readable: it resolves the recent IM fileId/dentryId/URL and reads that object directly instead of treating workspace, memory, knowledge or an old task's read list as conversation history.
+- Basic Behavior 0.11.6 adds focused Chat-history enrichment: when the Host exposes a trusted ChatSession/conversation mapping, the Agent may use a bounded read-only DWS history window to resolve the current message's omitted referent or prior attachment, while the triggering message remains the only source of this Run's goal and authorization.
+- Basic Behavior 0.11.5 turns a real Multica IM regression into a hard evidence-scope rule: a Run that lacks the previous quote/file projection may report only that Run-level gap, never claim the conversation did not receive the message; conversation-level absence requires an independent history readback.
+- Basic Behavior 0.11.4 closes the IM file-read loop: a trusted URL/file ID is used directly, online docs use doc read, ordinary files use read-only drive download into the current task, and the Agent no longer asks for confirmation merely to perform that read.
+- Basic Behavior now freezes the current Run's trusted time and rich-message projection before reasoning. Relative dates can no longer reuse a stale Session/UTC clock, and visible filenames, file IDs, URLs or quoted fields cannot be negated by an empty workspace scan or a missing content reader.
+- Multica native Project Workspaces no longer require fake local memory/knowledge/artifacts routes; OpenCode Workspaces retain the complete semantic-storage gate.
+- Multica Agent instructions are exactly the human-authored `AGENTS.md`. Definition/deployment hashes and the required Skill manifest remain in the deployment plan, operation and Receipt instead of being prepended to the System Prompt.
+- Removed `dingtalk-agent-boot-multica`. Multica assigns only Basic and Role Skills, and the deployment Issue smoke directly asks the Host-native Skill tool to load that frozen set.
+- Workspace inspection, platform registration, package contents and deterministic W4/W5 contracts enforce native Skill assignment and reject the obsolete Boot layer.
+- Multica deploy 0.3.2 recovers exactly once when a persisted load-smoke Issue has no task after assignment. It posts one stable-ID Agent mention on that Issue only for the empty-run state and never duplicates an already queued, running, or terminal smoke task.
+- Multica deploy load-smoke accepts the platform's two constrained result-file conventions, `reply.md` and `result.json`. Both remain fail-closed: the path must use an approved response filename without traversal, the payload must exactly match the marker and required Skill set, and any unapproved tool call still fails the gate.
+- Eval 0.7.3 adds the managed Multica `workspace run` path, current DWS `list-direct` readback, capability-aware event-subscription fallback, and a required IM matrix for continuation, quote, file, document and correction cases.
+- Compose 0.13.1 strengthens the readable Basic inheritance anchor: every task must load Basic through the Host-native Skill tool before analysis, reply, or Role Skill use. This introduces no Boot Skill or machine metadata in the System Prompt.
+- `doctor.ready` now treats Claude Code/Codex/OpenCode discovery conflicts as client-specific observations rather than runtime blockers; canonical Skill absence, DWS/auth, CLI and Node failures remain fail-closed.
+
+### Fixed
+
+- Synced the robot-eval suite's `exact-basic-version` expectation to the canonical Basic Behavior version (0.11.8 → 0.11.10). Contract 43 asserts the load-probe version tracks `metadata.version`; the earlier Basic bumps left this fixture behind, so a full run failed until it was re-synced.
+
+### Release boundary
+
+- These changes require a new Multica deployment so existing Agents drop the old Boot assignment and receive the readable Definition. The first `dta deploy` after upgrade rewrites each managed Agent's System Prompt to the raw `AGENTS.md`, so it is a content update rather than a no-op.
+
 ## 0.1.5-beta.1 - 2026-07-20
 
 Documentation and evaluation-tooling release. **No runtime code changes** — `bin/` and `src/` behavior is identical to 0.1.4; the only `bin/` edit is a header comment. Ships on the `beta` dist-tag; `latest` stays at 0.1.4.

package/README.en.md

@@ -2,26 +2,30 @@
 
 # dingtalk-agent
 
-**Give every digital employee the same verifiable behavior foundation.**
+**Let your coding agent turn an existing Agent into a DingTalk digital employee.**
 
 [![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)
 
-[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)
+Evaluating? → [What it is](#what-it-is) · [What it does](#what-it-does) · [When to use it](#when-to-use-it) 　|　 Ready to build? → [Quick start](#quick-start)
 
 [简体中文](README.md) · English
 
 </div>
 
-`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.
+![Someone @-mentions it in a group chat; it finishes the job like a colleague, leaving a trace at every step](docs/assets/digital-employee-at-work.svg)
 
-> **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.
+## What it is
+
+dta doesn't build the runtime substrate, but it owns the whole path of turning an Agent into a DingTalk digital employee.
+
+What separates a digital employee from a chatbot is a DingTalk-issued organizational identity: it has a name in the directory, can be @-mentioned, works only in the groups and conversations it was authorized for, and everything it does is recorded under its name.
 
-**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.**
+A working Agent still has to add a whole layer of engineering that has nothing to do with your business logic: identity and permissions, telling which message in a group is meant for it, not sending to the wrong person, and producing delivery evidence when it reports "done". Every new digital employee redoes all of that. dta turns it into a set of inheritable rules and one CLI that your coding agent installs and uses, so you don't have to study DingTalk's identity model, event model, and outbound limits yourself.
 
-![The complete path from Agent definition to delivery through two identity types](docs/assets/agent-delivery-lifecycle.svg)
+Works with: Claude Code · Codex · OpenCode · any coding agent　|　Managed platforms: Multica (supported) · DEAP (coming soon)
 
 ## Quick start
 
@@ -38,43 +42,24 @@ npm install --global --prefix "$HOME/.local" \
 "$HOME/.local/bin/dta" doctor
 ```
 
-`setup` installs the Basic Behavior, Compose, and Eval Skills, then checks DWS authentication and common Agent Hosts. Normal sessions do not require Workspace initialization.
-
-**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.
-
-## Why it exists
+`setup` installs the shared-behavior, compose, and eval Skills, then checks DWS authentication and common Agent Hosts. Normal sessions do not require Workspace initialization.
 
-A model that talks is not a digital employee that works reliably. `dta` turns the four most drift-prone concerns into inheritable, verifiable contracts:
+### Minimal runnable path
 
-- **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.
-
-## What an Agent is made of
-
-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.
-
-Full composition, dependencies, and boundaries: [Architecture](docs/ARCHITECTURE.md#2-一个-agent-由什么构成模型-a).
-
-**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:
+Start with these three — no DingTalk account, no managed platform, and no side effects:
 
 ```bash
-dta agent audit \
-  --bindings agent.bindings.json \
-  --require-skill <role-skill-name> \
-  --verify-load --yes --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
 ```
 
-## How this repo is divided
-
-**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).
+`release-manager` is a complete sample of a release-manager digital employee: it picks up "can we ship this version?" in a group, checks the gates, summarizes the verdict, and requires human confirmation before moving on. Replace the role duties in `agent/AGENTS.md` with your own, run `agent audit` again, and the only gap left is the load probe — which needs an Agent Host, see the [Compose Skill](skills/core/dta-agent-compose/SKILL.md).
 
-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).
+### Full delivery chain
 
-## Create → test → promote
-
-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-从定义到上线).
+<details>
+<summary>The complete create → test → ship commands (worth reading once you have a managed platform binding)</summary>
 
 ```bash
 # 1. Generate a zero-write plan, then commit it explicitly
@@ -84,8 +69,8 @@ dta agent enhance --project-name release-agent --role-skill release-manager \
 
 # 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
+dta workspace run local-dev --prompt-file prompt.md --execute --yes --json
+dta workspace eval local-dev --suite evals/suite.json --execute --yes --json
 
 # 3. Cloud preflight, promotion, and observation
 dta workspace inspect multica-dev --execute --yes --json
@@ -94,53 +79,100 @@ dta promote --source local-dev --target multica-dev --dry-run --json
 dta observe --promotion-id <promotion-id> --input <observation.json> --dry-run --json
 ```
 
-Plans are zero-write by default. Remote writes require an explicit target, the current `planId`, and confirmation.
+Plans are zero-write by default; every remote write requires an explicit target, the current `planId`, and confirmation. `<plan-id>` comes from the preceding dry run's `.planId`; `local-dev` / `multica-dev` are Workspace names you declare in `dingtalk-agent.json#workspaces`. 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-开发生命周期从定义到观测).
+
+</details>
+
+## What it does
+
+Turning an Agent into a DingTalk digital employee takes six stages, and dta covers every one:
+
+| Lifecycle stage | What dta does | With what |
+|---|---|---|
+| **① Body and employee skills** | An inheritable, verifiable shared behavior contract: when to speak, whether a message is even a task, who must approve an outbound action, how risk is graded, what counts as done, what to remember and forget. You write only the few dozen lines that differ by role | `dta-basic-behavior` · `agent enhance` · `examples/agents/` |
+| **② Identity acquisition and event perception** | Normalize differently shaped raw events into a stable structure; freeze the reply target and execution identity into a snapshot message text cannot alter, making wrong-recipient structurally impossible; bind permissions and outbound ownership per field; one event yields exactly one Run, losing and duplicating nothing across crashes | `prepare` · `run` · Field config |
+| **③ Managed-platform deployment** | See the plan before anything lands: frozen hashes for the body and the whole Skill tree plus a write budget; independent readback and a load smoke test after writing; re-running the same version writes nothing; failures roll back and shipped agents can be retired (today this lands on Multica) | `deploy` · `promote` · `--retire` |
+| **④ Driving it to work inside DingTalk** | Outbound has only four atoms; before an action the gate blocks overreach and target drift, after it a platform readback is mandatory; no blind retries when the outcome is uncertain; a "done" report must carry re-verifiable evidence | `act` · Action Gate · `task checkpoint` |
+| **⑤ Evaluation design** | Not a scoring tool but a method: how to pick the cheapest sufficient level, which evidence surfaces one verdict must collect, which failures may never be averaged away, how a real incident becomes a replayable case, and what blocks a release | `lab` · `workspace eval` · `dta-agent-eval` |
+| **⑥ Observation and feedback** | Bind a production finding to the exact version that ran, desensitize it, and feed it back into evaluation material, without ever changing the Agent's behavior on its own | `observe` |
+
+## When to use it
+
+Use it when:
+
+- you already have a working Agent and want it in DingTalk groups under an organizational identity, getting @-mentioned and assigned work;
+- you run DingTalk automation and have been bitten by sending to the wrong person, or by exit code 0 being treated as success;
+- you are building not one digital employee but a batch, and don't want shared behavior copied into several drifting prompts;
+- your work spans days, waits for human confirmation, and can be called off midway — not one-shot Q&A;
+- you need to prove to someone that what runs in production is the exact version you verified.
+
+Skip it when:
+
+- you just want a Q&A bot: one DingTalk robot webhook is enough, and this is overhead;
+- you just want to call DingTalk APIs: use DWS directly — it already works, and dta is not a prerequisite;
+- you are not on DingTalk: the only execution path is DWS and identity is issued by DingTalk, neither of which is swappable.
 
-The placeholders above are not yours to invent — each has a definite source:
+Not possible today: importing an Agent already deployed on another platform (data flows one way, local definition to managed platform, with no import command); triggers (webhooks, timers) are also out of scope.
 
-| Placeholder | Where it comes from |
+## Where it stands today
+
+| Area | Where it is |
 |---|---|
-| `<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 |
+| First five of the six stages | In shape |
+| Stage six (observation & metering) | The thinnest. Usage metering — interaction counts, tokens, cost, per-person/per-group breakdown — isn't built yet |
+| Managed platform | Multica supported; DEAP coming soon; the platform SPI isn't merged into main yet |
+| Agent Host | OpenCode complete; the Claude Code adapter isn't implemented |
+| Completion evidence | The verify side is implemented and contract-locked; the issue side isn't wired to a public command |
+| Importing an Agent from an external platform | No such command; data flows one way, local to platform |
+| Regression net | 62 deterministic contracts, run in 18 seconds |
 
-### Minimal runnable path (local only, three commands)
+## How it works
 
-To see something move first, don't start with the chain above — that is the full delivery pipeline. Start here:
+> **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.
 
-```bash
-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
-```
+These boundaries are structurally impossible to cross, not politely discouraged in a prompt: without an `@` in a group it stays silent; the CLI has no "send to" parameter, so the reply target can only come from the message that triggered it; a completion report must carry host-issued evidence that can be read back independently. All three are watched by deterministic contract evals — break them and the suite goes red.
+
+**DWS is DingTalk's own command-line tool** (separate from this project, with 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; every real DingTalk operation is ultimately executed by DWS.
+
+## FAQ
+
+**Is this yet another Agent framework?**
+No. It provides no model, no tool loop, and no agent runtime. It gives your coding agent a set of Skills and one CLI to compose an existing Agent into a DingTalk digital employee.
 
-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.
+**Does it conflict with Claude Code or Codex?**
+No — it is built for them. `dta setup` installs the Skills into these coding agents; after that you instruct them in natural language. The CLI also works standalone.
+
+**My Agent already runs on another platform — can I bring it in?**
+The body (role definition and Skills) is portable: compose locally, then ship to a managed platform. But there is no command today that imports from an external platform, and Multica is the only managed platform supported.
+
+**What do I need to try it once?**
+No DingTalk account and no managed platform. Composing, auditing, `workspace run/eval`, and the full contract suite all run locally; `doctor` marks what's missing as `partial` instead of failing. Only real outbound messaging and shipping need DWS authentication.
+
+**How much effort does it take?**
+The main work of the first role is writing the role duties clearly, not writing code: the body is Markdown, and you edit from the examples. Adding a second role changes three files and zero kernel code.
 
 ## Support
 
-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:
+A managed platform, an Agent Host, and the dta kernel are three separate things: the managed platform owns Workspace, Runtime, and observation, and binds a DingTalk-issued identity to the Agent (issuance stays with DingTalk); the Agent Host (a.k.a. Harness) loads definitions and Skills and isolates execution; the dta kernel is this project.
 
 | 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 |
+| **Managed platform** | Multica (DingTalk) supported; DEAP coming soon; onboarding a new platform takes the same path: author a platform Skill pack and register one entry |
+| **Local runtime** | Direct/Mounted sessions in Claude Code, Codex, OpenCode, and similar Hosts; OpenCode is the most complete local reference |
+| **Cloud runtime** | Multica Workspace / Runtime / Agent with the same definitions, Skills, gates, and evidence contract |
+| **Delivery identity** | Digital-employee/account identity or robot-app identity, both issued by DingTalk; neither changes the role's duties or expands its authority |
 
-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.
+DEAP may play two roles at once: its most important value to this project today is DingTalk-side identity/authorization and perception/human-interaction; whether it also embeds a runtime platform of its own is not yet settled. See the [DEAP platform note](skills/platforms/deap/PLATFORM.md). "Multi-platform" means the registry and onboarding contract are extensible; it does not claim that unopened platforms are deployed or Live-verified.
 
 ### Runtime modes
 
 | Mode | Use | Boundary |
 |---|---|---|
 | **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 |
+| **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` |
 
-Prepared Runs expose four message atoms: `ack`, `reply`, `ask`, and `silence`. An acknowledgement is not task acceptance, and a reply is not human acceptance.
-
-**Triggers are out of scope for this project**: `listen` is a replaceable local integration Adapter, and `dta deploy` never creates robots, webhooks, or timers.
+Prepared Runs expose four message atoms: `ack`, `reply`, `ask`, and `silence`. An acknowledgement is not task acceptance, and a reply is not human acceptance. Triggers are out of scope: `listen` is a replaceable local integration Adapter, and `dta deploy` never creates robots, webhooks, or timers.
 
 ## Docs
 
@@ -148,12 +180,13 @@ Prepared Runs expose four message atoms: `ack`, `reply`, `ask`, and `silence`. A
 |---|---|
 | Understand the Agent architecture and how the repo is divided | [Architecture](docs/ARCHITECTURE.md) |
 | Install, upgrade, or troubleshoot | [Installation](docs/INSTALLATION.md) |
+| Take over an agent already running in production (runtime view) | [Agent in Production](docs/AGENT-IN-PRODUCTION.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) |
+| Create or audit an Agent | [Compose Skill](skills/core/dta-agent-compose/SKILL.md) |
+| Test or debug a delivered Agent | [Eval Skill](skills/core/dta-agent-eval/SKILL.md) |
+| Read the shared behavior protocol (a contract written for models, not a tutorial) | [Basic Behavior Skill](skills/core/dta-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) |
+| Which platforms and open-source projects we keep absorbing practices from | [Prior Art](docs/PRIOR-ART.md) |
 
 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.