Implement ledger storage for plan history #53

New Issue

2026-01-03T23:46:27Z

KofTwentyTwo commented

2026-01-03 23:46:27 +00:00

(Migrated from github.com)

User Story

As a developer, I want qstudio to keep a history of all generated plans so I can review past plans, track what was implemented, and maintain an audit trail.

Design

Command Interface

# List recent plans
qstudio ledger

# List with filters
qstudio ledger --project orders-service
qstudio ledger --since 7d
qstudio ledger --limit 20

# Show specific plan
qstudio ledger show plan-abc123

# Export plan
qstudio ledger export plan-abc123 --output plan.md

# Search plans
qstudio ledger search "authentication"

# Delete old plans
qstudio ledger prune --older-than 90d

# Export all for backup
qstudio ledger export-all --output backup.json

Output Format

Plan History

ID          Project          Prompt (truncated)              Date                 Tokens
plan-abc123 orders-service   Add Order entity with CRUD...   2024-01-15 10:30:00  2,450
plan-def456 orders-service   Add authentication flow...      2024-01-14 15:20:00  3,120
plan-ghi789 user-service     Implement password reset...     2024-01-13 09:15:00  1,890

Showing 3 of 47 plans. Use --limit to see more.

Ledger Storage

~/.qctl/ledger/
├── index.json           # Plan index (id, project, date, prompt summary)
└── plans/
    ├── plan-abc123.json  # Full plan with metadata
    ├── plan-def456.json
    └── ...

Plan Record Format

{
  "id": "plan-abc123",
  "project": "orders-service",
  "project_path": "/Users/james/projects/orders-service",
  "created_at": "2024-01-15T10:30:00Z",
  "prompt": "Add Order entity with CRUD operations",
  "provider": "anthropic",
  "model": "claude-3-opus-20240229",
  "tokens": {
    "input": 1200,
    "output": 1250,
    "total": 2450
  },
  "context_files": [
    "src/main/java/com/example/model/Customer.java",
    "pom.xml"
  ],
  "plan_output": "# Implementation Plan...",
  "status": "generated"
}

Files to Create/Modify

File	Action	Purpose
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/LedgerCommand.java`	Create	Ledger management command
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/ledger/PlanLedger.java`	Create	Ledger storage engine
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/ledger/PlanRecord.java`	Create	Plan record model
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/ledger/LedgerIndex.java`	Create	Index for fast lookup
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/ledger/LedgerExporter.java`	Create	Export functionality
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/format/LedgerFormatter.java`	Create	Table output formatting

Implementation Tasks

Create LedgerCommand with subcommands (list, show, export, search, prune, export-all)
Create PlanLedger storage engine
Create PlanRecord model with full metadata
Create LedgerIndex for efficient listing
Implement search with text matching
Implement prune with age-based deletion
Implement export to JSON/markdown
Integrate with PlanCommand (auto-save plans)
Add retention policy configuration
Create LedgerFormatter for table output
Handle ledger corruption gracefully
Write unit tests for PlanLedger
Write unit tests for LedgerIndex

Acceptance Criteria

qstudio ledger lists recent plans
qstudio ledger show <id> displays full plan
qstudio ledger search "<query>" finds matching plans
qstudio ledger export <id> exports to file
qstudio ledger prune --older-than <days> removes old plans
Plans auto-saved after generation
Stores tokens, provider, context files
Supports filtering by project, date
Graceful handling of corrupted entries

## User Story As a developer, I want qstudio to keep a history of all generated plans so I can review past plans, track what was implemented, and maintain an audit trail. ## Design ### Command Interface ```bash # List recent plans qstudio ledger # List with filters qstudio ledger --project orders-service qstudio ledger --since 7d qstudio ledger --limit 20 # Show specific plan qstudio ledger show plan-abc123 # Export plan qstudio ledger export plan-abc123 --output plan.md # Search plans qstudio ledger search "authentication" # Delete old plans qstudio ledger prune --older-than 90d # Export all for backup qstudio ledger export-all --output backup.json ``` ### Output Format ``` Plan History ID Project Prompt (truncated) Date Tokens plan-abc123 orders-service Add Order entity with CRUD... 2024-01-15 10:30:00 2,450 plan-def456 orders-service Add authentication flow... 2024-01-14 15:20:00 3,120 plan-ghi789 user-service Implement password reset... 2024-01-13 09:15:00 1,890 Showing 3 of 47 plans. Use --limit to see more. ``` ### Ledger Storage ``` ~/.qctl/ledger/ ├── index.json # Plan index (id, project, date, prompt summary) └── plans/ ├── plan-abc123.json # Full plan with metadata ├── plan-def456.json └── ... ``` ### Plan Record Format ```json { "id": "plan-abc123", "project": "orders-service", "project_path": "/Users/james/projects/orders-service", "created_at": "2024-01-15T10:30:00Z", "prompt": "Add Order entity with CRUD operations", "provider": "anthropic", "model": "claude-3-opus-20240229", "tokens": { "input": 1200, "output": 1250, "total": 2450 }, "context_files": [ "src/main/java/com/example/model/Customer.java", "pom.xml" ], "plan_output": "# Implementation Plan...", "status": "generated" } ``` ## Files to Create/Modify | File | Action | Purpose | |------|--------|---------| | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/LedgerCommand.java` | Create | Ledger management command | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/ledger/PlanLedger.java` | Create | Ledger storage engine | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/ledger/PlanRecord.java` | Create | Plan record model | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/ledger/LedgerIndex.java` | Create | Index for fast lookup | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/ledger/LedgerExporter.java` | Create | Export functionality | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/format/LedgerFormatter.java` | Create | Table output formatting | ## Implementation Tasks - [ ] Create LedgerCommand with subcommands (list, show, export, search, prune, export-all) - [ ] Create PlanLedger storage engine - [ ] Create PlanRecord model with full metadata - [ ] Create LedgerIndex for efficient listing - [ ] Implement search with text matching - [ ] Implement prune with age-based deletion - [ ] Implement export to JSON/markdown - [ ] Integrate with PlanCommand (auto-save plans) - [ ] Add retention policy configuration - [ ] Create LedgerFormatter for table output - [ ] Handle ledger corruption gracefully - [ ] Write unit tests for PlanLedger - [ ] Write unit tests for LedgerIndex ## Acceptance Criteria - [ ] `qstudio ledger` lists recent plans - [ ] `qstudio ledger show <id>` displays full plan - [ ] `qstudio ledger search "<query>"` finds matching plans - [ ] `qstudio ledger export <id>` exports to file - [ ] `qstudio ledger prune --older-than <days>` removes old plans - [ ] Plans auto-saved after generation - [ ] Stores tokens, provider, context files - [ ] Supports filtering by project, date - [ ] Graceful handling of corrupted entries

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qctl#53