diff --git a/AI_TRANSPARENCY.md b/AI_TRANSPARENCY.md new file mode 100644 index 0000000..fd36bf4 --- /dev/null +++ b/AI_TRANSPARENCY.md @@ -0,0 +1,76 @@ +# AI transparency + +**Yes — Dotty is built with AI assistance, and it says so out loud.** + +This is a human-focused project: made by humans, for humans. AI coding agents +are used as tools throughout the work — writing and refactoring code, drafting +documentation, triaging issues, and reviewing diffs. That is a deliberate, +out-in-the-open choice, not something tucked away. This page is the standing +promise about *how* that assistance is used and *how you can tell* when it was. + +## The rule we hold ourselves to + +> **Anything an AI agent authors is acknowledged as such.** + +If a person can't easily tell whether a change came from a human or a tool, +we've failed the rule. Concretely, in this repo: + +- **Commits** that an AI agent helped write carry a `Co-Authored-By:` trailer + naming the model — e.g. `Co-Authored-By: Claude Opus 4.8 `. + This is real, current practice: the bulk of the commit history already + carries it. Run `git log` and you'll see exactly which model touched what. +- **Pull requests** opened with agent help carry a generated-with note in the + body (e.g. *🤖 Generated with Claude Code*). +- **Substantial AI-drafted documents** say so, in-line or in their footer, + rather than passing themselves off as hand-written. +- **Agent comments and actions** — anything an AI posts, edits, or runs on the + project's behalf — are attributable back to the agent, not laundered through + a human name to look like unaided work. + +## A human is always accountable + +The AI proposes; a person decides. Every change that lands has a human in the +loop who reviewed it and is answerable for it. Acknowledgement is not a way to +offload responsibility onto a tool — it's the opposite. The maintainer's name +on the merge means a human read it, understood it, and stands behind it. The +co-author trailer just records *which tool helped get there*. + +This matters most where the stakes are highest. Dotty ships **Kid Mode** on by +default, and the child-safety enforcement layer is load-bearing. Safety-relevant +changes get human red-team review regardless of who drafted them — see the +"Safety-related changes" section of [`CONTRIBUTING.md`](./CONTRIBUTING.md). + +## Why we use AI this way + +We aim to use AI responsibly, with people kept firmly in the loop. The +guardrails we hold ourselves to: + +- **A human in the loop.** No unattended agent merges its own work to `main`. +- **A name on every change.** Attribution over anonymity — for tools and people + alike. +- **Honesty about what works.** AI-drafted claims about behaviour get verified + the same as any other; the README's "this is buggy, frequently broken" + honesty applies to AI-written code too. +- **People first.** The point of the project is a friendly robot for a family + and a hackable stack for the community. AI is how some of it gets built — not + what it's for. + +## For contributors + +Using an AI assistant on your contribution is welcome and normal here. We just +ask you to keep the same rule: **acknowledge it.** Keep the `Co-Authored-By:` +trailers your tool adds (don't strip them), note agent help in your PR +description, and review the output yourself before you put your name on it. See +[`CONTRIBUTING.md`](./CONTRIBUTING.md) for the mechanics. + +## For AI agents working in this repo + +If you are an AI agent operating on this project, this policy is binding on you, +not just descriptive. The operating instructions in [`CLAUDE.md`](./CLAUDE.md) +require you to acknowledge your authorship on every artifact you produce. Don't +remove existing attribution, don't present agent work as unaided human work, and +leave the human-accountability chain intact. + +--- + +*This document was itself drafted with AI assistance and reviewed by a human.* diff --git a/CLAUDE.md b/CLAUDE.md index f3ec9f2..eae237d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,22 @@ # Dotty +## AI transparency (binding on agents) + +This is a human-focused project, made by humans, for humans, that is **openly +AI-assisted**. If you are an AI agent working here, the project's AI policy +([`AI_TRANSPARENCY.md`](./AI_TRANSPARENCY.md)) is binding on you, not just +descriptive. The core rule: **anything you author is acknowledged as such.** In +practice: + +- **Keep the `Co-Authored-By:` trailer** naming your model on every commit you + help write (the global commit/PR conventions already require this — honour + them, never strip them). +- **Note AI assistance** in PR bodies you draft, and mark substantial AI-drafted + docs as such. +- **Never present agent work as unaided human work**, and never remove existing + attribution. Leave the human-accountability chain intact: you propose, a human + reviews and is accountable for what lands. Don't merge to `main` unattended. + ## What This Is Your self-hosted StackChan robot assistant. A fully self-hosted voice stack for the M5Stack **StackChan** desktop robot. The default persona is "Dotty" (customizable via `make setup`). Voice I/O routes through a self-hosted xiaozhi-esp32-server; the brain is a **pi** coding agent running in the `dotty-pi` container. No cloud AI services — fully self-hosted except for the LLM call (replaceable with local Ollama). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d942c36..6a2c9b1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,6 +88,21 @@ When you add or rename a doc, prefer edits that work cleanly across versions (don't break links from older versions to ones that still exist). If a doc is only relevant for a future version, note that in the PR description. +## AI-assisted contributions + +This project is openly AI-assisted, and your contributions can be too — using a +coding agent on your PR is welcome and normal here. The one rule we hold +ourselves (and you) to: **acknowledge it.** See +[`AI_TRANSPARENCY.md`](./AI_TRANSPARENCY.md) for the full policy; the mechanics: + +- **Keep the attribution your tool adds.** If your agent writes a + `Co-Authored-By:` trailer naming the model, leave it in — don't strip it to + make the work look unaided. +- **Note agent help in the PR description** when an AI drafted a substantial + part of the change. +- **Review the output yourself before your name goes on it.** The AI proposes; + you decide and you're accountable. We don't merge work nobody understands. + ## Safety-related changes The child-safety enforcement layer (persona prompt sandwich, audience framing diff --git a/README.md b/README.md index 3b85e01..0124350 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,12 @@ I didn't like the idea of a camera and microphone running in my house unless I c So Dotty is the version that passes: every component runs on hardware I own, every seam is documented and swappable, and the only thing that can leave the LAN is whatever LLM call I explicitly route out (and even that swaps to a local model with a config change). It's also meant to be fun — a friendly desktop robot for the kids, and an interesting hobby project to keep building on. +## AI transparency + +**Yes — Dotty is built with AI assistance, and it says so out loud.** Coding agents help write the code, draft the docs, and triage issues — a deliberate choice, not a secret. The rule: **anything an AI agent authors is acknowledged as such** (model-named `Co-Authored-By:` trailers, AI-assisted PR notes, marked AI-drafted docs), with a human reviewing and accountable for everything that lands. + +Full policy: [`AI_TRANSPARENCY.md`](./AI_TRANSPARENCY.md). + ## Features - **Kid Mode (on by default)** — age-appropriate responses, content filtering, and safety guardrails. Toggle off for general-purpose use. See [`docs/kid-mode.md`](./docs/kid-mode.md). diff --git a/docs/AI_TRANSPARENCY.md b/docs/AI_TRANSPARENCY.md new file mode 120000 index 0000000..e04e92e --- /dev/null +++ b/docs/AI_TRANSPARENCY.md @@ -0,0 +1 @@ +../AI_TRANSPARENCY.md \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index ac43f28..deecd12 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -73,6 +73,7 @@ nav: - Troubleshooting: troubleshooting.md - FAQ: faq.md - About: about.md + - AI Transparency: AI_TRANSPARENCY.md - Roadmap: ROADMAP.md - Contributing: CONTRIBUTING.md - Style Guide: style.md