Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .agent/DEFERRED_VERIFICATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ is named in the commit that closes it.
| 1663afd, a327458 | MCP `emit` refuses what `validate` would refuse and takes `inbox_read`; `inbox` marks a reply to an earlier asking `stale`; driven over stdio by tests, not by an agent session | An agent may misread a refusal or ignore `stale` | One agent session using the MCP tools: a refused event, an `inbox_read` through `emit`, a stale reply seen |
| 45bc2ef | A round that is started again is allowed and counted on; tested, not seen from a real loop | A real restart shows a wrong round or a problem | A real loop restarting a round, shown on the board and passing `validate` |
| 5c6efbf, 5672f1a | The board's state lives in the user's state folder, and each repository and loop is a boundary. Seen on a running board on 2026-11-19: a watched folder whose `.loops` cannot be entered is named with the reason, a line dated 9999 and a `loop.json` that cannot be read leave every other loop shown, and Stop for another loop goes through beside the broken one. Not seen: a board started inside a watched repository that holds a planted state folder | The board reads state a repository planted | A board started inside a watched repository with a planted state folder, which it must leave unread |
| 5672f1a | A fault answers with the board's page (500); tested through the app. The 422 page was opened in Chrome on a running board (2026-11-18) | The page may not render in a real browser | The 500 page opened on a running board |
| c07643a | The overview's pulse turns an open page to stalled when a loop goes quiet; tested through the app | An open overview keeps showing running | An overview left open past 45 minutes of silence turns to stalled |
| cbe60a1 | A worktree counts only when its repository lists it back; tested with planted `.git` files | A real worktree is split from its repository, or a claim still passes | A real worktree and a folder with a `.git` file naming another repository, both on a running board |
| df0e651 | The browser is let in by the printed address (cookie `SameSite=Strict`); shown with curl and Chrome, not in Safari or Firefox | Another browser refuses the cookie on the redirect and shows the locked page | The printed address opened in Safari and Firefox, a loop page reached |
Expand All @@ -24,3 +23,5 @@ is named in the commit that closes it.
| the key per loop | Seen on a running board over the example loop on 2026-11-19: Stop wrote a line with `loop_sig` and `sig`, the key files had mode 0600 in a 0700 folder, and the example's own helper read the line as signed True. Not seen: a machine that already has an `inbox.key` and inboxes full of lines with `sig` only, and a loop with a helper pasted from the earlier text | After the upgrade earlier answers read as not from the board and a waiting question shows again, or a loop with the earlier helper stops taking a Stop | A board of the new version started on a machine with earlier loops: an earlier answer still reads as the board's (its mark is in the loop's `.earlier` list), and `loopcaptain doctor` passes on a loop with the earlier helper |
| the page limits, the open questions, the turn of a sleeping page | Seen on a running board on 2026-11-19: a loop of 75 rounds drawn 30 at a time with links to the rest, two open questions shown one after the other, an open page of a sleeping loop turning to stalled by itself, the example loop started from the board, answered with a button and going on. Not seen: the notice beside Start that a Stop is waiting, the Copy buttons of an empty board, `watch` and `unwatch` on a config a person wrote by hand, a log near 20 MB from a real loop | A wording or a layout reads worse live than in a test; a real config has a shape the line editor does not know and is written anew | Each opened or run once on a real board and a real config |
| hiding a loop, the old mark | Seen on a running board on 2026-11-19: `hide` took a waiting loop off an open first page, which reloaded by itself, out of the waiting count and the figures, the `hidden` chip listed it, its page opened with the command that shows it again, `unhide` brought it back; a loop silent for 20 days showed as stalled, marked old, outside the count of loops that need a look. Not seen: a loop hidden from one worktree and read from another, and `hide` on a config a person wrote by hand | A hidden loop comes back when its repository is read from another worktree | A loop hidden in the main checkout stays hidden while a worktree of that repository writes last |
| the waiting count in a background tab | Seen in Chrome on a running board on 2026-11-19, with the tab made to read as hidden and the notification replaced by a recorder: a second loop asked, the title went from (1) to (2) without the page being drawn again, and one notification was made. Not seen: the browser's own permission prompt answered by a person and the notification the system then shows; `status` and `inbox` were run against a real board's loops | The system shows nothing, or shows it for every poll | Notify allowed in the footer, the board's tab put behind another, a loop made to ask: one notification, and a click on it brings the tab forward |
| the site's head and the release notes | The built site carries a title, a sentence, a card picture and, on the first page, the project as data; no page loads a font from another host; a release note prints its commit's bullets. Checked on the built pages and by tests, not on the published site or a real release | A card that does not show when a link is shared; notes that read badly for a squash merge, whose body is the pull request's list of commits | A link to the published site pasted into a chat or a card checker shows the picture; the notes of the next release read well |
7 changes: 1 addition & 6 deletions .agent/FINDINGS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ in the commit that settles it. Proposed: now, later, check, drop.
| F15 | An optional exporter that tails `events.jsonl` and sends OTLP along docs/opentelemetry.md: its own process and dependency group, off by default, the first thing that would send data off the machine | open | later: when someone wants loops beside agent traces | docs/ARCHITECTURE.md section 15 |
| F17 | The tab title counts what waits; the favicon does not. A count in the icon needs a drawn image per number or script | open | later | src/loopcaptain/board/templates/overview.html |
| F18 | A prompt to build a loop, given to a fresh agent, ended with a 302-line loop file for a three-step job; a smaller starting template (one loop.py of 60 lines beside the helper) would make the first loop cheaper | open | later: check with the next acceptance run | the acceptance run of 2026-11-15 |
| F19 | "Door" is used for the two ways a loop writes its files (the MCP server's docstring and so `docs/reference/mcp.md`, `mcp_server/AGENTS.md`, `standard/LOOPS.md` section 5). A reader new to the project does not know what a door is; the architecture heading and picture now say "ways in" and name the script and MCP | open | later: reword with the next change to those files, then `make docs-pages` | `git grep -n -i door`, 2026-11-15 |
| F20 | SECURITY.md and the issue template send reporters to private security advisories, but private vulnerability reporting is switched off on the repository, so a reporter has no private way in | open | now: a repository setting, no file change | the repository's `private-vulnerability-reporting` setting read `enabled: false`; SECURITY.md:29-31, .github/ISSUE_TEMPLATE/config.yml |
| F26 | The release workflow tags and publishes on a push to main without waiting for CI: 0.3.1 was published 29 seconds after the CI run for the same commit was created | open | now: trigger on a successful CI run, or make the release job need a `make check` job | .github/workflows/release.yml:11-14, :55-66; run and upload times of 2026-11-15 |
| F34 | `a helper of 50 lines` is stale in CHANGELOG.md; the helper has 76 | open | later: the file is frozen at 0.1.0, so only if that entry is ever rewritten | CHANGELOG.md; `wc -l standard/loops.py` |
Expand All @@ -26,12 +25,9 @@ in the commit that settles it. Proposed: now, later, check, drop.
| F72 | PyPI holds no provenance attestations for the published files | open | later | PyPI file metadata of 0.3.1; .github/workflows/release.yml |
| F73 | `make setup` in a worktree repoints the main checkout's git hooks at the worktree's virtualenv | open | later: skip the install when the git dir is not the common dir, and say so in AGENTS.md section B.1 | Makefile:7-12; the installed hook's `INSTALL_PYTHON` line |
| F74 | The repository topics miss the terms people search by (agent loops, human in the loop, dashboard); one topic is shared by six repositories. Topics naming agent products would need a reading of rule 8 | open | check: add `human-in-the-loop`, `agent-monitoring`, `ai-agents`, `coding-agents`, `ralph-loop`, `local-first`, and one of `claude-code` or `agent-protocol`; a repository setting, no file change | repository topics read 2026-11-15 and 2026-11-19 |
| F75 | A shared link shows the code host's generic card, and the docs site has no card image | open | later | repository settings, zensical.toml; review of 2026-11-15 at 7e22640 |
| F76 | `How it differs` names no alternative, so a reader cannot place the project against tools they know. Naming other projects bends rule 8 | open | check: a rule change, and a section in docs/ARCHITECTURE.md | README.md `How it differs`; AGENTS.md rule 8 |
| F77 | A release note is one commit subject, and CHANGELOG.md 0.1.0 contradicts itself and the product in places | open | later: bullets from the commit body into the release note | CHANGELOG.md, scripts/release.py; the notes of 0.3.1 |
| F78 | The generated command-line reference has eleven empty descriptions, lower-cases proper names, and does not say that `emit` values parse as JSON | open | later | docs/reference/cli.md, src/loopcaptain/cli.py help texts |
| F77 | CHANGELOG.md 0.1.0 contradicts itself and the product in places (a helper of 50 lines, among others) | open | later: only if that entry is ever rewritten; the file is frozen at the first version | CHANGELOG.md |
| F80 | The standard a loop author pastes does not say what only `validate` checks beyond the JSON Schema (paths, rules across lines); a loop and a board that look at different key folders make every answer read as not from the person, with no sign on the board | open | later | standard/LOOPS.md, standard/schema/, docs/setup.md section 5; review of 2026-11-15 at 7e22640 |
| F81 | The docs site loads its fonts from a third-party host, while the board vendors its font | open | check: vendor the font in the site too | zensical.toml; requests of the built site, review of 2026-11-15 at 7e22640 |
| F83 | Small stale or author-facing statements across the standard, the site and the nested AGENTS.md files | open | later: with the next change to each file; done on 2026-11-16 for README.md, docs/index.md, docs/get-started.md, docs/installation.md, docs/agents.md and the one line in standard/AGENTS.md | git grep of the review |
| F84 | Protocol proposal held back by rule 3: the helper's `inbox()` could drop entries whose `signed` is not `true`, or that are `stale`, by default or behind an opt-in argument; today a loop filters them itself, and a call written against the earlier text must keep returning what it returned | open | later: an opt-in argument fits version 1, a new default is protocol 2 | standard/loops.py `inbox`; docs/ARCHITECTURE.md section 26, Rejected; commit a327458 |
| F89 | One loop page walks the watched folders several times per request: `find_loop`, `find_repo` and the repository list each call `find_repos(config())`. Measured on 300 folders, 100 of them with loops: 13 ms a walk, so about 50 ms of a page | open | later: one walk per request, if a board with hundreds of folders feels slow | src/loopcaptain/board/discover.py, board/app.py; measured 2026-11-19 |
Expand All @@ -46,4 +42,3 @@ in the commit that settles it. Proposed: now, later, check, drop.
| F112 | The block-list of key and credential names holds broad patterns (`secrets*`, `*.env`), so ordinary files with such names are refused too | open | check: keep them, or narrow them | src/loopcaptain/board/files.py:61-98 |
| F113 | The weekly link check reads the Markdown files only, not the built docs site; about six lines in the workflow would add it | open | check: add it, or skip | .github/workflows/links.yml |
| F114 | Discussions are off and the wiki is on with no page, so a question has no place but an issue | open | now: Discussions (Q&A) on, wiki off; a repository setting, no file change | repository settings read 2026-11-19 |
| F115 | The README gives a Ralph loop one line (`emit` once per iteration); no page walks through a worked shell loop that reports to the board | open | later: a "Monitor a Ralph loop" page | README.md:134 |
10 changes: 6 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,8 @@ Work in the loop's repository, not here, and follow
[standard/AGENTS.md](standard/AGENTS.md); propose the smallest change and
wait for a yes. Do not add this repository as a dependency of a loop. A
loop an agent session drives adds the MCP server, `loopcaptain mcp` over
stdio: `loopcaptain mcp-config <agent>` prints the line for it,
stdio, installed with its extra (`uv tool install 'loopcaptain[mcp]'`):
`loopcaptain mcp-config <agent>` prints the line for it,
[docs/agents.md](docs/agents.md) lists every agent.

### What the board does and does not do
Expand Down Expand Up @@ -142,13 +143,14 @@ stdio: `loopcaptain mcp-config <agent>` prints the line for it,
it the major one. A push with only `docs`, `test`, `chore`, `ci` or
`refactor` commits makes no release.
3. A release is a tag `vX.Y.Z` and a GitHub release whose notes are the
subjects of those commits, with the wheel attached: built with the
subjects of those commits, each with the bullets of its body below
it, with the wheel attached: built with the
tag's version, installed in a clean environment and smoke-tested first.
It goes to PyPI once the repository variable `PUBLISH_PYPI` is `true`.
4. Nothing is committed back. `pyproject.toml` says `0.0.0`; a checkout
and an install from `main` report that, a released wheel its tag.
5. A commit subject is a line of the release notes, so write it for a
user. `CHANGELOG.md` holds the first version and points to the
5. A commit subject is a line of the release notes and its bullets are
printed below it, so write both for a user. `CHANGELOG.md` holds the first version and points to the
releases.
6. The package version is not the protocol number: a release may add
optional fields and events, never break a loop written today.
Expand Down
7 changes: 6 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,9 @@ fault and the loop asks you what to do:
[standard/LOOPS.md](standard/LOOPS.md) and call it where a round and a
step begin and end, or append the JSON lines yourself.
2. **A Ralph loop or any loop around an agent's command line:** the shell
form, `loopcaptain emit <loop> <event> key=value`, once per iteration.
form, `loopcaptain emit <loop> <event> key=value` once per iteration and
`loopcaptain inbox <loop>` for your stop and notes; a worked `loop.sh` is
in [docs/shell-loop.md](docs/shell-loop.md).
3. **A long-running agent session:** add the MCP server
(`loopcaptain mcp-config <agent>`), and the session reports its rounds
through five tools.
Expand All @@ -150,6 +152,9 @@ loopcaptain validate <repository> # check a repository's .loops folders
loopcaptain doctor <repository> <loop> # does the loop take a stop?
loopcaptain mcp-config <agent> # how your agent adds the MCP server
loopcaptain emit <loop> <event> key=value # one event from a shell loop
loopcaptain inbox <loop> # what you sent it, for a shell loop to read
loopcaptain status # where every loop stands, in the terminal
loopcaptain hide <repository> <loop> # one loop off the first page
```

From a checkout, put `uv run` in front, or use the `make` targets in
Expand Down
14 changes: 7 additions & 7 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -557,8 +557,8 @@ would still vanish.
the line's `event` (`event_tag`); a name not in `EVENT_NAMES` reads as
`OtherEvent`, which the fold skips and which still counts as a sign of
life. `validate` warns (`unknown_events`). The published schema takes any
other event name with a `ts`. Writing stays strict: both `emit` doors
take known events only.
other event name with a `ts`. Writing stays strict: `emit` on the command
line and `emit` over MCP take known events only.

**Why.** Version 1 grows by new events, and the standard tells a board to
ignore what it does not know. A reader that refused them would call the
Expand Down Expand Up @@ -594,21 +594,21 @@ only grows). Raising an error without a key: a loop on a machine where no
board has run yet would not start. A new event for the case: boards
installed before unknown events were skipped would call it a problem.

## 27. A door refuses an event that would stay a problem, and no more
## 27. A way in refuses an event that would stay a problem, and no more

**Decision.** `before_writing` in `protocol/validate.py` holds what the
two doors that write on a loop's behalf check, the MCP `emit` and
two ways in that write on a loop's behalf check, the MCP `emit` and
`loopcaptain emit`. `refusals` (the round has started, the step is in
`loop.json`, the artifact exists, the verdict agrees with the round's
first) refuses an event: the door writes nothing. An `inbox_read` naming
first) refuses an event: nothing is written. An `inbox_read` naming
an entry the models cannot read is written with a warning; where
`loop.json` or the log cannot be read (over the size the reader takes,
unreadable), the event is written without the checks against the log,
with a warning. The MCP `emit` adds the warning to its answer,
`loopcaptain emit` writes it to standard error. Both take `inbox_read`.

**Why.** The log is append-only, so a line `validate` refuses is refused
for good; a writer that hears `recorded` never learns it. A door that
for good; a writer that hears `recorded` never learns it. A way in that
refuses more than `validate` calls a problem stops a loop for nothing.
The standard has a loop append `inbox_read` after acting on entries, and
a loop that reads the inbox file itself has no other way to mark them;
Expand All @@ -619,7 +619,7 @@ loop still has to report.

**Rejected.** Writing the line and returning the problems with it: the
problem is then permanent, and the caller can only add to it. Refusing
`inbox_read` on both doors: a shell loop would have to write the line by
`inbox_read` on both ways in: a shell loop would have to write the line by
hand, without any check of its ids. Refusing an unreadable entry or an
unreadable log: the loop could not report at all. Writing such a line
silently: the writer would not know its line went unchecked.
Expand Down
4 changes: 0 additions & 4 deletions docs/BACKLOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,3 @@ picked are in the ledgers in `.agent/`.

| # | Item | From | Picked |
|---|---|---|---|
| 1 | `loopcaptain status`: where every watched loop stands, in a terminal. `load_all` in `board/discover.py` already returns what it would print; nothing in the protocol changes | F64 | 2026-11-19 |
| 2 | `loopcaptain inbox <loop>`: read a loop's inbox from a shell, and one worked shell loop in the docs, so the shell route the README promises is whole | F49 | 2026-11-19 |
| 3 | Tell the person a loop waits while the board's tab is in the background: a count in the tab's title and a browser notification, on 127.0.0.1 only, nothing loaded from another origin | F65 | 2026-11-19 |
| 4 | The MCP SDK becomes an extra, `loopcaptain[mcp]`: a plain install pulls in about half as much, `loopcaptain mcp` without the extra says what to install, and the install line for agent sessions in the docs names the extra | F70 | 2026-11-19 |
Loading
Loading