Docs: verify and land in the API reference, audit log and limits (#115)

#111 documented Fix failing checks and Land when approved on the Tasks
page. The API reference had no entry for changing a task's options, nor
fix_checks and land on starting a task; the audit log lacked
task.options; and Limits had no row for fix runs.


Claude-Session: https://claude.ai/code/session_016q5wwBFck8JHq14gHUM2CL

Co-authored-by: Claude <noreply@anthropic.com>

Canberk Demirci authored 13 days ago· GitHub committed 13 days agosigned1 parent 63db7ddcommit 33e1ecf3507127a7d0592a269414456e37718b2dBrowse files

3 files changed+13−2

modifiedapps/diffinery/docs/reference/limits.md+1−0View file

modifiedapps/diffinery/docs/security/audit-log.md+2−1View file

modifiedapps/diffinery/src/docs/api-meta.ts+10−1View file

		@@ -236,6 +236,7 @@
236	236	\| Installing the runtime \| 10 minutes \| Installing Claude Code or Codex in the sandbox. \|
237	237	\| Goal and follow-up length \| 20,000 characters \| ``422 `goal` is longer than 20000 characters`` (or `body` for a follow-up). \|
238	238	\| Plan length \| 20,000 characters \| A [plan-first](/docs/agents/tasks#plan-first) run's plan is cut there and ends with `… (plan cut at 20000 characters)`. \|
	239	+\| Fix runs for failing checks \| 1 per commit, 3 per task \| With Fix failing checks, a fix run gets the last 80 log lines of each failing check. After 3, the task's conversation says the checks still fail. See [Verify and land](/docs/agents/tasks#verify-and-land). \|
239	240	\| Attempts per task \| 1 to 4 \| ``422 `attempts` must be a whole number from 1 to 4``. Each attempt counts toward how many tasks run at once. A task on a pull request's branch runs one. See [Best of N](/docs/agents/tasks#best-of-n). \|
240	241	\| Custom command length \| 2,000 characters \| ``422 `command` is longer than 2000 characters``. \|
241	242	\| Transcript \| 20,000 lines per run, 32 KiB per line \| Later output lines of a run aren't stored (Diffinery's own notes still are); a longer line is cut. \|

		@@ -74,9 +74,10 @@
74	74
75	75	\| Action \| Recorded when \| Target \| Detail \|
76	76	\|---\|---\|---\|---\|
77		-\| `task.start` \| Someone starts an [agent task](/docs/agents/tasks) \| `owner/repo#<task number>` \| `agent`, `runtime`; `provider` and `model` when it goes through OpenRouter; `plan_first` when it plans first; `attempts` when it runs more than one \|
	77	+\| `task.start` \| Someone starts an [agent task](/docs/agents/tasks) \| `owner/repo#<task number>` \| `agent`, `runtime`; `provider` and `model` when it goes through OpenRouter; `plan_first` when it plans first; `attempts` when it runs more than one; `fix_checks` and `land` \|
78	78	\| `task.message`, `task.retry` \| The person who started a task sends a follow-up or retries it \| `owner/repo#<task number>` \| none \|
79	79	\| `task.plan_approve` \| The person who started a [plan-first](/docs/agents/tasks#plan-first) task approves its plan \| `owner/repo#<task number>` \| none \|
	80	+\| `task.options` \| The person who started a task changes Fix failing checks or Land when approved \| `owner/repo#<task number>` \| `fix_checks`, `land` \|
80	81	\| `task.pick` \| The person who started a task with [attempts](/docs/agents/tasks#best-of-n) picks one \| `owner/repo#<task number>` \| `attempt` \|
81	82	\| `task.plan_split` \| The person who started a plan-first task hands its plan to their coordinator to split \| `owner/repo#<task number>` \| `post`, `coordinator_task` \|
82	83	\| `task.stop` \| Someone stops a task (its starter, its agent or a repository admin) \| `owner/repo#<task number>` \| none \|

		@@ -64,6 +64,7 @@
64	64	"POST /repos/{owner}/{repo}/diffinery/tasks/{number}/retry": { scope: "write", sessionOnly: true },
65	65	"POST /repos/{owner}/{repo}/diffinery/tasks/{number}/plan/approve": { scope: "write", sessionOnly: true },
66	66	"POST /repos/{owner}/{repo}/diffinery/tasks/{number}/attempts/{attempt}/pick": { scope: "write", sessionOnly: true },
	67	+ "PATCH /repos/{owner}/{repo}/diffinery/tasks/{number}": { scope: "write", sessionOnly: true },
67	68	"POST /repos/{owner}/{repo}/diffinery/tasks/{number}/plan/split": { scope: "write", sessionOnly: true },
68	69	"POST /repos/{owner}/{repo}/diffinery/project/posts": { scope: "write", sessionOnly: true },
69	70	"PUT /repos/{owner}/{repo}/diffinery/project/memory": { scope: "write", sessionOnly: true },
		@@ -1448,6 +1449,8 @@
1448	1449	base: ["string", "Branch to start from (default: the default branch)."],
1449	1450	plan_first: ["boolean", "`true` to plan in a read-only sandbox before building, `false` to build at once. Left out, the project's default; a project that requires plans ignores `false`. See /docs/agents/tasks#plan-first."],
1450	1451	attempts: ["integer", "1 (default) to 4: run the first build as that many attempts side by side, then pick one (422 above 1 for a task on a pull request's branch). See /docs/agents/tasks#best-of-n."],
	1452	+ fix_checks: ["boolean", "Start a fix run when the pull request's checks fail (default `true`, `false` for a task on a pull request's branch). See /docs/agents/tasks#verify-and-land."],
	1453	+ land: ["boolean", "Turn on auto-merge for its pull request as the task's agent, so it merges once approved and checks pass (default `false`)."],
1451	1454	command: ["string", "For `custom`: the shell command to run."],
1452	1455	},
1453	1456	},
		@@ -1518,9 +1521,15 @@
1518	1521	},
1519	1522	"GET /repos/{owner}/{repo}/diffinery/tasks/{number}": {
1520	1523	summary: "Get an agent task",
1521		- description: "The task, its runs and its pull request. Needs write access. A plan-first task also has `plan_state` (`planning`, `waiting`, `approved` or `split`) and `plan`; a task split from a plan has `parent_task`. A task with more than one attempt has `pick_state` (`running`, `waiting` or `picked`) and `picked_attempt`, and each run its `attempt`.",
	1524	+ description: "The task, its runs and its pull request. Needs write access. A plan-first task also has `plan_state` (`planning`, `waiting`, `approved` or `split`) and `plan`; a task split from a plan has `parent_task`. A task with more than one attempt has `pick_state` (`running`, `waiting` or `picked`) and `picked_attempt`, and each run its `attempt`. Every task has `fix_checks`, `check_fixes` (fix runs started so far) and `land`.",
1522	1525	access: "write",
1523	1526	},
	1527	+ "PATCH /repos/{owner}/{repo}/diffinery/tasks/{number}": {
	1528	+ summary: "Change a task's options",
	1529	+ description: "From a browser session only, by the person who started the task. `fix_checks` starts a fix run when its pull request's checks fail (one per commit, at most 3 per task); turning `land` on turns on auto-merge for an open pull request as the task's agent, under the usual rules for agents. 422 when a value isn't `true` or `false`; 409 `only agent tasks have these options` for an agent review. Audited as `task.options`. See /docs/agents/tasks#verify-and-land.",
	1530	+ access: "write",
	1531	+ body: { fix_checks: ["boolean", "Fix failing checks."], land: ["boolean", "Land when approved."] },
	1532	+ },
1524	1533	"GET /repos/{owner}/{repo}/diffinery/tasks/{number}/attempts": {
1525	1534	summary: "Compare a task's attempts",
1526	1535	description: "Needs write access. One entry per attempt of a best-of-N task: `attempt`, `run`, `state`, `error`, `branch`, `head_sha`, `changes` (`files`, `additions`, `deletions`), `checks` and `failing_checks` on its branch, `model_requests`, `tokens`, `summary` (its last message) and `compare_url`. See /docs/agents/tasks#best-of-n.",

codician/diffinerypublic

Docs: verify and land in the API reference, audit log and limits (#115)