# Implementation Plan: 0.5.0 Client/server workflow alignment and ticket protocol clarification

## Objectives
- Align the implemented MCP server workflow with the stricter client operating contract described in the 0.5.0 draft.
- Remove contradictions between repository rules, generated rules, and runtime behavior.
- Decide and implement a coherent boundary between protocol-enforced behavior and client-side convention.
- Make lifecycle, commit, and file-intent workflows clearer and safer for clients.
- Ensure mandatory workflow requirements in `.rules` are satisfiable using supported server primitives.

## Background
Version 0.4.13 substantially hardened the transaction core of AgentOps MCP. The server now behaves much more like a strict transaction/event engine with stronger guarantees around workspace initialization, transaction ordering, verify/commit sequencing, rebuild integrity, and resumability artifacts.

The 0.5.0 draft concludes that the main remaining problem is no longer low-level event correctness alone. Instead, the primary issue is workflow alignment across three layers:

1. the Python MCP server implementation,
2. the bootstrap/init script that provisions client-visible rules and state,
3. the `.rules` document that prescribes the expected operating model.

The review finds that event-level alignment is relatively strong, while ticket/workflow-level alignment is still incomplete. In particular:

- repository `.rules` and generated rules are not fully synchronized,
- `.rules` describes mandatory planning and ticket persistence behavior that the server does not fully support,
- task lifecycle helpers do not yet present a fully explicit status transition interface,
- commit policy is only partially enforced as protocol,
- file intent handling exists but remains low-level for clients.

Version 0.5.0 should close these gaps so the documented workflow and implemented workflow become the same thing.

## Problem Statement
The current system mixes two partially overlapping models:

- a strict transaction/event engine implemented by the server,
- a fuller ticket-oriented workflow described by `.rules`.

That mismatch creates ambiguity about what is guaranteed by protocol versus what is merely expected by convention.

As a result, the system currently risks:
1. distributing inconsistent rules to newly initialized workspaces,
2. requiring clients to maintain ticket documents without first-class server support,
3. exposing lifecycle helpers whose semantics are weaker or less explicit than the status machine described in `.rules`,
4. allowing commit policy requirements to remain advisory rather than enforced,
5. forcing clients to operate at raw event level for file-intent flows,
6. and leaving version/bootstrap surfaces more confusing than necessary.

Version 0.5.0 should resolve those mismatches explicitly instead of letting them remain implicit.

## Scope

### In scope
- Synchronization between repository `.rules` and generated client rules
- Explicit decision on whether planning/ticket persistence is protocol or convention
- Lifecycle API clarification or hardening around the documented status machine
- Stronger commit gating aligned with rules
- Improved client ergonomics for file-intent workflows
- Normalization of workflow-critical bootstrap/state surfaces where practical
- Documentation and acceptance criteria that reflect the real supported operating model

### Out of scope
- Replacing the canonical transaction/event-log architecture
- Weakening transaction ordering or integrity guarantees introduced in 0.4.13
- Broad redesign unrelated to client/server workflow alignment
- Nonessential cosmetic refactors with no protocol impact
- Building a full project management system beyond what the rules actually require

## Phases

### Phase 1: Establish one canonical workflow contract across rules, bootstrap, and runtime
**Goals**
- Remove contradictions between repository rules and generated rules.
- Make the intended workflow contract explicit before additional implementation work.
- Clarify which requirements are protocol-enforced versus client convention.

**Tasks**
- Compare repository `.rules` with the rules content generated by `zed-agentops-init.sh`.
- Identify all workflow-critical differences, especially around:
  - workspace initialization,
  - resume behavior,
  - active transaction handling,
  - ticket selection,
  - mandatory persistence and logging behavior.
- Decide on one canonical source of truth for rules text.
- Update generation flow so bootstrap output and repository rules cannot drift silently.
- Document which workflow requirements are:
  - enforced by server primitives,
  - expected from clients as convention,
  - or planned for new server support in 0.5.0.
- Review any runtime assumptions that are more permissive than the public rules wording and either align or document them.

**Deliverables**
- Canonical workflow contract for 0.5.0
- Eliminated drift between repository rules and generated rules
- Clear protocol-versus-convention boundaries for workflow behavior

---

### Phase 2: Resolve the ticket persistence boundary
**Goals**
- Make an explicit product and protocol decision about planning and ticket artifacts.
- Ensure `.rules` does not claim mandatory behavior the server cannot support.
- Either implement first-class ticket persistence support or reduce those requirements to documented convention.

**Tasks**
- Review the planning flow described in `.rules`, including:
  - `docs/__version__/plan.md`,
  - `docs/__version__/tickets_list.json`,
  - `docs/__version__/pX-tY.json`,
  - synchronized status persistence requirements.
- Assess current runtime support for:
  - plan generation,
  - ticket generation,
  - per-ticket updates,
  - synchronized ticket-list updates,
  - validation against runtime lifecycle transitions.
- Choose one of two directions:
  1. make ticket persistence a first-class protocol feature, or
  2. revise `.rules` so ticket persistence is an operating convention rather than mandatory protocol.
- If making it protocol:
  - define the canonical ticket schema,
  - define allowed ticket statuses,
  - define synchronization guarantees,
  - define how runtime lifecycle transitions update ticket artifacts.
- If making it convention:
  - rewrite rules wording to remove false guarantees,
  - preserve only the requirements that the server can actually support.
- Ensure the final contract leaves no ambiguous middle state.

**Deliverables**
- Explicit 0.5.0 decision on ticket persistence
- Updated rules and implementation plan consistent with that decision
- Defined artifact responsibilities for client and server

---

### Phase 3: Make lifecycle APIs reflect the status machine explicitly
**Goals**
- Align client-facing lifecycle operations with the documented top-level workflow states.
- Remove ambiguity between task helpers, generic progress reporting, and canonical status transitions.
- Ensure clients can understand the authoritative lifecycle interface clearly.

**Tasks**
- Review the documented top-level statuses:
  - `planned`
  - `in-progress`
  - `checking`
  - `verified`
  - `committed`
  - `done`
  - `blocked`
- Audit current lifecycle helper behavior and identify where semantics are:
  - explicit,
  - implicit through lower-level event interpretation,
  - or too permissive relative to the rules.
- Decide on the intended client-facing model:
  1. strict lifecycle/status transition API, or
  2. explicitly low-level event-oriented API with task helpers documented as convenience wrappers.
- If adopting a stricter lifecycle interface:
  - define exact transition semantics,
  - define allowed source and destination states,
  - define how verify and commit subflows update top-level lifecycle status.
- If retaining low-level semantics:
  - document task helpers as non-authoritative wrappers,
  - document the canonical status source and how clients should reason about it.
- Ensure terminal operations and intermediate states are represented coherently from the client perspective.
- Align any observability or task-summary outputs with the chosen lifecycle model.

**Deliverables**
- Clear canonical lifecycle model for clients
- Reduced ambiguity around task start, update, and end semantics
- Documented transition behavior consistent with `.rules`

---

### Phase 4: Tighten commit workflow enforcement
**Goals**
- Turn documented commit-policy requirements into explicit protocol enforcement where appropriate.
- Make commit behavior match the work loop described in `.rules`.
- Prevent commit attempts that should be rejected before reaching the VCS layer.

**Tasks**
- Review current commit flow behavior around:
  - prior verify pass,
  - repo status visibility,
  - no-change commit handling,
  - commit message normalization.
- Define the required preconditions for commit in 0.5.0.
- Ensure commit is explicitly blocked when:
  - verification has not passed,
  - there are no changes to commit,
  - or required transaction context is missing.
- Decide whether repo-status inspection is:
  - a hard precondition,
  - an automatically captured supporting observation,
  - or a required part of higher-level helper flows.
- Ensure commit errors distinguish:
  - failed preconditions,
  - repository clean state,
  - and underlying VCS failure.
- Align commit helper behavior and rules wording so they describe the same enforced contract.

**Deliverables**
- Stronger commit gating semantics
- Clear no-change commit behavior
- Rules and runtime behavior aligned for verify/commit workflow

---

### Phase 5: Improve file-intent ergonomics without weakening invariants
**Goals**
- Preserve the existing strict file-intent event model.
- Reduce client burden when performing common file-intent workflows.
- Make rule-compliant file mutation behavior easier to execute safely.

**Tasks**
- Review the current file-intent event sequence and required ordering.
- Identify the most common client actions that currently require low-level manual event construction.
- Design first-class helper flows for operations such as:
  - register file intent,
  - mark file work started,
  - mark file change applied,
  - mark file intent verified,
  - mark file intent completed.
- Ensure helper design preserves the existing guarantees:
  - prior registration requirement,
  - non-regressive state transitions,
  - verify-before-verified semantics.
- Decide whether helper flows become:
  - dedicated public tools,
  - higher-level wrappers around existing events,
  - or documented implementation guidance only.
- Document any required payload conventions so clients can use the helpers safely and consistently.

**Deliverables**
- Ergonomic file-intent workflow design for clients
- Preserved ordering and validation guarantees
- Reduced need for raw low-level event assembly in common flows

---

### Phase 6: Normalize workflow-critical bootstrap and version surfaces
**Goals**
- Reduce confusion in state bootstrap and version reporting.
- Ensure the initial workspace state shape and runtime-generated state shape are coherent enough for predictable workflow behavior.
- Clean up lower-priority alignment issues identified by the draft.

**Tasks**
- Compare bootstrap-created transaction state with runtime-rebuilt transaction state.
- Identify workflow-relevant shape differences, including fields such as:
  - drift indicators,
  - active transaction source metadata,
  - other state-shape defaults that affect reasoning or tooling.
- Normalize bootstrap output where practical so initial and rebuilt states share one predictable structure.
- Review version surfaces across:
  - server/package version,
  - schema version,
  - release/draft version,
  - any user-visible server info output.
- Clarify or rename version surfaces where necessary so operators can distinguish implementation version from workflow/release version.
- Review references to optional or unsupported tool contracts in `.rules` and remove or clarify them if they are not part of the actual exposed server contract.

**Deliverables**
- More coherent bootstrap state shape
- Clearer version/reporting surfaces
- Reduced conceptual drift in workflow documentation

---

### Phase 7: Add validation and regression coverage for workflow alignment decisions
**Goals**
- Protect the 0.5.0 workflow contract from future drift.
- Ensure the chosen protocol boundary is testable and observable.
- Prevent reintroduction of contradictions between rules and runtime behavior.

**Tasks**
- Add checks or tests that detect drift between repository `.rules` and generated rules content.
- Add tests for any new lifecycle status semantics introduced in 0.5.0.
- Add tests for commit precondition enforcement, especially:
  - verify required,
  - no-change rejection,
  - transaction-context requirements.
- Add tests for any new file-intent helper flows and their ordering guarantees.
- If ticket persistence becomes protocol:
  - add tests for ticket artifact creation,
  - synchronized status persistence,
  - and ticket/runtime consistency validation.
- If ticket persistence remains convention:
  - add regression checks that rules and documentation do not overstate server guarantees.
- Ensure verification covers both behavior and contract alignment artifacts.

**Deliverables**
- Regression protection for 0.5.0 workflow alignment
- Drift detection for workflow-critical rule surfaces
- Verification evidence that documented and implemented behavior agree

## Proposed ticket breakdown

### Phase 1 tickets
- `p1-t01` Align repository rules and bootstrap-generated rules from one canonical source
- `p1-t02` Decide whether ticket persistence is protocol or convention
- `p1-t03` Implement or revise ticket persistence requirements to match the chosen protocol model

### Phase 2 tickets
- `p2-t01` Align lifecycle APIs with the documented status machine
- `p2-t02` Implement strict commit gating and repo-state enforcement

### Phase 3 tickets
- `p3-t01` Add ergonomic first-class file intent helper support

### Phase 4 tickets
- `p4-t01` Improve file intent ergonomics with first-class helper workflows
- `p4-t02` Normalize bootstrap state shape and clarify version surfaces

### Phase 5 tickets
- `p5-t01` Add interoperability verification coverage and workflow alignment documentation
- `p5-t02` Add regression coverage for workflow alignment and protocol enforcement

## Acceptance criteria
1. Repository `.rules` and generated rules are identical for workflow-critical sections or are produced from one canonical source.
2. The 0.5.0 documentation clearly distinguishes protocol-enforced behavior from client-side operating convention.
3. `.rules` no longer describes mandatory behavior the server does not support, unless 0.5.0 implements that support.
4. Clients have a clear canonical lifecycle model for start, update/progress, verify, commit, and terminal completion.
5. Commit is explicitly blocked when verify has not passed.
6. Commit is explicitly blocked when there are no changes to commit.
7. File-intent workflow is supported through a safer and more ergonomic client-facing interface or equivalently clear helper contract.
8. Bootstrap state and runtime state are coherent enough that clients can reason about initialization and resume behavior predictably.
9. Version and workflow surfaces are clear enough that operators can distinguish implementation, schema, and release contexts.
10. Regression coverage exists for the chosen 0.5.0 contract so future drift between rules and implementation is detectable.

## Risks and considerations
- The largest design risk is preserving an ambiguous hybrid model where ticket persistence is described as mandatory but not actually supported.
- Tightening protocol behavior may require updating both runtime logic and rules wording together; partial changes will increase confusion.
- Ergonomic helper additions must not weaken the ordering invariants enforced by the transaction core.
- If lifecycle helpers remain convenience wrappers, that fact must be documented very clearly to avoid false expectations.
- Rules synchronization should ideally be mechanized so future edits cannot drift silently.

## Recommended execution order
1. Canonicalize the workflow contract and eliminate rules drift.
2. Decide the ticket persistence boundary.
3. Align lifecycle API semantics with the chosen contract.
4. Tighten commit gating.
5. Improve file-intent ergonomics.
6. Normalize bootstrap/version surfaces.
7. Add regression coverage that locks the decisions in place.

## Final planning note
Version 0.5.0 should be treated as a workflow-boundary release rather than another transaction-core-only hardening release. The core transaction engine is already substantially stronger after 0.4.13. The main remaining task is to ensure that the rules clients are asked to follow are the same rules the server actually supports and enforces.