Skip to content

Commit 6a0e4c1

Browse files
adamwdraperadamwdraper
authored
feat: add selective update for Directive-maintained files (#26)
- Enhance 'directive update' to selectively overwrite maintained files - Show preview of files to be updated before making changes - Prompt for confirmation (cancellable) - Update: templates, AOP, cursor rules - Protect: agent_context.md, specs/ directory - Handle non-interactive mode (auto-confirm) Adds: - _get_maintained_files() helper with hardcoded file list - _show_update_preview() to display what will change - Refactored cmd_update() with preview + confirmation - 9 comprehensive tests covering all acceptance criteria All 27 tests passing. No linting errors. Resolves: Spec 20251105-selective-update
1 parent 11ae305 commit 6a0e4c1

File tree

8 files changed

+1147
-10
lines changed

8 files changed

+1147
-10
lines changed

‎CHANGELOG.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [Unreleased]
9+
10+
### Added
11+
- **Selective Update Functionality**: `directive update` now actually updates Directive-maintained files
12+
- Shows clear preview of files to be overwritten before making any changes
13+
- Prompts for confirmation (cancellable) before proceeding
14+
- Updates maintained files: templates, `agent_operating_procedure.md`, cursor rules
15+
- Protects project-specific content: `agent_context.md`, `specs/` directory
16+
- Handles non-interactive mode (auto-confirms for CI/scripts)
17+
18+
### Changed
19+
- **`directive update` behavior enhancement** (not breaking):
20+
- **Old behavior**: Only copied new files that didn't exist (essentially non-functional after initial `init`)
21+
- **New behavior**: Selectively overwrites Directive-maintained files with latest from package
22+
- Files that WILL be updated: `agent_operating_procedure.md`, all templates, cursor rules
23+
- Files that will NOT be touched: `agent_context.md` (your context), `specs/` (your history)
24+
- Preview example:
25+
```
26+
The following files will be updated (overwritten):
27+
- directive/reference/agent_operating_procedure.md
28+
- directive/reference/templates/*.md
29+
- .cursor/rules/directive-core-protocol.mdc
30+
31+
Files that will NOT be modified:
32+
- directive/reference/agent_context.md (your project-specific context)
33+
- directive/specs/ (your project history)
34+
35+
Proceed with update? (Y/n)
36+
```
37+
38+
### Documentation
39+
- Updated implementation guides to clarify which files are "maintained" vs "project-specific"
40+
- Users should not customize templates or AOP directly (use `agent_context.md` for project customizations)
41+
- Running `directive update` after upgrading keeps you in sync with latest Directive improvements
42+
843
## [0.1.0] - 2025-10-16
944
1045
### Changed

‎directive/specs/20251105-selective-update/impact.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Impact Analysis — Selective Update for Directive-Maintained Files
2+
3+
**Spec ID**: 20251105
4+
**Created**: 2025-11-05
5+
6+
## Modules/packages likely touched
7+
- `src/directive/cli.py` — `cmd_update()` function needs complete refactor
8+
- Current behavior: non-destructive copy of all files
9+
- New behavior: selective overwrite of maintained files only
10+
- `src/directive/bundles.py` — may need helper to identify "maintained files" list
11+
- `src/directive/data/directive/` — package data structure (no changes needed, just reference)
12+
- `.cursor/rules/` — will be updated during update command
13+
- Tests: `tests/test_cli.py` — need new tests for selective update behavior
14+
15+
## Contracts to update (APIs, events, schemas, migrations)
16+
17+
### CLI Command Behavior Enhancement
18+
- **Command**: `directive update`
19+
- **Breaking change**: NO
20+
- Old: Non-destructive copy only (only adds new files, never updates existing)
21+
- New: Selective overwrite of maintained files (actually updates templates/AOP/cursor rules)
22+
- Current behavior is essentially non-functional for updates (always reports "0 copied, N skipped")
23+
- **User impact**:
24+
- Positive: Users can now actually get updates to templates and AOP
25+
- Minor: Users who customized templates, AOP, or cursor rules will see those overwritten (but this is the desired behavior)
26+
- **Documentation needs**:
27+
- CHANGELOG entry explaining new functionality
28+
- Document which files are "maintained" vs "project-specific"
29+
- Warn users not to customize maintained files
30+
31+
### New User Interaction
32+
- Confirmation prompt with preview of files to be overwritten
33+
- Must handle TTY vs non-TTY environments
34+
- Output format changes (more detailed feedback about what was actually updated)
35+
36+
## Risks
37+
38+
### Security
39+
- **Low risk**: No security concerns
40+
- File writes are restricted to known paths within directive/ and .cursor/
41+
- No new external inputs or data handling
42+
43+
### Performance/Availability
44+
- **Low risk**: CLI tool, local file operations only
45+
- Negligible performance impact (copying ~5-10 small text files)
46+
- No availability concerns (not a service)
47+
48+
### Data integrity
49+
- **Medium risk**: User customizations will be lost
50+
- **Mitigation 1**: Clear preview before overwriting shows exactly what will change
51+
- **Mitigation 2**: Confirmation prompt (cancellable)
52+
- **Mitigation 3**: Documentation warns users not to customize maintained files
53+
- **Mitigation 4**: agent_context.md and specs/ are explicitly protected (never overwritten)
54+
- **Low risk**: Incorrect file selection could overwrite user data
55+
- **Mitigation**: Hardcoded list of maintained files (not dynamic discovery)
56+
- **Mitigation**: Comprehensive tests covering edge cases
57+
58+
### Backward Compatibility
59+
- **Low risk**: Enhancement to existing `directive update` behavior, not breaking
60+
- Current command essentially does nothing useful (only copies new files)
61+
- New behavior makes the command actually functional for its intended purpose
62+
- Confirmation prompt protects users from accidental overwrites
63+
- **Note**: Not a breaking change, but document clearly in CHANGELOG as new feature
64+
65+
## Observability needs
66+
67+
### Logs
68+
- Not applicable (CLI tool, user sees direct output)
69+
- All feedback provided via stdout/stderr
70+
71+
### Metrics
72+
- Not applicable (no telemetry in CLI tool)
73+
74+
### Alerts
75+
- Not applicable (local CLI execution)
76+
77+
### User Feedback Requirements
78+
- **Before action**: Clear preview of files to be overwritten
79+
- **During action**: Progress indication (optional, files are small)
80+
- **After action**: Summary of what was actually updated
81+
- **On error**: Clear error messages if directive/ missing or file operations fail
82+

‎directive/specs/20251105-selective-update/implementation_summary.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Implementation Summary — Selective Update for Directive-Maintained Files
2+
3+
**Author**: AI Agent
4+
**Start Date**: 2025-11-05
5+
**Last Updated**: 2025-11-05
6+
**Status**: Complete
7+
**Branch**: `feature/20251105-selective-update`
8+
**Links**:
9+
- Spec: `/directive/specs/20251105-selective-update/spec.md`
10+
- TDR: `/directive/specs/20251105-selective-update/tdr.md`
11+
- Impact: `/directive/specs/20251105-selective-update/impact.md`
12+
13+
---
14+
15+
## Overview
16+
Enhancing `directive update` command to selectively overwrite Directive-maintained files (templates, AOP, cursor rules) while preserving project-specific content (specs, agent_context.md). Implementation includes preview display, confirmation prompt, and comprehensive test coverage.
17+
18+
## Files Changed
19+
20+
### New Files
21+
- None (all changes to existing files)
22+
23+
### Modified Files
24+
- `src/directive/cli.py` — Added `_get_maintained_files()` and `_show_update_preview()` helpers; completely refactored `cmd_update()` for selective overwrite with preview and confirmation
25+
- `tests/test_cli.py` — Added 9 new tests covering all acceptance criteria (preview, confirm/decline, non-interactive, edge cases, file protection)
26+
27+
### Deleted Files
28+
- None
29+
30+
## Key Implementation Decisions
31+
32+
### Decision 1: Hardcoded File List vs Dynamic Discovery
33+
**Context**: Need to identify which files to update
34+
**Choice**: Hardcoded list in `_get_maintained_files()` returning dict with 'directive' and 'cursor_rules' categories
35+
**Rationale**: Simple, predictable, testable; reduces risk of accidentally overwriting user files
36+
**Differs from TDR?**: No - exactly as planned
37+
38+
### Decision 2: Separate Preview and Copy Logic
39+
**Context**: Need to show preview before making changes
40+
**Choice**: Created separate `_show_update_preview()` function, then copy files individually
41+
**Rationale**: Clear separation of concerns; easier to test; user sees exactly what will happen
42+
**Differs from TDR?**: No - exactly as planned
43+
44+
### Decision 3: Reuse Existing `_ask_yes_no()` Helper
45+
**Context**: Need confirmation prompt with TTY detection
46+
**Choice**: Used existing `_ask_yes_no()` function which already handles TTY vs non-TTY
47+
**Rationale**: DRY principle; already tested and working; handles edge cases
48+
**Differs from TDR?**: No - TDR explicitly mentioned reusing this function
49+
50+
## Dependencies
51+
52+
### Added
53+
- None
54+
55+
### Updated
56+
- None
57+
58+
### Removed
59+
- None
60+
61+
## Database/Data Changes
62+
N/A - CLI tool, no database
63+
64+
## API/Contract Changes
65+
N/A - Local CLI tool, no external APIs
66+
67+
## Testing
68+
69+
### Test Coverage
70+
- **Unit tests**: 9 tests added, covering all acceptance criteria
71+
- All existing tests continue to pass (17 total tests in test_cli.py)
72+
- 100% coverage of new functionality (preview, confirmation, selective overwrite, edge cases)
73+
74+
### Test Files
75+
- `tests/test_cli.py` — Unit tests for cmd_update() behavior (lines 154-399)
76+
77+
### Spec → Test Mapping (All Passing ✓)
78+
- Spec AC 1: "Given directive/ exists, when update runs, then preview shown" → `test_update_shows_preview` ✓
79+
- Spec AC 2: "Given preview shown, when user confirms, then files overwritten" → `test_update_confirms_and_overwrites` ✓
80+
- Spec AC 3: "Given preview shown, when user declines, then no changes" → `test_update_declines_no_changes` ✓
81+
- Spec AC 4: "Given non-interactive mode, when update runs, then auto-confirms" → `test_update_noninteractive_autoconfirms` ✓
82+
- Spec AC 5: "Given no directive/, when update runs, then error message" → `test_update_no_directive_dir` ✓
83+
- Spec AC 6: "Given custom agent_context.md, when update runs, then unchanged" → `test_update_preserves_agent_context` ✓
84+
- Spec AC 7: "Given cursor rules exist, when update runs, then overwritten" → `test_update_overwrites_cursor_rules` ✓
85+
- Spec AC 8: "Given specs/ exists, when update runs, then unchanged" → `test_update_preserves_specs` ✓
86+
- Extra: "Given verbose flag, when update runs, then detailed output shown" → `test_update_verbose_flag` ✓
87+
88+
## Configuration Changes
89+
None
90+
91+
## Observability
92+
N/A - CLI tool with direct stdout/stderr feedback
93+
94+
## Security Considerations
95+
None - local file operations only
96+
97+
## Performance Impact
98+
Negligible - copying ~5-10 small text files
99+
100+
## Breaking Changes
101+
- [ ] No breaking changes
102+
- [x] Enhancement to existing command (not breaking, but changes behavior)
103+
104+
## Deviations from TDR
105+
None - Implementation followed TDR exactly as designed.
106+
107+
---
108+
109+
**Update Instructions**: Updating as implementation progresses.
110+

‎directive/specs/20251105-selective-update/spec.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Spec (per PR)
2+
3+
**Spec ID**: 20251105
4+
**Created**: 2025-11-05
5+
6+
**Feature name**: Selective Update for Directive-Maintained Files
7+
**One-line summary**: Allow users to safely update Directive-maintained files (templates, AOP, cursor rules) when new versions are released, while preserving project-specific content (specs and agent context).
8+
9+
---
10+
11+
## Problem
12+
When Directive releases updated templates, agent operating procedures, or cursor rules, users currently have to manually identify which files to update. The current `directive update` command copies everything non-destructively, meaning users never get updates to files they've already initialized. Users need an easy way to pull the latest Directive-maintained files while preserving only their project-specific content (specs and agent context).
13+
14+
## Goal
15+
Users can run `directive update` to refresh all Directive-maintained files (templates, AOP, and cursor rules), while preserving only their project-specific content (specs and agent context).
16+
17+
## Success Criteria
18+
- [ ] Users can update templates, AOP, and cursor rules with a single command
19+
- [ ] Project-specific content (agent_context.md and specs) is never overwritten
20+
- [ ] Users see a clear preview of exactly which files will be overwritten before any changes occur
21+
- [ ] Users can cancel the update after seeing the preview
22+
- [ ] Updates work seamlessly across version upgrades
23+
24+
## User Story
25+
As a Directive user, I want to easily pull the latest templates, agent operating procedures, and cursor rules when new versions are released, so that I can benefit from improvements without manually comparing files or worrying about losing my project-specific content (specs and agent context).
26+
27+
## Flow / States
28+
29+
**Happy Path:**
30+
1. User runs `directive update`
31+
2. Command checks if directive/ exists
32+
3. Command displays list of files that will be overwritten:
33+
```
34+
The following files will be updated (overwritten):
35+
- directive/reference/agent_operating_procedure.md
36+
- directive/reference/templates/spec_template.md
37+
- directive/reference/templates/impact_template.md
38+
- directive/reference/templates/tdr_template.md
39+
- directive/reference/templates/implementation_summary_template.md
40+
- .cursor/rules/directive-core-protocol.mdc
41+
42+
Files that will NOT be modified:
43+
- directive/reference/agent_context.md (your project-specific context)
44+
- directive/specs/ (your project history)
45+
```
46+
4. Command asks for confirmation (Y/n, default Yes)
47+
5. If confirmed, files are overwritten with latest versions from package
48+
6. Success message shows what was actually updated
49+
50+
**Edge Case - No directive/ directory:**
51+
1. User has no `directive/` directory yet
52+
2. Command detects this and suggests running `directive init` first
53+
3. Exits gracefully with helpful message
54+
55+
**Edge Case - Non-interactive mode:**
56+
1. User runs command in CI/non-TTY environment
57+
2. Command shows what would be updated
58+
3. Auto-confirms with default (Yes) and proceeds
59+
60+
## UX Links
61+
N/A - CLI only feature
62+
63+
## Requirements
64+
- Must show a clear preview of which files will be overwritten before making any changes
65+
- Must ask for user confirmation before overwriting (with sensible default)
66+
- Must update these Directive-maintained files with overwrite:
67+
- `directive/reference/agent_operating_procedure.md`
68+
- `directive/reference/templates/spec_template.md`
69+
- `directive/reference/templates/impact_template.md`
70+
- `directive/reference/templates/tdr_template.md`
71+
- `directive/reference/templates/implementation_summary_template.md`
72+
- `.cursor/rules/directive-core-protocol.mdc` (and any other cursor rules from package)
73+
- Must NOT overwrite project-specific content:
74+
- `directive/reference/agent_context.md` (project-specific context)
75+
- `directive/specs/` directory (project history)
76+
- Any other user-created files not in the package
77+
- Must work whether or not directive/ already exists
78+
- Must provide clear feedback about what was actually updated after completion
79+
- Must handle non-interactive mode gracefully (CI/scripts)
80+
81+
## Acceptance Criteria
82+
- Given a directive/ directory exists, when user runs `directive update`, then a preview of files to be overwritten is shown before any changes
83+
- Given the preview is shown, when user confirms (Y), then templates, AOP, and cursor rules are overwritten and success message shows what was updated
84+
- Given the preview is shown, when user declines (n), then no files are modified and command exits gracefully
85+
- Given command runs in non-interactive mode, when `directive update` is called, then it auto-confirms and proceeds with updates
86+
- Given directive/ doesn't exist, when user runs `directive update`, then command exits with helpful message to run `directive init`
87+
- Given `agent_context.md` has custom content, when user runs `directive update`, then `agent_context.md` is unchanged
88+
- Given `.cursor/rules/` has Directive rules, when user runs `directive update`, then cursor rules are overwritten with latest from package
89+
- Given `directive/specs/` has project history, when user runs `directive update`, then specs directory is unchanged
90+
91+
## Non-Goals
92+
- Intelligent merging of template changes (simple overwrite only)
93+
- Backup/restore functionality for overwritten files
94+
- Updating `.cursor/mcp.json` or `.cursor/servers/` (MCP setup remains one-time via `init`)
95+
- Version-aware updates or migration scripts
96+
- Selective update of individual files (all-or-nothing update of maintained files)
97+

0 commit comments

Comments
 (0)