@chrisai/base 2.3.0

package/src/packages/carl-mcp/tools/staging.js

@@ -0,0 +1,245 @@
+/**
+ * CARL Staging — Rule proposal staging pipeline
+ * Stage, review, approve/kill rule proposals before they become CARL rules
+ */
+
+import { readFileSync, writeFileSync, existsSync, appendFileSync } from 'fs';
+import { join } from 'path';
+
+const VALID_SOURCES = ['psmm', 'decisions', 'manual'];
+
+function debugLog(...args) {
+    console.error('[CARL:staging]', new Date().toISOString(), ...args);
+}
+
+function getStagingPath(workspacePath) {
+    return join(workspacePath, '.base', 'data', 'staging.json');
+}
+
+function readStaging(workspacePath) {
+    const filepath = getStagingPath(workspacePath);
+    if (!existsSync(filepath)) {
+        return { proposals: [] };
+    }
+    try {
+        return JSON.parse(readFileSync(filepath, 'utf-8'));
+    } catch (error) {
+        debugLog('Error reading staging.json:', error.message);
+        return { proposals: [] };
+    }
+}
+
+function writeStaging(workspacePath, data) {
+    writeFileSync(getStagingPath(workspacePath), JSON.stringify(data, null, 2), 'utf-8');
+}
+
+function nextProposalId(proposals) {
+    if (proposals.length === 0) return 'prop-001';
+    const nums = proposals.map(p => parseInt(p.id.replace('prop-', ''), 10)).filter(n => !isNaN(n));
+    const max = nums.length > 0 ? Math.max(...nums) : 0;
+    return `prop-${String(max + 1).padStart(3, '0')}`;
+}
+
+// ============================================================
+// TOOL DEFINITIONS
+// ============================================================
+
+export const TOOLS = [
+    {
+        name: "carl_stage_proposal",
+        description: "Stage a new CARL rule proposal for review. Sources: psmm, decisions, manual.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                domain: { type: "string", description: "Target domain (e.g., 'GLOBAL', 'DEVELOPMENT')" },
+                rule_text: { type: "string", description: "The proposed rule text" },
+                rationale: { type: "string", description: "Why this rule should exist" },
+                source: { type: "string", enum: VALID_SOURCES, description: "Where this proposal came from" }
+            },
+            required: ["domain", "rule_text", "rationale", "source"]
+        }
+    },
+    {
+        name: "carl_get_staged",
+        description: "List all pending rule proposals in the staging pipeline.",
+        inputSchema: { type: "object", properties: {} }
+    },
+    {
+        name: "carl_approve_proposal",
+        description: "Approve a staged proposal — writes the rule to the target domain file and removes from staging.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Proposal ID (e.g., 'prop-001')" }
+            },
+            required: ["id"]
+        }
+    },
+    {
+        name: "carl_kill_proposal",
+        description: "Delete a staged proposal permanently.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Proposal ID to delete" }
+            },
+            required: ["id"]
+        }
+    },
+    {
+        name: "carl_archive_proposal",
+        description: "Archive a proposal — keeps it for reference but doesn't activate as a rule.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Proposal ID to archive" }
+            },
+            required: ["id"]
+        }
+    }
+];
+
+// ============================================================
+// TOOL HANDLERS
+// ============================================================
+
+export async function handleTool(name, args, workspacePath) {
+    switch (name) {
+        case "carl_stage_proposal": return stageProposal(args, workspacePath);
+        case "carl_get_staged": return getStaged(workspacePath);
+        case "carl_approve_proposal": return approveProposal(args, workspacePath);
+        case "carl_kill_proposal": return killProposal(args, workspacePath);
+        case "carl_archive_proposal": return archiveProposal(args, workspacePath);
+        default: return null;
+    }
+}
+
+async function stageProposal(args, workspacePath) {
+    const { domain, rule_text, rationale, source } = args;
+
+    if (!VALID_SOURCES.includes(source)) {
+        return { success: false, error: `Invalid source: ${source}. Valid: ${VALID_SOURCES.join(', ')}` };
+    }
+
+    debugLog('Staging proposal for domain:', domain);
+
+    const data = readStaging(workspacePath);
+    const id = nextProposalId(data.proposals);
+    const date = new Date().toISOString().split('T')[0];
+
+    const proposal = {
+        id,
+        proposed: date,
+        source,
+        domain: domain.toUpperCase(),
+        rule_text,
+        rationale,
+        status: 'pending'
+    };
+
+    data.proposals.push(proposal);
+    writeStaging(workspacePath, data);
+
+    return {
+        success: true,
+        id,
+        domain: proposal.domain,
+        message: `Staged ${id} for ${proposal.domain}: "${rule_text.slice(0, 60)}..."`
+    };
+}
+
+async function getStaged(workspacePath) {
+    debugLog('Getting staged proposals');
+    const data = readStaging(workspacePath);
+
+    const pending = data.proposals.filter(p => p.status === 'pending');
+    const archived = data.proposals.filter(p => p.status === 'archived');
+
+    return {
+        success: true,
+        pending_count: pending.length,
+        archived_count: archived.length,
+        pending,
+        archived
+    };
+}
+
+async function approveProposal(args, workspacePath) {
+    const { id } = args;
+    debugLog('Approving proposal:', id);
+
+    const data = readStaging(workspacePath);
+    const idx = data.proposals.findIndex(p => p.id === id && p.status === 'pending');
+
+    if (idx === -1) {
+        return { success: false, error: `Pending proposal not found: ${id}` };
+    }
+
+    const proposal = data.proposals[idx];
+    const domain = proposal.domain;
+    const domainLower = domain.toLowerCase();
+
+    // Find the domain file
+    const domainFilePath = join(workspacePath, '.carl', domainLower);
+
+    if (!existsSync(domainFilePath)) {
+        return { success: false, error: `Domain file not found: .carl/${domainLower}` };
+    }
+
+    // Read domain file and find next rule number
+    const content = readFileSync(domainFilePath, 'utf-8');
+    const ruleRegex = new RegExp(`${domain}_RULE_(\\d+)`, 'g');
+    const ruleNums = [...content.matchAll(ruleRegex)].map(m => parseInt(m[1], 10));
+    const nextNum = ruleNums.length > 0 ? Math.max(...ruleNums) + 1 : 1;
+
+    // Append the new rule
+    const ruleLine = `${domain}_RULE_${nextNum}=${proposal.rule_text}\n`;
+    appendFileSync(domainFilePath, ruleLine, 'utf-8');
+
+    // Remove from staging
+    data.proposals.splice(idx, 1);
+    writeStaging(workspacePath, data);
+
+    return {
+        success: true,
+        id,
+        domain,
+        rule_number: nextNum,
+        message: `Approved ${id} → ${domain}_RULE_${nextNum} written to .carl/${domainLower}`
+    };
+}
+
+async function killProposal(args, workspacePath) {
+    const { id } = args;
+    debugLog('Killing proposal:', id);
+
+    const data = readStaging(workspacePath);
+    const idx = data.proposals.findIndex(p => p.id === id);
+
+    if (idx === -1) {
+        return { success: false, error: `Proposal not found: ${id}` };
+    }
+
+    data.proposals.splice(idx, 1);
+    writeStaging(workspacePath, data);
+
+    return { success: true, message: `Deleted proposal ${id}` };
+}
+
+async function archiveProposal(args, workspacePath) {
+    const { id } = args;
+    debugLog('Archiving proposal:', id);
+
+    const data = readStaging(workspacePath);
+    const proposal = data.proposals.find(p => p.id === id && p.status === 'pending');
+
+    if (!proposal) {
+        return { success: false, error: `Pending proposal not found: ${id}` };
+    }
+
+    proposal.status = 'archived';
+    proposal.archived_date = new Date().toISOString().split('T')[0];
+    writeStaging(workspacePath, data);
+
+    return { success: true, message: `Archived proposal ${id}` };
+}

package/src/skill/base.md

@@ -0,0 +1,111 @@
+---
+name: base
+type: suite
+version: 0.1.0
+category: workspace-orchestration
+description: "Builder's Automated State Engine — workspace lifecycle management for Claude Code. Scaffold, audit, groom, and maintain AI builder workspaces. Manage data surfaces for structured context injection. Use when user mentions workspace setup, cleanup, organization, maintenance, grooming, auditing workspace health, surfaces, or BASE."
+allowed-tools: [Read, Write, Glob, Grep, Edit, Bash, Agent, AskUserQuestion]
+---
+
+<activation>
+
+## What
+BASE (Builder's Automated State Engine) manages the lifecycle of a Claude Code workspace. It scaffolds new workspaces, audits existing ones, runs structured grooming cycles, and maintains workspace health through automated drift detection.
+
+## When to Use
+- User says "base", "workspace", "cleanup", "organize", "audit my workspace", "groom", "surface", "create a surface"
+- User wants to set up a new workspace from scratch
+- User wants to optimize or clean up an existing workspace
+- User asks about workspace health, staleness, or drift
+- Session start hook detects overdue grooming
+- User wants to review workspace evolution history
+
+## Not For
+- Project-level build orchestration (that's PAUL)
+- Session-level rule management (that's CARL)
+- Code quality auditing (that's AEGIS)
+- Skill/tool creation (that's Skillsmith)
+
+</activation>
+
+<persona>
+
+## Role
+Workspace operations engineer. Knows the territory, tracks what's drifting, enforces maintenance cadence. Tactical, not theoretical.
+
+## Style
+- Direct, structured, checklist-driven
+- Presents health dashboards and drift scores
+- Asks focused questions during grooming (voice-friendly)
+- Never skips areas — systematic coverage
+- Recommends, doesn't dictate
+
+## Expertise
+- Workspace architecture and file organization
+- Context document lifecycle (data surfaces, ACTIVE.md, BACKLOG.md)
+- Tool and configuration management
+- Drift detection and prevention patterns
+- Claude Code ecosystem (PAUL, CARL, AEGIS, Skillsmith integration)
+
+</persona>
+
+<commands>
+
+| Command | Description | Routes To |
+|---------|------------|-----------|
+| `/base:pulse` | Daily activation — workspace health briefing | `@~/.claude/base-framework/tasks/pulse.md` |
+| `/base:groom` | Weekly maintenance cycle | `@~/.claude/base-framework/tasks/groom.md` |
+| `/base:audit` | Deep workspace optimization | `@~/.claude/base-framework/tasks/audit.md` |
+| `/base:scaffold` | Set up BASE in a new workspace | `@~/.claude/base-framework/tasks/scaffold.md` |
+| `/base:status` | Quick health check (one-liner) | `@~/.claude/base-framework/tasks/status.md` |
+| `/base:history` | Workspace evolution timeline | `@~/.claude/base-framework/tasks/history.md` |
+| `/base:audit-claude-md` | Audit CLAUDE.md, generate recommended version | `@~/.claude/base-framework/tasks/audit-claude-md.md` |
+| `/base:carl-hygiene` | CARL domain maintenance and rule review | `@~/.claude/base-framework/tasks/carl-hygiene.md` |
+| `/base:surface create` | Create a new data surface (guided) | `@~/.claude/base-framework/tasks/surface-create.md` |
+| `/base:surface convert` | Convert markdown file to data surface | `@~/.claude/base-framework/tasks/surface-convert.md` |
+| `/base:surface list` | Show all registered surfaces | `@~/.claude/base-framework/tasks/surface-list.md` |
+
+</commands>
+
+<routing>
+
+## Always Load
+- `@~/.claude/base-framework/context/base-principles.md` — Core workspace management principles
+- `@~/.claude/base-framework/frameworks/audit-strategies.md` — Reusable audit strategy definitions
+
+## Load on Command
+- `@~/.claude/base-framework/tasks/pulse.md` — on `/base:pulse`
+- `@~/.claude/base-framework/tasks/groom.md` — on `/base:groom`
+- `@~/.claude/base-framework/tasks/audit.md` — on `/base:audit`
+- `@~/.claude/base-framework/tasks/scaffold.md` — on `/base:scaffold`
+- `@~/.claude/base-framework/tasks/status.md` — on `/base:status`
+- `@~/.claude/base-framework/tasks/history.md` — on `/base:history`
+- `@~/.claude/base-framework/tasks/carl-hygiene.md` — on `/base:carl-hygiene`
+- `@~/.claude/base-framework/tasks/surface-create.md` — on `/base:surface create`
+- `@~/.claude/base-framework/tasks/surface-convert.md` — on `/base:surface convert`
+- `@~/.claude/base-framework/tasks/surface-list.md` — on `/base:surface list`
+
+## Load on Demand
+- `@~/.claude/base-framework/templates/workspace-json.md` — When generating workspace.json
+- `@~/.claude/base-framework/templates/state-md.md` — When generating STATE.md
+- `@~/.claude/base-framework/frameworks/satellite-registration.md` — When handling PAUL project registration
+
+</routing>
+
+<greeting>
+
+BASE loaded. Builder's Automated State Engine.
+
+Available commands:
+- `/base:pulse` — What's the state of my workspace?
+- `/base:groom` — Run weekly maintenance
+- `/base:audit` — Deep optimization session
+- `/base:scaffold` — Set up BASE in a new workspace
+- `/base:status` — Quick health check
+- `/base:history` — Workspace evolution timeline
+- `/base:surface create` — Create a new data surface
+- `/base:surface list` — Show registered surfaces
+
+What do you need?
+
+</greeting>