docs(agentic-teams): document the new resources, and make the webhook reachable

Five resources shipped with no documentation and one documented lie:
docs/inference-tasks.md still told people `mcpctl get tasks` lists the
inference queue. Work items own that name now.

Adds docs/epics.md (the Epic -> EpicTask -> Task hierarchy, the state machine,
risk-scaled review gates, the accept-merges gate, and reconciliation),
docs/gitproviders.md (forge registration, discovery/import, merge-on-accept,
post-merge reopen) and docs/agent-authority.md (the three run modes, and
plainly which two are not implemented).

Two things found while writing them, both fixed rather than filed:

- `webhookSecretKey` was read by the webhook route but writable from NOWHERE
  -- absent from the create schema, update schema, service, CLI and apply
  spec. Since the endpoint fails closed on a null key, post-merge CI failures
  could never reopen their task; the board would keep claiming `merged` for
  work that broke the build. Adds --webhook-secret-key, the schema fields and
  the apply key, with tests covering persist / omit / explicit-null /
  reject-empty. Omission deliberately does not clear the column, so an
  unrelated edit cannot silently disarm the webhook.

- src/cli/src/commands/create.ts contained a literal NUL byte inside a string
  literal (a binary-file check written with the raw character rather than an escape). Identical behaviour, but it made the whole file read as
  binary, so `grep -I` skipped it entirely and 1120 lines of CLI were
  invisible to every text search. Replaced with the escape.

The Epic write path (criteria/status/tradeoffs) is API-only -- documented as
such rather than papered over, and filed as task 180.

Full suite 2612 green; lint at baseline 794/77.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4wNHWf7xSwnZCWpJcyv9p
This commit is contained in:
Michal
2026-08-16 00:14:58 +01:00
parent 2a85447fac
commit 6d38953a96
14 changed files with 587 additions and 6 deletions

View File

@@ -3485,6 +3485,17 @@
"status": "pending",
"subtasks": [],
"updatedAt": "2026-08-15T22:54:36.185Z"
},
{
"id": 180,
"title": "CLI for the Epic write path (status, criteria, tradeoffs)",
"description": "Marking a done-criterion met, setting Epic status and recording tradeoffs are POST /api/v1/epics/:id/{criteria,status,tradeoffs}. describe epic READS all of it — completeness bar, unmet criteria, reconciliation — but the CLI cannot WRITE any of it, so completeness is permanently 0% for anyone not driving the API by hand. That makes the Epic layer read-only in practice and the reconciliation feature unusable, since it exists to contrast claimed vs delivered and nothing can ever claim.",
"details": "Add an `epics` command group mirroring `tasks`:\n mcpctl epics criterion <epic> <id> --met|--unmet [--note]\n mcpctl epics status <epic> <open|delivered|delivered_with_tradeoffs|cancelled> [--note]\n mcpctl epics tradeoff <epic> --criterion <id> --why <text>\nRoutes already exist and are RBAC-mapped to edit:epics (url-permission.ts). Closing an Epic with unmet criteria must keep going through the tradeoffs path — the CLI must not offer a way to mark it delivered while criteria are unmet.\nPer the project rule, these are project-scoped commands: keep them out of the root --help (see task 174).\nReferenced from docs/epics.md as \"task 180\" — update that note when this lands.",
"testStrategy": "Unit: criterion --met flips only the named id and leaves others untouched; status delivered with unmet criteria is refused and names them; tradeoff records the reason. Verify describe epic completeness moves off 0% after a criterion is marked, and that reconciliation then has something to contrast.",
"status": "pending",
"priority": "medium",
"dependencies": [],
"subtasks": []
}
],
"metadata": {
@@ -3497,4 +3508,4 @@
]
}
}
}
}