diff --git a/openspec/changes/upstream-sync-audit-merge/.openspec.yaml b/openspec/changes/archive/2026-08-12-upstream-sync-audit-merge/.openspec.yaml similarity index 100% rename from openspec/changes/upstream-sync-audit-merge/.openspec.yaml rename to openspec/changes/archive/2026-08-12-upstream-sync-audit-merge/.openspec.yaml diff --git a/openspec/changes/upstream-sync-audit-merge/design.md b/openspec/changes/archive/2026-08-12-upstream-sync-audit-merge/design.md similarity index 100% rename from openspec/changes/upstream-sync-audit-merge/design.md rename to openspec/changes/archive/2026-08-12-upstream-sync-audit-merge/design.md diff --git a/openspec/changes/upstream-sync-audit-merge/proposal.md b/openspec/changes/archive/2026-08-12-upstream-sync-audit-merge/proposal.md similarity index 100% rename from openspec/changes/upstream-sync-audit-merge/proposal.md rename to openspec/changes/archive/2026-08-12-upstream-sync-audit-merge/proposal.md diff --git a/openspec/changes/upstream-sync-audit-merge/specs/tool-capabilities/spec.md b/openspec/changes/archive/2026-08-12-upstream-sync-audit-merge/specs/tool-capabilities/spec.md similarity index 100% rename from openspec/changes/upstream-sync-audit-merge/specs/tool-capabilities/spec.md rename to openspec/changes/archive/2026-08-12-upstream-sync-audit-merge/specs/tool-capabilities/spec.md diff --git a/openspec/changes/upstream-sync-audit-merge/tasks.md b/openspec/changes/archive/2026-08-12-upstream-sync-audit-merge/tasks.md similarity index 100% rename from openspec/changes/upstream-sync-audit-merge/tasks.md rename to openspec/changes/archive/2026-08-12-upstream-sync-audit-merge/tasks.md diff --git a/openspec/changes/wit-work-item-write/.openspec.yaml b/openspec/changes/archive/2026-08-12-wit-work-item-write/.openspec.yaml similarity index 100% rename from openspec/changes/wit-work-item-write/.openspec.yaml rename to openspec/changes/archive/2026-08-12-wit-work-item-write/.openspec.yaml diff --git a/openspec/changes/wit-work-item-write/design.md b/openspec/changes/archive/2026-08-12-wit-work-item-write/design.md similarity index 100% rename from openspec/changes/wit-work-item-write/design.md rename to openspec/changes/archive/2026-08-12-wit-work-item-write/design.md diff --git a/openspec/changes/wit-work-item-write/proposal.md b/openspec/changes/archive/2026-08-12-wit-work-item-write/proposal.md similarity index 100% rename from openspec/changes/wit-work-item-write/proposal.md rename to openspec/changes/archive/2026-08-12-wit-work-item-write/proposal.md diff --git a/openspec/changes/wit-work-item-write/specs/wit-work-item-write-create/spec.md b/openspec/changes/archive/2026-08-12-wit-work-item-write/specs/wit-work-item-write-create/spec.md similarity index 100% rename from openspec/changes/wit-work-item-write/specs/wit-work-item-write-create/spec.md rename to openspec/changes/archive/2026-08-12-wit-work-item-write/specs/wit-work-item-write-create/spec.md diff --git a/openspec/changes/wit-work-item-write/tasks.md b/openspec/changes/archive/2026-08-12-wit-work-item-write/tasks.md similarity index 100% rename from openspec/changes/wit-work-item-write/tasks.md rename to openspec/changes/archive/2026-08-12-wit-work-item-write/tasks.md diff --git a/openspec/specs/tool-capabilities/spec.md b/openspec/specs/tool-capabilities/spec.md index ef559e72..008414a4 100644 --- a/openspec/specs/tool-capabilities/spec.md +++ b/openspec/specs/tool-capabilities/spec.md @@ -2,9 +2,7 @@ ## Purpose Define the intended capability scope of the fork and how capability changes are governed. - ## Requirements - ### Requirement: Supported capability scope is intentionally limited The fork SHALL support a pragmatic subset of Azure DevOps MCP capabilities centered on work item and repository collaboration workflows unless expanded by an explicit change. @@ -38,4 +36,41 @@ Changes to supported capabilities SHALL preserve existing MCP tool contracts unl #### Scenario: Revising an existing tool behavior - GIVEN a change modifies an existing fork tool in a supported capability area - WHEN the change is proposed -- THEN the proposal SHALL describe compatibility expectations for tool name, input shape, and observable behavior \ No newline at end of file +- THEN the proposal SHALL describe compatibility expectations for tool name, input shape, and observable behavior + +### Requirement: Upstream synchronization is audit-first +The repository workflow SHALL provide an upstream synchronization audit phase that runs before any merge phase. + +#### Scenario: Running upstream sync workflow +- GIVEN upstream updates may affect fork-specific behavior +- WHEN a sync operation is initiated +- THEN an upstream impact audit SHALL run first +- AND the audit SHALL produce a severity-classified report + +### Requirement: Implemented fork capabilities receive targeted impact checks +The upstream audit SHALL explicitly evaluate impact on currently implemented fork collaboration capabilities. + +#### Scenario: Upstream changes include work item or repository tools +- GIVEN upstream changes are fetched for comparison +- WHEN audit classification is performed +- THEN changes affecting implemented fork capabilities SHALL be identified explicitly +- AND findings SHALL be classified by severity (High, Medium, Low) + +### Requirement: Merge phase targets a sync branch by default +The upstream merge phase SHALL merge into a sync branch derived from fork main, not directly into main by default. + +#### Scenario: Executing approved merge phase +- GIVEN the audit phase is complete and user confirmation is provided +- WHEN merge execution starts +- THEN the merge target SHALL be a sync branch +- AND direct merge into main SHALL be blocked unless explicitly overridden by policy + +### Requirement: High-impact findings gate merge execution +The merge phase SHALL be blocked when unresolved High-impact audit findings are present. + +#### Scenario: Audit reports unresolved High findings +- GIVEN the upstream audit report contains unresolved High-impact findings +- WHEN merge execution is requested +- THEN merge execution SHALL be blocked +- AND the workflow SHALL require explicit resolution or acknowledgment path before proceeding + diff --git a/openspec/specs/wit-work-item-write-create/spec.md b/openspec/specs/wit-work-item-write-create/spec.md new file mode 100644 index 00000000..8ea2a91b --- /dev/null +++ b/openspec/specs/wit-work-item-write-create/spec.md @@ -0,0 +1,54 @@ +# wit-work-item-write-create Specification + +## Purpose +TBD - created by archiving change wit-work-item-write. Update Purpose after archive. +## Requirements +### Requirement: Create work item with core parameters +The MCP tool `wit_work_item_write_create` SHALL create a new work item in an Azure DevOps project with a specified type, title, and optional description. + +#### Scenario: Successful work item creation with required fields +- **WHEN** the tool is called with valid collection, project, workItemType, and title parameters +- **THEN** a new work item SHALL be created in the specified project +- **AND** the tool SHALL return the newly created work item ID and URL +- **AND** the work item type SHALL match the specified workItemType +- **AND** the work item title SHALL match the specified title + +#### Scenario: Work item creation with description +- **WHEN** the tool is called with collection, project, workItemType, title, and description parameters +- **THEN** a new work item SHALL be created with all provided fields +- **AND** the work item description SHALL contain the provided text +- **AND** the work item SHALL be retrievable immediately after creation + +#### Scenario: Invalid work item type rejection +- **WHEN** the tool is called with a workItemType that does not exist in the project +- **THEN** the tool SHALL return an error response +- **AND** no work item SHALL be created +- **AND** the error message SHALL indicate the invalid work item type + +### Requirement: Contextual parameter specification +The tool SHALL accept Azure DevOps collection and project parameters to contextualize the work item creation operation. + +#### Scenario: Work item created in correct project context +- **WHEN** the tool is called with a specific collection and project +- **THEN** the work item SHALL be created in that specified project +- **AND** subsequent retrieval of the work item by ID SHALL be scoped to the same project + +### Requirement: Required parameter validation +The tool SHALL enforce that collection, project, workItemType, and title are provided and non-empty. + +#### Scenario: Missing required parameter handling +- **WHEN** the tool is called without a required parameter (collection, project, workItemType, or title) +- **THEN** the tool SHALL return a validation error +- **AND** no work item SHALL be created +- **AND** the error message SHALL indicate which required parameter is missing + +### Requirement: Response contract for successful creation +The tool response for a successful work item creation SHALL include the work item ID, URL, type, and title for immediate confirmation. + +#### Scenario: Response contains created work item identifiers +- **WHEN** a work item is successfully created +- **THEN** the response SHALL include the numeric work item ID +- **AND** the response SHALL include a URL to access the created work item +- **AND** the response SHALL include the work item type that was created +- **AND** the response SHALL include the title provided at creation time +