fix: always load archived beans, remove --with-archived flag (#33)

hmans · web-flow · commit d7b01db0dbfd · 2025-12-27T22:56:49.000+01:00
## Summary

- Remove the `--with-archived` flag entirely
- Always load beans from all subdirectories within `.beans/`
- Archive becomes purely organizational (keeps `.beans/` tidy) rather
than an access control mechanism

## Problem

The `--with-archived` flag created a usability antipattern where users
(or agents) needed prior knowledge about whether something was archived
to find it. This led to surprising scenarios where searches would fail
to find beans that existed but were archived.

## Solution

1. **Archived beans are always loaded** - No flag needed
2. **All subdirectories are now supported** - The loading mechanism now
recursively finds all `.md` files within `.beans/`, preparing for future
features like auto-filing beans into per-milestone or per-epic
directories

## Changes

### Commit 1: Remove `--with-archived` flag
- **cmd/root.go**: Removed `withArchived` variable and flag registration
- **internal/beancore/core.go**: Removed `withArchived` field,
`SetWithArchived()`, `WithArchived()` methods
- **cmd/archive.go**: Updated description
- **cmd/check.go**: Removed special handling that was enabling the flag

### Commit 2: Load beans from all subdirectories
- **internal/beancore/core.go**: Replace `loadFromDisk` +
`loadBeansFromDir` with `filepath.WalkDir` to recursively load all `.md`
files
- **internal/beancore/watcher.go**: Watch all subdirectories, not just
root + archive
- **internal/beancore/core_test.go**: Add `TestLoadFromSubdirectories`
to document the new behavior
- **cmd/prompt.tmpl**: Update agent instructions to remove
`--with-archived` references

## Test plan

- [x] All existing tests pass
- [x] Build succeeds
- [x] Verified `--with-archived` flag is no longer available
- [x] Verified beans in nested subdirectories are loaded correctly
- [x] New test documents loading from arbitrary subdirectory structures
- [x] Agent prompt template updated
diff --git a/.beans/beans-0ajg--beans-complete-command.md b/.beans/beans-0ajg--beans-complete-command.md
@@ -0,0 +1,23 @@
+---
+# beans-0ajg
+title: beans complete command
+status: todo
+type: task
+created_at: 2025-12-27T21:44:04Z
+updated_at: 2025-12-27T21:44:04Z
+parent: beans-mmyp
+---
+
+Add `beans complete <id> [--summary <text>]` command.
+
+## Behavior
+
+- Sets status to `completed`
+- Optional `--summary` flag to add a completion note to the bean body
+- Shows confirmation message with bean title
+
+## Example
+
+```bash
+beans complete beans-abc --summary "Implemented via PR #42"
+```
diff --git a/.beans/beans-18db--beans-milestones-command.md b/.beans/beans-18db--beans-milestones-command.md
@@ -0,0 +1,25 @@
+---
+# beans-18db
+title: beans milestones command
+status: todo
+type: task
+created_at: 2025-12-27T21:44:05Z
+updated_at: 2025-12-27T21:44:05Z
+parent: beans-mmyp
+---
+
+Add `beans milestones` command to list planned milestones.
+
+## Behavior
+
+- Lists all beans with type `milestone`
+- Shows progress (e.g., "3/10 children completed")
+- Sorted by priority or a target date if we add that field
+- Excludes completed/scrapped milestones by default (`--all` to include)
+
+## Example
+
+```bash
+beans milestones
+# Lists active milestones with their progress
+```
diff --git a/.beans/beans-7kb7--beans-blocked-command.md b/.beans/beans-7kb7--beans-blocked-command.md
@@ -0,0 +1,25 @@
+---
+# beans-7kb7
+title: beans blocked command
+status: todo
+type: task
+created_at: 2025-12-27T21:44:05Z
+updated_at: 2025-12-27T21:44:05Z
+parent: beans-mmyp
+---
+
+Add `beans blocked` command to show beans that are currently blocked.
+
+## Behavior
+
+- Lists beans that have blockers (other beans blocking them)
+- Shows what is blocking each bean
+- Helps identify bottlenecks in the project
+
+## Example
+
+```bash
+beans blocked
+# Shows:
+# beans-abc: "Add auth" (blocked by beans-xyz: "Set up database")
+```
diff --git a/.beans/beans-8q44--beans-ready-command.md b/.beans/beans-8q44--beans-ready-command.md
@@ -0,0 +1,25 @@
+---
+# beans-8q44
+title: beans ready command
+status: todo
+type: task
+created_at: 2025-12-27T21:44:04Z
+updated_at: 2025-12-27T21:44:04Z
+parent: beans-mmyp
+---
+
+Add `beans ready` command to find beans that are ready to work on.
+
+## Behavior
+
+- Shows beans with actionable status (`todo`) that are not blocked
+- Sorted by priority (critical → high → normal → low → deferred)
+- Excludes `completed`, `scrapped`, `draft`, and `in-progress`
+- Supports `--json` output
+
+## Example
+
+```bash
+beans ready
+# Lists all beans ready to pick up
+```
diff --git a/.beans/beans-jvkq--beans-start-command.md b/.beans/beans-jvkq--beans-start-command.md
@@ -0,0 +1,24 @@
+---
+# beans-jvkq
+title: beans start command
+status: todo
+type: task
+created_at: 2025-12-27T21:44:04Z
+updated_at: 2025-12-27T21:44:04Z
+parent: beans-mmyp
+---
+
+Add `beans start <id>` command.
+
+## Behavior
+
+- Sets status to `in-progress`
+- Displays the bean details (like `beans show`) so you can see what you're working on
+- Could optionally check if another bean is already in-progress and warn
+
+## Example
+
+```bash
+beans start beans-abc
+# Sets to in-progress and shows the bean
+```
diff --git a/.beans/beans-m364--beans-progress-command.md b/.beans/beans-m364--beans-progress-command.md
@@ -0,0 +1,29 @@
+---
+# beans-m364
+title: beans progress command
+status: todo
+type: task
+created_at: 2025-12-27T21:44:05Z
+updated_at: 2025-12-27T21:44:05Z
+parent: beans-mmyp
+---
+
+Add `beans progress` command to show a summary of work status.
+
+## Behavior
+
+- Shows counts by status (e.g., "5 in-progress, 12 todo, 8 completed")
+- Could show a simple progress bar
+- Optional: filter by milestone/epic to see progress on specific initiatives
+
+## Example
+
+```bash
+beans progress
+# Output:
+# In Progress: 2
+# Todo: 15  
+# Completed: 23
+# Scrapped: 3
+# ━━━━━━━━━━━━━━━━ 57% complete
+```
diff --git a/.beans/beans-mmyp--workflow-cli-commands.md b/.beans/beans-mmyp--workflow-cli-commands.md
@@ -0,0 +1,25 @@
+---
+# beans-mmyp
+title: Workflow CLI commands
+status: todo
+type: epic
+created_at: 2025-12-27T21:43:38Z
+updated_at: 2025-12-27T21:43:38Z
+---
+
+Add explicit workflow-style CLI commands that provide intuitive shortcuts for common operations. These commands wrap existing functionality with cleaner, more memorable interfaces.
+
+## Rationale
+
+Currently, users need to use `beans update <id> -s completed` to complete a bean. Workflow commands like `beans complete <id>` are more intuitive and can enforce best practices (like requiring a reason when scrapping).
+
+## Proposed Commands
+
+- `beans complete` - Complete a bean with optional summary
+- `beans scrap` - Scrap a bean with required reason  
+- `beans start` - Start working on a bean
+- `beans ready` - Find beans ready to work on
+- `beans next` - Show the next bean to work on
+- `beans milestones` - List planned milestones
+- `beans blocked` - Show blocked beans
+- `beans progress` - Show work progress summary
diff --git a/.beans/beans-p17z--beans-next-command.md b/.beans/beans-p17z--beans-next-command.md
@@ -0,0 +1,24 @@
+---
+# beans-p17z
+title: beans next command
+status: todo
+type: task
+created_at: 2025-12-27T21:44:04Z
+updated_at: 2025-12-27T21:44:04Z
+parent: beans-mmyp
+---
+
+Add `beans next` command to show the single most important bean to work on.
+
+## Behavior
+
+- Returns the highest-priority `todo` bean that is not blocked
+- Shows full bean details (like `beans show`)
+- If nothing is ready, suggests checking `beans blocked` or `beans list`
+
+## Example
+
+```bash
+beans next
+# Shows the single most important bean to tackle
+```
diff --git a/.beans/beans-r780--beans-scrap-command.md b/.beans/beans-r780--beans-scrap-command.md
@@ -0,0 +1,24 @@
+---
+# beans-r780
+title: beans scrap command
+status: todo
+type: task
+created_at: 2025-12-27T21:44:04Z
+updated_at: 2025-12-27T21:44:04Z
+parent: beans-mmyp
+---
+
+Add `beans scrap <id> --reason <text>` command.
+
+## Behavior
+
+- Sets status to `scrapped`
+- **Required** `--reason` flag to document why the bean was scrapped
+- Adds a `## Reason for Scrapping` section to the bean body (preserves project memory)
+- Shows confirmation message
+
+## Example
+
+```bash
+beans scrap beans-abc --reason "Superseded by beans-xyz approach"
+```
diff --git a/cmd/archive.go b/cmd/archive.go
@@ -14,8 +14,8 @@ var archiveCmd = &cobra.Command{
 	Use:   "archive",
 	Short: "Move completed/scrapped beans to the archive",
 	Long: `Moves all beans with status "completed" or "scrapped" to the archive directory (.beans/archive/).
-Archived beans are preserved for project memory but excluded from normal queries.
-Use --with-archived flag on other commands to include archived beans.
+Archived beans are preserved for project memory and remain visible in all queries.
+The archive keeps the main .beans directory tidy while preserving project history.
 
 Relationships (parent, blocking) are preserved in archived beans.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
diff --git a/cmd/check.go b/cmd/check.go
@@ -33,18 +33,8 @@ var checkCmd = &cobra.Command{
 - Circular dependencies (cycles in blocks/parent relationships)
 
 Use --fix to automatically remove broken links and self-references.
-Note: Cycles cannot be auto-fixed and require manual intervention.
-
-This command always includes archived beans to ensure link validation is complete.`,
+Note: Cycles cannot be auto-fixed and require manual intervention.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
-		// Always include archived beans for complete link validation
-		if !core.WithArchived() {
-			core.SetWithArchived(true)
-			if err := core.Load(); err != nil {
-				return fmt.Errorf("loading archived beans: %w", err)
-			}
-		}
-
 		var configErrors []string
 		var fixed int
 
diff --git a/cmd/prompt.tmpl b/cmd/prompt.tmpl
@@ -5,7 +5,6 @@ This project uses **beans**, an agentic-first issue tracker. Issues are called "
 
 - **Always use beans instead of TodoWrite to manage your work and tasks.**
 - **Always use beans instead of writing todo lists.**
-- **Use `--with-archived` to access project memory** (this will make beans include archived beans).
 
 All commands support `--json` for machine-readable output. Use this flag to parse responses easily.
 
@@ -127,19 +126,20 @@ beans query '{ beans(filter: { noParent: true }) { id title type } }'
 ## Archiving beans
 
 - `beans archive` moves beans marked as completed or scrapped to `.beans/archive/`. ONLY run this when the user explicitly tells you to do so.
-- Archived beans are preserved as **project memory** but excluded from normal queries.
+- Archived beans are preserved as **project memory** and remain visible in all queries.
+- The archive keeps the main `.beans/` directory tidy while preserving project history.
 - **IMPORTANT**: When scrapping a bean, always add a note explaining *why* it was scrapped. This helps future agents understand past decisions.
 
 ## Using archived beans for context
 
 Archived beans serve as project memory. Before starting new work, consider checking if similar work was done before:
 
 ```bash
-# Search archived beans for relevant context
-beans query --with-archived '{ beans(filter: { search: "authentication" }) { id title status body } }'
+# Search for relevant context (includes archived beans automatically)
+beans query '{ beans(filter: { search: "authentication" }) { id title status body } }'
 
-# Find all archived beans
-beans query --with-archived '{ beans(filter: { status: ["completed", "scrapped"] }) { id title status } }'
+# Find all completed/scrapped beans
+beans query '{ beans(filter: { status: ["completed", "scrapped"] }) { id title status } }'
 ```
 
 Use this to:
diff --git a/cmd/root.go b/cmd/root.go
@@ -13,7 +13,6 @@ var core *beancore.Core
 var cfg *config.Config
 var beansPath string
 var configPath string
-var withArchived bool
 
 var rootCmd = &cobra.Command{
 	Use:   "beans",
@@ -67,7 +66,6 @@ a full view of your project.`,
 		}
 
 		core = beancore.New(root, cfg)
-		core.SetWithArchived(withArchived)
 		if err := core.Load(); err != nil {
 			return fmt.Errorf("loading beans: %w", err)
 		}
@@ -79,7 +77,6 @@ a full view of your project.`,
 func init() {
 	rootCmd.PersistentFlags().StringVar(&beansPath, "beans-path", "", "Path to data directory (overrides config)")
 	rootCmd.PersistentFlags().StringVar(&configPath, "config", "", "Path to config file (default: searches upward for .beans.yml)")
-	rootCmd.PersistentFlags().BoolVar(&withArchived, "with-archived", false, "Include archived beans (from .beans/archive/)")
 }
 
 func Execute() {
diff --git a/internal/beancore/core.go b/internal/beancore/core.go
diff --git a/internal/beancore/core_test.go b/internal/beancore/core_test.go
diff --git a/internal/beancore/watcher.go b/internal/beancore/watcher.go
