claude-prism 1.6.0-beta.1 → 1.6.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-prism",
-  "version": "1.6.0-beta.1",
+  "version": "1.6.0",
   "description": "AI agent harness implementing the EUDEC methodology",
   "author": { "name": "lazysaturday91" },
   "repository": "https://github.com/lazysaturday91/claude-prism",

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0] — 2026-03-05
+
+### Added
+- **Session Bootstrap** — `<!-- PRISM:BOOT -->` block auto-injected into CLAUDE.md; instructs agents to read `docs/PROJECT-MEMORY.md`, `docs/HANDOFF.md`, active plans, and `.prism/registry.json` on session start
+- **Plan Frontmatter** — plans support YAML frontmatter (`status`, `created`, `depends_on`); `/plan list` shows status icons (📋 active, ✅ completed, 📦 archived, 🚫 blocked)
+- **Plan Check** — `/plan check` subcommand detects file overlaps across active plans (cross-plan conflict detection)
+- **Docs Scaffolding** — `prism init --docs` creates `docs/` structure with `PROJECT-MEMORY.md`, `HANDOFF.md` templates and `.prism/registry.json` (auto-scans existing docs)
+- **Project Registry** — `.prism/registry.json` catalogs SSOT documents, session files, and reference/archive paths
+- **Lightweight Recording** — lightweight tasks now record a 1-line summary to `docs/PROJECT-MEMORY.md`
+- **HANDOFF Auto-triggers** — rules.md documents PreCompact/SessionEnd hook auto-generation of HANDOFF.md
+
+### Changed
+- `getActivePlanInfo()` now filters by frontmatter `status: active` (backward-compatible: no frontmatter = active)
+- `dryRun()` shows docs scaffolding actions when `--docs` is used
+- `stats.md` plan list shows frontmatter status icons
+- `rules-lean.md` Session Handoff section updated with auto-generation info
+
+### New exports
+- `parseFrontmatter(content)` — parse YAML-like frontmatter from markdown
+- `getAllPlans(projectRoot)` — list all plans with frontmatter + progress info merged
+- `detectPlanConflicts(projectRoot)` — find file overlaps across active plans
+
 ## [1.6.0-beta.1] — 2026-03-04
 
 ### Added

package/README.md

@@ -90,6 +90,12 @@ Injected into `CLAUDE.md`, EUDEC is a behavioral framework that corrects how AI
 - **Streamlined verification**: 3-level fallback ladder (Tests → Build → Diff)
 - **Adaptive checkpoints**: no pause for small tasks, summary for medium, full for large
 
+**New in v1.6.0:**
+- **Session Bootstrap** — agents auto-read `PROJECT-MEMORY.md`, `HANDOFF.md`, active plans, and registry on session start
+- **Plan Lifecycle** — frontmatter (`status`, `created`, `depends_on`), `/plan check` for cross-plan file conflict detection
+- **Docs Scaffolding** — `prism init --docs` creates `docs/` with templates + `.prism/registry.json`
+- **Lightweight Recording** — even small tasks append a 1-line summary to `docs/PROJECT-MEMORY.md`
+
 **New in v1.4.0:**
 - **Native Claude Code plugin** — `claude plugin install claude-prism` for zero-config setup
 - **4 new hook events** — PreCompact (auto-HANDOFF), SessionEnd (session protection), SubagentStart (scope injection), TaskCompleted (plan auto-update)
@@ -187,6 +193,7 @@ Plugin mode auto-registers hooks and skills. Run `prism init` additionally if yo
 
 ```bash
 npx claude-prism init              # Install with hooks (prompts for HUD)
+npx claude-prism init --docs       # Install + docs scaffolding (PROJECT-MEMORY, HANDOFF, registry)
 npx claude-prism init --hud        # Install + auto-enable HUD
 npx claude-prism init --no-hooks   # Methodology only, no hooks
 npx claude-prism init --global     # Global skill (all projects)
@@ -271,7 +278,7 @@ prism update
 ## CLI Commands
 
 ```bash
-prism init [--no-hooks] [--global] [--dry-run]   # Install
+prism init [--no-hooks] [--docs] [--global] [--dry-run]  # Install
 prism init --hud                                   # Install + auto-enable HUD
 prism check [--ci]                                 # Verify installation
 prism doctor                                       # Diagnose issues

package/bin/cli.mjs

@@ -44,9 +44,11 @@ switch (command) {
 
     const hooks = !hasFlag('no-hooks');
 
+    const docs = hasFlag('docs');
+
     if (hasFlag('dry-run')) {
       const { dryRun } = await import('../lib/installer.mjs');
-      const result = dryRun(cwd, { hooks });
+      const result = dryRun(cwd, { hooks, docs });
       console.log('🌈 claude-prism init --dry-run\n');
       console.log('  Files that would be created/updated:\n');
       for (const action of result.actions) {
@@ -58,7 +60,7 @@ switch (command) {
     }
 
     console.log('🌈 claude-prism init\n');
-    await init(cwd, { hooks });
+    await init(cwd, { hooks, docs });
 
     console.log('✅ EUDEC methodology → CLAUDE.md');
     console.log('✅ Commands → /prism, /checkpoint, /plan');
@@ -67,6 +69,10 @@ switch (command) {
     } else {
       console.log('⏭️  Hooks skipped (--no-hooks)');
     }
+    if (docs) {
+      console.log('✅ Docs scaffolding → docs/PROJECT-MEMORY.md, docs/HANDOFF.md');
+      console.log('✅ Registry → .prism/registry.json');
+    }
 
     // HUD prompt — only ask interactively if not already installed and no flag given
     if (!hasFlag('no-hud') && process.stdin.isTTY) {
@@ -308,7 +314,7 @@ switch (command) {
     console.log(`🌈 claude-prism — EUDEC methodology framework for AI coding agents
 
 Usage:
-  prism init [--no-hooks]                Install prism in current project
+  prism init [--no-hooks] [--docs]       Install prism in current project
   prism init --global                    Install globally (~/.claude/) + OMC skill
   prism check [--ci]                     Verify installation
   prism doctor                           Diagnose issues with fix suggestions
@@ -325,6 +331,7 @@ Usage:
 
 Options:
   --no-hooks   Skip commit guard hook
+  --docs       Create docs/ scaffolding (PROJECT-MEMORY.md, HANDOFF.md, registry.json)
   --hud        Auto-enable HUD during init (no prompt)
   --no-hud     Skip HUD prompt during init
   --dry-run    Show what init would do without making changes

package/lib/handoff.mjs

@@ -70,23 +70,61 @@ export function generateHandoff(projectRoot) {
 }
 
 /**
- * Read active plan file and extract progress info
+ * Parse YAML-like frontmatter from markdown content
+ * @param {string} content - Markdown file content
+ * @returns {Object} Parsed frontmatter key-value pairs
  */
-export function getActivePlanInfo(projectRoot) {
-  const plansDir = join(projectRoot, '.prism', 'plans');
-  if (!existsSync(plansDir)) return null;
+export function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+  const fm = {};
+  for (const line of match[1].split('\n')) {
+    const [key, ...rest] = line.split(':');
+    if (key && rest.length) {
+      const val = rest.join(':').trim();
+      if (val.startsWith('[')) {
+        try { fm[key.trim()] = JSON.parse(val); } catch { fm[key.trim()] = val; }
+      } else {
+        fm[key.trim()] = val;
+      }
+    }
+  }
+  return fm;
+}
 
-  const planFiles = readdirSync(plansDir)
-    .filter(f => f.endsWith('.md'))
-    .sort()
-    .reverse();
+/**
+ * Get all plans with frontmatter and progress info
+ * @param {string} projectRoot - Project root directory
+ * @returns {Array<Object>} Array of plan objects
+ */
+export function getAllPlans(projectRoot) {
+  const plansDir = join(projectRoot, '.prism', 'plans');
+  if (!existsSync(plansDir)) return [];
+  const files = readdirSync(plansDir).filter(f => f.endsWith('.md')).sort().reverse();
+  return files.map(f => {
+    const content = readFileSync(join(plansDir, f), 'utf8');
+    const fm = parseFrontmatter(content);
+    const parsed = parsePlanContent(content, f);
+    return { file: f, content, ...fm, ...parsed };
+  });
+}
 
-  if (planFiles.length === 0) return null;
+/**
+ * Read active plan file and extract progress info
+ * Now uses frontmatter status to find active plans
+ */
+export function getActivePlanInfo(projectRoot) {
+  const plans = getAllPlans(projectRoot);
+  if (plans.length === 0) return null;
 
-  const planName = planFiles[0];
-  const content = readFileSync(join(plansDir, planName), 'utf8');
+  // Find the most recent plan with status: active (or no frontmatter = default active)
+  const activePlan = plans.find(p => (p.status || 'active') === 'active');
+  if (!activePlan) return null;
 
-  return parsePlanContent(content, planName);
+  return parsePlanContent(
+    readFileSync(join(projectRoot, '.prism', 'plans', activePlan.file), 'utf8'),
+    activePlan.file
+  );
 }
 
 /**
@@ -170,6 +208,49 @@ export function parsePlanContent(content, planName) {
   return { planName, total, done, nextBatch, nextTasks, currentBatchFiles };
 }
 
+/**
+ * Detect file overlaps across active plans
+ * @param {string} projectRoot - Project root directory
+ * @returns {Array<{file: string, plans: string[]}>} Conflicting files
+ */
+export function detectPlanConflicts(projectRoot) {
+  const plans = getAllPlans(projectRoot).filter(p => (p.status || 'active') === 'active');
+  const fileMap = new Map();
+
+  for (const plan of plans) {
+    const files = extractFilesInScope(plan.content || '');
+    for (const f of files) {
+      if (!fileMap.has(f)) fileMap.set(f, []);
+      fileMap.get(f).push(plan.file);
+    }
+  }
+
+  const conflicts = [];
+  for (const [file, planList] of fileMap) {
+    if (planList.length > 1) {
+      conflicts.push({ file, plans: planList });
+    }
+  }
+  return conflicts;
+}
+
+/**
+ * Extract file paths from "Files in Scope" section
+ * @param {string} content - Plan markdown content
+ * @returns {string[]} File paths found
+ */
+function extractFilesInScope(content) {
+  const scopeMatch = content.match(/##\s+Files\s+in\s+Scope\s*\n([\s\S]*?)(?=\n##|\n---|\s*$)/i);
+  if (!scopeMatch) return [];
+  const paths = [];
+  const backtickRegex = /`([^`]+\.[a-z]+)`/g;
+  let m;
+  while ((m = backtickRegex.exec(scopeMatch[1])) !== null) {
+    paths.push(m[1]);
+  }
+  return paths;
+}
+
 /**
  * Get git status info
  */

package/lib/installer.mjs

@@ -20,7 +20,7 @@ const TEMPLATES_DIR = join(__dirname, '..', 'templates');
  * @param {boolean} options.hooks - Install commit-guard hook
  */
 export async function init(projectDir, options = {}) {
-  const { hooks = true } = options;
+  const { hooks = true, docs = false } = options;
 
   // 1. Create directories
   const claudeDir = join(projectDir, '.claude');
@@ -108,6 +108,26 @@ export async function init(projectDir, options = {}) {
   if (!existsSync(prismGitignore)) {
     writeFileSync(prismGitignore, '.version\n');
   }
+
+  // 7. Docs scaffolding (optional)
+  if (docs) {
+    const docsDir = join(projectDir, 'docs');
+    mkdirSync(docsDir, { recursive: true });
+    mkdirSync(join(docsDir, 'reference'), { recursive: true });
+    mkdirSync(join(docsDir, 'archive'), { recursive: true });
+
+    const memoryPath = join(docsDir, 'PROJECT-MEMORY.md');
+    if (!existsSync(memoryPath)) {
+      writeFileSync(memoryPath, PROJECT_MEMORY_TEMPLATE);
+    }
+
+    const handoffPath = join(docsDir, 'HANDOFF.md');
+    if (!existsSync(handoffPath)) {
+      writeFileSync(handoffPath, HANDOFF_TEMPLATE);
+    }
+
+    createRegistry(projectDir);
+  }
 }
 
 /**
@@ -614,7 +634,7 @@ export function uninstallGlobal(options = {}) {
  * @returns {{ actions: Array<{type: string, path: string, status: string}> }}
  */
 export function dryRun(projectDir, options = {}) {
-  const { hooks = true } = options;
+  const { hooks = true, docs = false } = options;
   const claudeDir = join(projectDir, '.claude');
   const actions = [];
 
@@ -674,6 +694,19 @@ export function dryRun(projectDir, options = {}) {
     actions.push({ type: 'config', path: '.prism/config.json', status: 'create' });
   }
 
+  // Docs scaffolding
+  if (docs) {
+    const docsDir = join(projectDir, 'docs');
+    for (const sub of ['', 'reference/', 'archive/']) {
+      actions.push({ type: 'docs', path: `docs/${sub}`, status: existsSync(join(docsDir, sub)) ? 'exists' : 'create' });
+    }
+    const memoryPath = join(docsDir, 'PROJECT-MEMORY.md');
+    actions.push({ type: 'docs', path: 'docs/PROJECT-MEMORY.md', status: existsSync(memoryPath) ? 'exists' : 'create' });
+    const handoffPath = join(docsDir, 'HANDOFF.md');
+    actions.push({ type: 'docs', path: 'docs/HANDOFF.md', status: existsSync(handoffPath) ? 'exists' : 'create' });
+    actions.push({ type: 'docs', path: '.prism/registry.json', status: 'create' });
+  }
+
   return { actions };
 }
 
@@ -759,6 +792,67 @@ export function hudStatus(options = {}) {
   return { enabled, scriptExists: existsSync(scriptPath), command: cmd };
 }
 
+// ─── templates ───
+
+const PROJECT_MEMORY_TEMPLATE = `# Project Memory
+
+Cumulative knowledge that survives session transitions.
+
+## Architectural Decisions
+<!-- [date] [decision] — [rationale] -->
+
+## Conventions
+<!-- [naming, patterns, file structure rules] -->
+
+## Environment Gotchas
+<!-- [quirks, workarounds, version constraints] -->
+
+## Package Constraints
+<!-- [package@version — why pinned] -->
+`;
+
+const HANDOFF_TEMPLATE = `# Handoff
+
+## Status
+[What's done, what's remaining]
+
+## Current State
+[Branch name, last commit, any uncommitted changes]
+
+## Next Steps
+[Exact next action to take, with file paths]
+
+## Decisions Made
+[Key choices and why]
+
+## Known Issues
+[Anything broken or incomplete]
+`;
+
+function createRegistry(projectDir) {
+  const registryPath = join(projectDir, '.prism', 'registry.json');
+  const registry = {
+    ssot: [],
+    session: {
+      handoff: 'docs/HANDOFF.md',
+      memory: 'docs/PROJECT-MEMORY.md'
+    },
+    reference: [],
+    archive: 'docs/archive/'
+  };
+
+  const docsDir = join(projectDir, 'docs');
+  if (existsSync(docsDir)) {
+    const files = readdirSync(docsDir).filter(f => f.endsWith('.md'));
+    for (const f of files) {
+      if (f === 'HANDOFF.md' || f === 'PROJECT-MEMORY.md') continue;
+      registry.ssot.push({ path: `docs/${f}`, role: 'unknown' });
+    }
+  }
+
+  writeFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n');
+}
+
 // ─── internal helpers ───
 
 function injectRules(projectDir, overrideRulesPath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-prism",
-  "version": "1.6.0-beta.1",
+  "version": "1.6.0",
   "description": "AI agent harness implementing the EUDEC methodology — Essence, Understand, Decompose, Execute, Checkpoint.",
   "type": "module",
   "bin": {

package/templates/commands/claude-prism/plan.md

@@ -6,11 +6,17 @@ When this command is invoked:
 
 1. **Check** if `.prism/plans/` exists. If not, report "No plans directory found. Create one with `/claude-prism:plan create <topic>`."
 2. **Scan** `.prism/plans/` for all `.md` files
-3. **Show each plan** with:
-   - Filename and date
+3. **Parse frontmatter** for each plan (between `---` markers at file start):
+   - `status: active` → 📋
+   - `status: completed` → ✅
+   - `status: archived` → 📦
+   - `status: blocked` → 🚫
+   - No frontmatter → 📋 (default: active)
+4. **Show each plan** with:
+   - Status icon, filename and date
    - Goal (first line after `## Goal`)
    - Progress: count [x] vs [ ] tasks
-   - Status: Complete / In Progress / Not Started
+   - Frontmatter status + task-based progress
 
 ## Create New Plan
 
@@ -18,9 +24,15 @@ If user requests a new plan:
 
 1. **Determine topic** from user's description
 2. **Create file** at `.prism/plans/YYYY-MM-DD-<topic>.md`
-3. **Use EUDEC template**:
+3. **Use EUDEC template** (with frontmatter):
 
 ```
+---
+status: active
+created: YYYY-MM-DD
+depends_on: []
+---
+
 ## Goal
 One sentence: what we're building and why.
 
@@ -53,6 +65,20 @@ Tech stack, key decisions, 2-3 sentences max.
 
 4. **Announce**: "Plan file created. Use /claude-prism:prism to start execution."
 
+## Check (file overlap detection)
+
+If user requests a conflict check:
+
+1. **Read all active plans** from `.prism/plans/` (frontmatter `status: active` or no frontmatter)
+2. **Parse "Files in Scope"** section from each plan — extract backtick-wrapped file paths
+3. **Detect file overlaps** across plans
+4. **Report**:
+   - ⚠️ File overlap: `path/to/file`
+     ← plan-a.md (active)
+     ← plan-b.md (active)
+   - Recommendation: check dependency order or merge plans
+5. If no overlaps found: "✅ No file conflicts across active plans."
+
 ## View Specific Plan
 
 If user specifies a plan file:

package/templates/commands/claude-prism/stats.md

@@ -30,7 +30,7 @@ When this command is invoked:
     ✅ scope-guard    (warn: 4/8, block: 7/12)
 
   Plans:
-    📋 2026-02-15-p3-inspector.md    [3/5] 60%
-    📋 2026-02-15-p8-templates.md    [5/5] 100% ✅
-    📋 2026-02-16-p4-token.md        [0/4] 0%
+    📋 2026-02-15-p3-inspector.md    [3/5] 60%  (active)
+    ✅ 2026-02-15-p8-templates.md    [5/5] 100% (completed)
+    🚫 2026-02-16-p4-token.md        [0/4] 0%  (blocked)
 ```

package/templates/rules-lean.md

@@ -1,5 +1,17 @@
 
 <!-- PRISM:START -->
+<!-- PRISM:BOOT -->
+## Session Bootstrap (auto-generated by Prism)
+
+On session start, read in order:
+1. `docs/PROJECT-MEMORY.md` (if exists) — persistent architectural decisions and conventions
+2. `docs/HANDOFF.md` (if exists) — previous session's state and next steps
+3. `.prism/plans/` — scan for active plans (frontmatter `status: active`)
+4. `.prism/registry.json` (if exists) — project document registry
+
+After reading, verify described state matches reality (git status, file contents).
+<!-- PRISM:BOOT:END -->
+
 # Prism — EUDEC Methodology (Lean Mode)
 
 **EUDEC = Essence, Understand, Decompose, Execute, Checkpoint** — the core cycle.
@@ -14,7 +26,7 @@ For the full methodology, run `/claude-prism:prism`.
 
 | Weight | Criteria | Path |
 |--------|----------|------|
-| **Lightweight** | 1-2 files, <50 LOC, clear scope | Essence (1 line) → Execute → Verify → Done |
+| **Lightweight** | 1-2 files, <50 LOC, clear scope | Essence (1 line) → Execute → Verify → Record (1-line to `docs/PROJECT-MEMORY.md`) → Done |
 | **Standard** | 3-5 files, 50-200 LOC | Run `/claude-prism:prism` for full EUDEC guidance |
 | **Full** | 6+ files, 200+ LOC, or unclear scope | Run `/claude-prism:prism` for full EUDEC with plan file |
 
@@ -80,7 +92,9 @@ After 3 failed fixes: STOP. Discuss with user.
 
 ## Session Handoff
 
-When context is running low or switching tasks, create `docs/HANDOFF.md` with: Status, Current State, Next Steps, Decisions Made, Known Issues.
+Prism hooks auto-generate `docs/HANDOFF.md` on compaction and session end.
+`docs/PROJECT-MEMORY.md` is auto-appended on session end.
+For manual handoff: Status, Current State, Next Steps, Decisions Made, Known Issues.
 
 ## Completion Declaration
 

package/templates/rules.md

@@ -1,5 +1,17 @@
 
 <!-- PRISM:START -->
+<!-- PRISM:BOOT -->
+## Session Bootstrap (auto-generated by Prism)
+
+On session start, read in order:
+1. `docs/PROJECT-MEMORY.md` (if exists) — persistent architectural decisions and conventions
+2. `docs/HANDOFF.md` (if exists) — previous session's state and next steps
+3. `.prism/plans/` — scan for active plans (frontmatter `status: active`)
+4. `.prism/registry.json` (if exists) — project document registry
+
+After reading, verify described state matches reality (git status, file contents).
+<!-- PRISM:BOOT:END -->
+
 # Prism — EUDEC Methodology Framework
 
 **EUDEC = Essence, Understand, Decompose, Execute, Checkpoint** — the core cycle.
@@ -76,7 +88,7 @@ After extracting essence and task type, assess task weight to select the appropr
 | **Standard** | 3-5 files, 50-200 LOC | Full EUDEC, summary checkpoints |
 | **Full** | 6+ files, 200+ LOC, or unclear scope | Full EUDEC with plan file + full checkpoints |
 
-**Lightweight path** skips formal UNDERSTAND (sufficiency assessment, question rounds, alignment confirmation) and DECOMPOSE. The essence statement still grounds the work but takes one line, not a full section.
+**Lightweight path** skips formal UNDERSTAND (sufficiency assessment, question rounds, alignment confirmation) and DECOMPOSE. The essence statement still grounds the work but takes one line, not a full section. Record: append 1-line summary to `docs/PROJECT-MEMORY.md` (what was changed and why).
 
 **Bugfix fast path** (regardless of file count):
 1. Reproduce the symptom
@@ -419,6 +431,11 @@ User says "stop here" → clean exit
 - Task is multi-session by nature (multi-day refactor, large migration)
 - Switching to a different task mid-session
 
+**Auto-triggers (via Prism hooks):**
+- PreCompact hook → auto-generates `docs/HANDOFF.md`
+- SessionEnd hook → auto-generates `docs/HANDOFF.md` + appends to `docs/PROJECT-MEMORY.md`
+- `/compact` 실행 전 → HANDOFF 자동 저장 (hook으로 처리됨)
+
 ### 6-2. Handoff Document
 
 Create `docs/HANDOFF.md` with: