workspace-maxxing 0.1.0

package/src/scripts/validate.ts

@@ -0,0 +1,516 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface CheckResult {
+  name: string;
+  passed: boolean;
+  message: string;
+}
+
+export interface ValidationResult {
+  passed: boolean;
+  checks: CheckResult[];
+}
+
+const REQUIRED_SYSTEM_HEADINGS = [
+  '## Role',
+  '## Folder Map',
+  '## Workflow Rules',
+  '## Scope Guardrails',
+  '## Sequential Execution Protocol',
+  '## Stage Boundaries',
+  '## Tooling Policy',
+];
+
+const REQUIRED_ROOT_CONTEXT_HEADINGS = [
+  '## How to Use This File',
+  '## Task Routing',
+  '## Loading Order',
+  '## Scope Guardrails',
+  '## Sequential Routing Contract',
+  '## Stage Handoff Routing',
+  '## Escalation',
+];
+
+const REQUIRED_STAGE_CONTEXT_HEADINGS = [
+  '## Purpose',
+  '## Inputs',
+  '## Outputs',
+  '## Dependencies',
+  '## Required Evidence',
+  '## Completion Criteria',
+  '## Handoff',
+];
+
+const DISALLOWED_STAGE_SOURCE_EXTENSIONS = new Set([
+  '.ts',
+  '.tsx',
+  '.js',
+  '.jsx',
+  '.py',
+  '.java',
+  '.go',
+  '.rs',
+  '.cs',
+  '.cpp',
+  '.c',
+  '.rb',
+  '.php',
+  '.swift',
+  '.kt',
+  '.scala',
+]);
+
+export function validateWorkspace(workspacePath: string): ValidationResult {
+  const ws = path.resolve(workspacePath);
+  const checks: CheckResult[] = [];
+  const numberedFolders = getNumberedStageFolders(ws);
+
+  const systemMdPath = path.join(ws, 'SYSTEM.md');
+  const systemExists = fs.existsSync(systemMdPath);
+  checks.push({
+    name: 'SYSTEM.md exists',
+    passed: systemExists,
+    message: systemExists ? 'Found' : 'Missing',
+  });
+
+  if (systemExists) {
+    const systemContent = fs.readFileSync(systemMdPath, 'utf-8');
+    const hasFolderMap = systemContent.toLowerCase().includes('folder map');
+    checks.push({
+      name: 'SYSTEM.md contains folder map',
+      passed: hasFolderMap,
+      message: hasFolderMap ? 'Found' : 'Missing "folder map" reference',
+    });
+
+    addRequiredHeadingChecks('SYSTEM.md', systemContent, REQUIRED_SYSTEM_HEADINGS, checks);
+  } else {
+    checks.push({
+      name: 'SYSTEM.md contains folder map',
+      passed: false,
+      message: 'Cannot check — SYSTEM.md missing',
+    });
+
+    for (const heading of REQUIRED_SYSTEM_HEADINGS) {
+      checks.push({
+        name: `SYSTEM.md contains ${heading}`,
+        passed: false,
+        message: `Cannot check - SYSTEM.md missing`,
+      });
+    }
+  }
+
+  const contextMdPath = path.join(ws, 'CONTEXT.md');
+  const contextExists = fs.existsSync(contextMdPath);
+  checks.push({
+    name: 'CONTEXT.md exists at root',
+    passed: contextExists,
+    message: contextExists ? 'Found' : 'Missing',
+  });
+
+  if (contextExists) {
+    const contextContent = fs.readFileSync(contextMdPath, 'utf-8');
+    addRequiredHeadingChecks('CONTEXT.md', contextContent, REQUIRED_ROOT_CONTEXT_HEADINGS, checks);
+
+    const allReferenced = numberedFolders.every((folder) => contextContent.includes(`${folder}/CONTEXT.md`));
+    checks.push({
+      name: 'Root routing references all numbered stages',
+      passed: allReferenced,
+      message: allReferenced ? 'All numbered stages are routed' : 'Missing one or more numbered stage routes',
+    });
+
+    const enforcesSelectiveLoading =
+      /## Loading Order/i.test(contextContent)
+      && /SYSTEM\.md/i.test(contextContent)
+      && /Only the task files needed/i.test(contextContent);
+
+    checks.push({
+      name: 'Root loading order enforces selective loading',
+      passed: enforcesSelectiveLoading,
+      message: enforcesSelectiveLoading
+        ? 'Selective loading guidance found'
+        : 'Loading order lacks selective-loading guidance',
+    });
+  } else {
+    for (const heading of REQUIRED_ROOT_CONTEXT_HEADINGS) {
+      checks.push({
+        name: `CONTEXT.md contains ${heading}`,
+        passed: false,
+        message: 'Cannot check - CONTEXT.md missing',
+      });
+    }
+
+    checks.push({
+      name: 'Root routing references all numbered stages',
+      passed: false,
+      message: 'Cannot check - CONTEXT.md missing',
+    });
+    checks.push({
+      name: 'Root loading order enforces selective loading',
+      passed: false,
+      message: 'Cannot check - CONTEXT.md missing',
+    });
+  }
+
+  const executionLogPath = path.join(ws, '00-meta', 'execution-log.md');
+  const executionLogExists = fs.existsSync(executionLogPath);
+  checks.push({
+    name: '00-meta/execution-log.md exists',
+    passed: executionLogExists,
+    message: executionLogExists ? 'Found' : 'Missing',
+  });
+
+  if (executionLogExists) {
+    const executionLogContent = fs.readFileSync(executionLogPath, 'utf-8');
+    const hasStageChecklistHeading = /## Stage Checklist/i.test(executionLogContent);
+    checks.push({
+      name: 'Execution log contains stage checklist heading',
+      passed: hasStageChecklistHeading,
+      message: hasStageChecklistHeading ? 'Found' : 'Missing "## Stage Checklist" heading',
+    });
+
+    const hasAllStageChecklistEntries = numberedFolders.every((folder) => {
+      const pattern = new RegExp(`^\\s*-\\s*\\[[ xX]\\]\\s+${escapeRegExp(folder)}\\s*$`, 'm');
+      return pattern.test(executionLogContent);
+    });
+    checks.push({
+      name: 'Execution log references all numbered stages',
+      passed: hasAllStageChecklistEntries,
+      message: hasAllStageChecklistEntries
+        ? 'All numbered stages are present in checklist'
+        : 'Missing one or more numbered stage checklist entries',
+    });
+
+    const sequentialOrderValid = hasAllStageChecklistEntries
+      ? isExecutionChecklistSequential(executionLogContent, numberedFolders)
+      : false;
+    checks.push({
+      name: 'Execution log stage completion order is sequential',
+      passed: sequentialOrderValid,
+      message: sequentialOrderValid
+        ? 'Stage completion order is sequential'
+        : 'Found later stage marked complete before earlier stage',
+    });
+  } else {
+    checks.push({
+      name: 'Execution log contains stage checklist heading',
+      passed: false,
+      message: 'Cannot check - execution log missing',
+    });
+    checks.push({
+      name: 'Execution log references all numbered stages',
+      passed: false,
+      message: 'Cannot check - execution log missing',
+    });
+    checks.push({
+      name: 'Execution log stage completion order is sequential',
+      passed: false,
+      message: 'Cannot check - execution log missing',
+    });
+  }
+
+  for (const folder of numberedFolders) {
+    const contextPath = path.join(ws, folder, 'CONTEXT.md');
+    const exists = fs.existsSync(contextPath);
+    checks.push({
+      name: `${folder}/CONTEXT.md exists`,
+      passed: exists,
+      message: exists ? 'Found' : 'Missing',
+    });
+
+    if (exists) {
+      const content = fs.readFileSync(contextPath, 'utf-8');
+      const notEmpty = content.trim().length > 0;
+      checks.push({
+        name: `${folder}/CONTEXT.md is not empty`,
+        passed: notEmpty,
+        message: notEmpty ? `${content.trim().length} chars` : 'File is empty',
+      });
+
+      addRequiredHeadingChecks(`${folder}/CONTEXT.md`, content, REQUIRED_STAGE_CONTEXT_HEADINGS, checks);
+
+      const deps = extractStageRefs(extractDependenciesSection(content));
+      const currentNum = parseInt(folder.slice(0, 2), 10);
+      const pointsToLaterStage = deps.some((dep) => parseInt(dep.slice(0, 2), 10) > currentNum);
+
+      checks.push({
+        name: `${folder} dependencies do not point to later stages`,
+        passed: !pointsToLaterStage,
+        message: !pointsToLaterStage ? 'Dependency direction valid' : 'Found dependency on later-numbered stage',
+      });
+    } else {
+      for (const heading of REQUIRED_STAGE_CONTEXT_HEADINGS) {
+        checks.push({
+          name: `${folder}/CONTEXT.md contains ${heading}`,
+          passed: false,
+          message: 'Cannot check - CONTEXT.md missing',
+        });
+      }
+
+      checks.push({
+        name: `${folder} dependencies do not point to later stages`,
+        passed: false,
+        message: 'Cannot check - CONTEXT.md missing',
+      });
+    }
+
+    const disallowedFiles = findDisallowedStageSourceFiles(path.join(ws, folder));
+    checks.push({
+      name: `${folder} contains no product source code files`,
+      passed: disallowedFiles.length === 0,
+      message: disallowedFiles.length === 0
+        ? 'Only workflow documentation artifacts found'
+        : `Found source files: ${disallowedFiles.join(', ')}`,
+    });
+  }
+
+  const allFiles = getAllMarkdownFiles(ws);
+  const duplicateCheck = checkDuplicateContent(allFiles);
+  checks.push(duplicateCheck);
+
+  // Agent-driven test-case enforcement (default)
+  const agentDrivenRequired = true;
+
+  checks.push({
+    name: 'Agent-driven test-case mode enforced',
+    passed: true,
+    message: 'Agent-driven mode is the default; validator requires .agents/iteration/test-cases.json',
+  });
+
+  if (agentDrivenRequired) {
+    const testCasesPath = path.join(ws, '.agents', 'iteration', 'test-cases.json');
+    const readyMarker = path.join(ws, '.agents', 'iteration', '.test-cases-ready');
+
+    const testCasesExists = fs.existsSync(testCasesPath);
+    checks.push({
+      name: '.agents/iteration/test-cases.json exists',
+      passed: testCasesExists,
+      message: testCasesExists ? 'Found' : 'Missing agent-generated test-cases file',
+    });
+
+    if (testCasesExists) {
+      try {
+        const raw = fs.readFileSync(testCasesPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const isArray = Array.isArray(parsed);
+        checks.push({
+          name: 'test-cases.json is a JSON array',
+          passed: isArray,
+          message: isArray ? `Contains ${parsed.length} case(s)` : 'Not an array',
+        });
+
+        if (isArray) {
+          const missingFields: string[] = [];
+          for (let i = 0; i < Math.min(parsed.length, 5); i++) {
+            const tc = parsed[i];
+            if (!tc || typeof tc !== 'object' || !tc.id || !tc.input || !tc.expected) {
+              missingFields.push(`item[${i}]`);
+            }
+          }
+
+          checks.push({
+            name: 'test-cases.json items have minimal fields',
+            passed: missingFields.length === 0,
+            message: missingFields.length === 0 ? 'Sample items valid' : `Missing fields in ${missingFields.join(', ')}`,
+          });
+        }
+      } catch (e) {
+        const emsg = (e && (e as any).message) ? (e as any).message : String(e);
+        checks.push({
+          name: 'test-cases.json parseable JSON',
+          passed: false,
+          message: `JSON parse error: ${emsg}`,
+        });
+      }
+    }
+
+    const readyExists = fs.existsSync(readyMarker);
+    checks.push({
+      name: '.agents/iteration/.test-cases-ready exists',
+      passed: readyExists,
+      message: readyExists ? 'Found' : 'Missing readiness marker file',
+    });
+  }
+
+  const passed = checks.every((c) => c.passed);
+
+  console.log(`\nValidation: ${ws}`);
+  console.log('='.repeat(50));
+  for (const check of checks) {
+    const icon = check.passed ? '✓' : '✗';
+    console.log(`  ${icon} ${check.name}: ${check.message}`);
+  }
+  console.log('='.repeat(50));
+  console.log(passed ? '✓ All checks passed' : '✗ Some checks failed');
+
+  return { passed, checks };
+}
+
+function getAllMarkdownFiles(dir: string): string[] {
+  const results: string[] = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...getAllMarkdownFiles(fullPath));
+    } else if (entry.name.endsWith('.md')) {
+      results.push(fullPath);
+    }
+  }
+
+  return results;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function hasHeading(content: string, heading: string): boolean {
+  return new RegExp(`^${escapeRegExp(heading)}\\s*$`, 'im').test(content);
+}
+
+function addRequiredHeadingChecks(
+  fileLabel: string,
+  content: string,
+  headings: string[],
+  checks: CheckResult[],
+): void {
+  for (const heading of headings) {
+    const found = hasHeading(content, heading);
+    checks.push({
+      name: `${fileLabel} contains ${heading}`,
+      passed: found,
+      message: found ? 'Found' : `Missing ${heading}`,
+    });
+  }
+}
+
+function checkDuplicateContent(files: string[]): CheckResult {
+  const MIN_DUPLICATE_LENGTH = 50;
+  const duplicates: string[] = [];
+
+  for (let i = 0; i < files.length; i++) {
+    for (let j = i + 1; j < files.length; j++) {
+      const contentA = fs.readFileSync(files[i], 'utf-8');
+      const contentB = fs.readFileSync(files[j], 'utf-8');
+
+      const linesA = contentA.split('\n');
+      const linesB = contentB.split('\n');
+
+      for (const lineA of linesA) {
+        const trimmed = lineA.trim();
+        if (trimmed.length > MIN_DUPLICATE_LENGTH) {
+          for (const lineB of linesB) {
+            if (lineB.trim() === trimmed) {
+              duplicates.push(trimmed.substring(0, 60) + '...');
+              break;
+            }
+          }
+        }
+      }
+    }
+  }
+
+  if (duplicates.length > 0) {
+    return {
+      name: 'No duplicate content across files',
+      passed: false,
+      message: `Found ${duplicates.length} duplicate text block(s)`,
+    };
+  }
+
+  return {
+    name: 'No duplicate content across files',
+    passed: true,
+    message: 'No duplicates found',
+  };
+}
+
+function getNumberedStageFolders(workspacePath: string): string[] {
+  const entries = fs.readdirSync(workspacePath, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory() && /^\d{2}-/.test(entry.name) && entry.name !== '00-meta')
+    .map((entry) => entry.name);
+}
+
+function extractDependenciesSection(content: string): string {
+  const match = content.match(/## Dependencies\s*([\s\S]*?)(?=\n##\s|$)/i);
+  return match ? match[1] : '';
+}
+
+function extractStageRefs(content: string): string[] {
+  const refs = new Set<string>();
+  const regex = /(\d{2}-[A-Za-z0-9-_]+)/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(content)) !== null) {
+    refs.add(match[1]);
+  }
+
+  return Array.from(refs);
+}
+
+function isExecutionChecklistSequential(content: string, stages: string[]): boolean {
+  let foundUncheckedStage = false;
+
+  for (const stage of stages) {
+    const pattern = new RegExp(`^\\s*-\\s*\\[([ xX])\\]\\s+${escapeRegExp(stage)}\\s*$`, 'm');
+    const match = content.match(pattern);
+    if (!match) {
+      return false;
+    }
+
+    const isChecked = match[1].toLowerCase() === 'x';
+    if (!isChecked) {
+      foundUncheckedStage = true;
+      continue;
+    }
+
+    if (foundUncheckedStage) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function findDisallowedStageSourceFiles(stageDir: string): string[] {
+  const disallowed: string[] = [];
+
+  const walk = (currentDir: string): void => {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        walk(fullPath);
+        continue;
+      }
+
+      const ext = path.extname(entry.name).toLowerCase();
+      if (DISALLOWED_STAGE_SOURCE_EXTENSIONS.has(ext)) {
+        disallowed.push(path.relative(stageDir, fullPath).replace(/\\/g, '/'));
+      }
+    }
+  };
+
+  walk(stageDir);
+
+  return disallowed;
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const workspaceIdx = args.indexOf('--workspace');
+  const workspace = workspaceIdx !== -1 ? args[workspaceIdx + 1] : undefined;
+
+  if (!workspace) {
+    console.error('Usage: node validate.ts --workspace <path>');
+    process.exit(1);
+  }
+
+  const result = validateWorkspace(workspace);
+  process.exit(result.passed ? 0 : 1);
+}

package/templates/.workspace-templates/CONTEXT.md

@@ -0,0 +1,44 @@
+# Routing Table
+
+## How to Use This File
+
+Map each task to the smallest required context and avoid loading unrelated files.
+
+## Task Routing
+
+| When you need to... | Go to | Load |
+|---------------------|-------|------|
+| Understand workspace constraints | SYSTEM.md | Always loaded first |
+| Gather or validate inputs | 01-input/CONTEXT.md | Input stage contract |
+| Analyze, process, or draft | 02-process/CONTEXT.md | Processing stage contract |
+| Finalize and deliver outputs | 03-output/CONTEXT.md | Output stage contract |
+| Check available tools | 00-meta/tools.md | Tool inventory |
+
+## Loading Order
+
+1. SYSTEM.md (always)
+2. This root CONTEXT.md
+3. One relevant stage CONTEXT.md
+4. Only the task files needed for that stage
+
+## Scope Guardrails
+
+- Route domain goals into workflow design stages and markdown deliverables.
+- Do not scaffold backend, frontend, or runtime product repositories from this routing file.
+- Keep artifacts file-structured and markdown-first across numbered workflow folders.
+
+## Sequential Routing Contract
+
+- Route to the earliest incomplete stage listed in 00-meta/execution-log.md.
+- Do not skip forward to later stages while earlier stages remain incomplete.
+- Append handoff notes after each completed stage before advancing.
+
+## Stage Handoff Routing
+
+- 01-input -> 02-process when input completion criteria are met
+- 02-process -> 03-output when processing completion criteria are met
+- 03-output -> delivery and closure
+
+## Escalation
+
+Escalate when required sections are missing, routing is ambiguous, or dependencies conflict with stage order.

package/templates/.workspace-templates/SYSTEM.md

@@ -0,0 +1,44 @@
+# System - Workspace Root
+
+## Role
+You are an AI assistant operating inside this workspace. Follow stage contracts, route tasks through stage contexts, and keep information canonical.
+
+## Folder Map
+
+| Folder | Purpose |
+|--------|---------|
+| 00-meta/ | Workspace configuration, tool inventory, session notes |
+| 01-input/ | Source materials, intake, and validation |
+| 02-process/ | Analysis, transformation, and drafting |
+| 03-output/ | Final deliverables and publication artifacts |
+
+## Workflow Rules
+
+1. Read this file first every session.
+2. Read root `CONTEXT.md` before loading stage files.
+3. Load only the stage context and task files required for the current step.
+4. Keep one canonical source for each fact; do not duplicate content across stages.
+
+## Scope Guardrails
+
+- Build workflow documentation, not product implementation code.
+- Keep stage outputs markdown-first (plans, checklists, prompts, routing notes).
+- If the user asks for product code, convert that into workflow requirements and stay inside ICM workspace scope.
+
+## Sequential Execution Protocol
+
+1. Complete stages in ascending numeric order.
+2. Record each completed stage in 00-meta/execution-log.md before routing onward.
+3. Do not generate final output until all prior stages are marked complete.
+
+## Stage Boundaries
+
+- Execute stages in order unless explicit handoff says otherwise.
+- One-way dependencies only: upstream -> downstream.
+- Downstream stages may reference upstream outputs, never reverse.
+
+## Tooling Policy
+
+- Tool inventory is tracked in `00-meta/tools.md`.
+- Check inventory before proposing installs.
+- Record approved tool changes in `00-meta/tools.md`.

package/templates/.workspace-templates/references/anti-patterns.md

@@ -0,0 +1,16 @@
+# Anti-Patterns & Rationalization Prevention
+
+Common rationalizations agents use to skip steps, with reality checks.
+
+| Thought | Reality |
+|---------|---------|
+| "This workspace looks good enough" | Good enough is the enemy of excellent. Run validation. |
+| "I'll skip research and go straight to building" | Building without research produces generic, non-optimal workspaces. |
+| "The user didn't ask for tests" | Autonomous workflows require self-verification. Tests are mandatory. |
+| "I'll fix this later" | Later never comes. Fix it now or escalate. |
+| "This sub-skill doesn't apply here" | If there's a 1% chance it applies, dispatch it. |
+| "The score is fine" | Fine is not good. Target > 85. |
+| "I already validated this" | Validation is a snapshot. Re-validate after every change. |
+| "This prompt update is cosmetic" | Prompt quality directly impacts agent behavior. No cosmetic-only changes. |
+| "I'll do all phases at once" | Phases exist for a reason. Complete each before moving to the next. |
+| "The user will review anyway" | Autonomous means autonomous. Deliver quality without requiring human review. |

package/templates/.workspace-templates/references/iron-laws.md

@@ -0,0 +1,26 @@
+# Iron Laws
+
+These rules are absolute. No exceptions. No rationalizations.
+
+## The Iron Laws of Workspace Building
+
+1. **NO BUILD WITHOUT PLAN** — Every workspace must have an approved architecture plan before scaffold.ts runs.
+
+2. **NO PLAN WITHOUT RESEARCH** — Architecture decisions must be informed by pattern research and context gathering.
+
+3. **NO IMPROVEMENT WITHOUT VALIDATION** — Never claim a workspace improved without running validate.ts before and after.
+
+4. **NO COMPLETION CLAIM WITHOUT VERIFICATION** — Run the full test suite and validation checks before declaring delivery.
+
+5. **NO SKIPPING PHASES** — The hybrid flow exists for a reason. Complete each phase before moving to the next.
+
+6. **NO SILENT FAILURES** — If a sub-skill fails, report it. Do not continue as if nothing happened.
+
+## Enforcement
+
+Before any action, ask: "Which iron law does this touch?" If the answer is "none," you're probably about to break one.
+
+Violation of any iron law requires immediate escalation to the human with:
+- Which law was violated
+- Why it was violated
+- Proposed fix

package/templates/.workspace-templates/references/reporting-format.md

@@ -0,0 +1,52 @@
+# Sub-Skill Report Format
+
+All sub-skills return a structured JSON report. Use this exact format.
+
+## Report Structure
+
+```json
+{
+  "skill": "<skill-name>",
+  "status": "passed|failed|escalated",
+  "timestamp": "<ISO-8601 timestamp>",
+  "findings": [
+    "<specific finding 1>",
+    "<specific finding 2>"
+  ],
+  "recommendations": [
+    "<actionable recommendation 1>",
+    "<actionable recommendation 2>"
+  ],
+  "metrics": {
+    "<metric-name>": <value>,
+    "score": <0-100>,
+    "itemsChecked": <number>,
+    "itemsPassed": <number>
+  },
+  "nextSkill": "<next-skill-name>|none"
+}
+```
+
+## Field Descriptions
+
+- `skill`: Name of the sub-skill that generated this report
+- `status`: One of "passed", "failed", or "escalated"
+  - `passed`: All checks passed, no critical issues
+  - `failed`: One or more checks failed, actionable items exist
+  - `escalated`: Cannot proceed, requires human intervention
+- `timestamp`: ISO-8601 timestamp of report generation
+- `findings`: Array of specific observations (both positive and negative)
+- `recommendations`: Array of actionable next steps
+- `metrics`: Quantitative measurements from the sub-skill
+  - `score`: 0-100 quality score
+  - `itemsChecked`: Total items evaluated
+  - `itemsPassed`: Items that passed evaluation
+- `nextSkill`: Suggested next sub-skill to dispatch, or "none" if workflow is complete
+
+## Usage
+
+Print the report as JSON to stdout when the sub-skill completes:
+
+```bash
+echo '{"skill":"validation","status":"passed",...}'
+```