From b53aa7cb2367e93b9469b179e0d2c8aba239e1f4 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Fri, 12 Dec 2025 00:13:34 -0500 Subject: [PATCH] Add path safeguards to prevent structural damage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create docs/CANONICAL-PATHS.md as single source of truth - Add mandatory path verification rules to CLAUDE.md - Remove dead reference to CORRECT-ARCHITECTURE.md - Add recovery protocol for path issues 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- CHANGELOG.md | 8 +++ CLAUDE.md | 48 +++++++++++++- docs/CANONICAL-PATHS.md | 139 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 193 insertions(+), 2 deletions(-) create mode 100644 docs/CANONICAL-PATHS.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 450e3e0..a959dc4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] ### Added +- `docs/CANONICAL-PATHS.md` - Single source of truth for all file paths +- Path verification rules in CLAUDE.md (mandatory pre-flight check) +- Recovery protocol for path issues - Installation script (`scripts/setup.sh`) for new users - Post-update script (`scripts/post-update.sh`) for updates - Update documentation (`docs/UPDATING.md`) @@ -19,9 +22,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - `docs/workflows/` for workflow documentation ### Changed +- Replaced `docs/CORRECT-ARCHITECTURE.md` reference with `docs/CANONICAL-PATHS.md` +- Added mandatory path verification section to CLAUDE.md - Reorganized documentation into `docs/references/`, `docs/architecture/`, `docs/workflows/` - Updated CLAUDE.md with file creation governance +### Fixed +- Removed dead reference to non-existent `docs/CORRECT-ARCHITECTURE.md` + ### Removed - Organization/workspace GID variable (no longer needed) - Deprecated `cmdb-assistant/` plugin diff --git a/CLAUDE.md b/CLAUDE.md index 686e580..9537692 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -65,6 +65,50 @@ Before creating any file, verify: **Violation of these rules creates technical debt and project chaos.** +## Path Verification (MANDATORY) + +### Before Generating Any Prompt or Creating Any File + +**This is non-negotiable. Failure to follow causes structural damage.** + +1. **READ `docs/CANONICAL-PATHS.md` FIRST** + - This file is the single source of truth + - Never infer paths from memory or context + - Never assume paths based on conversation history + +2. **List All Paths** + - Before generating a prompt, list every file path it will create/modify + - Show the list to the user + +3. **Verify Each Path** + - Check each path against `docs/CANONICAL-PATHS.md` + - If a path is not in that file, STOP and ask + +4. **Show Verification** + - Present a verification table to user: + ``` + | Path | Matches CANONICAL-PATHS.md? | + |------|----------------------------| + | plugins/projman/... | ✅ Yes | + ``` + +5. **Get Confirmation** + - User must confirm paths are correct before proceeding + +### Relative Path Rules + +- Plugin to MCP server: `${CLAUDE_PLUGIN_ROOT}/../../mcp-servers/{server}` +- Marketplace to plugin: `./../../../plugins/{plugin-name}` +- **ALWAYS calculate from CANONICAL-PATHS.md, never from memory** + +### Recovery Protocol + +If you suspect paths are wrong: +1. Read `docs/CANONICAL-PATHS.md` +2. Compare actual structure against documented structure +3. Report discrepancies +4. Generate corrective prompt if needed + ## Core Architecture ### Three-Agent Model @@ -212,7 +256,7 @@ See [docs/reference-material/projman-implementation-plan.md](docs/reference-mate ### Repository Structure (DEFINITIVE) -⚠️ **See `docs/CORRECT-ARCHITECTURE.md` for the authoritative structure reference** +⚠️ **See `docs/CANONICAL-PATHS.md` for the authoritative path reference - THIS IS THE SINGLE SOURCE OF TRUTH** ``` bandit/support-claude-mktplace/ @@ -435,7 +479,7 @@ Test in real CuisineFlow repository with actual Gitea instance before distributi This repository contains comprehensive planning documentation: -- **`docs/CORRECT-ARCHITECTURE.md`** - ⚠️ DEFINITIVE repository structure reference +- **`docs/CANONICAL-PATHS.md`** - ⚠️ SINGLE SOURCE OF TRUTH for all paths (MANDATORY reading before any file operations) - **`docs/DOCUMENT-INDEX.md`** - Complete guide to all planning documents - **`docs/projman-implementation-plan-updated.md`** - Full 12-phase implementation plan - **`docs/projman-python-quickstart.md`** - Python-specific implementation guide diff --git a/docs/CANONICAL-PATHS.md b/docs/CANONICAL-PATHS.md new file mode 100644 index 0000000..5695588 --- /dev/null +++ b/docs/CANONICAL-PATHS.md @@ -0,0 +1,139 @@ +# Canonical Paths - SINGLE SOURCE OF TRUTH + +**This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.** + +Last Updated: 2025-12-12 + +--- + +## Repository Root Structure + +``` +support-claude-mktplace/ +├── .claude/ # Claude Code skills +├── .claude-plugin/ # Root marketplace manifest (if any) +├── .claude-plugins/ # Local marketplace definitions +│ └── projman-marketplace/ +│ └── .claude-plugin/ +│ └── marketplace.json +├── .scratch/ # Transient work (auto-cleaned) +├── docs/ # All documentation +│ ├── architecture/ # Draw.io diagrams and specs +│ ├── references/ # Reference specifications +│ └── workflows/ # Workflow documentation +├── hooks/ # Shared hooks (if any) +├── mcp-servers/ # Shared MCP servers (AT ROOT) +│ ├── gitea/ +│ ├── wikijs/ +│ └── netbox/ +├── plugins/ # ALL plugins (INSIDE plugins/) +│ ├── projman/ +│ ├── projman-pmo/ +│ ├── project-hygiene/ +│ └── cmdb-assistant/ +├── scripts/ # Setup and maintenance scripts +├── CLAUDE.md +├── README.md +├── LICENSE +├── CHANGELOG.md +└── .gitignore +``` + +--- + +## Path Patterns (MANDATORY) + +### Plugin Paths + +| Context | Pattern | Example | +|---------|---------|---------| +| Plugin location | `plugins/{plugin-name}/` | `plugins/projman/` | +| Plugin manifest | `plugins/{plugin-name}/.claude-plugin/plugin.json` | `plugins/projman/.claude-plugin/plugin.json` | +| Plugin commands | `plugins/{plugin-name}/commands/` | `plugins/projman/commands/` | +| Plugin agents | `plugins/{plugin-name}/agents/` | `plugins/projman/agents/` | +| Plugin .mcp.json | `plugins/{plugin-name}/.mcp.json` | `plugins/projman/.mcp.json` | + +### MCP Server Paths + +| Context | Pattern | Example | +|---------|---------|---------| +| MCP server location | `mcp-servers/{server-name}/` | `mcp-servers/gitea/` | +| MCP server code | `mcp-servers/{server-name}/mcp_server/` | `mcp-servers/gitea/mcp_server/` | +| MCP venv | `mcp-servers/{server-name}/.venv/` | `mcp-servers/gitea/.venv/` | + +### Relative Path Patterns (CRITICAL) + +| From | To | Pattern | +|------|----|---------| +| Plugin .mcp.json | MCP server | `${CLAUDE_PLUGIN_ROOT}/../../mcp-servers/{server}` | +| marketplace.json | Plugin | `./../../../plugins/{plugin-name}` | + +### Documentation Paths + +| Type | Location | +|------|----------| +| Reference specs | `docs/references/` | +| Architecture diagrams | `docs/architecture/` | +| Workflow docs | `docs/workflows/` | +| This file | `docs/CANONICAL-PATHS.md` | + +--- + +## Validation Rules + +### Before Creating Any File + +1. Check this file for the correct path pattern +2. Verify the parent directory exists in the structure above +3. If path not listed here, **STOP AND ASK** + +### Before Generating Any Prompt + +1. List all file paths the prompt will create/modify +2. Verify each path against patterns in this file +3. Show verification to user before proceeding + +### Relative Path Calculation + +From `plugins/projman/.mcp.json` to `mcp-servers/gitea/`: +``` +plugins/projman/.mcp.json + ↑ go up to plugins/projman/ (../) + ↑ go up to plugins/ (../) + ↑ go up to root/ (../) + → go down to mcp-servers/gitea/ (mcp-servers/gitea/) + +Result: ../../mcp-servers/gitea/ +With variable: ${CLAUDE_PLUGIN_ROOT}/../../mcp-servers/gitea/ +``` + +From `.claude-plugins/projman-marketplace/.claude-plugin/marketplace.json` to `plugins/projman/`: +``` +.claude-plugins/projman-marketplace/.claude-plugin/marketplace.json + ↑ go up to .claude-plugin/ (../) + ↑ go up to projman-marketplace/ (../) + ↑ go up to .claude-plugins/ (../) + ↑ go up to root/ (../) + → go down to plugins/projman/ (plugins/projman/) + +Result: ./../../../plugins/projman +``` + +--- + +## Anti-Patterns (NEVER DO THIS) + +| Wrong | Why | Correct | +|-------|-----|---------| +| `projman/` at root | Plugins go in `plugins/` | `plugins/projman/` | +| `../mcp-servers/` from plugin | Missing one level | `../../mcp-servers/` | +| `./projman` in marketplace | Wrong depth | `./../../../plugins/projman` | +| Creating `docs/CORRECT-ARCHITECTURE.md` | This file replaces it | Use `docs/CANONICAL-PATHS.md` | + +--- + +## Change Log + +| Date | Change | By | +|------|--------|-----| +| 2025-12-12 | Initial creation | Claude Code |