From c8fc4b2845ad9d61ae856999b15aa39e61f8402b Mon Sep 17 00:00:00 2001 From: Viktor Shcherbakov Date: Thu, 7 May 2026 21:47:31 +0200 Subject: [PATCH] =?UTF-8?q?docs(design):=20retire=20legacy=20{accepted}=20?= =?UTF-8?q?envelope=20wording=20from=20=C2=A73.4=20(#40)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DESIGN.md §3.4 still described `submit_result` as returning `{ accepted: true } | { accepted: false, errors: [...] }`. PR #38 landed the canonical `{ ok, errors?, data? }` envelope as the single shape for every agent endpoint (docs/contracts.md §4 + §4.4); the `grep:no-accepted-key` gate enforces the absence of the legacy form in source / test files. The two docs disagreed. Update §3.4 to point at docs/contracts.md §4 / §4.4 as authoritative and call out the legacy shape as retired. Drop the "will be reconciled" note in contracts.md §4.4 — that's what this PR does. Closes #40. Co-Authored-By: Claude Opus 4.7 (1M context) --- DESIGN.md | 2 +- docs/contracts.md | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 5b984d4..5bb74a3 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -298,7 +298,7 @@ No retries on schema-validation failure for MVP — the run fails. Three static tools, fixed for the lifetime of the connection: - `pull_task({ run_id?: string })` → `{ instructions, input, output_schema, claim }` or `null`. `run_id` is optional; when supplied, the claim is restricted to ready subtasks of that run (issue #75 — drives a single run end-to-end without picking up unrelated queued work). Forwards to `GET /work/next?run_id=…`. -- `submit_result(claim, result, notes?)` → `{ accepted: true } | { accepted: false, errors: [...] }`. `notes` is an optional free-text reflection persisted in the audit log alongside the structured `result`. +- `submit_result(claim, result, notes?)` → the canonical response envelope `{ ok, errors?, data? }` per `docs/contracts.md` §4. Validation failures use the `validation::` token form per §4.4. `notes` is an optional free-text reflection persisted in the audit log alongside the structured `result`. (The legacy `{ accepted: true | false, errors }` shape this section described pre-#38 has been retired — every agent endpoint uses the single envelope; `grep:no-accepted-key` enforces the absence in CI.) - `task_tool(subcommand: string, claim: string, args?: object)` → `string | object` — universal dispatcher. Invokes a publisher-declared subcommand for a claim (see §3.1). `claim` is required (no session-based fallback in MVP). Static description (visible to the host's tool catalog): > *Invoke a subcommand for the current claim. The subtask `instructions` will tell you which subcommands to use and when; `task_tool('', '', {...})` invokes one. The `claim` value is what `pull_task` returned in its `claim` field.* diff --git a/docs/contracts.md b/docs/contracts.md index 7697e92..8158869 100644 --- a/docs/contracts.md +++ b/docs/contracts.md @@ -241,9 +241,8 @@ There is no `{ "accepted": true, ... }` parallel envelope. The `grep:no-accepted-key` gate fails CI if `\baccepted:\s` appears in source or test files outside `_legacy/`. The gate covers TS/JS file extensions under `src/`, `packages/*/src/`, `apps/*/src/`, and the matching `test/` -trees. (DESIGN.md §3.4 mentions `{ accepted: true | false }` for the -old `submit_result` shape; that text is **superseded by this contract** -and will be reconciled when DESIGN.md is next revised.) +trees. (DESIGN.md §3.4 was reconciled in #40 — the `submit_result` +description there now points at this section as authoritative.) ---