@stablebaseline/sdk 0.6.3 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/openapi.json CHANGED
@@ -4287,7 +4287,7 @@
4287
4287
  },
4288
4288
  "strength": {
4289
4289
  "type": "number",
4290
- "description": "Optional 0..1 — how far the regenerated area may diverge from the original. Ignored by FLUX Fill (which balances via the prompt); leave unset unless using a non-Fill inpaint model."
4290
+ "description": "Optional 0..1: how far the regenerated area may diverge from the original. The editing model may balance this from the prompt instead, so leave it unset unless you need it."
4291
4291
  }
4292
4292
  },
4293
4293
  "required": [
@@ -5798,12 +5798,9 @@
5798
5798
  "documentId": {
5799
5799
  "type": "string"
5800
5800
  },
5801
- "libavoidRoute": {
5802
- "type": [
5803
- "boolean",
5804
- "string"
5805
- ],
5806
- "description": "Optional, used by the design worker's connector pass: route the batch's BOUND arrows and lines with the obstacle-aware libavoid router against the full scene before placing them (true), or 'force' to also discard hand-authored elbow points. Omit for the default as-authored routing. Declared because the tool rejects undeclared parameters and every builder-drawn arrow was failing on it (2026-09-09)."
5801
+ "rerouteConnectors": {
5802
+ "type": "boolean",
5803
+ "description": "Optional. Arrows and lines bound to a shape at BOTH ends (start.id and end.id) are always routed around the other shapes on the board unless you give them points. true: ignore the points you gave for such connectors and route them too. Omit to keep the points you supply."
5807
5804
  },
5808
5805
  "shapes": {
5809
5806
  "type": "array",
@@ -9048,7 +9045,7 @@
9048
9045
  "/tools/listImprovements": {
9049
9046
  "post": {
9050
9047
  "summary": "listImprovements",
9051
- "description": "List AND grep improvements in a project. `query` searches the title, friendlyId and problem statement, not just the title (substring by default; set isRegex:true for a regular expression, caseSensitive:true for exact case). Supports filtering by status, type, priority. For ranked semantic + text search use searchImprovements.",
9048
+ "description": "List AND grep improvements in a project. `query` searches the title, friendlyId and problem statement, not just the title (substring by default; set isRegex:true for a regular expression, caseSensitive:true for exact case). Supports filtering by status, type, priority, and by parentItemId for an item's children in the work hierarchy (an epic's stories, say). For ranked semantic + text search use searchImprovements. Every item carries its versionTimestamp, ready for updateImprovement, so one call here supplies the tokens for a whole batch of updates (fields [\"id\", \"friendlyId\", \"versionTimestamp\"] returns just those), and its parentItem: the item it belongs to in the work hierarchy ({ id, friendlyId, title, type, status, isTask }, or null).",
9052
9049
  "operationId": "listImprovements",
9053
9050
  "tags": [
9054
9051
  "improvements"
@@ -9063,13 +9060,18 @@
9063
9060
  "projectId": {
9064
9061
  "type": "string"
9065
9062
  },
9063
+ "parentItemId": {
9064
+ "type": "string",
9065
+ "maxLength": 64,
9066
+ "description": "Only the children of this item in the work hierarchy (its UUID or friendly id, such as IMP-12), whatever plan or phase they are in. \"none\" lists only the items with no parent. The work hierarchy is not the plan outline nesting (setPlanItemParent)."
9067
+ },
9066
9068
  "status": {
9067
9069
  "type": "string",
9068
9070
  "description": "Filter: captured, triaging, shaped, approved, ready_for_agent, in_progress, ready_for_review, in_review, blocked, done, rejected, deferred."
9069
9071
  },
9070
9072
  "type": {
9071
9073
  "type": "string",
9072
- "description": "Filter: feature, bug, tech_debt, architecture_gap, documentation_gap, risk, enhancement, task. Tasks (is_task=true) always have type='task'."
9074
+ "description": "Filter by type: feature, enhancement, bug, tech_debt, architecture_gap, documentation_gap, risk, epic, user_story, requirement, test_case, spike, task. Tasks (is_task=true) always have type='task'."
9073
9075
  },
9074
9076
  "priority": {
9075
9077
  "type": "string",
@@ -9132,7 +9134,7 @@
9132
9134
  "items": {
9133
9135
  "type": "string"
9134
9136
  },
9135
- "description": "Field projection. Valid fields: id, friendly_id, friendlyId, title, type, status, priority, source, category_id, categoryId, created_at, createdAt, updated_at, updatedAt, href."
9137
+ "description": "Field projection. Valid fields: id, friendly_id, friendlyId, title, type, status, priority, source, category_id, categoryId, parent_item_id, parentItemId, parentItem, created_at, createdAt, updated_at, updatedAt, versionTimestamp, href."
9136
9138
  }
9137
9139
  },
9138
9140
  "required": [
@@ -9220,7 +9222,7 @@
9220
9222
  "/tools/getImprovement": {
9221
9223
  "post": {
9222
9224
  "summary": "getImprovement",
9223
- "description": "Get full details for an improvement item including evidence, activity log, compliance context, and the `checklist` array (each item: id, text, due_date, completed_at, plus server-stamped attribution). Returns versionTimestamp — pass it to updateImprovement for optimistic locking. (For tasks specifically, use getTask + updateTask which are symmetric aliases.)",
9225
+ "description": "Get full details for an improvement item including evidence, activity log, compliance context, and the `checklist` array (each item: id, text, due_date, completed_at, plus server-stamped attribution). Returns versionTimestamp: pass it to updateImprovement for optimistic locking. (For tasks specifically, use getTask + updateTask which are symmetric aliases.) Also returns the work hierarchy: parentItem (the item this one belongs to, such as its epic or story: { id, friendlyId, title, type, status, isTask }, or null), children (the items that belong to it, in status order then by id, at most 200: each with ownerId, ownerTeamId and percentComplete) and childProgress { total, done, closed } over every child (closed counts done, rejected and deferred). Set a parent with parentItemId on updateImprovement or updateTask.",
9224
9226
  "operationId": "getImprovement",
9225
9227
  "tags": [
9226
9228
  "improvements"
@@ -9326,7 +9328,7 @@
9326
9328
  "/tools/createImprovement": {
9327
9329
  "post": {
9328
9330
  "summary": "createImprovement",
9329
- "description": "Create an improvement item in a project. Requires projectId and title. Auto-assigns friendly ID. Accepts every field updateImprovement accepts, so an item can be created complete in one call rather than create-then-update.",
9331
+ "description": "Create an improvement item in a project. Requires projectId and title. Auto-assigns friendly ID. Accepts every field updateImprovement accepts, so an item can be created complete in one call rather than create-then-update. Pass parentItemId to create it under its epic or story in the work hierarchy. Pass `fields` (for example [\"id\", \"friendlyId\", \"versionTimestamp\"]) for a short answer instead of the whole improvement.",
9330
9332
  "operationId": "createImprovement",
9331
9333
  "tags": [
9332
9334
  "improvements"
@@ -9346,7 +9348,203 @@
9346
9348
  },
9347
9349
  "type": {
9348
9350
  "type": "string",
9349
- "description": "Type. Default: enhancement. Valid values: feature, bug, tech_debt, architecture_gap, documentation_gap, risk, enhancement, task. Despite the tool's name there is no 'improvement' value — pass it and it is accepted as an alias for 'enhancement', which is also the default. Setting type='task' makes the row a task (TAS- prefix); any other type makes it a non-task improvement (IMP- prefix)."
9351
+ "description": "Type. Default: enhancement. One of: feature (New capability for users); enhancement (An improvement to something that already exists); bug (Something that does not work as it should); tech_debt (Work that makes the system easier and safer to change); architecture_gap (A missing or weak part of the architecture); documentation_gap (Documentation that is missing or out of date); risk (Something that could go wrong, to track and reduce); epic (A large body of work, delivered through several stories, features or tasks); user_story (A need told from a user's view: as a role, I want a goal, so that a benefit); requirement (A condition or capability the solution must meet, stated so it can be verified); test_case (Steps that verify a requirement or story, each with its expected result); spike (Time-boxed research to answer a question before committing to the work); task (A unit of work in a plan). Despite the tool's name there is no 'improvement' value: pass it and it is accepted as an alias for 'enhancement', which is also the default. Setting type='task' makes the row a task; any other type makes it a non-task item. The id's prefix follows the type: epic EPIC-, user_story STY-, requirement REQ-, test_case TC-, spike SPK-, task TAS-; every other type IMP-. The number is shared by every type and never changes: a type change rewrites only the prefix (STY-30 becomes IMP-30), and the old id still resolves. Types with fields of their own (epic, user_story, requirement, test_case, spike) take them in details."
9352
+ },
9353
+ "details": {
9354
+ "type": "object",
9355
+ "description": "The type's own fields. On update they MERGE key by key: keys you leave out are kept and null removes one. epic: success_measures. user_story: as_a, i_want, so_that (read as 'As a <as_a>, I want <i_want>, so that <so_that>') and story_points. requirement: statement ('The system shall...'), requirement_kind, rationale, source, verification_method. test_case: preconditions, test_steps (ordered { action, expected }), test_data, last_result, last_run_on. spike: question, timebox, findings. An item keeps its details when its type changes.",
9356
+ "properties": {
9357
+ "success_measures": {
9358
+ "type": [
9359
+ "string",
9360
+ "null"
9361
+ ],
9362
+ "maxLength": 20000,
9363
+ "description": "Success Measures (How will you know this epic delivered its outcome?)"
9364
+ },
9365
+ "as_a": {
9366
+ "type": [
9367
+ "string",
9368
+ "null"
9369
+ ],
9370
+ "maxLength": 500,
9371
+ "description": "As a (role or persona)"
9372
+ },
9373
+ "i_want": {
9374
+ "type": [
9375
+ "string",
9376
+ "null"
9377
+ ],
9378
+ "maxLength": 500,
9379
+ "description": "I want (what they want to do)"
9380
+ },
9381
+ "so_that": {
9382
+ "type": [
9383
+ "string",
9384
+ "null"
9385
+ ],
9386
+ "maxLength": 500,
9387
+ "description": "So that (the benefit to them)"
9388
+ },
9389
+ "story_points": {
9390
+ "type": [
9391
+ "number",
9392
+ "null"
9393
+ ],
9394
+ "minimum": 0,
9395
+ "maximum": 1000,
9396
+ "description": "Story Points (e.g. 3)"
9397
+ },
9398
+ "statement": {
9399
+ "type": [
9400
+ "string",
9401
+ "null"
9402
+ ],
9403
+ "maxLength": 20000,
9404
+ "description": "Requirement (The system shall...)"
9405
+ },
9406
+ "requirement_kind": {
9407
+ "type": [
9408
+ "string",
9409
+ "null"
9410
+ ],
9411
+ "enum": [
9412
+ "functional",
9413
+ "non_functional",
9414
+ "interface",
9415
+ "data",
9416
+ "business_rule",
9417
+ "constraint",
9418
+ "compliance",
9419
+ null
9420
+ ],
9421
+ "description": "Kind"
9422
+ },
9423
+ "rationale": {
9424
+ "type": [
9425
+ "string",
9426
+ "null"
9427
+ ],
9428
+ "maxLength": 20000,
9429
+ "description": "Rationale (Why it is needed...)"
9430
+ },
9431
+ "source": {
9432
+ "type": [
9433
+ "string",
9434
+ "null"
9435
+ ],
9436
+ "maxLength": 500,
9437
+ "description": "Source (A stakeholder, regulation or document)"
9438
+ },
9439
+ "verification_method": {
9440
+ "type": [
9441
+ "string",
9442
+ "null"
9443
+ ],
9444
+ "enum": [
9445
+ "test",
9446
+ "inspection",
9447
+ "analysis",
9448
+ "demonstration",
9449
+ null
9450
+ ],
9451
+ "description": "Verified By"
9452
+ },
9453
+ "preconditions": {
9454
+ "type": [
9455
+ "string",
9456
+ "null"
9457
+ ],
9458
+ "maxLength": 20000,
9459
+ "description": "Preconditions (What must be true before the test starts...)"
9460
+ },
9461
+ "test_steps": {
9462
+ "type": [
9463
+ "array",
9464
+ "null"
9465
+ ],
9466
+ "maxItems": 200,
9467
+ "items": {
9468
+ "type": "object",
9469
+ "properties": {
9470
+ "id": {
9471
+ "type": "string",
9472
+ "maxLength": 64,
9473
+ "description": "Optional; minted if omitted. Echo it back on the steps you keep."
9474
+ },
9475
+ "action": {
9476
+ "type": "string",
9477
+ "maxLength": 4000,
9478
+ "description": "What the tester does."
9479
+ },
9480
+ "expected": {
9481
+ "type": "string",
9482
+ "maxLength": 4000,
9483
+ "description": "What should happen."
9484
+ }
9485
+ }
9486
+ },
9487
+ "description": "Test Steps, in order. The list you send REPLACES the stored one."
9488
+ },
9489
+ "test_data": {
9490
+ "type": [
9491
+ "string",
9492
+ "null"
9493
+ ],
9494
+ "maxLength": 20000,
9495
+ "description": "Test Data (Inputs, accounts or records the steps use...)"
9496
+ },
9497
+ "last_result": {
9498
+ "type": [
9499
+ "string",
9500
+ "null"
9501
+ ],
9502
+ "enum": [
9503
+ "not_run",
9504
+ "passed",
9505
+ "failed",
9506
+ "blocked",
9507
+ null
9508
+ ],
9509
+ "description": "Last Result"
9510
+ },
9511
+ "last_run_on": {
9512
+ "type": [
9513
+ "string",
9514
+ "null"
9515
+ ],
9516
+ "description": "Last Run, YYYY-MM-DD."
9517
+ },
9518
+ "question": {
9519
+ "type": [
9520
+ "string",
9521
+ "null"
9522
+ ],
9523
+ "maxLength": 20000,
9524
+ "description": "Question (What does this spike need to find out?)"
9525
+ },
9526
+ "timebox": {
9527
+ "type": [
9528
+ "string",
9529
+ "null"
9530
+ ],
9531
+ "maxLength": 500,
9532
+ "description": "Timebox (e.g. 3 days)"
9533
+ },
9534
+ "findings": {
9535
+ "type": [
9536
+ "string",
9537
+ "null"
9538
+ ],
9539
+ "maxLength": 20000,
9540
+ "description": "Findings (What was learned, and the recommendation...)"
9541
+ }
9542
+ }
9543
+ },
9544
+ "parentItemId": {
9545
+ "type": "string",
9546
+ "maxLength": 64,
9547
+ "description": "The work item this one belongs to in the work hierarchy: an epic for a story, a story for its tasks or test cases. Any item in the same project, in any plan or phase. Not the plan outline nesting, which setPlanItemParent sets. Give its UUID or friendly id (such as IMP-12 or TAS-3). Rules: the same project; no loops (an item cannot sit inside its own children); at most 5 levels, counting this item's own children."
9350
9548
  },
9351
9549
  "priority": {
9352
9550
  "type": "string",
@@ -9354,6 +9552,20 @@
9354
9552
  },
9355
9553
  "status": {
9356
9554
  "type": "string",
9555
+ "enum": [
9556
+ "captured",
9557
+ "triaging",
9558
+ "shaped",
9559
+ "approved",
9560
+ "ready_for_agent",
9561
+ "in_progress",
9562
+ "ready_for_review",
9563
+ "in_review",
9564
+ "blocked",
9565
+ "done",
9566
+ "rejected",
9567
+ "deferred"
9568
+ ],
9357
9569
  "description": "Initial status. Default: captured."
9358
9570
  },
9359
9571
  "source": {
@@ -9565,7 +9777,7 @@
9565
9777
  },
9566
9778
  "is_task": {
9567
9779
  "type": "boolean",
9568
- "description": "Mark as task. Default: false. Prefer setting type='task' instead — is_task is kept in sync from the type enum by a DB trigger, and rows with type='task' get the TAS- friendly_id prefix while all others get IMP-."
9780
+ "description": "Mark as task. Default: false. Prefer setting type='task' instead: is_task is kept in sync from the type by a DB trigger, and the friendly id's prefix follows the type too (see type)."
9569
9781
  },
9570
9782
  "description": {
9571
9783
  "type": "string"
@@ -9594,6 +9806,15 @@
9594
9806
  "metadata": {
9595
9807
  "type": "object",
9596
9808
  "description": "Free-form JSON stored alongside the item. On updateImprovement this MERGES rather than replaces."
9809
+ },
9810
+ "fields": {
9811
+ "type": "array",
9812
+ "maxItems": 50,
9813
+ "items": {
9814
+ "type": "string",
9815
+ "maxLength": 64
9816
+ },
9817
+ "description": "Optional. Answer with only these fields instead of the whole improvement, for example [\"id\", \"versionTimestamp\"]. Any of the improvement's own fields (snake_case or camelCase) or of the keys around it in the full answer (versionTimestamp, href and, where present, url, title, trackingId, message). The id is always returned, and so is any notice that needs your attention (a note, such as a phase's dates following its tasks or an item's id changing with its type, and a date change's cascadePreview). Unknown names are ignored."
9597
9818
  }
9598
9819
  },
9599
9820
  "required": [
@@ -9682,7 +9903,7 @@
9682
9903
  "/tools/updateImprovement": {
9683
9904
  "post": {
9684
9905
  "summary": "updateImprovement",
9685
- "description": "Update an improvement (or a task — tasks share this row, but prefer the symmetric updateTask alias when working from getTask). Supports the full field set including `checklist` (tick-boxes with due dates + completion attribution) and `acceptance_criteria` (objects with per-row updated_by/at attribution). Requires versionTimestamp from getImprovement for optimistic locking. Statuses are captured / in_progress / blocked / done / rejected / deferred, and FOUR of those are CLOSED: blocked, done, rejected, deferred. Entering one needs its comment (blocked needs blocked_comment, rejected needs rejection_comment, done needs completion_comment); leaving one for an open status needs reopened_comment — including blocked -> in_progress, which surprises people because `blocked` does not sound terminal. `metadata` MERGES into what is stored (null on a key deletes it); pass metadata_replace:true to overwrite the object wholesale. Assignment: pass `owner_id=<uuid>` to assign to a user, `owner_team_id=<uuid>` to assign to a team (mutually exclusive — a DB CHECK constraint enforces this). To unassign, pass `owner_id=null` AND `owner_team_id=null`. To switch from a user owner to a team owner, send `owner_id=null, owner_team_id=<uuid>` in the SAME call (sending only one side leaves the stale value and triggers the XOR check). Use listAssignablePrincipals or listTeams to discover valid IDs.",
9906
+ "description": "Update an improvement, or many in one call (or a task: tasks share this row, but prefer the symmetric updateTask alias when working from getTask). Supports the full field set including `checklist` (tick-boxes with due dates + completion attribution), `acceptance_criteria` (objects with per-row updated_by/at attribution) and parentItemId (the epic or story it belongs to in the work hierarchy; null removes it). versionTimestamp (optimistic locking) is the item's updated_at in epoch milliseconds, and you rarely need a getImprovement call for it: listImprovements returns it for every improvement in a project (fields [\"id\", \"friendlyId\", \"versionTimestamp\"] keeps that answer short), getPlan (items[].versionTimestamp) for every item in a plan, and every write returns the new one. Pass `fields` (for example [\"id\", \"versionTimestamp\"]) for a short answer instead of the whole record. To change many improvements, send `items`: up to 200 entries of { improvementId, versionTimestamp, ...changes } per call (more than 200: split them into several calls of up to 200), each checked and written on its own and answered with one row per entry plus a summary. Statuses are captured / in_progress / blocked / done / rejected / deferred, and FOUR of those are CLOSED: blocked, done, rejected, deferred. Entering one needs its comment (blocked needs blocked_comment, rejected needs rejection_comment, done needs completion_comment); leaving one for an open status needs reopened_comment, including blocked -> in_progress, which surprises people because `blocked` does not sound terminal. `metadata` MERGES into what is stored (null on a key deletes it); pass metadata_replace:true to overwrite the object wholesale. Assignment: pass `owner_id=<uuid>` to assign to a user, `owner_team_id=<uuid>` to assign to a team (mutually exclusive: a DB CHECK constraint enforces this). To unassign, pass `owner_id=null` AND `owner_team_id=null`. To switch from a user owner to a team owner, send `owner_id=null, owner_team_id=<uuid>` in the SAME call (sending only one side leaves the stale value and triggers the XOR check). Use listAssignablePrincipals or listTeams to discover valid IDs.",
9686
9907
  "operationId": "updateImprovement",
9687
9908
  "tags": [
9688
9909
  "improvements"
@@ -9698,21 +9919,240 @@
9698
9919
  "type": "string",
9699
9920
  "description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
9700
9921
  },
9922
+ "planId": {
9923
+ "type": "string",
9924
+ "description": "Optional. Narrows a friendly-id lookup (such as IMP-42) to one plan, given as the plan's UUID or friendly id (such as PLN-3): the item must be in that plan. It never moves anything (plan_id does that) and is ignored when the id is a UUID."
9925
+ },
9701
9926
  "improvementId": {
9702
- "type": "string"
9927
+ "type": "string",
9928
+ "description": "Required unless you send items. The improvement's UUID or friendly id (such as IMP-42)."
9703
9929
  },
9704
9930
  "versionTimestamp": {
9705
9931
  "type": "number",
9706
- "description": "Version timestamp from getImprovement() for optimistic locking."
9932
+ "description": "Required unless you send items. The item's current versionTimestamp (its updated_at in epoch ms), as listImprovements, getPlan, getImprovement or your last write of it returned."
9707
9933
  },
9708
9934
  "title": {
9709
9935
  "type": "string"
9710
9936
  },
9711
9937
  "type": {
9712
- "type": "string"
9938
+ "type": "string",
9939
+ "description": "One of: feature (New capability for users); enhancement (An improvement to something that already exists); bug (Something that does not work as it should); tech_debt (Work that makes the system easier and safer to change); architecture_gap (A missing or weak part of the architecture); documentation_gap (Documentation that is missing or out of date); risk (Something that could go wrong, to track and reduce); epic (A large body of work, delivered through several stories, features or tasks); user_story (A need told from a user's view: as a role, I want a goal, so that a benefit); requirement (A condition or capability the solution must meet, stated so it can be verified); test_case (Steps that verify a requirement or story, each with its expected result); spike (Time-boxed research to answer a question before committing to the work); task (A unit of work in a plan). Changing the type keeps everything written on the item, its parent and children included. The id's prefix follows the type (see createImprovement's type) and its number stays, so the id can change (STY-30 becomes IMP-30 when a story becomes a feature): the answer's note then gives the new id, and the old one still resolves."
9940
+ },
9941
+ "details": {
9942
+ "type": "object",
9943
+ "description": "The type's own fields. On update they MERGE key by key: keys you leave out are kept and null removes one. epic: success_measures. user_story: as_a, i_want, so_that (read as 'As a <as_a>, I want <i_want>, so that <so_that>') and story_points. requirement: statement ('The system shall...'), requirement_kind, rationale, source, verification_method. test_case: preconditions, test_steps (ordered { action, expected }), test_data, last_result, last_run_on. spike: question, timebox, findings. An item keeps its details when its type changes.",
9944
+ "properties": {
9945
+ "success_measures": {
9946
+ "type": [
9947
+ "string",
9948
+ "null"
9949
+ ],
9950
+ "maxLength": 20000,
9951
+ "description": "Success Measures (How will you know this epic delivered its outcome?)"
9952
+ },
9953
+ "as_a": {
9954
+ "type": [
9955
+ "string",
9956
+ "null"
9957
+ ],
9958
+ "maxLength": 500,
9959
+ "description": "As a (role or persona)"
9960
+ },
9961
+ "i_want": {
9962
+ "type": [
9963
+ "string",
9964
+ "null"
9965
+ ],
9966
+ "maxLength": 500,
9967
+ "description": "I want (what they want to do)"
9968
+ },
9969
+ "so_that": {
9970
+ "type": [
9971
+ "string",
9972
+ "null"
9973
+ ],
9974
+ "maxLength": 500,
9975
+ "description": "So that (the benefit to them)"
9976
+ },
9977
+ "story_points": {
9978
+ "type": [
9979
+ "number",
9980
+ "null"
9981
+ ],
9982
+ "minimum": 0,
9983
+ "maximum": 1000,
9984
+ "description": "Story Points (e.g. 3)"
9985
+ },
9986
+ "statement": {
9987
+ "type": [
9988
+ "string",
9989
+ "null"
9990
+ ],
9991
+ "maxLength": 20000,
9992
+ "description": "Requirement (The system shall...)"
9993
+ },
9994
+ "requirement_kind": {
9995
+ "type": [
9996
+ "string",
9997
+ "null"
9998
+ ],
9999
+ "enum": [
10000
+ "functional",
10001
+ "non_functional",
10002
+ "interface",
10003
+ "data",
10004
+ "business_rule",
10005
+ "constraint",
10006
+ "compliance",
10007
+ null
10008
+ ],
10009
+ "description": "Kind"
10010
+ },
10011
+ "rationale": {
10012
+ "type": [
10013
+ "string",
10014
+ "null"
10015
+ ],
10016
+ "maxLength": 20000,
10017
+ "description": "Rationale (Why it is needed...)"
10018
+ },
10019
+ "source": {
10020
+ "type": [
10021
+ "string",
10022
+ "null"
10023
+ ],
10024
+ "maxLength": 500,
10025
+ "description": "Source (A stakeholder, regulation or document)"
10026
+ },
10027
+ "verification_method": {
10028
+ "type": [
10029
+ "string",
10030
+ "null"
10031
+ ],
10032
+ "enum": [
10033
+ "test",
10034
+ "inspection",
10035
+ "analysis",
10036
+ "demonstration",
10037
+ null
10038
+ ],
10039
+ "description": "Verified By"
10040
+ },
10041
+ "preconditions": {
10042
+ "type": [
10043
+ "string",
10044
+ "null"
10045
+ ],
10046
+ "maxLength": 20000,
10047
+ "description": "Preconditions (What must be true before the test starts...)"
10048
+ },
10049
+ "test_steps": {
10050
+ "type": [
10051
+ "array",
10052
+ "null"
10053
+ ],
10054
+ "maxItems": 200,
10055
+ "items": {
10056
+ "type": "object",
10057
+ "properties": {
10058
+ "id": {
10059
+ "type": "string",
10060
+ "maxLength": 64,
10061
+ "description": "Optional; minted if omitted. Echo it back on the steps you keep."
10062
+ },
10063
+ "action": {
10064
+ "type": "string",
10065
+ "maxLength": 4000,
10066
+ "description": "What the tester does."
10067
+ },
10068
+ "expected": {
10069
+ "type": "string",
10070
+ "maxLength": 4000,
10071
+ "description": "What should happen."
10072
+ }
10073
+ }
10074
+ },
10075
+ "description": "Test Steps, in order. The list you send REPLACES the stored one."
10076
+ },
10077
+ "test_data": {
10078
+ "type": [
10079
+ "string",
10080
+ "null"
10081
+ ],
10082
+ "maxLength": 20000,
10083
+ "description": "Test Data (Inputs, accounts or records the steps use...)"
10084
+ },
10085
+ "last_result": {
10086
+ "type": [
10087
+ "string",
10088
+ "null"
10089
+ ],
10090
+ "enum": [
10091
+ "not_run",
10092
+ "passed",
10093
+ "failed",
10094
+ "blocked",
10095
+ null
10096
+ ],
10097
+ "description": "Last Result"
10098
+ },
10099
+ "last_run_on": {
10100
+ "type": [
10101
+ "string",
10102
+ "null"
10103
+ ],
10104
+ "description": "Last Run, YYYY-MM-DD."
10105
+ },
10106
+ "question": {
10107
+ "type": [
10108
+ "string",
10109
+ "null"
10110
+ ],
10111
+ "maxLength": 20000,
10112
+ "description": "Question (What does this spike need to find out?)"
10113
+ },
10114
+ "timebox": {
10115
+ "type": [
10116
+ "string",
10117
+ "null"
10118
+ ],
10119
+ "maxLength": 500,
10120
+ "description": "Timebox (e.g. 3 days)"
10121
+ },
10122
+ "findings": {
10123
+ "type": [
10124
+ "string",
10125
+ "null"
10126
+ ],
10127
+ "maxLength": 20000,
10128
+ "description": "Findings (What was learned, and the recommendation...)"
10129
+ }
10130
+ }
10131
+ },
10132
+ "parentItemId": {
10133
+ "type": [
10134
+ "string",
10135
+ "null"
10136
+ ],
10137
+ "maxLength": 64,
10138
+ "description": "The work item this one belongs to in the work hierarchy: an epic for a story, a story for its tasks or test cases. Any item in the same project, in any plan or phase. Not the plan outline nesting, which setPlanItemParent sets. Give its UUID or friendly id (such as IMP-12 or TAS-3). Rules: the same project; no loops (an item cannot sit inside its own children); at most 5 levels, counting this item's own children. null removes the parent."
9713
10139
  },
9714
10140
  "status": {
9715
- "type": "string"
10141
+ "type": "string",
10142
+ "enum": [
10143
+ "captured",
10144
+ "triaging",
10145
+ "shaped",
10146
+ "approved",
10147
+ "ready_for_agent",
10148
+ "in_progress",
10149
+ "ready_for_review",
10150
+ "in_review",
10151
+ "blocked",
10152
+ "done",
10153
+ "rejected",
10154
+ "deferred"
10155
+ ]
9716
10156
  },
9717
10157
  "priority": {
9718
10158
  "type": "string"
@@ -9982,92 +10422,553 @@
9982
10422
  "percent_complete": {
9983
10423
  "type": "number",
9984
10424
  "description": "Progress percentage (0-100). Null to clear."
9985
- }
9986
- },
9987
- "required": [
9988
- "improvementId",
9989
- "versionTimestamp"
9990
- ]
9991
- }
9992
- }
9993
- }
9994
- },
9995
- "responses": {
9996
- "200": {
9997
- "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
9998
- "content": {
9999
- "application/json": {
10000
- "schema": {
10001
- "type": "object",
10002
- "additionalProperties": true
10003
- }
10004
- }
10005
- }
10006
- },
10007
- "400": {
10008
- "description": "Validation error.",
10009
- "content": {
10010
- "application/json": {
10011
- "schema": {
10012
- "$ref": "#/components/schemas/ErrorResponse"
10013
- }
10014
- }
10015
- }
10016
- },
10017
- "401": {
10018
- "description": "Missing or invalid credentials.",
10019
- "content": {
10020
- "application/json": {
10021
- "schema": {
10022
- "$ref": "#/components/schemas/ErrorResponse"
10023
- }
10024
- }
10025
- }
10026
- },
10027
- "403": {
10028
- "description": "Authenticated but lacking the required permission or feature flag.",
10029
- "content": {
10030
- "application/json": {
10031
- "schema": {
10032
- "$ref": "#/components/schemas/ErrorResponse"
10033
- }
10034
- }
10035
- }
10036
- },
10037
- "404": {
10038
- "description": "Resource not found.",
10039
- "content": {
10040
- "application/json": {
10041
- "schema": {
10042
- "$ref": "#/components/schemas/ErrorResponse"
10043
- }
10044
- }
10045
- }
10046
- },
10047
- "422": {
10048
- "description": "Body did not match the tool's input schema.",
10049
- "content": {
10050
- "application/json": {
10051
- "schema": {
10052
- "$ref": "#/components/schemas/ErrorResponse"
10053
- }
10054
- }
10055
- }
10056
- },
10057
- "500": {
10058
- "description": "Server error.",
10059
- "content": {
10060
- "application/json": {
10061
- "schema": {
10062
- "$ref": "#/components/schemas/ErrorResponse"
10063
- }
10064
- }
10065
- }
10066
- }
10067
- }
10068
- }
10069
- },
10070
- "/tools/deleteImprovement": {
10425
+ },
10426
+ "fields": {
10427
+ "type": "array",
10428
+ "maxItems": 50,
10429
+ "items": {
10430
+ "type": "string",
10431
+ "maxLength": 64
10432
+ },
10433
+ "description": "Optional. Answer with only these fields instead of the whole improvement, for example [\"id\", \"versionTimestamp\"]. Any of the improvement's own fields (snake_case or camelCase) or of the keys around it in the full answer (versionTimestamp, href and, where present, url, title, trackingId, message). The id is always returned, and so is any notice that needs your attention (a note, such as a phase's dates following its tasks or an item's id changing with its type, and a date change's cascadePreview). Unknown names are ignored."
10434
+ },
10435
+ "items": {
10436
+ "type": "array",
10437
+ "minItems": 1,
10438
+ "maxItems": 200,
10439
+ "description": "Optional bulk form: update up to 200 improvements in one call, each entry { improvementId, versionTimestamp, ...the fields to change } with the same fields as a single call. Every entry is checked and written on its own (permission, optimistic lock, audit), so one entry's conflict or error never stops the others. The answer has one row per entry, in your order: { index, id, status: \"updated\", versionTimestamp } or { index, id, status: \"conflict\" or \"failed\", error } (a conflict also carries currentVersionTimestamp), plus summary { requested, updated, failed, conflicts }. With items, send nothing else at the top level except projectId, planId and fields; fields then picks extra fields for each updated row (a row's status is its outcome, so the improvement's own status comes back as improvementStatus).",
10440
+ "items": {
10441
+ "type": "object",
10442
+ "properties": {
10443
+ "improvementId": {
10444
+ "type": "string"
10445
+ },
10446
+ "versionTimestamp": {
10447
+ "type": "number"
10448
+ },
10449
+ "title": {
10450
+ "type": "string"
10451
+ },
10452
+ "type": {
10453
+ "type": "string"
10454
+ },
10455
+ "details": {
10456
+ "type": "object",
10457
+ "properties": {
10458
+ "success_measures": {
10459
+ "type": [
10460
+ "string",
10461
+ "null"
10462
+ ],
10463
+ "maxLength": 20000
10464
+ },
10465
+ "as_a": {
10466
+ "type": [
10467
+ "string",
10468
+ "null"
10469
+ ],
10470
+ "maxLength": 500
10471
+ },
10472
+ "i_want": {
10473
+ "type": [
10474
+ "string",
10475
+ "null"
10476
+ ],
10477
+ "maxLength": 500
10478
+ },
10479
+ "so_that": {
10480
+ "type": [
10481
+ "string",
10482
+ "null"
10483
+ ],
10484
+ "maxLength": 500
10485
+ },
10486
+ "story_points": {
10487
+ "type": [
10488
+ "number",
10489
+ "null"
10490
+ ],
10491
+ "minimum": 0,
10492
+ "maximum": 1000
10493
+ },
10494
+ "statement": {
10495
+ "type": [
10496
+ "string",
10497
+ "null"
10498
+ ],
10499
+ "maxLength": 20000
10500
+ },
10501
+ "requirement_kind": {
10502
+ "type": [
10503
+ "string",
10504
+ "null"
10505
+ ],
10506
+ "enum": [
10507
+ "functional",
10508
+ "non_functional",
10509
+ "interface",
10510
+ "data",
10511
+ "business_rule",
10512
+ "constraint",
10513
+ "compliance",
10514
+ null
10515
+ ]
10516
+ },
10517
+ "rationale": {
10518
+ "type": [
10519
+ "string",
10520
+ "null"
10521
+ ],
10522
+ "maxLength": 20000
10523
+ },
10524
+ "source": {
10525
+ "type": [
10526
+ "string",
10527
+ "null"
10528
+ ],
10529
+ "maxLength": 500
10530
+ },
10531
+ "verification_method": {
10532
+ "type": [
10533
+ "string",
10534
+ "null"
10535
+ ],
10536
+ "enum": [
10537
+ "test",
10538
+ "inspection",
10539
+ "analysis",
10540
+ "demonstration",
10541
+ null
10542
+ ]
10543
+ },
10544
+ "preconditions": {
10545
+ "type": [
10546
+ "string",
10547
+ "null"
10548
+ ],
10549
+ "maxLength": 20000
10550
+ },
10551
+ "test_steps": {
10552
+ "type": [
10553
+ "array",
10554
+ "null"
10555
+ ],
10556
+ "maxItems": 200,
10557
+ "items": {
10558
+ "type": "object",
10559
+ "properties": {
10560
+ "id": {
10561
+ "type": "string",
10562
+ "maxLength": 64
10563
+ },
10564
+ "action": {
10565
+ "type": "string",
10566
+ "maxLength": 4000
10567
+ },
10568
+ "expected": {
10569
+ "type": "string",
10570
+ "maxLength": 4000
10571
+ }
10572
+ }
10573
+ }
10574
+ },
10575
+ "test_data": {
10576
+ "type": [
10577
+ "string",
10578
+ "null"
10579
+ ],
10580
+ "maxLength": 20000
10581
+ },
10582
+ "last_result": {
10583
+ "type": [
10584
+ "string",
10585
+ "null"
10586
+ ],
10587
+ "enum": [
10588
+ "not_run",
10589
+ "passed",
10590
+ "failed",
10591
+ "blocked",
10592
+ null
10593
+ ]
10594
+ },
10595
+ "last_run_on": {
10596
+ "type": [
10597
+ "string",
10598
+ "null"
10599
+ ]
10600
+ },
10601
+ "question": {
10602
+ "type": [
10603
+ "string",
10604
+ "null"
10605
+ ],
10606
+ "maxLength": 20000
10607
+ },
10608
+ "timebox": {
10609
+ "type": [
10610
+ "string",
10611
+ "null"
10612
+ ],
10613
+ "maxLength": 500
10614
+ },
10615
+ "findings": {
10616
+ "type": [
10617
+ "string",
10618
+ "null"
10619
+ ],
10620
+ "maxLength": 20000
10621
+ }
10622
+ }
10623
+ },
10624
+ "parentItemId": {
10625
+ "type": [
10626
+ "string",
10627
+ "null"
10628
+ ],
10629
+ "maxLength": 64
10630
+ },
10631
+ "status": {
10632
+ "type": "string",
10633
+ "enum": [
10634
+ "captured",
10635
+ "triaging",
10636
+ "shaped",
10637
+ "approved",
10638
+ "ready_for_agent",
10639
+ "in_progress",
10640
+ "ready_for_review",
10641
+ "in_review",
10642
+ "blocked",
10643
+ "done",
10644
+ "rejected",
10645
+ "deferred"
10646
+ ]
10647
+ },
10648
+ "priority": {
10649
+ "type": "string"
10650
+ },
10651
+ "urgency": {
10652
+ "type": "string"
10653
+ },
10654
+ "owner_id": {
10655
+ "type": [
10656
+ "string",
10657
+ "null"
10658
+ ]
10659
+ },
10660
+ "owner_team_id": {
10661
+ "type": [
10662
+ "string",
10663
+ "null"
10664
+ ]
10665
+ },
10666
+ "target_date": {
10667
+ "type": "string"
10668
+ },
10669
+ "start_date": {
10670
+ "type": "string"
10671
+ },
10672
+ "end_date": {
10673
+ "type": "string"
10674
+ },
10675
+ "category_id": {
10676
+ "type": "string"
10677
+ },
10678
+ "position": {
10679
+ "type": "number"
10680
+ },
10681
+ "problem_statement": {
10682
+ "type": "string"
10683
+ },
10684
+ "desired_outcome": {
10685
+ "type": "string"
10686
+ },
10687
+ "business_impact": {
10688
+ "type": "string"
10689
+ },
10690
+ "user_impact": {
10691
+ "type": "string"
10692
+ },
10693
+ "why_now": {
10694
+ "type": "string"
10695
+ },
10696
+ "acceptance_criteria": {
10697
+ "type": "array",
10698
+ "items": {
10699
+ "anyOf": [
10700
+ {
10701
+ "type": "string"
10702
+ },
10703
+ {
10704
+ "type": "object",
10705
+ "properties": {
10706
+ "id": {
10707
+ "type": "string"
10708
+ },
10709
+ "text": {
10710
+ "type": "string"
10711
+ },
10712
+ "updated_at": {
10713
+ "type": "string"
10714
+ },
10715
+ "updated_by": {
10716
+ "type": "string"
10717
+ },
10718
+ "updated_by_credential_name": {
10719
+ "type": "string"
10720
+ }
10721
+ },
10722
+ "required": [
10723
+ "text"
10724
+ ]
10725
+ }
10726
+ ]
10727
+ }
10728
+ },
10729
+ "checklist": {
10730
+ "type": "array",
10731
+ "items": {
10732
+ "type": "object",
10733
+ "properties": {
10734
+ "id": {
10735
+ "type": "string"
10736
+ },
10737
+ "text": {
10738
+ "type": "string"
10739
+ },
10740
+ "due_date": {
10741
+ "type": "string"
10742
+ },
10743
+ "completed": {
10744
+ "type": "boolean"
10745
+ },
10746
+ "completed_at": {
10747
+ "type": "string"
10748
+ },
10749
+ "completed_by": {
10750
+ "type": "string"
10751
+ },
10752
+ "completed_by_credential_name": {
10753
+ "type": "string"
10754
+ },
10755
+ "updated_at": {
10756
+ "type": "string"
10757
+ },
10758
+ "updated_by": {
10759
+ "type": "string"
10760
+ },
10761
+ "updated_by_credential_name": {
10762
+ "type": "string"
10763
+ }
10764
+ },
10765
+ "required": [
10766
+ "text"
10767
+ ]
10768
+ }
10769
+ },
10770
+ "constraints": {
10771
+ "type": "array",
10772
+ "items": {
10773
+ "type": "string"
10774
+ }
10775
+ },
10776
+ "non_goals": {
10777
+ "type": "array",
10778
+ "items": {
10779
+ "type": "string"
10780
+ }
10781
+ },
10782
+ "impacted_documents": {
10783
+ "type": "array",
10784
+ "items": {
10785
+ "type": "object"
10786
+ }
10787
+ },
10788
+ "linked_document_ids": {
10789
+ "type": "array",
10790
+ "items": {
10791
+ "type": "string"
10792
+ }
10793
+ },
10794
+ "impacted_diagrams": {
10795
+ "type": "array",
10796
+ "items": {
10797
+ "type": "object"
10798
+ }
10799
+ },
10800
+ "impacted_components": {
10801
+ "type": "array",
10802
+ "items": {
10803
+ "type": "string"
10804
+ }
10805
+ },
10806
+ "impacted_repositories": {
10807
+ "type": "array",
10808
+ "items": {
10809
+ "type": "string"
10810
+ }
10811
+ },
10812
+ "agent_ready": {
10813
+ "type": "boolean"
10814
+ },
10815
+ "agent_missing_info": {
10816
+ "type": "array",
10817
+ "items": {
10818
+ "type": "string"
10819
+ }
10820
+ },
10821
+ "agent_recommended_action": {
10822
+ "type": "string"
10823
+ },
10824
+ "agent_complexity": {
10825
+ "type": "string"
10826
+ },
10827
+ "agent_confidence": {
10828
+ "type": "number"
10829
+ },
10830
+ "agent_brief": {
10831
+ "type": "string"
10832
+ },
10833
+ "resolution_summary": {
10834
+ "type": "string"
10835
+ },
10836
+ "resolution_pr_url": {
10837
+ "type": "string"
10838
+ },
10839
+ "docs_updated": {
10840
+ "type": "boolean"
10841
+ },
10842
+ "follow_up_needed": {
10843
+ "type": "boolean"
10844
+ },
10845
+ "blocked_comment": {
10846
+ "type": "string"
10847
+ },
10848
+ "rejection_comment": {
10849
+ "type": "string"
10850
+ },
10851
+ "completion_comment": {
10852
+ "type": "string"
10853
+ },
10854
+ "reopened_comment": {
10855
+ "type": "string"
10856
+ },
10857
+ "relationships": {
10858
+ "type": "object"
10859
+ },
10860
+ "metadata": {
10861
+ "type": "object"
10862
+ },
10863
+ "metadata_replace": {
10864
+ "type": "boolean"
10865
+ },
10866
+ "plan_id": {
10867
+ "type": "string"
10868
+ },
10869
+ "phase_id": {
10870
+ "type": "string"
10871
+ },
10872
+ "is_task": {
10873
+ "type": "boolean"
10874
+ },
10875
+ "description": {
10876
+ "type": "string"
10877
+ },
10878
+ "wbs_code": {
10879
+ "type": "string"
10880
+ },
10881
+ "percent_complete": {
10882
+ "type": "number"
10883
+ }
10884
+ },
10885
+ "required": [
10886
+ "improvementId",
10887
+ "versionTimestamp"
10888
+ ]
10889
+ }
10890
+ }
10891
+ }
10892
+ }
10893
+ }
10894
+ }
10895
+ },
10896
+ "responses": {
10897
+ "200": {
10898
+ "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
10899
+ "content": {
10900
+ "application/json": {
10901
+ "schema": {
10902
+ "type": "object",
10903
+ "additionalProperties": true
10904
+ }
10905
+ }
10906
+ }
10907
+ },
10908
+ "400": {
10909
+ "description": "Validation error.",
10910
+ "content": {
10911
+ "application/json": {
10912
+ "schema": {
10913
+ "$ref": "#/components/schemas/ErrorResponse"
10914
+ }
10915
+ }
10916
+ }
10917
+ },
10918
+ "401": {
10919
+ "description": "Missing or invalid credentials.",
10920
+ "content": {
10921
+ "application/json": {
10922
+ "schema": {
10923
+ "$ref": "#/components/schemas/ErrorResponse"
10924
+ }
10925
+ }
10926
+ }
10927
+ },
10928
+ "403": {
10929
+ "description": "Authenticated but lacking the required permission or feature flag.",
10930
+ "content": {
10931
+ "application/json": {
10932
+ "schema": {
10933
+ "$ref": "#/components/schemas/ErrorResponse"
10934
+ }
10935
+ }
10936
+ }
10937
+ },
10938
+ "404": {
10939
+ "description": "Resource not found.",
10940
+ "content": {
10941
+ "application/json": {
10942
+ "schema": {
10943
+ "$ref": "#/components/schemas/ErrorResponse"
10944
+ }
10945
+ }
10946
+ }
10947
+ },
10948
+ "422": {
10949
+ "description": "Body did not match the tool's input schema.",
10950
+ "content": {
10951
+ "application/json": {
10952
+ "schema": {
10953
+ "$ref": "#/components/schemas/ErrorResponse"
10954
+ }
10955
+ }
10956
+ }
10957
+ },
10958
+ "500": {
10959
+ "description": "Server error.",
10960
+ "content": {
10961
+ "application/json": {
10962
+ "schema": {
10963
+ "$ref": "#/components/schemas/ErrorResponse"
10964
+ }
10965
+ }
10966
+ }
10967
+ }
10968
+ }
10969
+ }
10970
+ },
10971
+ "/tools/deleteImprovement": {
10071
10972
  "post": {
10072
10973
  "summary": "deleteImprovement",
10073
10974
  "description": "Delete an improvement and all associated evidence and activity.",
@@ -11395,7 +12296,7 @@
11395
12296
  "items": {
11396
12297
  "type": "string"
11397
12298
  },
11398
- "description": "Field projection. Valid fields: id, friendly_id, friendlyId, title, description, status, priority, icon, color, start_date, startDate, end_date, endDate, created_at, createdAt, updated_at, updatedAt, href."
12299
+ "description": "Field projection. Valid fields: id, friendly_id, friendlyId, title, description, status, priority, icon, color, start_date, startDate, end_date, endDate, created_at, createdAt, updated_at, updatedAt, versionTimestamp, href."
11399
12300
  }
11400
12301
  },
11401
12302
  "required": [
@@ -11483,7 +12384,7 @@
11483
12384
  "/tools/getPlan": {
11484
12385
  "post": {
11485
12386
  "summary": "getPlan",
11486
- "description": "Get full plan details including phases, items, and activity. Returns versionTimestamp — pass it to updatePlan for optimistic locking. Items include percent_complete for progress tracking.",
12387
+ "description": "Get full plan details including phases, items, and activity. Every level carries its own optimistic-lock token, so one call supplies them all: the top-level versionTimestamp is the plan's (for updatePlan), phases[].versionTimestamp each phase's (for updatePlanPhase) and items[].versionTimestamp each task's or improvement's (for updateTask / updateImprovement, including their bulk `items` form). Items include percent_complete for progress tracking.",
11487
12388
  "operationId": "getPlan",
11488
12389
  "tags": [
11489
12390
  "plans"
@@ -11589,7 +12490,7 @@
11589
12490
  "/tools/createPlan": {
11590
12491
  "post": {
11591
12492
  "summary": "createPlan",
11592
- "description": "Create a plan in a project. Requires projectId and title.",
12493
+ "description": "Create a plan in a project. Requires projectId and title. Pass `fields` (for example [\"id\", \"versionTimestamp\"]) for a short answer instead of the whole plan.",
11593
12494
  "operationId": "createPlan",
11594
12495
  "tags": [
11595
12496
  "plans"
@@ -11655,6 +12556,15 @@
11655
12556
  "type": "string"
11656
12557
  },
11657
12558
  "description": "Document IDs to link."
12559
+ },
12560
+ "fields": {
12561
+ "type": "array",
12562
+ "maxItems": 50,
12563
+ "items": {
12564
+ "type": "string",
12565
+ "maxLength": 64
12566
+ },
12567
+ "description": "Optional. Answer with only these fields instead of the whole plan, for example [\"id\", \"versionTimestamp\"]. Any of the plan's own fields (snake_case or camelCase) or of the keys around it in the full answer (versionTimestamp, href and, where present, url, title, trackingId, message). The id is always returned, and so is any notice that needs your attention (a note, such as a phase's dates following its tasks or an item's id changing with its type, and a date change's cascadePreview). Unknown names are ignored."
11658
12568
  }
11659
12569
  },
11660
12570
  "required": [
@@ -11743,7 +12653,7 @@
11743
12653
  "/tools/updatePlan": {
11744
12654
  "post": {
11745
12655
  "summary": "updatePlan",
11746
- "description": "Update a plan. Requires versionTimestamp from getPlan.",
12656
+ "description": "Update a plan. versionTimestamp (optimistic locking) is the plan's updated_at in epoch milliseconds: listPlans and getPlan return it, and every write returns the new one. Pass `fields` (for example [\"id\", \"versionTimestamp\"]) for a short answer instead of the whole plan.",
11747
12657
  "operationId": "updatePlan",
11748
12658
  "tags": [
11749
12659
  "plans"
@@ -11764,7 +12674,7 @@
11764
12674
  },
11765
12675
  "versionTimestamp": {
11766
12676
  "type": "number",
11767
- "description": "Version timestamp from getPlan() for optimistic locking."
12677
+ "description": "The plan's current versionTimestamp (its updated_at in epoch ms), as listPlans, getPlan or your last write of it returned."
11768
12678
  },
11769
12679
  "title": {
11770
12680
  "type": "string"
@@ -11809,6 +12719,15 @@
11809
12719
  },
11810
12720
  "metadata": {
11811
12721
  "type": "object"
12722
+ },
12723
+ "fields": {
12724
+ "type": "array",
12725
+ "maxItems": 50,
12726
+ "items": {
12727
+ "type": "string",
12728
+ "maxLength": 64
12729
+ },
12730
+ "description": "Optional. Answer with only these fields instead of the whole plan, for example [\"id\", \"versionTimestamp\"]. Any of the plan's own fields (snake_case or camelCase) or of the keys around it in the full answer (versionTimestamp, href and, where present, url, title, trackingId, message). The id is always returned, and so is any notice that needs your attention (a note, such as a phase's dates following its tasks or an item's id changing with its type, and a date change's cascadePreview). Unknown names are ignored."
11812
12731
  }
11813
12732
  },
11814
12733
  "required": [
@@ -12002,7 +12921,7 @@
12002
12921
  "/tools/listPlanPhases": {
12003
12922
  "post": {
12004
12923
  "summary": "listPlanPhases",
12005
- "description": "List phases for a plan ordered by position.",
12924
+ "description": "List phases for a plan ordered by position. Each phase carries its own versionTimestamp, ready for updatePlanPhase.",
12006
12925
  "operationId": "listPlanPhases",
12007
12926
  "tags": [
12008
12927
  "plans"
@@ -12119,6 +13038,10 @@
12119
13038
  "type": "string",
12120
13039
  "description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
12121
13040
  },
13041
+ "planId": {
13042
+ "type": "string",
13043
+ "description": "Optional. Narrows a friendly-id lookup to one plan, given as the plan's UUID or friendly id (such as PLN-3). Phase ids are numbered per plan, so PHA-2 exists in every plan and planId is what makes one unique. Ignored when phaseId is a UUID."
13044
+ },
12122
13045
  "phaseId": {
12123
13046
  "type": "string",
12124
13047
  "description": "Accepts either the UUID or the friendly id (e.g. PHA-7); friendly ids are resolved within your organisation."
@@ -12209,7 +13132,7 @@
12209
13132
  "/tools/createPlanPhase": {
12210
13133
  "post": {
12211
13134
  "summary": "createPlanPhase",
12212
- "description": "Create a phase in a plan. Position and wbs_code are auto-computed.",
13135
+ "description": "Create a phase in a plan. Position and wbs_code are auto-computed. By default a phase's dates follow its tasks (date_mode 'auto'): once any task in it has dates, the phase runs from the earliest task start to the latest task end and stays in step as tasks change, so there is no need to maintain phase dates by hand. Pass `fields` (for example [\"id\", \"versionTimestamp\"]) for a short answer instead of the whole phase.",
12213
13136
  "operationId": "createPlanPhase",
12214
13137
  "tags": [
12215
13138
  "plans"
@@ -12246,13 +13169,21 @@
12246
13169
  "type": "string",
12247
13170
  "description": "WBS code. Auto-computed if omitted."
12248
13171
  },
13172
+ "date_mode": {
13173
+ "type": "string",
13174
+ "enum": [
13175
+ "auto",
13176
+ "manual"
13177
+ ],
13178
+ "description": "auto (default): the phase's dates follow its tasks, from the earliest task start to the latest task end, updated whenever a task is added, moved, re-dated or removed; start_date/end_date only hold while no task in the phase has dates. manual: the dates you set are kept as they are."
13179
+ },
12249
13180
  "start_date": {
12250
13181
  "type": "string",
12251
- "description": "YYYY-MM-DD."
13182
+ "description": "YYYY-MM-DD. With date_mode 'auto' it is replaced by the tasks' range once a task in the phase has dates."
12252
13183
  },
12253
13184
  "end_date": {
12254
13185
  "type": "string",
12255
- "description": "YYYY-MM-DD."
13186
+ "description": "YYYY-MM-DD, on or after start_date. With date_mode 'auto' it is replaced by the tasks' range once a task in the phase has dates."
12256
13187
  },
12257
13188
  "color": {
12258
13189
  "type": "string",
@@ -12267,6 +13198,15 @@
12267
13198
  "#6b7280"
12268
13199
  ],
12269
13200
  "description": "Phase color. Must be one of: #3b82f6 (Blue), #f59e0b (Amber), #8b5cf6 (Purple), #ec4899 (Pink), #06b6d4 (Cyan), #14b8a6 (Teal), #6366f1 (Indigo), #6b7280 (Gray). Red and green are reserved for blocked / done item statuses."
13201
+ },
13202
+ "fields": {
13203
+ "type": "array",
13204
+ "maxItems": 50,
13205
+ "items": {
13206
+ "type": "string",
13207
+ "maxLength": 64
13208
+ },
13209
+ "description": "Optional. Answer with only these fields instead of the whole phase, for example [\"id\", \"versionTimestamp\"]. Any of the phase's own fields (snake_case or camelCase) or of the keys around it in the full answer (versionTimestamp, href and, where present, url, title, trackingId, message). The id is always returned, and so is any notice that needs your attention (a note, such as a phase's dates following its tasks or an item's id changing with its type, and a date change's cascadePreview). Unknown names are ignored."
12270
13210
  }
12271
13211
  },
12272
13212
  "required": [
@@ -12355,7 +13295,7 @@
12355
13295
  "/tools/updatePlanPhase": {
12356
13296
  "post": {
12357
13297
  "summary": "updatePlanPhase",
12358
- "description": "Update a plan phase. Requires versionTimestamp from getPlanPhase (not getPlan).",
13298
+ "description": "Update a plan phase, or many phases in one call. Each phase has its own versionTimestamp (its updated_at in epoch milliseconds): listPlanPhases and getPlan (phases[].versionTimestamp) return it for every phase in a plan, getPlanPhase for one, and every write returns the new one. Never pass the plan's own top-level versionTimestamp. A phase with date_mode 'auto' (the default) takes its dates from its tasks; set date_mode 'manual' to pin dates by hand, or 'auto' to make them follow the tasks again. Pass `fields` (for example [\"id\", \"versionTimestamp\"]) for a short answer; a `note` saying the dates were replaced by the tasks' range always comes back. To change many phases, send `items`: up to 200 entries of { phaseId, versionTimestamp, ...changes } per call (more than 200: split them into several calls of up to 200), each checked and written on its own and answered with one row per entry plus a summary.",
12359
13299
  "operationId": "updatePlanPhase",
12360
13300
  "tags": [
12361
13301
  "plans"
@@ -12371,12 +13311,17 @@
12371
13311
  "type": "string",
12372
13312
  "description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
12373
13313
  },
13314
+ "planId": {
13315
+ "type": "string",
13316
+ "description": "Optional. Narrows a friendly-id lookup to one plan, given as the plan's UUID or friendly id (such as PLN-3). Phase ids are numbered per plan, so PHA-2 exists in every plan and planId is what makes one unique. Ignored when phaseId is a UUID."
13317
+ },
12374
13318
  "phaseId": {
12375
- "type": "string"
13319
+ "type": "string",
13320
+ "description": "Required unless you send items. The phase's UUID or friendly id (such as PHA-7); with a friendly id, give planId too, since PHA- ids repeat in every plan."
12376
13321
  },
12377
13322
  "versionTimestamp": {
12378
13323
  "type": "number",
12379
- "description": "Version timestamp from getPlanPhase() for optimistic locking."
13324
+ "description": "Required unless you send items. The phase's own current versionTimestamp (its updated_at in epoch ms), as listPlanPhases, getPlan (phases[].versionTimestamp), getPlanPhase or your last write of it returned. Not the plan's."
12380
13325
  },
12381
13326
  "name": {
12382
13327
  "type": "string"
@@ -12398,11 +13343,27 @@
12398
13343
  "wbs_code": {
12399
13344
  "type": "string"
12400
13345
  },
13346
+ "date_mode": {
13347
+ "type": "string",
13348
+ "enum": [
13349
+ "auto",
13350
+ "manual"
13351
+ ],
13352
+ "description": "auto: the phase's dates follow its tasks (earliest task start to latest task end, kept current). manual: the dates you set are kept. Switching to auto recomputes the dates at once when the phase has dated tasks."
13353
+ },
12401
13354
  "start_date": {
12402
- "type": "string"
13355
+ "type": [
13356
+ "string",
13357
+ "null"
13358
+ ],
13359
+ "description": "YYYY-MM-DD, or null to clear. While date_mode is 'auto' and the phase has dated tasks, the tasks' range wins and the reply carries a note saying so; send date_mode 'manual' with it to set it by hand."
12403
13360
  },
12404
13361
  "end_date": {
12405
- "type": "string"
13362
+ "type": [
13363
+ "string",
13364
+ "null"
13365
+ ],
13366
+ "description": "YYYY-MM-DD on or after start_date, or null to clear. While date_mode is 'auto' and the phase has dated tasks, the tasks' range wins and the reply carries a note saying so; send date_mode 'manual' with it to set it by hand."
12406
13367
  },
12407
13368
  "color": {
12408
13369
  "type": [
@@ -12421,12 +13382,92 @@
12421
13382
  null
12422
13383
  ],
12423
13384
  "description": "Phase color. Must be one of: #3b82f6 (Blue), #f59e0b (Amber), #8b5cf6 (Purple), #ec4899 (Pink), #06b6d4 (Cyan), #14b8a6 (Teal), #6366f1 (Indigo), #6b7280 (Gray). Red and green are reserved for blocked / done item statuses. Pass null to clear."
13385
+ },
13386
+ "fields": {
13387
+ "type": "array",
13388
+ "maxItems": 50,
13389
+ "items": {
13390
+ "type": "string",
13391
+ "maxLength": 64
13392
+ },
13393
+ "description": "Optional. Answer with only these fields instead of the whole phase, for example [\"id\", \"versionTimestamp\"]. Any of the phase's own fields (snake_case or camelCase) or of the keys around it in the full answer (versionTimestamp, href and, where present, url, title, trackingId, message). The id is always returned, and so is any notice that needs your attention (a note, such as a phase's dates following its tasks or an item's id changing with its type, and a date change's cascadePreview). Unknown names are ignored."
13394
+ },
13395
+ "items": {
13396
+ "type": "array",
13397
+ "minItems": 1,
13398
+ "maxItems": 200,
13399
+ "description": "Optional bulk form: update up to 200 phases in one call, each entry { phaseId, versionTimestamp, ...the fields to change } with the same fields as a single call. Every entry is checked and written on its own (permission, optimistic lock, audit), so one entry's conflict or error never stops the others. The answer has one row per entry, in your order: { index, id, status: \"updated\", versionTimestamp } or { index, id, status: \"conflict\" or \"failed\", error } (a conflict also carries currentVersionTimestamp), plus summary { requested, updated, failed, conflicts }. With items, send nothing else at the top level except projectId, planId and fields; fields then picks extra fields for each updated row (a row's status is its outcome, so the phase's own status comes back as phaseStatus).",
13400
+ "items": {
13401
+ "type": "object",
13402
+ "properties": {
13403
+ "phaseId": {
13404
+ "type": "string"
13405
+ },
13406
+ "versionTimestamp": {
13407
+ "type": "number"
13408
+ },
13409
+ "name": {
13410
+ "type": "string"
13411
+ },
13412
+ "description": {
13413
+ "type": "string"
13414
+ },
13415
+ "status": {
13416
+ "type": "string"
13417
+ },
13418
+ "priority": {
13419
+ "type": "string"
13420
+ },
13421
+ "position": {
13422
+ "type": "number"
13423
+ },
13424
+ "wbs_code": {
13425
+ "type": "string"
13426
+ },
13427
+ "date_mode": {
13428
+ "type": "string",
13429
+ "enum": [
13430
+ "auto",
13431
+ "manual"
13432
+ ]
13433
+ },
13434
+ "start_date": {
13435
+ "type": [
13436
+ "string",
13437
+ "null"
13438
+ ]
13439
+ },
13440
+ "end_date": {
13441
+ "type": [
13442
+ "string",
13443
+ "null"
13444
+ ]
13445
+ },
13446
+ "color": {
13447
+ "type": [
13448
+ "string",
13449
+ "null"
13450
+ ],
13451
+ "enum": [
13452
+ "#3b82f6",
13453
+ "#f59e0b",
13454
+ "#8b5cf6",
13455
+ "#ec4899",
13456
+ "#06b6d4",
13457
+ "#14b8a6",
13458
+ "#6366f1",
13459
+ "#6b7280",
13460
+ null
13461
+ ]
13462
+ }
13463
+ },
13464
+ "required": [
13465
+ "phaseId",
13466
+ "versionTimestamp"
13467
+ ]
13468
+ }
12424
13469
  }
12425
- },
12426
- "required": [
12427
- "phaseId",
12428
- "versionTimestamp"
12429
- ]
13470
+ }
12430
13471
  }
12431
13472
  }
12432
13473
  }
@@ -12525,6 +13566,10 @@
12525
13566
  "type": "string",
12526
13567
  "description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
12527
13568
  },
13569
+ "planId": {
13570
+ "type": "string",
13571
+ "description": "Optional. Narrows a friendly-id lookup to one plan, given as the plan's UUID or friendly id (such as PLN-3). Phase ids are numbered per plan, so PHA-2 exists in every plan and planId is what makes one unique. Ignored when phaseId is a UUID."
13572
+ },
12528
13573
  "phaseId": {
12529
13574
  "type": "string"
12530
13575
  }
@@ -13074,7 +14119,7 @@
13074
14119
  "/tools/createTask": {
13075
14120
  "post": {
13076
14121
  "summary": "createTask",
13077
- "description": "Create a task in a plan. Requires planId and title. Accepts every field updateTask accepts, so a task can be created complete in ONE call — no create-then-update, and no window in which other actors read a half-written record.",
14122
+ "description": "Create a task in a plan. Requires planId and title. Accepts every field updateTask accepts, so a task can be created complete in ONE call: no create-then-update, and no window in which other actors read a half-written record. Pass parentItemId to create it under its story, requirement or feature in the work hierarchy (which may be in another plan, or in none). Pass `fields` (for example [\"id\", \"friendlyId\", \"versionTimestamp\"]) for a short answer instead of the whole task.",
13078
14123
  "operationId": "createTask",
13079
14124
  "tags": [
13080
14125
  "plans"
@@ -13096,15 +14141,34 @@
13096
14141
  "type": "string",
13097
14142
  "description": "Phase to assign to."
13098
14143
  },
14144
+ "parentItemId": {
14145
+ "type": "string",
14146
+ "maxLength": 64,
14147
+ "description": "The work item this one belongs to in the work hierarchy: an epic for a story, a story for its tasks or test cases. Any item in the same project, in any plan or phase. Not the plan outline nesting, which setPlanItemParent sets. Give its UUID or friendly id (such as IMP-12 or TAS-3). Rules: the same project; no loops (an item cannot sit inside its own children); at most 5 levels, counting this item's own children."
14148
+ },
13099
14149
  "description": {
13100
14150
  "type": "string"
13101
14151
  },
13102
14152
  "type": {
13103
14153
  "type": "string",
13104
- "description": "Type. Default: task. Tasks created in plans are typed 'task' (friendly_id prefix TAS-). Override only if you want the row to appear as a non-task improvement (IMP- prefix). Valid values: feature, bug, tech_debt, architecture_gap, documentation_gap, risk, enhancement, task."
14154
+ "description": "Type. Default: task, which takes a TAS- id. Override only to put another kind of work item in the plan, for example a user_story (a STY- id) or a test_case (a TC- id); the id's prefix follows the type. Valid values: feature, enhancement, bug, tech_debt, architecture_gap, documentation_gap, risk, epic, user_story, requirement, test_case, spike, task."
13105
14155
  },
13106
14156
  "status": {
13107
14157
  "type": "string",
14158
+ "enum": [
14159
+ "captured",
14160
+ "triaging",
14161
+ "shaped",
14162
+ "approved",
14163
+ "ready_for_agent",
14164
+ "in_progress",
14165
+ "ready_for_review",
14166
+ "in_review",
14167
+ "blocked",
14168
+ "done",
14169
+ "rejected",
14170
+ "deferred"
14171
+ ],
13108
14172
  "description": "Initial status. Default: captured."
13109
14173
  },
13110
14174
  "priority": {
@@ -13336,6 +14400,15 @@
13336
14400
  "metadata": {
13337
14401
  "type": "object",
13338
14402
  "description": "Free-form JSON stored alongside the task. On updateTask this MERGES rather than replaces."
14403
+ },
14404
+ "fields": {
14405
+ "type": "array",
14406
+ "maxItems": 50,
14407
+ "items": {
14408
+ "type": "string",
14409
+ "maxLength": 64
14410
+ },
14411
+ "description": "Optional. Answer with only these fields instead of the whole task, for example [\"id\", \"versionTimestamp\"]. Any of the task's own fields (snake_case or camelCase) or of the keys around it in the full answer (versionTimestamp, href and, where present, url, title, trackingId, message). The id is always returned, and so is any notice that needs your attention (a note, such as a phase's dates following its tasks or an item's id changing with its type, and a date change's cascadePreview). Unknown names are ignored."
13339
14412
  }
13340
14413
  },
13341
14414
  "required": [
@@ -13424,7 +14497,7 @@
13424
14497
  "/tools/listTasks": {
13425
14498
  "post": {
13426
14499
  "summary": "listTasks",
13427
- "description": "List AND grep tasks in a plan. `query` searches the title, friendlyId and description, not just the title (substring by default; set isRegex:true for a regular expression, caseSensitive:true for exact case). Supports filtering by status, priority and phaseId.",
14500
+ "description": "List AND grep tasks in a plan. `query` searches the title, friendlyId and description, not just the title (substring by default; set isRegex:true for a regular expression, caseSensitive:true for exact case). Supports filtering by status, priority, phaseId and parentItemId (a story's tasks in the work hierarchy, say). Every task carries its versionTimestamp, ready for updateTask, so one call here supplies the tokens for a whole batch of updates, and its parent_item_id and parentItem (the item it belongs to in the work hierarchy, or null).",
13428
14501
  "operationId": "listTasks",
13429
14502
  "tags": [
13430
14503
  "plans"
@@ -13451,6 +14524,11 @@
13451
14524
  "type": "string",
13452
14525
  "description": "Filter by phase."
13453
14526
  },
14527
+ "parentItemId": {
14528
+ "type": "string",
14529
+ "maxLength": 64,
14530
+ "description": "Only the children of this item in the work hierarchy (its UUID or friendly id, such as IMP-12), whatever plan or phase they are in. \"none\" lists only the items with no parent. The work hierarchy is not the plan outline nesting (setPlanItemParent)."
14531
+ },
13454
14532
  "query": {
13455
14533
  "type": "string",
13456
14534
  "description": "Grep across title, friendlyId and description. Substring by default; a regular expression when isRegex:true; case-insensitive unless caseSensitive:true."
@@ -13565,7 +14643,7 @@
13565
14643
  "/tools/getTask": {
13566
14644
  "post": {
13567
14645
  "summary": "getTask",
13568
- "description": "Get a task by ID with full details, evidence, activity, and the `checklist` array (each item: id, text, due_date, completed_at, plus server-stamped attribution). Returns versionTimestamp; pass it to updateTask to modify. Includes percent_complete for progress tracking.",
14646
+ "description": "Get a task by ID with full details, evidence, activity, and the `checklist` array (each item: id, text, due_date, completed_at, plus server-stamped attribution). Returns versionTimestamp; pass it to updateTask to modify. Includes percent_complete for progress tracking. Also returns the work hierarchy: parentItem (the item this one belongs to, such as its epic or story: { id, friendlyId, title, type, status, isTask }, or null), children (the items that belong to it, in status order then by id, at most 200: each with ownerId, ownerTeamId and percentComplete) and childProgress { total, done, closed } over every child (closed counts done, rejected and deferred). Set a parent with parentItemId on updateImprovement or updateTask.",
13569
14647
  "operationId": "getTask",
13570
14648
  "tags": [
13571
14649
  "plans"
@@ -13671,7 +14749,7 @@
13671
14749
  "/tools/updateTask": {
13672
14750
  "post": {
13673
14751
  "summary": "updateTask",
13674
- "description": "Update a task. Tasks share a row with improvements (`improvement_items` with `is_task=true`), so this is a thin alias over updateImprovement — every field on updateImprovement is supported, including `checklist`, `acceptance_criteria`, dates, owner, percent_complete, etc. Requires versionTimestamp from getTask for optimistic locking. Statuses are captured / in_progress / blocked / done / rejected / deferred, and FOUR of those are CLOSED: blocked, done, rejected, deferred. Entering one needs its comment (blocked_comment / rejection_comment / completion_comment); leaving one for an open status needs reopened_comment — including blocked -> in_progress, which surprises people because `blocked` does not sound terminal. `metadata` MERGES into what is stored (null on a key deletes it); pass metadata_replace:true to overwrite the object wholesale. To edit checklist items: call getTask, modify the `checklist` array (preserving each row's `id` to keep its attribution stamps), and pass the full array back here — array order is the sort order. Assignment: pass `owner_id=<uuid>` to assign to a user, `owner_team_id=<uuid>` to assign to a team (mutually exclusive — the DB enforces with a CHECK constraint). To unassign, pass `owner_id=null` AND `owner_team_id=null`. To switch owner kind, send the new value AND null the old one in the SAME call.",
14752
+ "description": "Update a task, or many tasks in one call. Tasks share a row with improvements (`improvement_items` with `is_task=true`), so this is a thin alias over updateImprovement: every field on updateImprovement is supported, including `checklist`, `acceptance_criteria`, dates, owner, percent_complete, parentItemId (the story or requirement it belongs to in the work hierarchy), etc. versionTimestamp (optimistic locking) is the task's updated_at in epoch milliseconds, and you rarely need a getTask call for it: listTasks and getPlan (items[].versionTimestamp) return it for every task in a plan at once, and every write returns the task's new one. Pass `fields` (for example [\"id\", \"versionTimestamp\"]) for a short answer instead of the whole task. To change many tasks (a plan-wide re-date, say), send `items`: up to 200 entries of { taskId, versionTimestamp, ...changes } per call (more than 200: split them into several calls of up to 200), each checked and written on its own and answered with one row per entry plus a summary. Statuses are captured / in_progress / blocked / done / rejected / deferred, and FOUR of those are CLOSED: blocked, done, rejected, deferred. Entering one needs its comment (blocked_comment / rejection_comment / completion_comment); leaving one for an open status needs reopened_comment, including blocked -> in_progress, which surprises people because `blocked` does not sound terminal. `metadata` MERGES into what is stored (null on a key deletes it); pass metadata_replace:true to overwrite the object wholesale. To edit checklist items: call getTask, modify the `checklist` array (preserving each row's `id` to keep its attribution stamps), and pass the full array back here; array order is the sort order. Assignment: pass `owner_id=<uuid>` to assign to a user, `owner_team_id=<uuid>` to assign to a team (mutually exclusive: the DB enforces it with a CHECK constraint). To unassign, pass `owner_id=null` AND `owner_team_id=null`. To switch owner kind, send the new value AND null the old one in the SAME call.",
13675
14753
  "operationId": "updateTask",
13676
14754
  "tags": [
13677
14755
  "plans"
@@ -13687,21 +14765,49 @@
13687
14765
  "type": "string",
13688
14766
  "description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
13689
14767
  },
14768
+ "planId": {
14769
+ "type": "string",
14770
+ "description": "Optional. Narrows a friendly-id lookup (such as TAS-55) to one plan, given as the plan's UUID or friendly id (such as PLN-3): the task must be in that plan. It never moves anything (plan_id does that) and is ignored when the id is a UUID."
14771
+ },
13690
14772
  "taskId": {
13691
- "type": "string"
14773
+ "type": "string",
14774
+ "description": "Required unless you send items. The task's UUID or friendly id (such as TAS-55)."
13692
14775
  },
13693
14776
  "versionTimestamp": {
13694
14777
  "type": "number",
13695
- "description": "Version timestamp from getTask() for optimistic locking."
14778
+ "description": "Required unless you send items. The task's current versionTimestamp (its updated_at in epoch ms), as listTasks, getPlan, getTask or your last write of it returned."
13696
14779
  },
13697
14780
  "title": {
13698
14781
  "type": "string"
13699
14782
  },
13700
14783
  "type": {
13701
- "type": "string"
14784
+ "type": "string",
14785
+ "description": "Changing the type converts the task and its id takes the new type's prefix, keeping its number (TAS-12 becomes STY-12 as a user_story): the answer's note then gives the new id, and the old one still resolves."
14786
+ },
14787
+ "parentItemId": {
14788
+ "type": [
14789
+ "string",
14790
+ "null"
14791
+ ],
14792
+ "maxLength": 64,
14793
+ "description": "The work item this one belongs to in the work hierarchy: an epic for a story, a story for its tasks or test cases. Any item in the same project, in any plan or phase. Not the plan outline nesting, which setPlanItemParent sets. Give its UUID or friendly id (such as IMP-12 or TAS-3). Rules: the same project; no loops (an item cannot sit inside its own children); at most 5 levels, counting this item's own children. null removes the parent."
13702
14794
  },
13703
14795
  "status": {
13704
- "type": "string"
14796
+ "type": "string",
14797
+ "enum": [
14798
+ "captured",
14799
+ "triaging",
14800
+ "shaped",
14801
+ "approved",
14802
+ "ready_for_agent",
14803
+ "in_progress",
14804
+ "ready_for_review",
14805
+ "in_review",
14806
+ "blocked",
14807
+ "done",
14808
+ "rejected",
14809
+ "deferred"
14810
+ ]
13705
14811
  },
13706
14812
  "priority": {
13707
14813
  "type": "string"
@@ -13964,12 +15070,298 @@
13964
15070
  "phase_id": {
13965
15071
  "type": "string",
13966
15072
  "description": "Assign to phase. Null to unassign."
15073
+ },
15074
+ "fields": {
15075
+ "type": "array",
15076
+ "maxItems": 50,
15077
+ "items": {
15078
+ "type": "string",
15079
+ "maxLength": 64
15080
+ },
15081
+ "description": "Optional. Answer with only these fields instead of the whole task, for example [\"id\", \"versionTimestamp\"]. Any of the task's own fields (snake_case or camelCase) or of the keys around it in the full answer (versionTimestamp, href and, where present, url, title, trackingId, message). The id is always returned, and so is any notice that needs your attention (a note, such as a phase's dates following its tasks or an item's id changing with its type, and a date change's cascadePreview). Unknown names are ignored."
15082
+ },
15083
+ "items": {
15084
+ "type": "array",
15085
+ "minItems": 1,
15086
+ "maxItems": 200,
15087
+ "description": "Optional bulk form: update up to 200 tasks in one call, each entry { taskId, versionTimestamp, ...the fields to change } with the same fields as a single call. Every entry is checked and written on its own (permission, optimistic lock, audit), so one entry's conflict or error never stops the others. The answer has one row per entry, in your order: { index, id, status: \"updated\", versionTimestamp } or { index, id, status: \"conflict\" or \"failed\", error } (a conflict also carries currentVersionTimestamp), plus summary { requested, updated, failed, conflicts }. With items, send nothing else at the top level except projectId, planId and fields; fields then picks extra fields for each updated row (a row's status is its outcome, so the task's own status comes back as taskStatus).",
15088
+ "items": {
15089
+ "type": "object",
15090
+ "properties": {
15091
+ "taskId": {
15092
+ "type": "string"
15093
+ },
15094
+ "versionTimestamp": {
15095
+ "type": "number"
15096
+ },
15097
+ "title": {
15098
+ "type": "string"
15099
+ },
15100
+ "type": {
15101
+ "type": "string"
15102
+ },
15103
+ "parentItemId": {
15104
+ "type": [
15105
+ "string",
15106
+ "null"
15107
+ ],
15108
+ "maxLength": 64
15109
+ },
15110
+ "status": {
15111
+ "type": "string",
15112
+ "enum": [
15113
+ "captured",
15114
+ "triaging",
15115
+ "shaped",
15116
+ "approved",
15117
+ "ready_for_agent",
15118
+ "in_progress",
15119
+ "ready_for_review",
15120
+ "in_review",
15121
+ "blocked",
15122
+ "done",
15123
+ "rejected",
15124
+ "deferred"
15125
+ ]
15126
+ },
15127
+ "priority": {
15128
+ "type": "string"
15129
+ },
15130
+ "urgency": {
15131
+ "type": "string"
15132
+ },
15133
+ "owner_id": {
15134
+ "type": [
15135
+ "string",
15136
+ "null"
15137
+ ]
15138
+ },
15139
+ "owner_team_id": {
15140
+ "type": [
15141
+ "string",
15142
+ "null"
15143
+ ]
15144
+ },
15145
+ "target_date": {
15146
+ "type": "string"
15147
+ },
15148
+ "start_date": {
15149
+ "type": "string"
15150
+ },
15151
+ "end_date": {
15152
+ "type": "string"
15153
+ },
15154
+ "position": {
15155
+ "type": "number"
15156
+ },
15157
+ "description": {
15158
+ "type": "string"
15159
+ },
15160
+ "wbs_code": {
15161
+ "type": "string"
15162
+ },
15163
+ "percent_complete": {
15164
+ "type": "number"
15165
+ },
15166
+ "problem_statement": {
15167
+ "type": "string"
15168
+ },
15169
+ "desired_outcome": {
15170
+ "type": "string"
15171
+ },
15172
+ "business_impact": {
15173
+ "type": "string"
15174
+ },
15175
+ "user_impact": {
15176
+ "type": "string"
15177
+ },
15178
+ "why_now": {
15179
+ "type": "string"
15180
+ },
15181
+ "acceptance_criteria": {
15182
+ "type": "array",
15183
+ "items": {
15184
+ "anyOf": [
15185
+ {
15186
+ "type": "string"
15187
+ },
15188
+ {
15189
+ "type": "object",
15190
+ "properties": {
15191
+ "id": {
15192
+ "type": "string"
15193
+ },
15194
+ "text": {
15195
+ "type": "string"
15196
+ },
15197
+ "updated_at": {
15198
+ "type": "string"
15199
+ },
15200
+ "updated_by": {
15201
+ "type": "string"
15202
+ },
15203
+ "updated_by_credential_name": {
15204
+ "type": "string"
15205
+ }
15206
+ },
15207
+ "required": [
15208
+ "text"
15209
+ ]
15210
+ }
15211
+ ]
15212
+ }
15213
+ },
15214
+ "checklist": {
15215
+ "type": "array",
15216
+ "items": {
15217
+ "type": "object",
15218
+ "properties": {
15219
+ "id": {
15220
+ "type": "string"
15221
+ },
15222
+ "text": {
15223
+ "type": "string"
15224
+ },
15225
+ "due_date": {
15226
+ "type": "string"
15227
+ },
15228
+ "completed": {
15229
+ "type": "boolean"
15230
+ },
15231
+ "completed_at": {
15232
+ "type": "string"
15233
+ },
15234
+ "completed_by": {
15235
+ "type": "string"
15236
+ },
15237
+ "completed_by_credential_name": {
15238
+ "type": "string"
15239
+ },
15240
+ "updated_at": {
15241
+ "type": "string"
15242
+ },
15243
+ "updated_by": {
15244
+ "type": "string"
15245
+ },
15246
+ "updated_by_credential_name": {
15247
+ "type": "string"
15248
+ }
15249
+ },
15250
+ "required": [
15251
+ "text"
15252
+ ]
15253
+ }
15254
+ },
15255
+ "constraints": {
15256
+ "type": "array",
15257
+ "items": {
15258
+ "type": "string"
15259
+ }
15260
+ },
15261
+ "non_goals": {
15262
+ "type": "array",
15263
+ "items": {
15264
+ "type": "string"
15265
+ }
15266
+ },
15267
+ "impacted_documents": {
15268
+ "type": "array",
15269
+ "items": {
15270
+ "type": "object"
15271
+ }
15272
+ },
15273
+ "linked_document_ids": {
15274
+ "type": "array",
15275
+ "items": {
15276
+ "type": "string"
15277
+ }
15278
+ },
15279
+ "impacted_diagrams": {
15280
+ "type": "array",
15281
+ "items": {
15282
+ "type": "object"
15283
+ }
15284
+ },
15285
+ "impacted_components": {
15286
+ "type": "array",
15287
+ "items": {
15288
+ "type": "string"
15289
+ }
15290
+ },
15291
+ "impacted_repositories": {
15292
+ "type": "array",
15293
+ "items": {
15294
+ "type": "string"
15295
+ }
15296
+ },
15297
+ "agent_ready": {
15298
+ "type": "boolean"
15299
+ },
15300
+ "agent_missing_info": {
15301
+ "type": "array",
15302
+ "items": {
15303
+ "type": "string"
15304
+ }
15305
+ },
15306
+ "agent_recommended_action": {
15307
+ "type": "string"
15308
+ },
15309
+ "agent_complexity": {
15310
+ "type": "string"
15311
+ },
15312
+ "agent_confidence": {
15313
+ "type": "number"
15314
+ },
15315
+ "agent_brief": {
15316
+ "type": "string"
15317
+ },
15318
+ "resolution_summary": {
15319
+ "type": "string"
15320
+ },
15321
+ "resolution_pr_url": {
15322
+ "type": "string"
15323
+ },
15324
+ "docs_updated": {
15325
+ "type": "boolean"
15326
+ },
15327
+ "follow_up_needed": {
15328
+ "type": "boolean"
15329
+ },
15330
+ "blocked_comment": {
15331
+ "type": "string"
15332
+ },
15333
+ "rejection_comment": {
15334
+ "type": "string"
15335
+ },
15336
+ "completion_comment": {
15337
+ "type": "string"
15338
+ },
15339
+ "reopened_comment": {
15340
+ "type": "string"
15341
+ },
15342
+ "relationships": {
15343
+ "type": "object"
15344
+ },
15345
+ "metadata": {
15346
+ "type": "object"
15347
+ },
15348
+ "metadata_replace": {
15349
+ "type": "boolean"
15350
+ },
15351
+ "plan_id": {
15352
+ "type": "string"
15353
+ },
15354
+ "phase_id": {
15355
+ "type": "string"
15356
+ }
15357
+ },
15358
+ "required": [
15359
+ "taskId",
15360
+ "versionTimestamp"
15361
+ ]
15362
+ }
13967
15363
  }
13968
- },
13969
- "required": [
13970
- "taskId",
13971
- "versionTimestamp"
13972
- ]
15364
+ }
13973
15365
  }
13974
15366
  }
13975
15367
  }
@@ -14158,7 +15550,7 @@
14158
15550
  "/tools/setPlanItemParent": {
14159
15551
  "post": {
14160
15552
  "summary": "setPlanItemParent",
14161
- "description": "Set or clear the WBS parent-child nesting of a task/improvement (outline hierarchy, no scheduling effect). Same plan and phase required. Max depth: 5.",
15553
+ "description": "Set or clear the plan outline (WBS) nesting of a task or improvement: the indent inside one plan phase, with no scheduling effect. Parent and child must be in the same plan and the same phase, and the WBS numbers are recalculated. Max depth: 5. This is NOT the work hierarchy: for an epic's stories or a story's tasks or test cases, in any plan or phase, set parentItemId with createImprovement, updateImprovement, createTask or updateTask instead.",
14162
15554
  "operationId": "setPlanItemParent",
14163
15555
  "tags": [
14164
15556
  "plans"
@@ -14172,11 +15564,11 @@
14172
15564
  "properties": {
14173
15565
  "itemId": {
14174
15566
  "type": "string",
14175
- "description": "Item ID to re-parent."
15567
+ "description": "Item ID to indent or un-indent in the plan outline."
14176
15568
  },
14177
15569
  "parentId": {
14178
15570
  "type": "string",
14179
- "description": "New parent ID. Null to un-indent."
15571
+ "description": "The outline parent's ID, in the same plan and phase. Null to un-indent. Not the work hierarchy parent (parentItemId)."
14180
15572
  }
14181
15573
  },
14182
15574
  "required": [