@prmichaelsen/remember-mcp 4.0.2 → 4.1.0

package/agent/commands/acp.validate.md

@@ -39,6 +39,22 @@ Unlike `@acp.sync` which compares docs to code, `@acp.validate` checks the inter
 
 ## Steps
 
+### 0. Display Command Header
+
+```
+⚡ @acp.validate
+  Validate all ACP documents for structure, consistency, correctness, and namespace conventions
+
+  Related:
+    @acp.package-validate  Package-specific validation
+    @acp.sync              Sync documentation with code
+    @acp.update            Update progress tracking
+    @acp.report            Generate report with validation results
+    @acp.init              Can include validation during init
+```
+
+This step is informational only — do not wait for user input.
+
 ### 1. Validate Directory Structure
 
 Check that all required directories and files exist.
@@ -239,10 +255,17 @@ Check index files in `agent/index/` for schema correctness and referential integ
   - 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, artifact
+  - Validate `kind` is one of: `pattern`, `command`, `design`, `note`, `directive`
+    - `requirements` is accepted as a deprecated alias for `design` (warn: "use `design` instead")
+    - `artifact` is also accepted for backward compatibility
+  - Validate path/kind consistency:
+    - If `path` is `null`: `kind` must be `note` or `directive`
+    - If `path` is a string: `kind` must be `pattern`, `command`, or `design`
+    - For `path: null` entries, `description` must be non-empty (it IS the content)
   - Validate `applies` values use fully qualified command names (contain a dot, e.g. `acp.proceed`)
-  - Check that each `path` actually exists in the project
+  - For entries where `path` is a string: check that the path actually exists in the project
   - Warn on missing paths (file may have been moved or deleted)
+  - Skip path existence check for `path: null` entries
 - Check total indexed entries across all files (warn if > 20)
 - Check per-namespace entry count (warn if > 10)
 

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

@@ -38,6 +38,19 @@ Unlike `@acp-version-update` which applies updates immediately, this command onl
 
 ## Steps
 
+### 0. Display Command Header
+
+Display the following informational header, then continue immediately:
+
+```
+⚡ @acp.version-check-for-updates
+  Check if newer version of ACP is available without applying updates
+
+  Related:
+    @acp.version-check    Show current version only
+    @acp.version-update   Apply updates if available
+```
+
 ### 1. Run Update Check Script
 
 Execute the check-for-updates script.

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

@@ -36,6 +36,19 @@ Unlike `@acp-version-check-for-updates` which checks for newer versions, this co
 
 ## Steps
 
+### 0. Display Command Header
+
+Display the following informational header, then continue immediately:
+
+```
+⚡ @acp.version-check
+  Display current ACP version and compatibility information
+
+  Related:
+    @acp.version-check-for-updates   Check if newer version available
+    @acp.version-update              Update to latest version
+```
+
 ### 1. Run Version Script
 
 Execute the version check script.

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

@@ -39,6 +39,20 @@ Unlike `@acp-version-check-for-updates` which only checks, this command actually
 
 ## Steps
 
+### 0. Display Command Header
+
+Display the following informational header, then continue immediately:
+
+```
+⚡ @acp.version-update
+  Update ACP files (AGENT.md, templates, scripts) to the latest version
+
+  Related:
+    @acp.version-check-for-updates   Check before updating
+    @acp.version-check               Verify version after updating
+    @acp.init                        Reload context after updating
+```
+
 ### 1. Verify Prerequisites
 
 Check that update can proceed safely.

package/agent/commands/command.template.md

@@ -96,6 +96,39 @@ The agent infers intent from context. "Show me global packages" maps to `--globa
 
 [Detailed, sequential steps the agent should follow:]
 
+### 0. Display Command Header (Default)
+
+When the command is invoked, immediately display a brief informational header before proceeding with execution. This step does NOT block execution — the agent prints it and continues into Step 1 without pausing.
+
+**Actions**:
+- Print the command's **Purpose** (from the metadata above)
+- Print a one-line summary of what this invocation will do
+- Print a **Usage** block listing available arguments and flags
+- Print a **Related Commands** block listing related commands with one-line descriptions
+
+**Display format**:
+```
+⚡ @{namespace}.{command-name}
+  {Purpose line from metadata}
+
+  Usage:
+    @{namespace}.{command-name}                    {default behavior}
+    @{namespace}.{command-name} --flag             {what --flag does}
+    @{namespace}.{command-name} --option <value>   {what --option does}
+
+  Related:
+    @{namespace}.{related-1}   {one-line description}
+    @{namespace}.{related-2}   {one-line description}
+```
+
+**Notes**:
+- If the command has no arguments, omit the Usage block
+- If the command has no related commands, omit the Related block
+- Keep descriptions short (under 60 characters)
+- This step is informational only — do not wait for user input
+
+**Expected Outcome**: User sees at a glance what the command does, how to customize it, and what else is available
+
 ### 1. [Step Name]
 
 [Description of what to do in this step]

package/agent/commands/git.commit.md

@@ -44,6 +44,20 @@ This command intelligently detects if changes represent a version change, determ
 
 ## Steps
 
+### 0. Display Command Header
+
+Display the following informational header, then continue immediately:
+
+```
+⚡ @git.commit
+  Automate version detection, changelog updates, and git commits with proper semantic versioning
+
+  Related:
+    @acp.version-check    Check current version
+    @acp.version-update   Update ACP itself
+    @acp.status           Check project status before committing
+```
+
 ### 1. Analyze Changes for Version Impact
 
 Review the staged/unstaged changes and determine:

package/agent/commands/git.init.md

@@ -42,6 +42,19 @@ The command is smart about .gitignore - it evaluates your project to determine w
 
 ## Steps
 
+### 0. Display Command Header
+
+Display the following informational header, then continue immediately:
+
+```
+⚡ @git.init
+  Initialize a git repository with intelligent .gitignore based on project type
+
+  Related:
+    @git.commit   Make your first commit after init
+    @acp.init     Initialize ACP structure after git init
+```
+
 ### 1. Evaluate Project Type
 
 Analyze the project structure to determine the technology stack and project type.

package/agent/manifest.yaml

@@ -4,9 +4,9 @@
 packages:
   acp-core:
     source: https://github.com/prmichaelsen/agent-context-protocol.git
-    package_version: 5.28.9
+    package_version: 5.30.0
     installed_at: 2026-03-14T06:27:55Z
-    updated_at: 2026-03-20T10:17:51Z
+    updated_at: 2026-03-23T00:09:35Z
     files:
       commands:
         - name: acp.clarification-address.md
@@ -61,4 +61,4 @@ packages:
         - name: requirements.template.md
 
 manifest_version: 1.0.0
-last_updated: 2026-03-20T10:17:51Z
+last_updated: 2026-03-23T00:09:35Z

package/agent/milestones/milestone-24-mcp-elicitation-confirmation.md

@@ -0,0 +1,99 @@
+# Milestone 24: MCP Elicitation Confirmation Flow
+
+**Goal**: Replace the two-phase token+confirm/deny confirmation pattern with MCP elicitation for protected operations, while keeping confirm/deny as fallback for non-elicitation clients.
+**Duration**: 1 week
+**Dependencies**: M23 (Trust Level Protection)
+**Status**: Not Started
+
+---
+
+## Overview
+
+Protected operations (publish, retract, revise, delete, set-trust-level) currently use a two-phase token pattern: the tool returns a `{ token }`, then the agent calls `remember_confirm` or `remember_deny`. The problem is that an autonomous agent can call confirm immediately in the same tool loop — auto-confirming without any user involvement.
+
+MCP elicitation (`server.elicitInput()`) is the spec-native solution. It allows the server to pause a tool call and request user confirmation directly through the client, bypassing the agent entirely. The MCP SDK v1.27.1 (installed) fully supports this.
+
+For clients that don't support elicitation, the existing token+confirm/deny flow is preserved as a fallback.
+
+---
+
+## Deliverables
+
+### 1. Elicitation Helper Utility
+- `src/utils/elicitation.ts` — shared helper that checks client capabilities and issues confirmation prompts or returns fallback
+
+### 2. Updated Protected Tool Handlers
+- All 5 protected tools (publish, retract, revise, delete-memory, request-set-trust-level) use elicitation when available
+- Fallback to token flow when elicitation not supported
+
+### 3. Server Wiring
+- `server.ts` and `server-factory.ts` pass `Server` instance to protected tool handlers
+
+---
+
+## Success Criteria
+
+- [ ] `npm run build` completes without errors
+- [ ] `npm run typecheck` passes
+- [ ] `npm test` — all existing tests pass
+- [ ] Protected tools use elicitation when client supports it
+- [ ] Protected tools fall back to token+confirm/deny when client doesn't support elicitation
+- [ ] `remember_confirm` and `remember_deny` tools still work for fallback clients
+
+---
+
+## Key Files to Create
+
+```
+src/
+└── utils/
+    └── elicitation.ts
+```
+
+## Key Files to Modify
+
+```
+src/
+├── tools/
+│   ├── publish.ts
+│   ├── retract.ts
+│   ├── revise.ts
+│   ├── delete-memory.ts
+│   └── request-set-trust-level.ts
+├── server.ts
+└── server-factory.ts
+```
+
+---
+
+## Tasks
+
+1. [Task 530: Create elicitation helper utility](../tasks/milestone-24-mcp-elicitation-confirmation/task-530-create-elicitation-helper.md) - Shared helper for elicitation with fallback detection
+2. [Task 531: Update protected tool handler signatures](../tasks/milestone-24-mcp-elicitation-confirmation/task-531-update-handler-signatures.md) - Add optional `server` parameter to protected tool handlers
+3. [Task 532: Implement elicitation in protected tools](../tasks/milestone-24-mcp-elicitation-confirmation/task-532-implement-elicitation-in-tools.md) - Wire elicitation logic into publish, retract, revise, delete, set-trust-level
+4. [Task 533: Wire server instance through entry points](../tasks/milestone-24-mcp-elicitation-confirmation/task-533-wire-server-instance.md) - Pass server to protected tool handlers in server.ts and server-factory.ts
+5. [Task 534: Verification and cleanup](../tasks/milestone-24-mcp-elicitation-confirmation/task-534-verification-cleanup.md) - Build, typecheck, test, update tool descriptions
+
+---
+
+## Testing Requirements
+
+- [ ] Existing unit tests pass without modification
+- [ ] Build succeeds
+- [ ] Typecheck passes
+
+---
+
+## Risks and Mitigation
+
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|---------------------|
+| Client doesn't support elicitation | Medium | High | Fallback to existing token+confirm/deny flow |
+| Elicitation throws on unsupported clients | High | Low | Capability check before calling elicitInput |
+| Confirm handler logic duplication | Medium | Medium | Reuse existing confirm handler code path internally |
+
+---
+
+**Next Milestone**: TBD
+**Blockers**: None
+**Notes**: Start with a spike on `remember_publish` to verify elicitation works end-to-end before migrating all protected operations.