attckdigital/smith/smith-ledger

Smith Ledger — Knowledge Base Management

Browse, search, and manage the Smith Ledger. The Ledger is the persistent knowledge base that captures patterns, antipatterns, tool preferences, edge cases, and project quirks learned from past Smith workflows. It lives at .smith/vault/ledger/.

Arguments: $ARGUMENTS

Vault Logging

Throughout this action, log significant events to the vault session log. Read the session log path from .smith/vault/.current-session. If the file is missing or the vault is not initialized, skip all logging silently.

Timestamps are UTC. HH:MM:SS comes from date -u +%H:%M:%S — never a local clock, never a time from memory. The append already runs through a shell, so read the clock in that same command (TS=$(date -u +%H:%M:%S)) and spend no extra tool call. Substitute the resulting value: an unexpanded $(...) reaching the log is a known regression and will not parse. Every hook-written stamp in this log is date -u, so a local-clock entry lands hours away from its neighbours and skews the workflow window hooks/workflow_summary_lib.py derives from them.

Append entries using this format:

### [HH:MM:SS] /smith-ledger <event>
 
**User Request:**
> <verbatim user message that triggered this action>
 
**Subcommand:** <dashboard|list|show|search|prune|promote|demote|export|reset>
**Synthesized Input:** <brief summary of args/filters>
**Outcome:** <what happened — counts, changes made, results found>
**Artifacts:** <files read/modified>
**Systems affected:** <system IDs>

Log at these points:

1. On invocation — which subcommand was used and with what arguments
2. After any mutation — prune, promote, demote, or reset operations that modify Ledger files

Ledger Directory Structure

The Ledger lives at .smith/vault/ledger/ with the following files:

.smith/vault/ledger/
  meta.yaml             # Overview stats — last reflection date, total counts, config
  patterns.md           # Validated approaches that work well
  antipatterns.md       # Approaches that failed or caused problems
  tool-preferences.md   # Tool/library/API usage preferences and gotchas
  edge-cases.md         # Non-obvious behaviors, boundary conditions, quirks in tools/APIs
  project-quirks.md     # Project-specific conventions, workarounds, and constraints
  archive/              # Archived Ledger snapshots from resets

Ledger Entry Format

Each Ledger file (patterns.md, antipatterns.md, etc.) contains entries in this format:

## <Title>
 
-**Date:** YYYY-MM-DD
-**Category:** implementation | testing | debugging | specification | audit
-**Confidence:** low | medium | high
-**Observations:** N
-**Source reflections:** <comma-separated list of reflection session dates or spec IDs>
 
### Context
 
<When and why this pattern/antipattern/preference/edge-case applies>
 
### Pattern
 
<The actual pattern, antipattern, tool preference, edge case, or project quirk — what to do or what to avoid>
 
### Evidence
 
<Specific examples from past workflows that support this entry>
 
### Related
 
<Links to related entries, specs, or code files>
 
---

meta.yaml Format

last_reflection: "YYYY-MM-DD"
total_reflections: N
total_entries: N
config:
  low_confidence_prune_days: 30
  medium_confidence_demote_days: 90
entries_by_file:
  patterns: N
  antipatterns: N
  tool-preferences: N
  edge-cases: N
  project-quirks: N

Subcommands

/smith-ledger (no args) — Dashboard

Display a summary dashboard:

1. Check if `.smith/vault/ledger/` exists. If not, display the following and stop:

`` No Ledger found. Run /smith-reflect after a workflow to start building the Ledger, or run /smith to initialize the vault structure. ``

1. Read `meta.yaml` for overview stats (last reflection date, total reflections, total entries, config).

1. Read each Ledger file and count entries by confidence level. An entry boundary is a line starting with ## (heading level 2). Extract the **Confidence:** value from each entry.

1. Display the dashboard:

SMITH LEDGER — Dashboard
========================
 
Last reflection: YYYY-MM-DD
Total reflections: N
Total entries: N
 
| File                | Entries | High | Medium | Low |
|---------------------|---------|------|--------|-----|
| patterns.md         |    N    |  N   |   N    |  N  |
| antipatterns.md     |    N    |  N   |   N    |  N  |
| tool-preferences.md |    N    |  N   |   N    |  N  |
| edge-cases.md       |    N    |  N   |   N    |  N  |
| project-quirks.md   |    N    |  N   |   N    |  N  |
 
Top High-Confidence Patterns:
1. [Title] — [Category] ([N] observations)
2. [Title] — [Category] ([N] observations)
3. [Title] — [Category] ([N] observations)

If there are no high-confidence entries, show "No high-confidence entries yet." instead of the Top Patterns section.

Show up to 5 high-confidence entries, sorted by observation count descending. Draw from all Ledger files, not just patterns.md.

/smith-ledger list — List Entries

List all entries, optionally filtered by category, confidence, or file.

Flags:

• --category <cat> — Filter by category. Valid values: implementation, testing, debugging, specification, audit
• --confidence <level> — Filter by confidence. Valid values: low, medium, high
• --file <filename> — Show only entries from a specific file. Valid values: patterns, antipatterns, tools (alias for tool-preferences), edge-cases, quirks (alias for project-quirks)

Flags can be combined. When multiple flags are provided, apply all filters (AND logic).

No flags: List all entries across all files, grouped by file.

Display format per entry:

[confidence] Title — Category (N observations, last: YYYY-MM-DD)

Group entries under their file heading:

--- patterns.md ---
[high] Always rebuild Docker after code changes — implementation (4 observations, last: 2026-04-01)
[medium] Use processing_ledger for pipeline stages — implementation (2 observations, last: 2026-03-28)
 
--- antipatterns.md ---
[high] Don't mock the database in integration tests — testing (3 observations, last: 2026-04-05)

If no entries match the filters, display: "No entries match the given filters."

/smith-ledger show <title> — Show Full Entry

Search across all Ledger files for an entry whose ## <Title> heading matches the given title. Matching is case-insensitive and supports partial matches (the query is a substring of the title).

Single match: Display the full entry including all fields (title, date, category, confidence, observations, source reflections, context, pattern, evidence, related). Also display the source file name.

Multiple matches: List them with index numbers and ask which one to display:

Multiple entries match "docker":
 
1. [high] Always rebuild Docker after code changes — patterns.md
2. [medium] Docker Compose ordering matters for healthchecks — edge-cases.md
3. [low] Docker layer caching invalidation — tool-preferences.md
 
Which entry would you like to see? (1-3)

No matches: Display: No entries found matching "<title>".

/smith-ledger search <query> — Search

Search across all Ledger files for the query string using case-insensitive matching.

For each match:

1. Identify which entry the match belongs to (find the nearest preceding ## heading)
2. Display the entry title, file, and confidence
3. Show the matching line with surrounding context (2 lines before and after)

Display format:

--- patterns.md: "Always rebuild Docker after code changes" [high] ---
  ...
  Docker containers cache the build artifacts. When you change source code,
> the running container still has the old code unless you rebuild.
  Always run `docker compose up -d --build <service>` after changes.
  ...
 
--- edge-cases.md: "Qdrant WAL recovery on unclean shutdown" [medium] ---
  ...
  If Colima is stopped without first running `docker compose down`,
> Qdrant will perform WAL recovery on next start, which can take hours
  with large collections (935K+ entries).
  ...

If no matches found, display: No results for "<query>".

/smith-ledger prune — Interactive Pruning

Scan all Ledger files for prune candidates based on age and confidence:

1. Identify candidates:

• Remove candidates: Low-confidence entries where the **Date:** is older than config.low_confidence_prune_days days (default: 30)
• Demote candidates: Medium-confidence entries where the **Date:** is older than config.medium_confidence_demote_days days (default: 90). These will be demoted to low confidence, not removed.

1. Read config values from meta.yaml under config:. If meta.yaml is missing or config values are absent, use defaults (30 days for low, 90 days for medium).

1. Display candidates grouped by action:

SMITH LEDGER — Prune Candidates
================================
 
Entries to REMOVE (low confidence, older than 30 days):
  1. "Ruff format before commit" — tool-preferences.md (dated 2026-02-15)
  2. "Check Neo4j constraints on startup" — patterns.md (dated 2026-02-20)
 
Entries to DEMOTE to low (medium confidence, older than 90 days):
  3. "Qdrant batch size limit" — edge-cases.md (dated 2026-01-10)
 
Total: 2 removals, 1 demotion

1. Prompt for confirmation: Remove 2 entries and demote 1 entry? (yes/no)

1. If confirmed:

• Remove the identified entries from their respective files (delete the entire entry block from ## to the next --- separator or end of file)
• Demote identified entries by changing their **Confidence:** value from medium to low
• Update meta.yaml counts accordingly
• Report: Pruned: 2 removed, 1 demoted. Total entries: N

1. If declined: Display: Prune cancelled. No changes made.

If no candidates are found, display: No prune candidates found. Ledger is clean.

/smith-ledger prune --auto — Automatic Pruning

Same logic as interactive prune but without confirmation. Execute immediately and report results.

Display:

Auto-prune complete: N removed, M demoted. Total entries: N

/smith-ledger promote <title> — Promote Confidence

1. Find the entry by title using the same case-insensitive partial match logic as show.
2. If multiple matches, list them and ask which one to promote.
3. Raise confidence one level:

• low -> medium
• medium -> high
• high -> Display: "<Title>" is already at high confidence. No change.

1. Update the entry in place in its Ledger file — change the **Confidence:** line.
2. Report: Promoted "<Title>" from <old> to <new> confidence.

/smith-ledger demote <title> — Demote Confidence

1. Find the entry by title using the same case-insensitive partial match logic as show.
2. If multiple matches, list them and ask which one to demote.
3. Lower confidence one level:

• high -> medium
• medium -> low
• low -> Display: "<Title>" is already at low confidence. No change.

1. Update the entry in place in its Ledger file — change the **Confidence:** line.
2. Report: Demoted "<Title>" from <old> to <new> confidence.

/smith-ledger export — Export Full Ledger

Concatenate all Ledger files into a single markdown document and output it to chat.

Format:

1. Start with the contents of meta.yaml wrapped in a YAML code block
2. For each Ledger file (in order: patterns, antipatterns, tool-preferences, edge-cases, project-quirks):

• Add a level-1 heading: # <filename>
• Include the full file contents

Output the entire document to chat. Do not write it to a file unless the user explicitly asks.

/smith-ledger reset — Reset Ledger