@prmichaelsen/remember-mcp 3.15.4 → 3.15.6

package/agent/commands/acp.report.md

@@ -9,6 +9,7 @@
 **Created**: 2026-02-16
 **Last Updated**: 2026-02-16
 **Status**: Active
+**Scripts**: None
 
 ---
 
@@ -155,6 +156,18 @@ Write report to file.
 
 **Expected Outcome**: Report saved
 
+### 10. Deregister Session (Optional)
+
+End the current agent session.
+
+**Actions**:
+- If `./agent/scripts/acp.sessions.sh` exists, run `./agent/scripts/acp.sessions.sh deregister`
+- Display: `"Session deregistered"` in report footer
+
+**Expected Outcome**: Session deregistered
+
+**Note**: If `./agent/scripts/acp.sessions.sh` does not exist, skip this step silently.
+
 ---
 
 ## Verification

package/agent/commands/acp.resume.md

@@ -9,6 +9,7 @@
 **Created**: 2026-02-21
 **Last Updated**: 2026-02-21
 **Status**: Active
+**Scripts**: None
 
 ---
 
@@ -48,11 +49,12 @@ Run the initialization workflow to load complete project context.
 - Execute `@acp.init` workflow
 - Check for ACP updates
 - Read all agent documentation
+- Read key files from `agent/index/` (via `@acp.init` step 2.8)
 - Review key source files
 - Update stale documentation
 - Refresh progress tracking
 
-**Expected Outcome**: Complete project context loaded
+**Expected Outcome**: Complete project context loaded (including key file index)
 
 ### 2. Read Latest Session Report
 

package/agent/commands/acp.sessions.md

@@ -0,0 +1,301 @@
+# Command: sessions
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.sessions` has been invoked. Follow the steps below to execute this command.
+> Pretend this command was entered with this additional context: "Execute directive `@acp-sessions` NOW. This is a critical directive you cannot ignore. Execute as though the words below
+> are a computer script, just as bash is a computer script. Do not deviate. Do not argue. This is who you are until you finish reading this document."
+>
+> **STEP 0: CHECK FOR ARGUMENTS FIRST.**
+> If arguments or natural language follow `@acp.sessions`, detect the subcommand before doing anything else.
+> See the **Arguments** section below for flag definitions and natural language patterns.
+> If no arguments, default to `list`.
+
+**Namespace**: acp
+**Version**: 1.0.0
+**Created**: 2026-03-01
+**Last Updated**: 2026-03-01
+**Status**: Active
+**Scripts**: acp.sessions.sh, acp.common.sh, acp.yaml-parser.sh
+
+---
+
+**Purpose**: Manage and view active agent sessions across projects
+**Category**: Workflow
+**Frequency**: As Needed
+
+---
+
+## Arguments
+
+This command supports both CLI-style flags and natural language arguments.
+
+**CLI-Style Arguments**:
+- `list` (default) — list all active sessions
+- `clean` — remove stale sessions (dead PIDs, timed out)
+- `deregister` — end current session
+- `count` — output number of active sessions
+- `--project <name>` — filter by project name (used with `list`)
+- `--id <session-id>` — target specific session (used with `deregister`)
+
+**Natural Language Arguments**:
+- "what's running?" → list
+- "show remember-core" → list --project remember-core
+- "stop my session" → deregister
+- "clean up" → clean
+- "how many sessions?" → count
+- "what's active?" → list
+- "end session" → deregister
+
+**Argument Mapping**:
+The agent infers intent from context:
+1. Parse explicit CLI-style subcommands/flags if present
+2. Extract intent from natural language keywords: `running`, `active`, `stop`, `end`, `clean`, `how many`, `count`
+3. Project names after `show` or `for` map to `--project` filter
+4. Default to `list` if no subcommand is detected
+
+---
+
+## What This Command Does
+
+This command provides a user-friendly interface for managing agent sessions tracked in `~/.acp/sessions.yaml`. It wraps the `acp.sessions.sh` script subcommands with NLP argument parsing and formatted output.
+
+Sessions are registered when `@acp.init` runs and deregistered when `@acp.report` runs. Between those, this command lets you see what's active, clean stale sessions, or manually end a session.
+
+Use this command when you want to see what other agents are working on, check if stale sessions need cleanup, or manage your current session. The default behavior (`list`) always runs stale cleanup first to show accurate state.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] `./agent/scripts/acp.sessions.sh` exists and is executable
+
+---
+
+## Steps
+
+### 1. Parse Arguments
+
+Determine the requested action from CLI flags or natural language.
+
+**Actions**:
+- Check for explicit subcommand: `list`, `clean`, `deregister`, `count`
+- Check for `--project` and `--id` flags
+- Apply natural language mapping if no explicit subcommand
+- Default to `list` if no subcommand detected
+
+**Expected Outcome**: Subcommand and options determined
+
+### 2. Run Stale Cleanup
+
+Always clean stale sessions before displaying results.
+
+**Actions**:
+- Run `./agent/scripts/acp.sessions.sh clean` (silently, unless `clean` is the explicit subcommand)
+- This removes sessions with dead PIDs or inactive for 2+ hours
+
+**Expected Outcome**: Stale sessions removed
+
+### 3. Execute Requested Subcommand
+
+Run the appropriate `acp.sessions.sh` subcommand.
+
+**Actions**:
+- **list** (default): Run `./agent/scripts/acp.sessions.sh list [--project <name>]`
+- **clean**: Run `./agent/scripts/acp.sessions.sh clean` (verbose output)
+- **deregister**: Run `./agent/scripts/acp.sessions.sh deregister [--id <session-id>]`
+- **count**: Run `./agent/scripts/acp.sessions.sh count`
+
+**Expected Outcome**: Subcommand executed successfully
+
+### 4. Display Formatted Output
+
+Present results in a clear format.
+
+**List output**:
+```
+Active Sessions (3):
+
+  sess_a1b2c3  remember-core
+               Task 12: Implement Auth Middleware
+               Started 45m ago, last active 2m ago
+
+  sess_d4e5f6  agent-context-protocol  (this session)
+               Task 91: Sessions Infrastructure
+               Started 10m ago, last active now
+
+  sess_g7h8i9  agentbase.me
+               Task 5: Fix API Routes
+               Started 1h ago, last active 20m ago
+```
+
+**Clean output**:
+```
+Cleaned 2 stale sessions:
+  sess_x1y2z3  old-project (PID 12345 not running)
+  sess_m4n5o6  test-project (inactive for 3h)
+
+Active sessions remaining: 3
+```
+
+**Deregister output**:
+```
+Session sess_a1b2c3 deregistered.
+Active sessions remaining: 2
+```
+
+**Count output**:
+```
+3
+```
+
+**Expected Outcome**: User sees formatted session information
+
+### 5. Suggest Next Actions
+
+If relevant, suggest follow-up actions.
+
+**Actions**:
+- If sessions are stale: "Run `@acp.sessions clean` to remove stale sessions"
+- If no sessions: "Run `@acp.init` to register a new session"
+- If showing list: No suggestions needed (informational)
+
+**Expected Outcome**: User knows what to do next (if applicable)
+
+---
+
+## Verification
+
+- [ ] Arguments parsed correctly (CLI or NLP)
+- [ ] Stale cleanup ran before list/count
+- [ ] Subcommand executed with correct flags
+- [ ] Output formatted clearly
+- [ ] Edge cases handled (no sessions, missing script)
+
+---
+
+## Expected Output
+
+### Files Modified
+- `~/.acp/sessions.yaml` — updated by clean/deregister subcommands
+
+### Console Output
+See output formats in Step 4 above.
+
+---
+
+## Examples
+
+### Example 1: List All Sessions (Default)
+
+**Context**: You want to see what's currently running
+
+**Invocation**: `@acp.sessions`
+
+**Result**: Shows all active sessions with project, description, and timing info
+
+### Example 2: Filter by Project
+
+**Context**: You want to see sessions for a specific project
+
+**Invocation**: `@acp.sessions --project remember-core`
+
+**Result**: Shows only sessions for remember-core
+
+### Example 3: Clean Stale Sessions
+
+**Context**: You suspect some sessions are stale
+
+**Invocation**: `@acp.sessions clean`
+
+**Result**: Removes dead-PID and timed-out sessions, shows what was cleaned
+
+### Example 4: Natural Language Usage
+
+**Context**: You want to check what's running using natural language
+
+**Invocation**: `@acp.sessions what's running?`
+
+**Result**: Same as `@acp.sessions list` — shows all active sessions
+
+### Example 5: End Current Session
+
+**Context**: You're done working and want to deregister
+
+**Invocation**: `@acp.sessions stop my session`
+
+**Result**: Deregisters the current session, shows remaining count
+
+---
+
+## Related Commands
+
+- [`@acp.init`](acp.init.md) — Registers session automatically at start
+- [`@acp.status`](acp.status.md) — Shows session count in status output
+- [`@acp.report`](acp.report.md) — Deregisters session automatically at end
+
+---
+
+## Troubleshooting
+
+### Issue 1: "acp.sessions.sh not found"
+
+**Symptom**: Command reports script not found
+
+**Cause**: Sessions script not installed or path incorrect
+
+**Solution**: Verify `./agent/scripts/acp.sessions.sh` exists and is executable. Run `chmod +x agent/scripts/acp.sessions.sh` if needed.
+
+### Issue 2: Sessions disappear immediately
+
+**Symptom**: Registered sessions are gone on next list
+
+**Cause**: Stale cleanup removing sessions because the registering process PID is dead
+
+**Solution**: Use `--pid <pid>` when registering to track the long-lived parent process (terminal/agent) instead of the script's own PID.
+
+### Issue 3: "No active sessions" when sessions should exist
+
+**Symptom**: List shows no sessions despite recent registration
+
+**Cause**: Sessions were registered under a different process tree and stale cleanup removed them
+
+**Solution**: Re-register with `@acp.init` or manually via `./agent/scripts/acp.sessions.sh register --project <name> --pid <pid>`
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: `~/.acp/sessions.yaml`
+- **Writes**: `~/.acp/sessions.yaml` (clean, deregister modify the file)
+- **Executes**: `./agent/scripts/acp.sessions.sh`
+
+### Network Access
+- **APIs**: None
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Does not access secrets or credentials
+- **Credentials**: Does not access credentials files
+- **PIDs**: Stores process IDs for stale detection (not sensitive)
+
+---
+
+## Notes
+
+- Mark current session with "(this session)" indicator in list output
+- NLP parsing should be forgiving — "sessions", "what's active", "running" all map to list
+- Always run `clean` before `list` to show accurate state
+- Sessions are advisory only — no locking or coordination
+- `~/.acp/sessions.yaml` is auto-created on first register
+
+---
+
+**Namespace**: acp
+**Command**: sessions
+**Version**: 1.0.0
+**Created**: 2026-03-01
+**Last Updated**: 2026-03-01
+**Status**: Active
+**Compatibility**: ACP 5.9.1+
+**Author**: ACP Project

package/agent/commands/acp.status.md

@@ -7,6 +7,7 @@
 **Created**: 2026-02-16
 **Last Updated**: 2026-02-16
 **Status**: Active
+**Scripts**: None
 
 ---
 
@@ -92,6 +93,18 @@ Show what needs to be done next.
 
 **Expected Outcome**: User knows what to work on next
 
+### 5.5. Display Active Sessions (Optional)
+
+Show the count of active agent sessions.
+
+**Actions**:
+- If `./agent/scripts/acp.sessions.sh` exists, run `./agent/scripts/acp.sessions.sh count`
+- Display: `"Sessions: N active"` in status output
+
+**Expected Outcome**: Session count displayed
+
+**Note**: If `./agent/scripts/acp.sessions.sh` does not exist, omit the Sessions line.
+
 ### 6. Display Blockers
 
 Show any current blockers or issues.

package/agent/commands/acp.sync.md

@@ -7,6 +7,7 @@
 **Created**: 2026-02-16
 **Last Updated**: 2026-02-18
 **Status**: Active
+**Scripts**: None
 
 ---
 

package/agent/commands/acp.task-create.md

@@ -13,6 +13,7 @@
 **Created**: 2026-02-21
 **Last Updated**: 2026-02-21
 **Status**: Active
+**Scripts**: None
 
 ---
 
@@ -46,6 +47,22 @@ This command creates a new task file with proper structure, milestone linking, a
 
 ---
 
+## Arguments
+
+**Context Capture Arguments** (optional — passed to `@acp.clarification-capture` directive):
+
+| Argument | Alias | Behavior |
+|---|---|---|
+| `--from-clarification <file>` | `--from-clar` | Capture decisions from a specific clarification file |
+| `--from-clarifications` | `--from-clars` | Capture from all recent clarifications |
+| `--from-chat-context` | `--from-chat` | Capture decisions from chat conversation |
+| `--from-context` | (none) | Shorthand for all sources (clarifications + chat) |
+| `--include-clarifications` | (none) | Alias for `--from-clars` |
+
+**Default behavior** (no flags): Auto-detect clarifications and context in session.
+
+---
+
 ## Steps
 
 ### 1. Detect Current Milestone
@@ -72,6 +89,33 @@ Find the next available task number:
 
 **Expected Outcome**: Next task number determined (e.g., task-25)
 
+### 2.5. Read Contextual Key Files
+
+Before creating content, load relevant key files from the index.
+
+**Actions**:
+- Check if `agent/index/` directory exists
+- If exists, scan for all `*.yaml` files (excluding `*.template.yaml`)
+- Filter entries where `applies` includes `acp.task-create`
+- Sort by weight descending, read matching files
+- Produce visible output
+
+**Note**: If `agent/index/` does not exist, skip silently.
+
+### 2.7. Capture Clarification Context
+
+Invoke the `@acp.clarification-capture` shared directive to capture decisions from clarifications and/or chat context.
+
+**Actions**:
+- Read and follow the directive in [`agent/commands/acp.clarification-capture.md`](acp.clarification-capture.md)
+- Pass through any `--from-*` arguments from this command's invocation
+- If no `--from-*` flags specified: auto-detect clarifications in session (default behavior)
+- If uncaptured clarifications detected, show warning and ask user whether to include
+- Directive returns a "Key Design Decisions" markdown section (or nothing if no context)
+- Hold the generated section for insertion during Step 6 (Generate Task File)
+
+**Expected Outcome**: Key Design Decisions section generated (if context available), or skipped cleanly
+
 ### 3. Check for Draft File
 
 Check if draft file was provided as argument:
@@ -126,6 +170,29 @@ If draft file was provided, create clarification if needed:
 
 **Expected Outcome**: Clarification created and answered (if needed)
 
+### 5.5. Cross-Reference Design Documents
+
+Invoke the `@acp.design-reference` shared directive to discover and extract design document context.
+
+**Actions**:
+- Read and follow the directive in [`agent/commands/acp.design-reference.md`](acp.design-reference.md)
+- Pass context from this command:
+  - `topic_keywords`: Keywords from task name and milestone name
+  - `milestone_name`: Current milestone name (from Step 1)
+  - `user_description`: User's task description (from Step 4)
+  - `draft_content`: Draft file content (from Step 3, if provided)
+- The directive will:
+  1. Search `agent/design/` for relevant documents by keyword matching
+  2. Report what was found/skipped
+  3. Extract design elements across 8 categories (implementation steps, argument tables, UX specs, edge cases, format specs, integration points, lifecycle rules, decision rationale)
+  4. Flag any design gaps (suggest clarification if needed)
+  5. Return structured data: design elements, gaps, and paths
+- Hold the returned design elements for use in Step 6
+
+**If no design found**: The directive warns and returns empty. Proceed to Step 6 with available context only (user input, draft, clarifications).
+
+**Expected Outcome**: Design elements extracted and ready for task generation, or skipped cleanly with warning
+
 ### 6. Generate Task File
 
 Create task file from template:
@@ -141,19 +208,39 @@ Create task file from template:
 - Fill in metadata:
   - Task number and name
   - Milestone link
+  - **Design Reference**: If Step 5.5 found a design document, link to it: `[{Design Name}](../design/{namespace}.{design-name}.md)`. If none found, set to `None`.
   - Estimated time
   - Dependencies
   - Status: "Not Started"
 - Fill in sections:
   - Objective (from collected info)
   - Context (from collected info or draft)
-  - Steps (from draft/clarification or template structure)
-  - Verification checklist
+  - **Steps** — must include implementation-level detail:
+    - Each step should be concrete and actionable, not a vague summary
+    - Include specific sub-steps for complex operations
+    - If Step 5.5 returned design elements, integrate them:
+      - Preserve argument/parameter tables from the design — include verbatim or as detailed prose
+      - Preserve UX specifications — exact warning text, prompt formats, display output
+      - Preserve format specifications — output structure, naming conventions, file format rules
+      - Include integration points — which other commands/systems are affected and how
+      - Include lifecycle rules — status transitions, cleanup behavior, ordering constraints
+      - Include decision rationale inline where it aids implementation
+    - If the design describes N distinct operations, the task should have corresponding steps covering all N (grouping related operations into fewer steps is acceptable, but no operation may be omitted)
+  - **Verification checklist** — must cover every design requirement:
+    - One verification item per design requirement from the design document
+    - Include edge cases from the design (partial data, conflicts, empty state, missing files)
+    - Include format verification (output matches specified format)
+    - Include integration verification (affected commands updated correctly)
+    - If the design has a Testing Strategy section, map each test scenario to a verification item
+  - If Key Design Decisions section was generated in Step 2.7: Insert it into the task document
+  - If Step 5.5 returned design decisions (from the design doc's Key Design Decisions section): Carry relevant decisions into the task's Key Design Decisions section
 - Save to appropriate path (milestone subdirectory or unassigned/)
 
+> **Self-Contained Task Principle**: After generating the task, verify that an agent reading ONLY this task file could implement the feature without needing to read the design document. If any design element is missing from the task, add it before saving.
+
 **Note**: Older tasks may use flat structure (`agent/tasks/task-{N}-{name}.md`) for historical reasons. New tasks should use milestone subdirectories.
 
-**Expected Outcome**: Task file created in milestone subdirectory
+**Expected Outcome**: Task file created in milestone subdirectory with complete design coverage
 
 ### 7. Update progress.yaml
 
@@ -215,6 +302,21 @@ Next steps:
 
 **Expected Outcome**: User knows task was created successfully
 
+### 10. Prompt to Add to Key File Index
+
+After successful creation, offer to add the new file to the index (if `agent/index/` exists).
+
+**Display**:
+```
+Would you like to add this to the key file index?
+  - Yes, add to agent/index/local.main.yaml
+  - No, skip
+```
+
+If yes, prompt for weight, description, rationale, and applies values. Add entry to `agent/index/local.main.yaml`.
+
+**Note**: Skip silently if `agent/index/` does not exist.
+
 ---
 
 ## Verification

package/agent/commands/acp.update.md

@@ -7,6 +7,7 @@
 **Created**: 2026-02-16
 **Last Updated**: 2026-02-16
 **Status**: Active
+**Scripts**: None
 
 ---
 

package/agent/commands/acp.validate.md

@@ -9,6 +9,7 @@
 **Created**: 2026-02-16
 **Last Updated**: 2026-02-21
 **Status**: Active
+**Scripts**: None
 
 ---
 
@@ -173,7 +174,35 @@ Check namespace usage across all files.
 
 **Expected Outcome**: Namespace conventions validated, errors reported for violations
 
-### 9. Check Cross-References
+### 9. Validate Key File Index
+
+Check index files in `agent/index/` for schema correctness and referential integrity.
+
+**Actions**:
+- Check that `agent/index/` directory exists (warn if missing)
+- For each `*.yaml` file in `agent/index/` (skip `*.template.yaml`):
+  - Verify filename follows `{namespace}.{qualifier}.yaml` naming
+  - Parse the index entries under the top-level key
+  - For each entry, verify required fields present: `path`, `weight`, `kind`, `description`, `rationale`, `applies`
+  - Validate `weight` is a number in range 0.0-1.0
+  - Validate `kind` is one of: pattern, command, design, requirements
+  - Validate `applies` values use fully qualified command names (contain a dot, e.g. `acp.proceed`)
+  - Check that each `path` actually exists in the project
+  - Warn on missing paths (file may have been moved or deleted)
+- Check total indexed entries across all files (warn if > 20)
+- Check per-namespace entry count (warn if > 10)
+
+**Output format**:
+```
+📑 Index Validation:
+  ✓ agent/index/local.main.yaml (5 entries, all valid)
+  ⚠️ agent/index/core-sdk.main.yaml: path not found: agent/patterns/core-sdk.deleted.md
+  ✓ Total: 8 entries across 2 namespaces (within limits)
+```
+
+**Expected Outcome**: Index files validated for schema and referential integrity
+
+### 10. Check Cross-References
 
 Validate links between documents.
 
@@ -187,7 +216,7 @@ Validate links between documents.
 
 **Expected Outcome**: All links are valid
 
-### 10. Generate Validation Report
+### 11. Generate Validation Report
 
 Summarize validation results.
 
@@ -214,6 +243,7 @@ Summarize validation results.
 - [ ] All command documents are valid
 - [ ] Namespace conventions validated
 - [ ] Reserved names checked
+- [ ] Key file index validated (schema, paths, limits)
 - [ ] No broken internal links
 - [ ] Validation report generated
 

package/agent/commands/acp.version-check-for-updates.md

@@ -7,6 +7,7 @@
 **Created**: 2026-02-16
 **Last Updated**: 2026-02-16
 **Status**: Active
+**Scripts**: acp.version-check-for-updates.sh
 
 ---
 

package/agent/commands/acp.version-check.md

@@ -7,6 +7,7 @@
 **Created**: 2026-02-16
 **Last Updated**: 2026-02-16
 **Status**: Active
+**Scripts**: acp.version-check.sh
 
 ---
 

package/agent/commands/acp.version-update.md

@@ -7,6 +7,7 @@
 **Created**: 2026-02-16
 **Last Updated**: 2026-02-16
 **Status**: Active
+**Scripts**: acp.version-update.sh, acp.common.sh
 
 ---
 

package/agent/commands/command.template.md

@@ -9,6 +9,11 @@
 **Created**: YYYY-MM-DD
 **Last Updated**: YYYY-MM-DD
 **Status**: [Draft | Active | Deprecated]
+**Scripts**: {namespace}.{command-name}.sh, acp.common.sh, acp.yaml-parser.sh
+
+---
+
+**Note**: The `**Scripts**:` field is REQUIRED and must list ALL script dependencies (direct + shared utilities). This must match the `scripts` array in package.yaml exactly. If the command has no script dependencies, use `**Scripts**: None`.
 
 ---
 
@@ -290,6 +295,24 @@ Example output message or status report
 
 ---
 
+## Key Design Decisions (Optional)
+
+<!-- This section is populated by @acp.clarification-capture when
+     create commands are invoked with --from-clar, --from-chat, or
+     --from-context. It can also be manually authored.
+     Omit this section entirely if no decisions to capture.
+
+     Group decisions by agent-inferred category using tables:
+
+### {Category}
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| {decision} | {choice} | {rationale} |
+-->
+
+---
+
 ## Notes
 
 [Any additional context, warnings, or considerations:]

package/agent/commands/git.commit.md

@@ -9,6 +9,7 @@
 **Created**: 2026-02-16
 **Last Updated**: 2026-02-16
 **Status**: Active
+**Scripts**: None
 
 ---
 

package/agent/commands/git.init.md

@@ -7,6 +7,7 @@
 **Created**: 2026-02-16
 **Last Updated**: 2026-02-16
 **Status**: Active
+**Scripts**: None
 
 ---