tdoms-mcp 0.6.2 → 0.7.0

package/README.md

@@ -66,6 +66,12 @@ tool_timeout_sec = 60
 
 Restart or reload the agent's MCP servers after changing the configuration.
 
+## Agent Skill
+
+The package includes a portable developer skill at `skills/tdoms-mcp-routing`. Its `SKILL.md` teaches agents how to select core, full-profile, or Octo tools; discover site-specific values; perform guarded task, source, compile, checkout, promote, transfer, branch, and approval workflows; and verify final TD/OMS state.
+
+Agents that support `SKILL.md` folders can register that directory using their normal skill installation mechanism. The skill contains no credentials, connection profiles, organization-specific values, or personal information. Runtime tool schemas and values returned by the connected TD/OMS server remain authoritative.
+
 Detect supported local clients from the installed command:
 
 ```shell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tdoms-mcp",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Agent-neutral MCP server for TD/OMS change-management workflows.",
   "type": "module",
   "license": "MIT",

package/skills/tdoms-mcp-routing/SKILL.md

@@ -1,48 +1,89 @@
 ---
 name: tdoms-mcp-routing
-description: Use TD/OMS change management through the standalone TD/OMS MCP or Octo MCP tools. Trigger for tasks, requests, source, objects, checkout, promote, transfer, compile, branches, connection lists, logs, spool files, conflicts, labels, and other TD/OMS workflows, especially when an agent incorrectly asks for Octo sign-in or a programmer ID.
+description: Operate TD/OMS change management through the standalone TD/OMS MCP or, when necessary, the Octo extension MCP. Use for developer workflows involving tasks, requests, objects, source, checkout, promote, transfer, compile, branches, solutions, connection lists, logs, spool files, revisions, conflicts, ratification, labels, trackers, remote jobs, or TD/OMS option discovery. Also use when choosing between standalone and Octo tools, diagnosing Octo sign-in or programmer-context failures, or explaining TD/OMS MCP capabilities and limits.
 ---
 
 # TD/OMS MCP Routing
 
-Prefer the standalone TD/OMS MCP when available. It works independently of the Octo VS Code UI.
+Use the standalone MCP as the primary automation surface. It talks to the configured TD/OMS REST server and does not control VS Code or require an Octo session.
 
-## Standalone Core Flow
+## Load References Deliberately
 
-1. Call `tdoms_get_current_context`. Let it select the only connection and derive the TD/OMS programmer ID from the saved profile.
-2. Call `tdoms_list_capabilities` when the requested workflow or required choices are unclear.
-3. Call `tdoms_discover_options` before choosing application, environment, programmer, path, reason, target, object, template, conflict resolution, or any site-specific value.
-4. Use `tdoms_discover_options` for structured task, request, component, source, queue, compile, history, log, spool, tracker, dependency, and dashboard reads.
-5. For changes, call `tdoms_plan_workflow` with the exact context, selections, and `optionSelections` for values returned by discovery. Show the user its action, target, endpoint/body preview, warnings, and blockers.
-6. Call `tdoms_execute_workflow` with the returned `planId` and `confirm: true` only after the user approves that exact preview.
-7. Call `tdoms_get_workflow_status` for asynchronous work.
+- Read [references/workflow-playbooks.md](references/workflow-playbooks.md) before performing a domain workflow such as checkout, promote, source save, compile, completion, ratification, branch work, or conflict handling.
+- Read [references/tool-and-extension-map.md](references/tool-and-extension-map.md) when selecting tools, comparing the standalone MCP with Octo, or checking whether a capability is core-only, full-profile, UI-only, or unsupported.
+- Read [references/tdoms-domain-and-sources.md](references/tdoms-domain-and-sources.md) when terminology, lifecycle semantics, source authority, or version differences matter.
 
-Never guess a value when discovery returns no choices or `supported: false`. Ask one concise question instead.
+## Establish Runtime Context
 
-For "my tasks," use option set `tasks` without supplying a programmer. The MCP uses the saved TD/OMS username automatically. Set `context.allUsers: true` only when the user requests tasks for everyone.
+1. Inspect the tools actually available in the current agent session. Runtime tool schemas override this skill if names or inputs differ.
+2. Call `tdoms_list_connections`.
+3. If exactly one connection exists, omit `connectionId` where the schema permits and call `tdoms_get_current_context`.
+4. If several connections exist, select only from the returned profiles. Ask the user to choose when the request does not identify one.
+5. If no connection exists, direct the user to save and test one through `tdoms-mcp ui`. Never request a password, token, or certificate contents in chat.
+6. Treat `user.programmerId` from current context as the default identity for "my" records. Do not ask for a programmer ID unless the user is reassigning work, selecting another programmer, or the server cannot derive one.
 
-## Mutation Rules
+## Choose the Surface
 
-- Read current state before planning.
-- Treat source saves, checkout, promote, transfer, compile, complete, delete, process, queue, release, close, and configuration changes as mutations.
-- Never set `confirm: true` without explicit approval of the current plan.
-- Stop when TD/OMS reports warnings, locks, conflicts, authority failures, or changed state. Summarize the result and replan if needed.
-- Never ask the user to paste TD/OMS credentials into chat.
+- Prefer the seven `core` tools for portable agent workflows and small tool budgets.
+- Use `tdoms_discover_options` for both choices and structured reads that replace Octo views.
+- Use `tdoms_plan_workflow` and `tdoms_execute_workflow` whenever the requested mutation appears in `tdoms_list_capabilities`.
+- Use a `full` named tool when no core capability exists or when a typed tool gives safer inputs, richer diagnostics, or a complete read workflow.
+- Use Octo tools only when the user explicitly needs an Octo panel/editor or when the standalone MCP lacks the required TD/OMS or Octo-cloud operation.
+- Do not use `tdoms_call_api` until named and planned tools have been ruled out and the endpoint and body are documented for the connected TD/OMS version.
 
-## Full Profile
+## Read Workflow
 
-When `TDOMS_MCP_PROFILE=full`, prefer a specific named read tool when it is clearer than generic discovery. Named mutation tools still require explicit approval and `confirm: true`.
+1. Resolve context.
+2. Call `tdoms_list_capabilities` if the workflow is unclear.
+3. Call `tdoms_discover_options` with the relevant `optionSet`, narrow context, and pagination.
+4. Treat returned `value` fields as machine inputs and `label` fields as display text.
+5. Honor `enabled`, `source.authoritative`, `warnings`, and `supported`.
+6. Follow pagination rather than assuming the first page is complete.
+7. Verify the returned application, task, environment, object, library, member, or path before reporting results.
 
-Use typed transfer tools in this sequence: select targets, prepare, inspect warnings, execute, then monitor progress. Use typed source tools to read the latest source and last-change marker before saving. Use compile-and-check to retrieve diagnostics instead of asking the user to paste spool output.
+For "my tasks," discover `tasks` without a programmer filter. The MCP applies the saved TD/OMS username in uppercase. Set `context.allUsers: true` only when the user requests a cross-user search.
 
-## Octo MCP Fallback
+## Planned Mutation Workflow
 
-If only the extension MCP is available:
+Follow this sequence for every supported core mutation:
 
-- Use `OMS-Database-REST-API.getRecords` for reads and task lists.
-- Use `TD-OMS-Task-API` only for task mutations.
-- Use `TD-OMS-Branch-Service-API` for branch mutations.
-- Treat `Octo-Views` and `Octo-Wizards` as UI launchers, not proof that an action completed.
-- Do not require `Octo-User-Context` before direct TD/OMS reads.
+1. Read the current state.
+2. Discover every site-specific choice required by the capability.
+3. Call `tdoms_plan_workflow` with:
+   - the exact capability `workflow` id;
+   - stable identifiers in `context`;
+   - mutation fields in `selections`;
+   - each chosen discovery value in `optionSelections`, keyed by option-set name.
+4. Stop on blockers. Never invent a missing option or silently replace an unavailable choice.
+5. Present the plan title, target, endpoint/body preview, warnings, and expiry to the user.
+6. Obtain explicit approval for that exact preview.
+7. Call `tdoms_execute_workflow` with the matching `planId` and `confirm: true`.
+8. Call `tdoms_get_workflow_status` and/or a domain read to verify the postcondition.
 
-If Octo user context says sign-in is required but a direct TD/OMS read succeeds, continue with the direct tool and report that the Octo UI context is stale. Retry programmer filters in uppercase before reporting that no tasks exist.
+Plans expire after ten minutes, execute once, and are rejected if state or selected options change. Re-discover and replan instead of trying to force a stale plan.
+
+## Full-Profile Mutation Workflow
+
+Some full-profile actions, including task creation, source save, compile, connection-list processing, and several branch or request actions, are not represented by a core plan id.
+
+1. Read current state and discover choices first.
+2. Prefer a typed named tool over an `*_action` tool or raw API call.
+3. Construct the exact arguments but do not call the mutation yet.
+4. Show the user the action, target, important fields, and likely effect.
+5. Call the named tool with `confirm: true` only after explicit approval.
+6. Re-read TD/OMS to verify the result. A successful transport response is not sufficient proof of the final lifecycle state.
+
+## Safety And Failure Rules
+
+- Treat create, change, save, connect, disconnect, process, queue, release, checkout, promote, transfer, complete, ratify, resolve, close, schedule, delete, purge, and configuration operations as mutations.
+- Do not equate `OMQRTO/select` with a completed transfer; it discovers eligible targets and may initialize preparatory server state.
+- Stop on authority errors, locks, pre-transfer checks, warnings requiring a decision, version conflicts, stale source markers, compile failures, or changed task state.
+- Preserve server casing and exact codes. Retry a programmer lookup in uppercase only when identity-derived lookup returned no records.
+- Do not broaden to all users, all applications, or unfiltered database queries without a user need.
+- Do not claim that an Octo wizard or view launcher completed work. It only opened UI.
+- If Octo user context reports sign-in required but standalone reads succeed, continue through the standalone MCP and describe the Octo session as separate or stale.
+- Never expose saved connection metadata beyond what the task requires. Never print passwords, JWTs, master keys, CA contents, local credential files, or personal filesystem paths.
+
+## Finish With Evidence
+
+Report the identifiers used, the observed final state, warnings that remain, and any follow-up state check needed. Distinguish clearly between planned, submitted, queued, running, completed, rejected, and unsupported work.

package/skills/tdoms-mcp-routing/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "TD/OMS MCP Routing"
-  short_description: "Route TD/OMS change-management workflows"
-  default_prompt: "Use $tdoms-mcp-routing to handle this TD/OMS request safely through MCP."
+interface:
+  display_name: "TD/OMS Change Management"
+  short_description: "Run safe TD/OMS developer workflows"
+  default_prompt: "Use $tdoms-mcp-routing to execute this TD/OMS developer workflow with live option discovery, explicit approval, and final-state verification."

package/skills/tdoms-mcp-routing/references/tdoms-domain-and-sources.md

@@ -0,0 +1,78 @@
+# TD/OMS Domain And Sources
+
+## Contents
+
+- Source authority
+- Domain model
+- Change lifecycle
+- Version and site variability
+- Public references
+
+## Source Authority
+
+Use evidence in this order:
+
+1. Live MCP tool names, schemas, and responses.
+2. Choices returned by the connected TD/OMS server.
+3. The standalone MCP capability registry and typed tool implementation for the installed package version.
+4. Documentation supplied by the user's TD/OMS administrators for that server version and site policy.
+5. Official public Remain Software product, marketplace, and release documentation for conceptual context.
+6. This skill's audited extension comparison as a versioned compatibility snapshot.
+
+Do not derive REST payloads, reason codes, environment codes, or authorization decisions from marketing pages. Public documentation establishes concepts; live schemas and server responses establish executable values.
+
+## Domain Model
+
+- Application: the TD/OMS-managed software scope. Applications define environment and workflow context.
+- Environment: a lifecycle location such as development, test, acceptance, emergency, or production. Actual codes and paths are site-defined.
+- Request: a higher-level change or business request that may connect to tasks.
+- Task/fix: the principal unit of assigned change work, lifecycle status, programmer ownership, and transfer control.
+- Solution: a task-connected change record for an object/component.
+- Object/component: a managed deployable or source-backed artifact. IBM i identity commonly includes object name, type, library, and optional member/detail.
+- Source: editable content associated with a managed object or IFS item. Saves require current identity and concurrency markers.
+- Branch/path: site-defined routing or isolation metadata controlling where work moves.
+- Transfer: the controlled movement of task objects/solutions between lifecycle environments.
+- Checkout: a transfer that brings eligible managed content into a development context.
+- Promote: a transfer that advances completed work toward a later environment.
+- Build queue/compile: asynchronous object creation work with queue state, compile results, event records, logs, and spool files.
+- Ratification: an approval/rejection gate used for peer review, user acceptance, management approval, or another configured quality gate.
+- Revision/conflict: archived or competing versions used for compare, history, and controlled resolution.
+
+These relationships are stable concepts, but field names, statuses, reasons, transfer paths, and policy gates are configured per site.
+
+## Change Lifecycle
+
+A robust agent workflow follows:
+
+1. Identify the application and current task/request.
+2. Read the assigned programmer, status, path, environment, objects, and relevant history.
+3. Discover allowed choices from the connected server.
+4. Connect or create the intended object/solution under the task.
+5. Read and edit source with concurrency protection.
+6. Compile and inspect terminal diagnostics.
+7. Review dependencies, conflicts, labels/comments, and required approvals.
+8. Prepare checkout/promote/transfer and inspect pre-transfer checks.
+9. Execute only after explicit approval.
+10. Monitor asynchronous work and verify final TD/OMS state.
+11. Complete or ratify only when site policy and observed state allow it.
+
+This is a decision framework, not a universal site policy. The connected server remains authoritative.
+
+## Version And Site Variability
+
+- TD/OMS and Octo evolve independently and expose different capabilities by release.
+- Octo views and wizards are UI affordances; their visible fields may be populated by multiple TD/OMS APIs and database views.
+- Some option lists are authoritative configuration reads. Others are inferred from values present in existing records and are marked non-authoritative by the MCP.
+- Tracker integration, user options, compile overrides, templates, action groups, transfer checks, and ratification are especially site-specific.
+- Internal or licensed REST documentation may be available to a user's organization. Use it when supplied, but do not reproduce confidential material in public skill output.
+
+## Public References
+
+- [TD/OMS product overview](https://remainsoftware.com/tdoms/) describes TD/OMS as application lifecycle and change management across IBM i, Windows, and Unix/Linux, including development, test, acceptance, deployment, impact analysis, version history, and ratification.
+- [Octo TD/OMS Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=remainsoftware.octo-tdoms) documents Work Management, task details, source editing, object connection, checkout/promote, build queue, spool files, IFS, revision compare, analytics, dependencies, and Kanban in Octo.
+- [TD/OMS productivity](https://remainsoftware.com/td-oms-increases-alm-productivity/) provides conceptual background for impact analysis, compare/merge, controlled deployment, rollback, transfer logs, and multi-platform deployment.
+- [TD/OMS collaboration](https://remainsoftware.com/td-oms-increases-alm-collaboration/) explains ratification as a configurable approval process used for peer review, acceptance, or promotion gates.
+- [TD/OMS V17.0.1 release](https://remainsoftware.com/news/new-release-td-oms-v17-0-milestone-1-2/) documents Octo transfer history, version conflicts, impact analysis, compile results, and members in component views.
+- [Web and VS Code TD/OMS V17.0.2 release](https://remainsoftware.com/news/new-release-web-and-vscode-td-oms-v17-0-milestone-2/) documents compile-error visualization, transfer/log history, compile overrides, transfer-path behavior, programmer assignment, ratification history, and build-queue integrations.
+
+Public pages are contextual sources only. Always defer executable details to the live MCP schema and the connected TD/OMS server.

package/skills/tdoms-mcp-routing/references/tool-and-extension-map.md

@@ -0,0 +1,150 @@
+# Tool And Extension Map
+
+## Contents
+
+- Runtime profiles
+- Core interface
+- Discovery option sets
+- Core capability registry
+- Full-profile families
+- Octo extension comparison
+- View replacements
+- Intentional exclusions
+
+## Runtime Profiles
+
+The standalone server has two profiles:
+
+- `core`: 7 agent-neutral tools. Prefer this for broad client compatibility and limited tool budgets.
+- `full`: 226 named tools in the audited release. Prefer this for typed direct actions, specialized reads, and developer diagnostics.
+
+Counts are a release snapshot, not an API contract. Inspect the live MCP tool list and schemas before acting.
+
+## Core Interface
+
+| Tool | Purpose |
+| --- | --- |
+| `tdoms_list_connections` | List saved local connection profiles without returning secrets. |
+| `tdoms_get_current_context` | Resolve connection, TD/OMS username/programmer identity, applications, and environments. |
+| `tdoms_list_capabilities` | Return workflow ids, option sets, required context, mode, support, and Octo wizard mapping. |
+| `tdoms_discover_options` | Return normalized choices or structured records from TD/OMS. |
+| `tdoms_plan_workflow` | Create a read-only mutation preview and ten-minute plan. |
+| `tdoms_execute_workflow` | Revalidate and execute one approved plan. |
+| `tdoms_get_workflow_status` | Read plan state and execution result. |
+
+## Discovery Option Sets
+
+Discovery exposes 40 option sets. Use the exact runtime enum if it differs.
+
+- Identity and configuration: `applications`, `environments`, `programmers`, `userClasses`.
+- Task metadata: `taskStatuses`, `taskTypes`, `releases`, `priorities`, `completionReasons`, `ratificationReasons`.
+- Change structure: `branchesPaths`, `taskObjects`, `solutions`, `solutionTypes`, `memberAttributes`, `labels`.
+- Transfer and build: `transferTargets`, `subEnvironments`, `compileOverrides`, `conflicts`, `schedules`, `remoteJobs`.
+- Creation and history: `objectTemplates`, `objectLocations`, `revisions`, `userOptions`, `trackerLinks`.
+- Structured view reads: `tasks`, `requests`, `components`, `connectionLists`, `buildQueue`, `compileResults`, `transferHistory`, `logs`, `spoolFiles`, `trackerRecords`, `source`, `dependencies`, `dashboards`.
+
+`OMSINFO/system`, `OMQRTO/select`, and `OMQRNO/location` results are authoritative for their returned choices. Several database-derived metadata lists are marked non-authoritative because they infer valid values from existing records. Respect `source.authoritative` in every response.
+
+## Core Capability Registry
+
+The registry mirrors the 28 audited Octo wizards as structured workflows. It contains 24 supported mutations, 3 supported read-only capabilities, and 1 Octo-only unsupported capability.
+
+| Workflow id | Mode | Required option sets or note |
+| --- | --- | --- |
+| `change-member-attribute` | Mutation | `memberAttributes` |
+| `change-programmer` | Mutation | `programmers`, `userClasses` |
+| `change-solution-type` | Mutation | `solutions`, `solutionTypes` |
+| `change-task-transfer-path` | Mutation | `branchesPaths` |
+| `compile-override` | Mutation | `compileOverrides`, `taskObjects` |
+| `complete-task` | Mutation | `completionReasons` |
+| `delete-objects` | Mutation | `taskObjects` |
+| `disconnect-solutions` | Mutation | `solutions` |
+| `display-message` | Read-only | Return message data; no window is opened. |
+| `edit-branch` | Mutation | `branchesPaths` |
+| `fill-object-file` | Mutation | `taskObjects` |
+| `manage-label` | Mutation | `labels` |
+| `link-issue-to-task` | Mutation | `trackerLinks` |
+| `link-task-to-issue` | Mutation | `trackerLinks` |
+| `move-solutions` | Mutation | `solutions`, `branchesPaths` |
+| `new-object` | Mutation | `objectTemplates`, `objectLocations` |
+| `new-task-branch` | Mutation | `branchesPaths` |
+| `close-remote-job` | Mutation | `remoteJobs`, `completionReasons` |
+| `reopen-remote-job` | Mutation | `remoteJobs` |
+| `schedule-remote-job` | Mutation | `remoteJobs`, `schedules` |
+| `revision-compare` | Read-only | `revisions` |
+| `solution-conflict` | Read-only | Discover `solutions` and `conflicts`; resolution is site-specific. |
+| `task-ratification` | Mutation | `ratificationReasons`, `programmers` |
+| `tracker-server-manager` | Unsupported | Octo configuration; no known TD/OMS REST endpoint. |
+| `transfer` | Mutation | `taskObjects`, `transferTargets`, `subEnvironments` |
+| `unlink-task-from-issue` | Mutation | `trackerLinks` |
+| `execute-user-option` | Mutation | `userOptions` |
+| `resolve-version-conflict` | Mutation | `conflicts` |
+
+The registry is not the complete full-profile capability list. For example, task creation, request creation, source saves, compile queue work, branch stash/restore/purge, and connection-list processing use full named tools.
+
+## Full-Profile Families
+
+Prefer the most specific tool whose schema matches the operation.
+
+- Context and connection: `tdoms_connection_*`, `tdoms_get_system_info`.
+- Tasks: `tdoms_task_*`, `tdoms_create_task`, `tdoms_search_tasks`.
+- Requests: `tdoms_request_*`.
+- Solutions and objects: `tdoms_solution_*`, `tdoms_object_*`, `tdoms_component_*`.
+- Source and IFS: `tdoms_read_source_all`, `tdoms_save_source_all`, `tdoms_patch_source_literal`, `tdoms_source_*`, `tdoms_ifs_*`.
+- New objects: `tdoms_new_object_location`, `tdoms_new_object_create`, `tdoms_new_source_member_create`.
+- Transfer: `tdoms_transfer_select_targets`, `tdoms_transfer_prepare`, `tdoms_transfer_execute_number`, `tdoms_transfer_progress_number`, plus typed checkout/promote tools.
+- Compile: `tdoms_compile_and_check`, `tdoms_compile_*`, `tdoms_build_queue_*`, `tdoms_compile_override_*`.
+- Branches: `tdoms_branch_*`.
+- Connection lists: `tdoms_connection_list_*`.
+- History and diagnostics: `tdoms_transfer_history`, `tdoms_log_*`, `tdoms_spool_*`, `tdoms_remote_job_*`.
+- Governance and metadata: `tdoms_comment_*`, `tdoms_label_*`, `tdoms_user_option_*`, `tdoms_version_conflict_*`.
+- Analysis and views: `tdoms_analysis_*`, `tdoms_dashboard_*`, `tdoms_kanban_*`, `tdoms_tracker_*`.
+- Advanced: `tdoms_query_database`, administration tools, family `*_action` tools, and `tdoms_call_api`.
+
+Specific typed tools should outrank family action tools. Family action tools should outrank `tdoms_call_api`.
+
+## Octo Extension Comparison
+
+The extension audit was performed against Octo TD/OMS `1.5.1260701`. Its 95 tools were grouped as follows:
+
+| Extension group | Count | Standalone relationship |
+| --- | ---: | --- |
+| Branch API | 7 | Covered by full `tdoms_branch_*`; selected branch workflows also have core plans. |
+| Task API | 11 | Covered by full `tdoms_task_*`; selected task workflows also have core plans. |
+| Database REST API | 1 | Covered by discovery and full `tdoms_query_database`. |
+| Octo Views | 20 | Replaced by structured reads; no VS Code panel is opened. |
+| Octo Wizards | 28 | Mapped into the core capability registry; tracker server manager remains Octo-only. |
+| Octo local/context utilities | 28 | Mostly intentionally excluded; agents already provide generic text, crypto, and encoding utilities. |
+
+The standalone MCP adds many REST operations that the extension exposes only indirectly through UI services or internal clients. It also adds option normalization, automatic connection-derived identity, token refresh, read-only planning, plan expiry, state revalidation, confirmation gates, and post-operation status reads.
+
+Do not describe this as visual parity. It provides TD/OMS data and change-management parity where documented, not VS Code panels, editors, decorations, command-palette behavior, Octo mail, or Octo session management.
+
+## View Replacements
+
+| Octo view intent | Core discovery or full named read |
+| --- | --- |
+| Work Management | `tasks`, `requests`; `tdoms_task_search`, `tdoms_request_search` |
+| Branches | `branchesPaths`; `tdoms_branch_search`, `tdoms_branch_get` |
+| Task Editor | `tdoms_task_details` or task-related option sets |
+| Component Editor / Components | `components`, `taskObjects`; object/component detail tools |
+| Solution Editor | `solutions`; `tdoms_solution_details` |
+| Source Editor | `source`; `tdoms_read_source_all` |
+| Spool source/files | `spoolFiles`; spool list/fetch tools |
+| Build Queue | `buildQueue`; build-queue tools |
+| Analytics | `dashboards`; dashboard and analysis tools |
+| Connection List | `connectionLists`; connection-list tools |
+| Dependency Graph | `dependencies`; analysis tools |
+| Transfer History | `transferHistory`; transfer-history tools |
+| Log History / Details | `logs`; log tools |
+| Tracker | `trackerRecords`; tracker tools |
+| Compile Result | `compileResults`; compile-result/error tools |
+| Remote Job Monitor | `remoteJobs`; remote-job tools |
+
+## Intentional Exclusions
+
+- Octo mail notification is not a TD/OMS change-management operation.
+- Generic hashing, UUID, Base64, JSON, URL, time, byte-size, EBCDIC, and packed-decimal utilities are not duplicated.
+- Tracker server administration remains Octo-only without a documented TD/OMS endpoint.
+- UI-only navigation and editor state are not controlled.
+- Site-specific behavior without an authoritative API choice is returned as unsupported instead of guessed.

package/skills/tdoms-mcp-routing/references/workflow-playbooks.md

@@ -0,0 +1,205 @@
+# TD/OMS Workflow Playbooks
+
+## Contents
+
+- Common preflight
+- Find my work
+- Task and request lifecycle
+- Source changes
+- New objects and members
+- Checkout, promote, and transfer
+- Compile and diagnostics
+- Solutions, components, and connection lists
+- Branches and paths
+- Completion and ratification
+- Revisions and conflicts
+- Logs, spool files, and remote jobs
+- Labels, comments, user options, and trackers
+- Analytics, dependencies, and Kanban
+- Failure recovery
+
+## Common Preflight
+
+For every playbook:
+
+1. List connections and resolve current context.
+2. Keep application, task/request number, environment, path, object, library, type, and member as separate fields.
+3. Discover site values instead of using examples from documentation.
+4. Read current state before a mutation.
+5. Use a core plan when a matching capability id exists.
+6. Otherwise preview a full named mutation and obtain explicit approval before `confirm: true`.
+7. Verify the postcondition with a fresh read.
+
+## Find My Work
+
+Core:
+
+1. Call `tdoms_get_current_context`.
+2. Discover `tasks` with application/status/search filters as needed. Do not pass programmer for "my tasks."
+3. Page until the requested scope is satisfied.
+4. For one task, discover `taskObjects`, `solutions`, `buildQueue`, `compileResults`, `transferHistory`, `logs`, and `trackerRecords` only as needed.
+
+Full:
+
+- Use `tdoms_task_search` for lists and `tdoms_task_details` for an aggregate view.
+- Use `tdoms_task_objects`, `tdoms_task_requests`, `tdoms_task_tickets`, `tdoms_task_comments`, and similar reads for focused follow-up.
+
+If no task is found, retry the derived programmer in uppercase before reporting no records. Do not broaden to all programmers automatically.
+
+## Task And Request Lifecycle
+
+Creating a task or request requires the full profile:
+
+1. Discover applications, programmers, task types, releases, priorities, paths, or request metadata required by the live tool schema.
+2. Build a preview for `tdoms_create_task` or `tdoms_request_create`.
+3. Obtain approval, call with `confirm: true`, then fetch the created identifier.
+
+For supported changes such as programmer, path, completion, ratification, and ticket links, prefer the matching core capability. Use full `tdoms_task_*` and `tdoms_request_*` for status, copy, delete, request connections, and other lifecycle actions absent from the core registry.
+
+Never infer that a task is ready to complete from its description. Read objects, build state, transfer state, conflicts, and site-required reasons first.
+
+## Source Changes
+
+1. Resolve the exact object, type, library, member/detail, application, and task.
+2. Read all pages with core `source` discovery or full `tdoms_read_source_all`.
+3. Preserve the returned last-change marker and encoding metadata.
+4. Make the smallest requested edit locally.
+5. Show a concise diff and target identity.
+6. Obtain approval.
+7. Prefer `tdoms_patch_source_literal` for a narrow literal replacement or `tdoms_save_source_all` for a complete save. Pass the latest change marker.
+8. Re-read source and compare the saved text.
+
+Use `tdoms_ifs_read`, `tdoms_ifs_save`, and `tdoms_ifs_compare` for IFS content. Stop on stale markers or object locks and re-read before retrying.
+
+## New Objects And Members
+
+1. Discover application, environment, task, object type, and attribute.
+2. Call core discovery for `objectLocations`/`objectTemplates` or full `tdoms_new_object_location`.
+3. Use only returned libraries, source files, templates, and defaults.
+4. For a new object, use the core `new-object` plan or full `tdoms_new_object_create`.
+5. For a member in an existing source file, use `tdoms_new_source_member_create`.
+6. Verify the object/component record and source location after creation.
+
+Keep TD/OMS field distinctions exact: the new-object API uses `task`, `newObject`, `newObjectLibrary`, `newObjectType`, and `newAttribute`. Do not substitute similarly named task/object fields from other APIs.
+
+## Checkout, Promote, And Transfer
+
+Never jump directly to execute.
+
+Core planned flow:
+
+1. Discover `taskObjects`.
+2. Discover `transferTargets` and `subEnvironments` with action, application, task, source environment, and object list.
+3. Plan workflow `transfer` with exact returned options.
+4. Review source, target, objects, action, warnings, and preview.
+5. Approve and execute the plan.
+6. Read workflow status and transfer history.
+
+Full typed flow:
+
+1. Call `tdoms_transfer_select_targets` with `Checkout`, `Promote`, `Copy`, or `Move` as appropriate.
+2. Select a returned target; do not type a remembered environment code.
+3. Preview and approve `tdoms_transfer_prepare`.
+4. Stop if preparation reports pre-transfer checks, conflicts, missing dependencies, or warnings requiring a decision.
+5. Approve `tdoms_transfer_execute_number` using the returned transfer number.
+6. Poll `tdoms_transfer_progress_number` and verify transfer history plus task/object state.
+
+The convenience tools `tdoms_checkout_*` and `tdoms_promote_*` can run several phases. Use them only when their complete request bodies have already been discovered and approved. A queued or running transfer is not completed.
+
+## Compile And Diagnostics
+
+1. Read the task object and source state.
+2. Check existing build queue and compile results.
+3. Preview the exact object/task/solution compile target.
+4. Obtain approval.
+5. Prefer `tdoms_compile_and_check` for an object because it queues, releases, and parses compile events in one workflow.
+6. Use `tdoms_compile_task`, `tdoms_compile_solution`, or `tdoms_compile_object` when broader queue control is needed.
+7. Read build queue, compile result, parsed events, logs, and spool files until a terminal state appears.
+
+Do not report success from queue acceptance alone. Report severity, source line when available, message id/text, object, member, and final build status. Compile overrides require separate discovery and approval.
+
+## Solutions, Components, And Connection Lists
+
+- Discover `solutions` and `taskObjects` before moving, changing, disconnecting, or deleting them.
+- Use core plans for change solution type, disconnect solutions, move solutions, change member attribute, delete objects, and fill object file.
+- Use full solution/object tools for connect, lock/unlock, relations, close, refill, and operations not in the core registry.
+
+For a connection list:
+
+1. Read list and entries.
+2. Preview additions/changes/deletions.
+3. Obtain approval for each mutation scope.
+4. Re-read the list.
+5. Treat `process` as a separate mutation, obtain approval, then verify resulting task/object state and logs.
+
+## Branches And Paths
+
+- Discover `branchesPaths` and current task path first.
+- Use `new-task-branch`, `edit-branch`, or `change-task-transfer-path` core plans when applicable.
+- Use full `tdoms_branch_*` tools for search/get, status recalculation, delete, stash, restore, and purge.
+- Treat purge as irreversible and require especially clear target confirmation.
+- Verify affected tasks/solutions and branch status after mutation.
+
+## Completion And Ratification
+
+Completion:
+
+1. Read task details, objects, compile state, conflicts, and transfer state.
+2. Discover `completionReasons`.
+3. Plan `complete-task` with the exact reason and task identifiers.
+4. Obtain approval, execute, and re-read task status.
+
+Ratification:
+
+1. Read pending ratification state and authorized choices.
+2. Discover `ratificationReasons` and programmers when required.
+3. Plan `task-ratification` with the explicit decision and comment fields required by the live schema.
+4. Never infer approval or rejection from conversational sentiment.
+5. Obtain explicit approval for the recorded decision, execute, and verify ratification history/status.
+
+## Revisions And Conflicts
+
+- Discover `revisions`, then use `revision-compare` or full source compare tools for read-only review.
+- Discover `conflicts` and read object/version context before resolving.
+- `solution-conflict` is discovery-only because resolution behavior may be site-specific.
+- Use `resolve-version-conflict` only when the server returns a documented resolution choice and the user approves the exact object/version decision.
+- Re-read conflicts and source history after execution.
+
+## Logs, Spool Files, And Remote Jobs
+
+- Use `logs` discovery or full log-history/message tools; preserve job and message identifiers.
+- Use `spoolFiles` discovery or spool list/fetch for diagnostics. Deletion is a separate confirmed mutation.
+- Discover `remoteJobs` before close, reopen, or schedule operations.
+- Use the matching core plan where available, otherwise the full typed tool.
+- Verify remote-job state after the call; asynchronous acceptance is not completion.
+
+## Labels, Comments, User Options, And Trackers
+
+- Discover labels before applying, changing, removing, or deleting them.
+- Read existing comments before add/reply/change/delete operations.
+- Discover `userOptions`; treat execution as arbitrary site-configured behavior and show the selected option and target before approval.
+- Discover tracker links/records before link or unlink.
+- Tracker server administration is Octo-only unless a site supplies a documented TD/OMS endpoint.
+
+## Analytics, Dependencies, And Kanban
+
+- Use `dashboards` or full dashboard tools for warnings such as missing source and problematic transfers.
+- Use `dependencies` or full impact/dependency tools before high-impact changes.
+- Use Kanban reads for visualization data. Moving a card changes task/request state and is a mutation requiring approval.
+- Treat inferred dashboard or database data as evidence, not as authorization for a mutation.
+
+## Failure Recovery
+
+| Failure | Response |
+| --- | --- |
+| No connection | Ask the user to configure and test one in `tdoms-mcp ui`. |
+| Multiple connections | Return profile choices and ask for the intended system. |
+| Authentication/token failure | Let automatic refresh run; if login still fails, ask the user to update the saved connection in the UI. |
+| `supported: false` | Report the warning and required context; do not guess. |
+| Empty options | Check context, casing, filters, and pagination; then ask one focused question. |
+| Plan expired/stale | Re-read, re-discover, create a new plan, and obtain approval again. |
+| Authority failure | Stop and report the TD/OMS operation and target that lacked authority. |
+| Lock/version conflict | Read lock/conflict/source history; do not overwrite. |
+| Transfer warning | Stop between prepare and execute until the user resolves or approves a documented choice. |
+| Compile failure | Fetch parsed events, logs, and spool output; do not mark work complete. |
+| Octo sign-in error | Use standalone context if available; Octo and standalone authentication are separate. |