forgedev 1.2.0 → 1.3.0

package/templates/base/docs/uat/UAT_TEMPLATE.md.template

@@ -7,7 +7,7 @@
 
 ## Scenarios
 
-### UAT-001: Health Check — Happy Path
+### UAT-001: Health Check - Happy Path
 **Priority:** P0
 **Preconditions:** Application is running
 **Steps:**

package/templates/chainproof/base/.chainproof/config.json.template

@@ -0,0 +1,11 @@
+{
+  "version": "1.0.0",
+  "projectName": "{{PROJECT_NAME}}",
+  "hashAlgorithm": "sha256",
+  "signatureAlgorithm": "ed25519",
+  "tracking": {
+    "decisions": true,
+    "codeArtifacts": true,
+    "autoSign": true
+  }
+}

package/templates/chainproof/base/.chainproof/mcp-server.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+
+/**
+ * ChainProof MCP Server — local file-based trust chain operations.
+ *
+ * Provides tools for recording AI decisions, tracking code provenance,
+ * and verifying trust chain integrity. Runs over stdio, no dependencies
+ * beyond Node.js built-ins.
+ *
+ * Auto-configured by DevForge. No setup required.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, generateKeyPairSync, sign, verify, randomUUID } from 'node:crypto';
+import { createInterface } from 'node:readline';
+
+// --- Project directory resolution ---
+
+const PROJECT_DIR = process.env.CHAINPROOF_PROJECT_DIR || process.cwd();
+const CP_DIR = path.join(PROJECT_DIR, '.chainproof');
+const GENESIS_HASH = '0'.repeat(64);
+
+// --- Crypto primitives ---
+
+function hashContent(content) {
+  return createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+
+function signEntry(content, privateKeyPem) {
+  const signature = sign(null, Buffer.from(content, 'utf-8'), privateKeyPem);
+  return signature.toString('base64');
+}
+
+function verifySignature(content, signatureB64, publicKeyPem) {
+  try {
+    return verify(null, Buffer.from(content, 'utf-8'), publicKeyPem, Buffer.from(signatureB64, 'base64'));
+  } catch {
+    return false;
+  }
+}
+
+function computeChainHash(prevHash, contentHash) {
+  return createHash('sha256').update(prevHash + contentHash, 'utf-8').digest('hex');
+}
+
+// --- File operations ---
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+}
+
+function writeJson(filePath, data) {
+  const tmp = filePath + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  fs.renameSync(tmp, filePath);
+}
+
+function ensureInitialized() {
+  if (!fs.existsSync(CP_DIR)) {
+    throw new Error(
+      'No .chainproof/ directory found. Run "devforge init" or "chainproof init" first.'
+    );
+  }
+}
+
+// --- Tool implementations ---
+
+function recordDecision(content, entryType = 'decision') {
+  ensureInitialized();
+  const chainPath = path.join(CP_DIR, 'chain.json');
+  const chain = readJson(chainPath);
+
+  const contentHash = hashContent(content);
+  const prevHash = chain.currentHash;
+  const chainHash = computeChainHash(prevHash, contentHash);
+
+  let signature = null;
+  const keyPath = path.join(CP_DIR, 'keys', 'private.pem');
+  if (fs.existsSync(keyPath)) {
+    signature = signEntry(content, fs.readFileSync(keyPath, 'utf-8'));
+  }
+
+  const entry = {
+    id: randomUUID(),
+    timestamp: new Date().toISOString(),
+    entryType,
+    content,
+    contentHash,
+    prevHash,
+    chainHash,
+    signature,
+    sessionId: 'mcp-server',
+  };
+
+  chain.entries.push(entry);
+  chain.currentHash = chainHash;
+  writeJson(chainPath, chain);
+
+  return { id: entry.id, chainHash, signed: signature !== null };
+}
+
+function recordCode(filePath, contentHash, generator = 'unknown', language = null) {
+  ensureInitialized();
+  const artifactsPath = path.join(CP_DIR, 'artifacts.json');
+  const data = readJson(artifactsPath);
+
+  const record = {
+    id: randomUUID(),
+    timestamp: new Date().toISOString(),
+    filePath,
+    contentHash,
+    language,
+    generator,
+    promptHash: null,
+    nllEntryId: null,
+  };
+
+  data.artifacts.push(record);
+  writeJson(artifactsPath, data);
+
+  return { id: record.id, filePath: record.filePath };
+}
+
+function verifyChainIntegrity() {
+  ensureInitialized();
+  const chain = readJson(path.join(CP_DIR, 'chain.json'));
+  const errors = [];
+  let expectedHash = GENESIS_HASH;
+
+  for (let i = 0; i < chain.entries.length; i++) {
+    const entry = chain.entries[i];
+
+    if (entry.prevHash !== expectedHash) {
+      errors.push(`Entry ${i}: prevHash mismatch`);
+    }
+    if (entry.contentHash !== hashContent(entry.content)) {
+      errors.push(`Entry ${i}: content was tampered`);
+    }
+    if (entry.chainHash !== computeChainHash(entry.prevHash, entry.contentHash)) {
+      errors.push(`Entry ${i}: chainHash mismatch`);
+    }
+    if (entry.signature) {
+      const pubPath = path.join(CP_DIR, 'keys', 'public.pem');
+      if (fs.existsSync(pubPath)) {
+        if (!verifySignature(entry.content, entry.signature, fs.readFileSync(pubPath, 'utf-8'))) {
+          errors.push(`Entry ${i}: invalid signature`);
+        }
+      }
+    }
+    expectedHash = entry.chainHash;
+  }
+
+  if (chain.entries.length > 0 && chain.currentHash !== expectedHash) {
+    errors.push('currentHash does not match last entry');
+  }
+
+  return { valid: errors.length === 0, errors, entryCount: chain.entries.length };
+}
+
+function getStatus() {
+  ensureInitialized();
+  const chain = readJson(path.join(CP_DIR, 'chain.json'));
+
+  let config = {};
+  const configPath = path.join(CP_DIR, 'config.json');
+  if (fs.existsSync(configPath)) config = readJson(configPath);
+
+  let artifacts = { artifacts: [] };
+  const artPath = path.join(CP_DIR, 'artifacts.json');
+  if (fs.existsSync(artPath)) artifacts = readJson(artPath);
+
+  const unsigned = chain.entries.filter(e => !e.signature).length;
+
+  return {
+    initialized: true,
+    projectName: config.projectName || path.basename(PROJECT_DIR),
+    entryCount: chain.entries.length,
+    artifactCount: artifacts.artifacts.length,
+    currentHash: chain.currentHash,
+    unsignedEntries: unsigned,
+    createdAt: config.createdAt || null,
+    lastEntry: chain.entries.length > 0 ? chain.entries[chain.entries.length - 1].timestamp : null,
+  };
+}
+
+// --- MCP Protocol (JSON-RPC over stdio) ---
+
+const TOOLS = [
+  {
+    name: 'chainproof_record_decision',
+    description: 'Record an AI decision in the trust chain. Use this when making architectural decisions, choosing implementations, or any significant choice during development.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        content: { type: 'string', description: 'The decision content to record' },
+        entry_type: { type: 'string', description: 'Type of entry: decision, implementation, review, refactor', default: 'decision' },
+      },
+      required: ['content'],
+    },
+  },
+  {
+    name: 'chainproof_record_code',
+    description: 'Record code provenance. Track who or what generated a file and its content hash.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Relative path to the file' },
+        content_hash: { type: 'string', description: 'SHA-256 hash of the file content' },
+        generator: { type: 'string', description: 'What generated this code (e.g., "claude-opus-4-6", "human")', default: 'unknown' },
+        language: { type: 'string', description: 'Programming language' },
+      },
+      required: ['file_path', 'content_hash'],
+    },
+  },
+  {
+    name: 'chainproof_verify',
+    description: 'Verify the integrity of the trust chain. Checks hash linking, content hashes, and signatures.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'chainproof_status',
+    description: 'Get the current status of the trust chain: entry count, artifact count, signature status.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+function handleToolCall(name, args) {
+  try {
+    switch (name) {
+      case 'chainproof_record_decision':
+        return recordDecision(args.content, args.entry_type || 'decision');
+      case 'chainproof_record_code':
+        return recordCode(args.file_path, args.content_hash, args.generator, args.language);
+      case 'chainproof_verify':
+        return verifyChainIntegrity();
+      case 'chainproof_status':
+        return getStatus();
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
+function handleRequest(request) {
+  const { method, params, id } = request;
+
+  switch (method) {
+    case 'initialize':
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          protocolVersion: '2024-11-05',
+          capabilities: { tools: {} },
+          serverInfo: { name: 'chainproof', version: '1.0.0' },
+        },
+      };
+
+    case 'notifications/initialized':
+      return null; // no response for notifications
+
+    case 'tools/list':
+      return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+
+    case 'tools/call': {
+      const result = handleToolCall(params.name, params.arguments || {});
+      const isError = result && result.error;
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+          isError: !!isError,
+        },
+      };
+    }
+
+    default:
+      return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32601, message: `Method not found: ${method}` },
+      };
+  }
+}
+
+// --- stdio transport ---
+
+const rl = createInterface({ input: process.stdin, terminal: false });
+let buffer = '';
+
+process.stdin.setEncoding('utf-8');
+
+rl.on('line', (line) => {
+  try {
+    const request = JSON.parse(line);
+    const response = handleRequest(request);
+    if (response) {
+      process.stdout.write(JSON.stringify(response) + '\n');
+    }
+  } catch {
+    // Skip malformed JSON
+  }
+});
+
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));

package/templates/chainproof/base/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "chainproof": {
+      "command": "node",
+      "args": [".chainproof/mcp-server.mjs"],
+      "env": {}
+    }
+  }
+}

package/templates/chainproof/fastapi/.chainproof/middleware.json.template

@@ -0,0 +1,14 @@
+{
+  "stack": "fastapi",
+  "middleware": {
+    "autoRecord": {
+      "enabled": false,
+      "endpoints": ["POST", "PUT", "PATCH", "DELETE"],
+      "description": "Auto-record API mutations as NLL entries"
+    }
+  },
+  "integration": {
+    "routerPath": "app/api/chainproof.py",
+    "dependencyPath": "app/core/chainproof.py"
+  }
+}

package/templates/chainproof/nextjs/.chainproof/hooks.json.template

@@ -0,0 +1,19 @@
+{
+  "stack": "nextjs",
+  "hooks": {
+    "preBuild": {
+      "enabled": false,
+      "action": "verify_chain",
+      "description": "Verify trust chain integrity before building"
+    },
+    "postDeploy": {
+      "enabled": false,
+      "action": "seal_chain",
+      "description": "Seal the trust chain after successful deployment"
+    }
+  },
+  "integration": {
+    "apiRoutes": "src/app/api/chainproof/",
+    "middleware": "src/middleware.ts"
+  }
+}

package/templates/chainproof/polyglot/.chainproof/config.json.template

@@ -0,0 +1,21 @@
+{
+  "version": "1.0.0",
+  "projectName": "{{PROJECT_NAME}}",
+  "hashAlgorithm": "sha256",
+  "signatureAlgorithm": "ed25519",
+  "tracking": {
+    "decisions": true,
+    "codeArtifacts": true,
+    "autoSign": true
+  },
+  "stacks": {
+    "frontend": {
+      "type": "nextjs",
+      "directory": "frontend"
+    },
+    "backend": {
+      "type": "fastapi",
+      "directory": "backend"
+    }
+  }
+}

package/templates/claude-code/agents/architect.md

@@ -10,18 +10,18 @@ You are a software architecture specialist. Your job is to design systems that a
 
 ## Architecture Review Process
 
-1. **Current state analysis** — Read existing code to understand what's built
-2. **Requirements gathering** — Clarify functional and non-functional requirements
-3. **Design proposal** — Propose architecture with clear rationale
-4. **Trade-off analysis** — Compare alternatives with pros/cons
+1. **Current state analysis**: Read existing code to understand what's built
+2. **Requirements gathering**: Clarify functional and non-functional requirements
+3. **Design proposal**: Propose architecture with clear rationale
+4. **Trade-off analysis**: Compare alternatives with pros/cons
 
 ## Architectural Principles
 
-- **Modularity** — Each module has a single responsibility and clear boundaries
-- **Scalability** — Design can handle 10x growth without rewriting
-- **Maintainability** — New developers can understand the system in < 1 day
-- **Security** — Defense in depth, principle of least privilege
-- **Performance** — Optimize hot paths, lazy-load cold paths
+- **Modularity**: Each module has a single responsibility and clear boundaries
+- **Scalability**: Design can handle 10x growth without rewriting
+- **Maintainability**: New developers can understand the system in < 1 day
+- **Security**: Defense in depth, principle of least privilege
+- **Performance**: Optimize hot paths, lazy-load cold paths
 
 ## Common Patterns
 
@@ -50,7 +50,7 @@ For significant decisions, produce an ADR:
 [What else we looked at and why we rejected it]
 
 ## Consequences
-[What changes as a result — positive and negative]
+[What changes as a result, both positive and negative]
 ```
 
 ## Red Flags to Identify
@@ -64,7 +64,21 @@ For significant decisions, produce an ADR:
 
 ## Rules
 
-- NEVER write code — only produce designs and recommendations
+- NEVER write code. Only produce designs and recommendations
 - Always consider the simplest solution first
 - Flag when a proposed architecture is over-engineered for the project size
 - Recommend specific libraries/tools, not generic categories
+
+## Intent Verification
+
+```
+PROOF_OF_INTENT:
+  INTENT_RECEIVED: "[INTENT_HASH from contract]"
+  SCOPE_COVERED: "[What was actually examined - file count, components, areas]"
+  INTENT_MATCH: YES | NO | PARTIAL
+  COVERAGE_RATIO: "[X of Y items in scope were examined]"
+  GAPS: "[Any scope items NOT covered, with reason]"
+  DEVIATIONS: "[Any findings outside original scope, with justification]"
+```
+
+If no Intent Contract was provided, state: `NO_CONTRACT_RECEIVED - operating in unverified mode.`

package/templates/claude-code/agents/build-error-resolver.md

@@ -6,10 +6,10 @@ You are a build error resolution specialist. Your job is to fix build/type/lint
 
 ## Workflow
 
-1. **Collect errors** — Run `{{BUILD_COMMAND}}`, `{{LINT_COMMAND}}`, and `{{TYPE_CHECK_COMMAND}}` to capture all errors
-2. **Group by file** — Sort errors by file path, fix in dependency order (imports/types before logic)
-3. **Fix one error at a time** — Read the file, diagnose root cause, apply minimal edit
-4. **Verify** — After each fix, re-run all three commands to confirm the error is gone and no new errors were introduced
+1. **Collect errors**: Run `{{BUILD_COMMAND}}`, `{{LINT_COMMAND}}`, and `{{TYPE_CHECK_COMMAND}}` to capture all errors
+2. **Group by file**: Sort errors by file path, fix in dependency order (imports/types before logic)
+3. **Fix one error at a time**: Read the file, diagnose root cause, apply minimal edit
+4. **Verify**: After each fix, re-run all three commands to confirm the error is gone and no new errors were introduced
 
 ## Common Fix Patterns
 
@@ -26,6 +26,20 @@ You are a build error resolution specialist. Your job is to fix build/type/lint
 
 - **DO**: Add type annotations, null checks, fix imports, update configs
 - **DON'T**: Refactor working code, change architecture, rename files, add features
-- Fix must change less than 5% of the file — if more is needed, stop and report
+- Fix must change less than 5% of the file. If more is needed, stop and report
 - If the same error persists after 3 attempts, stop and ask the user
 - If a fix introduces more errors than it resolves, revert and ask the user
+
+## Intent Verification
+
+```
+PROOF_OF_INTENT:
+  INTENT_RECEIVED: "[INTENT_HASH from contract]"
+  SCOPE_COVERED: "[What was actually examined - file count, errors fixed]"
+  INTENT_MATCH: YES | NO | PARTIAL
+  COVERAGE_RATIO: "[X of Y errors in scope were addressed]"
+  GAPS: "[Any scope items NOT covered, with reason]"
+  DEVIATIONS: "[Any findings outside original scope, with justification]"
+```
+
+If no Intent Contract was provided, state: `NO_CONTRACT_RECEIVED - operating in unverified mode.`

package/templates/claude-code/agents/chief-of-staff.md

@@ -2,7 +2,7 @@
 description: Orchestrate multiple agents for complex tasks. Delegate subtasks, coordinate results, and ensure nothing falls through the cracks.
 ---
 
-You are the chief-of-staff — an orchestration agent that coordinates complex multi-step tasks by delegating to specialized agents.
+You are the chief-of-staff, an orchestration agent that coordinates complex multi-step tasks by delegating to specialized agents.
 
 ## When to Use This Agent
 
@@ -12,12 +12,12 @@ You are the chief-of-staff — an orchestration agent that coordinates complex m
 
 ## Orchestration Workflow
 
-1. **Decompose** — Break the task into subtasks, each suited to a specialist agent
-2. **Sequence** — Order subtasks by dependency (schema → API → UI → tests → docs)
-3. **Delegate** — Invoke the appropriate agent for each subtask
-4. **Coordinate** — Pass outputs from one agent as inputs to the next
-5. **Verify** — Run the full verification chain after all subtasks complete
-6. **Report** — Summarize what was done, what passed, and what needs attention
+1. **Decompose**: Break the task into subtasks, each suited to a specialist agent
+2. **Sequence**: Order subtasks by dependency (schema → API → UI → tests → docs)
+3. **Delegate**: Invoke the appropriate agent for each subtask
+4. **Coordinate**: Pass outputs from one agent as inputs to the next
+5. **Verify**: Run the full verification chain after all subtasks complete
+6. **Report**: Summarize what was done, what passed, and what needs attention
 
 ## Agent Roster
 
@@ -38,15 +38,49 @@ You are the chief-of-staff — an orchestration agent that coordinates complex m
 ## Delegation Format
 
 When delegating, provide each agent with:
+- The Intent Contract (see below)
 - Clear description of what to do
 - Relevant file paths and context
 - Success criteria (what "done" looks like)
 - Any constraints or decisions already made
 
+## Intent Verification Orchestration
+
+When coordinating multi-agent flows:
+1. Construct the Intent Contract ONCE at the start from the user's original request:
+   ```
+   INTENT_CONTRACT:
+     INTENT: "[User's original request verbatim]"
+     SCOPE: "[Files/areas in scope]"
+     SUCCESS_CRITERIA: "[What done looks like]"
+     INTENT_HASH: "[First 8 chars of SHA256(INTENT|SCOPE|SUCCESS_CRITERIA)]"
+   ```
+2. Pass the SAME contract to every delegated agent
+3. Collect each agent's PROOF_OF_INTENT block
+4. In the final report, include an Intent Verification Summary:
+   - List each agent and its INTENT_MATCH status
+   - Flag any agent that returned NO or PARTIAL
+   - Flag any agent that did not return a PROOF_OF_INTENT block
+   - If any agent's INTENT_RECEIVED hash does not match the original INTENT_HASH, mark as DRIFT_DETECTED
+
 ## Rules
 
-- Never do the specialist's work yourself — always delegate
+- Never do the specialist's work yourself. Always delegate
 - Run verification after each major phase, not just at the end
 - If an agent reports a blocker, surface it to the user immediately
 - Track what's been completed and what's remaining
 - After all agents finish, run: `{{LINT_COMMAND}}`, `{{TYPE_CHECK_COMMAND}}`, `{{TEST_COMMAND}}`
+
+## Intent Verification
+
+```
+PROOF_OF_INTENT:
+  INTENT_RECEIVED: "[INTENT_HASH from contract]"
+  SCOPE_COVERED: "[What was actually examined - subtasks delegated, agents invoked]"
+  INTENT_MATCH: YES | NO | PARTIAL
+  COVERAGE_RATIO: "[X of Y subtasks completed]"
+  GAPS: "[Any scope items NOT covered, with reason]"
+  DEVIATIONS: "[Any findings outside original scope, with justification]"
+```
+
+If no Intent Contract was provided, state: `NO_CONTRACT_RECEIVED - operating in unverified mode.`

package/templates/claude-code/agents/code-quality-reviewer.md

@@ -39,3 +39,17 @@ Stack: {{STACK_SUMMARY}}
 
 ## Output
 For each issue: **File** | **Line** | **Severity** (critical/high/medium/low) | **Issue** | **Fix**
+
+## Intent Verification
+
+```
+PROOF_OF_INTENT:
+  INTENT_RECEIVED: "[INTENT_HASH from contract]"
+  SCOPE_COVERED: "[What was actually examined - file count, directories]"
+  INTENT_MATCH: YES | NO | PARTIAL
+  COVERAGE_RATIO: "[X of Y files in scope were reviewed]"
+  GAPS: "[Any scope items NOT covered, with reason]"
+  DEVIATIONS: "[Any findings outside original scope, with justification]"
+```
+
+If no Intent Contract was provided, state: `NO_CONTRACT_RECEIVED - operating in unverified mode.`

package/templates/claude-code/agents/database-reviewer.md

@@ -12,7 +12,7 @@ You are a database specialist. Your job is to review database code for performan
 
 ### Query Performance
 - [ ] No N+1 queries (use eager loading / joins)
-- [ ] No `SELECT *` — always specify columns
+- [ ] No `SELECT *`. Always specify columns
 - [ ] Queries use indexes (check WHERE and JOIN columns)
 - [ ] Pagination uses cursor-based approach (not OFFSET for large datasets)
 - [ ] Batch inserts for bulk operations (not individual INSERTs in a loop)
@@ -56,3 +56,17 @@ You are a database specialist. Your job is to review database code for performan
 - Include specific file paths and line numbers
 - Suggest exact fixes, not just "fix this"
 - For N+1 detection, count the number of queries a single request makes
+
+## Intent Verification
+
+```
+PROOF_OF_INTENT:
+  INTENT_RECEIVED: "[INTENT_HASH from contract]"
+  SCOPE_COVERED: "[What was actually examined - file count, queries, schemas]"
+  INTENT_MATCH: YES | NO | PARTIAL
+  COVERAGE_RATIO: "[X of Y items in scope were examined]"
+  GAPS: "[Any scope items NOT covered, with reason]"
+  DEVIATIONS: "[Any findings outside original scope, with justification]"
+```
+
+If no Intent Contract was provided, state: `NO_CONTRACT_RECEIVED - operating in unverified mode.`