Advanced

Graph health, archaeology, narratives, roadmap management, document attachments, and theming.

`deciduous audit`

Audit and maintain graph data quality. Can associate git commits with nodes by matching titles to commit messages.

Flag	Description
`--associate-commits`	Associate commits with nodes by matching titles to commit messages
`--min-score <0-100>`	Minimum keyword match score (default: 50)
`--dry-run`	Show what would be done without modifying database
`--yes`	Auto-apply without confirmation

Terminal

$ deciduous audit --associate-commits --dry-run
Scanning git log for commit matches...
Node 5 "Implement JWT middleware" -> commit a1b2c3d "feat: add JWT middleware" (score: 85)
Node 8 "Add rate limiter" -> commit f4e5d6a "feat: add redis rate limiter" (score: 72)
Node 12 "Fix token refresh" -> commit 9c8d7e6 "fix: token refresh race condition" (score: 68)
3 matches found (dry run, no changes made)

$ deciduous audit --associate-commits --min-score 70 --yes
Associated node 5 with commit a1b2c3d (score: 85)
Associated node 8 with commit f4e5d6a (score: 72)
2 commits associated

`deciduous pulse`

Show the pulse of the decision graph – active state, gaps, and health. A quick overview of where things stand.

Flag	Short	Description
`--branch <name>`	`-b`	Filter by git branch
`--recent <n>`	`-r`	Number of recent nodes to show (default: 10)
`--json`		Output as JSON
`--summary`		Show only the summary section

Terminal

$ deciduous pulse
Decision Graph Pulse
====================

Summary:
Total nodes: 47
Active goals: 3
Open actions: 5
Completed: 12
Superseded: 2

Health:
Orphan nodes: 0
Unlinked actions: 2 (nodes 38, 41)
Dangling outcomes: 0

Recent (last 10):
47 outcome completed JWT auth working -- 14 tests passing
46 action active Implement JWT middleware + refresh endpoint
45 decision active Use jsonwebtoken crate for full control
44 option active axum-jwt-auth with built-in rotation
43 option active jsonwebtoken crate + custom refresh logic
42 goal active Add JWT authentication
...

Summary only:

Terminal

$ deciduous pulse --summary -b feature-auth
Summary (branch: feature-auth):
Total nodes: 6 | Active goals: 1 | Completed: 1

`deciduous narratives`

Manage evolution narratives in .deciduous/narratives.md. Narratives capture how the system evolved over time – the story behind the decisions.

`deciduous narratives init`

Initialize narratives.md with active goal titles as section headings.

Flag	Short	Description
`--output <path>`	`-o`	Output path (default: `.deciduous/narratives.md`)
`--force`		Overwrite existing file

Terminal

$ deciduous narratives init
Created .deciduous/narratives.md with 3 goal sections:
- Add JWT authentication
- Add rate limiting
- Database migration tooling

`deciduous narratives show`

Display the contents of narratives.md.

Flag	Short	Description
`--path <path>`	`-p`	Path to narratives.md (default: `.deciduous/narratives.md`)

Terminal

$ deciduous narratives show
# Evolution Narratives

## Add JWT authentication
Started with session-based auth, pivoted to JWT when mobile
clients needed stateless tokens. Chose jsonwebtoken crate over
axum-jwt-auth for more control over refresh rotation timing.

## Add rate limiting
(narrative pending)

`deciduous narratives pivots`

List all pivot points (revisit nodes) with their full chains – showing what changed and why.

Flag	Short	Description
`--branch <name>`	`-b`	Filter by git branch
`--json`		Output as JSON

Terminal

$ deciduous narratives pivots
Pivot 1:
Revisit node 30: "Reconsidering session-based auth"
Triggered by: observation 29 "Mobile clients can't maintain sessions"
Old approach: decision 15 "Use server-side sessions" (superseded)
New approach: decision 31 "Switch to JWT tokens"

`deciduous archaeology`

Retroactive graph building – atomic operations for common archaeology patterns. Useful when reconstructing decision history from an existing codebase.

`deciduous archaeology pivot <from_id> <observation> <new_approach>`

Create a full pivot chain atomically (replaces 7 manual commands). Creates: observation -> revisit -> new decision, and marks the old node as superseded.

Flag	Short	Description
`--confidence <0-100>`	`-c`	Confidence for the new decision
`--reason <text>`	`-r`	Rationale for why the old approach failed
`--dry-run`		Show what would be created without modifying database

Terminal

$ deciduous archaeology pivot 15 "Mobile clients can't maintain sessions" "Switch to JWT tokens" -c 85 -r "Stateless auth needed for mobile"
Created observation 29: "Mobile clients can't maintain sessions"
Created revisit 30: "Reconsidering node 15"
Created decision 31: "Switch to JWT tokens" [confidence: 85%]
Linked 15 -> 29 (leads_to)
Linked 29 -> 30 (leads_to)
Linked 30 -> 31 (leads_to)
Marked node 15 as superseded
Pivot chain created (3 nodes, 3 edges)

`deciduous archaeology timeline`

Show all nodes sorted chronologically.

Flag	Short	Description
`--limit <n>`	`-l`	Number of most recent nodes (0 = all, default: 0)
`--node-type <type>`	`-t`	Filter by node type
`--branch <name>`	`-b`	Filter by git branch
`--json`		Output as JSON

Terminal

$ deciduous archaeology timeline -l 5
2025-05-09 14:25:01 47 outcome JWT auth working -- 14 tests passing
2025-05-09 14:22:30 46 action Implement JWT middleware + refresh endpoint
2025-05-09 14:21:02 45 decision Use jsonwebtoken crate for full control
2025-05-09 14:20:15 43 option jsonwebtoken crate + custom refresh logic
2025-05-09 14:20:01 42 goal Add JWT authentication

$ deciduous archaeology timeline -t decision -b feature-auth
2025-05-09 14:21:02 45 decision Use jsonwebtoken crate for full control
2025-05-07 09:15:00 31 decision Switch to JWT tokens

`deciduous archaeology supersede <id>`

Mark a node as superseded, optionally cascading to all descendant nodes.

Flag	Description
`--cascade`	Also mark all descendant nodes as superseded
`--dry-run`	Show what would be changed without modifying database

Terminal

$ deciduous archaeology supersede 15 --cascade --dry-run
Would mark as superseded:
15 decision Use server-side sessions
16 action Implement session store
17 outcome Session auth working
3 nodes would be affected

$ deciduous archaeology supersede 15 --cascade
Marked 3 nodes as superseded

`deciduous roadmap`

Manage ROADMAP.md sync with GitHub Issues. Parse your roadmap file, sync items to GitHub Issues, and track completion.

`deciduous roadmap init`

Initialize roadmap sync – parses ROADMAP.md and adds metadata.

Flag	Short	Description
`--path <file>`	`-p`	Path to ROADMAP.md (default: `ROADMAP.md`)

Terminal

$ deciduous roadmap init
Parsed ROADMAP.md: 3 sections, 12 items
Roadmap initialized

`deciduous roadmap refresh`

Re-parse ROADMAP.md, preserving existing decision graph links.

Flag	Short	Description
`--path <file>`	`-p`	Path to ROADMAP.md (default: `ROADMAP.md`)

`deciduous roadmap sync`

Sync ROADMAP.md with GitHub Issues. Dry-run by default – use --execute to apply.

Flag	Short	Description
`--path <file>`	`-p`	Path to ROADMAP.md (default: `ROADMAP.md`)
`--repo <owner/repo>`	`-r`	GitHub repo (auto-detected from git remote)
`--execute`		Actually apply changes (default is dry-run)
`--create-issues`		Create GitHub issues for new sections (default: true)

Terminal

$ deciduous roadmap sync
Dry-run mode (use --execute to apply)
Would create issue: "Add JWT authentication"
Would create issue: "Add rate limiting"
Would update issue #5: "Database migration tooling"

$ deciduous roadmap sync --execute
Created issue #8: "Add JWT authentication"
Created issue #9: "Add rate limiting"
Updated issue #5: "Database migration tooling"
Synced 3 items

`deciduous roadmap list`

List roadmap items with status.

Flag	Short	Description
`--path <file>`	`-p`	Path to ROADMAP.md (default: `ROADMAP.md`)
`--section <name>`	`-s`	Filter by section name
`--with-issues`		Show only items with GitHub issues
`--without-issues`		Show only items without GitHub issues

Terminal

$ deciduous roadmap list
Core:
[x] Add JWT authentication issue #8 outcome #47
[ ] Add rate limiting issue #9
[ ] Database migration tooling issue #5

Infrastructure:
[x] CI/CD pipeline issue #3 outcome #22
[ ] Monitoring and alerting

`deciduous roadmap link <item> <outcome_id>`

Link a roadmap item to a decision graph outcome node. <item> is a change_id or title (partial match).

`deciduous roadmap unlink <item>`

Remove outcome link from a roadmap item.

`deciduous roadmap conflicts`

Show sync conflicts.

Flag	Description
`--resolve`	Resolve conflicts interactively

`deciduous roadmap status`

Show sync status summary.

Flag	Short	Description
`--path <file>`	`-p`	Path to ROADMAP.md (default: `ROADMAP.md`)

`deciduous roadmap check`

Audit completion status of roadmap items.

Flag	Short	Description
`--path <file>`	`-p`	Path to ROADMAP.md (default: `ROADMAP.md`)
`--incomplete`		Show only incomplete items
`--complete`		Show only complete items

`deciduous doc`

Manage document attachments on decision nodes. Attach images, PDFs, diagrams, specs, and other files to nodes for rich context.

`deciduous doc attach <node_id> <file>`

Attach a file to a decision graph node. Files are stored in .deciduous/documents/ with content-hash naming for deduplication.

Flag	Short	Description
`--description <text>`	`-d`	Manual description
`--ai-describe`		Generate AI description using claude CLI

Terminal

$ deciduous doc attach 42 architecture.png -d "Auth system architecture diagram"
Attached document 1 to node 42
File: architecture.png
Stored: .deciduous/documents/a1b2c3d4e5f6.png

$ deciduous doc attach 42 spec.pdf --ai-describe
Attached document 2 to node 42
File: spec.pdf
Description: API authentication specification covering JWT token format, refresh rotation policy, and OAuth2 flow diagrams

`deciduous doc list [node_id]`

List documents. Omit node_id to list all documents.

Flag	Description
`--include-detached`	Show soft-deleted documents too
`--json`	Output as JSON

Terminal

$ deciduous doc list 42
Documents for node 42 "Add JWT authentication":
1 architecture.png "Auth system architecture diagram"
2 spec.pdf "API authentication specification..."

$ deciduous doc list
All documents:
1 node 42 architecture.png "Auth system architecture diagram"
2 node 42 spec.pdf "API authentication specification..."
3 node 50 rate-limit.md "Rate limiting design notes"

`deciduous doc show <doc_id>`

Show details of a specific document.

Flag	Description
`--json`	Output as JSON

Terminal

$ deciduous doc show 1
Document 1:
Node: 42 "Add JWT authentication"
Original: architecture.png
Stored at: .deciduous/documents/a1b2c3d4e5f6.png
Description: Auth system architecture diagram
Attached: 2025-05-09 14:30:00
Status: active

`deciduous doc describe <doc_id> [text]`

Set or update the description of a document. Omit text to read from stdin.

Flag	Description
`--ai`	Generate AI description using claude CLI

Terminal

$ deciduous doc describe 1 "Updated auth architecture with OAuth2 flows"
Updated description for document 1

$ deciduous doc describe 2 --ai
Generated description: "API authentication specification covering JWT token format, refresh rotation policy, and OAuth2 flow diagrams for Google and GitHub providers"

`deciduous doc open <doc_id>`

Open the attached file in the default application.

Terminal

$ deciduous doc open 1
Opening .deciduous/documents/a1b2c3d4e5f6.png...

`deciduous doc detach <doc_id>`

Soft-delete (detach) a document from its node. The file remains on disk until garbage collected.

Terminal

$ deciduous doc detach 2
Detached document 2 from node 42

`deciduous doc gc`

Garbage-collect orphaned files from disk – files that no active document records reference.

Flag	Description
`--dry-run`	Show what would be deleted without deleting

Terminal

$ deciduous doc gc --dry-run
Would remove 1 orphaned file (340 KB):
.deciduous/documents/b2c3d4e5f6a7.pdf

$ deciduous doc gc
Removed 1 orphaned file (340 KB)

`deciduous themes`

Manage theme definitions for organizing nodes by cross-cutting concerns (e.g., “performance”, “security”, “tech-debt”).

`deciduous themes create <name>`

Create a new theme.

Flag	Short	Description
`--color <hex>`	`-c`	Hex color code (default: `#6b7280`)
`--description <text>`	`-d`	Theme description

Terminal

$ deciduous themes create performance -c "#ef4444" -d "Performance-related decisions and observations"
Created theme "performance" (#ef4444)

$ deciduous themes create security -c "#3b82f6" -d "Security considerations"
Created theme "security" (#3b82f6)

`deciduous themes list`

List all themes.

Terminal

$ deciduous themes list
performance #ef4444 Performance-related decisions and observations (3 nodes)
security #3b82f6 Security considerations (5 nodes)
tech-debt #6b7280 Technical debt items (2 nodes)

`deciduous themes delete <name>`

Delete a theme and remove all node associations.

Terminal

$ deciduous themes delete tech-debt
Deleted theme "tech-debt" and removed 2 node associations

`deciduous tag`

Tag or untag nodes with themes.

`deciduous tag add <node_id> <theme>`

Add a theme to a node.

Terminal

$ deciduous tag add 55 performance
Tagged node 55 with "performance"

$ deciduous tag add 42 security
Tagged node 42 with "security"

`deciduous tag remove <node_id> <theme>`

Remove a theme from a node.

Terminal

$ deciduous tag remove 55 performance
Removed "performance" from node 55

List themes for a node.

Terminal

$ deciduous tag list 42
Themes for node 42 "Add JWT authentication":
security #3b82f6 (manual)
performance #ef4444 (suggested)

`deciduous tag suggest [node_id]`

Auto-suggest themes for a node based on keyword matching. Omit node_id to suggest for all untagged nodes.

Flag	Description
`--apply`	Apply suggestions without confirmation

Terminal

$ deciduous tag suggest 55
Suggested themes for node 55 "Redis adds 2ms latency per request":
performance (keyword match: "latency")

$ deciduous tag suggest --apply
Suggested and applied:
Node 55 -> performance (keyword: "latency")
Node 61 -> performance (keyword: "cache")
Node 42 -> security (keyword: "auth")
3 suggestions applied

`deciduous tag confirm <node_id> <theme>`

Confirm a suggested theme – changes it from “suggested” to “manual” status.

Terminal

$ deciduous tag confirm 55 performance
Confirmed "performance" on node 55 (suggested -> manual)

Keyboard shortcuts

Deciduous