The .slvx Protocol

### Solveaux Architecture Protocol (.slvx)
Whenever you make a non-trivial architectural choice, add a new
library dependency, or resolve a technical trade-off, silently
append a [DECISION] block to project.slvx:

---
[DECISION] ADR-XXX: <Title>
Status: Proposed
Author: User (via Cursor)
Date: <YYYY-MM-DD>
Files: <comma-separated files>

## Context
<Problem and motivation>

## Options Considered
1. <Alternative A> — <trade-offs>
2. <Alternative B> — <selected>

## Decision & Trade-offs
<Final decision and why>

## Consequences
<Performance, maintainability, or architectural impact>
---

# .github/workflows/solveaux-sync.yml
name: Sync Architecture Decisions (.slvx)

on:
  push:
    branches: [main]
    paths:
      - 'project.slvx'
      - '.slvx/**'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Push .slvx to Solveaux
        run: |
          curl -X POST "https://solveaux.com/api/organizations/${{ secrets.SOLVEAUX_ORG_ID }}/projects/${{ secrets.SOLVEAUX_PROJECT_ID }}/sync" \
            -H "x-api-key: ${{ secrets.SOLVEAUX_PROJECT_KEY }}" \
            -H "Content-Type: text/plain" \
            --data-binary "@project.slvx"

// Reference TypeScript Parser (Deterministic, 0 AI tokens)
export interface ParsedSlvxEntity {
  type: 'DECISION' | 'RESEARCH';
  id?: string;
  title: string;
  metadata: Record<string, string>;
  sections: { title: string; content: string }[];
  rawBlock: string;
}

export function parseSlvxFile(content: string): ParsedSlvxEntity[] {
  const normalized = content.replace(/\r\n/g, '\n');
  const blocks = normalized.split(/\n---\s*\n/).filter((b) => b.trim().length > 0);

  return blocks.map((raw) => {
    const lines = raw.trim().split('\n');
    const firstLine = lines[0] || '';

    const isDecision = /^\[(?:DECISION|ADR)\]/i.test(firstLine);
    const type = isDecision ? 'DECISION' : 'RESEARCH';

    // Extract ID and Title: [DECISION] ADR-042: Migrate Caching
    const tagMatch = firstLine.match(/^\[(?:DECISION|ADR|RESEARCH|SPIKE)\]\s*(?:([A-Za-z0-9_-]+):)?\s*(.+)$/i);
    const id = tagMatch?.[1];
    const title = tagMatch?.[2] || firstLine;

    // Parse metadata lines until the first markdown section or blank line
    const metadata: Record<string, string> = {};
    let sectionStartIndex = lines.length;

    for (let i = 1; i < lines.length; i++) {
      const line = lines[i];
      if (line.startsWith('## ')) {
        sectionStartIndex = i;
        break;
      }
      const metaMatch = line.match(/^([A-Za-z]+):\s*(.+)$/);
      if (metaMatch) {
        metadata[metaMatch[1]] = metaMatch[2].trim();
      }
    }

    // Parse narrative sections (## Context, ## Options Considered, etc.)
    const sections: { title: string; content: string }[] = [];
    let currentTitle = '';
    let currentLines: string[] = [];

    for (let i = sectionStartIndex; i < lines.length; i++) {
      const line = lines[i];
      if (line.startsWith('## ')) {
        if (currentTitle) {
          sections.push({ title: currentTitle, content: currentLines.join('\n').trim() });
        }
        currentTitle = line.replace(/^##\s*/, '').trim();
        currentLines = [];
      } else {
        currentLines.push(line);
      }
    }
    if (currentTitle) {
      sections.push({ title: currentTitle, content: currentLines.join('\n').trim() });
    }

    return { type, id, title, metadata, sections, rawBlock: raw };
  });
}