forge-dev-framework 1.0.1 → 1.2.0

package/.claude/hooks/forge-event-guard.cjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// FORGE Hook: Event Immutability Guard
+// PreToolUse on Edit — prevents modifying existing event files in state/events/
+// Events are append-only per FORGE architecture
+
+const path = require('path');
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name || '';
+    const filePath = data.tool_input?.file_path || '';
+
+    // Only guard Edit operations on event files
+    if (toolName === 'Edit' && filePath) {
+      const resolved = path.resolve(filePath);
+      const eventsDir = path.resolve(process.cwd(), 'state', 'events');
+
+      if (resolved.startsWith(eventsDir) && resolved.endsWith('.json')) {
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: 'FORGE: Events are append-only. Cannot edit files in state/events/. Write new events instead.'
+        }));
+        return;
+      }
+    }
+
+    process.stdout.write(JSON.stringify({ decision: 'approve' }));
+  } catch (e) {
+    // Don't block on parse errors
+    process.stdout.write(JSON.stringify({ decision: 'approve' }));
+  }
+});

package/.claude/hooks/forge-size-guard.cjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// FORGE Hook: File Size Guard
+// PostToolUse on Write/Edit — warns when artifacts exceed token limits
+// Limits: CLAUDE.md ~2000t, rules ~1000t, REQUIREMENTS.md ~4000t, PLAN.md ~6000t
+
+const fs = require('fs');
+const path = require('path');
+
+// Approximate tokens as chars/4
+const LIMITS = {
+  'CLAUDE.md': { tokens: 2000, chars: 8000 },
+  'REQUIREMENTS.md': { tokens: 4000, chars: 16000 },
+  'PLAN.md': { tokens: 6000, chars: 24000 },
+};
+const RULES_LIMIT = { tokens: 1000, chars: 4000 };
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const filePath = data.tool_input?.file_path || data.tool_result?.file_path || '';
+
+    if (!filePath) {
+      process.stdout.write(JSON.stringify({ decision: 'approve' }));
+      return;
+    }
+
+    const basename = path.basename(filePath);
+    const resolved = path.resolve(filePath);
+
+    // Check specific file limits
+    let limit = LIMITS[basename];
+
+    // Check rules directory
+    if (!limit && resolved.includes('.claude/rules/') && resolved.endsWith('.md')) {
+      limit = RULES_LIMIT;
+    }
+
+    if (limit && fs.existsSync(resolved)) {
+      const size = fs.statSync(resolved).size;
+      if (size > limit.chars) {
+        const approxTokens = Math.round(size / 4);
+        process.stderr.write(
+          `\x1b[33m⚠ FORGE: ${basename} is ~${approxTokens} tokens (limit: ~${limit.tokens}). Consider trimming.\x1b[0m\n`
+        );
+      }
+    }
+
+    process.stdout.write(JSON.stringify({ decision: 'approve' }));
+  } catch (e) {
+    process.stdout.write(JSON.stringify({ decision: 'approve' }));
+  }
+});

package/.claude/rules/api-patterns.md

@@ -1,98 +1,13 @@
-# FORGE API Design Patterns
-
-> **Scope:** Internal FORGE APIs and interfaces between components.
-
-## File Naming
-
-- Use `kebab-case.ts` for files
-- Use `PascalCase` for types, interfaces, classes
-- Use `camelCase` for functions, variables
-
-## Module Structure
-
-Each module exports:
-1. Types/interfaces first
-2. Functions/operations
-3. Constants at the end
-
-```typescript
-// src/state/event-types.ts
-export interface StateEvent { ... }
-export interface TaskStartedEvent extends StateEvent { ... }
-
-export function createEvent(type: EventType, payload: unknown): StateEvent { ... }
-
-export const EVENT_TYPES = ['TASK_STARTED', 'TASK_COMPLETED', ...] as const;
-```
-
-## Error Handling
-
-- Define custom error types extending `Error`
-- Include error codes for programmatic handling
-- Provide context in error messages
-
-```typescript
-export class StateValidationError extends Error {
-  constructor(
-    public schema: string,
-    public errors: z.ZodError,
-  ) {
-    super(`State validation failed for ${schema}: ${errors.message}`);
-    this.name = 'StateValidationError';
-  }
-}
-```
-
-## Async Operations
-
-- Use `async/await`, not Promises directly
-- Return typed promises: `Promise<T>`
-- Handle rejections with try/catch
-
-```typescript
-export async function loadState(path: string): Promise<State> {
-  try {
-    const content = await fs.readFile(path, 'utf-8');
-    return JSON.parse(content);
-  } catch (error) {
-    throw new StateLoadError(path, error);
-  }
-}
-```
-
-## Input Validation
-
-- Use Zod schemas for all public APIs
-- Validate at module boundaries
-- Return typed results, never `any`
-
-```typescript
-import { z } from 'zod';
-
-const EventSchema = z.object({
-  eventId: z.string(),
-  timestamp: z.string().datetime(),
-  taskId: z.string(),
-  actor: z.string(),
-  type: z.enum(EVENT_TYPES),
-  payload: z.unknown(),
-});
-
-export function parseEvent(data: unknown): StateEvent {
-  return EventSchema.parse(data);
-}
-```
-
-## File I/O
-
-- Use absolute paths from project root
-- Check file existence before reading
-- Use atomic writes (write to temp, then rename)
-
-```typescript
-export async function writeState(path: string, state: State): Promise<void> {
-  const tmpPath = `${path}.tmp`;
-  await fs.writeFile(tmpPath, JSON.stringify(state, null, 2));
-  await fs.rename(tmpPath, path);
-}
-```
+---
+globs:
+  - "src/**/*.ts"
+---
+
+# API Design Patterns
+
+- **Files:** `kebab-case.ts` | **Types:** `PascalCase` | **Functions:** `camelCase`
+- **Module exports order:** types/interfaces → functions → constants
+- **Errors:** Custom error classes extending `Error` with error codes and context
+- **Async:** Use `async/await` with typed `Promise<T>` returns, try/catch for rejections
+- **Validation:** Zod schemas at all public API boundaries — never return `any`
+- **File I/O:** Absolute paths from project root, check existence, atomic writes (write to temp → rename)

package/.claude/rules/context-efficiency.md

@@ -0,0 +1,10 @@
+# Context Efficiency
+
+- **Read selectively:** Use `offset`/`limit` for large files — don't read entire files when only a section matters
+- **Minimize re-reads:** Cache key info in your working memory instead of re-reading the same file multiple times
+- **Short outputs:** Prefer concise tool output — pipe through `head`/`tail` when full output isn't needed
+- **Atomic tasks:** One task = one focused context. Don't accumulate unrelated work in a single session
+- **Summarize early:** After reading large files, extract what you need and move on — don't keep raw content in context
+- **Event hygiene:** Old events auto-archive after 7 days (SessionStart hook). Don't read archived events unless replaying state
+- **File size limits:** CLAUDE.md ~2000t, rules ~1000t each, REQUIREMENTS.md ~4000t, PLAN.md ~6000t (enforced by PostToolUse hook)
+- **Team messages:** Keep inter-agent messages concise — include only actionable information

package/.claude/rules/security-baseline.md

@@ -1,204 +1,18 @@
-# FORGE Security Baseline
-
-> **Scope:** Input validation, secrets management, dependency security, file operations.
-
-## Input Validation
-
-**All user input MUST be validated** with Zod schemas:
-
-```typescript
-const ConfigSchema = z.object({
-  mode: z.enum(['yolo', 'interactive']),
-  depth: z.enum(['quick', 'standard', 'comprehensive']),
-  maxTeammates: z.number().int().min(2).max(6),
-});
-
-export function loadConfig(path: string): Config {
-  const raw = JSON.parse(fs.readFileSync(path, 'utf-8'));
-  return ConfigSchema.parse(raw);
-}
-```
-
-### Path Validation
-
-Prevent directory traversal:
-
-```typescript
-import { resolve, normalize } from 'path';
-
-export function safeJoin(base: string, userPath: string): string {
-  const resolved = resolve(base, userPath);
-  if (!resolved.startsWith(base)) {
-    throw new Error('Invalid path: outside base directory');
-  }
-  return resolved;
-}
-```
-
-## Secrets Management
-
-**NEVER hardcode secrets.** Use environment variables:
-
-```typescript
-export function getApiKey(): string {
-  const key = process.env.FORGE_API_KEY;
-  if (!key) {
-    throw new Error('FORGE_API_KEY environment variable not set');
-  }
-  return key;
-}
-```
-
-### Git Ignore
-
-Add to `.gitignore`:
-
-```
-# FORGE
-state/events/*.json  # Optional: don't commit event logs
-.planning/local/     # User-specific config
-.env                 # Environment variables
-*.tmp                # Temp files
-```
-
-## Command Injection Prevention
-
-**NEVER pass user input directly to shell commands.** Use array arguments:
-
-```typescript
-// BAD
-await execa(`git checkout ${userBranch}`);
-
-// GOOD
-await execa('git', ['checkout', userBranch]);
-```
-
-## File Permissions
-
-Respect user's umask, don't over-permission:
-
-```typescript
-import { constants } from 'fs';
-
-await fs.writeFile(path, content, {
-  mode: 0o644, // rw-r--r--
-});
-```
-
-For sensitive files:
-
-```typescript
-await fs.writeFile(path, secrets, {
-  mode: 0o600, // rw-------
-});
-```
-
-## Dependency Security
-
-Run `npm audit` in CI:
-
-```yaml
-# .github/workflows/ci.yml
-- name: Audit dependencies
-  run: npm audit --audit-level=moderate
-```
-
-### Locked Dependencies
-
-Commit `package-lock.json`. Always install with exact versions:
-
-```bash
-npm ci  # Use lock file, don't update
-```
-
-## Code Execution Safety
-
-**NO `eval()`, no dynamic imports from untrusted sources:**
-
-```typescript
-// BAD
-const module = await import(userPath);
-
-// GOOD — validate against whitelist
-const ALLOWED = ['state', 'cli', 'templates'];
-if (ALLOWED.includes(userPath)) {
-  const module = await import(`./${userPath}`);
-}
-```
-
-## Event Log Integrity
-
-Events should be **append-only**. Never modify existing events:
-
-```typescript
-export async function writeEvent(path: string, event: StateEvent): Promise<void> {
-  if (await fs.pathExists(path)) {
-    throw new Error(`Event file already exists: ${path}`);
-  }
-  await fs.writeFile(path, JSON.stringify(event, null, 2), { mode: 0o444 }); // read-only
-}
-```
-
-## State Validation
-
-Validate `STATE.json` against schema on every read:
-
-```typescript
-export async function loadState(path: string): Promise<State> {
-  const content = await fs.readFile(path, 'utf-8');
-  const raw = JSON.parse(content);
-  return StateSchema.parse(raw); // Zod validation
-}
-```
-
-## Git Worktree Isolation
-
-Ensure worktrees can't access each other's files:
-
-```typescript
-export function validateWorktreePath(worktreePath: string): void {
-  if (!worktreePath.startsWith('.worktrees/')) {
-    throw new Error('Invalid worktree: must be under .worktrees/');
-  }
-}
-```
-
-## Error Messages
-
-**Don't leak sensitive info in errors:**
-
-```typescript
-// BAD — leaks file path
-throw new Error(`Failed to read ${filePath}`);
-
-// GOOD — generic error
-throw new Error('Failed to read configuration file');
-```
-
-## CI/CD Security
-
-```yaml
-# .github/workflows/ci.yml
-permissions:
-  contents: read  # No write access
-  issues: read
-  pull-requests: read
-
-- name: Run tests
-  run: npm test
-```
-
-## Third-Party Code
-
-Review all dependencies before adding:
-
-```bash
-npm audit
-npm ls <package>
-```
-
-Prefer well-maintained packages with:
-- Active development
-- Security policy
-- TypeScript types
-- Low dependency count
+---
+globs:
+  - "src/**/*.ts"
+  - "*.json"
+---
+
+# Security Baseline
+
+- **Input validation:** All user input validated with Zod schemas
+- **Path validation:** Prevent directory traversal — resolve and check `startsWith(base)`
+- **Secrets:** Never hardcode — use environment variables only
+- **Command injection:** Never pass user input to shell strings — use array args: `execa('git', ['checkout', branch])`
+- **File permissions:** `0o644` default, `0o600` for sensitive files, respect user umask
+- **No `eval()`** or dynamic imports from untrusted sources
+- **Events are append-only** — never modify, write as read-only (`0o444`)
+- **Validate STATE.json** against schema on every read
+- **Error messages:** Don't leak file paths or sensitive info
+- **Dependencies:** `npm audit` in CI, commit `package-lock.json`, use `npm ci`

package/.claude/rules/testing-standards.md

@@ -1,177 +1,16 @@
-# FORGE Testing Standards
-
-> **Scope:** Test coverage, test structure, what to test and how.
-
-## Test Structure
-
-Place tests next to source files with `.test.ts` suffix:
-
-```
-src/state/
-  event-types.ts
-  event-types.test.ts
-src/cli/
-  init.ts
-  init.test.ts
-```
-
-## Unit Tests
-
-Test **pure functions** and **business logic**:
-
-```typescript
-// event-types.test.ts
-import { describe, it, expect } from 'jest';
-import { parseEvent, createEvent } from './event-types';
-
-describe('parseEvent', () => {
-  it('parses valid TASK_STARTED event', () => {
-    const event = parseEvent({
-      eventId: 'evt-001',
-      timestamp: '2026-02-11T21:10:00Z',
-      taskId: 'api-003',
-      actor: 'backend',
-      type: 'TASK_STARTED',
-      payload: {},
-    });
-
-    expect(event.type).toBe('TASK_STARTED');
-  });
-
-  it('throws on missing eventId', () => {
-    expect(() => parseEvent({})).toThrow('eventId');
-  });
-
-  it('throws on invalid timestamp format', () => {
-    expect(() => parseEvent({
-      eventId: 'evt-001',
-      timestamp: 'invalid',
-      taskId: 'api-003',
-      actor: 'backend',
-      type: 'TASK_STARTED',
-      payload: {},
-    })).toThrow('timestamp');
-  });
-});
-```
-
-## Integration Tests
-
-Test **workflows end-to-end**:
-
-```typescript
-// state-merge.integration.test.ts
-describe('State Steward merge', () => {
-  const testDir = tmpdir();
-
-  beforeEach(async () => {
-    await fs.mkdir(`${testDir}/state/events`, { recursive: true });
-  });
-
-  it('merges events in timestamp order', async () => {
-    await writeEvent(`${testDir}/state/events/evt-002.json`, {
-      timestamp: '2026-02-11T21:11:00Z',
-      type: 'TASK_COMPLETED',
-    });
-    await writeEvent(`${testDir}/state/events/evt-001.json`, {
-      timestamp: '2026-02-11T21:10:00Z',
-      type: 'TASK_STARTED',
-    });
-
-    const state = await mergeEvents(testDir);
-
-    expect(state.tasks[0].status).toBe('completed');
-  });
-});
-```
-
-## Coverage Targets
-
-- **Core logic** (state, events, templates): >90%
-- **CLI commands**: >70%
-- **Git operations**: >80%
-
-Run: `npm run test:coverage`
-
-## Test Data
-
-Create fixtures in `test/fixtures/`:
-
-```
-test/fixtures/
-  events/
-    task-started.json
-    task-completed.json
-  state/
-    initial-state.json
-```
-
-## Mocking
-
-Mock external dependencies (git, fs, network):
-
-```typescript
-import { jest } from '@jest/globals';
-
-jest.mock('execa', () => ({
-  execa: jest.fn(),
-}));
-
-import { execa } from 'execa';
-
-it('creates git worktree', async () => {
-  (execa as jest.Mock).mockResolvedValue({ stdout: '' });
-
-  await createWorktree('api-003', 'forge/api-003');
-
-  expect(execa).toHaveBeenCalledWith('git', [
-    'worktree', 'add', '.worktrees/api-003', '-b', 'forge/api-003',
-  ]);
-});
-```
-
-## Test Organization
-
-Use `describe` for logical groups, `it` for individual tests:
-
-```typescript
-describe('State Steward', () => {
-  describe('mergeEvents', () => {
-    it('handles empty event directory');
-    it('sorts events by timestamp');
-    it('handles duplicate eventIds');
-    it('skips malformed events');
-  });
-});
-```
-
-## Async Tests
-
-Always `await` async operations:
-
-```typescript
-it('merges events', async () => {
-  const state = await mergeEvents('/path/to/events');
-  expect(state).toBeDefined();
-});
-```
-
-## Clean Up
-
-Use `beforeEach` / `afterEach` for test isolation:
-
-```typescript
-import { tmpdir } from 'os';
-import { rimraf } from 'rimraf';
-
-let testDir: string;
-
-beforeEach(async () => {
-  testDir = path.join(tmpdir(), `forge-test-${Date.now()}`);
-  await fs.mkdir(testDir, { recursive: true });
-});
-
-afterEach(async () => {
-  await rimraf(testDir);
-});
-```
+---
+globs:
+  - "**/*.test.ts"
+  - "**/*.spec.ts"
+  - "src/**/*.ts"
+---
+
+# Testing Standards
+
+- **Placement:** Tests next to source files with `.test.ts` suffix
+- **Coverage:** Core logic >90%, CLI >70%, Git ops >80%
+- **Fixtures:** In `test/fixtures/` (events, state samples)
+- **Mocking:** Mock externals (git, fs, network) with `jest.mock()`
+- **Structure:** `describe` for groups, `it` for cases, always `await` async ops
+- **Cleanup:** `beforeEach`/`afterEach` with temp dirs, `rimraf` after
+- **Run:** `npm test` / `npm run test:coverage`