{
  "$schema": "https://meshkore.com/standard.schema.json",
  "name": "MeshKore Standard",
  "version": "12.0.0",
  "updated": "2026-06-02",
  "canonical_url": "https://meshkore.com/standard",
  "canonical_md": "https://meshkore.com/standard.md",
  "rule": "If anything elsewhere contradicts this document, this document wins.",
  "folder_layout": {
    "root": ".meshkore/",
    "entries": [
      {
        "path": "public/",
        "committed": true,
        "purpose": "identity, type, admission, members, modules (cluster.yaml + README.md). Only this dir reaches git."
      },
      {
        "path": "public/cluster.yaml",
        "committed": true,
        "purpose": "cluster identity + admission + modules (see schema 'cluster_yaml')"
      },
      {
        "path": "public/README.md",
        "committed": true,
        "purpose": "how to join this cluster (human-readable)"
      },
      {
        "path": "docs/",
        "committed": false,
        "purpose": "cross-cutting docs: architecture / product / conventions / deploy / security / ops"
      },
      {
        "path": "docs/INDEX.md",
        "committed": false,
        "purpose": "map only, no prose (R6)"
      },
      {
        "path": "docs/governance.md",
        "committed": false,
        "purpose": "thin pointer to https://meshkore.com/standard \u2014 never a duplicated copy"
      },
      {
        "path": "modules/<id>/",
        "committed": false,
        "purpose": "per-module bucket: README + tasks + log + diagrams"
      },
      {
        "path": "modules/<id>/tasks/<ID>-<slug>.md",
        "committed": false,
        "purpose": "active tasks for this module"
      },
      {
        "path": "modules/<id>/log/<YYYY-MM>/",
        "committed": false,
        "purpose": "archived (done) tasks, monthly buckets"
      },
      {
        "path": "modules/<id>/diagrams/",
        "committed": false,
        "purpose": "mermaid sources next to the doc they illustrate"
      },
      {
        "path": "roadmap/state.json",
        "committed": false,
        "generated": true,
        "purpose": "built by roadmap-build.py; never hand-edit"
      },
      {
        "path": "roadmap/state.js",
        "committed": false,
        "generated": true,
        "purpose": "same as state.json wrapped as JS for the architect"
      },
      {
        "path": "roadmap/initiatives/<id>.md",
        "committed": false,
        "purpose": "cross-module initiatives (see schema 'initiative_frontmatter')"
      },
      {
        "path": "timeline/<YYYY-MM-DD>.jsonl",
        "committed": false,
        "generated": true,
        "purpose": "one event per line, UTC, append-only"
      },
      {
        "path": "log/<YYYY-MM-DD>.md",
        "committed": false,
        "purpose": "human prose session log (local date)"
      },
      {
        "path": "agents/<id>.yaml",
        "committed": false,
        "purpose": "per-machine agent identity"
      },
      {
        "path": "credentials/",
        "committed": false,
        "purpose": "secrets, mode 0600"
      },
      {
        "path": "scripts/",
        "committed": false,
        "purpose": "helpers downloaded from /reference/cluster/scripts/"
      },
      {
        "path": "architect/",
        "committed": false,
        "purpose": "cached visualizer"
      },
      {
        "path": ".runtime/",
        "committed": false,
        "purpose": "daemon ephemera"
      }
    ],
    "gitignore_contract": [
      ".meshkore/*",
      "!.meshkore/public/"
    ]
  },
  "cluster_yaml": {
    "required_fields": [
      "version",
      "id",
      "type",
      "name",
      "transport.endpoint",
      "modules"
    ],
    "fields": {
      "version": {
        "type": "integer",
        "literal": 1
      },
      "id": {
        "type": "string",
        "pattern": "^[a-z0-9-]{2,40}$"
      },
      "type": {
        "type": "string",
        "enum": [
          "dev",
          "comms",
          "service",
          "mixed"
        ]
      },
      "name": {
        "type": "string"
      },
      "description": {
        "type": "string",
        "optional": true
      },
      "transport": {
        "type": "object",
        "fields": {
          "protocol": {
            "type": "string",
            "enum": [
              "websocket",
              "sse",
              "nats"
            ],
            "default": "websocket"
          },
          "endpoint": {
            "type": "string",
            "format": "uri",
            "required": true
          },
          "fallback": {
            "type": "string",
            "format": "uri",
            "optional": true
          }
        }
      },
      "bootstrap": {
        "type": "object",
        "optional": true,
        "fields": {
          "hub": {
            "type": "string",
            "format": "uri"
          },
          "install": {
            "type": "string",
            "format": "uri"
          },
          "operate": {
            "type": "string",
            "format": "uri"
          },
          "standard": {
            "type": "string",
            "format": "uri"
          },
          "spec": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "git": {
        "type": "object",
        "optional": true,
        "fields": {
          "repo": {
            "type": "string"
          },
          "branch": {
            "type": "string",
            "default": "main"
          },
          "auto_pull": {
            "type": "boolean",
            "default": true
          },
          "auto_commit": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "architect": {
        "type": "object",
        "fields": {
          "port": {
            "type": "integer",
            "default": 5570
          }
        }
      },
      "profile": {
        "type": "object",
        "fields": {
          "capabilities": {
            "type": "array",
            "items": "string",
            "default": []
          },
          "visible_in_directory": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "admission": {
        "type": "object",
        "fields": {
          "mode": {
            "type": "string",
            "enum": [
              "pubkey",
              "manual",
              "open"
            ],
            "default": "pubkey"
          },
          "approval": {
            "type": "string",
            "enum": [
              "auto",
              "auto-on-github",
              "manual"
            ],
            "default": "manual"
          },
          "github_users": {
            "type": "array",
            "items": "string"
          },
          "admission_token_lifetime": {
            "type": "integer",
            "default": 3600
          },
          "max_pending_requests": {
            "type": "integer",
            "default": 50
          }
        }
      },
      "members": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "id",
            "role",
            "pubkey",
            "pubkey_fingerprint",
            "authorized_at",
            "authorized_by"
          ],
          "fields": {
            "id": {
              "type": "string"
            },
            "role": {
              "type": "string",
              "enum": [
                "coordinator",
                "participant"
              ]
            },
            "pubkey": {
              "type": "string"
            },
            "pubkey_fingerprint": {
              "type": "string",
              "pattern": "^SHA256:"
            },
            "github_user": {
              "type": "string",
              "optional": true
            },
            "authorized_at": {
              "type": "string",
              "format": "date"
            },
            "authorized_by": {
              "type": "string"
            }
          }
        }
      },
      "modules": {
        "type": "array",
        "min": 1,
        "must_include_id": "general",
        "items": {
          "type": "object",
          "required": [
            "id",
            "kind"
          ],
          "fields": {
            "id": {
              "type": "string",
              "pattern": "^[a-z0-9-]{2,40}$"
            },
            "name": {
              "type": "string",
              "optional": true
            },
            "kind": {
              "type": "string",
              "enum": [
                "code",
                "spec",
                "docs",
                "area"
              ]
            },
            "path": {
              "type": "string",
              "optional": true
            },
            "parent": {
              "type": "string",
              "optional": true
            },
            "description": {
              "type": "string",
              "optional": true
            }
          }
        }
      }
    }
  },
  "task_frontmatter": {
    "location_template": ".meshkore/modules/<module-id>/tasks/<ID>-<slug>.md",
    "required": [
      "id",
      "title",
      "status",
      "priority",
      "owner",
      "category",
      "created",
      "updated"
    ],
    "fields": {
      "id": {
        "type": "string",
        "pattern": "^[A-Z][A-Z0-9]{0,3}\\d+$"
      },
      "title": {
        "type": "string"
      },
      "status": {
        "type": "string",
        "enum": [
          "backlog",
          "next",
          "active",
          "blocked",
          "done"
        ]
      },
      "priority": {
        "type": "string",
        "enum": [
          "low",
          "medium",
          "high",
          "critical"
        ]
      },
      "owner": {
        "type": "string"
      },
      "category": {
        "type": "string",
        "description": "MUST equal a declared module id from cluster.yaml"
      },
      "created": {
        "type": "string",
        "format": "date"
      },
      "updated": {
        "type": "string",
        "format": "date"
      },
      "tags": {
        "type": "array",
        "items": "string",
        "optional": true
      },
      "depends_on": {
        "type": "array",
        "items": "string",
        "optional": true
      },
      "initiative": {
        "type": "string",
        "optional": true
      },
      "parent_initiative": {
        "type": "string",
        "optional": true
      },
      "order": {
        "type": "integer",
        "min": 0,
        "max": 9,
        "optional": true
      },
      "effort": {
        "type": "string",
        "optional": true
      }
    },
    "done_handling": "When status becomes 'done', move file from modules/<id>/tasks/ to modules/<id>/log/<YYYY-MM>/. Frontmatter unchanged."
  },
  "protocols": {
    "location": ".meshkore/protocols/",
    "purpose": "Reusable, indexed multi-step runbooks. Cross-cutting work that touches multiple scopes (docs + code + commit + deploy). When the operator says `apply P<N>`, an agent executes the Steps section and files a run log.",
    "identifier": "P<N> \u2014 letter-prefix-then-number, joining the cluster's existing T/V/D/C/N/AG family.",
    "file_naming": "P<N>-<slug>.md, one protocol per file. Filename prefix MUST match the `id` field in frontmatter.",
    "frontmatter": {
      "required": [
        "id",
        "title",
        "scope",
        "status",
        "priority",
        "owner",
        "created",
        "updated"
      ],
      "fields": {
        "id": {
          "type": "string",
          "pattern": "^P\\d+$"
        },
        "title": {
          "type": "string"
        },
        "scope": {
          "type": "string",
          "enum": [
            "cluster",
            "project",
            "module"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "draft",
            "stable",
            "deprecated"
          ]
        },
        "priority": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high",
            "critical"
          ]
        },
        "owner": {
          "type": "string"
        },
        "created": {
          "type": "string",
          "format": "date"
        },
        "updated": {
          "type": "string",
          "format": "date"
        },
        "tags": {
          "type": "array",
          "items": "string",
          "optional": true
        },
        "needs_inputs": {
          "type": "array",
          "items": "string",
          "optional": true
        }
      }
    },
    "body_sections": [
      "Goal",
      "When to apply",
      "Inputs",
      "Preconditions",
      "Steps",
      "Verification",
      "Rollback",
      "Related"
    ],
    "run_log": {
      "location": ".meshkore/protocols/log/<YYYY-MM>/P<N>-<YYYY-MM-DD>-<context>.md",
      "frontmatter": {
        "required": [
          "protocol",
          "date",
          "operator",
          "agent",
          "outcome"
        ]
      }
    },
    "gitignore": "Commit the protocol files + INDEX.md; keep log/ local per machine.",
    "endpoints": {
      "GET  /protocols": "no-auth, list (id, title, scope, status, updated, log_count)",
      "GET  /protocols/<id>": "no-auth, raw markdown + parsed frontmatter",
      "GET  /protocols/<id>/runs": "no-auth, recent run-log entries (latest 50)",
      "WS broadcast": "protocols.updated on file change"
    }
  },
  "links_registry": {
    "location": ".meshkore/public/links.yaml",
    "purpose": "Source of truth for where each module runs locally, where it is deployed in production, and what version is live. Replaces ad-hoc links.md lists.",
    "scope": "Optional file. Projects that deploy nothing may omit it. The daemon treats a missing file as { version: 1, modules: [] }.",
    "schema": {
      "version": {
        "type": "integer",
        "const": 1
      },
      "modules": {
        "type": "array",
        "items": {
          "id": {
            "type": "string",
            "description": "MUST match cluster.yaml.modules[].id"
          },
          "local": {
            "type": "object",
            "optional": true,
            "fields": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "command": {
                "type": "string"
              },
              "health": {
                "type": "string",
                "optional": true
              }
            }
          },
          "prod": {
            "type": "object",
            "optional": true,
            "fields": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "provider": {
                "type": "string",
                "enum": [
                  "fly",
                  "cloudflare-pages",
                  "cloudflare-workers",
                  "vercel",
                  "render",
                  "self-hosted",
                  "other"
                ]
              },
              "project": {
                "type": "string",
                "description": "Provider-side project/app name"
              },
              "region": {
                "type": "string",
                "optional": true
              },
              "deploy_command": {
                "type": "string",
                "optional": true
              },
              "deployed_version": {
                "type": "string",
                "optional": true
              },
              "deployed_sha": {
                "type": "string",
                "optional": true
              },
              "deployed_at": {
                "type": "string",
                "format": "date-time",
                "optional": true
              },
              "deployed_by": {
                "type": "string",
                "optional": true
              }
            }
          },
          "repo": {
            "type": "object",
            "optional": true,
            "fields": {
              "branch": {
                "type": "string"
              },
              "head_sha": {
                "type": "string"
              },
              "version": {
                "type": "string",
                "optional": true
              }
            }
          },
          "notes": {
            "type": "string",
            "optional": true
          }
        }
      }
    },
    "maintenance": "Agent-maintained. Every commit that changes where a module runs, where it deploys, what branch it lives on, or what version it carries MUST update the matching entry in the same commit (extension of \u00a76 commit conventions).",
    "endpoints": {
      "GET  /links": "no-auth, full registry as JSON",
      "GET  /links/<id>": "no-auth, one module's entry",
      "POST /links/<id>": "bearer-auth, atomic patch of local/prod/repo blocks",
      "WS broadcast": "links.updated on every rewrite"
    }
  },
  "doc_frontmatter": {
    "location_template": ".meshkore/docs/<category>/<file>.md",
    "required": [
      "title",
      "category",
      "updated",
      "owner",
      "status"
    ],
    "fields": {
      "title": {
        "type": "string"
      },
      "category": {
        "type": "string",
        "enum": [
          "architecture",
          "product",
          "conventions",
          "deploy",
          "security",
          "ops",
          "modules",
          "governance"
        ]
      },
      "tags": {
        "type": "array",
        "items": "string",
        "optional": true
      },
      "updated": {
        "type": "string",
        "format": "date"
      },
      "owner": {
        "type": "string"
      },
      "status": {
        "type": "string",
        "enum": [
          "draft",
          "stable",
          "deprecated"
        ]
      },
      "related": {
        "type": "array",
        "items": "string",
        "optional": true
      }
    },
    "exemptions": [
      "INDEX.md (any folder)",
      "README.md (any folder)",
      ".meshkore/docs/governance.md",
      ".meshkore/log/**",
      ".meshkore/timeline/**",
      "generated files: state.json, state.js, directory.json"
    ]
  },
  "governance_rules": {
    "R1": {
      "title": "Categorize by intent, not by age",
      "categories": {
        "architecture": "How is the system built?",
        "product": "What are we, and why?",
        "conventions": "What rules must I follow?",
        "modules": "How does this specific code module work?",
        "deploy": "How do I run / deploy this?",
        "security": "What can go wrong?",
        "ops": "What's happening day-to-day?"
      }
    },
    "R2": {
      "title": "Max 200 lines per file",
      "split_when_over_lines": 200
    },
    "R3": {
      "title": "One topic, one canonical file"
    },
    "R4": {
      "title": "Frontmatter required (see doc_frontmatter)"
    },
    "R5": {
      "title": "Link, don't copy"
    },
    "R6": {
      "title": "INDEX.md is a map, not content"
    }
  },
  "log_streams": {
    "session": {
      "path_template": ".meshkore/log/<YYYY-MM-DD>.md",
      "format": "human prose, append-only, topic-grouped",
      "frontmatter": "not required (R4 exemption)",
      "date_zone": "local"
    },
    "timeline": {
      "path_template": ".meshkore/timeline/<YYYY-MM-DD>.jsonl",
      "format": "one JSON event per line",
      "generated_by": "daemon, build script, or .meshkore/scripts/timeline-append.py",
      "date_zone": "UTC",
      "event_shape": {
        "ts": "ISO-8601 UTC",
        "type": "string (task.started | task.completed | task.failed | chat.user | chat.assistant.delta | chat.assistant.final | commit.created | deploy.completed | ...)",
        "author": "member-id",
        "text": "free-form"
      }
    },
    "debug": {
      "path": ".meshkore/.runtime/debug.jsonl",
      "convention": "https://meshkore.com/reference/conventions/debug-stream",
      "feature_flag": "debug.stream.v1",
      "daemon_min_version": "py-1.10.17",
      "purpose": "Cross-component structured event stream the architect (or operator) tails to debug a session without screenshots. Daemon writes structured events directly; cockpit posts to POST /debug/log and the daemon stamps src='cockpit'.",
      "retention": "30 minutes OR 5 MB, whichever ceiling hits first. Trim is atomic \u2014 keep events whose ts is within the last 30 min, rewrite the file.",
      "gitignored": true,
      "event_shape": {
        "ts": "ISO-8601 UTC with ms (e.g. 2026-05-30T15:33:37.429Z) \u2014 required",
        "src": "enum: daemon | cockpit | agent \u2014 required (server-forced to 'cockpit' for POST /debug/log)",
        "lvl": "enum: debug | info | warn | error \u2014 required",
        "tag": "kebab-case event category, dotted sub-namespaces allowed (e.g. architect-wake.skipped) \u2014 required",
        "msg": "human-readable line, <= 4000 chars \u2014 required",
        "conv": "conv id when conv-scoped \u2014 optional",
        "agent_id": "Axx-style label \u2014 optional",
        "data": "structured payload, token-like keys auto-redacted \u2014 optional"
      },
      "canonical_tags": [
        "boot",
        "log",
        "chat-dispatch",
        "subagent-final",
        "architect-wake",
        "architect-wake.skipped",
        "architect-wake.failed",
        "init-archive",
        "http",
        "ux.run-all",
        "ux.stop-architect",
        "ux.validation",
        "transport.reconnect"
      ],
      "redaction": {
        "keys_masked": [
          "token",
          "authorization",
          "bearer",
          "api_key",
          "apikey",
          "secret",
          "password"
        ],
        "value_pattern": "strings starting with 'Bearer ' longer than 24 chars are replaced with 'Bearer <redacted>'",
        "applies_to": "data only; msg is not auto-scrubbed \u2014 producers must avoid embedding secrets in msg"
      },
      "endpoints": {
        "tail": {
          "method": "GET",
          "path": "/debug/tail",
          "auth": "Bearer <portal-token>",
          "since": "py-1.10.17",
          "query": {
            "last": "window in seconds, default 300",
            "tag": "comma-separated tag filter, optional",
            "level": "minimum level (debug < info < warn < error), default 'debug'"
          },
          "response_shape": {
            "events": "array of event objects, oldest first",
            "retained_secs": "int \u2014 actual age of the oldest event still on disk",
            "window_secs": "int \u2014 echo of the requested window",
            "generated_at": "ISO-8601 UTC"
          }
        },
        "log": {
          "method": "POST",
          "path": "/debug/log",
          "auth": "Bearer <portal-token>",
          "since": "py-1.10.17",
          "body": "single event OR {events: [...]}",
          "src_stamping": "server forces src='cockpit'; clients cannot forge src='daemon'",
          "response_shape": {
            "accepted": "int \u2014 number of events persisted"
          }
        }
      },
      "feature_detect": {
        "endpoint": "GET /health",
        "flag_path": "features.debug.stream.v1",
        "absent_means": "daemon predates py-1.10.17 \u2014 cockpit MUST disable its POST /debug/log transport, log to console only, and show a quiet 'debug stream needs daemon >= py-1.10.17' banner. Tail endpoint absence MUST NOT raise."
      },
      "additivity": "Consumers MUST ignore unknown tags and unknown data fields rather than reject. New tags require a one-line note in the convention's canonical-tags table."
    }
  },
  "path_conventions": [
    {
      "writing": "A new task to track",
      "path": ".meshkore/modules/<module>/tasks/<ID>-<slug>.md"
    },
    {
      "writing": "A done task being archived",
      "path": ".meshkore/modules/<module>/log/<YYYY-MM>/<ID>-<slug>.md"
    },
    {
      "writing": "A cross-module initiative",
      "path": ".meshkore/roadmap/initiatives/<id>.md"
    },
    {
      "writing": "Per-module README",
      "path": ".meshkore/modules/<id>/README.md"
    },
    {
      "writing": "Architecture / product / convention doc",
      "path": ".meshkore/docs/<category>/<slug>.md"
    },
    {
      "writing": "Diagram",
      "path": "<doc-slug>/diagrams/*.mmd (next to the doc it illustrates)"
    },
    {
      "writing": "Daily session log (prose)",
      "path": ".meshkore/log/<YYYY-MM-DD>.md"
    },
    {
      "writing": "Event timeline (machine)",
      "path": ".meshkore/timeline/<YYYY-MM-DD>.jsonl"
    },
    {
      "writing": "Cluster identity for the world",
      "path": ".meshkore/public/cluster.yaml"
    },
    {
      "writing": "Credentials / tokens / env vars",
      "path": ".meshkore/credentials/ (mode 0600, gitignored)"
    },
    {
      "writing": "Per-machine agent identity",
      "path": ".meshkore/agents/<id>.yaml"
    }
  ],
  "hard_rules": [
    "Never commit .meshkore/credentials/. Ever.",
    "Never commit anything under .meshkore/ outside public/.",
    "Never push to origin without the operator explicitly asking.",
    "Never edit generated files (state.json, state.js, directory.json, .runtime/**).",
    "Never invent a new top-level module / category without first declaring it in cluster.yaml.",
    "Never duplicate normative content from this standard into a local doc. Link to https://meshkore.com/standard.",
    "Every commit produced by an LLM agent must carry `Agent:` and `Model:` git trailers identifying the agent role and the model id (in addition to `Co-Authored-By:`). See `commit_attribution`."
  ],
  "editor_boot": {
    "filenames": {
      "claude": "CLAUDE.md",
      "cursor": ".cursorrules",
      "windsurf": ".windsurfrules"
    },
    "block_url": "https://meshkore.com/standard.md#8-editor-boot-block-canonical",
    "block_text": "See section 8 of the canonical document; paste verbatim. Editor-specific extras go BELOW the canonical block, never above."
  },
  "python_daemon": {
    "url": "https://meshkore.com/reference/cluster/scripts/daemon.py",
    "implementation": "python",
    "min_python": "3.8",
    "deps": "stdlib only (no pip, no venv)",
    "platforms": [
      "macos",
      "linux",
      "windows"
    ],
    "rationale": "Drops cleanly onto enterprise machines that block unsigned binaries. Any AI agent in an editor can curl-and-run it inside the repo.",
    "endpoints": {
      "GET  /health": "no-auth identity + cluster summary",
      "GET  /info": "no-auth /health + version + paths",
      "GET  /state": "no-auth filesystem-derived state.json",
      "GET  /reload": "bearer-auth rebuild + broadcast",
      "GET  /agents": "no-auth list of .meshkore/agents/*.yaml",
      "GET  /events": "WebSocket: hello, heartbeat, state.rebuilt, daemon.shutdown",
      "POST /shutdown": "bearer-auth graceful exit (the architect Stop button)"
    },
    "scope_today": "Single canonical L3 entry \u2014 read paths (visualization, file-derived state, multi-project listing, lifecycle) plus runner surface (agent dispatch, chat, headless claude --session-id, cron scheduling).",
    "stop_from_architect": "POST /shutdown with the bearer token from .meshkore/credentials/portal-token; the Projects rail Stop button does this."
  },
  "adding_projects": {
    "human_url": "https://meshkore.com/standard#10-3-adding-more-projects-to-your-architect",
    "modes": {
      "local": {
        "status": "available",
        "summary": "Paste the canonical prompt into an AI agent inside the new repo. The agent scaffolds .meshkore/, downloads the Python daemon, and starts it. Architect auto-detects via port scan.",
        "architect_button": "#projects-rail-add (opens modal in architect.meshkore.com)",
        "prompt_url": "https://meshkore.com/standard#10-3-1-the-canonical-apply-standard-prompt"
      },
      "cloud": {
        "status": "in-progress",
        "summary": "Add a remote project (teammate's laptop, VM, or mobile) by registering a bridge with a cloud relay. Architect connects to the relay instead of localhost. Owned by a separate work-stream \u2014 see hand-off prompt.",
        "transport_change": "architect -> cloud relay (WSS) -> bridge daemon (on remote machine) -> local Python daemon",
        "daemon_contract_preserved": true,
        "out_of_scope_for_standard": [
          "auth",
          "billing",
          "rate-limiting",
          "bridge<->relay transport"
        ]
      }
    }
  },
  "multi_project": {
    "model": "per-folder daemon",
    "summary": "Each .meshkore/-shaped repo runs its own Python daemon on its own port. Daemons coexist on the same machine; the architect probes the range and lists them.",
    "port_range": [
      5570,
      5589
    ],
    "default_port": 5570,
    "port_resolution": "Try cluster.yaml.architect.port first; on conflict scan 5570-5589 for the first free port; persist chosen port to .meshkore/.runtime/port.",
    "switch_in_architect": "One-click via the leftmost Projects rail. Switching swaps DAEMON_BASE + WebSocket; no separate URL.",
    "isolation": "Each daemon watches only its own .meshkore/. No cross-project bleeding of state, members, credentials, or tasks.",
    "future_initiative": "single-daemon-multi-project \u2014 a single daemon process managing many projects under one port. Roadmap, not v6.0.0."
  },
  "validation": {
    "local_command": "python3 .meshkore/scripts/roadmap-build.py --validate",
    "checks": [
      "folder layout matches \u00a72",
      "public/cluster.yaml validates against \u00a73",
      "every task has category matching its module id",
      "every task has required frontmatter fields",
      "every non-exempt doc has required frontmatter fields",
      ".gitignore contains the two-line contract from \u00a72.2"
    ],
    "ci_hook": "roadmap-build.py --validate; daemon runs it on boot; architect shows yellow warnings for invalid files"
  },
  "versioning": {
    "current": "6.0.0",
    "semver": {
      "major": "breaking change to folder layout, schemas, or hard rules",
      "minor": "new section, new optional field, new path convention",
      "patch": "clarifications, wording, examples"
    },
    "changelog_url": "https://meshkore.com/standard#11-versioning",
    "migration_signal": "On major bump, the daemon polls /standard/version and refuses cluster writes until the operator updates .meshkore/STANDARD_VERSION (after applying the manual migration block from CHANGELOG.md)."
  },
  "layer_model": {
    "L0": {
      "label": "folder",
      "needs_account": false,
      "needs_binary": false,
      "needs_network": false,
      "scope": "this standard"
    },
    "L1": {
      "label": "rules",
      "needs_account": false,
      "needs_binary": false,
      "needs_network": false,
      "scope": "this standard + editor boot block"
    },
    "L2": {
      "label": "hub",
      "needs_account": true,
      "needs_binary": false,
      "needs_network": true,
      "scope": "discoverability"
    },
    "L3": {
      "label": "daemon",
      "needs_account": false,
      "needs_binary": false,
      "needs_network": "localhost",
      "scope": "local automation"
    },
    "L4": {
      "label": "mesh",
      "needs_account": true,
      "needs_binary": false,
      "needs_network": true,
      "scope": "cross-cluster agent calls"
    }
  },
  "agent_protocol": {
    "fetch_at_session_start": "https://meshkore.com/standard/version",
    "fetch_full_schema": "https://meshkore.com/standard.json",
    "fetch_changelog_on_drift": "https://meshkore.com/standard/CHANGELOG.md",
    "cache_ttl_seconds": 86400,
    "before_writing_code": "Fetch the relevant standards/stack/<layer>.md and standards/audit/<stack>.md from /reference/standards/.",
    "on_drift": "If a local doc contradicts this standard, surface diff to the operator and ask before overriding. This standard is canonical for universal pieces; project-specific overrides must be marked as such."
  },
  "commit_attribution": {
    "applies_to": "Every git commit whose author or co-author is an LLM agent (Claude or otherwise). Human-only commits MAY omit; mixed-authored commits MUST include.",
    "format": "Git trailers appended to the commit message body (after a blank line, before the existing `Co-Authored-By:` trailer). Three required keys when authored by an LLM:",
    "trailers": {
      "Agent": {
        "description": "The agent ROLE / type that produced the commit. Comes from the daemon's `agent_type` field or the conv slug pattern.",
        "examples": [
          "master",
          "roadmap-architect",
          "work-I13-CAT2",
          "deploy-cavioca-prod",
          "review",
          "docs",
          "custom"
        ]
      },
      "Model": {
        "description": "The exact MODEL ID the agent ran under, as published by the model vendor.",
        "examples": [
          "claude-opus-4-8",
          "claude-opus-4-7",
          "claude-sonnet-4-6",
          "claude-haiku-4-5",
          "gpt-5",
          "cursor-default"
        ]
      },
      "Co-Authored-By": {
        "description": "Standard git trailer with the model's human-readable display name. Pre-existing convention; kept for GitHub UI attribution.",
        "example": "Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
      }
    },
    "example": "feat(rail): show waiting-on pill while subagents stream\n\nMaster polled its waiting list every 2s \u2014 replaced with WS-driven\nincrementals so the pill flips the moment a child finalises.\n\nAgent: master\nModel: claude-opus-4-7\nCo-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>",
    "rationale": "Field-reported 2026-06-02: a fast 'resync' pass from a roadmap-architect looked indistinguishable in git history from real subagent work. Trailers make the role and the model legible to git log / blame / analytics, enable cohort metrics across versions, and survive merges + cherry-picks unchanged.",
    "parsing": "`git interpret-trailers --parse` extracts these as RFC 5322 headers. Analytics example: `git log --format='%H%n%(trailers:key=Agent,valueonly,separator=)%n%(trailers:key=Model,valueonly,separator=)'`.",
    "non_llm": "Human-only commits MAY omit Agent + Model trailers. A commit by an agent that DOESN'T know its model id (rare; usually a misconfigured runner) MUST set `Model: unknown` \u2014 never omit silently.",
    "applies_to_subagents": "The daemon spawns subagents via Claude Code; the agent's spawn-time briefing now includes its own `Agent:` slug and `Model:` id, so each subagent stamps its own commits correctly without operator intervention."
  }
}