diff --git a/.claude/settings.json b/.claude/settings.json index a3414ce..d81de46 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -73,7 +73,7 @@ { "hooks": [ { - "command": "~/.local/bin/enola hook session-start", + "command": "command -v enola >/dev/null 2>&1 && enola hook session-start || true", "source": "enola", "timeout": 60, "type": "command" @@ -90,7 +90,7 @@ "type": "command" }, { - "command": "~/.local/bin/enola hook stop", + "command": "command -v enola >/dev/null 2>&1 && enola hook stop || true", "source": "enola", "timeout": 60, "type": "command" @@ -126,7 +126,6 @@ "Bash(mempalace wake-up:*)", "Bash(mempalace mine:*)", "Bash(mempalace split:*)", - "Bash(~/.local/share/mempalace-venv/bin/python3 tools/brain.py:*)", "Bash(python3 tools/brain.py:*)", "Bash(python tools/brain.py:*)", "Bash(tools/brain:*)", diff --git a/.claude/skills/pr/SKILL.md b/.claude/skills/pr/SKILL.md index e05b72f..1e3da2d 100644 --- a/.claude/skills/pr/SKILL.md +++ b/.claude/skills/pr/SKILL.md @@ -109,18 +109,15 @@ git commit -m "" If multiple coherent changes, multiple commits. If a single change spans many files, one commit is fine. -Co-author footer (Claude Code already adds this when committing on -the agent's behalf — preserve it): - -``` -Co-Authored-By: Claude -``` - -**No personal data in the commit message or the PR body.** Model -attribution (`Co-Authored-By`) is fine; **session URLs, private -chat links, tokens, emails, and other account-tied identifiers are -not** — this is a shared and potentially public repo. If your -harness appends a session URL by default, strip it. The commit-msg +**No AI attribution.** No `Co-Authored-By` line naming an assistant, +no "generated with" line, no session link, in the commit message or +the PR body. If your harness adds one by default, strip it before the +commit lands. + +**No personal data in the commit message or the PR body.** Session +URLs, private chat links, tokens, emails, and other account-tied +identifiers never appear: this is a shared and potentially public +repo. If your harness appends a session URL by default, strip it. The commit-msg git hook (`brain.py check-no-personal-data`) rejects a commit whose message carries a session URL; run the same check on the PR body before creating: diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b4220c9..ce365dc 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,5 +6,5 @@ Link where the work comes from inline (the decision, the discussion, the issue, the source page). Keep it out of the public record: no session URLs, private links, -tokens, or emails. +tokens, or emails, and no AI attribution lines. --> diff --git a/AGENTS.md b/AGENTS.md index 1b9ebd8..f68bc8c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -369,15 +369,20 @@ distinction. Decision-matrix-style tables in those pages are PR descriptions, commit messages, and release notes are shared — and on a public repo, world-readable. They **must not** contain session URLs, private chat links, tokens, emails, or other -account-tied identifiers. Model attribution (`Co-Authored-By: -Claude …`) is fine; a session URL is not. +account-tied identifiers. **No AI attribution** either: no +`Co-Authored-By` line naming an assistant, no session link, no +"generated with" line. The author is the contributor of record and a +tool is not a co-author. This overrides any harness default that adds +such markers; strip them before the commit or the body lands. Enforced deterministically: the `commit-msg` git hook runs `brain.py check-no-personal-data` (session-URL / account-link patterns; extend per-org via a git-ignored `.personal-data-patterns` file), and the `/pr` skill runs the same check on the PR body. If a harness appends a session URL by default, strip it — the guard -does not depend on the harness behaving. +does not depend on the harness behaving. The guard matches session +URLs only; the no-attribution rule is a policy the author keeps, not +something the hook checks. ### Audit log @@ -1294,7 +1299,18 @@ HMAC keys (`agent-key issue|rotate|revoke`); on this tier every `wiki/_state/events` (authored by the authenticated agent), and `GET /api/events?since=` is the authenticated read. The auth boundary rejects forged appends at write time and drops tampered lines -on read. **Owner-subscription wake**: an agent `subscribe`s to a +on read. **Trust model, plainly:** the keys are symmetric (HMAC), so the +hub holds every agent's secret and can sign as any of them; there is no +replay or timestamp check; the stream is append-only by convention, not +enforced; and verification runs against the *current* keyring, so +revoking or rotating a key makes that agent's earlier events fail +verification and disappear from reads. "Authenticated" means "signed by +a holder of that agent's key", not "provably only that agent". Asymmetric +keys would remove the forgery limit and are not built. Event `seq` +assignment and append are serialized by a lock. The tier has no deploy +story: `deploy/` serves the three read-only surfaces only, and the hosted +tier is exercised locally by `tools/emulate-agentic.py`. +**Owner-subscription wake**: an agent `subscribe`s to a ref-pattern with a wake URL (a signed subscribe event); a matching append POSTs a signed hint (seq + ref, no payload) to the owner through an SSRF guard, capped per event, with the per-agent cursor as the diff --git a/CHANGELOG.md b/CHANGELOG.md index 355b256..cf08a81 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,45 @@ All notable changes to the brain kernel. Versions correspond to shipped roadmap slices (`wiki/brain/roadmap.md` holds the full narrative; the ADR shelf holds the decisions). +## 0.31.1, 2026-10-25 +Final polish: documentation made to match the code, and defects that +could mislead or hurt a user fixed. No new features. +- Scheduling: `schedule run-due` now honours `cadence:` (daily, weekly, + monthly; last runs are recorded under `ran` in + `wiki/_state/schedule.json`) and takes `--force` to run everything. It + writes the producer heartbeat after every completed run and records + which jobs failed in it, so `doctor` and the app strip report a failing + job as failing and a running producer as running (a new `failing` + state beside `current`, `stalled`, `never`). Before, one failing job + withheld the heartbeat and the producers read as dead. +- `overlap-refresh` no longer writes `No module named 'sklearn'` into a + report and records `ok`. Without scikit-learn it writes nothing and + records a named `skipped`; a failing cluster run records a failure. + scikit-learn is declared as the optional `cluster` extra. +- Event stream: `seq` assignment and append are now one locked step + (thread lock plus a file lock where `flock` exists). The docs and the + code comments state the real trust model: symmetric keys (the hub can + sign as any agent), no replay or clock check, append-only by + convention, and a revoked or rotated key makes that agent's history + fail verification and vanish from reads. +- `tools/emulate-agentic.py` refuses to start when the repository + already has a keyring, cursors or event stream, instead of deleting + them. +- `.claude/settings.json` calls `enola` from `PATH` and skips the hook + when it is absent, rather than a machine-specific absolute path that + `init --full` copied into every instance. The machine-specific + permission entry is gone too. +- Specialized agents say they emit a note on the event stream; nothing + moves those notes into the tend inbox, and the docs now say so. +- Seven wiki pages that claimed `confidence: high` with a 2026-07-10 + `updated:` date were demoted to `medium`: `reflection-check` failed on + them every day, and so did a freshly born instance. +- Contribution policy: no AI attribution in commits or pull requests. +- Documentation: this changelog gains 0.21.0 to 0.30.0 (reconstructed, + see the note there); the roadmap, state page, README, CONTRIBUTING + and `AGENTS.md` corrected for skill count, subcommands, dependencies + and the hosted tier's missing deploy story. + ## 0.31.0 — 2026-08-06 - Intent compilation: every wiki page carries a derived `enola_intent:` block (`brain.py intent stamp`, idempotent — kind → type, repos → @@ -28,6 +67,64 @@ narrative; the ADR shelf holds the decisions). fallback now finds `sources:` mid-frontmatter (it anchored on end-of-string, which the stamped block broke). +## 0.30.0, 2026-07-14 +*0.21.0 to 0.30.0 were reconstructed on 2026-10-25 from git history +(`VERSION` bumps, one per merged pull request) and +`wiki/brain/state.md`; they were not written at release time, and only +`v0.20.0` and `v0.31.0` were tagged.* +- Specialized spoke agents under `tools/agents/` (a drift-reconciler and + an observability-triage agent) that subscribe, do deterministic prep + and emit a note on the event stream; never an LLM. +- `tools/emulate-agentic.py`: the whole hub-and-spoke loop on one + machine (real hub, real agents, emulated producers). +- `agent-key provision ` prints the env, listener and subscribe + block that wires a harness in. + +## 0.29.0, 2026-07-14 +- Spoke client `tools/brain-agent.py` (`emit`, `pull`, `subscribe`, + `listen`), stdlib-only, mirroring the server's signing; `POST + /api/events` is the matching authenticated agent write endpoint. + +## 0.28.0, 2026-07-14 +- Owner-subscription wake: `subscribe --agent --pattern --wake-url`; a + matching event sends a signed webhook hint (seq and ref, no payload) + through an SSRF guard, capped at 32 per event, with the per-agent + cursor as the at-least-once backstop. + +## 0.27.0, 2026-07-14 +- Per-agent identity and a signed event stream for the hosted tier + (`BRAIN_HOSTED=1`): `agent-key issue|rotate|revoke`, `events + emit|since|verify`, `GET /api/events?since=`. Keys and the stream + are git-ignored runtime state. Local-first is unchanged. + +## 0.26.0, 2026-07-14 +- Graph provenance and drift shown as page trust signals: a "pages rely + on this" chip and an "uncertain but load-bearing" banner. + +## 0.25.0, 2026-07-14 +- Topics lead with an executive brief and collapse the discussion; the + compose form stays hidden until opened. + +## 0.24.0, 2026-07-14 +- One collaboration control on every card, page and thread (comment, + queue, post, plus edit and remove of your own pending items); + `/api/act` gains `edit` and `remove`, `/api/pending` lists them. + +## 0.23.0, 2026-07-14 +- Async conversation surface over the inbox: `/channels/`, a Thread + panel on each topic, server-stamped attribution, post text fenced as + untrusted data. + +## 0.22.0, 2026-07-14 +- Deterministic structure connector (source inventory and Python + symbols, no network or LLM) writing snapshots to `sources/structure/` + and queueing drift inbox items; ships off. + +## 0.21.0, 2026-07-14 +- Per-edge provenance on the link graph (`wiki/_views/graph.json`: + extracted, inferred, ambiguous), rendered at `/graph/` and surfaced in + MCP page reads. + ## 0.20.0 — 2026-07-12 - Playthrough-sweep delivery: all eight three-persona suggestions built, merged, and graduated to the approved ADR/PRD shelves — diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 24dfbd3..d1f84b9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,13 +19,23 @@ agents alike. - **No personal data in public artifacts.** PR descriptions, commit messages, and release notes must not contain session URLs, private links, tokens, emails, or account-tied identifiers. The PR template - (`.github/pull_request_template.md`) sets the shape; model - attribution (`Co-Authored-By`) is fine, a session URL is not. + (`.github/pull_request_template.md`) sets the shape. +- **No AI attribution.** Commits and PRs carry no `Co-Authored-By` + line naming an assistant, no session link and no "generated with" + line. The author is the contributor of record; a tool is not a + co-author. If a harness adds such a line by default, strip it before + the commit lands. (The commit-msg hook checks session URLs only; the + rest is yours to keep.) - Agent-authored content starts at `confidence: low` (or `medium` with cited evidence) and cannot self-promote to `high` in the same change. -- Kernel code is stdlib-only Python by design; the UI is the only - npm surface. A new dependency is an ADR-sized decision. +- Kernel code uses the standard library plus two declared packages: + `pyyaml` (required) and `tiktoken` (listed in `requirements.txt`; the + tools run without it but fall back to a rough token estimate, so + committed `wiki/_views/` drift from CI's unless it is installed). + `scikit-learn` is optional (the `cluster` extra, used by the + overlap job). The UI is the only npm surface. A new dependency is an + ADR-sized decision. - Discussion belongs in `wiki//topics/` (dated, attributed entries), not in issue threads the corpus can't cite. diff --git a/README.md b/README.md index c23615b..8292cba 100644 --- a/README.md +++ b/README.md @@ -88,10 +88,20 @@ The **kernel** — mechanism, no content: layers (sources → wiki → schema), three levels (brain / org / repo), page kinds, governance, the `/shape` workflow, `ai_suggestion` discipline. -- **`tools/`** — `brain.py` (validate / check / views / search / - stats / status / schedule / sync-cursor / install-sibling / init), - the stdio MCP server, sibling-repo sync, local hooks, page - templates. +- **`tools/`**: `brain.py`, one CLI with 42 subcommands (`brain.py + --help` lists them): the corpus gates (`validate`, `check`, + `reflection-check`, `check-home-fresh`, `check-readme-fresh`, + `check-no-notion-writes`, `check-no-personal-data`), reading and + views (`views`, `stats`, `coverage`, `search`, `index`, `query`, + `page`, `links`, `lint-page`, `verify-claims`, `personas`, `cluster`), + the queue and operations (`inbox`, `attention`, `schedule`, `doctor`, + `status`, `setup`, `serve`, `rotate-log`, `efforts`, `rebase`, + `promote`, `snapshot`), connectors and the graph (`structure`, + `enola`, `intent`, `sync-cursor`), the hosted tier (`agent-key`, + `events`, `subscribe`, `subscriptions`) and birth and reach (`init`, + `install-agent`, `install-sibling`). Beside it: the stdio MCP server, + the spoke client, specialized agents, sibling-repo sync, local hooks + and page templates. - **`.claude/`** — the full slash-command surface (`/in`, `/capture`, `/ask`, `/sync`, `/groom`, `/attention`, `/shape`, `/continue`, `/zoom-out`, @@ -301,7 +311,16 @@ personal data, no boilerplate. | Structure | ✅ pull connector | Deterministic code-shape snapshots (source inventory + Python symbols) → architectural-drift inbox items via baseline diff; drift auto-clears once a wiki page cites the snapshot. No network / binary / LLM; read-only git with a clean-tree guard. Configure `connectors.structure.repos`. `brain.py structure findings` turns those facts into conservative, computed findings (`oversized-package`, `god-file`, and `symbol-blindness`, which reports the share of a repo the substrate cannot see past file level — symbol visibility is Python-only). `brain.py structure judge` records accepted / rejected / noise into a write-on-judgment ledger with **no pending state**: absence means unjudged, not queued. Per [`wiki/brain/adrs/structure-findings-and-verdict-ledger.md`](wiki/brain/adrs/structure-findings-and-verdict-ledger.md). | | Architecture graph | ⬜ optional tier | `brain.py enola` — cluster snapshots over the same repos via the external [enola](https://github.com/enola-labs/enola) binary, with committed receipts in `wiki/_state/enola/`, drift reporting, merged explainer findings, a verdict ledger, `impact ` (fan-in / fan-out / named callers) from the on-disk fact set, `baseline` + `check` (grades a change against a pinned before — **reports, never gates**; its `declined` verdict means the snapshots were not comparable and reads as *not asked*, never as a pass), `coverage` (which cross-repo edges resolved, so a genuinely isolated service reads apart from one whose edges could not be followed), `explain`, `doctor` (whether the session hooks are *firing*, not merely configured), and an experimental `history` family (`log` / `show` / `diff` / `blame` / `gc`) that answers *when* something entered the architecture — a question a snapshot structurally cannot. The wiki itself compiles into this graph: every page carries a derived `enola_intent:` block (`brain.py intent stamp`, auto-restamped by the pre-commit hook, gated by the `intent-page-block` detector and preflight), repo citations become page-to-code anchors, and `enola govern ` answers the reverse query — *which compiled pages govern this file or symbol* (with relation trails), or, for a page path, *which code its anchors cover*. Verdict compilation went live with enola v0.3.9 (2026-08-06, the first release carrying the upstream intent standard from enola-labs/enola#197); under an older pinned binary the blocks still compile forward-compatibly and `govern` answers *no knowledge pages compiled* — a named skip, never an error. See [`wiki/brain/topics/intent-compilation.md`](wiki/brain/topics/intent-compilation.md). Session hooks are available via `enola install --hooks`: a baseline pinned at session start and a regression reported at session end, which is the one place the graph speaks unasked. The **ceiling** to the structure connector's **floor**: it answers what in-kernel extraction cannot, and it is allowed to be absent — nothing may depend on it being installed. Note the trade the other way: the connector reads `git ls-files` and therefore sees only *tracked* files, while enola walks the filesystem — so the ignore list is the only thing between the graph and a vendored dependency tree. The defaults exclude `.venv`, `site-packages`, `node_modules`, build output and the usual caches; extend them per repo via `connectors.enola.ignore`. The cluster is generated from `brain.config.yml` (`active_repos` + `connectors.enola.repos`); the generated `mcp-arch.yaml` and all `.enola/` artifacts are gitignored. | -**Twelve of the twenty-five skills consult these substrates**, and every +| GitHub | via `gh` CLI | Pre-allowed in `.claude/settings.json`. | +| MCP | ✅ `tools/brain-mcp.py` | Read-only; stdio or `--http` (loopback Host + Origin checks); `BRAIN_SERVING=1` excludes ai-suggestion drafts across *every* read surface (MCP, serve JSON API, search CLI, static build) + query audit log. | +| Hosted tier | ✅ `BRAIN_HOSTED=1` (runs locally; no deploy story) | Authenticated, writable multi-agent tier. Per-agent symmetric HMAC keys (the hub can sign as any agent; see the trust notes in the agentic-tier section); `POST /api/events` is the agent write endpoint (any signed event kind) and `/api/act` writes are signed events too; `GET /api/events?since=` is the authenticated read; the auth boundary rejects appends with a mismatched signature at write time and drops lines that fail verification on read. **Owner-subscription wake**: subscribe to a ref-pattern with a wake URL, and a matching event POSTs a signed hint (seq + ref, no payload) through an SSRF guard, capped per event, with the cursor as the at-least-once backstop. Off by default — local-first is byte-for-byte unchanged. | +| Spoke client | ✅ `tools/brain-agent.py` | The harness-side half: an agent in any harness runs it to `emit` / `pull` / `subscribe` / `listen` against a hosted brain, mirroring the server's signing. Config via `BRAIN_URL` / `BRAIN_AGENT_ID` / `BRAIN_AGENT_SECRET`. The brain is the hub; the harness stays the execution spoke. `agent-key provision ` emits the env + listener + subscribe block to wire a harness in. | +| Specialized agents | ✅ `tools/agents/` | Spoke agents that subscribe + react deterministically (wake → prep → emit a result note on the event stream, never an LLM; the note is not copied into the tend inbox): a drift-reconciler and an observability-triage agent (Sentry/Datadog/Langfuse-shaped alerts). Real observability integrations become connectors emitting the same alert events. | +| Local emulation | ✅ `tools/emulate-agentic.py` | Runs the whole agentic loop on one machine — real hub + real spoke agents + emulated producers → wakes → reactions on a signed stream. No deployment; a live smoke test of the real code paths. It uses this repository's own keyring and event stream paths, so it refuses to start where either exists; run it in a throwaway checkout. | +| Datasette | ✅ pilot | `tools/serve-datasette.sh` — faceted browse + SQL + JSON API over the derived index (immutable mode). | +| mempalace | optional | Verbatim / semantic-recall layer. | + +**Twelve of the twenty-six skills consult these substrates**, and every one names both tiers in order — the structure connector first because it always answers, the graph tier second because it is allowed to be absent. `/sync` reports an architecture-drift step and the finding *count* (never @@ -314,15 +333,6 @@ stale-citation triggers; and `/ask`, `wiki-query`, `wiki-plan`, `review`, `zoom-out`, `wiki-overlap` and `wiki-coverage` each gain the consultation their own judgment step was missing. -| GitHub | via `gh` CLI | Pre-allowed in `.claude/settings.json`. | -| MCP | ✅ `tools/brain-mcp.py` | Read-only; stdio or `--http` (loopback Host + Origin checks); `BRAIN_SERVING=1` excludes ai-suggestion drafts across *every* read surface (MCP, serve JSON API, search CLI, static build) + query audit log. | -| Hosted tier | ✅ `BRAIN_HOSTED=1` | Authenticated, writable multi-agent tier. Per-agent HMAC keys; `POST /api/events` is the agent write endpoint (any signed event kind) and `/api/act` writes are signed events too; `GET /api/events?since=` is the authenticated read; the auth boundary rejects forged appends at write time and drops tampered lines on read. **Owner-subscription wake**: subscribe to a ref-pattern with a wake URL, and a matching event POSTs a signed hint (seq + ref, no payload) through an SSRF guard, capped per event, with the cursor as the at-least-once backstop. Off by default — local-first is byte-for-byte unchanged. | -| Spoke client | ✅ `tools/brain-agent.py` | The harness-side half: an agent in any harness runs it to `emit` / `pull` / `subscribe` / `listen` against a hosted brain, mirroring the server's signing. Config via `BRAIN_URL` / `BRAIN_AGENT_ID` / `BRAIN_AGENT_SECRET`. The brain is the hub; the harness stays the execution spoke. `agent-key provision ` emits the env + listener + subscribe block to wire a harness in. | -| Specialized agents | ✅ `tools/agents/` | Spoke agents that subscribe + react deterministically (wake → prep → queue a result note, never an LLM): a drift-reconciler and an observability-triage agent (Sentry/Datadog/Langfuse-shaped alerts). Real observability integrations become connectors emitting the same alert events. | -| Local emulation | ✅ `tools/emulate-agentic.py` | Runs the whole agentic loop on one machine — real hub + real spoke agents + emulated producers → wakes → reactions on a signed stream. No deployment; a live smoke test of the real code paths. | -| Datasette | ✅ pilot | `tools/serve-datasette.sh` — faceted browse + SQL + JSON API over the derived index (immutable mode). | -| mempalace | optional | Verbatim / semantic-recall layer. | - ## The agentic tier — hub-and-spoke (advanced, off by default) The brain is **not** a harness and never runs your agents — but it can @@ -331,9 +341,10 @@ harnesses. Turn on the hosted tier (`BRAIN_HOSTED=1`) and: - Each agent gets a **per-agent identity** (`agent-key issue`) — an HMAC key that signs everything it writes. -- Agents write to a **signed, append-only event stream** and read it - from a per-agent cursor. The auth boundary rejects forged appends at - write time and drops tampered lines on read. +- Agents write to a **signed event stream** (append-only by + convention) and read it from a per-agent cursor. The auth boundary + rejects appends whose signature does not match the claimed agent's key + and drops lines that fail verification on read. - An agent **subscribes** to what it cares about (a repo, a thread, a producer) and is **woken** when a matching event lands — a webhook hint (seq + ref, no payload) through an SSRF guard, with the cursor as @@ -345,15 +356,36 @@ harnesses. Turn on the hosted tier (`BRAIN_HOSTED=1`) and: in. - **Specialized agents** (`tools/agents/`) subscribe and react *deterministically* — a drift-reconciler, an observability-triage - agent — waking, prepping, and queuing work for a tend session, never - invoking an LLM. + agent, waking, prepping, and emitting a `note` event with the result, + never invoking an LLM. Those notes live on the event stream (read them + with `events since`); nothing copies them into the tend inbox + (`wiki/_state/inbox/`) that `/tend` digests. See the whole loop without deploying anything: ```bash python3 tools/emulate-agentic.py # real hub + real agents + emulated producers, on one machine + # (run in a throwaway checkout; refuses if a keyring or stream exists) ``` +**What the signatures do and do not prove.** Keys are symmetric +(HMAC-SHA256), so the hub holds every agent's secret and can sign as any +of them, and so can anyone who can read the keyring (`agent-keys.json`, +git-ignored, mode 0600). A valid signature means "a holder of this +agent's key wrote it", not "only this agent could have". There is no +replay or timestamp check. Nothing enforces append-only beyond the code +path (the files can be edited). Verification runs against the current +keyring, so revoking or rotating a key makes that agent's earlier events +fail verification and vanish from every read. Appends are serialized so +each event gets a unique `seq`. Asymmetric keys would fix the forgery +limit; they are not built. + +**There is no deploy story for this tier.** `deploy/` ships the three +read-only surfaces only; the hosted tier is run and tested locally +(`tools/emulate-agentic.py`, which starts a hub on loopback). Deploying +a hub (hosting, TLS, key distribution, an identity-aware proxy) is +open and unplanned. + With the tier off, **local-first is byte-for-byte unchanged** — no keyring, no stream, no daemon, no subscriptions. The two settled principles hold throughout: no scheduled LLM (a wake is a hint, not a diff --git a/VERSION b/VERSION index 26bea73..f176c94 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.31.0 +0.31.1 diff --git a/brain-schedule.yml b/brain-schedule.yml index 164e5eb..fb389fb 100644 --- a/brain-schedule.yml +++ b/brain-schedule.yml @@ -1,15 +1,16 @@ # brain-schedule.yml — declarative recurring operations. # -# This config is portable (cron / GitHub Actions / Claude Code's -# ScheduleWakeup all consume the same shape). The runtime that -# executes is separate; v1 ships the config + listing only. +# `cadence:` (daily, weekly or monthly) is honoured by `run-due`: an +# operation runs only when that many days have passed since it last +# ran (recorded under `ran` in wiki/_state/schedule.json). `run --target` +# always runs one operation; `run-due --force` ignores cadence. # # `brain.py schedule list` prints these. -# `brain.py schedule run ` invokes a single op. -# `brain.py schedule run-due` invokes every op whose `next_run` is -# past. The runner that fires on cron lives in -# .github/workflows/scheduled.yml (proposed) or as a Claude Code -# /loop routine (proposed) — separate decision. +# `brain.py schedule run --target ` invokes a single op. +# `brain.py schedule run-due` invokes every enabled op that is due. +# The runner that fires it is the OS timer installed by +# tools/install-timer.sh (systemd user timer); scheduled.yml is a +# manual-only GitHub Actions dispatch for a one-off CI-side refresh. version: 1 diff --git a/log/log.md b/log/log.md index b49e214..2b4929a 100644 --- a/log/log.md +++ b/log/log.md @@ -385,3 +385,6 @@ 2026-08-06 merge — PR #49: Scrub the origin client's lineage from the attention-board slice diff: 4 files, +31/-22 restricted-paths: false +2026-10-25 commit — 91c8aa8: Final polish 0.31.1 (docs true to code, health, cadence, trust model, attribution policy) + diff: 38 files, +547/-144 + restricted-paths: true diff --git a/pyproject.toml b/pyproject.toml index c0244e0..30aacb5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -16,7 +16,8 @@ dependencies = ["pyyaml>=6"] dynamic = ["version"] [project.optional-dependencies] -full = ["tiktoken", "datasette", "pytest"] +cluster = ["scikit-learn"] +full = ["tiktoken", "datasette", "pytest", "scikit-learn"] [project.scripts] brain = "tools.brain:main" diff --git a/tests/test_identity_events.py b/tests/test_identity_events.py index f01f951..a093118 100644 --- a/tests/test_identity_events.py +++ b/tests/test_identity_events.py @@ -386,6 +386,42 @@ class _Args: assert brain._agent_secret("harness-agent") # key was issued +def test_concurrent_appends_get_unique_seqs(monkeypatch, tmp_path): + """seq assignment and append are one locked step: threaded appends + never share a seq.""" + import threading + _isolate(monkeypatch, tmp_path) + brain.agent_key_issue("racer") + results = [] + + def emit(): + for _ in range(10): + results.append(brain.event_emit("racer", "note", "r")["seq"]) + + threads = [threading.Thread(target=emit) for _ in range(8)] + for t in threads: + t.start() + for t in threads: + t.join() + assert sorted(results) == list(range(80)) + + +def test_emulation_refuses_where_a_keyring_exists(monkeypatch, tmp_path): + """The emulation deletes the keyring and stream it finds, so it must + refuse to start when a live one exists.""" + import importlib.util + spec = importlib.util.spec_from_file_location( + "emulate_agentic", REPO / "tools" / "emulate-agentic.py") + emu = importlib.util.module_from_spec(spec) + spec.loader.exec_module(emu) + _isolate(monkeypatch, tmp_path) + assert emu._live_state() == [] + brain.agent_key_issue("precious") + assert emu._live_state() == [brain.AGENT_KEYS] + assert emu.main() == 2 + assert brain.AGENT_KEYS.exists(), "refusal must leave the keyring alone" + + def test_emulation_runs_the_whole_loop(): """The local emulation drives the real hub + spoke agents + handlers end to end: producers fire, specialized agents wake, and their result diff --git a/tests/test_setup_doctor.py b/tests/test_setup_doctor.py index 3cee918..d5636c2 100644 --- a/tests/test_setup_doctor.py +++ b/tests/test_setup_doctor.py @@ -87,8 +87,9 @@ def test_producer_health_states(tmp_path, monkeypatch): def test_check_no_personal_data_rejects_session_url(tmp_path): - """The commit-msg guard rejects session URLs but passes clean - messages (incl. Co-Authored-By model attribution).""" + """The commit-msg guard rejects session URLs and passes other + messages. It matches session URLs only: the no-AI-attribution rule + is contribution policy, not something the hook checks.""" import subprocess import sys from pathlib import Path @@ -101,3 +102,29 @@ def run(text): assert run("fix\n\nClaude-Session: https://claude.ai/code/session_ABC") == 1 assert run("fix\n\nCo-Authored-By: Claude ") == 0 assert run("a normal message") == 0 + + +def test_producer_heartbeat_reports_failed_jobs(tmp_path, monkeypatch): + """A completed run touches the heartbeat even when a job failed; the + health reads as failing (running, jobs broken), never as stalled.""" + monkeypatch.setattr(brain, "PRODUCER_HEARTBEAT", tmp_path / "hb.json") + brain._producer_touch(["overlap-refresh"]) + health = brain._producer_health() + assert health["state"] == "failing" + assert health["failed"] == ["overlap-refresh"] + brain._producer_touch([]) + assert brain._producer_health()["state"] == "current" + + +def test_cadence_elapsed(): + today = brain.today_utc() + iso = lambda days: (today - __import__("datetime").timedelta(days=days)).isoformat() + assert brain._cadence_elapsed("daily", None) + assert brain._cadence_elapsed("daily", iso(1)) + assert not brain._cadence_elapsed("daily", iso(0)) + assert not brain._cadence_elapsed("weekly", iso(3)) + assert brain._cadence_elapsed("weekly", iso(7)) + assert not brain._cadence_elapsed("monthly", iso(29)) + assert brain._cadence_elapsed("monthly", iso(30)) + assert brain._cadence_elapsed("fortnightly", iso(0)) + assert brain._cadence_elapsed("daily", "not-a-date") diff --git a/tools/agents/drift_reconciler.py b/tools/agents/drift_reconciler.py index 450b07c..ae86a4d 100755 --- a/tools/agents/drift_reconciler.py +++ b/tools/agents/drift_reconciler.py @@ -3,9 +3,11 @@ Subscribes to repo structure-drift events. On wake it does deterministic prep — identifies the repo whose code shape moved — and emits a -`reconcile:` note, so a tend session in a harness updates that -repo's architecture.md against the snapshot. It never reasons itself; -it turns a drift event into queued, attributable reconciliation work. +`reconcile:` note on the event stream, which a session in a +harness can read (`events since`) and act on by updating that repo's +architecture.md against the snapshot. It never reasons itself; it turns +a drift event into an attributable note. Nothing moves that note into +the tend inbox (`wiki/_state/inbox/`) today; the stream is its queue. Run as: brain-agent listen --on-wake "python3 tools/agents/drift_reconciler.py" (with the agent's BRAIN_URL / BRAIN_AGENT_ID / BRAIN_AGENT_SECRET set). @@ -27,7 +29,7 @@ def main() -> int: repo = ev.get("ref", "").split(":", 1)[-1] or "unknown" spoke().emit("note", f"reconcile:{repo}") print(f"drift-reconciler: {repo} drifted (event seq {ev.get('seq')}) — " - f"queued reconcile:{repo} for the next tend") + f"emitted reconcile:{repo} note on the event stream") return 0 diff --git a/tools/agents/observability_triage.py b/tools/agents/observability_triage.py index bd160ee..a3736bd 100755 --- a/tools/agents/observability_triage.py +++ b/tools/agents/observability_triage.py @@ -5,8 +5,9 @@ Langfuse — emulated locally, real ones would be connectors). On wake it triages deterministically: parses the source and level, assigns a severity by a simple heuristic, and emits a `triage::` -note for a tend session to act on. No LLM — deterministic prep only; the -severity call is a lookup, and the reasoning is queued for a harness. +note on the event stream for a harness session to read and act on (it is +not copied into the tend inbox). No LLM, deterministic prep only; the +severity call is a lookup, and the reasoning is left to a harness. Alert ref shape: alert::: e.g. alert:sentry:error:issue-4821 · alert:datadog:warning:mon-77 @@ -40,7 +41,7 @@ def main() -> int: severity = SEVERITY.get(level.lower(), "low") spoke().emit("note", f"triage:{source}:{severity}:{ident}") print(f"observability-triage: {source} {level} ({ident}) → " - f"severity {severity} — queued triage note") + f"severity {severity}, emitted triage note on the event stream") return 0 diff --git a/tools/brain.py b/tools/brain.py index 6324f5a..1db722e 100755 --- a/tools/brain.py +++ b/tools/brain.py @@ -35,6 +35,7 @@ import argparse import ast import collections +import contextlib import datetime as dt import fnmatch import functools @@ -92,21 +93,25 @@ PRODUCER_STALE_HOURS = 36 # a daily timer past this is stalled, not calm -def _producer_touch() -> None: - """Heartbeat written by `schedule run-due` (what the timer runs) - so producer freshness is observable without depending on any one - OS (Viktor producer-death finding, 2026-07-12).""" +def _producer_touch(failed=None) -> None: + """Heartbeat written by every completed `schedule run-due` (what the + timer runs), whether or not its operations passed: the heartbeat says + the loop ran, `failed` says which jobs did not. Producer freshness is + observable without depending on any one OS (Viktor producer-death + finding, 2026-07-12).""" import time PRODUCER_HEARTBEAT.parent.mkdir(parents=True, exist_ok=True) PRODUCER_HEARTBEAT.write_text(json.dumps( {"last_run": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), - "epoch": int(time.time())}, indent=2) + "\n") + "epoch": int(time.time()), + "failed": sorted(failed or [])}, indent=2) + "\n") def _producer_health() -> dict: - """state: 'current' (ran within the window), 'stalled' (heartbeat - older than the window — producers likely dead), 'never' (no - heartbeat yet — fresh install or hand-run only).""" + """state: 'current' (ran within the window, every job passed), + 'failing' (ran within the window, some jobs failed; `failed` names + them), 'stalled' (heartbeat older than the window, producers likely + dead), 'never' (no heartbeat yet, fresh install or hand-run only).""" import time if not PRODUCER_HEARTBEAT.exists(): return {"state": "never", "hours": None} @@ -115,8 +120,14 @@ def _producer_health() -> dict: age_h = (int(time.time()) - int(data["epoch"])) / 3600 except (ValueError, KeyError, OSError): return {"state": "never", "hours": None} - return {"state": "current" if age_h <= PRODUCER_STALE_HOURS - else "stalled", "hours": round(age_h, 1)} + failed = data.get("failed") or [] + if age_h > PRODUCER_STALE_HOURS: + state = "stalled" + elif failed: + state = "failing" + else: + state = "current" + return {"state": state, "hours": round(age_h, 1), "failed": failed} def serving_mode() -> bool: @@ -1372,6 +1383,7 @@ def render_app_page(views: list | None = None) -> str: // silence, not calm (Viktor producer-death finding). const queue = s.inbox ? s.inbox + ' to tend' : (s.producers === 'stalled' ? '⚠ producers stalled (queue may be stale)' + : s.producers === 'failing' ? '⚠ producers running, some jobs failing' : 'queue clear'); document.getElementById('strip').textContent = (s.fails ? '✗ ' + s.fails + ' failing · ' : @@ -2398,7 +2410,8 @@ def cmd_check_no_personal_data(args) -> int: for pat in hits: print(f" - matched forbidden pattern: {pat}", file=sys.stderr) print(" Strip session URLs and account-tied links. Model " - "attribution (Co-Authored-By) is fine.", file=sys.stderr) + "attribution (Co-Authored-By naming an assistant) is " + "not allowed by policy.", file=sys.stderr) return 1 return 0 @@ -2821,6 +2834,11 @@ def add(id: str, label: str, status: str, detail: str, hint: str = ""): "check the timer/service: systemctl --user status " f"{timer_unit.replace('.timer', '.service')} — or run " "`brain.py schedule run-due` by hand") + elif ph["state"] == "failing": + add("producers", "producer freshness", "fail", + f"accumulation ran {ph['hours']}h ago and is running, but " + f"{len(ph['failed'])} job(s) failed: {', '.join(ph['failed'])}", + "brain.py schedule run --target to see the error") elif ph["state"] == "current": add("producers", "producer freshness", "ok", f"accumulation ran {ph['hours']}h ago") @@ -3366,6 +3384,18 @@ def _channels_data() -> dict: # unsigned append at WRITE time; event_read VERIFIES attribution on # READ and drops anything that fails. Per-agent cursors (reusing the # connector-cursor shape) track each reader's position. +# +# Trust model, stated plainly. Keys are SYMMETRIC (HMAC-SHA256): the hub +# holds every agent's secret, so it can sign as any agent, and anyone who +# reads the keyring can too. The signature proves "someone holding this +# agent's key wrote it", not "only this agent could have". There is no +# replay or timestamp check (`ts` is signed but not compared to a clock, +# and a captured signed request can be sent again). The stream is +# append-only by convention, not by enforcement: nothing stops an +# operator editing the files. Verification happens at read time against +# the CURRENT keyring, so revoking or rotating an agent's key makes its +# past events fail verification and vanish from every read. Asymmetric +# keys would fix the forgery and attribution limits and are out of scope. # Local-first is untouched: with no keyring and no hosted tier, none of # this runs and the machine-stamped author stays the default. The legacy # "operator" principal is honoured — see _machine_author. @@ -3474,6 +3504,24 @@ def _event_period() -> str: return today_utc().isoformat()[:7] # YYYY-MM +_EVENT_APPEND_LOCK = threading.Lock() + + +@contextlib.contextmanager +def _event_file_lock(): + try: + import fcntl + except ImportError: # no flock (Windows): the thread lock alone + yield + return + with (EVENTS_DIR / ".append.lock").open("a") as lock: + fcntl.flock(lock, fcntl.LOCK_EX) + try: + yield + finally: + fcntl.flock(lock, fcntl.LOCK_UN) + + def event_append(agent_id: str, kind: str, ref: str, ts: str, sig: str) -> dict: """WRITE-time auth boundary: reject an append whose signature does @@ -3487,11 +3535,16 @@ def event_append(agent_id: str, kind: str, ref: str, ts: str, if not hmac.compare_digest( _event_sign(secret, agent_id, kind, ref, ts), sig): raise PermissionError("signature rejected") - event = {"seq": _event_count(), "ts": ts, "agent": agent_id, - "kind": kind, "ref": ref, "sig": sig} EVENTS_DIR.mkdir(parents=True, exist_ok=True) - with (EVENTS_DIR / f"{_event_period()}.jsonl").open("a") as fh: - fh.write(json.dumps(event, sort_keys=True) + "\n") + # seq is "how many events exist": counting and appending must be one + # step, or two threaded-server requests share a seq. The thread lock + # covers one process; the file lock covers a second process (the CLI + # emitting while the hub runs) where flock exists. + with _EVENT_APPEND_LOCK, _event_file_lock(): + event = {"seq": _event_count(), "ts": ts, "agent": agent_id, + "kind": kind, "ref": ref, "sig": sig} + with (EVENTS_DIR / f"{_event_period()}.jsonl").open("a") as fh: + fh.write(json.dumps(event, sort_keys=True) + "\n") return event @@ -5027,6 +5080,7 @@ def cmd_status(_args) -> int: sched = json.loads(SCHEDULE_STATE.read_text()) last = sched.get("last_run") or "?" failed = sched.get("failed") or [] + skipped = sched.get("skipped") or [] age = "" try: delta = (today_utc() - dt.date.fromisoformat(last)).days @@ -5038,8 +5092,12 @@ def cmd_status(_args) -> int: print(f"schedule: last run {last}{age} — " f"{len(failed)} FAILED: {', '.join(failed)}") else: + n_ok = sum(1 for v in (sched.get("operations") or {}).values() + if v == "ok") + note = (f", {len(skipped)} skipped: {', '.join(skipped)}" + if skipped else "") print(f"schedule: last run {last}{age} — " - f"{len(sched.get('operations') or {})} operations ok") + f"{n_ok} operations ok{note}") except json.JSONDecodeError: print("schedule: state unparseable") else: @@ -8805,14 +8863,32 @@ def _schedule_run_notion_walk() -> int: return 0 +SCHEDULE_SKIPPED = 75 # an in-process handler's "named skip": not ok, not failed + + def _schedule_run_overlap_refresh() -> int: - """Re-run the cluster command and dump output to wiki/_overlaps/.""" + """Re-run the cluster command and dump output to wiki/_overlaps/. + + Clustering needs scikit-learn (the optional `cluster` extra). Without + it the job writes no report and returns SCHEDULE_SKIPPED, so the run + records a named skip rather than an empty report marked ok. + """ + import importlib.util + if importlib.util.find_spec("sklearn") is None: + print("overlap-refresh: skipped, scikit-learn is not installed " + "(pip install scikit-learn, or `pip install -e .[cluster]`)", + file=sys.stderr) + return SCHEDULE_SKIPPED overlap_path = WIKI / "_overlaps" / f"auto-refresh-{today_utc().isoformat()}.md" overlap_path.parent.mkdir(exist_ok=True) res = subprocess.run( [sys.executable, str(REPO / "tools" / "brain.py"), "cluster"], capture_output=True, text=True, timeout=60, cwd=REPO, ) + if res.returncode != 0: + print(f"overlap-refresh: cluster failed (exit {res.returncode}): " + f"{(res.stdout or res.stderr).strip()[:300]}", file=sys.stderr) + return res.returncode today = today_utc().isoformat() body = f"""--- title: "Auto-refreshed cluster scan {today}" @@ -8974,11 +9050,29 @@ def _schedule_run_ai_suggestion_grooming() -> int: } +CADENCE_DAYS = {"daily": 1, "weekly": 7, "monthly": 30} + + +def _cadence_elapsed(cadence, last_ran) -> bool: + """True when an operation with this cadence is due. No recorded run, + an unknown cadence or an unparseable date all mean due.""" + days = CADENCE_DAYS.get(str(cadence or "").lower()) + if days is None or not last_ran: + return True + try: + last = dt.date.fromisoformat(str(last_ran)) + except ValueError: + return True + return (today_utc() - last).days >= days + + def cmd_schedule(args) -> int: """Manage the declarative schedule at brain-schedule.yml. - This v1 ships the config + listing only; the runner is a - separate decision. + `list` prints the operations, `run --target ` runs one, and + `run-due` runs every enabled operation whose cadence (daily, weekly + or monthly) has elapsed since it last ran; `run-due --force` ignores + cadence. The OS timer (tools/install-timer.sh) calls `run-due`. """ config_path = REPO / "brain-schedule.yml" if not config_path.exists(): @@ -9036,10 +9130,23 @@ def cmd_schedule(args) -> int: # red badge, not more. rc_total = 0 outcomes = {} + try: + prior = json.loads(SCHEDULE_STATE.read_text()) + except (OSError, ValueError): + prior = {} + ran = dict(prior.get("ran") or {}) + force = bool(getattr(args, "force", False)) for entry in config.get("operations") or []: if not entry.get("enabled"): continue name = entry.get("name") + if not force and not _cadence_elapsed( + entry.get("cadence"), ran.get(name)): + print(f"# not due: {name} ({entry.get('cadence')}, " + f"last ran {ran.get(name)})", file=sys.stderr) + if name in (prior.get("operations") or {}): + outcomes[name] = prior["operations"][name] + continue print(f"# running: {name}", file=sys.stderr) try: if name in SCHEDULE_HANDLERS: @@ -9050,26 +9157,37 @@ def cmd_schedule(args) -> int: continue rc = subprocess.run(handler, shell=True, cwd=REPO).returncode - outcomes[name] = "ok" if rc == 0 else f"exit {rc}" + if rc == 0: + outcomes[name] = "ok" + elif rc == SCHEDULE_SKIPPED and name in SCHEDULE_HANDLERS: + outcomes[name] = "skipped" + else: + outcomes[name] = f"exit {rc}" + if outcomes[name] != "skipped": + ran[name] = today_utc().isoformat() except Exception as exc: # noqa: BLE001 — the record is the point # A raising handler would otherwise abort the sweep with # nothing written down about which op died. outcomes[name] = f"{type(exc).__name__}: {exc}" rc = 1 - if rc != 0: + if rc != 0 and outcomes.get(name) != "skipped": rc_total = rc - failed = {k: v for k, v in outcomes.items() if v != "ok"} + failed = {k: v for k, v in outcomes.items() + if v not in ("ok", "skipped")} + skipped = sorted(k for k, v in outcomes.items() if v == "skipped") SCHEDULE_STATE.parent.mkdir(parents=True, exist_ok=True) SCHEDULE_STATE.write_text(json.dumps({ "last_run": today_utc().isoformat(), "operations": outcomes, "failed": sorted(failed), + "skipped": skipped, + "ran": ran, }, indent=2) + "\n") if failed: print(f"# schedule: {len(failed)} operation(s) failed: " f"{', '.join(sorted(failed))}", file=sys.stderr) - if rc_total == 0: - _producer_touch() # heartbeat: the accumulation loop is alive + # The heartbeat says the loop ran; the failed list says what broke. + _producer_touch(failed) return rc_total print(f"unknown schedule op: {op}", file=sys.stderr) @@ -11005,6 +11123,9 @@ def main() -> int: help="list (default) | run --target | run-due") ap_sched.add_argument("--target", help="operation name when op=run") + ap_sched.add_argument("--force", action="store_true", + help="with run-due: ignore cadence and run every " + "enabled operation") ap_sched.set_defaults(func=cmd_schedule) ap_init = sub.add_parser( diff --git a/tools/emulate-agentic.py b/tools/emulate-agentic.py index 738db69..2678608 100755 --- a/tools/emulate-agentic.py +++ b/tools/emulate-agentic.py @@ -6,7 +6,9 @@ fires emulated producers (a structure-drift event and Sentry / Datadog / Langfuse alerts), and shows each agent get woken and emit its result — the complete loop end to end. Everything is torn down and the runtime -state (git-ignored) is cleaned up on exit. +state (git-ignored) is cleaned up on exit. It writes its keyring and event +stream into the repository it runs in, so it refuses to start when that +repository already has either; use a throwaway checkout. python3 tools/emulate-agentic.py @@ -53,15 +55,35 @@ def _banner(msg): print(f"\n\033[1m{msg}\033[0m") +def _live_state() -> list[str]: + """Paths of real hosted-tier state in this repository. The emulation + issues its own keys and removes the keyring, cursors and event stream + on exit, so it must not start where any of them already exist.""" + found = [] + if brain.AGENT_KEYS.exists() and brain._load_agent_keys(): + found.append(brain.AGENT_KEYS) + if brain.EVENT_CURSORS.exists(): + found.append(brain.EVENT_CURSORS) + if brain.EVENTS_DIR.exists() and any(brain.EVENTS_DIR.glob("*.jsonl")): + found.append(brain.EVENTS_DIR) + return found + + def main() -> int: + live = _live_state() + if live: + print("emulate-agentic: refusing to run, this repository has live " + "hosted-tier state that the emulation would delete:", + file=sys.stderr) + for path in live: + print(f" {path}", file=sys.stderr) + print("Run it in a throwaway checkout (or after moving that state " + "aside).", file=sys.stderr) + return 2 ba = _spoke() tmp_cursors = REPO / "wiki" / "_state" / ".emulate-cursors.json" os.environ["BRAIN_AGENT_CURSORS"] = str(tmp_cursors) - # Clean any prior emulation state. - brain.AGENT_KEYS.unlink(missing_ok=True) - brain.EVENT_CURSORS.unlink(missing_ok=True) - shutil.rmtree(brain.EVENTS_DIR, ignore_errors=True) tmp_cursors.unlink(missing_ok=True) _banner("1. issue keys — producers + specialized agents") diff --git a/tools/templates/owner-subagent-prompt.md b/tools/templates/owner-subagent-prompt.md index 27ba55d..93e287f 100644 --- a/tools/templates/owner-subagent-prompt.md +++ b/tools/templates/owner-subagent-prompt.md @@ -106,8 +106,8 @@ The default Phase-shape for `{{phase}}` is: (`AGENTS.md` / `.claude/skills/**` / `tools/**` / etc.): `~/.local/share/mempalace-venv/bin/python3 tools/brain.py check-readme-fresh --base origin/main` The CI gate enforces the same — fix locally first. -5. **Commit + push.** Standard `Co-Authored-By: Claude Opus 4.7 - ` footer. `git push -u origin HEAD`. +5. **Commit + push.** No AI attribution in the commit message (no + `Co-Authored-By` naming an assistant, no session link). `git push -u origin HEAD`. 6. **Open PR.** Executive-summary body, under 200 words, no H2 scaffolding (per `.claude/skills/pr/SKILL.md` § PR body shape). `gh pr edit --body` is silently broken on this account — diff --git a/ui/src/pages/onboarding.astro b/ui/src/pages/onboarding.astro index 6c9514d..b796521 100644 --- a/ui/src/pages/onboarding.astro +++ b/ui/src/pages/onboarding.astro @@ -171,7 +171,7 @@ const slides: Slide[] = [ title: 'The brain as a coordination hub for many agents.', body: 'Off by default and local-first-preserving. Turn on the hosted tier and the brain coordinates many agents that run in their own harnesses — it is never a harness itself.', bullets: [ - 'Each agent has a signed identity. Agents write a signed, append-only event stream and read it from a per-agent cursor; forged or tampered events are rejected.', + 'Each agent has a signed identity. Agents write a signed, append-only event stream and read it from a per-agent cursor; forged or tampered events are rejected (keys are symmetric, so the hub itself can sign as any agent).', 'An agent subscribes to what it cares about — a repo, a thread, a producer — and is woken when a matching event lands. A wake is a hint, never an invocation; the agent reacts on its own next tend.', 'Specialized agents (a drift-reconciler; an observability-triage agent for Sentry / Datadog / Langfuse) subscribe and react deterministically. See the whole loop locally, no deployment: run tools/emulate-agentic.py.', ], diff --git a/wiki/_views/ai-suggestions.md b/wiki/_views/ai-suggestions.md index e85a120..1089c57 100644 --- a/wiki/_views/ai-suggestions.md +++ b/wiki/_views/ai-suggestions.md @@ -2,7 +2,7 @@ title: AI suggestions — drafts for human review kind: meta status: living -updated: 2026-08-07 +updated: 2026-10-25 confidence: high sources: - tools/brain.py diff --git a/wiki/_views/attention.md b/wiki/_views/attention.md index e8f7904..a73aeec 100644 --- a/wiki/_views/attention.md +++ b/wiki/_views/attention.md @@ -2,7 +2,7 @@ title: Attention — what deserves the day kind: meta status: living -updated: 2026-08-07 +updated: 2026-10-25 confidence: high sources: - tools/brain.py diff --git a/wiki/_views/by-epic.md b/wiki/_views/by-epic.md index 28edd5c..bb6a498 100644 --- a/wiki/_views/by-epic.md +++ b/wiki/_views/by-epic.md @@ -2,7 +2,7 @@ title: Index — by epic kind: meta status: living -updated: 2026-08-07 +updated: 2026-10-25 confidence: high sources: - tools/brain.py diff --git a/wiki/_views/by-kind.md b/wiki/_views/by-kind.md index e1fe277..3188172 100644 --- a/wiki/_views/by-kind.md +++ b/wiki/_views/by-kind.md @@ -2,7 +2,7 @@ title: Index — by kind kind: meta status: living -updated: 2026-08-07 +updated: 2026-10-25 confidence: high sources: - tools/brain.py diff --git a/wiki/_views/by-repo.md b/wiki/_views/by-repo.md index 1bf0d48..db72e76 100644 --- a/wiki/_views/by-repo.md +++ b/wiki/_views/by-repo.md @@ -2,7 +2,7 @@ title: Index — by repo kind: meta status: living -updated: 2026-08-07 +updated: 2026-10-25 confidence: high sources: - tools/brain.py diff --git a/wiki/_views/by-team.md b/wiki/_views/by-team.md index 3113075..efc8176 100644 --- a/wiki/_views/by-team.md +++ b/wiki/_views/by-team.md @@ -2,7 +2,7 @@ title: Index — by team kind: meta status: living -updated: 2026-08-07 +updated: 2026-10-25 confidence: high sources: - tools/brain.py diff --git a/wiki/_views/custom/engineer.md b/wiki/_views/custom/engineer.md index 0623de5..78237aa 100644 --- a/wiki/_views/custom/engineer.md +++ b/wiki/_views/custom/engineer.md @@ -2,7 +2,7 @@ title: "Engineer view" kind: meta status: living -updated: 2026-08-07 +updated: 2026-10-25 confidence: high sources: - ../../../views/engineer.yml @@ -38,13 +38,13 @@ What changed in the decision trail, what the brain wants deepened, and the produ | path | confidence | inbound | |---|---|---| +| brain/state.md | medium | 7 | | brain/adrs/mcp-cli-surface.md | medium | 6 | | brain/adrs/per-agent-identity.md | medium | 6 | -| brain/state.md | medium | 6 | -| brain/adrs/queue-and-tend-inbox.md | high | 5 | -| brain/adrs/multi-prd-epic-shape.md | high | 4 | +| brain/adrs/queue-and-tend-inbox.md | medium | 5 | +| brain/adrs/multi-prd-epic-shape.md | medium | 4 | | brain/adrs/owner-subscription-wake.md | medium | 4 | -| brain/adrs/successor-ssg-for-ui.md | high | 4 | +| brain/adrs/successor-ssg-for-ui.md | medium | 4 | | brain/topics/one-point-oh-criteria.md | medium | 4 | | brain/adrs/connector-snapshot-contract.md | medium | 3 | | brain/adrs/home-content-shape.md | medium | 3 | diff --git a/wiki/_views/custom/operator.md b/wiki/_views/custom/operator.md index fd9b357..29b2815 100644 --- a/wiki/_views/custom/operator.md +++ b/wiki/_views/custom/operator.md @@ -2,7 +2,7 @@ title: "Operator view" kind: meta status: living -updated: 2026-08-07 +updated: 2026-10-25 confidence: high sources: - ../../../views/operator.yml @@ -36,11 +36,11 @@ No connectors configured. | brain/adrs/connector-snapshot-contract.md | decision | medium | 2026-07-10 | | brain/adrs/home-content-shape.md | decision | medium | 2026-07-10 | | brain/adrs/kernel-manifest-instancing.md | decision | medium | 2026-07-10 | -| brain/adrs/multi-prd-epic-shape.md | decision | high | 2026-07-10 | +| brain/adrs/multi-prd-epic-shape.md | decision | medium | 2026-07-10 | | brain/adrs/operator-lesson-pattern.md | decision | medium | 2026-07-10 | | brain/adrs/parallel-efforts-on-request.md | decision | medium | 2026-07-10 | | brain/adrs/parallel-execution-agent-teams.md | decision | medium | 2026-07-10 | -| brain/adrs/queue-and-tend-inbox.md | decision | high | 2026-07-10 | +| brain/adrs/queue-and-tend-inbox.md | decision | medium | 2026-07-10 | | brain/adrs/shape-deepdive-pre-flight.md | decision | medium | 2026-07-10 | | brain/adrs/shape-up-pitches.md | decision | medium | 2026-07-10 | diff --git a/wiki/_views/custom/pm.md b/wiki/_views/custom/pm.md index bb28c5c..177382b 100644 --- a/wiki/_views/custom/pm.md +++ b/wiki/_views/custom/pm.md @@ -2,7 +2,7 @@ title: "PM view" kind: meta status: living -updated: 2026-08-07 +updated: 2026-10-25 confidence: high sources: - ../../../views/pm.yml diff --git a/wiki/_views/graph.json b/wiki/_views/graph.json index 56810ae..0bf06d2 100644 --- a/wiki/_views/graph.json +++ b/wiki/_views/graph.json @@ -1275,6 +1275,11 @@ "target": "brain/prds/persona-playthrough-loop.md", "provenance": "extracted" }, + { + "source": "brain/roadmap.md", + "target": "brain/state.md", + "provenance": "extracted" + }, { "source": "brain/roadmap.md", "target": "brain/topics/one-point-oh-criteria.md", diff --git a/wiki/_views/pages.json b/wiki/_views/pages.json index 730c3de..3258e84 100644 --- a/wiki/_views/pages.json +++ b/wiki/_views/pages.json @@ -1,5 +1,5 @@ { - "generated": "2026-08-07", + "generated": "2026-10-25", "home_sections": [ { "anchor": "what-changed", @@ -321,7 +321,7 @@ "kind": "decision", "status": "accepted", "updated": "2026-07-10", - "confidence": "high", + "confidence": "medium", "summary": "Umbrella-scale work gets a kind: epic page with children spawned as regular PRDs linked via parent_epic; epics carry no engineering bets and no umbrella ADR.\n", "sources": [ "../../../sources/research/2026-07-10--tend-sweep-2-verification.md", @@ -545,7 +545,7 @@ "kind": "decision", "status": "accepted", "updated": "2026-07-10", - "confidence": "high", + "confidence": "medium", "summary": "No LLM ever runs on a schedule: deterministic producers accumulate inbox items (cursor diffs, half-life crossings, link health); interactive sessions digest them via /tend. Amended twice: research-picker damping; one-runner enforcement.\n", "sources": [ "../../../sources/research/2026-07-10--hub-adr-verification.md", @@ -741,7 +741,7 @@ "kind": "decision", "status": "accepted", "updated": "2026-07-10", - "confidence": "high", + "confidence": "medium", "summary": "Astro is the UI substrate (originally Astro + Starlight): content collections over the symlinked wiki, static build, mobile-native. The 2026-07-12 presentation-layer rewrite retired Starlight; Astro stays.\n", "sources": [ "../../../sources/research/2026-07-10--hub-adr-verification.md", @@ -1068,7 +1068,7 @@ "kind": "meta", "status": "living", "updated": "2026-07-10", - "confidence": "high", + "confidence": "medium", "sources": [ "../../AGENTS.md" ], @@ -1918,8 +1918,8 @@ "title": "Brain roadmap \u2014 0.x arc toward a self-maintaining, servable brain", "kind": "meta", "status": "living", - "updated": "2026-07-10", - "confidence": "high", + "updated": "2026-10-25", + "confidence": "medium", "sources": [ "../../sources/research/2026-07-10--tend-sweep-2-verification.md", "../../sources/conversations/2026-07-10--self-hosting-roadmap-intent.md", @@ -1936,14 +1936,14 @@ ] } }, - "tokens": 5155 + "tokens": 5596 }, { "path": "brain/state.md", "title": "Brain \u2014 state", "kind": "reference", "status": "living", - "updated": "2026-07-10", + "updated": "2026-10-25", "confidence": "medium", "sources": [ "../../AGENTS.md" @@ -1957,7 +1957,7 @@ ] } }, - "tokens": 5033 + "tokens": 5208 }, { "path": "brain/topics/chat-surface-necessity.md", @@ -2194,7 +2194,7 @@ "kind": "meta", "status": "living", "updated": "2026-07-10", - "confidence": "high", + "confidence": "medium", "sources": [ "../../AGENTS.md" ], @@ -2324,7 +2324,7 @@ "kind": "reference", "status": "living", "updated": "2026-07-10", - "confidence": "high", + "confidence": "medium", "sources": [ "../../sources/research/2026-07-10--tend-sweep-2-verification.md", "../../.claude/skills/capture/SKILL.md" diff --git a/wiki/brain/adrs/multi-prd-epic-shape.md b/wiki/brain/adrs/multi-prd-epic-shape.md index 14e2965..c29f4ed 100644 --- a/wiki/brain/adrs/multi-prd-epic-shape.md +++ b/wiki/brain/adrs/multi-prd-epic-shape.md @@ -3,7 +3,7 @@ title: "Epics are single-page umbrella artifacts with parent_epic linkage, valid kind: decision status: accepted updated: 2026-07-10 -confidence: high +confidence: medium summary: > Umbrella-scale work gets a kind: epic page with children spawned as regular PRDs linked via parent_epic; epics carry no engineering bets and no umbrella ADR. sources: diff --git a/wiki/brain/adrs/queue-and-tend-inbox.md b/wiki/brain/adrs/queue-and-tend-inbox.md index affa759..e5242f6 100644 --- a/wiki/brain/adrs/queue-and-tend-inbox.md +++ b/wiki/brain/adrs/queue-and-tend-inbox.md @@ -3,7 +3,7 @@ title: "Self-maintenance is queue-and-tend: deterministic producers accumulate a kind: decision status: accepted updated: 2026-07-10 -confidence: high +confidence: medium summary: > No LLM ever runs on a schedule: deterministic producers accumulate inbox items (cursor diffs, half-life crossings, link health); interactive sessions digest them via /tend. Amended twice: research-picker damping; one-runner enforcement. sources: diff --git a/wiki/brain/adrs/successor-ssg-for-ui.md b/wiki/brain/adrs/successor-ssg-for-ui.md index a59cdc9..8072d22 100644 --- a/wiki/brain/adrs/successor-ssg-for-ui.md +++ b/wiki/brain/adrs/successor-ssg-for-ui.md @@ -3,7 +3,7 @@ title: "Adopt Astro + Starlight + Pagefind as the successor SSG for the UI" kind: decision status: accepted updated: 2026-07-10 -confidence: high +confidence: medium summary: > Astro is the UI substrate (originally Astro + Starlight): content collections over the symlinked wiki, static build, mobile-native. The 2026-07-12 presentation-layer rewrite retired Starlight; Astro stays. sources: diff --git a/wiki/brain/index.md b/wiki/brain/index.md index c2f1e5c..94c6f01 100644 --- a/wiki/brain/index.md +++ b/wiki/brain/index.md @@ -3,7 +3,7 @@ title: "Brain (meta level)" kind: meta status: living updated: 2026-07-10 -confidence: high +confidence: medium sources: - ../../AGENTS.md enola_intent: diff --git a/wiki/brain/roadmap.md b/wiki/brain/roadmap.md index 40bb9d3..80ef00b 100644 --- a/wiki/brain/roadmap.md +++ b/wiki/brain/roadmap.md @@ -2,8 +2,8 @@ title: "Brain roadmap — 0.x arc toward a self-maintaining, servable brain" kind: meta status: living -updated: 2026-07-10 -confidence: high +updated: 2026-10-25 +confidence: medium sources: - ../../sources/research/2026-07-10--tend-sweep-2-verification.md - ../../sources/conversations/2026-07-10--self-hosting-roadmap-intent.md @@ -409,6 +409,31 @@ shelf home renders a generated Project overview (reading path, open work, recent decisions, freshness, honest gaps) per the presentation-layer ADR's second amendment. +## 0.20.0 to 0.31.0: the agentic tier, graph, intent (**shipped 2026-07-12 to 2026-08-06**) + +Summarised here from [`CHANGELOG.md`](../../CHANGELOG.md) (the +authoritative per-version record; 0.21 to 0.30 were reconstructed from +git history on 2026-10-25) and [state.md](state.md). + +- **0.20.0 (2026-07-12)**: the playthrough-sweep delivery and public + repository hygiene; the public history starts here. +- **0.21.0 to 0.26.0 (2026-07-14)**: per-edge provenance on the link + graph, the structure connector, an async conversation surface over the + inbox, one collaboration control, topics that lead with a brief, and + page trust signals. +- **0.27.0 to 0.30.0 (2026-07-14)**: the agentic tier. Per-agent + identity and a signed event stream (0.27), owner-subscription wake + (0.28), the spoke client (0.29), specialized agents and the local + emulation (0.30). Off by default; local-first is unchanged. It has no + deploy story yet: `deploy/` serves the three read-only surfaces only. +- **0.31.0 (2026-08-06)**: intent compilation (`enola_intent:` blocks, + `brain.py enola govern`), with the attention board, structure findings + and the enola tier carried across in the weeks before it. +- **0.31.1 (2026-10-25)**: final polish, no features. The project is + left standalone and maintained as is; the 1.0 gate + ([one-point-oh-criteria](topics/one-point-oh-criteria.md)) is not met + (criteria 2 to 4 need calendar time and a real adoption). + ## Standing ideas (unversioned) Deliberately not adopted from the studied prior art: a vector diff --git a/wiki/brain/state.md b/wiki/brain/state.md index 2a91064..5bc4c30 100644 --- a/wiki/brain/state.md +++ b/wiki/brain/state.md @@ -2,7 +2,7 @@ title: "Brain — state" kind: reference status: living -updated: 2026-07-10 +updated: 2026-10-25 confidence: medium sources: - ../../AGENTS.md @@ -34,13 +34,13 @@ into the sections below. - **Specialized agents + a local emulation of the whole loop (0.30.0, 2026-07-14).** The agentic future runs end to end on one machine, no deployment. Two **specialized spoke agents** ship under `tools/agents/` - — a **drift-reconciler** (subscribes to repo drift; on wake queues a - `reconcile:` note for a tend session) and an + — a **drift-reconciler** (subscribes to repo drift; on wake emits a + `reconcile:` note on the event stream) and an **observability-triage** agent (subscribes to `alert:*` from emulated - Sentry / Datadog / Langfuse producers; assigns severity and queues a - triage note). Both do **deterministic prep only** and emit a result + Sentry / Datadog / Langfuse producers; assigns severity and emits a + triage note on the stream). Both do **deterministic prep only** and emit a result event — they never invoke an LLM, so the no-scheduled-LLM invariant - holds; the reasoning is queued for a harness. `tools/emulate-agentic.py` + holds; the reasoning is left to a harness. `tools/emulate-agentic.py` is the **local hosting emulation**: it starts a real hosted hub, issues keys, runs the real spoke agents as listeners, fires the producers, and shows producers → wakes → agent reactions on a signed @@ -353,20 +353,30 @@ into the sections below. ## Perceived -*(no Now-vs-Perceived gaps recorded yet)* - -## Target +Gaps recorded at the 0.31.1 polish (2026-10-25), each now stated in the +docs rather than implied: +- The event stream reads as "signed, append-only, authenticated". The + keys are symmetric, so the hub can sign as any agent; there is no + replay or clock check; revoking or rotating a key makes that agent's + past events fail verification and vanish from reads. +- Spoke agents emit `note` events on the stream; nothing copies them + into `wiki/_state/inbox/`, which is what `/tend` digests. +- The hosted tier has no deploy story. +## Target - Adopt for a project: fill `brain.config.yml`, author team/user personas, run the first `/in` ingest. -- The 0.x arc per [roadmap.md](roadmap.md) (operator intent captured - 2026-07-10): scheduled autonomy (0.2) → connector snapshot-writers - for Slack / Notion / GitHub (0.3) → pruning + deepening with a - research loop (0.4) → a read-only grounded chat plane for people - outside the product (0.5) → the self-hosting profile that carries - it (0.6). Local-first stays the default operating mode throughout. +- The 0.2 to 0.6 arc in [roadmap.md](roadmap.md) (scheduled autonomy, + connectors, pruning, serving) shipped in July 2026 and has been + extended through 0.31.1; the roadmap's last section is the current + record. There is no active feature roadmap. +- Not done, and not scheduled (stated limits as of 2026-10-25): deploying + the hosted agentic tier (no deploy story exists; `deploy/` serves the + read-only surfaces), the 1.0 gate's criteria 2 to 4, asymmetric keys + for the event stream, and moving spoke-agent notes into the tend + inbox. Local-first stays the default operating mode. ## Open threads diff --git a/wiki/index.md b/wiki/index.md index 5f9bd22..8c9265b 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -23,6 +23,7 @@ start filling in as the slash-command surface runs. ## What changed +- **2026-10-25**: **0.31.1: final polish, docs made true to the code.** Health now reports a failing scheduled job as failing and a running producer as running; `cadence:` is honoured by `run-due`; the overlap job records a named skip without scikit-learn; the event stream's real trust model (symmetric keys, no replay check, no deploy story) is stated; the emulation script refuses to delete a live keyring; no machine path ships; the changelog, roadmap and state page reach the current version. No new features. (brain) - **2026-08-07** — **Producers back on schedule after a 60-hour timer gap.** `doctor` flagged dead producers; `schedule run-due` by hand refreshed the state (overlap auto-refresh, zoom-out digest, suggestion grooming) and restored the doctor suite to green. The machine timer remains the real fix. Note for the gate: `wiki/_state/` outputs tripped home-pairing — tooling surfaces arguably belong on its exempt list. (operations) - **2026-08-06** — **The release gate opens: enola v0.3.9 carries the intent standard.** Upstream merged the intent work (enola-labs/enola#197) and cut v0.3.9, so verdict compilation is live for any instance whose pinned binary crosses it — regenerate the snapshot and the wiki is in the graph, exactly as [intent compilation](brain/topics/intent-compilation.md) § Release gate promised. README and the topic page now record the gate as opened rather than pending. (intent-compilation) - **2026-08-06** — **The standalone guarantee re-verified at zero.** diff --git a/wiki/org/index.md b/wiki/org/index.md index 50c59bc..2150ec3 100644 --- a/wiki/org/index.md +++ b/wiki/org/index.md @@ -3,7 +3,7 @@ title: "Org — methodology + cross-product" kind: meta status: living updated: 2026-07-10 -confidence: high +confidence: medium sources: - ../../AGENTS.md enola_intent: diff --git a/wiki/org/operator-lessons.md b/wiki/org/operator-lessons.md index b631cdb..25ba9a4 100644 --- a/wiki/org/operator-lessons.md +++ b/wiki/org/operator-lessons.md @@ -3,7 +3,7 @@ title: "Operator lessons" kind: reference status: living updated: 2026-07-10 -confidence: high +confidence: medium sources: - ../../sources/research/2026-07-10--tend-sweep-2-verification.md - ../../.claude/skills/capture/SKILL.md