feat: brain_pending and brain_promote — close the curation loop for raw → wiki promotion #38

New Issue

2026-06-06T06:12:33Z

mathias commented

2026-06-06 06:12:33 +00:00

Context

Surfaced during the genesis session for the brain Hall taxonomy (claude.ai, 2026-05-06). The raw → wiki promotion step is the single biggest friction point in the human curation workflow and has no tooling.

Currently:

Agents write to brain/raw/ via the retrospective skill
A human must manually review, move, rename, update frontmatter, and add wikilinks
There is no MCP tool to list what's pending or to promote a note in one call

This means the brain grows only as fast as you perform manual file operations. For a system with multiple parallel Claude Code sessions generating retrospectives, the review queue can back up quickly — and there's no visibility into it.

Two new MCP tools

`brain_pending`

Lists files in brain/raw/ awaiting human review.

tool: brain_pending
params: (none)

returns: [
  {
    filename: string,
    created_at: string (ISO 8601),
    size_bytes: int,
    excerpt: string  // first 200 chars of body after frontmatter
  }
]

Sorted by created_at ascending (oldest first — natural review order).

`brain_promote`

Moves a file from brain/raw/ to brain/wiki/<wing>/<hall>/, rewrites frontmatter, and triggers auto-tunnel detection.

tool: brain_promote
params:
  filename:  string   // basename in brain/raw/ (e.g. "2026-05-06-lejpa-decision.md")
  wing:      string   // target wing (e.g. "jepa-fx")
  hall:      enum     // facts | decisions | failures | hypotheses | sources
  slug:      string?  // target filename slug (defaults to source filename stripped of date prefix)

returns:
  path: string   // relative path of promoted note in brain/wiki/

On promotion:

Reads source file from brain/raw/<filename>
Rewrites YAML frontmatter: adds wing, hall, created_at, promoted_at; preserves any existing custom fields
Writes to brain/wiki/<wing>/<hall>/<slug>.md
Deletes source from brain/raw/
Runs DetectTunnels on the promoted content — appends auto-detected cross-wing wikilinks
Regenerates _index.md for the target wing

Implementation

Both tools follow the existing handler pattern in ingestion/internal/mcp/.

REST endpoints for completeness (useful for shell scripts):

GET /pending — same as brain_pending
POST /promote — same as brain_promote, body {filename, wing, hall, slug?}

Acceptance criteria

brain_pending returns all files in brain/raw/ with excerpt, sorted oldest-first
brain_pending returns empty array (not error) when brain/raw/ is empty or absent
brain_promote moves file, rewrites frontmatter correctly, deletes source
brain_promote with invalid hall returns a clear error before touching the filesystem
brain_promote is idempotent on slug collision — returns error if target already exists (no silent overwrite)
Auto-tunnel runs after promotion; exact-match links written, fuzzy candidates written to brain/raw/tunnel-candidates-<date>.md
_index.md regenerated for target wing after promotion
task check passes
Tests: pending with files, pending empty, promote happy path, promote invalid hall, promote slug collision

Notes

brain_promote must be atomic from the caller's perspective: if the write fails, the source file must not be deleted. Use write-then-delete, not move.
This is the human-facing complement to brain_write (agent-facing). Agents write directly to wiki/ with wing+hall; humans promote from raw/.
Does not block #32, #34, or #35 — independent of the routing/skill pipeline.

## Context Surfaced during the genesis session for the brain Hall taxonomy (claude.ai, 2026-05-06). The raw → wiki promotion step is the single biggest friction point in the human curation workflow and has no tooling. Currently: - Agents write to `brain/raw/` via the `retrospective` skill - A human must manually review, move, rename, update frontmatter, and add wikilinks - There is no MCP tool to list what's pending or to promote a note in one call This means the brain grows only as fast as you perform manual file operations. For a system with multiple parallel Claude Code sessions generating retrospectives, the review queue can back up quickly — and there's no visibility into it. ## Two new MCP tools ### `brain_pending` Lists files in `brain/raw/` awaiting human review. ``` tool: brain_pending params: (none) returns: [ { filename: string, created_at: string (ISO 8601), size_bytes: int, excerpt: string // first 200 chars of body after frontmatter } ] ``` Sorted by `created_at` ascending (oldest first — natural review order). ### `brain_promote` Moves a file from `brain/raw/` to `brain/wiki/<wing>/<hall>/`, rewrites frontmatter, and triggers auto-tunnel detection. ``` tool: brain_promote params: filename: string // basename in brain/raw/ (e.g. "2026-05-06-lejpa-decision.md") wing: string // target wing (e.g. "jepa-fx") hall: enum // facts | decisions | failures | hypotheses | sources slug: string? // target filename slug (defaults to source filename stripped of date prefix) returns: path: string // relative path of promoted note in brain/wiki/ ``` On promotion: 1. Reads source file from `brain/raw/<filename>` 2. Rewrites YAML frontmatter: adds `wing`, `hall`, `created_at`, `promoted_at`; preserves any existing custom fields 3. Writes to `brain/wiki/<wing>/<hall>/<slug>.md` 4. Deletes source from `brain/raw/` 5. Runs `DetectTunnels` on the promoted content — appends auto-detected cross-wing wikilinks 6. Regenerates `_index.md` for the target wing ## Implementation Both tools follow the existing handler pattern in `ingestion/internal/mcp/`. REST endpoints for completeness (useful for shell scripts): - `GET /pending` — same as `brain_pending` - `POST /promote` — same as `brain_promote`, body `{filename, wing, hall, slug?}` ## Acceptance criteria - [ ] `brain_pending` returns all files in `brain/raw/` with excerpt, sorted oldest-first - [ ] `brain_pending` returns empty array (not error) when `brain/raw/` is empty or absent - [ ] `brain_promote` moves file, rewrites frontmatter correctly, deletes source - [ ] `brain_promote` with invalid `hall` returns a clear error before touching the filesystem - [ ] `brain_promote` is idempotent on slug collision — returns error if target already exists (no silent overwrite) - [ ] Auto-tunnel runs after promotion; exact-match links written, fuzzy candidates written to `brain/raw/tunnel-candidates-<date>.md` - [ ] `_index.md` regenerated for target wing after promotion - [ ] `task check` passes - [ ] Tests: pending with files, pending empty, promote happy path, promote invalid hall, promote slug collision ## Notes - `brain_promote` must be atomic from the caller's perspective: if the write fails, the source file must not be deleted. Use write-then-delete, not move. - This is the human-facing complement to `brain_write` (agent-facing). Agents write directly to `wiki/` with wing+hall; humans promote from `raw/`. - Does not block #32, #34, or #35 — independent of the routing/skill pipeline. ## Related - Hyperguild #1 (Hall taxonomy — prerequisite, already shipped) - Hyperguild #2 (Tunnels — `DetectTunnels` consumed here) - brain: `knowledge/2026-05-03-parallelism-bottlenecked-by-review-attention.md` (relevant insight) --- _Created via git-mcp on behalf of @mathiasbq_

mathias referenced this issue

2026-06-15 17:57:14 +00:00

Brain interface: intent↔interface mismatch analysis (problem statement, evidence-backed) #43

mathias referenced this issue

2026-06-22 05:43:04 +00:00

feat: brain_pending + brain_promote tools — close the raw→wiki curation loop #37

mathias referenced this issue

2026-06-22 06:06:16 +00:00

feat: brain_update — supersede-by-slug write verb (+ read-after-write: brain_get, brain_write handle) #45

mathias referenced this issue

2026-06-22 06:15:02 +00:00

feat: brain_update — supersede-by-slug write verb (+ read-after-write: brain_get, brain_write handle) #45