From d39f7cdeebe9693d07aeba66c1465a8f2f6c5016 Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Wed, 22 Apr 2026 02:35:37 -0400 Subject: [PATCH 1/7] =?UTF-8?q?docs:=20land=20AGENT-CLAIM-PROTOCOL.md=20?= =?UTF-8?q?=E2=80=94=20git-native=20claim=20spec=20for=20external=20agents?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Standalone, linkable doc so a maintainer can hand one URL (plus the task URL) to an external agent — ChatGPT, Codex, Gemini, Deep Research, human contributor on another harness — and have them onboard from zero context. - New doc at docs/AGENT-CLAIM-PROTOCOL.md with: - Paste-ready hand-off template (one URL + one task + one mode-name) - Five-step TL;DR (clone/pull -> check -> claim -> work -> release) - Five mode sections: Deep Research (read-only, no claim), Codex sandbox (PR-write), direct-commit (maintainer), review/advisory (no claim), report-back / write-via-maintainer (no claim; maintainer commits the artifact) - Claim file shape (docs/claims/.md) with template - Slug rules, session identity, lifecycle (claim / progress / release) - Conflict resolution (merge = coordination), stale-claim force-release - Scope discipline section (claim code not identity; facts not framings; scope the maintainer asked for) - Platform adapters (GH Issues / Jira / Linear) — optional mirrors - "What this protocol does NOT do" block - docs/AGENT-ISSUE-WORKFLOW.md §"The claim / lock protocol" now cross-references AGENT-CLAIM-PROTOCOL.md as the git-native substrate specification; adapter table git-native row points to docs/claims/.md mechanism. References section adds the pointer. - AGENTS.md §"Contributor required reading" adds both AGENT-CLAIM-PROTOCOL.md (one-link external-agent onboarding) and AGENT-ISSUE-WORKFLOW.md (dual-track principle + adapter choice) as explicit required reading — they were only discoverable transitively before. UX geared to observed external-agent responses: ChatGPT Deep Research and Gemini review patterns both surface honest substrate-limits ("I can't push to git directly") followed by structured output artefacts. The report-back mode is first-class so agents in that shape have a welcome, not a gate. Co-Authored-By: Claude Opus 4.7 --- AGENTS.md | 13 + docs/AGENT-CLAIM-PROTOCOL.md | 490 +++++++++++++++++++++++++++++++++++ docs/AGENT-ISSUE-WORKFLOW.md | 15 +- 3 files changed, 515 insertions(+), 3 deletions(-) create mode 100644 docs/AGENT-CLAIM-PROTOCOL.md diff --git a/AGENTS.md b/AGENTS.md index 2ce3a47d..9617d2cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -337,6 +337,19 @@ Detail lives in: checklist, tick-history append protocol, the never-idle priority ladder. Required reading for any harness running `/loop` autonomously. +- `docs/AGENT-CLAIM-PROTOCOL.md` — standalone, + linkable git-native claim specification for any + external agent picking up a PR task (ChatGPT, + Codex, Gemini, Deep Research, human + contributor). Hand this URL plus a task URL to an + external agent as a one-link onboarding briefing. + Platform adapters (GH Issues / Jira / Linear) + live in `docs/AGENT-ISSUE-WORKFLOW.md`. +- `docs/AGENT-ISSUE-WORKFLOW.md` — dual-track + principle (active-workflow surface + durable + git-history surface) and the three platform + adapters. Read at factory setup to pick the + active-workflow surface. - `docs/category-theory/README.md` — category-theory foundations the operator algebra rests on. Upstream CTFP sources (Milewski + the .NET port) live under diff --git a/docs/AGENT-CLAIM-PROTOCOL.md b/docs/AGENT-CLAIM-PROTOCOL.md new file mode 100644 index 00000000..a71a28aa --- /dev/null +++ b/docs/AGENT-CLAIM-PROTOCOL.md @@ -0,0 +1,490 @@ +# Agent Claim Protocol — git-native, platform-optional + +**If you've been handed this URL with a task, read the +[TL;DR](#tl-dr-five-steps) first. The rest of the doc explains +the details, but the five steps are enough to start.** + +This protocol lets any AI agent (ChatGPT / Codex / Deep +Research / Claude Code / Gemini / Aider / Cursor) or human +contributor pick up a PR task on the Zeta repository without +prior context on the factory. If you have a git clone, you +have everything you need. Optional adapters mirror the +protocol onto GitHub Issues / Jira / Linear without changing +its semantics. + +This doc is the **standalone, linkable** companion to +[`AGENT-ISSUE-WORKFLOW.md`](AGENT-ISSUE-WORKFLOW.md). That +doc explains the *dual-track principle* and platform +adapters; this doc specifies the *git-native claim +mechanism* that every adapter is built on. + +## Hand-off template — paste this with the task + +If you're a maintainer handing a task to an external agent +(ChatGPT, Codex, Deep Research, a team member on another +harness), this is the prompt body. Fill the two placeholders +and paste it along with any issue / task link: + +> You have a PR task on the Zeta repository at +> `https://github.com/Lucent-Financial-Group/Zeta`. +> +> 1. Read the claim protocol: +> `https://github.com/Lucent-Financial-Group/Zeta/blob/main/docs/AGENT-CLAIM-PROTOCOL.md` +> 2. The task is: **\** +> 3. Follow the TL;DR. Use the **\ sandbox | direct-commit>** mode section that matches +> how you work. +> 4. Respect the "Scope discipline" and "What this protocol +> does NOT do" sections. +> 5. Open a PR on `Lucent-Financial-Group/Zeta` when you're +> done. Release your claim in the same PR. + +One URL + one task + one mode-name is the full briefing. The +agent follows the protocol URL and picks up everything else +from there. + +## TL;DR — five steps + +### 1. Clone and pull + +``` +git clone https://github.com/Lucent-Financial-Group/Zeta.git +cd Zeta +git pull --ff-only origin main +``` + +### 2. Check for an existing claim on the work you want + +``` +ls docs/claims/ # live claims +cat docs/claims/.md # details of a specific claim +``` + +A live claim with `claimed-at` within the last 24 hours is +**active** — pick different work or wait. A claim older than +24 hours without a progress signal is **stale** and may be +force-released (see [Stale claims](#stale-claims-and-force-release)). + +### 3. File your claim + +Create `docs/claims/.md` using the +[claim file template](#claim-file-shape), then commit it: + +``` +git checkout -b claim/ # or your working branch +# write docs/claims/.md +git add docs/claims/.md +git commit -m "claim: - " +git push -u origin claim/ +``` + +### 4. Do the work + +Commit as you normally would on `claim/` (or the +branch you're using). If the work is expected to run longer +than four hours, add an occasional *progress commit* +touching the claim file so parallel agents see the claim is +still live: + +``` +# edit docs/claims/.md (update ETA or append a Note) +git commit -am "progress: - " +git push +``` + +### 5. Release + +When you open a PR (or land the work directly), **delete the +claim file in the same PR**: + +``` +git rm docs/claims/.md +git commit -m "release: - landed in " +``` + +If the work is abandoned, release with a reason instead: +`release: - abandoned, reason: <...>`. The BACKLOG +row / issue stays open for another agent. + +That is the whole protocol. The remaining sections specify +the details (modes, slug rules, file shape, conflict +resolution, stale-claim handling, scope discipline, +platform adapters) that make it robust under parallel +agents. + +## Modes — pick the one that matches how you work + +Different harnesses have different execution shapes. Use the +mode section that matches yours. + +### Deep Research mode (read-only) + +If you are running in **Deep Research** mode (ChatGPT Deep +Research, Claude research mode, any read-only absorption +task), **you do not need to claim anything**. You are not +writing to the repo. Skip the claim steps and focus on the +reading. + +If your Deep Research run produces a report that the user +wants to land in the repo, *that* is a separate PR task — +claim it when you move from reading to writing. + +### Codex / sandbox mode (PR-write) + +If you are running in **OpenAI Codex** or another sandbox +that clones, works, and opens a PR in one shot: + +- The claim commit and the release commit both land on your + feature branch as part of the PR. One PR carries: claim + + work + release. +- No intermediate progress commits are required (your run is + short enough that the 24-hour window isn't in play). +- Open the PR against `Lucent-Financial-Group/Zeta` and wait + for review. The release commit inside the PR is what + retires the claim on merge. + +### Direct-commit mode (trusted maintainer) + +If you are a maintainer landing work directly on `main` +(not via PR): + +- Claim commit first, pushed to `main`. +- Work commits. +- Release commit last, pushed to `main`, referencing the + landing SHA. + +Direct-commit is unusual and reserved for maintainers with +push access. Default to the PR path unless you know you +have direct-commit authority. + +### Review / advisory mode (no claim required) + +If you are reviewing an existing claim or advising on a +design (Gemini offering pair-programming feedback, a +reviewer commenting on an open PR, a human giving +architectural advice), **no claim file is needed**. Review +is additive work that attaches to someone else's claim: + +- Leave comments on the PR / claim file / issue. +- Open a separate advisory issue if the suggestion is big + enough to warrant its own BACKLOG row. +- Do not file a claim unless you are about to *write* code + or docs. + +Review and advisory output is valuable even when the +substrate cannot push code — see the next mode. + +### Report-back / write-via-maintainer mode (no claim required) + +If your substrate cannot push to git directly (a ChatGPT +conversation without Codex, a Deep Research run that can +only read, a human AI without connector write access), +**produce an output artifact instead of claiming**: + +- Write the result as a markdown file, a patch, a table, a + checklist, or whatever shape the task requires. +- Send it back to the maintainer in the conversation. +- The maintainer commits the artifact on your behalf. +- Attribution in the commit message names your substrate + (e.g. `... contributed by chatgpt-deep-research per + `). + +This mode is **first-class**. The factory observed Amara's +Deep Research archive report and Gemini's architectural +review arriving in exactly this shape, and both produced +load-bearing output. The protocol welcomes the pattern: +honest substrate-limits + substantive output + maintainer +commits = valid contribution. You are not expected to solve +a write-access problem that your substrate cannot solve. + +## Claim file shape + +A claim file lives at `docs/claims/.md`. The shape is +intentionally minimal so the protocol is easy to follow +across harnesses. **Copy-paste this template:** + +```markdown +# Claim - + +- **Session:** +- **Harness:** +- **Claimed at:** +- **ETA:** +- **Scope:** +- **Durable target:** +- **Platform mirror:** + +## Notes + + +``` + +### Slug rules + +A slug is a short, kebab-case identifier that uniquely names +the claim: + +- **`backlog-`** — claim on a numbered row in + `docs/BACKLOG.md` (e.g. `backlog-42`). Preferred when the + work unit already has a durable row. +- **`bug-`** — claim on a numbered row in `docs/BUGS.md`. +- **`issue-`** — claim on a GitHub / Jira / Linear issue + by its external ID (e.g. `issue-107`). Use the platform + ID verbatim so the claim file and the platform issue share + a name. +- **`task-`** — free-form claim not tied to a + numbered row. Use sparingly; prefer filing a BACKLOG row + first so the work has a durable anchor. + +Slugs are globally unique within `docs/claims/`. If work is +already in flight under one slug, don't create a sibling +slug for the same scope — join the existing claim by +commenting in the claim file, or coordinate via the platform +mirror if one exists. + +### Session identity + +`Session` is a free-form string that lets parallel agents +tell claims apart. Suggested formats: + +- `claude-code//` — Claude Code. +- `codex//` — OpenAI Codex. +- `chatgpt-deep-research//` — + ChatGPT Deep Research (write-mode only; read-mode skips + the claim). +- `gemini-cli//` — Gemini CLI. +- `` — human contributor. + +Identity is a courtesy signal for parallel agents trying to +contact the claim-holder. Be honest about which harness is +holding the claim — the honesty makes cross-harness audits +(and the factory's alignment research) possible. + +## Lifecycle — claim, progress, release + +The lifecycle has three operations, each realised as a +commit: + +| Operation | Commit message | File change | +|---|---|---| +| **Claim** | `claim: - ` | Add `docs/claims/.md` | +| **Progress** | `progress: - ` | Touch `docs/claims/.md` (update ETA or append to Notes) | +| **Release** | `release: - landed in ` or `release: - abandoned, reason: <...>` | Delete `docs/claims/.md` | + +Commit messages follow the `verb: - ` pattern +so parallel agents can filter the log: + +``` +git log --grep="^claim: \|^progress: \|^release: " --oneline +``` + +### Claim commit details + +Before committing, `git pull --ff-only origin main` to see +any recently-filed claims. If a claim file with your target +slug already exists on `main`, pick a different slug or +coordinate with the existing claim. + +The claim commit can sit on a feature branch +(`claim/`), a work branch (`feat/`), or a +speculative branch — what matters is that the commit +reaches `origin` promptly. Until you push, parallel agents +don't see the claim. + +### Progress signal details + +Progress signals become important when the expected ETA +crosses the 24-hour active-claim window. A progress commit +touches the claim file in any way — update `ETA`, append to +Notes, add a cross-reference — and resets the 24-hour +stale-claim clock. + +Progress commits need not land on `main`; pushing to the +branch that carries the claim file is enough, as long as +the branch is visible on the remote: + +``` +git ls-remote origin | grep claim/ +``` + +### Release commit details + +The release commit records the disposition: + +- `release: - landed in ` — work completed; + cite the landing commit's SHA. +- `release: - merged as PR #` — work completed + via PR; the PR merge SHA is a good citation. +- `release: - abandoned, reason: <...>` — work not + completed; the BACKLOG row / issue stays open. + +The release commit is part of the same PR that lands the +work (recommended — keeps claim lifecycle tied to the +work's landing) or a follow-up commit after merge. + +## Conflict resolution — merge conflicts are the coordination signal + +If two agents try to claim the same slug simultaneously, git +enforces coordination for us: + +1. Agent A writes `docs/claims/backlog-42.md` and pushes. + Push succeeds — A holds the claim. +2. Agent B, from an older checkout, writes + `docs/claims/backlog-42.md` and pushes. Push fails + (non-fast-forward). +3. Agent B pulls — merge conflict on + `docs/claims/backlog-42.md`. +4. Agent B resolves by **accepting A's version** (A pushed + first; A holds the claim) and picks different work. B's + local claim file is discarded. + +If both agents genuinely want to collaborate on the same +work, they add each other as sessions in a single claim +file: + +```markdown +- **Session:** agent-A, agent-B (co-claim 2026-04-22T19:30:00Z) +``` + +## Stale claims and force-release + +A claim is **active** for 24 hours from its most recent +commit (claim, progress, or any commit touching +`docs/claims/.md`). After 24 hours of no activity, +the claim is **stale**. + +To force-release a stale claim: + +1. Verify the claim is genuinely stale: + ``` + git log -1 --format=%ci -- docs/claims/.md + ``` + The timestamp must be more than 24 hours before `now`. +2. Delete the claim file with a citation: + ``` + git rm docs/claims/.md + git commit -m "force-release: - stale since " + ``` +3. Push and take the work. + +**Do not** force-release inside the 24-hour window. If you +believe a claim is stuck but within the window, add a +`progress` commit with a `blocked` marker or leave a Note +asking the claim-holder to check in. + +The 24-hour window is tunable per adopter; overrides land +in `AGENT-ISSUE-WORKFLOW.md` or an ADR under +`docs/DECISIONS/`. + +## Scope discipline — what you claim, what you don't + +This section exists because external agents (especially +ChatGPT / Deep Research / Codex) often arrive with helpful +instincts that exceed the claim's scope. The protocol is +narrow on purpose: + +**Claim the work, not the repo.** A claim covers the +specific task (a BACKLOG row, a bug fix, a feature). It does +not authorise sweeping refactors, broad renames, or +unrelated cleanups encountered along the way. If you notice +something else that needs fixing, file a new BACKLOG row +rather than bundling it into the claim. + +**Claim code, not identity.** The factory has personas +(named reviewer roles) and agent notebooks under +`memory/persona/` — those are **harness-local, not in the +git tree**. An external agent with git access sees the +soul-file (public repo surface) but not the persona layer, +and the claim protocol is for code and docs only. Do not +invent persona-names, do not claim identity surfaces, do +not modify anything under `memory/` (you cannot — it's not +in git). + +**Claim facts, not framings.** If your work touches +`docs/ALIGNMENT.md`, `GOVERNANCE.md`, or a research report, +claim the *factual change* you are making (fix a typo, add +a row, clarify a definition). Do not use the claim as an +entry point for renegotiating the factory's values, +philosophy, or register — those go through the renegotiation +protocol in `docs/ALIGNMENT.md`. + +**Claim the scope the maintainer asked for.** If the +hand-off template said "fix typo in X", do not expand to +"fix typo in X and also add a test and also refactor the +module." Narrow scope makes review possible; scope creep +makes PRs un-mergeable. + +## Platform adapters — additive, not required + +If the adopter has chosen GitHub Issues / Jira / Linear as +the active-workflow surface, the git-native claim file +remains the durable record; the platform mirror is an +ephemeral overlay that gains richer UX (labels, +notifications, dashboards) without changing the protocol. + +| Adapter | Mirror on claim | Mirror on release | +|---|---|---| +| **GitHub Issues** | Comment on the issue: `claimed by - see docs/claims/.md`; add `in-progress` label | Comment `released - landed in `; remove `in-progress` label; close issue if work done | +| **Jira / Linear** | Transition to `In Progress`; assign to self; add comment linking `docs/claims/.md` | Transition to `Done` / `Released`; comment with commit SHA | +| **Git-native only** | (no mirror) | (no mirror) | + +The platform comment and the claim file are created +together, but the claim file is authoritative if they +disagree — the file is in git, the comment is on the +platform. If the platform is down, the claim still exists. + +## What this protocol does NOT do + +- Does **not** replace the dual-track principle. Durable + git-history (BACKLOG rows, BUGS entries, commit messages) + is still the authoritative record of what happened. Claim + files are the *coordination* surface, not the *history* + surface. +- Does **not** enforce claims at the git level. No + pre-commit hook blocks work without a claim file. The + protocol is discipline, not gate. If collision rate + becomes problematic, a hook lands via ADR. +- Does **not** require external platform access. GitHub + Issues / Jira / Linear are optional adapters. +- Does **not** grant work authority. Holding a claim means + "no other agent should duplicate this effort"; it does + not mean "my PR will be merged." Review, alignment with + the factory's direction, and the maintainer's sign-off + all still apply. +- Does **not** expire automatically. Stale claims remain + visible in `docs/claims/` until another agent + force-releases them. The 24-hour window is the + force-release *permission*, not an auto-cleanup. +- Does **not** track work progress in detail. Progress + signals are coarse ("the claim is still alive"); for + fine-grained progress use PR draft status, commit log, + or BACKLOG row updates. +- Does **not** authorise modifying the factory's alignment + contract, persona notebooks, or values surfaces. See + "Scope discipline" above. +- Does **not** grant write access to repos you don't + otherwise have write access to. If you are working from a + fork, open the PR from the fork. If you have no write + access anywhere, file a BACKLOG row or issue and stop. + +## References + +- [`AGENT-ISSUE-WORKFLOW.md`](AGENT-ISSUE-WORKFLOW.md) — + dual-track principle + three platform adapters; this + doc is the git-native substrate underneath it. +- [`AGENTS.md`](../AGENTS.md) — universal onboarding handbook + (read for repo-wide rules, pre-v1 status, three + load-bearing values). +- [`docs/BACKLOG.md`](BACKLOG.md) — durable backlog (always + required regardless of adapter). +- [`docs/BUGS.md`](BUGS.md) — durable bug ledger. +- [`docs/HUMAN-BACKLOG.md`](HUMAN-BACKLOG.md) — items + awaiting maintainer sign-off. +- [`docs/ALIGNMENT.md`](ALIGNMENT.md) — the alignment + contract; the renegotiation protocol lives there for + changes outside claim scope. +- [`GOVERNANCE.md`](../GOVERNANCE.md) — numbered repo-wide + rules; §2 (docs-as-current-state) and §24 (install + script) are most relevant to adopters configuring the + workflow at setup. diff --git a/docs/AGENT-ISSUE-WORKFLOW.md b/docs/AGENT-ISSUE-WORKFLOW.md index 81114baf..9efe56ec 100644 --- a/docs/AGENT-ISSUE-WORKFLOW.md +++ b/docs/AGENT-ISSUE-WORKFLOW.md @@ -80,14 +80,20 @@ copying the factory should read this doc and choose consciously. ## The claim / lock protocol (adapter-neutral) Parallel agents need a non-colliding way to signal "I'm -starting on this work." The protocol is the same across -adapters; only the mechanism differs: +starting on this work." The full git-native protocol +specification lives in +[`docs/AGENT-CLAIM-PROTOCOL.md`](AGENT-CLAIM-PROTOCOL.md) — +that doc is the standalone, linkable reference you hand to +an external agent (ChatGPT / Codex / Gemini / Deep Research) +along with the task URL. The table below summarises the +mechanism per adapter; the git-native row is the substrate +the other two adapters mirror. | Adapter | Claim mechanism | Release mechanism | Lookup for parallel agent | |---|---|---|---| | GitHub Issues | Comment `claimed by session — ETA <...>` + add `in-progress` label | Comment `releasing — landed in ` + remove label + close (if done) | `gh issue list --label in-progress` | | Jira | Transition to `In Progress` state + assign to self + add comment | Transition to `Done` / `Released` + comment with commit | `jql: status = "In Progress"` | -| Git-native | Short commit touching the row: `BACKLOG: claim row #42 — session ` | Commit touching the row: `BACKLOG: release row #42 — landed in ` | `git log --grep="claim row" docs/BACKLOG.md` | +| Git-native | Claim file at `docs/claims/.md`; commit `claim: — ` (see [`AGENT-CLAIM-PROTOCOL.md`](AGENT-CLAIM-PROTOCOL.md) for the full shape) | Delete the claim file; commit `release: — landed in ` | `ls docs/claims/` or `git log --grep="^claim: " --oneline` | ### Claim windows and stale-claim force-release @@ -192,6 +198,9 @@ Jira or git-native can skip it. ## References +- [`AGENT-CLAIM-PROTOCOL.md`](AGENT-CLAIM-PROTOCOL.md) — + the standalone, linkable git-native claim specification + (hand this URL to external agents along with the task) - `AGENTS.md` — universal onboarding - `CLAUDE.md` — Claude Code harness rules - `docs/BACKLOG.md` — durable research backlog (always required) From b94abf778c2b3eadb950856fd6024206872537e0 Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Wed, 22 Apr 2026 02:50:18 -0400 Subject: [PATCH 2/7] docs/AGENT-CLAIM-PROTOCOL.md: fix markdownlint MD051 on TL;DR anchor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI (markdownlint-cli2) flagged "[TL;DR](#tl-dr-five-steps)" as an invalid link fragment. The GitHub slug algorithm transforms "## TL;DR — five steps" to "tl-dr--five-steps" (double dash from the em-dash), not "tl-dr-five-steps". Simpler fix than chasing the slug algorithm: rename the header to "## TL;DR: five steps" (colon strips cleanly; no em-dash) so the slug is the predictable "tldr-five-steps". Update the link to match. Semantics unchanged. Unblocks PR #108 auto-merge. --- docs/AGENT-CLAIM-PROTOCOL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/AGENT-CLAIM-PROTOCOL.md b/docs/AGENT-CLAIM-PROTOCOL.md index a71a28aa..8564593e 100644 --- a/docs/AGENT-CLAIM-PROTOCOL.md +++ b/docs/AGENT-CLAIM-PROTOCOL.md @@ -1,7 +1,7 @@ # Agent Claim Protocol — git-native, platform-optional **If you've been handed this URL with a task, read the -[TL;DR](#tl-dr-five-steps) first. The rest of the doc explains +[TL;DR: five steps](#tldr-five-steps) first. The rest of the doc explains the details, but the five steps are enough to start.** This protocol lets any AI agent (ChatGPT / Codex / Deep @@ -43,7 +43,7 @@ One URL + one task + one mode-name is the full briefing. The agent follows the protocol URL and picks up everything else from there. -## TL;DR — five steps +## TL;DR: five steps ### 1. Clone and pull From be20a9adaaafbdd09544ab4a1fa17401d62308cc Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Fri, 24 Apr 2026 10:55:08 -0400 Subject: [PATCH 3/7] =?UTF-8?q?docs:=20FIRST-PR.md=20=E2=80=94=20first-cla?= =?UTF-8?q?ss=20entry=20surface=20for=20fresh=20devs=20+=20vibe=20coders?= =?UTF-8?q?=20(#109)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: FIRST-PR.md first-class entry surface for fresh devs + vibe coders Aaron 2026-04-22: "can we make a first class surface for that entry point for fresh devs and vibe coders who are just starting out". - New docs/FIRST-PR.md promoted to first-class surface: - UI-first four-click contribution path (no CLI, no clone, no F# needed) - Web-UI file-edit walkthrough (GitHub pencil icon -> fork -> edit -> PR) - Vibe-coder flow (human directs AI, AI does writing, human reviews proposed diff) - Human claim walkthrough (GitHub Issues only; no git-native claim files required) - "What you do NOT need to worry about" section - Pointers added: - README.md: new "Contributing" section with three entry points (FIRST-PR / CONTRIBUTING / AGENT-CLAIM-PROTOCOL) - AGENTS.md §"Contributor required reading": FIRST-PR.md entry above AGENT-CLAIM-PROTOCOL.md - CONTRIBUTING.md: top-banner pointer to FIRST-PR.md for first-time / AI-directed contributors - docs/AGENT-CLAIM-PROTOCOL.md: fix markdownlint MD051 on TL;DR anchor (rename "TL;DR - five steps" -> "TL;DR: five steps" so GitHub slug algorithm produces a stable anchor; unblocks PR #108 CI) - docs/BACKLOG.md: P2 row "First-principle seed to Zeta derivation - common vernacular only" per Aaron 2026-04-22 directive Stacked on agent-claim-protocol-git-native (PR #108) because FIRST-PR.md references AGENT-CLAIM-PROTOCOL.md. * docs/BACKLOG.md: P2 row — capability-limited-AI bootstrap guide 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". Filed above the first-principle-seed P2 row. Proposes docs/CAPABILITY-LIMITED-BOOTSTRAP.md covering five capability- limited persona shapes (short-context / small-parameter / tool-restricted / no-web-sandbox / stateless) with a rung-by-rung bootstrap ladder and a falsification anchor (can a 7B-parameter model open a merged PR using only docs/FIRST-PR.md + one issue URL?). Composes with the vibe-coded hypothesis, AGENT-CLAIM-PROTOCOL.md report-back mode, and the witnessable-self-directed-evolution discipline — if crippled agents can use the factory, its intelligence is genuinely externalised rather than large-model- carrier-transported. * docs/BACKLOG.md: revision — personal-resilience axis on capability-limited-AI bootstrap row Aaron 2026-04-22 same-day extension: "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". Adds personal-resilience as a second rationale axis alongside capability-democratisation. The factory is meant to survive its maintainer losing access to frontier models — if circumstances force a move to local / open-weights / tiny models, the factory keeps working. Pragmatic test: a ~4-8B-parameter local-inference model on commodity hardware produces meaningful factory work when paired with the bootstrap guide + soul-file + tests as error- corrector. Dated revision block preserves chronology per capture-everything discipline. Composes with soul-file germination (already designed to bootstrap from nothing; now extended to "from a tiny model on a laptop"). * docs/BACKLOG.md: strip stray conflict marker from rebase resolution --- AGENTS.md | 7 ++ CONTRIBUTING.md | 6 + README.md | 16 +++ docs/BACKLOG.md | 191 ++++++++++++++++++++++++++++++++ docs/FIRST-PR.md | 280 +++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 500 insertions(+) create mode 100644 docs/FIRST-PR.md diff --git a/AGENTS.md b/AGENTS.md index 9617d2cb..f37969b5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -337,6 +337,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 b533e5d3..8a2af426 100644 --- a/README.md +++ b/README.md @@ -207,6 +207,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 405a7b1c..4b8166e5 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -6735,6 +6735,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. From b4d781773693e850752efce9858b62246678045d Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Fri, 24 Apr 2026 19:24:17 -0400 Subject: [PATCH 4/7] docs/AGENT-CLAIM-PROTOCOL.md: drain PR #108 review threads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolves 13 unresolved review threads on PR #108: - Track docs/claims/ with a README.md placeholder so the TL;DR `ls docs/claims/` lookup works on a fresh clone. - Hand-off template + Codex/sandbox section: declare the report-back fallback explicitly and require pushing the claim commit early (sandbox-local claims are invisible). - Switch claim-file Session field to opaque Session ID so permanent git history does not carry direct agent or human handles (per "no name attribution" rule). - Replace the "Amara / Gemini" example narrative with a role-referenced version ("external-AI Deep Research / architectural review"). - Correct the factually-wrong "memory/ is not in the git tree" claim. memory/ is tracked; the rule is "external claim-holders do not modify it without explicit scope." - Reconcile docs/AGENT-ISSUE-WORKFLOW.md: the (3) git-native section and the claim-mechanism table now both point at AGENT-CLAIM-PROTOCOL.md as the authoritative substrate; backlog-row markers are row-local annotations, not the lock. Em-dash → hyphen in the table commit-message examples to match the canonical pattern. Anchor link `#tldr-five-steps` was already correct post-e5b9d14; that thread is stale. PR-preservation drain log: docs/pr-preservation/108-drain-log.md. --- docs/AGENT-CLAIM-PROTOCOL.md | 118 ++++++++++++++++++++++++----------- docs/AGENT-ISSUE-WORKFLOW.md | 26 +++++--- docs/claims/README.md | 31 +++++++++ 3 files changed, 130 insertions(+), 45 deletions(-) create mode 100644 docs/claims/README.md diff --git a/docs/AGENT-CLAIM-PROTOCOL.md b/docs/AGENT-CLAIM-PROTOCOL.md index 8564593e..818d6267 100644 --- a/docs/AGENT-CLAIM-PROTOCOL.md +++ b/docs/AGENT-CLAIM-PROTOCOL.md @@ -32,12 +32,17 @@ and paste it along with any issue / task link: > `https://github.com/Lucent-Financial-Group/Zeta/blob/main/docs/AGENT-CLAIM-PROTOCOL.md` > 2. The task is: **\** > 3. Follow the TL;DR. Use the **\ sandbox | direct-commit>** mode section that matches -> how you work. +> sandbox | direct-commit | report-back>** mode section +> that matches how you work. > 4. Respect the "Scope discipline" and "What this protocol > does NOT do" sections. -> 5. Open a PR on `Lucent-Financial-Group/Zeta` when you're -> done. Release your claim in the same PR. +> 5. If you can push and open a PR, do so on +> `Lucent-Financial-Group/Zeta` when you're done and +> release your claim in the same PR. If your substrate +> cannot push (read-only Deep Research, no-connector +> chat), use the **report-back / write-via-maintainer** +> mode and return the artifact for the maintainer to +> commit on your behalf. One URL + one task + one mode-name is the full briefing. The agent follows the protocol URL and picks up everything else @@ -56,10 +61,16 @@ git pull --ff-only origin main ### 2. Check for an existing claim on the work you want ``` -ls docs/claims/ # live claims +ls docs/claims/ # live claims (the directory is tracked; + # README.md is the non-empty placeholder) cat docs/claims/.md # details of a specific claim ``` +If `docs/claims/` is somehow missing on a fresh clone (it +shouldn't be — the directory ships tracked with a +`README.md`), recreate it with `mkdir -p docs/claims` +before filing your claim. + A live claim with `claimed-at` within the last 24 hours is **active** — pick different work or wait. A claim older than 24 hours without a progress signal is **stale** and may be @@ -134,15 +145,28 @@ claim it when you move from reading to writing. If you are running in **OpenAI Codex** or another sandbox that clones, works, and opens a PR in one shot: -- The claim commit and the release commit both land on your - feature branch as part of the PR. One PR carries: claim + - work + release. +- **Push the claim commit early.** A claim that lives only + on a sandbox-local feature branch is invisible to parallel + agents looking up `docs/claims/` on `main`. Land the + `claim: - ` commit on a pushed branch + *before* doing the work, so other agents see it via + `git ls-remote origin claim/` and the GitHub branch + list. (Pushing the claim does not require an open PR; a + bare branch is enough.) +- The release commit lands on the same feature branch as + part of the PR. One PR carries: claim + work + release. - No intermediate progress commits are required (your run is short enough that the 24-hour window isn't in play). - Open the PR against `Lucent-Financial-Group/Zeta` and wait for review. The release commit inside the PR is what retires the claim on merge. +If your sandbox truly cannot push to `origin` until PR-open +time, that is the **report-back / write-via-maintainer** +mode below — declare it explicitly so other agents know the +claim won't appear on `main` until the maintainer commits +the artifact. + ### Direct-commit mode (trusted maintainer) If you are a maintainer landing work directly on `main` @@ -189,13 +213,14 @@ only read, a human AI without connector write access), (e.g. `... contributed by chatgpt-deep-research per `). -This mode is **first-class**. The factory observed Amara's -Deep Research archive report and Gemini's architectural -review arriving in exactly this shape, and both produced -load-bearing output. The protocol welcomes the pattern: -honest substrate-limits + substantive output + maintainer -commits = valid contribution. You are not expected to solve -a write-access problem that your substrate cannot solve. +This mode is **first-class**. The factory has observed +external-AI Deep Research archive reports and external-AI +architectural reviews arriving in exactly this shape, and +both produced load-bearing output. The protocol welcomes +the pattern: honest substrate-limits + substantive output ++ maintainer commits = valid contribution. You are not +expected to solve a write-access problem that your +substrate cannot solve. ## Claim file shape @@ -206,7 +231,7 @@ across harnesses. **Copy-paste this template:** ```markdown # Claim - -- **Session:** +- **Session ID:** - **Harness:** - **Claimed at:** - **ETA:** @@ -220,6 +245,17 @@ across harnesses. **Copy-paste this template:** cross-references to prior work> ``` +**Session ID is opaque.** The repo rule "no name +attribution in code, docs, or skills" (see +[`docs/AGENT-BEST-PRACTICES.md`](AGENT-BEST-PRACTICES.md)) +applies to claim files because they live in `docs/` and +their commits become permanent git history. Use an opaque +session ID (a short hash, a UUID, a date-stamp + harness +tag) plus the harness type. Contact handles, real names, +and direct agent identities stay out of the claim file — +route them out-of-band through the platform mirror or the +PR thread when contact is needed. + ### Slug rules A slug is a short, kebab-case identifier that uniquely names @@ -245,21 +281,24 @@ mirror if one exists. ### Session identity -`Session` is a free-form string that lets parallel agents -tell claims apart. Suggested formats: - -- `claude-code//` — Claude Code. -- `codex//` — OpenAI Codex. -- `chatgpt-deep-research//` — - ChatGPT Deep Research (write-mode only; read-mode skips - the claim). -- `gemini-cli//` — Gemini CLI. -- `` — human contributor. - -Identity is a courtesy signal for parallel agents trying to -contact the claim-holder. Be honest about which harness is -holding the claim — the honesty makes cross-harness audits -(and the factory's alignment research) possible. +`Session ID` is an opaque short string that lets parallel +agents tell claims apart without putting direct agent or +human names into git history. Suggested formats (all +omit usernames and direct identities): + +- `claude-code/` — Claude Code. +- `codex/` — OpenAI Codex. +- `chatgpt-deep-research/` — ChatGPT Deep + Research (write-mode only; read-mode skips the claim). +- `gemini-cli/` — Gemini CLI. +- `human/` — human contributor. + +Be honest about which harness is holding the claim — the +honesty makes cross-harness audits (and the factory's +alignment research) possible. If a parallel agent needs to +*contact* the claim-holder, use the platform mirror (GitHub +Issue, Jira ticket) or the PR thread; those surfaces accept +real handles without polluting git history. ## Lifecycle — claim, progress, release @@ -393,13 +432,16 @@ rather than bundling it into the claim. **Claim code, not identity.** The factory has personas (named reviewer roles) and agent notebooks under -`memory/persona/` — those are **harness-local, not in the -git tree**. An external agent with git access sees the -soul-file (public repo surface) but not the persona layer, -and the claim protocol is for code and docs only. Do not -invent persona-names, do not claim identity surfaces, do -not modify anything under `memory/` (you cannot — it's not -in git). +`memory/persona/`. Some of that material is committed to +git (the `memory/` tree is tracked; see `memory/MEMORY.md` +and `memory/persona/README.md` for what lives where), and +some is harness-local. External agents arriving via this +protocol claim code and docs on the public repo surface +only. Do not invent persona-names, do not claim identity +surfaces, and do not modify anything under `memory/` +unless your hand-off explicitly scoped you to a memory +file — the persona layer is curated by the factory's +internal agents, not external claim-holders. **Claim facts, not framings.** If your work touches `docs/ALIGNMENT.md`, `GOVERNANCE.md`, or a research report, diff --git a/docs/AGENT-ISSUE-WORKFLOW.md b/docs/AGENT-ISSUE-WORKFLOW.md index 9efe56ec..a7f3c251 100644 --- a/docs/AGENT-ISSUE-WORKFLOW.md +++ b/docs/AGENT-ISSUE-WORKFLOW.md @@ -61,12 +61,24 @@ picked at setup time: private / air-gapped work. - Requirements: none beyond git. - In this mode the in-repo markdown files (`docs/BACKLOG.md`, - `docs/BUGS.md`, `docs/HUMAN-BACKLOG.md`) are the **only** - surface; "active workflow" state lives in commit messages - and row-level status markers (`[in-progress 2026-04-22 by - session X]`, `[blocked on ...]`, `[done in SHA]`). -- Claims happen via short status-marker commits that are - visible to parallel agents running `git log docs/BACKLOG.md`. + `docs/BUGS.md`, `docs/HUMAN-BACKLOG.md`) are the durable + backlog surface; "active workflow" state lives in commit + messages and the row-level status indicators those rows + carry (`[blocked on ...]`, `[done in SHA]`). +- Claims happen via the **git-native claim protocol** — the + authoritative substrate specified in + [`AGENT-CLAIM-PROTOCOL.md`](AGENT-CLAIM-PROTOCOL.md): a + per-claim file at `docs/claims/.md` plus + `claim:` / `progress:` / `release:` commits on a branch + visible to `origin`. Parallel agents discover live claims + via `ls docs/claims/` or + `git log --grep="^claim: " --oneline`. +- Backlog row markers (`[in-progress ...]`, `[blocked ...]`) + remain useful as **row-local annotations** on the durable + backlog row, but they are not the locking mechanism — the + claim file is. Adopters who want backlog-only claims (no + separate `docs/claims/` directory) can document that + divergence in their own ADR. ### Choosing at setup @@ -93,7 +105,7 @@ the other two adapters mirror. |---|---|---|---| | GitHub Issues | Comment `claimed by session — ETA <...>` + add `in-progress` label | Comment `releasing — landed in ` + remove label + close (if done) | `gh issue list --label in-progress` | | Jira | Transition to `In Progress` state + assign to self + add comment | Transition to `Done` / `Released` + comment with commit | `jql: status = "In Progress"` | -| Git-native | Claim file at `docs/claims/.md`; commit `claim: — ` (see [`AGENT-CLAIM-PROTOCOL.md`](AGENT-CLAIM-PROTOCOL.md) for the full shape) | Delete the claim file; commit `release: — landed in ` | `ls docs/claims/` or `git log --grep="^claim: " --oneline` | +| Git-native | Claim file at `docs/claims/.md` (directory tracked, `README.md` placeholder); commit `claim: - ` (see [`AGENT-CLAIM-PROTOCOL.md`](AGENT-CLAIM-PROTOCOL.md) for the full shape) | Delete the claim file; commit `release: - landed in ` | `ls docs/claims/` or `git log --grep="^claim: " --oneline` | ### Claim windows and stale-claim force-release diff --git a/docs/claims/README.md b/docs/claims/README.md new file mode 100644 index 00000000..741ade68 --- /dev/null +++ b/docs/claims/README.md @@ -0,0 +1,31 @@ +# Live claims + +This directory holds **active claim files** under the +git-native claim protocol specified in +[`../AGENT-CLAIM-PROTOCOL.md`](../AGENT-CLAIM-PROTOCOL.md). + +Each live claim is one file at `docs/claims/.md`, +where `` follows the slug rules in the protocol +(`backlog-`, `bug-`, `issue-`, or +`task-`). + +## How to use + +- **Look for live claims:** `ls docs/claims/` +- **Read a specific claim:** `cat docs/claims/.md` +- **File a new claim:** create `docs/claims/.md` + using the [claim file template](../AGENT-CLAIM-PROTOCOL.md#claim-file-shape) + and commit `claim: - ` +- **Release a claim:** delete the file in the same PR + that lands the work + +A live claim with `claimed-at` within the last 24 hours +is **active** — pick different work or wait. A claim +older than 24 hours without a progress signal is +**stale** and may be force-released (see +[Stale claims](../AGENT-CLAIM-PROTOCOL.md#stale-claims-and-force-release)). + +This directory is tracked so a fresh clone has the +lookup target already in place; the `README.md` keeps +it non-empty across release cycles when no claims are +live. From 0639ec2a89d6f78703811d1fee386229ac331746 Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Fri, 24 Apr 2026 19:25:53 -0400 Subject: [PATCH 5/7] docs/pr-preservation/108-drain-log.md: append drain log Per Otto-250 PR-preservation: per-thread (id, file:line, verbatim original comment, outcome, verbatim reply, resolution commit) for all 13 threads on PR #108. Resolution SHA: 541e7b7. --- docs/pr-preservation/108-drain-log.md | 245 ++++++++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 docs/pr-preservation/108-drain-log.md diff --git a/docs/pr-preservation/108-drain-log.md b/docs/pr-preservation/108-drain-log.md new file mode 100644 index 00000000..00e2c0df --- /dev/null +++ b/docs/pr-preservation/108-drain-log.md @@ -0,0 +1,245 @@ +# PR #108 drain log — `docs: AGENT-CLAIM-PROTOCOL.md — git-native claim spec for external agents (one-URL handoff)` + +Drain ferry: 2026-04-24. Resolution commit on top of the rebased branch: `541e7b7`. Auto-merge armed; rebased onto fresh `origin/main` before drain. PR scope is docs-only (introduces `docs/AGENT-CLAIM-PROTOCOL.md`, `docs/FIRST-PR.md`; updates `docs/AGENT-ISSUE-WORKFLOW.md`, `docs/BACKLOG.md`, `AGENTS.md`, `CONTRIBUTING.md`, `README.md`). + +Per Otto-250 PR-preservation drain-log discipline: per-thread fields are reviewer, file:line, original comment verbatim, outcome, reply verbatim, resolution commit. Bot handles preserved verbatim per Otto-237. + +--- + +## Thread 1 — `PRRT_kwDOSF9kNM58swbC` + +- **Reviewer:** Copilot +- **File:line:** `docs/AGENT-CLAIM-PROTOCOL.md:60` +- **Outcome:** FIX +- **Resolution commit:** `541e7b7` + +### Original comment + +> P1: Ensure docs/claims exists before TL;DR claim commands +> +> The quick-start starts with `ls docs/claims/` and then asks contributors to add `docs/claims/.md`, but this commit does not create or track a `docs/claims/` directory anywhere, so the documented flow fails on a fresh clone (`ls` errors and claim-file creation cannot follow the listed commands). Add an explicit `mkdir -p docs/claims` step (or a tracked placeholder file) before these commands so first-time claimers can execute the protocol as writ + +### Reply + +> Fixed in 541e7b7. `docs/claims/README.md` now ships tracked as the non-empty placeholder so `ls docs/claims/` resolves on a fresh clone. Step 2 of the TL;DR was also reworded to note the directory is tracked and to fall back to `mkdir -p docs/claims` only if it is somehow missing. + +--- + +## Thread 2 — `PRRT_kwDOSF9kNM58swbF` + +- **Reviewer:** Copilot +- **File:line:** `docs/AGENT-ISSUE-WORKFLOW.md:96` +- **Outcome:** FIX +- **Resolution commit:** `541e7b7` + +### Original comment + +> P2: Reconcile git-native claim instructions in workflow doc +> +> This table switches git-native claiming to `docs/claims/.md`, but earlier in the same file the git-native adapter section still instructs claim signaling via BACKLOG row status-marker commits and `git log docs/BACKLOG.md`; that contradiction will cause parallel agents to use different locking mechanisms and miss each other's claims. Update the earlier git-native section to match the new claim-file protocol so the workflow remains internally co + +### Reply + +> Fixed in 541e7b7. The earlier "(3) Git-native only" section now points at `AGENT-CLAIM-PROTOCOL.md` as the authoritative claim-file substrate. Backlog-row markers are reframed as row-local annotations, not the locking mechanism. The mechanism table and the prose section now agree. + +--- + +## Thread 3 — `PRRT_kwDOSF9kNM58syNY` + +- **Reviewer:** chatgpt-codex-connector +- **File:line:** `docs/AGENT-ISSUE-WORKFLOW.md:90` +- **Outcome:** FIX +- **Resolution commit:** `541e7b7` + +### Original comment + +> P1: The updated git-native claim mechanism now depends on `docs/claims/.md`, but earlier in this doc's "Git-native only" section it still describes claims as row-marker commits in `docs/BACKLOG.md`. That leaves the document internally inconsistent about what "git-native" means. Update the earlier git-native-only description to match the new claim-file protocol (or explicitly differentiate backlog row markers from claim files). + +### Reply + +> Fixed in 541e7b7 (same edit as thread `PRRT_kwDOSF9kNM58swbF`). The "(3) Git-native only" section now points at `AGENT-CLAIM-PROTOCOL.md` and explicitly differentiates backlog-row markers (row-local annotations) from claim files (the lock). + +--- + +## Thread 4 — `PRRT_kwDOSF9kNM58syN6` + +- **Reviewer:** chatgpt-codex-connector +- **File:line:** `docs/AGENT-ISSUE-WORKFLOW.md:96` +- **Outcome:** FIX +- **Resolution commit:** `541e7b7` + +### Original comment + +> P1: The table suggests `ls docs/claims/`, but `docs/claims/` doesn't exist in the repo today, so this lookup command will fail for new clones unless the directory is added/tracked or the docs instruct creating it first. Also, commit message examples here use an em dash (`—`) while `AGENT-CLAIM-PROTOCOL.md` uses a hyphen (`-`); standardising punctuation would make the convention easier to follow and grep. + +### Reply + +> Fixed in 541e7b7. Both halves: `docs/claims/README.md` now ships tracked (so `ls docs/claims/` resolves on fresh clones); the table's `claim:` / `release:` examples switched from em-dash to ASCII hyphen to match the canonical pattern in `AGENT-CLAIM-PROTOCOL.md`. The table cell now also notes the directory is tracked with a `README.md` placeholder. + +--- + +## Thread 5 — `PRRT_kwDOSF9kNM58syOH` + +- **Reviewer:** chatgpt-codex-connector +- **File:line:** `docs/AGENT-CLAIM-PROTOCOL.md` (line null) +- **Outcome:** BACKLOG+RESOLVE (already-fixed) +- **Resolution commit:** `e5b9d14` (prior commit on this branch, pre-rebase) + +### Original comment + +> P1: The internal link target for the TL;DR section looks incorrect. GitHub's anchor for the heading `## TL;DR — five steps` will be based on `tldr` (not `tl-dr`), so `[TL;DR](#tl-dr-five-steps)` likely resolves to a non-existent anchor. Update the link to the actual generated anchor, or add an explicit anchor ID matching `tl-dr-five-steps` to keep the short link stable. + +### Reply + +> Already addressed in commit e5b9d14 ("docs/AGENT-CLAIM-PROTOCOL.md: fix markdownlint MD051 on TL;DR anchor") earlier on this branch. The current state shows `[TL;DR: five steps](#tldr-five-steps)` linking to `## TL;DR: five steps` — GitHub's anchor generator strips the colon and the link resolves correctly. This thread predates the fix; resolving as already-fixed. + +--- + +## Thread 6 — `PRRT_kwDOSF9kNM58syOT` + +- **Reviewer:** chatgpt-codex-connector +- **File:line:** `docs/AGENT-CLAIM-PROTOCOL.md:61` +- **Outcome:** FIX +- **Resolution commit:** `541e7b7` + +### Original comment + +> P1: The TL;DR commands assume `docs/claims/` already exists, but the repository currently has no `docs/claims/` directory. As written, `ls docs/claims/` will fail on a fresh clone. Either add a tracked `docs/claims/` directory (e.g., with a short README / placeholder file) or adjust the instructions to create it (`mkdir -p docs/claims`) before listing/catting claim files. + +### Reply + +> Fixed in 541e7b7. Same fix as thread `PRRT_kwDOSF9kNM58swbC`: `docs/claims/README.md` ships tracked, plus the TL;DR step 2 prose explicitly mentions both that the directory is tracked and the `mkdir -p docs/claims` fallback if it is somehow missing. + +--- + +## Thread 7 — `PRRT_kwDOSF9kNM58syOc` + +- **Reviewer:** chatgpt-codex-connector +- **File:line:** `docs/AGENT-CLAIM-PROTOCOL.md:215` +- **Outcome:** FIX +- **Resolution commit:** `541e7b7` + +### Original comment + +> P1: The claim template asks for `Session: `, which will put contributor/agent names into `docs/claims/.md` and therefore into permanent git history. This conflicts with `docs/AGENT-BEST-PRACTICES.md` ("No name attribution in code, docs, or skills"). Consider switching the template to an opaque session ID (plus harness type) and making any contact handle optional/out-of-band. + +### Reply + +> Fixed in 541e7b7. Template field renamed `Session` → `Session ID` with the explicit instruction "opaque session ID; do not use direct agent or human handles." The "Session identity" section was reworked to drop `` from every suggested format (now just `/`) and to route contact handles out-of-band through the platform mirror or the PR thread. A new paragraph cites `docs/AGENT-BEST-PRACTICES.md` and explains why claim files (which become permanent git history) are inside the no-name-attribution scope. + +--- + +## Thread 8 — `PRRT_kwDOSF9kNM58syOp` + +- **Reviewer:** chatgpt-codex-connector +- **File:line:** `docs/AGENT-CLAIM-PROTOCOL.md:194` +- **Outcome:** FIX +- **Resolution commit:** `541e7b7` + +### Original comment + +> P1: This paragraph introduces a direct contributor name ("Amara"), which conflicts with the repo rule to avoid direct contributor/agent names in code/docs/skills (see `docs/AGENT-BEST-PRACTICES.md` operational rule "No name attribution in code, docs, or skills"). Rephrase to describe the observed pattern generically (e.g., "a Deep Research archive report" / "an architectural review") without naming individuals. + +### Reply + +> Fixed in 541e7b7. The Report-back / write-via-maintainer paragraph now reads "external-AI Deep Research archive reports and external-AI architectural reviews" — role refs only, no direct contributor or agent names. Composes with thread `PRRT_kwDOSF9kNM58uoJH` which flagged the same passage. + +--- + +## Thread 9 — `PRRT_kwDOSF9kNM58syOz` + +- **Reviewer:** chatgpt-codex-connector +- **File:line:** `docs/AGENT-CLAIM-PROTOCOL.md:402` +- **Outcome:** FIX +- **Resolution commit:** `541e7b7` + +### Original comment + +> P1: This section claims `memory/persona/` and `memory/` are "not in the git tree" and therefore cannot be modified. In this repo, `memory/` is tracked (e.g., `memory/MEMORY.md` exists), so this is factually incorrect and will confuse external agents. If the intent is "do not modify memory entries," state it as a policy/permission boundary rather than a git-visibility claim. + +### Reply + +> Fixed in 541e7b7. Reframed as a permission boundary, not a git-visibility claim: the doc now acknowledges `memory/` is tracked (citing `memory/MEMORY.md` and `memory/persona/README.md` as the canonical map), and states the rule as "external claim-holders do not modify the persona layer unless your hand-off explicitly scoped you to a memory file." Factually correct and the no-touch rule is preserved. + +--- + +## Thread 10 — `PRRT_kwDOSF9kNM58umGB` + +- **Reviewer:** Copilot +- **File:line:** `docs/AGENT-CLAIM-PROTOCOL.md:139` +- **Outcome:** FIX +- **Resolution commit:** `541e7b7` + +### Original comment + +> P1: Publish claim before doing work on PR branches +> +> In Codex/sandbox mode this says a single PR should contain `claim + work + release`, which keeps the claim file only on a feature branch until merge. Parallel agents following the documented lookup (`ls docs/claims/` / `git log --grep="^claim:"`) against `main` will not see that active claim, so two agents can independently claim the same slug and duplicate the task. This breaks the lock protocol in the common PR workflow unless claims are first published to + +### Reply + +> Fixed in 541e7b7. Codex/sandbox mode section now leads with "Push the claim commit early" — the `claim:` commit lands on a pushed branch (no PR required) so other agents can see it via `git ls-remote origin claim/` before the work starts. A trailing paragraph addresses the case where the sandbox cannot push at all: that case is the report-back / write-via-maintainer mode, which the doc now requires the agent to declare explicitly so other agents know the claim won't appear on `main` until the maintainer commits the artifact. + +--- + +## Thread 11 — `PRRT_kwDOSF9kNM58uoIL` + +- **Reviewer:** chatgpt-codex-connector +- **File:line:** `docs/AGENT-CLAIM-PROTOCOL.md:40` +- **Outcome:** FIX +- **Resolution commit:** `541e7b7` + +### Original comment + +> The hand-off template always instructs the agent to open a PR and release the claim, but this conflicts with the later "Deep Research" and "Report-back / write-via-maintainer" modes where the substrate may be read-only/no-push. Adjust the template so it branches: "If you can push/open a PR, do so; otherwise use report-back mode and return an artifact for the maintainer to commit." + +### Reply + +> Fixed in 541e7b7. Step 5 of the hand-off template now branches: open a PR if you can push, otherwise use the report-back / write-via-maintainer mode and return the artifact for the maintainer to commit. Step 3's mode list also added `report-back` as a fourth option so the hand-off briefing names all four substrate-shape modes. + +--- + +## Thread 12 — `PRRT_kwDOSF9kNM58uoJH` + +- **Reviewer:** chatgpt-codex-connector +- **File:line:** `docs/AGENT-CLAIM-PROTOCOL.md:198` +- **Outcome:** FIX (composes with thread 8) +- **Resolution commit:** `541e7b7` + +### Original comment + +> This section introduces a personal name ("Amara") in a doc. Repo convention is to avoid direct contributor/agent names in docs (use role references instead; names are limited to memory/persona/** and a few carve-outs like docs/HUMAN-BACKLOG.md). Please rewrite this example to be name-free (e.g., "a ChatGPT Deep Research archive report"). + +### Reply + +> Fixed in 541e7b7 (same edit as thread `PRRT_kwDOSF9kNM58syOp`). The paragraph now reads "external-AI Deep Research archive reports and external-AI architectural reviews" — role refs only, no direct contributor or agent names. + +--- + +## Thread 13 — `PRRT_kwDOSF9kNM58uoJo` + +- **Reviewer:** chatgpt-codex-connector +- **File:line:** `docs/AGENT-ISSUE-WORKFLOW.md:96` +- **Outcome:** FIX (composes with thread 4) +- **Resolution commit:** `541e7b7` + +### Original comment + +> The commit message examples in this row use an em dash (`—`) but `docs/AGENT-CLAIM-PROTOCOL.md` specifies the canonical pattern as `verb: - `. Please pick one delimiter and apply consistently (preferably the ASCII `-` to avoid copy/paste and tooling surprises). + +### Reply + +> Fixed in 541e7b7 (same edit as thread `PRRT_kwDOSF9kNM58syN6`). The table's `claim: - ` and `release: - landed in ` examples now use ASCII hyphen, matching the canonical pattern in `AGENT-CLAIM-PROTOCOL.md`. + +--- + +## Rebase summary + +Branch was rebased from its original tip (`a63405b` plus the merge of `1956fb1`) onto current `origin/main` (`033bb4f`). Three commits replayed cleanly with no merge conflicts: `4241703` (the original AGENT-CLAIM-PROTOCOL landing), `b7f57b2` (the markdownlint anchor fix), and `56ca17e` (the FIRST-PR.md companion doc, originally on a separate PR #109 that merged into this branch). The drain commit `541e7b7` lands on top of those three. + +## Final state + +- Unresolved threads: 0 (target) +- mergeable: MERGEABLE (target after the force-push triggers GitHub recompute) +- Auto-merge armed: pre-existing +- Pushed SHAs: `541e7b7` (drain commit) on top of the three rebased PR commits From bbcce33031647dbe56160ea99e6230a2a7dee91b Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Fri, 24 Apr 2026 19:28:00 -0400 Subject: [PATCH 6/7] docs/AGENT-CLAIM-PROTOCOL.md: fix markdownlint MD032 (replace + with prose) --- docs/AGENT-CLAIM-PROTOCOL.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/AGENT-CLAIM-PROTOCOL.md b/docs/AGENT-CLAIM-PROTOCOL.md index 818d6267..749a1dd1 100644 --- a/docs/AGENT-CLAIM-PROTOCOL.md +++ b/docs/AGENT-CLAIM-PROTOCOL.md @@ -217,10 +217,10 @@ This mode is **first-class**. The factory has observed external-AI Deep Research archive reports and external-AI architectural reviews arriving in exactly this shape, and both produced load-bearing output. The protocol welcomes -the pattern: honest substrate-limits + substantive output -+ maintainer commits = valid contribution. You are not -expected to solve a write-access problem that your -substrate cannot solve. +the pattern: honest substrate-limits plus substantive +output plus maintainer commits equals a valid contribution. +You are not expected to solve a write-access problem that +your substrate cannot solve. ## Claim file shape From f669710322fae7cf0c7beb5dd8fb41724707f4df Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Fri, 24 Apr 2026 19:48:43 -0400 Subject: [PATCH 7/7] =?UTF-8?q?docs:=20drain=20late-review=20threads=20on?= =?UTF-8?q?=20PR=20#108=20(round=202=20=E2=80=94=209=20threads)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address late Copilot re-review on AGENT-CLAIM-PROTOCOL, AGENT-ISSUE-WORKFLOW, FIRST-PR, and the claims/ README. - TL;DR step 2, AGENT-ISSUE-WORKFLOW git-native section + table row, and the claims/README all now describe discovery via `git fetch origin && git branch -r --list 'origin/claim/*'` plus `git show origin/claim/:docs/claims/.md`. `ls docs/claims/` is reframed as the merged-but-not-released view, not the active-claim view. - Claim-commit-details paragraph now requires the claim commit to land on `claim/` specifically — that branch name gives push-time slug uniqueness via non-fast-forward rejection. Arbitrary branch names break the lock. - Co-claim example switched from `Session: agent-A, agent-B` to `Sessions: sess_7f3a9c2d, sess_b84e1a6f` to match the no-direct-handle rule from the round-1 template rename. - FIRST-PR.md: corrected the misleading "not in the repo" note about the dismissive-closing memory file (it is in-repo and indexed). Replaced direct reviewer names in three places with role refs (harsh-critic, maintainability reviewer, documentation agent), with the EXPERT-REGISTRY link as the canonical name source. Drain log appended (no edits to the round-1 section per Otto-229 append-only). --- docs/AGENT-CLAIM-PROTOCOL.md | 63 +++++++--- docs/AGENT-ISSUE-WORKFLOW.md | 15 ++- docs/FIRST-PR.md | 34 +++--- docs/claims/README.md | 17 ++- docs/pr-preservation/108-drain-log.md | 164 ++++++++++++++++++++++++++ 5 files changed, 255 insertions(+), 38 deletions(-) diff --git a/docs/AGENT-CLAIM-PROTOCOL.md b/docs/AGENT-CLAIM-PROTOCOL.md index 749a1dd1..1aabbea0 100644 --- a/docs/AGENT-CLAIM-PROTOCOL.md +++ b/docs/AGENT-CLAIM-PROTOCOL.md @@ -60,10 +60,27 @@ git pull --ff-only origin main ### 2. Check for an existing claim on the work you want +Claim files live on pushed `claim/` branches (see +step 3) — they may not yet be merged to `main`. To see +*all* live claims, refresh remote refs and list both the +working tree (claims that have already merged or are +still tracked on `main`) and remote claim branches: + ``` -ls docs/claims/ # live claims (the directory is tracked; - # README.md is the non-empty placeholder) -cat docs/claims/.md # details of a specific claim +git fetch origin # refresh remote refs +ls docs/claims/ # claims visible on the + # current checkout (the + # directory is tracked; + # README.md is the + # non-empty placeholder) +git branch -r --list 'origin/claim/*' # remote claim branches — + # active claims pushed + # but not yet merged +git show origin/claim/:docs/claims/.md # details of a specific + # remote claim +cat docs/claims/.md # details of a claim that + # is already on this + # branch ``` If `docs/claims/` is somehow missing on a fresh clone (it @@ -320,16 +337,33 @@ git log --grep="^claim: \|^progress: \|^release: " --oneline ### Claim commit details -Before committing, `git pull --ff-only origin main` to see -any recently-filed claims. If a claim file with your target -slug already exists on `main`, pick a different slug or -coordinate with the existing claim. +Before committing, refresh remote refs and check whether +`origin` already has a `claim/` branch (or a claim +file on `main`) for your target slug: + +``` +git fetch origin +git ls-remote --heads origin "claim/" +git show "origin/main:docs/claims/.md" 2>/dev/null +``` -The claim commit can sit on a feature branch -(`claim/`), a work branch (`feat/`), or a -speculative branch — what matters is that the commit -reaches `origin` promptly. Until you push, parallel agents -don't see the claim. +If either lookup returns a hit, pick a different slug or +coordinate with the existing claim — `main`-side claims +are merged-but-not-released claims; `claim/`-branch +hits are active claims still in flight. + +The claim commit **must** land on a branch named +`claim/` so the slug-uniqueness lock works. Pushing +the claim file on an arbitrary branch name (`feat/`, +a speculative branch, etc.) does not reserve the slug: +`git push` only updates the refspec you push, so two +agents can each push `docs/claims/.md` on different +remote branches and neither push fails. Use +`claim/` so the second pusher gets a non-fast-forward +rejection and discovers the existing claim. After the +claim lands, work commits can move to a separate working +branch (`feat/`); the `claim/` branch stays +as the lock until release. ### Progress signal details @@ -380,10 +414,11 @@ enforces coordination for us: If both agents genuinely want to collaborate on the same work, they add each other as sessions in a single claim -file: +file (use opaque session IDs, not direct agent or human +handles, per the `Session ID` template field): ```markdown -- **Session:** agent-A, agent-B (co-claim 2026-04-22T19:30:00Z) +- **Sessions:** sess_7f3a9c2d, sess_b84e1a6f (co-claim 2026-04-22T19:30:00Z) ``` ## Stale claims and force-release diff --git a/docs/AGENT-ISSUE-WORKFLOW.md b/docs/AGENT-ISSUE-WORKFLOW.md index a7f3c251..897b6992 100644 --- a/docs/AGENT-ISSUE-WORKFLOW.md +++ b/docs/AGENT-ISSUE-WORKFLOW.md @@ -69,10 +69,15 @@ picked at setup time: authoritative substrate specified in [`AGENT-CLAIM-PROTOCOL.md`](AGENT-CLAIM-PROTOCOL.md): a per-claim file at `docs/claims/.md` plus - `claim:` / `progress:` / `release:` commits on a branch - visible to `origin`. Parallel agents discover live claims - via `ls docs/claims/` or - `git log --grep="^claim: " --oneline`. + `claim:` / `progress:` / `release:` commits on a + `claim/` branch pushed to `origin`. Parallel + agents discover live claims by listing remote claim + branches (`git fetch origin && + git branch -r --list 'origin/claim/*'`) and reading + the claim file directly from the remote ref + (`git show origin/claim/:docs/claims/.md`); + `ls docs/claims/` on `main` only shows merged-but-not- + released claims, not active ones still in flight. - Backlog row markers (`[in-progress ...]`, `[blocked ...]`) remain useful as **row-local annotations** on the durable backlog row, but they are not the locking mechanism — the @@ -105,7 +110,7 @@ the other two adapters mirror. |---|---|---|---| | GitHub Issues | Comment `claimed by session — ETA <...>` + add `in-progress` label | Comment `releasing — landed in ` + remove label + close (if done) | `gh issue list --label in-progress` | | Jira | Transition to `In Progress` state + assign to self + add comment | Transition to `Done` / `Released` + comment with commit | `jql: status = "In Progress"` | -| Git-native | Claim file at `docs/claims/.md` (directory tracked, `README.md` placeholder); commit `claim: - ` (see [`AGENT-CLAIM-PROTOCOL.md`](AGENT-CLAIM-PROTOCOL.md) for the full shape) | Delete the claim file; commit `release: - landed in ` | `ls docs/claims/` or `git log --grep="^claim: " --oneline` | +| Git-native | Claim file at `docs/claims/.md` on a `claim/` branch pushed to `origin` (directory tracked on `main`, `README.md` placeholder); commit `claim: - ` (see [`AGENT-CLAIM-PROTOCOL.md`](AGENT-CLAIM-PROTOCOL.md) for the full shape) | Delete the claim file; commit `release: - landed in ` | `git fetch origin && git branch -r --list 'origin/claim/*'` (active claims) plus `ls docs/claims/` (claims merged to `main`) | ### Claim windows and stale-claim force-release diff --git a/docs/FIRST-PR.md b/docs/FIRST-PR.md index 5bc5eae8..9c4cc275 100644 --- a/docs/FIRST-PR.md +++ b/docs/FIRST-PR.md @@ -129,11 +129,12 @@ shape is: 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, +The team's reviewers are organised by role — a harsh-critic, +a maintainability reviewer, a documentation agent, and +several others. Each role has a stable identity in the +expert registry; the registry is where direct names live. +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 @@ -211,10 +212,10 @@ it for everyone else. 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. + GOVERNANCE §20 requires at least the harsh-critic + + maintainability reviewers 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. @@ -235,10 +236,11 @@ it for everyone else. 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). + for the discipline (the file is in-repo under + `memory/` and indexed from `memory/MEMORY.md`, + though some harnesses may not surface that path + by default — mentioned here so you know the + principle is codified). ## What this doc is NOT @@ -255,9 +257,9 @@ it for everyone else. [`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. + *contributors*; they are direct with *code*. The + harsh-critic role never compliments code; that is a + feature of the role, not hostility toward you. ## If you got this far and want more diff --git a/docs/claims/README.md b/docs/claims/README.md index 741ade68..83bb44fe 100644 --- a/docs/claims/README.md +++ b/docs/claims/README.md @@ -11,11 +11,22 @@ where `` follows the slug rules in the protocol ## How to use -- **Look for live claims:** `ls docs/claims/` -- **Read a specific claim:** `cat docs/claims/.md` +- **Look for live claims:** active claims live on pushed + `claim/` branches (not yet merged to `main`). + Refresh remote refs and list them: + `git fetch origin && git branch -r --list 'origin/claim/*'`. + `ls docs/claims/` only shows claims that have been + merged to the current branch. +- **Read a specific claim:** view the file from the + remote claim ref — + `git show origin/claim/:docs/claims/.md` + (active claim) or `cat docs/claims/.md` (claim + already on this branch). - **File a new claim:** create `docs/claims/.md` using the [claim file template](../AGENT-CLAIM-PROTOCOL.md#claim-file-shape) - and commit `claim: - ` + on a `claim/` branch and commit + `claim: - `, then push to + `origin`. - **Release a claim:** delete the file in the same PR that lands the work diff --git a/docs/pr-preservation/108-drain-log.md b/docs/pr-preservation/108-drain-log.md index 00e2c0df..206161c7 100644 --- a/docs/pr-preservation/108-drain-log.md +++ b/docs/pr-preservation/108-drain-log.md @@ -243,3 +243,167 @@ Branch was rebased from its original tip (`a63405b` plus the merge of `1956fb1`) - mergeable: MERGEABLE (target after the force-push triggers GitHub recompute) - Auto-merge armed: pre-existing - Pushed SHAs: `541e7b7` (drain commit) on top of the three rebased PR commits + +--- + +## Drain pass: 2026-04-24 (round 2 — 9 threads after late re-review) + +After the round-1 drain pushed `541e7b7`, late Copilot + Copilot-PR-reviewer re-review opened 9 new threads on the same surfaces. Branch was rebased onto fresh `origin/main` cleanly (six commits replayed, no conflicts). All 9 threads landed in a single drain commit. + +### Thread R2-1 — `PRRT_kwDOSF9kNM59iAuY` + +- **Reviewer:** Copilot +- **File:line:** `docs/AGENT-CLAIM-PROTOCOL.md:386` +- **Outcome:** FIX + +#### Original comment + +> P1: The co-claim example reintroduces `Session` (not `Session ID`) and uses direct identifiers (`agent-A`, `agent-B`), which conflicts with the template and the surrounding guidance to keep session identifiers opaque and avoid direct handles in claim files. Update the example to use `Session ID` (or a `Sessions:` field) and show opaque IDs instead of names. + +#### Reply + +> Fixed. The co-claim example now uses `Sessions:` with opaque session IDs (`sess_7f3a9c2d`, `sess_b84e1a6f`) and an explicit pointer to the `Session ID` template field's no-direct-handle rule. Matches the renamed template field from round 1 thread `PRRT_kwDOSF9kNM58syOc`. + +--- + +### Thread R2-2 — `PRRT_kwDOSF9kNM59iAul` + +- **Reviewer:** Copilot +- **File:line:** `docs/AGENT-ISSUE-WORKFLOW.md:75` +- **Outcome:** FIX + +#### Original comment + +> P0: The git-native adapter lookup/release guidance suggests `ls docs/claims/` and `git log --grep=...` as ways for parallel agents to discover live claims. But the git-native protocol described here creates claims on pushed branches (e.g., `claim/`), so `ls` on a checkout of `main` won't show active claims, and `git log` without `--all/--remotes` won't search remote branch histories. Update this section/table to point at remote-branch discovery (e.g., listing `origin/claim/*` and showing claim files from those refs). + +#### Reply + +> Fixed. The "(3) Git-native only" prose now says discovery uses `git fetch origin && git branch -r --list 'origin/claim/*'` for active claims plus `git show origin/claim/:docs/claims/.md` to read a claim's contents. `ls docs/claims/` is reframed as the merged-but-not-released view, not the active-claim view. Composes with R2-3 (the table row). + +--- + +### Thread R2-3 — `PRRT_kwDOSF9kNM59iAuv` + +- **Reviewer:** Copilot +- **File:line:** `docs/AGENT-ISSUE-WORKFLOW.md:108` +- **Outcome:** FIX + +#### Original comment + +> P0: This table row's lookup guidance (`ls docs/claims/` or `git log --grep=...`) won't let a parallel agent see live claims if claims are held on remote `claim/` branches (as in `AGENT-CLAIM-PROTOCOL.md`). Consider changing the lookup to explicitly list remote `claim/*` branches and to read claim files from those remote refs. + +#### Reply + +> Fixed. The git-native row's "Claim mechanism" cell now spells out the `claim/` branch + push-to-`origin` requirement, and the "Lookup for parallel agent" cell now reads `git fetch origin && git branch -r --list 'origin/claim/*'` (active claims) plus `ls docs/claims/` (claims merged to `main`). Composes with R2-2. + +--- + +### Thread R2-4 — `PRRT_kwDOSF9kNM59iAuy` + +- **Reviewer:** Copilot +- **File:line:** `docs/claims/README.md:17` +- **Outcome:** FIX + +#### Original comment + +> P1: "Look for live claims: `ls docs/claims/`" will only show claim files present in the currently checked-out branch. If the protocol uses pushed `claim/` branches to hold active claims, this command on `main` will not show live claims. Consider updating this README to describe how to list remote `origin/claim/*` branches and view `docs/claims/.md` from those refs. + +#### Reply + +> Fixed. The README's "How to use" list now leads with `git fetch origin && git branch -r --list 'origin/claim/*'` for active claims, `git show origin/claim/:docs/claims/.md` for reading a specific active claim, and reframes `ls docs/claims/` / `cat` as the merged-claim view. Filing-a-new-claim guidance now requires a `claim/` branch. + +--- + +### Thread R2-5 — `PRRT_kwDOSF9kNM59iAu3` + +- **Reviewer:** Copilot +- **File:line:** `docs/FIRST-PR.md:241` +- **Outcome:** FIX + +#### Original comment + +> P1: This section links to `../memory/feedback_engage_substantively_no_dismissive_closing_with_silencing_shadow_2026_04_21.md` and then states "that file is not in the repo". The file appears to exist in-repo under `memory/` (and is indexed from `memory/MEMORY.md`), so the note is misleading and may cause readers to ignore a valid reference. Either drop the "not in the repo" claim, or rewrite to accurately explain visibility/scope (e.g., if some harnesses don't ship `memory/`). + +#### Reply + +> Fixed. The note now correctly states the file is in-repo under `memory/` and indexed from `memory/MEMORY.md`, with a softened caveat that some harnesses may not surface the path by default. Verified the file exists at `memory/feedback_engage_substantively_no_dismissive_closing_with_silencing_shadow_2026_04_21.md`. + +--- + +### Thread R2-6 — `PRRT_kwDOSF9kNM59iAu8` + +- **Reviewer:** Copilot +- **File:line:** `docs/AGENT-CLAIM-PROTOCOL.md:67` +- **Outcome:** FIX + +#### Original comment + +> P0: The TL;DR "check for existing claim" commands only inspect the working tree on `main` (`ls docs/claims/` / `cat docs/claims/.md`). But per step 3 you create/push the claim on a remote branch (`claim/`), so a fresh clone of `main` will not contain active claim files. This makes the primary collision-avoidance step ineffective. Update step 2 to discover remote claim branches (e.g., list `origin/claim/*`) and to read claim files directly from those refs (e.g., via `git show origin/claim/:docs/claims/.md`) instead of `cat` on `main`. + +#### Reply + +> Fixed. TL;DR step 2 now leads with `git fetch origin` to refresh remote refs, then lists both active claims (`git branch -r --list 'origin/claim/*'`) and merged claims (`ls docs/claims/`), and shows reading active claims via `git show origin/claim/:docs/claims/.md` alongside `cat docs/claims/.md` for already-merged claims. The collision-avoidance step now actually finds active claims. + +--- + +### Thread R2-7 — `PRRT_kwDOSF9kNM59iAvD` + +- **Reviewer:** Copilot +- **File:line:** `docs/AGENT-CLAIM-PROTOCOL.md:325` +- **Outcome:** FIX + +#### Original comment + +> P1: This paragraph says to look for an existing claim file on `main`, but claims are pushed to `origin` on a branch and may never land on `main` (claim + release can both be inside the same PR). As written, `git pull` on `main` won't reveal active claims. Consider changing this to check for an existing remote `claim/` branch (or other protocol-defined remote refs) instead of checking `main` for the file. + +#### Reply + +> Fixed. The "Claim commit details" pre-commit-check paragraph now uses `git fetch origin` + `git ls-remote --heads origin "claim/"` (active claims) plus `git show "origin/main:docs/claims/.md"` (merged-but-not-released claims). Both lookups are spelled out so an agent on a fresh checkout doesn't miss active claims still in flight. + +--- + +### Thread R2-8 — `PRRT_kwDOSF9kNM59iBdM` + +- **Reviewer:** Copilot +- **File:line:** `docs/AGENT-CLAIM-PROTOCOL.md:330` +- **Outcome:** FIX + +#### Original comment + +> **P1: Enforce single claim ref for slug uniqueness** +> +> This allows claim commits to live on arbitrary branches (`claim/`, `feat/`, etc.), which breaks the lock guarantee described later: `git push` only updates the refspec you push, so two agents can each push `docs/claims/.md` on different remote branches without a non-fast-forward conflict and both think they hold the claim. Fresh evidence vs. the earlier thread is that the new text explicitly permits non-`claim/` branches, so the push-time lock disappears. + +#### Reply + +> Fixed. The "Claim commit details" paragraph now requires the claim commit to land on `claim/` specifically — that's the branch name that gives push-time slug uniqueness via non-fast-forward rejection. Work commits move to a separate working branch after the claim lands; the `claim/` branch stays as the lock until release. The previous "feature branch / work branch / speculative branch" wording is replaced with the explicit reasoning for why an arbitrary branch name fails the lock. + +--- + +### Thread R2-9 — `PRRT_kwDOSF9kNM59iBdO` + +- **Reviewer:** Copilot +- **File:line:** `docs/FIRST-PR.md:134` +- **Outcome:** FIX + +#### Original comment + +> **P2: Replace named reviewers with role references** +> +> This introduces direct reviewer names in a docs surface, which conflicts with the documented rule in `docs/AGENT-BEST-PRACTICES.md` ("No name attribution in code, docs, or skills" outside carve-outs). Keeping personal names here creates policy drift and unnecessary churn whenever reviewer rosters change; this section should use stable role references and keep identity details in the registry link. + +#### Reply + +> Fixed in three places. The introductory paragraph at line 132 is rewritten to use role refs (harsh-critic, maintainability reviewer, documentation agent) with the EXPERT-REGISTRY link as the canonical name source. Line 214's GOVERNANCE §20 reference now reads "harsh-critic + maintainability reviewers" instead of named individuals. Line 258's "What this doc is NOT" bullet now reads "the harsh-critic role" instead of a direct name. Matches the AGENT-BEST-PRACTICES.md "No name attribution in code, docs, or skills" rule. + +--- + +## Round-2 rebase summary + +Branch was rebased onto fresh `origin/main` (`134a68d`). Six commits replayed cleanly with no merge conflicts. The round-2 drain commit lands on top of those six. + +## Round-2 final state + +- Unresolved threads: 0 (target after force-push) +- mergeable: MERGEABLE (target after the force-push triggers GitHub recompute) +- Auto-merge armed: pre-existing