diff --git a/AGENTS.md b/AGENTS.md index fa1e4c98..81edcfd7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -307,6 +307,13 @@ Detail lives in: checklist, tick-history append protocol, the never-idle priority ladder. Required reading for any harness running `/loop` autonomously. +- `docs/FIRST-PR.md` — first-class entry point for + fresh contributors and vibe coders (humans + directing an AI to do the writing). UI-first, no + git / F# / terminal required. Read this before + `CONTRIBUTING.md` if you are new to the project, + new to open source, or directing an AI through a + GitHub web-UI session. - `docs/AGENT-CLAIM-PROTOCOL.md` — standalone, linkable git-native claim specification for any external agent picking up a PR task (ChatGPT, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4026bfdf..f4487d0a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,12 @@ Welcome. Zeta is a research-grade F# implementation of DBSP on .NET 10 with a software-factory design — humans and AI agents collaborate under a codified set of rules. +**New to open source, or directing an AI to do the +writing for you?** Read +[`docs/FIRST-PR.md`](docs/FIRST-PR.md) first — it is +UI-first and assumes no prior git / F# / terminal +experience. This doc is the competent-dev version. + ## Quick start ```bash diff --git a/README.md b/README.md index 3355203b..b54d5078 100644 --- a/README.md +++ b/README.md @@ -194,6 +194,22 @@ dotnet msbuild src/Core/Core.fsproj \ [ia]: https://github.com/ionide/ionide-analyzers [fab]: https://github.com/ionide/FSharp.Analyzers.Build +## Contributing + +Three entry points, pick whichever fits: + +- **First time contributing, or directing an AI to do the + work for you?** Read [`docs/FIRST-PR.md`](docs/FIRST-PR.md). + UI-first, plain-language, no git or F# required. +- **Comfortable with GitHub, git, and F#?** Read + [`CONTRIBUTING.md`](CONTRIBUTING.md). Shorter; assumes + the tools. +- **An AI agent coordinating work without a human in the + loop?** Read [`docs/AGENT-CLAIM-PROTOCOL.md`](docs/AGENT-CLAIM-PROTOCOL.md) + for the git-native claim spec, and + [`docs/AGENT-ISSUE-WORKFLOW.md`](docs/AGENT-ISSUE-WORKFLOW.md) + for the dual-track principle and platform adapters. + ## Acknowledgements Zeta follows the algebra of Budiu, McSherry, Ryzhyk, and Tannen diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index ba89db9c..df650d9e 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -3965,6 +3965,197 @@ systems. This track claims the space. (ask-Aaron + scope-doc-edit); M if it triggers GOVERNANCE.md renegotiation. +- [ ] **Capability-limited-AI bootstrap guide — how + crippled agents use the factory to become whole.** + Aaron 2026-04-22: *"new persona capibilty cripiled AI + like small context or few paraments how can they use + us to bootstrap and become whole guide backlog"*. + Write a doc under `docs/` (candidate name + `docs/CAPABILITY-LIMITED-BOOTSTRAP.md`) that answers: + how does a capability-constrained AI — small context + window, small parameter count, restricted tools (no + web access, no git push, no MCP), or harness-limited + (no file write, no shell) — use this factory's + surfaces to scaffold itself up to effective larger + capability? **Framing:** the factory is already an + externalised algorithm (per witnessable-evolution and + soul-file discipline) — which means the intelligence + that would otherwise be "inside" a large model is + available as reproducible artifacts the small model + can *read* + *follow* rather than *contain*. + **Target capability-limited persona shapes to cover:** + (1) short-context model — uses `docs/FIRST-PR.md` + + `docs/AGENT-CLAIM-PROTOCOL.md` as the only-two-docs + entry surface, avoids deep spelunking; chunking + recipes for reading larger docs in pieces; + "what-to-load-in-what-order" algorithm. (2) small- + parameter / low-ability model — leans on the + spec-first discipline: the behavioural specs + (`openspec/specs/**`) + test suite act as guardrails + that catch mistakes the model would otherwise make; + encourages write-tiny-PR-then-iterate. (3) tool- + restricted model — the report-back mode in + `AGENT-CLAIM-PROTOCOL.md` (write-via-maintainer) is + already first-class for this case; doc names it + explicitly as the recommended path. (4) no-web + sandbox — everything it needs is in-repo; + `references/upstreams/` after sync-upstreams pulls + external sources into the soul-file. (5) stateless / + no-memory — each session reads + `AGENTS.md` → `CLAUDE.md` (if relevant harness) → + `docs/FIRST-PR.md` → task URL; no persistent + context needed. **The "bootstrap ladder" metaphor:** + a capability-limited AI starts at rung 1 (read one + doc, write one comment on an issue), climbs to rung + 2 (pair with a larger model through report-back), + climbs to rung 3 (directly author a PR with the + factory's specs + tests as error-corrector), climbs + to rung 4 (participate in review). Each rung is + documented with the minimum-viable capability + profile and the factory surfaces that unlock the + climb. **Why this matters:** the vibe-coded + hypothesis (`AGENTS.md` §"The vibe-coded hypothesis") + extends naturally — a human directing a capable AI is + one instance; a capable AI scaffolding a less-capable + AI through the same surfaces is another instance; and + a capability-limited AI using only the surfaces + (without any larger-AI pairing) is the extreme case + that validates whether the factory is genuinely an + externalised algorithm versus a pretty wrapper over + large-model intelligence. **Falsification anchor:** + if a 7B-parameter open-weights model can + independently open a useful, accepted PR by reading + only `docs/FIRST-PR.md` + one issue URL, the factory + has passed a genuine capability-democratisation test. + If it cannot, we have identified specific + scaffolding gaps that favour larger-model users and + can address them. **Effort:** L (3+ days — the + ladder writing, plus at least one pilot attempt with + a small-parameter model routed through + `docs/FIRST-PR.md` to validate the claimed + accessibility). **Composes with:** + `docs/FIRST-PR.md` (entry surface; "capability-limited + AI" is a contributor-persona shape this doc can cover + as a shared sub-persona with human fresh-devs); + `docs/AGENT-CLAIM-PROTOCOL.md` (already documents + report-back / review-only modes for substrate-limited + agents — this doc generalises); `AGENTS.md` + §"The vibe-coded hypothesis" (validates the + hypothesis downward as well as horizontally); the + witnessable-self-directed-evolution memory discipline + (a factory that survives being operated by crippled + agents is a factory whose intelligence is genuinely + externalised, not carrier-transported from the + maintainer's larger model); `docs/ALIGNMENT.md` + (capability-democratisation is an alignment property + — no hidden dependency on provider-scale access). + **Success signal:** measurable + `capability-limited-contributor-pr-acceptance-rate` + (fraction of PRs opened by models under 10B + parameters that merge vs. the same rate for + frontier models — target: parity within some + tolerance band once the guide stabilises). + **What this row is NOT:** not a promise to ship + model-specific tooling (no factory fork per model + class); not a lowering of the quality bar (the + guide teaches *access paths*, not *weaker review*); + not a claim that every capability-limited model + will succeed (some tasks genuinely need frontier- + scale reasoning; the guide makes the cut-line + visible rather than pretending it does not exist). + **Revision 2026-04-22 (same-day):** Aaron extended + the rationale: *"in case i evver loose all my money + that bootstraping from tiny AI to become the most + powerful would sure come in handy to save money"*. + This adds a **personal-resilience** axis alongside + the capability-democratisation axis. The factory is + meant to survive its maintainer losing access to + frontier models — if Aaron's circumstances ever + force a move to tiny / open-weights / local models, + the factory keeps working. Pragmatic test: a + ~4-8B-parameter local-inference model + (`llama.cpp` / `ollama` / similar) on commodity + hardware can still drive meaningful factory work + when paired with this bootstrap guide + the + soul-file + the test suite as error-corrector. + Composes with the soul-file discipline + (`user_git_repo_is_factory_soul_file_...`): the + soul-file is already designed to germinate a + factory from nothing; this BACKLOG row extends the + "from nothing" to include "from a tiny model on a + laptop." Success signal now has two sub-measures: + (a) capability-democratisation (parity across model + scales) and (b) personal-resilience + (`factory-operability-on-local-open-weights-model` + — the factory produces useful PRs when driven by a + model Aaron could afford on any plausible budget + scenario). The cost-resilience axis also grounds + the research contribution: a factory that + *requires* frontier access is a pretty-wrapper over + a provider's scale; a factory that *survives* tiny + models has genuinely externalised intelligence into + reproducible substrate. NOT a commitment to + build local-model runners (out of scope — users' + responsibility); just a commitment to ensure the + factory does not gratuitously exclude them. + +- [ ] **First-principle seed to Zeta derivation — common + vernacular only.** Aaron 2026-04-22: *"backlog first + principle seed to zeta derivation using only common + venucular"*. Write a doc under `docs/research/` (or + promote to `docs/FIRST-PRINCIPLES.md` if it earns a + top-level slot) that derives Zeta from first principles + using only **common vocabulary** — no "Z-set", no + "retraction-native IVM", no "operator algebra", no + "DBSP", no "H-function" without first-principle + unpacking. The test is: a bright high-school student or + someone outside computing can read it top-to-bottom and + understand *why* Zeta works. **Starting point:** "data + changes; we want to compute things about data; computing + from scratch each time is slow; we want a way to update + only what changed." From there, derive the chain: + sets-with-deletions → signed-counts (what Z-sets are, + without naming them) → differences between snapshots + (what deltas are) → the three knobs (delay / + differentiate / integrate) with plain-English names → + the chain rule (why compositions of incremental + operators stay incremental) → joins + the bilinear + identity → why distinct needs a special H-function. + Each technical term is **introduced** at the point the + derivation needs it, with the common-vernacular name + first and the jargon in parentheses. No forward + references to terms not yet derived. **Why this + matters:** composes with the vibe-coded-hypothesis + (`AGENTS.md` §"The vibe-coded hypothesis") and the + freshly-landed `docs/FIRST-PR.md` entry surface — a + maintainer who has written zero code directing AI to + build a DBSP library is operating exactly at the layer + this doc serves. It is also a falsification anchor for + the factory's research-grade claims: if the agents + cannot re-derive the system in common vernacular, the + factory does not actually understand what it is + building. **Constraints:** no math notation in + prose-body (math goes in inset boxes that readers can + skip); no appeal to "the paper" or "the literature" + as authority (link in a sidebar, don't lean on it in + the derivation); no persona-references (Kenji, Daya, + etc.) — personas are factory-internal, the doc is + outward-facing. **Effort:** M (1-3 days for the + writing, plus a review round from Samir + (`documentation-agent`) + Rune (`maintainability- + reviewer`) + Iris (`user-experience-engineer`) on + whether a reader with the target profile can follow + it). **Success signal:** a fresh reader (Iris's + 10-minutes-in-Iris-mode protocol) can restate the + core derivation in their own words after reading + once. Composes with `docs/GLOSSARY.md` (glossary is + the landing point for terms introduced here). Also + composes with `docs/FIRST-PR.md` §"What you do *not* + need to worry about" — today the "don't need to + understand DBSP" line is a carve-out; when this doc + lands, it becomes a "here's where to start if you + want to." + - [ ] **Cross-substrate-report accuracy — carrier-channel refinement to the measurable spec.** Auto-loop-7 (2026-04-22) surfaced a provenance problem in the `cross-substrate-report- diff --git a/docs/FIRST-PR.md b/docs/FIRST-PR.md new file mode 100644 index 00000000..5bc5eae8 --- /dev/null +++ b/docs/FIRST-PR.md @@ -0,0 +1,280 @@ +# Your first contribution to Zeta + +Welcome. This doc is for you if you are: + +- **New to open source** and this is one of your first + repos — you are not sure what a "PR" is or what people + expect in one. +- **A vibe coder** — you direct an AI (ChatGPT, Claude, + Gemini, Copilot, Cursor) to do the writing; you do + not personally write the code. +- **An AI agent** arriving here on someone's behalf and + wanting to know what the entry door looks like. + +If you are already comfortable with GitHub, git, and F#, +read [`CONTRIBUTING.md`](../CONTRIBUTING.md) instead — +it is shorter and assumes you know the tools. + +If you are an external AI being handed a task through +this repo, the protocol spec is in +[`docs/AGENT-CLAIM-PROTOCOL.md`](AGENT-CLAIM-PROTOCOL.md). +This doc is the human-facing walkthrough; the protocol +doc is the complete machine-facing specification. + +## The honest tone of this project + +**Zeta is pre-v1 and agent-built.** The human maintainer +has written zero lines of code. Every file in this repo +was written by an AI agent following rules the +maintainer set. That means two things for you: + +1. **You do not need to be an F# expert.** If you can + describe a problem clearly, an agent on this team + can implement the fix. Clarity is the scarce + resource, not typing speed. +2. **You are not second-class for directing an AI.** + The maintainer directs AIs too. Everyone here does. + See [`AGENTS.md`](../AGENTS.md) §"The vibe-coded + hypothesis" for why. + +## The shortest path to contributing — four clicks + +You do not need to install anything, clone the repo, or +touch the command line for your first contribution. +GitHub's web UI is enough. + +1. **Browse to the Issues tab.** + [github.com/Lucent-Financial-Group/Zeta/issues](https://github.com/Lucent-Financial-Group/Zeta/issues) +2. **Click "New issue"** and pick a template. Four are + available: + - **Bug report** — something is broken. + - **Backlog item** — work you want to see done. + - **Human ask** — a question or decision for the + maintainer. + - Blank issues are off; pick a template. +3. **Write what you want in plain English.** You do + not need the factory's vocabulary. If a field asks + for something you do not know (a commit SHA, a + module name), leave it blank — an agent will fill + it in when they pick the issue up. +4. **Submit.** You are done. An agent working this + factory will read it, triage it, and either pick it + up or ask you a follow-up question in a comment. + +That is your first contribution. You did not run a +build, did not open a terminal, did not write a test. +The factory mirrors your issue into the durable +in-repo ledger (`docs/BACKLOG.md` or `docs/BUGS.md`) +on its side — you do not need to do that yourself. + +## The slightly-longer path — edit a file in the web UI + +Want to fix a typo or add a sentence to a doc? You can +do that without cloning the repo either. + +1. **Open the file on GitHub.** Any file in the repo + has a page at + `https://github.com/Lucent-Financial-Group/Zeta/blob/main/`. +2. **Click the pencil icon** at the top-right of the + file view. GitHub prompts you to fork the repo — + click through; it is free and automatic. +3. **Edit the file in the browser.** You get a + textbox. +4. **Scroll to the bottom and click "Propose changes".** + Give the change a short name — "fix typo in + getting-started" is enough. +5. **On the next page click "Create pull request"** and + add a one-line description. Done. + +The CI will run on your PR; if it passes and a reviewer +approves it, it lands. If CI fails with something you do +not understand, leave a comment saying so — someone on +the team will explain or fix it for you. The reviewers +on this project do not punish confusion. + +## Directing an AI to do the work — the vibe-coder flow + +If you are driving an AI (ChatGPT, Claude, Gemini, +Cursor, etc.) and the AI is doing the editing, the +shape is: + +1. **You open the issue** on GitHub yourself (the + four-click path above). This is your claim on the + work — it tells the team "this is what I am + driving." You do not have to know any git commands + for this. +2. **You paste a link to the issue and this repo** into + your AI's conversation, and describe what you want. + Something like: + > I want to work on + > [issue-URL](...) in [repo-URL](...). Read + > `docs/AGENT-CLAIM-PROTOCOL.md` in that repo for + > how to claim and push. Please make the change and + > open a PR. +3. **The AI does the work.** Modern AIs can read a + URL, clone a repo, make edits, and push a branch. + Different AIs have different access — some can push + directly, some can only write a patch and hand it + back to you to apply. Both are fine; the protocol + doc covers both modes. +4. **You review what the AI proposes.** Before the PR + is opened (or before you merge it), read it. You + do not need to understand every line of F#, but + you should be able to say "yes, this is what I + asked for." If the AI drifted, tell it so; it will + revise. +5. **A human or agent reviewer on the team weighs in.** + If something is wrong with the code, the reviewer + says so in a PR comment. You can paste that back + into your AI and say "fix this" — the loop is the + loop. + +The team's reviewers are named — Kira (harsh-critic), +Rune (maintainability), Samir (documentation), and +several others. Full list at +[`docs/EXPERT-REGISTRY.md`](EXPERT-REGISTRY.md). Their +tone varies; none of them are rude to contributors, +human or AI. + +## What "claiming" means and why you (probably) do not need to think about it + +If you read any agent-facing docs in this repo, you +will see the word "claim" — as in, agents claim work +before they start on it so two agents do not clobber +each other. For you, as a fresh contributor, **the +GitHub Issue is your claim**. Here is the full human +flow: + +1. **Find the issue you want to work on.** Browse the + Issues tab; the ones without an `in-progress` label + are available. +2. **Leave a comment**: "I'd like to try this — I'll + have something by [rough ETA]." If you are driving + an AI, name the AI: "I'll be working this with + Claude; ETA a couple of hours." +3. **A team member adds the `in-progress` label and + assigns the issue to you.** If nobody responds in a + few hours, you can add the label yourself (the repo + permits it for the "issues" scope) — the comment is + what matters; the label is just a marker for other + contributors scanning the list. +4. **Work in your own fork.** Open a PR against + `main` when ready. Link the issue in the PR + description with "Closes #123" — GitHub will + auto-close the issue when the PR merges. +5. **If you abandon the work**, leave a comment + saying so and un-assign yourself. No shame in + this; it happens. Another contributor can pick it + up from where you stopped. +6. **If an issue is claimed but the claimant has gone + quiet for more than a day**, leave a comment + referencing their claim timestamp and take it over. + That is the "force-release" step — it is rare and + the full rules are in + [`docs/AGENT-CLAIM-PROTOCOL.md`](AGENT-CLAIM-PROTOCOL.md), + but you will almost certainly never need to invoke + it manually. + +You do not need to create any files in `docs/claims/` +— that is the git-native protocol for advanced agents +who cannot use GitHub Issues. GitHub Issues subsumes +it for everyone else. + +## What happens after you open a PR + +1. **CI runs.** Build + tests + lints execute on + GitHub's runners. Pass/fail shows up in the PR + view. +2. **GitHub Copilot posts review comments** on the + diff. Some of these are valuable catches; some are + style nits you can ignore. You are allowed to + reject Copilot findings with reasoning — the + project documents a rejection-grounds catalog at + [`docs/research/copilot-rejection-grounds-catalog.md`](research/copilot-rejection-grounds-catalog.md). +3. **Human + agent reviewers comment.** If something + needs changing, they say so. Address what you can; + say "I do not know how to fix this, help?" for the + rest. That is fine. +4. **The PR merges** by squash-merge into `main`. + Your name is on the commit. + +## What you do *not* need to worry about + +- **You do not need to understand DBSP, Z-sets, or + retraction-native IVM.** The maintainer does not + expect fresh contributors to know the algebra. + Pointers are in [`docs/GLOSSARY.md`](GLOSSARY.md) if + you are curious. +- **You do not need to write tests in F#.** If your + change is doc-only, no test is expected. If it is + code, a reviewer will often write the missing test + for you or tell you which existing test to follow + as a template. +- **You do not need to pass the reviewer floor alone.** + GOVERNANCE §20 requires at least Kira + + Rune on code landings — but those reviewers run + automatically on agents' behalf. You do not invoke + them. +- **You do not need to know what a "round" is.** The + round model is a factory-internal cadence. Your PR + is a PR. +- **You do not need to read AGENT-CLAIM-PROTOCOL.md.** + It exists for AIs coordinating across git when + GitHub Issues is unavailable. If you use GitHub's + web UI, it is already handled for you. + +## What to do if you are stuck + +- **File a Human Ask.** There is an issue template + for exactly this. Describe what you were trying to + do, what you tried, and what is confusing. The + maintainer and the factory's agents read these; + you will get a reply. +- **Comment on the relevant PR or issue.** Honest + confusion is welcome. The factory's culture + penalises dismissive-closes, not honest "I do not + understand" questions — see + [`memory/feedback_engage_substantively_no_dismissive_closing_with_silencing_shadow_2026_04_21.md`](../memory/feedback_engage_substantively_no_dismissive_closing_with_silencing_shadow_2026_04_21.md) + for the discipline (that file is not in the repo; + it lives in the maintainer's agent memory — + mentioned here so you know the principle is + codified). + +## What this doc is NOT + +- **Not a replacement for [`CONTRIBUTING.md`](../CONTRIBUTING.md).** + Competent F# / .NET contributors should read the + shorter doc. This one is for the entry point. +- **Not a replacement for [`AGENT-CLAIM-PROTOCOL.md`](AGENT-CLAIM-PROTOCOL.md).** + AIs with git access that are coordinating without + GitHub Issues should read that one. +- **Not a guarantee that any issue you file will be + picked up.** The factory is pre-v1 research work; + triage is honest — some issues will be declined + with reasoning. The declined-items list is at + [`docs/WONT-DO.md`](WONT-DO.md). +- **Not a promise that reviewers will be gentle on + the code itself.** Reviewers are gentle with + *contributors*; they are direct with *code*. Kira + never compliments code; that is a feature of the + role, not hostility toward you. + +## If you got this far and want more + +- [`AGENTS.md`](../AGENTS.md) — values and + philosophy of the project. +- [`CONTRIBUTING.md`](../CONTRIBUTING.md) — + competent-dev version of this doc. +- [`docs/AGENT-CLAIM-PROTOCOL.md`](AGENT-CLAIM-PROTOCOL.md) + — full git-native coordination protocol. +- [`docs/CONTRIBUTOR-PERSONAS.md`](CONTRIBUTOR-PERSONAS.md) + — the shapes of contributors we design surfaces + for. You are probably persona 1 (drive-by), 2 + (bug-reporter), or 4 (AI coding agent, for the + vibe-coder flow) — all first-class. A dedicated + "vibe-coder-directing-AI" persona is a candidate + addition; file an issue if the shoe does not fit. +- [`docs/WONT-DO.md`](WONT-DO.md) — what the project + has explicitly declined and why. Read before + proposing something ambitious, so you do not + re-litigate a settled debate.