git:20260917.ce9787c to git:20260917.50292cc

# Repository Agent Guide

This file applies to the entire repository. Keep changes scoped, preserve

unrelated work, and use `gofmt` for every modified Go file.

## Build and test

- Build: `make build` (wraps `scripts/dev/build.sh` → `go build -o dws ./cmd`; bare `go build ./cmd` fails because output name `cmd` collides with the directory)

- Full test suite: `DWS_PACKAGE_VERSION=0.0.0-test go test ./...`

- Param aliases generate: `go generate ./internal/cli` (entry point: `internal/cli/gen.go`; Catalog is not generated)

- Optional diagnostic MCP dump (not a Schema pin): `make fetch-mcp-metadata` (requires `dws auth login`; writes under `artifacts/`)

- Check generated drift + assembly determinism: `./scripts/policy/check-generated-drift.sh`

- Check the Schema contract: `./scripts/policy/check-schema-catalog.sh`

- Coverage-gate test naming: tests that carry coverage for the macOS platform

gate must be named `TestCrossPlatformCoverage*` (or `TestAllShortcuts*`);

`scripts/policy/run-platform-coverage-gate.sh` only selects those prefixes,

so a covering test with any other name silently leaves its target uncovered.

- Package-var injection seams (e.g. `pipelineBuildEffectiveRegistry`): swap

them in tests only via `testseam.Swap(t, &seam, stub)` from

`internal/testseam` — it restores the previous value through `t.Cleanup`

structurally. Like the manual pattern it replaces, Swap mutates global state

and is **not** safe for `t.Parallel` tests.

- Cross-package test helpers (e.g. `StoreProductDeclRawForTest`) live in

per-package `fortest.go` files, never scattered through production files;

the `ForTest` suffix is the boundary and production code must not call them.

Schema Catalog delivery is **声明即 Catalog**: production assembles via

`RegisterSchemaSourceRoot` → `ResolveSchemaBuild` (factory registered in

`internal/app`). Schema identity is **not** produced at compile or release

time; shipping binaries do not embed binary-pinned cache digests. On

supported platforms (darwin/linux/windows amd64/arm64) production enables the

persistent cache: install or the first schema-consuming path generates

identity from this binary's live declarations, writes authenticated disk

shards, and later processes load that local identity then verify digests

before reading protobuf. A missing sidecar generates then uses the cache;

it is not a permanent live-only mode. Plugins that change the command

surface still disable cache publication, repair, and prewarm; read-only

serving of the unchanged reviewed surface continues (plugin commands never

enter the Schema surface, cached or live). Tests may also inject identity via

`RegisterSchemaCacheOptions`.

See `docs/rfc-schema-runtime-cache.md` for the single RFC covering the

local-identity shipping model, complete-tree performance contract, cache

delivery; no sibling plan/design/performance pages are kept. Telemetry

delivery is the detached background-process model (see

`.changes/clitrack-detached-reporting.md`), not the retired in-process

`NoFlushWait` CLI default.

There is no

`cmd_schema_catalog` `//go:generate` delivery step. `dws schema -f json` remains

the wire projection. `cmd_schema_catalog` produces CI/local dumps only;

`internal/cli/schema_catalog/`, `internal/cli/schema_meta_index.gob`, and

`internal/cli/schema_meta_index.json` must not be committed. `schema_agent_metadata/` is retired: if that directory

(or `schema_agent_metadata_audit.json`) is present, policy fails.

Command identity is no longer a file input: it is collected from

`ContractFinal.Identity` on the live Cobra leaves

(`internal/cli/schema_identity_collect.go` → `BuildEffectiveCommandRegistry`).

The reviewed `schema_command_registry/` was retired together with that

switchover and must not reappear; identity changes happen by editing the leaf

declaration. The remaining **reviewed inputs** under `internal/cli` (see Agent

Schema contract) keep separate authorities — do not merge them with

`param_concepts.json` or promote any of them into Catalog declaration.

## Command framework declaration

- Framework definition: `docs/rfc-command-framework-convergence.md` **§5.0**

- Today (leaf): `helpers.LeafSpec` / `shortcut.Shortcut` → `corecmd.Spec` (+ optional `Contract`) → `corecmd.New`

- Today (non-leaf): owning Cobra command → complete `corecmd.GroupPolicy{Mode, Positionals, Recovery}` → `corecmd.ApplyGroupPolicy`; the final assembled-tree gate rejects undeclared groups and stale group declarations on leaves

- **Declare = final Schema source**: `Flags` / `Constraints` / `Safety` / `ConstParams` / `Contract` (`corecmd.ContractDecl`; nested fields are `contract.*`)

- Naming: `ContractDecl` is the authoring leaf declaration. "Schema" means Catalog / `ToolSpec` delivery — do not reintroduce `SchemaDecl`.

- `Safety` uses `contract.SafetySpec` (`internal/corecmd/contract` only — no `cli.*` type alias). Its `confirmation` drives the runtime gate; `effect` / `risk` / `idempotency` are published unchanged. When `Contract` is set, convert once via `contractfinal.RegisterRuntimeContractFinal` (all callers — `corecmd.New` registers internally); assembly **pass-throughs** Final.

- Package seam:

- types / ProductDecl → `corecmd/contract` (DTO only; **no** Cobra-keyed ContractFinal store)

- AnnotateRuntime* writers → `internal/corecmd/runtimeannotate` (framework-owned)

- ContractFinal cobra store + Register → `internal/corecmd/contractfinal` (framework-owned)

- homology gates → `internal/cli/homology`

- Catalog assembly / `ResolveMeta` (`RegisterSchemaSourceRoot` → `ResolveSchemaBuild`); go:embed only for reviewed inputs → `internal/cli` root (package-local aliases for annotate/store APIs live in `runtime_schema_seam.go`; the former `cli/runtimeannotate` / `cli/contractfinal` shim packages are removed — import `corecmd/*` directly)

- **Hard rule**: `internal/corecmd` (and its subpackages) must **not** import any `internal/cli` package

- Command metadata must not keep discarded Cobra trees alive. Use framework

`commandstore.Map` weak keys for DTO metadata; values must not reference commands.

Execution-hook lookups must also use weak values when closures can capture a

command; the installed RunE pipeline owns those hooks strongly.

- Authoring tiers (current, not aspirational):

- **Tier1** — `corecmd.New` / `helpers.NewLeafCommand` (fully managed declare + execute)

- **Tier2** — `DeclareLeafMetadata` (helpers migration; **Shortcut may also use this path — acceptable**)

- **Tier3** — bare Cobra (should shrink over time; reviewed exclusions where needed)

- Long-term outlook only: broader mcpbind / fewer hand-written `Execute` bodies. **Not** a current hard requirement to delete `Shortcut.Execute` or force mcpbind.

- Group policy is separate from the leaf tiers: `corecmd.Spec` remains leaf-only. `ApplyGroupPolicy` must not infer or enable `TraverseChildren`; parent local-flag inheritance remains an explicit owning-command surface.

- Description declare vs delivery: construction requires `ContractDecl.Description` (evidence). Catalog delivery prefers Cobra Long → provenance `cobra_help`; without Long, declared text → `contract_final`. Title: declared first, then Short, then MCP. Do **not** read this as "declare = wire final" or dual authority.

- **Execute** = hooks (`Validate` / `Call` / `RunE` / `PostMount`) — not a second surface authority

- Declaration path has **no reviewed parallel fields**; migration-only `runtime_gate` annotate until `Safety` is declared

- **Do not add** new production `AnnotateRuntimeRisk` / `AnnotateRuntimeGate`

(`runtime_gate`) call sites; migrate leaves to declared `Safety` /

`ContractDecl` instead. Existing annotate sites may remain until migrated.

## flag / help / schema homology

- Decision (path A — Contract/LeafSpec is CLI-surface authority **and must embed into Schema**): `docs/flag-help-schema-homology.md`

- Hard rule: every help/Schema fact is **declared** **or** **annotated**; never inference-only (§1.1–§1.3; framework §5.0).

- Embed path: `corecmd.New` → `dws.schema.*` annotations → Schema catalog assembly

- MCP metadata must not create CLI flags; optional 1:1 passthrough is a gated subset only.

- Gate IDs: `HOM-P*`, `HOM-S*`, `HOM-I1`, `HOM-D1` (see that doc §3–§4). `HOM-P1`/`HOM-D1`/`HOM-S1`/`HOM-S2` are on the `check-schema-catalog.sh` policy whitelist; remaining IDs land incrementally.

## Agent Schema contract

The Schema data flow is one way:

```text

1. app.NewRootCommand()

└─ builds the real Cobra command tree and flags

└─ leaf Safety / Contract / contract.ParamDecl declare ContractFinal (declare-or-annotate)

2. CollectIdentitySpecs (ContractFinal.Identity on live Cobra leaves)

└─ forms EffectiveCommandRegistry

└─ binds exactly to real Cobra leaves and aliases

3. Parameter resolution

Cobra flags

+ contract.ParamDecl.Property / native annotations (primary property authority)

+ schema_parameter_mapping_ledger.go (mapping_exclusions / removals only;

active bindings JSON retired after Track 1 Phase 2)

└─ produces ParameterSpec and constraints

4. Agent and interface semantics

ProductDecl + leaf ContractFinal Selection / Safety / Interface

+ contract.ParamDecl (interface_type / property)

└─ resolves Agent metadata by source precedence

Markdown is evidence only; it is not concatenated into final prose

└─ schema_hints/ and schema_mcp_metadata.json are fully retired

5. One typed hub

BoundCommandRegistry

+ ParameterSpec

+ Agent metadata

+ Interface metadata

└─ resolves every command exactly once into ToolSpec

└─ aggregates SchemaRegistry + SchemaIndex

└─ ResolveSchemaBuild assembles at runtime; deliverySchemaCatalog wraps it (lazy, sync.Once)

6. Runtime delivery (no generate-written Catalog authority)

SchemaRegistry

└─ dws schema list/product/group/leaf/--all (-f json wire)

└─ ResolveMeta projects Identity/Safety/Selection from the same registry

└─ CI may dump Catalog via cmd_schema_catalog for jq gates / determinism

```

**Reviewed inputs / 评审输入** (organizational family under `internal/cli`;

parallel peers, not one merged authority). These are assembly inputs only —

never Catalog declaration authority, never leaf `Contract` / `ProductDecl`

substitutes. Keep them side-by-side; do **not** fold one into another:

| Input | Path | Owns |

|---|---|---|

| Command identity | collected from `ContractFinal.Identity` on live Cobra leaves (`schema_identity_collect.go`; not a file input) | stable identity, primary CLI path, aliases, navigation |

| Param concepts | `param_concepts.json` (+ `.schema.json`) | argv synonym / concept dictionary (reduced to `param_aliases_generated.go`) |

| Exclusions | `schema_command_exclusions.go` | exact reviewed CLI paths excluded from Schema (non-empty reason) |

| Mapping ledger | `schema_parameter_mapping_ledger.go` | `mapping_exclusions` / removals (CLI flags with no direct RPC property); active bindings JSON retired |

`schema_mcp_metadata.json` is retired and must not reappear. Interface facts

(`interface_ref`, `interface_type`, …) declare on leaf `Contract` /

`contract.ParamDecl`. Retiring the pin cleared MCP-sourced `interface_type`

values from the wire; schema-compat deliberately accepts clearing (missing =

unknown for consumers) while still rejecting any change to a different

non-empty value. Re-populating a value requires an explicit `ParamDecl`

declaration, not a new pin.

**Aliases are three distinct layers** (do not conflate):

| Layer | Owns |

|---|---|

| `FlagSpec.Aliases` / Cobra flag aliases | executable flag synonyms on a leaf |

| `ContractFinal.Identity` `aliases` | reviewed CLI-path aliases for the same command identity |

| `param_concepts.json` | argv synonym / concept dictionary (central preparse normalization) |

**Visibility vs exclusions:** collected identity `visibility` is dormant (all

entries default `public`); “runnable but not Agent-visible” belongs in

`schema_command_exclusions.go`, not new `visibility` values. Native identity

annotations are consistency assertions only — they must agree with the

collected identity and never materialize or override it.

Leaf declare (`Contract` / `ParamDecl` / `Safety` / `ProductDecl`) and the live

Cobra tree remain separate from this table: declare owns semantics; Cobra owns

executability and flags.

After binding there is no second identity source and no identity precedence

winner. The binder must reject a missing/non-runnable Cobra path, an alias

collision, and any native identity annotation that disagrees with the effective

registry. A missing native identity annotation is allowed because annotations

are implementation-side assertions, not identity fallbacks.

The assembler resolves every bound command exactly once into one `ToolSpec`.

CI determinism (`check-schema-assembly.sh`) and policy jq gates consume a

fresh assembly dump; runtime consumes the same `ResolveSchemaBuild` path via

`RegisterSchemaSourceRoot`. Neither path may reopen annotations, merge source

records, or use a previous Catalog JSON as a source.

Pure typed consumption lives in `internal/cli/schemaruntime`, with parent-cli

aliases for compatibility. It must remain independent of cli/Cobra/app/auth.

The private generated protobuf lives in `internal/cli/schemacachepb`; bounded

authenticated I/O and atomic publication live in `internal/schemacache` and

must not call payload parsers. Framework constraint DTO normalization belongs

to `internal/corecmd/contract`, never a dependency from corecmd back into cli.

`internal/schemareader` owns the immutable binary identity and composes that

backend with the same typed decoders used by the CLI. Keep repair and process

memoization in cli. Every public process invocation constructs the same complete

Cobra tree before parsing argv, including root help, version, Schema, utilities,

business commands, and completion. Do not add argv-selected product trees,

pre-Cobra Schema execution, or a separate root-help projection.

The startup warning's agent-relative paths are shared through internal/skillpaths.

Publish the live Catalog pointer only after its Meta projection is complete.

### Assembly vs consumption

**Assembly** (declare → typed registry; CI + runtime):

- Runtime entry: `RegisterSchemaSourceRoot` (`internal/app`) →

`ResolveSchemaBuild` / `deliverySchemaCatalog` (lazy, sync.Once).

- CI tool: `cmd_schema_catalog` dumps an assembled Catalog for jq/determinism;

it is **not** a `//go:generate` or committed delivery step.

- `gen.go` only generates `param_aliases_generated.go`.

- Inputs: **reviewed inputs** (param_concepts / exclusions / mapping ledger —

see table above) + ProductDecl/ContractFinal (identity is collected from

`ContractFinal.Identity`) + live Cobra tree.

`schema_hints/`, `schema_agent_metadata/`, `schema_command_registry/`, and

`schema_mcp_metadata.json` must not reappear.

- Gates: `make generate-schema` (param aliases + assembly determinism),

`check-generated-drift.sh`, `check-schema-catalog.sh`.

**Consumption** (runtime, unified API):

- Entry point: `ResolveMeta(cliPath) → CommandMeta{Identity, Safety, Selection}`

in `internal/cli/command_meta.go` — projected from the assembled registry

when the app factory is registered.

- Consumers: `--help` (Safety annotation via `RenderSafetyAnnotation`),

agent selection, future skill generation; `dws schema` uses the same

assembled Catalog (`-f json` wire unchanged).

- `SafetyForCLIPath` delegates to `ResolveMeta` (backward compatible).

This split is architecturally isomorphic to Lark's typed metadata registry,

navigation catalog, and schema renderer. DWS intentionally preserves its

existing flat JSON wire contract for compatibility; do not treat architectural

alignment as permission to make an unversioned wire-format change.

The identity collected from `ContractFinal.Identity` (via

`CollectIdentitySpecs`) is the sole source of stable command identity and

navigation. The executable Cobra tree remains the source of truth for whether

a CLI path exists, is runnable, and which flags it accepts. Schema coverage is

bidirectional:

1. Every final `SchemaRegistry` tool, including its serialized Catalog

projection, must resolve to an executable Cobra command.

2. Every public runnable Cobra leaf must either resolve to Schema or appear as

an exact, reviewed exclusion with a non-empty reason in

`internal/cli/schema_command_exclusions.go` (central Go groups; not JSON).

Do not use prefix or wildcard exclusions: they can silently hide future

commands. Remove an exclusion when its command enters Schema; stale, invalid,

or duplicate exclusions must fail generation and CI.

When adding or changing an Agent-visible command, review all relevant inputs:

- Leaf `ContractFinal.Identity` for canonical identity, primary CLI path,

aliases, and stable navigation. Identity is collected from the live Cobra

leaves (`CollectIdentitySpecs`); there is no separate identity file. Invalid

canonical paths, alias collisions, stale paths, and drift fail collection,

binding, and policy.

- Leaf `Safety` / `Contract` (`corecmd.ContractDecl`) / `contract.ParamDecl`

(helpers `LeafSpec` or shortcut `Contract`) for parameter facts, interface

disposition, safety, and Agent selection prose. Delivered provenance is

`contract_final` from `corecmd.contract` (description may stamp `cobra_help`

when Cobra Long wins). Product routing uses `ProductDecl`

(`internal/corecmd/contract`; provenance label remains `cli.product_decl`).

- `internal/cli/schema_hints/` is fully retired. Do not reintroduce HintFiles,

audit JSON, or `imported/` baselines; declare on ProductDecl / the owning

leaf instead.

- Native Runtime Schema identity annotations, when present, as consistency

assertions against `EffectiveCommandRegistry`. They must agree exactly and

must never materialize, infer, or override registry identity.

- Flag-to-interface property mappings and required/default semantics.

- Do not expect generate-written Catalog delivery. Run

`make generate-schema` only to refresh param aliases and prove assembly

determinism. Do not expect or commit `schema_agent_metadata/`.

Run the reverse-completeness tests whenever the Cobra tree changes. A command

that works through `dws <path>` but cannot be found through the matching

`dws schema` lookup is a contract failure unless it has a reviewed exact

exclusion.

`RegisterSchemaHints` / `ToolSchemaHint` overlays are fully removed. Parameter

and selection facts must be declared on the owning leaf (`contract.ParamDecl` /

`Contract`) or via `ProductDecl`; do not reintroduce overlay registries.

For Agent-authored selection edits:

1. Confirm the exact command and flag names in the current Cobra tree.

2. Declare selection prose on the owning leaf (`Contract.Selection` /

`DeclareLeafMetadata`) and product routing via `ProductDecl`; declare

safety / parameters / interface on the same leaf.

3. Do not copy generated Catalog fields into source inputs.

4. Run generation, drift, Schema policy, and the focused CLI tests before

proposing the change.

## Agent curation workflow

Use this workflow when refreshing Agent selection prose and confirmation

alignment. Prefer **agent-authored review** over bulk merge scripts that dump

Skill Markdown into Catalog fields.

Human-authored inputs:

| Block | Path | Owns |

|---|---|---|

| **declaration** | helpers / shortcut `Safety` + `Contract` / `contract.ParamDecl` + `ProductDecl` | `effect` / `risk` / `confirmation` / `idempotency` / `interface_*` / parameter facts / selection prose (`contract_final`) |

`schema_hints/` is fully retired. Do not reintroduce HintFiles or audit JSON.

### Goals

1. **Selection prose** is decision-oriented (Feishu/Lark style): trigger intent,

sibling-command routing, and outcome shape — not a restatement of the

summary. Delivered Catalog provenance is `contract_final` from leaf

`Contract.Selection` / `ProductDecl`.

2. **Safety** follows Runtime: `confirmation=user_required` when the leaf

Contract/Safety (or remaining `runtime_gate` annotate) requires a user gate

(for example `confirm_delete`, `typed_yes`, `confirm_dangerous`).

3. **Parameter facts** are declared on the leaf (`contract.ParamDecl` /

`Contract.Parameters` / FlagSpec). Do not reintroduce HintFile or

`RegisterSchemaHints` overlays.

### Authoring

For every curated tool:

1. Declare safety/interface/parameters/selection on the owning leaf

(`DeclareLeafMetadata` / `Shortcut.Contract` / `contract.ParamDecl`) and product routing

via `ProductDecl` when needed.

2. Run `make generate-schema` (param aliases + assembly determinism). Do not

create or commit `schema_catalog/` or Schema meta-index fixtures.

### Pull live MCP descriptions (personal token)

Schema delivery no longer embeds a pinned MCP JSON. Prefer live Schema from a

logged-in personal session when reviewing interface facts before declaring them

on the leaf:

```bash

dws auth status # token_valid should be true

dws schema <mcp-canonical> --jq '{canonical_path,interface_ref,parameters}' -f json

# or CLI path: dws schema --cli-path "drive copy" --jq '{canonical_path,interface_ref,parameters}' -f json

```

Resolve MCP identity via declared `interface_ref` when CLI canonical ≠ MCP path

(example: CLI `drive.copy_document` → live `doc.copy_document`). On pull

failure, fall back to Skill + Cobra Help, and record evidence

(for example `live-dws-schema:<path>#FAILED`). Never print or commit tokens.

`make fetch-mcp-metadata` writes an optional diagnostic dump under `artifacts/`

only — do not commit it as a Schema pin.

Precedence when sources disagree: **Runtime/Cobra / leaf Contract > live MCP >

Skill (evidence only)**.

### Parallel product agents

Split work by product groups. Each agent must:

- Read Skill, Cobra/`--help`, Runtime confirmation sites, and live

`dws schema <leaf> --compact` for its tools. Mapping/interface/provenance

audits may query the full leaf only through a narrow `--jq` / `--fields`

projection; do not load an entire full leaf into Agent context.

- Hand-write selection prose and leaf Contract / ProductDecl declarations;

forbid wholesale JSON merges from review dumps.

- Edit only its product’s leaf declarations (and `ProductDecl` when needed).

- **Never** `git checkout` unrelated product files to “clean scope”.

### Regenerate and gates

```bash

make generate-schema

./scripts/policy/check-runtime-confirmation-truth.sh

go test ./internal/app -run '^TestSheetFinalSchemaConfirmationMatchesRuntimeGuards$' -count=1

```

`check-runtime-confirmation-truth.sh` compares live ContractFinal.Safety with the assembled ToolSpec `confirmation=user_required` and probes the runtime gate.

`schema_hints/` must stay absent.

Example rules (fail generation otherwise):

- At most two examples per tool; no `--yes` in stored examples.

- Examples must match live Cobra argv (path, flags, required groups).

- No shell comments in examples.

After generation, spot-check Catalog: selection and safety/interface

provenance are `contract_final` from ProductDecl / leaf declarations

(`user_required` must match Runtime confirmation gates).

`make generate-schema` refreshes `param_aliases_generated.go` and runs

assembly determinism (`check-schema-assembly.sh`). It does not rewrite a

committed Catalog as delivery authority — runtime reassembles from

declarations. Byte guards fail if generation mutates parameter-concept

inputs; policy fails if the retired `schema_command_registry/` reappears.

Selection prose may choose a more or less restrictive recommendation. It cannot

create a Cobra command or flag, change parameter facts, invent an

RPC/interface, alter safety metadata, or bypass command completeness. Examples

must use an executable primary/alias path and flags accepted by the live Cobra

command; never add `--yes` to stored examples.

Every example is always checked against its real `BoundCommand`: exact path,

accepted flags, Cobra required flags/positionals, and the effective

`require_one_of`, `require_together`, and `mutually_exclusive` constraints must

all pass before execution eligibility is considered. A missing required value,

constraint failure, runtime error, or MCP resolution error is a contract bug;

none is a valid reason to skip an example.

Example execution defaults to contract validation only. Runtime execution is

opt-in: an example enters `dry_run` only when its final `ToolSpec` publishes an

explicit reviewed dry-run capability. The test never injects `--yes`, and

`risk`/`confirmation` values do not manufacture preview support. A narrow

runtime precondition that cannot be derived from the typed contract may use an

exact zero-based `example_dispositions` entry with `mode=contract_only`,

`reviewed=true`, one of the schema-enumerated reason codes, and a concrete

non-empty reason. Such a disposition may only narrow an explicit dry-run

capability; it cannot turn an ordinary contract-only example into a skip.

Duplicate, missing, and out-of-range indexes fail validation. Never catch a

dry-run failure and dynamically downgrade it to `contract_only`.

Normal Go tests run the exhaustive contract gate. Run

`make test-schema-agent-examples` to additionally execute the eligible subset

through the real Cobra `--dry-run` path with isolated HOME and blocked proxies.

The test reports stable `total`, `contract`, `dry_run`, `contract_only`,

`reviewed_manual`, and per-reason counts; changing those counts requires a

review of the corresponding typed dry-run capability or manual disposition.

This target is also part of `make policy`.

Treat every tool `use_when` entry as a reviewed positive selection scenario

whose expected result is that tool's canonical path, and every `avoid_when`

entry as a reviewed negative scenario that must not choose that tool. The

deterministic gate derives a typed evaluation fixture from these same fields;

it requires exact tool coverage, a real runnable `BoundCommandRegistry`

primary command, at least one positive and negative assertion per tool, and no

literal contradictory expectations. It does not claim that string matching

proves natural-language understanding.

Semantic selection is an explicit opt-in live-model check. Run the smoke set

(one positive and one negative scenario per product) with

`DWS_AGENT_SELECTION_LIVE=1 ARK_API_KEY=... ARK_BASE_URL=... ARK_MODEL=... go test ./internal/app -run TestAgentSelectionArkLive -count=1`.

Add `DWS_AGENT_SELECTION_FULL=1` to evaluate every committed tool scenario, or

set `DWS_AGENT_SELECTION_CASES` to comma-separated fixture case IDs. Normal CI

never calls a model; its blockers remain the reproducible fixture, binding,

example, provenance, and final-delivery facts.

The live evaluator sends only case IDs/scenarios plus one same-product

candidate table; expected/forbidden assertions stay local and must never be

included in the model prompt. Built-in Ark HTTPS bases are allowlisted. A

different HTTPS provider requires its exact base in

`DWS_AGENT_SELECTION_ALLOWED_BASE_URLS`; plaintext HTTP is accepted only for a

loopback test server so API credentials are never sent to an arbitrary clear

text endpoint.

## Safety metadata

Parameter and safety resolution is mostly source-precedence based and

value-neutral: do not choose a winner because one value looks stricter. A

higher-priority reviewed metadata/explicit source may intentionally raise or

lower description, mapping, `effect`, `risk`, `confirmation`, or `idempotency`.

Preserve all candidates and the selected source in provenance, and fail

same-precedence conflicts rather than silently merging them.

`required` is the exception. Cobra `MarkFlagRequired` is a hard floor: the

final Agent projection must keep `required=true` and cannot be lowered by a

lower-precedence source. A higher-precedence declaration may still raise an

optional flag to required. `cli_required` continues to mirror the executable

Cobra marker.

For command-level description: **declare required, delivery Long may win**.

`ContractDecl.Description` is mandatory at construction (declaration evidence).

Catalog delivery prefers Cobra Long when present (provenance `cobra_help`,

resolution `cobra_help_preferred`); without Long, the declared Description is

delivered as `contract_final`. Title keeps declared ContractDecl /

ContractFinal first, then Cobra Short, then MCP metadata. This is one authority

chain with an explicit delivery preference — not two competing sources.

Generic RPC prose may remain an unselected provenance candidate (and

parameter-level `interface_description`); it must not overwrite a specialized

leaf's title or description.

For every delivered `ToolSpec` and `ParameterSpec` field, the provenance

winner value must exactly equal the delivered value. Checking only source,

count, presence, or hash is not a sufficient final-delivery invariant.

The same resolved `ToolSpec` must drive every projection. The full leaf payload

must equal the corresponding tool in `schema --all` and the full Catalog tool.

Overview/product/group summaries and Catalog summaries must equal

`ToolSpec.ToSummaryPayload()`. An alias lookup may change only the view fields

`cli_path` and `is_alias`; it must not re-resolve or mutate the command

contract.

This build-time rule is distinct from runtime drift handling. If shipped Help

and leaf Schema disagree, pass only flags accepted by Cobra. For conflicting

safety information, do not silently take the less restrictive behavior: use

the safer interpretation or stop and report the contract drift.

Do not infer one safety field from another. In particular, `effect=destructive`

or `risk=high` does not mechanically rewrite `confirmation`; the final

precedence winner for each field is authoritative. When

`confirmation=user_required`, obtain confirmation before adding `--yes`.

Keep CLI confirmation behavior and Schema metadata consistent, and add a

semantic regression test through the final embedded loader/query delivery

path; a generator unit test or JSON count alone is insufficient.

## Unified result Schema and performance

The unified runtime envelope and the per-command Schema result declaration are

related but distinct contracts:

- Runtime owns the outer machine envelope (`ok`, `outcome`, `data`, `error`,

`meta`) and derives it through `internal/output`. Business commands return a

`CommandResult`; they must not hand-author the outer JSON shape.

- A leaf `Contract.Result` / `contract.ResultSpec` describes the reviewed

business value inside `data`. It may declare `outcomes`, `data_schema`, and

`sensitive_paths`. `Contract.Pagination` is a separate command capability

because pagination is emitted under envelope `meta`, not inside `data`.

- `outcomes` is the set of results a command may produce; it is not the outcome

of the current invocation. `data_schema` is a JSON Schema object for business

data and must not duplicate the framework envelope.

- Result declarations are delivered in the full leaf and in the reviewed

`--compact` Agent projection. Compact retains the normalized `result` object

verbatim but still omits provenance, interface bindings, and other audit-only

fields. Product/group summaries remain navigation views and need not repeat

every leaf Result. When an Agent needs return-shape facts, query the compact

leaf directly; do not load the whole full Catalog.

- A missing `result` means “no reviewed return-value declaration is published

for this leaf.” It does **not** prove that the runtime is legacy, and it must

not be filled by inference from examples, MCP samples, or previous command

output. Runtime rollout remains an internal per-command fact.

- The public contract has no `contract_version`, no `--output-contract`, and no

Agent-selectable protocol alias. Agents continue to request machine output

with `--format json`; migrated commands use the unified result directly and

unmigrated commands retain their current legacy output.

- Existing `dev` / `devapp` pilot coverage is gradual. Active reviewed

`devapp` shortcuts are gated on a non-empty Result declaration, while `dev`

currently has representative Result coverage. Do not describe that as

repository-wide coverage. Any newly activated Agent-visible command should

add and test its Result declaration; the remaining pilot gaps should shrink,

not expand.

The compact/full leaf `result` object has one stable shape:

```json

{

"result": {

"outcomes": ["success", "pending", "partial_failure", "failure"],

"data_schema": {

"type": "object",

"properties": {

"items": {

"type": "array",

"items": {

"type": "object",

"properties": {

"id": {"type": "string", "description": "Stable resource ID"},

"name": {"type": "string", "description": "Display name"}

}

}

}

}

},

"sensitive_paths": ["credential.secret"]

},

"pagination": {

"kind": "cursor",

"cursor_parameter": "cursor",

"meta_path": "meta.pagination",

"endpoint_exhausted_path": "meta.pagination.endpoint_exhausted",

"next_token_path": "meta.pagination.next_token"

}

}

```

Field rules:

| Field | Required | Contract |

|---|---|---|

| `outcomes` | yes | Non-empty unique subset of `success`, `pending`, `partial_failure`, `failure`; normalization publishes canonical order. |

| `data_schema` | yes | One recursive JSON Schema **object** describing only the runtime envelope's `data` value. Every named `properties` child must have a non-empty `description`. It must not duplicate `ok`, `outcome`, `error`, or `meta`. |

| `sensitive_paths` | no | Unique safe dot paths relative to `data`; renderers/redaction consumers must not treat them as shell/JQ expressions. |

Optional members are omitted, never emitted as `null`. A leaf without a

reviewed Result omits the entire `result` key. Compact must preserve the same

normalized Result value as the full leaf; it must not summarize, infer, rename,

or independently rebuild any Result field. Product/group summaries do not

aggregate child Result objects.

`pagination` is a sibling of `result`, not a child. It declares the canonical

CLI cursor parameter and the fixed framework paths under `meta.pagination`.

Product response fields used to derive that metadata remain mapper internals;

they are not part of `result.data_schema`. Do not execute a second request to

derive pagination metadata.

Invalid result declarations fail closed during normalization: unknown or

duplicate outcomes, a non-object/multiple `data_schema`, unsafe or duplicate

sensitive paths, unsupported pagination kinds, attempts to override framework

meta paths, and an invalid cursor parameter must be rejected rather than

silently removed.

Full-leaf wire round trips must

preserve the normalized Result exactly. Do not commit generated Schema JSON as

evidence; tests construct contracts in Go and runtime/CI assemble the Catalog

from declarations.

### Performance model and rules

- Catalog construction is declaration-driven and cached through the existing

lazy `sync.Once` delivery path. Do not reassemble or reopen annotations per

command invocation, per leaf lookup, or per renderer.

- Normalizing one Result declaration is linear in the size of that declaration.

Full `schema --all` is linear in tools + parameters + Result schema bytes and

is an audit/compatibility export, not the normal Agent discovery path.

Overview → compact product/group → compact leaf remains the normal route;

only the final leaf carries its Result declaration.

- Constructing a `CommandResult` defensively clones result data and validates

invariants; rendering is buffer-first and then writes once. Both CPU cost and

transient memory are O(payload size), with roughly one additional in-memory

rendered copy. This buys immutability and prevents partial JSON leakage, but

it is not free.

- Large list/search commands must use bounded pages and publish continuation

facts. The current emitter buffers one command result/page before publishing;

pagination is the memory bound. Continuous event streams are a separate,

command-specific protocol and are not described by `ResultSpec`.

- A `dual_validate` command must execute the business request exactly once,

validate a shadow unified result, and preserve legacy bytes. Never obtain

validation by issuing a second network or write request.

- Filters and alternate formats are render-time work over the same in-memory

result. They must not rerun the business operation or rebuild Schema.

- Performance changes must preserve the one-result, buffer-first, fail-closed,

and atomic `--output` guarantees. Do not trade correctness for a microbenchmark

improvement. For a material hot-path change, benchmark representative small

and page-sized payloads and report allocations/bytes as well as latency.

## Current Schema boundaries

- `schema list` remains a progressive overview. `schema --all` is the stable

full-export contract: every final `SchemaIndex` tool must contain its

complete leaf parameters, constraints, and safety semantics, including an empty

`parameters` object for commands without flags. Keep it suitable for the #602

compatibility baseline and fail rather than silently emitting a partial

export.

- `schema --all` is not normal command discovery. Use overview -> compact

product/group -> compact leaf for routine Agent work. `--compact` is the

reviewed positive-field allowlist for Agent context: new full/audit fields

must not appear there until explicitly reviewed. A compact full export is not

a complete compatibility baseline.

- `dws <path> --help` defines whether Cobra exposes a path and which flags the

executable accepts. A compact leaf defines Agent selection, CLI parameters,

constraints, safety/confirmation semantics, and any reviewed `result`

contract. Full leaf fields such as `property`, `interface_ref`, and

provenance are audit facts. A conflict is contract drift, not permission to

guess.

- Schema and Help describe commands; neither returns DingTalk business data.

After discovery, execute the real read/search/list command to obtain data.