mathias/hyperguild
1
0
Fork 0
Code Issues 30 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

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

New Issue
Closed
opened 2026-06-06 06:10:30 +00:00 by mathias · 1 comment
mathias commented 2026-06-06 06:10:30 +00:00
Owner
Copy Link
Copy Source

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.

{
  "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:

  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
## 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
mathias commented 2026-06-22 05:43:04 +00:00
Author
Owner
Copy Link
Copy Source

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.

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.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
agent/ready
Meets the agent-ready contract; authorizes unattended execution
 blocked/client
Waiting on the client
 blocked/supplier
Waiting on a supplier
 blocked/upstream
Waiting on an upstream project or vendor
 risk/high
Irreversible, security-relevant, or control plane
 risk/low
Reversible, local, test-covered
 risk/medium
Touches shared state, deploys or data
 size/l
Too big - split it
 size/m
Under two days
 size/s
Under half a day
 size/xs
Under an hour
 status:dispatch
status:dispatched
status:review
status:reviewing
type/chore
Maintenance, no behaviour change
 type/decision
Human decision required; never agent/ready
 type/docs
Documentation only
 type/feat
New capability
 type/fix
Corrects broken behaviour
 type/ops
Infrastructure, deploy, runtime
 type/research
Investigate; output is a finding, not code
 type/test
Test coverage only
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
renovate-bot mathias
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mathias/hyperguild#37