code-graph-llm 2.0.0 → 2.1.0

package/AGENT_RULES.md

@@ -1,16 +1,12 @@
 # AGENT OPERATIONAL PROTOCOL (STRICT)
 > This protocol is MANDATORY for all LLM agents. Failure to update memory is a failure of the task.
-
 ## 🧠 THE REFLECTION CYCLE
-Every execution MUST follow this cycle:
-1. **PRE-TASK:** Read `PROJECT_REFLECTIONS.md` to identify existing pitfalls (OS, Deps, Logic).
-2. **EXECUTION:** Monitor for any "Learned Moments":
-   - **Task Failures:** Identify the root cause (e.g., "Win32 shell restrictions").
-   - **Sub-optimal Logic:** Identify better abstractions (e.g., "Prefer fsp over fs").
-   - **Environment Issues:** Identify missing dependencies or OS incompatibilities.
-3. **POST-TASK:** Immediately run `code-graph reflect <CAT> <LESSON>` for any discovery. 
-   - **DO NOT** wait for the user to ask. 
-   - **DO NOT** commit until `llm-code-graph.md` is regenerated.
+Every execution SHOULD follow this cycle:
+1. **PRE-TASK:** Read \`PROJECT_REFLECTIONS.md\` to identify existing pitfalls.
+2. **EXECUTION:** Monitor for "Learned Moments" (failures, unexpected behaviors, or non-obvious fixes).
+3. **POST-TASK:** If a significant lesson was learned, run \`code-graph reflect <CAT> <LESSON>\`. 
+   - **NOTE:** Routine, expected changes do not require reflections. Focus on high-signal context.
+
 
 ## ⚠️ CRITICAL MANDATES
 - **OS [win32]:** Always prefix npm commands with `cmd /c`. 

package/README.md

@@ -27,6 +27,9 @@ npm install --save-dev code-graph-llm
 
 ### 2. Core Commands
 ```bash
+# Initialize Agent Rules and Reflection files (Scaffolding)
+code-graph init
+
 # Generate the llm-code-graph.md map
 code-graph generate
 

package/index.js

@@ -273,6 +273,46 @@ class ReflectionManager {
   }
 }
 
+/**
+ * Scaffolds the initial agent-agnostic rule and reflection files.
+ */
+class ProjectInitializer {
+  static async init(cwd) {
+    const rulesPath = path.join(cwd, CONFIG.RULES_FILE);
+    const reflectPath = path.join(cwd, CONFIG.REFLECTIONS_FILE);
+
+    const rulesContent = `# AGENT OPERATIONAL PROTOCOL (STRICT)
+> This protocol is MANDATORY for all LLM agents. Failure to update memory is a failure of the task.
+
+## 🧠 THE REFLECTION CYCLE
+1. **PRE-TASK:** Read \`${CONFIG.REFLECTIONS_FILE}\` to identify existing pitfalls.
+2. **EXECUTION:** Monitor for "Learned Moments" (failures, corrections, or discoveries).
+3. **POST-TASK:** Immediately run \`code-graph reflect <CAT> <LESSON>\` for any discovery. 
+
+## 📝 REFLECTION CATEGORIES
+- \`LOGIC\`: Code bugs or complex regex pitfalls.
+- \`ENV\`: OS compatibility or shell behaviors.
+- \`DEP\`: Library bugs or version deprecations.
+- \`STYLE\`: Project-specific architectural rules.
+`;
+
+    const reflectContent = `# PROJECT_REFLECTIONS & LESSONS LEARNED\n> LLM AGENT MEMORY: READ BEFORE STARTING TASKS. UPDATE ON FAILURES.\n`;
+
+    try {
+      if (!fs.existsSync(rulesPath)) {
+        await fsp.writeFile(rulesPath, rulesContent);
+        console.log(`[Code-Graph] Initialized ${CONFIG.RULES_FILE}`);
+      }
+      if (!fs.existsSync(reflectPath)) {
+        await fsp.writeFile(reflectPath, reflectContent);
+        console.log(`[Code-Graph] Initialized ${CONFIG.REFLECTIONS_FILE}`);
+      }
+    } catch (err) {
+      console.error(`[Code-Graph] Initialization failed: ${err.message}`);
+    }
+  }
+}
+
 // --- CLI Entry Point ---
 
 async function main() {
@@ -284,17 +324,21 @@ async function main() {
       case 'generate':
         await new ProjectMapper(cwd).generate();
         break;
+      case 'init':
+        await ProjectInitializer.init(cwd);
+        break;
       case 'reflect':
         await ReflectionManager.add(args[0], args.slice(1).join(' '));
         break;
       case 'install-hook':
+        await ProjectInitializer.init(cwd);
         await installGitHook(cwd);
         break;
       case 'watch':
         startWatcher(cwd);
         break;
       default:
-        console.log('Usage: code-graph [generate|reflect|install-hook|watch]');
+        console.log('Usage: code-graph [generate|init|reflect|install-hook|watch]');
     }
   } catch (err) {
     console.error(`[Code-Graph] Critical Error: ${err.message}`);
@@ -306,9 +350,30 @@ async function installGitHook(cwd) {
   const hookPath = path.join(cwd, '.git', 'hooks', 'pre-commit');
   if (!fs.existsSync(path.dirname(hookPath))) return console.error('[Code-Graph] No .git directory found.');
 
-  const content = `#!/bin/sh\n# Code-Graph Sync\necho "[Code-Graph] Validating..."\nnode "${__filename}" generate\ngit add "${CONFIG.MAP_FILE}"\nif [ ! -z "$(git diff --cached --shortstat)" ]; then\n  echo "[Code-Graph] Reminder: Run 'code-graph reflect' if this fix resolves a non-obvious bug."\nfi`;
+  const content = `#!/bin/sh
+# Code-Graph Advisory: Map Sync & Reflection Reminder
+echo "[Code-Graph] Validating commit..."
+
+# 1. Regenerate Map
+node "${__filename}" generate
+git add "${CONFIG.MAP_FILE}"
+
+# 2. Reflection Advisory
+# Notify if code changed but reflections didn't (Soft Nudge)
+CODE_CHANGES=$(git diff --cached --name-only | grep -E "\\.(${CONFIG.SUPPORTED_EXTENSIONS.map(e => e.slice(1)).join('|')})$")
+REFLECT_CHANGES=$(git diff --cached --name-only | grep "${CONFIG.REFLECTIONS_FILE}")
+
+if [ ! -z "$CODE_CHANGES" ] && [ -z "$REFLECT_CHANGES" ]; then
+  echo "--------------------------------------------------------"
+  echo "ℹ️  [Code-Graph] ADVISORY: Reflection Check"
+  echo "Significant code changes detected without a reflection."
+  echo "If you learned something new or fixed a non-obvious bug,"
+  echo "run 'code-graph reflect LOGIC <lesson>' before committing."
+  echo "--------------------------------------------------------"
+fi
+`;
   await fsp.writeFile(hookPath, content, { mode: 0o755 });
-  console.log('[Code-Graph] Pre-commit hook installed.');
+  console.log('[Code-Graph] Pre-commit Advisory installed (Soft Enforcement).');
 }
 
 function startWatcher(cwd) {

package/llm-code-graph.md

@@ -4,8 +4,8 @@
 > Legend: [CORE] Entry Point, (↑N) Outgoing Deps, (↓M) Incoming Dependents
 > Notation: syms: [Name [Signature/Context]], desc: File Summary, [TAG: Context]
 
-- [CORE] index.js (↑6 ↓1) [TODO: |FIXME|BUG|DEPRECATED):?\s*(.*)/i,, bug: ."\nfi`;] | desc: !usrbinenv node
-  - syms: [CONFIG [=], CodeParser [--- Core Services --- Handles extraction of symbols, edges, and metadata from source code.], ProjectMapper [Manages the project mapping and file generation.], ReflectionManager [Manages project reflections and lessons learned.], SUPPORTED_EXTENSIONS [: [], add [(context ? `${display} [${context}]` : display)], extract [(content)], installGitHook [(cwd)], main [|app|server|cli)\./i.test(path.basename(relPath))], processFile [(fullPath, relPath)], startWatcher [(cwd)], walk [(dir, ig)]]
+- [CORE] index.js (↑6 ↓1) [TODO: |FIXME|BUG|DEPRECATED):?\s*(.*)/i,, bug: s or complex regex pitfalls., bug: s or version deprecations., bug: ,"] | desc: !usrbinenv node
+  - syms: [CONFIG [=], CodeParser [--- Core Services --- Handles extraction of symbols, edges, and metadata from source code.], ProjectInitializer [Scaffolds the initial agent-agnostic rule and reflection files.], ProjectMapper [Manages the project mapping and file generation.], ReflectionManager [Manages project reflections and lessons learned.], SUPPORTED_EXTENSIONS [: [], add [(context ? `${display} [${context}]` : display)], extract [(content)], init [(cwd)], installGitHook [(cwd)], main [|app|server|cli)\./i.test(path.basename(relPath))], processFile [(fullPath, relPath)], walk [(dir, ig)]]
 - [CORE] test/index.test.js (↑10 ↓0) | desc: 
   - syms: []
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-graph-llm",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Compact, language-agnostic codebase mapper for LLM token efficiency.",
   "main": "index.js",
   "bin": {