The brain write pipeline has a documented gap: notes written to brain/raw/ by the retrospective skill have no tooling to support the human review and promotion step. The only way to move a note from raw/ to wiki/<wing>/<hall>/ is to manually move the file, rename it, update frontmatter, and optionally add wikilinks.
This is the single highest-friction step in the DIKW pipeline for a human curator. It was identified in the 2026-05-06 GitOps workflow session and never tracked as an issue.
Two tools needed
brain_pending
Lists files currently sitting in brain/raw/ awaiting review.
{"name":"brain_pending","description":"List notes in brain/raw/ awaiting human review and promotion to wiki.","inputSchema":{"type":"object","properties":{"limit":{"type":"integer","description":"max results, default 20"}}}}
Returns per file: filename, created_at, excerpt (first 200 chars of body after frontmatter). Sorted newest-first. Gives both the human and the agent visibility into the review queue without requiring a terminal.
brain_promote
Moves a note from brain/raw/ to brain/wiki/<wing>/<hall>/, rewrites frontmatter, and triggers auto-tunnel detection.
{"name":"brain_promote","description":"Promote a note from brain/raw/ to brain/wiki/<wing>/<hall>/. Rewrites frontmatter, runs auto-tunnel detection.","inputSchema":{"type":"object","required":["filename","wing","hall","slug"],"properties":{"filename":{"type":"string","description":"filename in brain/raw/ (with or without .md)"},"wing":{"type":"string","description":"target wing, e.g. hyperguild"},"hall":{"type":"string","enum":["facts","decisions","failures","hypotheses","sources"]},"slug":{"type":"string","description":"target filename slug, e.g. two-agent-gitops-handoff"}}}}
Steps performed atomically:
Read brain/raw/<filename>.md
Rewrite frontmatter: set wing, hall, created_at (preserve original if present), remove raw-stage markers
Write to brain/wiki/<wing>/<hall>/<slug>.md
Delete brain/raw/<filename>.md
Run auto-tunnel detection on the promoted note's content (same logic as post-brain_write)
Rebuild _index.md for the target wing
Non-destructive: if step 3 fails (e.g. slug already exists), the raw file is left untouched and an error is returned.
Implementation notes
Both tools live in ingestion/internal/mcp/ following the existing tool pattern
REST equivalents: GET /pending and POST /promote on the ingestion HTTP API (for completeness, not required for MCP-first use)
brain_pending is read-only — LOW risk tier
brain_promote is a move operation — MEDIUM risk tier (reversible only if you have the content; slug collision guard prevents data loss)
Tests: pending on empty dir, pending with files, promote happy path, promote slug-collision error, promote missing source file
Acceptance criteria
brain_pending returns list of files in brain/raw/ with excerpt
#27 (claudewatcher) — primary producer of raw/ entries
#32 (brain injection audit) — quality of what gets promoted matters
Hyperguild issues #1, #2 (Hall taxonomy + tunnels) — the destination layout these tools write to
## Context
The brain write pipeline has a documented gap: notes written to `brain/raw/` by the `retrospective` skill have no tooling to support the human review and promotion step. The only way to move a note from `raw/` to `wiki/<wing>/<hall>/` is to manually move the file, rename it, update frontmatter, and optionally add wikilinks.
This is the single highest-friction step in the DIKW pipeline for a human curator. It was identified in the 2026-05-06 GitOps workflow session and never tracked as an issue.
## Two tools needed
### `brain_pending`
Lists files currently sitting in `brain/raw/` awaiting review.
```json
{
"name": "brain_pending",
"description": "List notes in brain/raw/ awaiting human review and promotion to wiki.",
"inputSchema": {
"type": "object",
"properties": {
"limit": { "type": "integer", "description": "max results, default 20" }
}
}
}
```
Returns per file: `filename`, `created_at`, `excerpt` (first 200 chars of body after frontmatter). Sorted newest-first. Gives both the human and the agent visibility into the review queue without requiring a terminal.
### `brain_promote`
Moves a note from `brain/raw/` to `brain/wiki/<wing>/<hall>/`, rewrites frontmatter, and triggers auto-tunnel detection.
```json
{
"name": "brain_promote",
"description": "Promote a note from brain/raw/ to brain/wiki/<wing>/<hall>/. Rewrites frontmatter, runs auto-tunnel detection.",
"inputSchema": {
"type": "object",
"required": ["filename", "wing", "hall", "slug"],
"properties": {
"filename": { "type": "string", "description": "filename in brain/raw/ (with or without .md)" },
"wing": { "type": "string", "description": "target wing, e.g. hyperguild" },
"hall": { "type": "string", "enum": ["facts", "decisions", "failures", "hypotheses", "sources"] },
"slug": { "type": "string", "description": "target filename slug, e.g. two-agent-gitops-handoff" }
}
}
}
```
Steps performed atomically:
1. Read `brain/raw/<filename>.md`
2. Rewrite frontmatter: set `wing`, `hall`, `created_at` (preserve original if present), remove raw-stage markers
3. Write to `brain/wiki/<wing>/<hall>/<slug>.md`
4. Delete `brain/raw/<filename>.md`
5. Run auto-tunnel detection on the promoted note's content (same logic as post-`brain_write`)
6. Rebuild `_index.md` for the target wing
Non-destructive: if step 3 fails (e.g. slug already exists), the raw file is left untouched and an error is returned.
## Implementation notes
- Both tools live in `ingestion/internal/mcp/` following the existing tool pattern
- REST equivalents: `GET /pending` and `POST /promote` on the ingestion HTTP API (for completeness, not required for MCP-first use)
- `brain_pending` is read-only — LOW risk tier
- `brain_promote` is a move operation — MEDIUM risk tier (reversible only if you have the content; slug collision guard prevents data loss)
- Tests: pending on empty dir, pending with files, promote happy path, promote slug-collision error, promote missing source file
## Acceptance criteria
- [ ] `brain_pending` returns list of files in `brain/raw/` with excerpt
- [ ] `brain_promote` moves file, rewrites frontmatter correctly, deletes source, triggers tunnel detection
- [ ] Slug collision returns error, raw file left intact
- [ ] `task check` passes
- [ ] Both tools registered in `ingestion/internal/mcp/server.go`
## Related
- Identified in 2026-05-06 GitOps workflow session (genesis of gitea-mcp)
- brain note: `wiki/hyperguild/decisions/two-agent-gitops-handoff-via-pr-comments.md`
- #27 (claudewatcher) — primary producer of raw/ entries
- #32 (brain injection audit) — quality of what gets promoted matters
- Hyperguild issues #1, #2 (Hall taxonomy + tunnels) — the destination layout these tools write to
Closing as duplicate of #38. Both were filed ~2 min apart in the same 2026-05-06 genesis session and spec the identical brain_pending + brain_promote pair with the same five-step promote logic and risk tiers.
Implementation note carried to #38: both issues assume the old brain/raw/ → brain/wiki/ layout. Per #43 the current layout is knowledge/ (unreviewed) → wiki/ (promoted). Paths to be reconciled at implementation time.
Tracked as the "promote half" of the broader interface problem in #43.
Closing as duplicate of #38. Both were filed ~2 min apart in the same 2026-05-06 genesis session and spec the identical `brain_pending` + `brain_promote` pair with the same five-step promote logic and risk tiers.
Keeping #38 because it's strictly stronger:
- `brain_pending` sorts oldest-first (natural review order) vs. newest-first here
- explicit empty-dir → `[]` (not error), invalid-`hall` validated before any filesystem touch
- explicit write-then-delete atomicity guarantee
- fuzzy tunnel candidates written to a sidecar
- agent/human split stated outright (agents write `wiki/` directly; humans promote from `raw/`)
Implementation note carried to #38: both issues assume the old `brain/raw/` → `brain/wiki/` layout. Per #43 the current layout is `knowledge/` (unreviewed) → `wiki/` (promoted). Paths to be reconciled at implementation time.
Tracked as the "promote half" of the broader interface problem in #43.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Context
The brain write pipeline has a documented gap: notes written to
brain/raw/by theretrospectiveskill have no tooling to support the human review and promotion step. The only way to move a note fromraw/towiki/<wing>/<hall>/is to manually move the file, rename it, update frontmatter, and optionally add wikilinks.This is the single highest-friction step in the DIKW pipeline for a human curator. It was identified in the 2026-05-06 GitOps workflow session and never tracked as an issue.
Two tools needed
brain_pendingLists files currently sitting in
brain/raw/awaiting review.Returns per file:
filename,created_at,excerpt(first 200 chars of body after frontmatter). Sorted newest-first. Gives both the human and the agent visibility into the review queue without requiring a terminal.brain_promoteMoves a note from
brain/raw/tobrain/wiki/<wing>/<hall>/, rewrites frontmatter, and triggers auto-tunnel detection.Steps performed atomically:
brain/raw/<filename>.mdwing,hall,created_at(preserve original if present), remove raw-stage markersbrain/wiki/<wing>/<hall>/<slug>.mdbrain/raw/<filename>.mdbrain_write)_index.mdfor the target wingNon-destructive: if step 3 fails (e.g. slug already exists), the raw file is left untouched and an error is returned.
Implementation notes
ingestion/internal/mcp/following the existing tool patternGET /pendingandPOST /promoteon the ingestion HTTP API (for completeness, not required for MCP-first use)brain_pendingis read-only — LOW risk tierbrain_promoteis a move operation — MEDIUM risk tier (reversible only if you have the content; slug collision guard prevents data loss)Acceptance criteria
brain_pendingreturns list of files inbrain/raw/with excerptbrain_promotemoves file, rewrites frontmatter correctly, deletes source, triggers tunnel detectiontask checkpassesingestion/internal/mcp/server.goRelated
wiki/hyperguild/decisions/two-agent-gitops-handoff-via-pr-comments.mdClosing as duplicate of #38. Both were filed ~2 min apart in the same 2026-05-06 genesis session and spec the identical
brain_pending+brain_promotepair with the same five-step promote logic and risk tiers.Keeping #38 because it's strictly stronger:
brain_pendingsorts oldest-first (natural review order) vs. newest-first here[](not error), invalid-hallvalidated before any filesystem touchwiki/directly; humans promote fromraw/)Implementation note carried to #38: both issues assume the old
brain/raw/→brain/wiki/layout. Per #43 the current layout isknowledge/(unreviewed) →wiki/(promoted). Paths to be reconciled at implementation time.Tracked as the "promote half" of the broader interface problem in #43.