ADR: Update ADR status and supersession (adr_status)

[rshade]

Priority: P2 - Medium Priority

Part of Epic: #289
Estimated Effort: 4-6 hours
Phase: 1 - Foundation

Problem Statement

ADR statuses change over time - decisions get accepted, rejected, deprecated, or superseded. Users need a tool to update these statuses while maintaining proper cross-references.

Proposed Solution

Implement adr_status tool that:

1. Updates the status of an existing ADR
2. Handles supersession relationships (updates both ADRs)
3. Validates status transitions
4. Preserves file formatting

Implementation Guidance

Tool Schema

const AdrStatusUpdateArgsSchema = z.object({
  directory: z.string().optional()
    .describe("Working directory"),
  number: z.number()
    .describe("ADR number to update"),
  status: z.enum(["proposed", "accepted", "rejected", "deprecated", "superseded"])
    .describe("New status"),
  supersededBy: z.number().optional()
    .describe("ADR number that supersedes this one (required if status=superseded)"),
});

Status Transitions

Valid transitions:

proposed → accepted | rejected
accepted → deprecated | superseded
rejected → (terminal)
deprecated → superseded
superseded → (terminal)

Supersession Handling

When marking ADR as superseded:

1. Update old ADR status to "Superseded by ADR-XXX"
2. Update new ADR to reference "Supersedes ADR-YYY"

Development Steps

1. Codebase Analysis

   • Review how adr-tools handles supersession
   • Understand in-place file editing patterns

2. Implementation

   • Add to src/tools/adr-tools.ts
   • Implement status update logic
   • Handle cross-reference updates
   • Preserve original file formatting

3. Testing Requirements

   • Test all valid status transitions
   • Test supersession creates proper links
   • Test invalid transitions are rejected
   • Test file formatting is preserved
   • Target: 85-90%+ coverage

4. Linting & Validation

   make lint
   make test
   make build

Acceptance Criteria

Feature Complete:

• Updates ADR status in file
• Validates status transitions
• Handles supersession (updates both ADRs)
• Preserves original formatting
• Returns updated metadata

Quality Gates:

• make lint passes with zero errors
• make test passes with 85-90%+ coverage
• make build completes successfully

Documentation:

• JSDoc comments for all public methods
• Update src/instructions.md

Example Usage

// Accept a proposed decision
adr_status({ number: 3, status: "accepted" })
// Updates ADR-3 status from "Proposed" to "Accepted"

// Mark as superseded
adr_status({ number: 2, status: "superseded", supersededBy: 5 })
// Updates ADR-2: "Superseded by ADR-5"
// Updates ADR-5: "Supersedes ADR-2"

// Deprecate old decision
adr_status({ number: 1, status: "deprecated" })

References

• Epic: Epic: Architecture Decision Records (ADR) Tooling Support #289
• Depends on: adr_list/adr_show (for parsing)
• adr-tools supersede: https://github.com/npryce/adr-tools