feat: whyrating - initial project from turbostarter boilerplate

2026-02-04 01:54:52 +01:00
commit 5cdc07cd39
1618 changed files with 338230 additions and 0 deletions
--- a/docs/tcs/TCS-QUICKSTART.md
+++ b/docs/tcs/TCS-QUICKSTART.md
@@ -0,0 +1,208 @@
+# TCS Quick Start
+
+> Build a compiler in hours, not weeks.
+
+## Prerequisites
+
+- Node.js 18+
+- pnpm
+- Anthropic API key
+
+## 1. Define Your Triangle (5 min)
+
+Pick 3 representations of the same semantic content:
+
+```
+Example: Form Builder
+├── Visual: Form UI mockup/description
+├── Structured: JSON Schema
+└── Compact: FormDSL
+```
+
+## 2. Write Initial Spec (15 min)
+
+```markdown
+# FormDSL Spec v0.1
+
+## Syntax
+form "name"
+  ? field_id "Label" type [validation]
+  ! message "text"
+  -> next_field
+end
+
+## Types
+Tx = text, Em = email, Ph = phone, Nm = number
+
+## Example
+form "contact"
+  ? name "Your name" Tx [required]
+  ? email "Email" Em [required]
+  ! thanks "Thank you!"
+end
+```
+
+## 3. Create Sample Generator (10 min)
+
+```typescript
+// tcs/generate.ts
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic();
+
+export async function generateTriangle(prompt: string) {
+  const [visual, structured, dsl] = await Promise.all([
+    client.messages.create({
+      model: 'claude-sonnet-4-20250514',
+      max_tokens: 2000,
+      messages: [{ role: 'user', content: `Describe this form visually: ${prompt}` }]
+    }),
+    client.messages.create({
+      model: 'claude-sonnet-4-20250514',
+      max_tokens: 2000,
+      messages: [{ role: 'user', content: `Generate JSON Schema for: ${prompt}` }]
+    }),
+    client.messages.create({
+      model: 'claude-sonnet-4-20250514',
+      max_tokens: 2000,
+      system: `You write FormDSL. Spec: [paste spec here]`,
+      messages: [{ role: 'user', content: prompt }]
+    }),
+  ]);
+
+  return { visual, structured, dsl };
+}
+```
+
+## 4. Create Triangulator (10 min)
+
+```typescript
+// tcs/triangulate.ts
+export async function triangulate(sample: Triangle) {
+  const response = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 2000,
+    messages: [{
+      role: 'user',
+      content: `Compare these 3 representations. Are they semantically equivalent?
+
+VISUAL:
+${sample.visual}
+
+JSON SCHEMA:
+${JSON.stringify(sample.structured, null, 2)}
+
+DSL:
+${sample.dsl}
+
+Return JSON: { equivalent: boolean, disagreements: string[], specGaps: string[] }`
+    }]
+  });
+
+  return JSON.parse(response.content[0].text);
+}
+```
+
+## 5. Run TCS Loop (iterate)
+
+```typescript
+// tcs/iterate.ts
+async function tcsIteration(spec: string, sampleCount = 10) {
+  // Generate samples
+  const prompts = await generatePrompts(sampleCount);
+  const samples = await Promise.all(prompts.map(generateTriangle));
+
+  // Triangulate
+  const results = await Promise.all(samples.map(triangulate));
+
+  // Collect findings
+  const findings = results
+    .filter(r => !r.equivalent)
+    .flatMap(r => r.specGaps);
+
+  // Evolve spec if needed
+  if (findings.length > 0) {
+    spec = await evolveSpec(spec, findings);
+  }
+
+  // Build/update compiler
+  await buildCompiler(spec);
+
+  // Test
+  const testResults = await runTests(samples.filter((_, i) => results[i].equivalent));
+
+  return { spec, passRate: testResults.passRate, findings };
+}
+
+// Main loop
+let spec = readFileSync('spec.md', 'utf-8');
+while (true) {
+  const result = await tcsIteration(spec);
+  spec = result.spec;
+
+  if (result.passRate === 1 && result.findings.length === 0) {
+    console.log('Converged!');
+    break;
+  }
+}
+```
+
+## 6. Output
+
+After convergence:
+
+```
+output/
+├── spec-final.md      # Evolved specification
+├── compiler/
+│   ├── scanner.ts     # Tokenizer
+│   ├── parser.ts      # AST builder
+│   └── emitter.ts     # Code generator
+└── tests/
+    └── samples.json   # Validated test cases
+```
+
+## Tips
+
+1. **Start small** - 5-10 samples per iteration
+2. **Parallelize** - Generate/triangulate concurrently
+3. **Trust disagreements** - They reveal real spec gaps
+4. **Checkpoint often** - Save state every iteration
+5. **Let it converge** - Don't manually fix, let TCS find issues
+
+## Example Run
+
+```bash
+$ pnpm tcs:run --spec form-dsl.md --target 50
+
+Iteration 1: 10 samples, 3 disagreements, 2 spec changes
+Iteration 2: 10 samples, 1 disagreement, 1 spec change
+Iteration 3: 10 samples, 0 disagreements, 0 spec changes
+Iteration 4: 20 samples, 0 disagreements, 0 spec changes
+✓ Converged at 50 samples, 4 iterations
+```
+
+## Quality Rules (Non-Negotiable)
+
+1. **No bypassing** - Errors reveal spec gaps, don't suppress them
+2. **No patches** - Generalize fixes, don't add special cases
+3. **Production code** - Strict TypeScript, no TODOs, no debug code
+4. **Redesign when stuck** - Bad architecture can't be patched
+
+```typescript
+// ❌ WRONG
+try { parse(input) } catch { return null }  // Bypassing
+if (sample === 'special') { ... }            // Isolated patch
+const x: any = ...                            // Not production
+
+// ✅ RIGHT
+const result = parse(input)                   // Let it fail, fix root cause
+handleAllCases(sample)                        // Generalized solution
+const x: ParsedNode = ...                     // Strict types
+```
+
+## Next Steps
+
+- Read [TCS-AI-METHODOLOGY.md](./TCS-AI-METHODOLOGY.md) for full theory
+- Read [TCS-CLAUDE-CODE.md](./TCS-CLAUDE-CODE.md) for Claude Code execution
+- Check [TCS-ROADMAP.md](./TCS-ROADMAP.md) for liquid package applications