SyncytiumMD

# SyncytiumMD

> One canonical `.syncytium/` context transpiled into every AI coding tool,
> with a multi-agent handoff baton and a lease-based workspace lock.

- Version: 0.3.1
- npm: https://www.npmjs.com/package/syncytium-md
- Repository: https://github.com/mrcbrbn5361/SyncytiumMD
- MCP Registry name: io.github.mrcbrbn5361/syncytiummd
- License: MIT

## Run the MCP server

```json
{
  "mcpServers": {
    "syncytium": {
      "command": "npx",
      "args": [
        "--ignore-scripts",
        "-y",
        "-p",
        "syncytium-md@0.3.1",
        "syncytium-mcp"
      ]
    }
  }
}
```

```bash
npx -y -p syncytium-md@0.3.1 syncytium-mcp
```

## Tools (23)

Every input is validated with zod before it reaches the engine, every tool
declares MCP safety annotations, and all calls are rate limited in-process.

- `syncytium_create_rule` — Create a canonical rule (write)
- `syncytium_diff` — Check context drift (read)
- `syncytium_doctor` — Read-only workspace health check (read)
- `syncytium_get_context` — Get canonical context (read)
- `syncytium_get_graph` — Get the knowledge graph (read)
- `syncytium_get_history` — Get handoff history (read)
- `syncytium_handoff` — Record agent handoff (write)
- `syncytium_import` — Import unmanaged rule files (write)
- `syncytium_lint` — Lint canonical content (read)
- `syncytium_list_decisions` — List ADRs (read)
- `syncytium_list_rules` — List canonical rules (read)
- `syncytium_list_trash` — List recoverable deletions (read)
- `syncytium_lock_acquire` — Acquire the workspace lease (write)
- `syncytium_lock_release` — Release the workspace lease (write)
- `syncytium_lock_status` — Read lease status (read)
- `syncytium_record_decision` — Record an ADR (write)
- `syncytium_remove_decision` — Archive and remove an ADR (destructive)
- `syncytium_remove_rule` — Archive and remove a canonical rule (destructive)
- `syncytium_restore` — Restore an archived rule or ADR (write)
- `syncytium_sync` — Regenerate bridge files and prune orphans (destructive)
- `syncytium_update_rule` — Update a canonical rule (write)
- `syncytium_validate` — Validate config and rule frontmatter (read)
- `syncytium_validate_fix` — Repair invalid config or frontmatter (write)

## Canonical workspace

- `.syncytium/rules/` — stack-aware rules with zod-validated frontmatter
- `.syncytium/memory/decisions.md` — architectural decision records
- `.syncytium/HANDOFF.md` — live agent handoff baton
- `.syncytium/memory/lock.json` — machine-local workspace lease
- `syncytium sync` — regenerate bridge files; `syncytium diff --check` — drift gate

## More

- `llms-full.txt` — full rule and ADR text
- `server.json` — MCP Registry manifest
- `README.md` — setup and CLI reference

## Canonical rules (5)

### adapter-standards — AI Tool Adapter Guidelines & Architecture

> Standards for implementing new IDE and CLI bridge adapters in SyncytiumMD

Tags: #architecture #adapters #extensibility

# AI Tool Adapter Guidelines

When adding or updating adapters in `src/adapters/`:
1. **Interface Contract:**
   - Every adapter must implement `AgentAdapter` from `src/core/types.ts`.
   - Implement `readonly id`, `readonly name`, `readonly category`, `readonly description`, `readonly defaultTargetFiles`.
2. **Deterministic Output:**
   - The `generate(context: CanonicalContext)` method must return an array of `GeneratedFile[]`.
   - Every file must include a leading or trailing SyncytiumMD header comment (e.g. `# Auto-generated by SyncytiumMD`) unless the format forbids comments.
3. **Preserve User Modifications:**
   - Adapters should respect user custom sections where supported.
4. **Registration:**
   - Register all new adapters in `AdapterRegistry` (`src/adapters/registry.ts`).
5. **Coverage:**
   - Add unit tests verifying target file generation in `tests/syncytium.test.ts`.

### code-style — Code Style & Formatting

> Enforce clean, readable, modern standards across the project

Tags: #style #typescript #formatting

# Code Style & Formatting

- Write clean, modular, and self-documenting code.
- Always prefer strict types, immutable data structures, and pure functions where reasonable.
- Keep functions concise with a single responsibility.
- Preserve existing comments and documentation unless explicitly asked to modify them.
- Avoid unnecessary dependencies; prefer standard library APIs where possible.

## Repository-specific conventions

- **Comments explain *why*.** A comment restating what the code does is noise;
  a comment explaining a non-obvious constraint, a bug workaround, or a
  deliberate deviation is mandatory. Prefer a short comment at the point of
  the decision over a long block at the top of the file.
- **Never let a shared, cached object escape.** `gray-matter` hands back the
  same object for identical content, and `DEFAULT_CONFIG` / `INITIAL_RULES` /
  `INITIAL_DECISIONS` are module-level singletons. Copy before mutating
  (see `clone()` in `src/core/storage.ts` and `deepClone()` in the config path).
- **Order-dependent output is a bug.** Rule loading is sorted explicitly so
  generated files are byte-identical across platforms.
- **Derive, do not duplicate.** The version lives in `src/version.ts`, the
  Markdown renderer in `src/ui/markdown.ts` (injected into the browser bundle
  via `Function.prototype.toString()`), and path safety in `src/core/paths.ts`.
  A second copy will drift.
- When a bug is fixed, add a test that fails without the change and name the
  regression in the test description.

### release-criteria — Release & Verification Criteria

> Every change ships green: typecheck, build, tests, lint, and zero context drift

Tags: #release #ci #quality

# Release Criteria

A change is not done until all of these pass locally:

```bash
npm run typecheck   # tsc --noEmit over src/ and tests/
npm run build       # tsup, ESM + .d.ts
npm test            # 129 tests, build-first + dist-tests (Node 20+)
npm run verify      # all three, in order
```

## Before opening a PR

- `node dist/cli/index.js lint` — canonical rules and frontmatter are valid.
- `node dist/cli/index.js diff` — **no** drift between `.syncytium/` and the
  committed bridge files. Commit the regenerated files together with the change.
- `node dist/cli/index.js doctor` — no `error` checks. Warnings are acceptable
  only when they are pre-existing and unrelated.

## Releasing

`npm run release` runs the whole pipeline and **fails loudly**:

1. `typecheck` → `build` → `test`
2. `npm publish`
3. polls `npm view` with exponential backoff until the version is served
4. `npm install -g` and verifies the installed version

Never hand-edit `src/version.ts` or `package.json` version independently: a unit
test asserts they match, and `--bump` updates both together.

## Definition of done

- New behaviour has a test that fails without the change.
- Public behaviour changes are reflected in `README.md` **and** `README.tr.md`.
- Architectural decisions go into `.syncytium/memory/decisions.md` via
  `syncytium adr add`.
- The handoff baton is updated before the turn ends:
  `syncytium handoff --from "<agent>" -g "<goal>" -d "<done>" -t "<todo>"`.

### security — Security & Safe Coding

> Security rules, secrets handling, and sanitization

Tags: #security #boundaries

# Security & Boundaries

- The Obsidian Studio server binds to `127.0.0.1` and rejects any request whose
  `Host` header is not a loopback name. This is a DNS-rebinding guard: without
  it, any web page the user has open could read `/api/file` from their
  workspace. `--allow-remote` lifts the guard and must only be used knowingly.
- `Access-Control-Allow-Origin` is `null` (same-origin) by default.
- `/api/file` refuses in-root secrets (`.env*`, `*.pem`, `*.key`, `id_rsa`,
  `.npmrc`, `.netrc`, …) and everything under `.git/`, in addition to the
  path-traversal containment check.
- Rule ids arrive from user-authored frontmatter and are interpolated into
  generated file paths. **Every** path is slugified (`src/core/paths.ts`) and
  every write is re-checked against the workspace root before touching disk.
- The UI escapes `projectName` and all node ids, serialises its bootstrap config
  with `<`/`>`/`&`/U+2028 escaped, and uses event delegation instead of inline
  `onclick` — a hostile rule id in a cloned repo must not be able to run script.
- `syncytium clean` deletes only files carrying the Syncytium banner. A user's
  own `.cursor/rules/my-rule.mdc` is never touched.
- MCP tool inputs are validated with zod before they reach the engine.
- Every MCP tool declares honest `readOnlyHint` / `destructiveHint` /
  `idempotentHint` / `openWorldHint` annotations in `src/mcp/safety.ts`, and the
  server enforces a per-tool sliding-window rate limit there. A scanner or
  gateway can therefore reason about the surface, and a runaway agent loop is
  stopped in-process even when the client ignores the hints.
- Destructive MCP tools are safe by default: `dryRun` defaults to `true` and an
  actual delete requires `dryRun: false` **and** `confirm: true`.
- Deletions are recoverable. `removeRule` / `removeDecision` archive the exact
  source bytes under `.syncytium/memory/trash/` before touching the live file,
  and `syncytium_restore` / `restoreFromTrash` undo the operation.
- `syncytium_doctor` is strictly read-only. Its `fix` strings are suggestions;
  it never runs them, spawns processes, or edits git/CI state.
- Never log or echo secrets, tokens or full file contents to stdout: stdout is
  the MCP JSON-RPC transport.

### testing-standards — Testing Standards & Verification

> Quality assurance and test verification guidelines

Globs: `**/*.test.ts`, `**/*.test.tsx`, `**/*.spec.ts`, `tests/**/*`
Tags: #test #quality

## Testing Guidelines
- Write unit tests for all business logic and edge cases.
- Mock external network requests, timers, and heavy I/O in unit test suites.
- Verify tests pass before completing any implementation task.
- Follow the Arrange-Act-Assert pattern for test clarity.

## Architectural decisions (15)

### ADR-001 — Adopt SyncytiumMD as Universal Context Bridge

Status: accepted · 2026-09-19

**Context:** Multiple AI agents and IDEs (Cursor, Claude Code, Copilot, Cline, Antigravity, etc.) are used concurrently, leading to fragmented context and duplicated rules.

**Decision:** Use SyncytiumMD as the single source of truth (.syncytium/) to transpile and synchronize rules, memories, and handoff state across all AI coding tools.

**Consequences:** All tools stay in sync with zero manual copy-pasting. Changes in rules propagate automatically to all connected IDEs and CLIs.

### ADR-002 — Zero-Heavy-Dependencies Knowledge Graph UI

Status: accepted · 2026-09-19

**Context:** Users need an Obsidian-style visual brain graph of their rules, tags, and ADRs without installing heavy frontend runtimes (e.g. Next.js, Electron, or Express).

**Decision:** Implement an embedded Canvas-based force-directed graph server using native node:http and Server-Sent Events (SSE).

**Consequences:** Instant startup, zero external runtime weight, works offline, and automatically re-renders when files in .syncytium/ change.

### ADR-003 — Lease-Based Multi-Agent Collision Prevention Lock

Status: accepted · 2026-09-19

**Context:** When running multiple autonomous agents or human-AI handoffs, agents risk overwriting each other's active work simultaneously.

**Decision:** Introduce syncytium lock with time-expiring leases (e.g. 30-45 minutes) stored in .syncytium/memory/lock.json.

**Consequences:** Agents verify workspace availability before starting long autonomous runs; expired locks clear automatically without blocking forever.

### ADR-004 — Automated Release Pipeline with NPM CDN Replication Polling

Status: accepted · 2026-09-19

**Context:** Publishing to NPM immediately triggers ETARGET errors if global installation is attempted before edge CDNs replicate the new version tarball.

**Decision:** Implement scripts/release.mjs (npm run release) which verifies tests, publishes, polls npm view with exponential backoff until live, and then installs globally.

**Consequences:** Zero failed releases, automated verification, and frictionless developer workflow.

### ADR-005 — High-Performance 3D Knowledge Galaxy with Physics Sleep & Geometry Pooling

Status: accepted · 2026-09-19

**Context:** For large codebases with dozens of files, tags, and rules, the 3D WebGL knowledge graph experienced sluggish startup, canvas texture contention, and unbounded O(N^2) physics loop CPU load.

**Decision:** Implement Three.js unit sphere geometry and material caching/pooling, simulation alpha decay with auto-sleeping (0% idle CPU load), LOD lazy text sprite generation, floating hover tooltips, and compact view mode (--compact, --no-files, --no-tags).

**Consequences:** Silky 60+ FPS rendering, instant boot on large repositories, zero idle CPU consumption, and clean uncluttered visual brain inspection.

### ADR-006 — Make the drift gate capable of failing

Status: accepted · 2026-09-26

**Context:** syncytium diff computed hasDrift and printed a tip, but always exited 0. The generated GitHub Actions workflow step named 'Verify Zero Context Drift', the pre-commit hook's 'if [ \True -ne 0 ]' guard, and the README claim were therefore all no-ops: a drifted commit could never be caught.

**Decision:** Add diff --check, which exits 1 on any modified, missing or orphaned file. The CI template and the generated pre-commit hook both call it. doctor additionally inspects the workflow text and warns when it does not use --check, because an existing workflow silently keeps the old no-op behaviour.

**Consequences:** Drift is now a real gate. Projects upgrading with a previously generated .github/workflows/syncytium.yml must run syncytium ci --force once; doctor tells them so explicitly.

### ADR-007 — Never delete a directory that shares its name with a generated target

Status: accepted · 2026-09-26

**Context:** cleanManagedFiles ran fs.rm(dir, { recursive: true }) for directory targets such as .cursor/rules/ and .gemini/antigravity/rules/. A developer's own .cursor/rules/my-rule.mdc, which carries no Syncytium banner, was destroyed. Separately, deleting a rule left its generated files on disk forever, and diff declared an 'unmanaged' status it never produced.

**Decision:** clean now deletes only files carrying the Syncytium banner, file by file, and prunes a directory only once it is actually empty. sync additionally prunes banner-tagged files that the current rule set no longer generates, and diff reports them as 'unmanaged' with the reason.

**Consequences:** Hand-written rules in shared directories are safe. Removing a rule is now self-cleaning, so users no longer need to hunt down stale .mdc files by hand.

### ADR-008 — Escape every value that reaches the browser and stop inlining onclick handlers

Status: accepted · 2026-09-26

**Context:** The Obsidian Studio page interpolated projectName raw into the title element and the header, and serialised the bootstrap config with a bare JSON.stringify, so a value containing a script-closing tag terminated the block. Node ids, which come from user-authored rule frontmatter, were injected unescaped into data-id attributes and inline onclick handlers in seven places. A cloned repository containing a hostile rule id was therefore stored XSS.

**Decision:** projectName is HTML-escaped; the bootstrap config is serialised with angle brackets, ampersand and the U+2028/9 line separators escaped; the category value is allow-listed; and every node id is escaped and carried in a data-node-id attribute handled by one delegated document listener. No inline handlers and no globals on window remain.

**Consequences:** The page can no longer execute script from repository content. The trade-off is that the 17 inline onclick attributes had to go, which is why the two window.* exports were removed.

### ADR-009 — Deep-copy everything gray-matter returns

Status: accepted · 2026-09-26

**Context:** gray-matter caches parsed results by content string and hands back the same object on a repeated parse. addDecision pushed the new ADR into the array returned by loadDecisions, mutating that cached object. Removing the ADR again wrote a file whose frontmatter listed one decision, yet loadDecisions kept returning two for the rest of the process. DEFAULT_CONFIG, INITIAL_RULES and INITIAL_DECISIONS are module-level singletons with the same hazard.

**Decision:** Every loader in SyncytiumStorage deep-copies its result before returning: loadDecisions, loadHandoff, loadHandoffHistory and the config path. Module-level templates are cloned before use. A regression test asserts that mutating one loaded config does not affect the next read.

**Consequences:** Callers may safely mutate what they get back. The cost is a JSON round-trip per load, which is irrelevant at this data size and is not on the hot path of a sync.

### ADR-010 — zod is the single validation boundary

Status: accepted · 2026-09-26

**Context:** SyncytiumConfigSchema was declared and never used: loadConfig did a bare JSON.parse and a cast, so a corrupt config silently fell back to defaults and doctor's config try/catch could never fire. Rule frontmatter, ADRs, handoff status and every MCP tool input were equally unvalidated, and several MCP handlers cast args to any.

**Decision:** All validation lives in src/core/schemas.ts. loadConfigDetailed reports the exact field errors instead of swallowing them; doctor surfaces them as an error with a fix hint; validate --fix repairs the file. Every MCP tool input is parsed with a zod schema before it reaches the engine, and the shared parse helper returns a ready-made tool error rather than throwing.

**Consequences:** Invalid input is reported where the user is looking, not swallowed. A malformed config can no longer quietly reset enabledAdapters to the defaults and stop generating half the bridge files.

### ADR-011 — One Markdown renderer, injected into the browser

Status: accepted · 2026-09-26

**Context:** The client-side parser duplicated a server-side renderer and had drifted. Its code-fence rule was built with new RegExp from a string literal, where an escaped space class degrades to a character class matching only s and S, so fenced code never matched. The blockquote rule ran after escaping had already turned the angle bracket into an entity, so quotes rendered as raw text. List items were emitted with no enclosing list element, and code contents were subsequently rewritten by the header and list rules.

**Decision:** The renderer lives in src/ui/markdown.ts and is injected into the served page verbatim via Function.prototype.toString(), so the browser copy and the one used by syncytium export --html are the same code by construction. It escapes first, then transforms, and lifts fenced and inline code into placeholders so no later rule can touch it.

**Consequences:** One implementation, one place to fix, and the unit tests that cover the parser now cover the browser's copy too.

### ADR-012 — AGENTS.md and GEMINI.md are first-class targets

Status: accepted · 2026-09-26

**Context:** The adapter set covered the 2024-era IDE landscape but not the two conventions that have since become the de facto standard for non-IDE agents: AGENTS.md and GEMINI.md. Copilot's path-specific instruction files were also missing, so glob-scoped rules were flattened into a single always-apply document, and Roo Code had no mode definition to load.

**Decision:** Add two adapters, AgentsAdapter and GeminiAdapter, bringing the built-in set to ten. Copilot now also emits one .github/instructions/*.instructions.md per glob-scoped rule, and Cline emits a .roomodes architect mode. The Gemini adapter deliberately does not write .gemini/settings.json, because that schema is CLI-owned and inventing keys risks breaking the user's own configuration.

**Consequences:** Context reaches Codex-style and Gemini CLI agents without a manual copy-paste, and glob-scoped rules are enforced per path in Copilot instead of everywhere. The roomodes file uses hash comments rather than the HTML banner so it stays valid YAML; the banner detector keys off the marker text, not the comment style.

### ADR-013 — Real file and directory graph nodes for the 3D vault

Status: accepted · 2026-11-05

**Context:** v0.3.0 built file nodes from each adapter's defaultTargetFiles, which includes directories such as .cursor/rules/. Clicking Cursor opened a dead 404 because /api/file cannot read a directory, and the seven generated .mdc rules were absent from the graph entirely.

**Decision:** Generate the actual adapter output in memory and expose each generated file as a file node, each declared or implied directory as a new dir node, and an adapter 'used' flag derived from whether its targets exist on disk. Add /api/list for directory contents and make /api/file return 400 with isDirectory for a directory instead of a misleading 404.

**Consequences:** The Obsidian studio now lists real files per tool and opens their Markdown. The graph does one extra generateAll per request, which is cheap for ten adapters but adds work on very large rule sets.

### ADR-014 — Structured MCP outputs and a read-only validate tool

Status: accepted · 2026-11-05

**Context:** Catalogue scanners grade a server by the honesty of its tool contract. v0.3.0 advertised output-free read tools, closed nothing, and marked syncytium_validate as a write tool even though it only mutated when fix:true.

**Decision:** Declare outputSchema for every stable read tool and return matching structuredContent, close every inputSchema with additionalProperties:false, describe every property, and split mutation into a separate syncytium_validate_fix write tool. syncytium_validate is now strictly read-only.

**Consequences:** Scanners and clients can validate results mechanically and the annotations match behaviour. The tool count grows from 22 to 23 and get_context stays polymorphic, so it deliberately has no outputSchema.

### ADR-015 — Publish MCP metadata from CI with OIDC only

Status: accepted · 2026-11-05

**Context:** Discovery by MCP catalogues and agents requires an official server.json at registry.modelcontextprotocol.io. Manual publishing needs a long-lived credential and drifts from the repository, and any secret posted in chat must never be committed.

**Decision:** Add server.json plus deterministic llms.txt and llms-full.txt, and publish both through a GitHub Actions workflow that uses GitHub OIDC with id-token: write, verifies the mcp-publisher binary with cosign, waits for npm to serve the version, and skips a version already listed. The npm package declares mcpName so the registry can verify ownership.

**Consequences:** No stored secret, no third-party posting, and each release publishes verifiable metadata. Publishing only happens for a release or an explicit manual run, and the registry is in preview.