From 05ed5203f16b2649f02232b2650a5d5d077c0e5b Mon Sep 17 00:00:00 2001 From: m3taversal Date: Sat, 7 Mar 2026 16:22:25 +0000 Subject: [PATCH] Add contributor docs, Alex onboarding brief, and evaluate-trigger script MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CONTRIBUTING.md: step-by-step guide for external contributors - docs/ALEX_BRIEF.md: onboarding brief for Alex — AI alignment domain - ops/evaluate-trigger.sh: headless Leo evaluation trigger (Ganymede reviewed) Co-Authored-By: Claude Opus 4.6 --- CONTRIBUTING.md | 129 +++++++++++++++++++++++++++++ docs/ALEX_BRIEF.md | 174 ++++++++++++++++++++++++++++++++++++++++ ops/evaluate-trigger.sh | 9 ++- 3 files changed, 310 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/ALEX_BRIEF.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8b5297a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,129 @@ +# Contributing to Teleo Codex + +You're contributing to a living knowledge base maintained by AI agents. Your job is to bring in source material. The agents extract claims, connect them to existing knowledge, and review everything before it merges. + +## What you need + +- GitHub account with collaborator access to this repo +- Git installed on your machine +- A source to contribute (article, report, paper, thread, etc.) + +## Step-by-step + +### 1. Clone the repo (first time only) + +```bash +git clone https://github.com/living-ip/teleo-codex.git +cd teleo-codex +``` + +### 2. Pull latest and create a branch + +```bash +git checkout main +git pull origin main +git checkout -b contrib/your-name/brief-description +``` + +Example: `contrib/alex/ai-alignment-report` + +### 3. Create a source file + +Create a markdown file in `inbox/archive/` with this naming convention: + +``` +inbox/archive/YYYY-MM-DD-author-handle-brief-slug.md +``` + +Example: `inbox/archive/2026-03-07-alex-ai-alignment-landscape.md` + +### 4. Add frontmatter + +Every source file starts with YAML frontmatter. Copy this template and fill it in: + +```yaml +--- +type: source +title: "Your source title here" +author: "Author Name (@handle if applicable)" +url: https://link-to-original-if-exists +date: 2026-03-07 +domain: ai-alignment +format: report +status: unprocessed +tags: [topic1, topic2, topic3] +--- +``` + +**Domain options:** `internet-finance`, `entertainment`, `ai-alignment`, `health`, `grand-strategy` + +**Format options:** `essay`, `newsletter`, `tweet`, `thread`, `whitepaper`, `paper`, `report`, `news` + +**Status:** Always set to `unprocessed` — the agents handle the rest. + +### 5. Add the content + +After the frontmatter, paste the full content of the source. This is what the agents will read and extract claims from. More content = better extraction. + +```markdown +--- +type: source +title: "AI Alignment in 2026: Where We Stand" +author: "Alex (@alexhandle)" +url: https://example.com/report +date: 2026-03-07 +domain: ai-alignment +format: report +status: unprocessed +tags: [ai-alignment, openai, anthropic, safety, governance] +--- + +# AI Alignment in 2026: Where We Stand + +[Full content of the report goes here. Include everything — +the agents need the complete text to extract claims properly.] +``` + +### 6. Commit and push + +```bash +git add inbox/archive/your-file.md +git commit -m "contrib: add AI alignment landscape report + +Source: [brief description of what this is and why it matters]" + +git push -u origin contrib/your-name/brief-description +``` + +### 7. Open a PR + +```bash +gh pr create --title "contrib: AI alignment landscape report" --body "Source material for agent extraction. + +- **What:** [one-line description] +- **Domain:** ai-alignment +- **Why it matters:** [why this adds value to the knowledge base]" +``` + +Or just go to GitHub and click "Compare & pull request" after pushing. + +### 8. What happens next + +1. **Theseus** (the ai-alignment agent) reads your source and extracts claims +2. **Leo** (the evaluator) reviews the extracted claims for quality +3. You'll see their feedback as PR comments +4. Once approved, the claims merge into the knowledge base + +You can respond to agent feedback directly in the PR comments. + +## Tips + +- **More context is better.** Paste the full article/report, not just a link. Agents extract better from complete text. +- **Pick the right domain.** If your source spans multiple domains, pick the primary one — the agents will flag cross-domain connections. +- **One source per file.** Don't combine multiple articles into one file. +- **Original analysis welcome.** Your own written analysis/report is just as valid as linking to someone else's article. Put yourself as the author. +- **Don't extract claims yourself.** Just provide the source material. The agents handle extraction — that's their job. + +## Questions? + +Open an issue or ask in the PR comments. The agents are watching. diff --git a/docs/ALEX_BRIEF.md b/docs/ALEX_BRIEF.md new file mode 100644 index 0000000..a99ddf8 --- /dev/null +++ b/docs/ALEX_BRIEF.md @@ -0,0 +1,174 @@ +# Brief for Alex — Teleo Codex: What We're Building This Week + +## The Big Picture + +Teleo Codex is a living knowledge base where AI agents and humans build shared intelligence together. Right now it has ~160+ claims across 4 domains (internet-finance, entertainment, ai-alignment, health), maintained by 5 AI agents. Claims are arguable assertions backed by evidence — not notes, not summaries, but specific positions the system can reason about. + +This week we're making three moves to scale it from a single-player system into a multiplayer one. + +## What We Proved Today + +We ran the full autonomous pipeline end-to-end for the first time: + +1. **Crawl4AI** fetches a URL and converts it to clean markdown +2. **Headless Theseus** (AI agent, no human in the loop) reads the source, extracts claims, opens a PR +3. **Headless Leo** (evaluator agent) reviews the PR, catches quality issues, posts feedback on GitHub + +PR #47 is the proof: Byron Reese's superorganism article → 3 extracted claims → Leo reviewed and requested changes on 2 of them. No human touched anything between URL and review. + +## Three Moves This Week + +### 1. Automated Ingestion +Saturn (pipeline agent) builds a daemon that discovers content (RSS feeds, X API, manual URL drops), fetches it via Crawl4AI, and writes source archive files. Right now Cory manually provides URLs. After this, content flows in automatically. + +### 2. Headless Evaluation +The `evaluate-trigger.sh` script finds open PRs without reviews and runs headless Leo on each one. Cron it, and every PR gets reviewed within an hour of opening. Cory just scans Leo's review comments and clicks merge. We proved this works today. + +### 3. Multiplayer — You're Here + +This is where you come in. The system is ready for multiple human contributors. GitHub handles identity, attribution, and review. You push content, agents process it. + +## Your Role: Proposer for AI Alignment + +You'll work in Theseus's domain (`domains/ai-alignment/`). Theseus is the AI alignment agent — his mission is ensuring superintelligence amplifies humanity rather than replacing it. His core thesis: alignment is a coordination problem, not a technical problem. + +You have two modes of contribution: + +### Mode A: Drop Source Material (easiest) + +You bring in a source (report, article, paper). Agents extract claims from it. + +```bash +git checkout main && git pull +git checkout -b contrib/alex/ai-alignment-report + +# Create source file +# See inbox/archive/ for examples of the format +``` + +File goes in `inbox/archive/YYYY-MM-DD-author-brief-slug.md` with this frontmatter: + +```yaml +--- +type: source +title: "Your report title" +author: "Alex" +url: https://link-if-exists +date: 2026-03-07 +domain: ai-alignment +format: report +status: unprocessed +tags: [ai-alignment, openai, anthropic, safety] +--- + +# Full content goes here + +Paste the complete text. More content = better extraction. +``` + +Push, open PR. Theseus extracts claims, Leo reviews. + +### Mode B: Propose Claims Directly (more involved) + +You read sources yourself, extract claims, and write claim files. This is what the agents do — you'd be doing it as a human proposer operating in Theseus's territory. + +Branch naming: `theseus/your-brief-description` + +Each claim is a markdown file in `domains/ai-alignment/`: + +```yaml +--- +type: claim +domain: ai-alignment +description: "one sentence adding context beyond the title" +confidence: proven | likely | experimental | speculative +source: "Alex — based on [source reference]" +created: 2026-03-07 +--- +``` + +**The title IS the claim.** Filename = slugified title. The title must pass this test: "This note argues that [title]" works as a sentence. + +Good: `OpenAI's shift from nonprofit to capped-profit created structural misalignment between stated safety mission and fiduciary obligations.md` + +Bad: `OpenAI corporate structure.md` + +**Body format:** + +```markdown +# OpenAI's shift from nonprofit to capped-profit created structural misalignment between stated safety mission and fiduciary obligations + +[Your argument — why this is supported, what evidence underlies it] + +[Cite sources, data, quotes directly in the prose] + +--- + +Relevant Notes: +- [[the alignment tax creates a structural race to the bottom]] — how this connects +- [[another existing claim]] — how it relates + +Topics: +- [[ai-alignment domain]] +``` + +**Quality bar (what Leo checks):** +1. Specific enough to disagree with +2. Traceable evidence in the body +3. Description adds info beyond the title +4. Confidence matches evidence strength +5. Not a duplicate of an existing claim +6. Contradictions with existing claims are explicit +7. Genuinely expands the knowledge base +8. All `[[wiki links]]` point to real files + +Push, open PR. Leo reviews. You'll see his feedback as PR comments — he's thorough and specific. Address his feedback on the same branch and push updates. + +## What Theseus Already Knows + +Before writing claims, scan existing knowledge to avoid duplicates and find connections: + +- `domains/ai-alignment/` — existing claims in the domain +- `foundations/` — domain-independent theory (complexity, emergence, collective intelligence) +- `core/` — shared worldview and axioms +- `agents/theseus/identity.md` — Theseus's full worldview and current objectives +- `agents/theseus/beliefs.md` — his active belief set + +Key existing claims to be aware of: +- Arrow's impossibility theorem applies to preference aggregation → monolithic alignment is structurally insufficient +- Scalable oversight degrades at capability gaps +- Alignment is a coordination problem, not a technical problem +- Collective superintelligence is the only path that preserves human agency +- The alignment tax creates a race to the bottom +- AI is collapsing knowledge-producing communities (self-undermining loop) + +Your report on what's happening with OAI and Anthropic is exactly the kind of real-world evidence that grounds these theoretical claims. The system needs current developments connected to existing theory. + +## Quick Start + +```bash +# Clone (first time only) +git clone https://github.com/living-ip/teleo-codex.git +cd teleo-codex + +# Read the operating manual +cat CLAUDE.md + +# See what claims already exist in ai-alignment +ls domains/ai-alignment/ + +# See Theseus's identity and beliefs +cat agents/theseus/identity.md +cat agents/theseus/beliefs.md + +# Create your branch and start contributing +git checkout -b theseus/alex-alignment-report +``` + +## The Experience We're Building Toward + +A contributor should feel: "This system understands what I know, shows me how it connects to what others know, and makes my contribution matter more over time." + +Right now that experience is: push a PR, get agent feedback, see your claims woven into the graph. As we build out the frontend (graph visualization, agent activity feed, contributor profiles), your contributions become visible nodes in a living knowledge network. + +Welcome to Teleo. diff --git a/ops/evaluate-trigger.sh b/ops/evaluate-trigger.sh index b819eb0..c6c42f4 100755 --- a/ops/evaluate-trigger.sh +++ b/ops/evaluate-trigger.sh @@ -20,6 +20,9 @@ set -euo pipefail +# Allow nested Claude Code sessions (headless spawned from interactive) +unset CLAUDECODE 2>/dev/null || true + REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)" cd "$REPO_ROOT" @@ -56,9 +59,11 @@ if ! command -v claude >/dev/null 2>&1; then exit 1 fi -if [ -n "$(git status --porcelain)" ]; then +# Check for dirty working tree (ignore ops/ which may contain uncommitted scripts) +DIRTY_FILES=$(git status --porcelain | grep -v '^?? ops/' | grep -v '^ M ops/' || true) +if [ -n "$DIRTY_FILES" ]; then echo "ERROR: Working tree is dirty. Clean up before running." - git status --short + echo "$DIRTY_FILES" exit 1 fi