Systemorph/MeshWeaver / .claude/skills/new-repo
new-repo
VerifiedStand up a NEW repository in the MeshWeaver fleet — a satellite node repo (packages the mesh compiles live) or, rarely, a deployment repo. Use when creating a new Systemorph repo, when adopting the shared CI into an existing one, or when auditing whether a repo is wired correctly (AGENTS.md, scripts/ gates, reusable-workflow CI, publish-bake + the release poll, branch protection, OIDC, .gitignore). Grounded in the six repos that already exist — MeshWeaver.Plugins, .Education, .Reinsurance, .SocialMedia, .Manufacturing, Memex — and in CiContentBake.md + ContinuousDeliveryContract.md.
/new-repo — Stand up a repository in the fleet
🚨 READ FIRST — what a stand-up measured on 2026-09-20 (MeshWeaver.FundReporting)
This section OVERRIDES the sections below wherever they disagree. They were written from the fleet as it stood in late August; every item here was measured while standing up a private content repo on 2026-09-20, and each names the section it corrects. Where a sentence below contradicts one of these, this one is the current fleet and that one is history.
- The lanes are called
@mainnow, not by SHA. Every adopted caller (Crm, SocialMedia, Reinsurance) readsuses: Systemorph/MeshWeaver/.github/workflows/node-repo-*.yml@mainwithplatform-ref: main/scripts-ref: main, and the platform IMAGE is resolved at run time bypreflight(resolve-platform.py, the newest SEALED set) —Nothing pins the platformREFUSES a pin coming back. §5's "pin everyuses:to a 40-char SHA" describes the pre-2026-09-12 shape. CopyMeshWeaver.Crm@main'sci.yml(the newest content-only caller; SocialMedia's carries asrc/module lane you do not want). - Core's fleet roster must name the repo, or
validateis red on the first PR.node-repo-validateasserts a row for the calling repo in core's.github/lane-caller-grants.yml(This repo's callers still match the platform's fleet roster→ "is not in Systemorph/MeshWeaver's .github/lane-caller-grants.yml"). Add the row — Crm's ten callers, same grants — in a core PR BEFORE the first push (core #4975 is the shape). 🔒 Core is PUBLIC and the roster names the repo, so a client's repo gets a neutral name (what it does, never whose it is); the client is named only inside the repo. - Four org inputs are
selected-visibility and do NOT reach a new repo:CONTROL_WEBHOOK_SECRET,CONTROL_WEBHOOK_URL,MW_RUNNER_GATE,MW_RUNNER_HEAVY. Add the repo id:gh api -X PUT orgs/Systemorph/actions/secrets/CONTROL_WEBHOOK_SECRET/repositories/<repo_id>(and…/actions/variables/<NAME>/repositories/<repo_id>for the three variables). Preflight names them, so this is a red, not a hole — but it is a step §10 did not list. The runner group isvisibility: all; 🚨 the two org Apps are different things and must not be conflated —meshweaver-cloud(app_id 4220566) is the write App the lanes mint from,meshweaver-readeris the read-only App §10a callsfleet-reader, whose INSTALLATION is what core's pinned-digest sweep and lock discover the fleet from. Measured 2026-09-20,gh api /orgs/Systemorph/installations --jq '.installations[]|"\(.app_slug) \(.repository_selection)"'returned both withrepository_selection: all, which is the only reason that day's new repo needed no install step. §10a's requirement stands: run that one-liner, and if either has flipped toselected, add the repo to it — a repo the read-only App does not reach is not red, it is simply absent from the sweep. - The ACR scope map also needs
memex-portal-ai content/read(the gate pulls the PORTAL image as the reference set since core #3022):--repository mw-plugin-test content/read metadata/read --repository memex-portal-ai content/read— §10a lists only the tester. meshweaver-cloudnow holdsworkflows: write(andissues: write) — §13's "noworkflowspermission" is history; verify with the App JWT →GET /appas §10a says.- The OIDC identity
github-actions-bakeis at 14 of Azure's 20 federated-credential slots after this repo (two per repo). Three more repos fill it; plan the identity split before then. validate-repos.pywalks EVERY top-level folder, so a non-package folder (client reference material, a transcription) must be in every script'sSKIPset AND inscripts/gen-manifests.config.json— being package-less (noindex.json) keeps it out of the manifest, the bake and the registry, but not out of the JSON-shape walk.- The mesh gate reads the
Testsarea's rendered table, so a CASE NAME containing ❌ counts as a failure (41/41 passedandtests=FAILED). Never put a verdict glyph in a case name. - Running the in-node tests locally on a Mac:
run-node-tests.pybuilds a console runner against the image's (Linux, arm64) framework and dies at run with exit 134. Build it with--keep, then execute the keptbin/Debug/net11.0INSIDE the tester image:docker cpit into a container of the image, strip theMicrosoft.AspNetCore.Appentry fromNodeTests.runtimeconfig.json, copy the extracted refs'Microsoft.AspNetCore.App/<the image runtime version>/*.dll(read it off the refs folder, never a remembered number) beside it, deleteNodeTests.deps.json,docker start -a. The compile gate needs the three registry-served module assemblies (MeshWeaver.AI,MeshWeaver.Markdown.Collaboration,MeshWeaver.Maps) beside the image's/app— it REFUSES an/app-only set by design. - A client-private repo is MOUNTED on the instances that should see it, never registered on the
public registry: registration seeds
<Source>/*for EVERY configured source to any instance on a plan (MeshWeaverInstanceService.PlanGrantEntries), and there is no per-source private flag. The mount ispluginRepos[] {isRegistrySource: true}on the instance's Deployment record (App- authenticated, no per-source token;SecretNameis never rendered), mirrored into the overlay (Record renders the overlayreds otherwise), and the Store lists it becauseStoreManifestSource.Resolvefolds the deployment's configured GIT sources (Plugins #2192/#2194) — the live Store node is system-synced and is never edited for this.
Copy a repo that already works; do not invent a shape. Six exist today and they agree on far more than they differ. What follows is the agreement, with each divergence flagged as a decision you have to make rather than a default you can drift into.
Canonical references — read the relevant one before wiring the lane:
- CiContentBake.md → "Node repos run the same lane — as reusable workflows" (the CI contract, the pin rule, the required-check rename).
- ContinuousDeliveryContract.md → the publication set, the release POLL, and "Register BOTH OIDC subject formats".
- AGENTS.md — the fleet's working rules. A satellite does not restate them; it points at them.
/pullrequest·/plugins— the PR gate, and registering the new repo as a catalog source.
0. Which kind of repo is this?
| Node repo (the normal case) | Deployment repo | |
|---|---|---|
| Holds | mesh packages: node-per-file JSON + Source/*.cs the mesh compiles at RUNTIME | portal config, per-environment values, migrations |
| Builds | nothing — no .csproj unless it ships a compiled module | .slnx + images |
| Examples | MeshWeaver.{Plugins, Education, Reinsurance, SocialMedia, Manufacturing} | Systemorph/Memex (private) |
| This skill covers | all of it | §11 only |
🚨 A deployment repo's directory names are tenant identities. Never copy an environment name, hostname, customer name or subscription id out of Memex into a public repo, a doc, or a skill.
Everything below is the node-repo lane.
1. Create the repo, and the eight files that make it one
Systemorph/MeshWeaver.<Name>, default branch main, private unless the content is public
(Reinsurance, SocialMedia and Manufacturing are; Plugins and Education are too — check before
assuming). Then the skeleton, all copied:
| File | Copy from | Adapt |
|---|---|---|
AGENTS.md | MeshWeaver.SocialMedia/AGENTS.md | §2 |
CLAUDE.md | any repo — the 11-byte single line @AGENTS.md, uniform across all six | no |
README.md | MeshWeaver.SocialMedia/README.md (30 lines: what it is, a module table, a ## Developing block of three commands, a pointer at AGENTS.md) | yes |
.gitignore | MeshWeaver.Manufacturing/.gitignore — 32 lines, the cleanest in the fleet. §9 | small |
.github/workflows/ci.yml | MeshWeaver.SocialMedia/.github/workflows/ci.yml | §5 |
.github/dependabot.yml | any node repo — they share a verbatim header and the github-actions block | drop the /e2e npm block if no e2e |
scripts/ | §4 | the SKIP set |
.claude/skills/{debug,pullrequest,node-files,gates,module-versions}/SKILL.md | MeshWeaver.SocialMedia/.claude/skills/ | §2 — all five; the table used to name two and §2 five |
LICENSE where the content is licensed (Reinsurance, SocialMedia, Manufacturing carry one;
Plugins and Education do not). No node repo has a root docs/ — its documentation lives on the
mesh; only the deployment repo has one.
2. AGENTS.md — take SocialMedia's, and know what you are taking
🚨 The shared rule blocks are the baseline every repo carries — copy them from core's AGENTS.md
for the new repo's class, verify against a temporary copy of the register that adds the repo to repos and to each block's
required-in — check-shared-rules.py --manifest <temporary copy> --local <repo>=<path-to-AGENTS.md> (a
--local naming an unregistered repo is refused — the gate reads only registered repos), then
register the repo once that PR merges: SharedRuleBlocks → "The baseline every repo carries".
Donor: MeshWeaver.SocialMedia/AGENTS.md. A fleet-wide compaction is in flight — one
docs/agents-md-factor-out PR per repo (Education #224, Reinsurance #104, SocialMedia #95,
Manufacturing #26, Memex #142; Plugins uncommitted) moving each file's evidence into on-demand
skills. Take the post-factor-out form, not what main shows today, and check whether the PR has
landed before copying.
| repo | AGENTS.md on main | after the factor-out | skills after |
|---|---|---|---|
| Plugins | 135 KB / 1957 L | ~46 KB | 14 |
| Education | 34.6 KB / 512 L | 16.7 KB | 9 |
| Reinsurance | 31.5 KB / 445 L | 19.1 KB | 7 |
| Memex | 27.3 KB / 420 L | 15.1 KB | 4 |
| SocialMedia | 20.7 KB / 309 L | 13.6 KB | 5 |
| Manufacturing | 18.7 KB / 272 L | 12.8 KB | 3 |
SocialMedia wins on the pair, not on size alone: it lands thinnest-but-one with the complete
skill set — debug, pullrequest, node-files, gates, module-versions — and it is the repo
whose CI is the fully-adopted thin caller you are about to copy in §5, so the two halves match.
Manufacturing is 0.8 KB smaller and has zero unique headings (the purest skeleton), but it has
no .claude/ at all and its PR lands without debug or pullrequest — a gap in the wave, not a
design choice. Take Manufacturing's .gitignore and heading skeleton; take SocialMedia's file.
Its opening move is the thing to copy first: it does not restate the authoring rules, it
points at Plugins' AGENTS.md as authoritative and says "Everything there applies here
unchanged; this file carries only what is specific to this repo." That is the compaction. A new
repo that restates the plugin mechanism has already forked it. Three blockquote callouts sit under
that H1 in Reinsurance, SocialMedia and Manufacturing near-verbatim — copy all three: the
upstream-authority pointer, the skills-delta note, and the system-synced-space access
rule (on a GitSynced space the only Admin is system-security; never hand-create a module's
Space, never grant yourself rights to preview something).
Fleet-universal — keep these, verbatim in shape:
| Section | Where |
|---|---|
## The instances (which mesh am I talking to?) | 6/6, heading identical — which portal each MCP server actually talks to, before any mutation |
## Work in worktrees | 6/6, heading identical. git worktree add .worktrees/<name> -b feat/<name> main; .worktrees/ gitignored |
| The docs pointer | 6/6 in substance, three headings: ## 📚 Docs live on the mesh (Reinsurance, SocialMedia, Manufacturing) · ## 📚 Where the documentation lives — search the memex MCP (Education, Memex) · ## 📚 Read the MeshWeaver docs through the memex MCP (Plugins) |
| How work ships | 6/6, two headings: ## Git workflow (Education, Reinsurance, SocialMedia, Memex) · ## Ship it: merge by DEFAULT … (Plugins, Manufacturing) |
Node-repo-universal (the four content repos, exact text shared) — copy these too:
- Node FILE formats —
.mdfor agents/skills,.csfor C# source,.jsonfor the rest. - Gates (all of them are hard PR gates) — the §4 list, as a numbered contract.
- 🚨 A folder is addressable only when a node FILE backs it —
X/with noX.jsonbeside it is unreachable.
Repo-specific — rewrite these, do not copy the content: ## The modules (your table),
the body of ## Gates (yours will match §4), ## Repo-specific scripts, and anything naming a
partition, a product or a price.
Two rules are fleet-universal but do NOT live in a satellite's AGENTS.md — and that is
deliberate. "No band-aids" appears in exactly one of the seven files (core's) and
-warnaserror in two (core, Memex — the only repos with a .NET build). A node repo inherits them
by pointing at core, not by restating them. Do not paste them in; do add the pointer.
🚨 Do not copy SocialMedia's ## Git workflow paragraph. It says "Never commit or push
automatically — wait for the maintainer to ask", which contradicts core's AGENTS.md and the
other three node repos. Take Reinsurance's ## Git workflow ("When the work is finished,
finish it — commit and run /pullrequest without being asked", plus never-push-to-main and
never-merge-red) or Manufacturing's ## Ship it: merge by DEFAULT (the same policy with an
explicit fatal / system-changing / destructive stop table). Both match the platform.
Skills — copy five. Every repo with a .claude/ carries debug and pullrequest today
(Plugins, Reinsurance, SocialMedia; Education adds course-e2e, create-space, markdown-nodes);
the factor-out wave converges the node repos on three more: node-files, gates,
module-versions. debug is effectively byte-shared — its description is identical across four
repos and only allowed-tools varies. pullrequest is the one you must edit: each names its own
repo, its own pre-flight gates and its own deploy target. No repo in the fleet has .claude/agents/.
SocialMedia's own note says why the files are thin: each loads the master node from the mesh
(get Skill/<name> over the mesh MCP) and carries only this repo's delta. The test for a delta:
would this sentence be true in another repo? If yes, it belongs in the master, not here.
🚨 .claude/settings.local.json is per-user state and must not be tracked. Reinsurance tracks
one today (git ls-files returns it) — because no node repo's .gitignore mentions .claude at
all. §9 is the fix.
3. Repo layout — one directory per package, node-per-file
A package is a top-level directory whose root is <Package>/index.json. Verified shape, from
MeshWeaver.Manufacturing/Manufacturing/:
Manufacturing/
index.json ← the package ROOT: nodeType "Store/Plugin", content $type "PluginContent"
manifest.lock ← generated; never hand-edited
Source/ ← PARTITION-level shared C#, pulled in via `shared=@Manufacturing/Source`
Station.json ← a NodeType node (leaf = X.json; node-with-children = X.json BESIDE X/)
Station/
Source/StationLayoutAreas.cs ← compiled by the MESH at runtime, never by CI's dotnet build
Test/StationTests.cs ← singular `Test/`, not `Tests/`
Test/StationTestsArea.cs ← backs WithView("Tests", …) — the area the gate EXECUTES
AnnealingAN1.json … ← instances of the type
Agent/…, Skill/… ← authored as `.md` with front matter, never escaped JSON
content/og-card.png, content/videos/… ← raw assets, never nodes
(MeshWeaver.Plugins/RemoteControl/ is the compact reference for all of it — 19 files, an Agent/
and a Skill/ both .md, two NodeTypes with Source/ + Test/, one UiContribution, and a
manifest.lock short enough to read whole.)
The root (Manufacturing/index.json) — real key set: $type: MeshNode, id, namespace: "",
path, mainNode, name, description, nodeType: "Store/Plugin", category, icon (inline
SVG), state: "Active", and content of $type: "PluginContent" carrying
requires: ["Publish@^1.0.8", "Store@^1.0.0"] (a caret pin accepts compatible updates and refuses
a new major; the bare form ["Store"] stays valid and unconstrained), version (the series,
e.g. "1.2"), description, body (the Store card's marketing page, ending @@("area/Search")),
price + currency + contactEmail, publicSegments, minMeshVersion, installPaths,
marketingPath, tier, preInstalled, and entryPoint. SocialMedia's adds
module: "MeshWeaver.Social" for a mixed package (content + a compiled module).
entryPoint is optional (LinkedIn omits it) and takes three shapes: a plain node path
(RemoteControl/Start), a node path whose default view is the app (Manufacturing/Overview), or an
explicit layout-area route {node}/area/{Area} (Providers/ProvidersApp/area/ProviderSetup).
No leading slash.
A NodeType node (Manufacturing/Station.json) — nodeType: "NodeType" and a content of
$type: "NodeTypeDefinition" with description, includeGlobalTypes, sources
(["namespace:Source scope:subtree", "shared=@Manufacturing/Source"]) and — 🚨 — a
configuration lambda that is C# inside a JSON string:
"configuration": "config => config.WithContentType<Station>().AddDefaultLayoutAreas()
.AddLayout(layout => layout.AddStationLayoutAreas().WithView(\"Tests\", StationTestsArea.Tests))"
That string is invisible to grep --include='*.cs' and to every dotnet build. It is why AGENTS.md's
in-mesh-source rule exists and why §4's compile gate is not optional.
manifest.lock — generated, six keys: schema: "mw-manifest/1", module, files (every
file in the folder — .json, .cs under Source/+Test/, .md, and content/ assets — as
repo-path → sha256; 161 entries for Manufacturing), moduleVersion (a content hash — exact but
unordered, so nothing can pin against it), version (SemVer, the number dependents pin),
sourceCommit. You own MAJOR.MINOR via the root's content.version; gen-manifests.py derives
PATCH. Never hand-edit it, and 🚨 never commit a node's version field — that is the owning
hub's persistence counter, and a checked-in one makes MonotonicWriteGuard refuse the install
(found in every node repo in 2026-08, counters as high as 4489).
A menu entry is DATA. nodeType: "UiContribution" — e.g.
MeshWeaver.Plugins/Approvals/RequestApprovalMenu.json: content.$type: "UiContribution" with
context ("Node", "Admin" in the live files; the type declares Node/Mesh/Settings/
AiMenu/SidePanel/TopBar — src/MeshWeaver.Graph/Configuration/UiContributionNodeType.cs),
label + labelKey (i18n — supply it), icon (emoji), area, href ({node} is the only
placeholder the seam substitutes), order, requiredPermission. Installing the package adds the
entry; removing it removes it — no platform build. Visibility is enforced by the compiled
aggregator against a closed gate vocabulary; a contribution can only ever NARROW itself. Only four
exist in the whole fleet, all in Plugins — so copy one rather than deriving it.
4. scripts/ — the validators the CI invokes by path
🚨 The reusable workflows run python3 scripts/<x>.py from the CALLER's checkout, by
repo-relative path (node-repo-validate.yml:50,55,67, node-repo-compile-check.yml:155,
node-repo-tag-modules.yml:59, node-repo-gate.yml:200). There is no shared copy in core — a
find over the platform repo for all fourteen filenames returns zero hits, and
node-repo-tag-modules.yml says why: "scripts/tag-modules.py lives in each node repo, so parsing
its text would couple this shared template to a file it does not own." Every caller carries its own.
| Script | Carried by | What it asserts | Key flags |
|---|---|---|---|
validate-repos.py | all 5 | node JSON shape + NodeType Source/ presence, and fails on any module file hidden by .gitignore. Shape only — it does not compile | none (Plugins adds --self-test) |
gen-manifests.py | all 5 | regenerates manifest.lock; --check = current, --check-versions = the derived SemVer matches the content | --check, --check-versions, --no-fetch |
compile-check.py | Plugins, Reins, Social, Manuf | compiles every NodeType's resolved source set — concatenated, usings hoisted, and the configuration lambda — against the framework assemblies exactly as the mesh does on import | --refs <dir>, --image, --gen-allow |
tag-modules.py | all 5 | cuts <Module>/vX.Y.Z on main; verifies rather than moves a tag that already exists | --dry-run |
affected-modules.py | Plugins, Reins, Social, Manuf | the diff → changed modules → transitive dependents → their dependencies, 1:1 with LocalNodeRepo.CollectDependencies | --range/--changed/--all/--self-test, --json, --root |
store-presentation.py | Plugins, Edu, Reins, Social | derives the Store checklist: name/description/icon/category/Store/Plugin/content.body/@@("area/Search")/og image, split REQUIRED vs POLISH | --check, --self-test |
check-covers.py | Plugins, Edu, Reins, Social | no cover is a wall of text — longest prose paragraph (structure excluded) | --max N (400), --report, --self-test |
dep-graph.py | Plugins, Reins, Social, Manuf | the package graph from content.requires, leaves first | --mermaid (Reins: --check-staged) |
run-node-tests.py, gen-scope-proxies.py | Plugins, Reins | run a module's in-node tests without a mesh; materialise scope proxies (never hand-written) | --refs, --list / --check |
Exactly three are byte-identical across every repo that has them — copy those verbatim:
check-covers.py, store-presentation.py, compile-check.allow. Everything else diverges, and
the divergence is almost always one line: the SKIP set of top-level directories that are not
packages (Reinsurance adds "legacy", Plugins adds "app", Education skips dot-directories).
Take the newest copy from MeshWeaver.Plugins — it is the hardened superset for every script
except dep-graph.py --check-staged (Reinsurance-only) — and edit SKIP. Two known-stale copies to
avoid inheriting: SocialMedia's and Manufacturing's dep-graph.py read content.requires raw, so a
pinned edge "Store@^1.0.0" is invisible to them; Manufacturing's gen-manifests.py (14 KB vs
~35 KB) derives the patch from tags only, with no --no-fetch and no two-witness baseline.
Repo-specific — know they exist rather than copying blind: check-test-suites.py (Plugins,
Manufacturing — ratchets tests=skipped, which the gate prints inside a line beginning ok),
check-ci-invariants.py + fetch-registry-package.py (Manufacturing),
check-discriminators.py / check-scripts.py / check-agent-parity.py / check-impersonation.py
(Plugins), check-course.py / check_batteries.py / check-examples.py (Education).
Allow files are one-way ratchets — a NEW failure fails the PR; an entry that now passes is STALE and also fails ("remove it — it compiles now"). Who consumes what:
| file | where | consumed by |
|---|---|---|
compile-check.allow | scripts/ | scripts/compile-check.py |
plugin-gate.allow | repo root | not a script — passed to mw-plugin-test as --allow, and it is node-repo-gate.yml's allow-file default |
plugin-tests.allow | repo root | scripts/check-test-suites.py (growth blocked separately via --base-ref origin/main) |
cover-prose.allow | repo root | scripts/check-covers.py |
layout-area-data-bake.allow | repo root | core's .github/scripts/check-layout-area-data-bake.py, fetched by node-repo-validate.yml. It is REQUIRED: a missing file is red. An empty file is correct for a repository where nothing bakes. On a PR, the tree is compared with the base (--base): the number of baking units may not grow, and a PR that converts an area must lower or delete its line. Doc/GUI/DataBinding has the details. |
🚨 Seed every one of them EMPTY. They exist to grandfather debt you inherited; a new repo has
none, and an entry added in the same diff as the hole it excuses is a trapdoor exactly one commit
wide. Where a repo gates additions, the event test lives inside the step, never as an if:.
Every script that can ships --self-test, and CI runs the self-test immediately before the
check — because against a clean tree a gate prints the same green tick whether it measures
correctly, measures the wrong thing, or measures nothing at all.
5. CI — a THIN CALLER of core's reusable workflows. Never a copy.
🚨 This is the load-bearing rule of the whole skill. The shared jobs live in the platform repo
as workflow_call workflows. A satellite that hand-rolls or copy-pastes them forks the contract
and stops receiving its fixes.
Systemorph/MeshWeaver/.github/workflows/
node-repo-validate.yml job: validate name: Validate node repos
node-repo-compile-check.yml job: compile-check name: Compile every NodeType (vs core)
node-repo-gate.yml job: test-repos name: Compile + render node repos (MeshWeaver from ACR)
node-repo-tag-modules.yml job: tag-modules name: Tag module versions
node-repo-publish-bake.yml job: publish-bake name: Bake + publish NodeType assemblies to portal storage
node-repo-module-pack.yml (mixed packages only — builds + packs a compiled module)
Adoption status today, so you copy the right file: SocialMedia and Reinsurance call the full
five — they are the models. Plugins calls only module-pack + publish-bake (its gates carry
repo-specific machinery). Education and Manufacturing call none and hand-roll. Copy
MeshWeaver.SocialMedia/.github/workflows/ci.yml.
A real caller, verbatim from it:
validate:
uses: Systemorph/MeshWeaver/.github/workflows/node-repo-validate.yml@a727426b09107e2aa6da2fc4f68aae7240fdd6e9
compile-check:
needs: [preflight, validate]
uses: Systemorph/MeshWeaver/.github/workflows/node-repo-compile-check.yml@a727426b09107e2aa6da2fc4f68aae7240fdd6e9
with:
test-image: ${{ vars.MW_TEST_IMAGE }}
image-digest: ${{ needs.preflight.outputs.image-digest }}
secrets:
acr-username: ${{ secrets.ACR_USERNAME }}
acr-password: ${{ secrets.ACR_PASSWORD }}
The rules the caller must honour:
- 🚨 SUPERSEDED — see "READ FIRST" at the top: the fleet calls the lanes
@mainwith run-time platform resolution, and a pin coming back is REFUSED byNothing pins the platform. The paragraph below is the pre-2026-09-12 shape, kept for repos that have not moved. Pin everyuses:to a 40-char commit SHA, never@mainand never a tag. On@mainone edit to a shared workflow changes every satellite's gates at once and "did my change break this, or did the workflow move under me?" stops being answerable. A tag is worse: moving it changes all satellites with no commit anywhere to attribute it to. GitHub forbids an expression inuses:, so the SHA is literal on each line — bump them all in one commit. SocialMedia's preflight reads its ownuses:lines back and prints the pin's age, shouting past 30 days; copy that step. - Pin the platform IMAGE by digest too (
tag@digest), and bump it often. The pin buys reproducibility, but it also caps what the gates can SEE — a pin lagging the platform by days is a gate reporting on a framework nobody runs. That is exactly how the 2026-08-09AddTrackingoutage shipped green. An unpinned image is an explicitallow-unpinned: true, never a silent fallback. - Triggers:
push: [main],pull_request,merge_group,workflow_dispatch,repository_dispatch: types: [meshweaver-framework-released], andschedule(§6). 🚨merge_groupis not optional on a repo with a merge queue — its absence does not look like a missing trigger, it looks like a PR that queues and then sits there until it is ejected with no failing check to point at. cancel-in-progressmust be OFF for main pushes:${{ !(github.event_name == 'push' && github.ref == 'refs/heads/main') }}. Written as push-AND-main, notgithub.ref != 'refs/heads/main'— a scheduled or dispatched run also carries the default-branch ref and those must keep superseding each other. Superseding stays on for PR branches, which is where the runner saving is. Measured on Plugins with the ref-only form: 18 of one day's main runs endedcancelled, each killed by the next merge, so the publish jobs never ran and the registry served bytes older than main.- Keep repo policy in the caller: the digest pin, the gating (
if:/needs:), the dispatch receiver, the module-bundle job, andscripts/.
6. CD — publish, bake, and the poll that actually delivers
The ladder (policy
platform-backwards-compatibility). A node repo's publication is sealed under the platform COMPATIBILITY keyc<major>e<epoch>, which every platform build of one epoch shares — so a new platform build does NOT require this repo to rebuild or re-seal, and installs keep running its bytes across platform rolls. Its publication rolls independently once its floor (the producing platform build) is ≤ the platform an install runs. Only a DECLARED break (an epoch bump) requires a coordinated rebuild and seal, and then platform rolls are held by name until it lands. Never pin a platform image or a Deployment record to work around one. Full procedure: Deploying Across Platform Versions.
Publication is node-repo-publish-bake.yml, gated main-only or on a release trigger:
publish-bake:
if: >
(github.event_name == 'push' && github.ref == 'refs/heads/main') ||
github.event_name == 'repository_dispatch' ||
github.event_name == 'schedule'
needs: [preflight, validate, compile-check, test-repos]
permissions: {contents: read, id-token: write} # azure/login OIDC — no long-lived storage secret
uses: Systemorph/MeshWeaver/.github/workflows/node-repo-publish-bake.yml@<sha>
with:
bake-source: <lowercase repo short name> # plugins | reinsurance | socialmedia
test-image: ${{ vars.MW_TEST_IMAGE }}
image-digest: ${{ needs.preflight.outputs.bake-image-digest }}
bake-publish-targets: ${{ vars.BAKE_PUBLISH_TARGETS }}
stage-repo: Systemorph/MeshWeaver.Plugins # only if a package `requires` a module from there
stage-modules: Store # only what you USE; the lane stages their `requires` closure
The digest that the BAKE uses is not the digest the GATES use, and conflating them is the bug.
Two questions: the gates ask "do two runs of identical code agree?" → the pin. The bake asks
"does the RELEASED framework identity have published bundles?" → the currently-released image.
SocialMedia's preflight resolves this in a bake-target step: on repository_dispatch/schedule
it resolves docker manifest inspect -v → .Descriptor.digest and fails loud if it gets no
digest, because silently falling back to the pin would republish an identity that is already
published and leave every instance held, under a green tick.
🚨 repository_dispatch is memex's EVENT; the schedule is the fallback. The registry's
PlatformBuildInboxWatcher dispatches meshweaver-framework-released to every repository the
Hosting/Deployment records name as a registry source — so a new repo is subscribed by being named
on a Deployment record (Systemorph/Memex mesh/Deployments/*.json, pluginRepos[] with
isRegistrySource), never by an edit in core. Core CD dispatches to no repository (its
notify-dependents was withdrawn 2026-09-03; the 2026-08-22 predecessor printed a not-configured
notice for its whole life while the fleet stayed a release behind, every check green). A node repo
without schedule never bakes for a released identity when a dispatch is lost. It bakes its pin,
on its own pushes, forever, and the only symptom is an instance HELD on that repo's bundles.
Stagger the minute; observed today: SocialMedia 7,37, Plugins 17,47, Reinsurance 22,52,
Education 32.
FOLLOW_RELEASE vs the pin, in one line: github.event_name == 'repository_dispatch' || github.event_name == 'schedule' — true ⇒ bake the released image; false ⇒ bake the pin, which
certifies the bits the gates just ran.
Module bundles (mixed packages only) go through node-repo-module-pack.yml with modules (a
JSON array of {package, module, project}), platform-ref, registry-source, and a publish
expression that is trunk-only, not push-only — a release-follow schedule or dispatch MUST
publish or the rebuild it just did is discarded. 🚨 platform-ref is a literal, not
${{ env.MW_PLATFORM_REF }}: the env context is unavailable in a reusable workflow's with:. Keep
the uses: ref and platform-ref the same commit — the lane runs a script from the platform
checkout it makes at platform-ref.
7. The preflight job — a gate NEVER tests its own inputs
One job asserts every value that comes from outside the tree, fails RED naming exactly what to
provision, and every gate needs: it and runs UNCONDITIONALLY.
preflight:
name: Required CI inputs
runs-on: ubuntu-latest
outputs:
# 🚨 TWO outputs, and they are not interchangeable. The GATES read the PIN — an immutable
# digest every job shares, so one run cannot straddle two images. The BAKE reads whatever
# the release tag resolves to RIGHT NOW, because its job is to republish against the
# identity the platform actually released. Defining only `image-digest` leaves the
# publish-bake job in §6 consuming an output that does not exist: it resolves to the empty
# string, and the bake targets nothing while the run still goes green.
image-digest: ${{ steps.pin.outputs.image-digest }}
bake-image-digest: ${{ steps.bake-target.outputs.image-digest }}
if: github.event.pull_request.head.repo.fork != true # the ONLY exemption, on the EVENT
steps:
- name: Assert every externally-provisioned CI input is present
env: {MW_TEST_IMAGE: "${{ vars.MW_TEST_IMAGE }}", ACR_USERNAME: "${{ secrets.ACR_USERNAME }}", …}
run: |
set -euo pipefail
missing=()
[ -n "${MW_TEST_IMAGE:-}" ] || missing+=("vars.MW_TEST_IMAGE — the mw-plugin-test image reference")
…
if [ ${#missing[@]} -gt 0 ]; then
echo "::error::Required CI inputs are not provisioned, so the gates cannot run. A gate that cannot run fails RED."
for m in "${missing[@]}"; do echo "::error::missing: ${m}"; done
exit 1
fi
Why, in three lines: a missing input is a RED job naming what to set, never a skip; gates run
unconditionally behind needs:; anything genuinely exempt is a check on the event
(fork, ref, event_name) — never if: ${{ vars.X != '' }}. At job level those two look
identical and only one is safe, because GitHub renders a skipped job with the same tick as a
passed one, so "the gate never ran" and "the gate passed" become indistinguishable and the
failure is self-concealing. Not theoretical: Plugins' cross-repo gate was built that shape and
therefore never ran once — #683 deleted a live API and put nine plugin partitions on the
compilation-error overlay in production.
Adding an input is one line in missing. A staging device ("stay green until X is wired")
that outlives its staging is a silent hole; delete it the day X is wired.
8. Branch protection + required checks
🚨 Adoption RENAMES the required contexts. A reusable-called workflow's runs report as
<caller job> / <inner job name>. Update branch protection in the same change — a context left
at the old name waits forever. Verified live today:
| repo | contexts | strict |
|---|---|---|
| SocialMedia, Reinsurance (adopted) | validate / Validate node repos, compile-check / Compile every NodeType (vs core), test-repos / Compile + render node repos (MeshWeaver from ACR) | false |
| Plugins, Manufacturing (hand-rolled) | Validate node repos, Compile every NodeType (vs core), Compile + render node repos (MeshWeaver from ACR) | Plugins true, Manufacturing false |
| MeshWeaver, Education, Memex | no branch protection (core uses a ruleset instead — main pr protection, id 2128472: pull_request, copilot_code_review, required_status_checks {strict: false, checks: ["Consolidate test results"]}, deletion, non_fast_forward) | — |
🔒 A later @ref bump renames nothing — neither the caller's job id nor the inner name: — so
the contexts survive bumps. Only renaming a job in the reusable workflow breaks them, which is why
that rename is a breaking change to every caller.
strict is PER-REPO. Measure it; never remember it:
gh api repos/Systemorph/<repo>/branches/main/protection --jq '.required_status_checks.strict' # 404 = unprotected
Choose strict: false. Plugins is the only true in the fleet and it is a merge treadmill:
every merge makes every other branch stale, so each PR needs a fresh CI cycle to catch up. With
false a branch that is merely behind main merges fine; what you still owe is no conflicts and
a green required check. If you want the combination-that-lands tested, that is a merge queue
(merge_group: trigger + queue settings), not strict.
9. .gitignore — two ways to lose files silently
Start from MeshWeaver.Manufacturing/.gitignore (32 lines) and keep its opening banner, which
is the fleet's institutional memory:
🚨 THIS IS A NODE REPO — do NOT add .NET build-output rules here. Every top-level module folder is a mesh partition of node files, and a node folder may legitimately be named
Release/,Debug/,Bin/orLog/.
Because git never descends into an ignored directory, a swallowed file is not even reported as
untracked. It has bitten twice: [Rr]elease/ hid 77 UWDeepfield node files during the import
into MeshWeaver.Reinsurance, and [Dd]ebug/ hid the /debug SKILL directory in Plugins — git add
said "nothing to commit". validate-repos.py now fails on any module file hidden by
.gitignore; keep that check. If a tree genuinely needs build-output rules, scope them by path
(legacy/**/[Dd]ebug/, src/**/bin/, test/**/obj/), never bare.
🚨 The second way: .claude/. Two opposite mistakes are live in the fleet right now.
- A blanket
.claude/means skills can never be committed — and a doc gate later pointed at the skills root would then walk an empty directory and report green having checked nothing. Memex is exactly that (.gitignore:393); its fix, PR #142, has to change the ignore and teachscripts/check-doc-links.pyto walk the skills, in one commit. - No rule at all — the state of all five node repos — leaves per-user state committable, and
Reinsurance has committed
.claude/settings.local.json.
The correct form, which today exists only in core's .gitignore (lines 433-440):
# Claude Code per-user local state (settings.local.json, plans/, scheduled_tasks.lock, …)
# — but DO track the shared team skills under .claude/skills/.
.claude/*
!.claude/skills/
Core adds !.claude/skills/debug/ and !.claude/skills/release/ only because it also carries
generic [Dd]ebug/ / [Rr]elease/ rules. A node repo following the banner above needs neither —
but if you ever add such a rule, add the matching negation in the same commit. (Memex's fix branch
adds the two-line form without the per-skill negations, and its lines 16/18 still swallow both.)
Also fleet-universal, present in all six: .worktrees/, node_modules/, __pycache__/, *.pyc.
And anchor a nested-repo ignore with a leading slash — an unanchored plugins/ matches at every
depth and, on macOS's case-insensitive filesystem, also matches Plugins/.
10. Secrets, variables and OIDC
Provision under Settings → Secrets and variables → Actions. Verified names across the fleet:
| Needed for | Plugins | Reins. | Social | Manuf. | Edu | |
|---|---|---|---|---|---|---|
vars.MW_TEST_IMAGE | the gates (image whose /app assemblies are the reference set) | ✓ | ✓ | ✓ | ✓ | — |
secrets.ACR_USERNAME / ACR_PASSWORD | docker login for that image | ✓ | ✓ | ✓ | ✓ | — |
vars.BAKE_PUBLISH_TARGETS | publish-bake — <account>/<share>[/<base-path>], whitespace-separated | ✓ | ✓ | ✓ | — | ✓ |
secrets.AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_SUBSCRIPTION_ID | azure/login OIDC for the publish | ✓ | ✓ | ✓ | — | ✓ |
secrets.MESHWEAVER_APP_ID / MESHWEAVER_APP_PRIVATE_KEY | GitHub App that staging a cross-repo module (stage-repo) reads with | ✓ | ✓ | ✓ | — | — |
vars.MW_REGISTRY_URL + secrets.MW_REGISTRY_KEY | the gate fetching the upstream publication over HTTPS (works on pull_request) | — | ✓ | ✓ | — | ✓ |
secrets.REGISTRY_PUBLISH_TOKEN | handing a packed module bundle to the registry | ✓ | — | ✓ | — | — |
Minimum for a content-only repo: MW_TEST_IMAGE + ACR_USERNAME + ACR_PASSWORD. Add the
BAKE_PUBLISH_TARGETS + AZURE_* set the moment you turn on publish-bake — a missing value there
fails the job by design; a grey skip would silently restore every-pod-rebakes-everything.
🚨 Register BOTH OIDC subject formats — GitHub subjects are immutable, and which form a repo
presents varies per repo inside one org at the same moment. Measured 2026-08-17: Education and
SocialMedia presented the immutable form while Plugins presented the classic one, so tidying all
four to immutable broke Plugins with AADSTS700213: No matching federated identity record found.
REPO=MeshWeaver.<Name>; SHORT=<short>
REPO_ID=$(gh api repos/Systemorph/$REPO --jq .id); ORG_ID=$(gh api orgs/Systemorph --jq .id)
ISSUER=https://token.actions.githubusercontent.com
az identity federated-credential create -g <aks-resource-group> --identity-name github-actions-bake \
--name "gh-$SHORT-main-classic" --issuer "$ISSUER" \
--subject "repo:Systemorph/$REPO:ref:refs/heads/main" --audience api://AzureADTokenExchange
az identity federated-credential create -g <aks-resource-group> --identity-name github-actions-bake \
--name "gh-meshweaver-$SHORT-main" --issuer "$ISSUER" \
--subject "repo:Systemorph@$ORG_ID/$REPO@$REPO_ID:ref:refs/heads/main" --audience api://AzureADTokenExchange
Expect two rows per repo. When AADSTS700213 appears, copy the presented subject verbatim out
of the error and add a credential for it, keeping the existing one — deleting the other format
is what turns another repo's green lane red. Full text:
ContinuousDeliveryContract.md
→ "Register BOTH OIDC subject formats".
Dependabot: secrets provisioned for Actions are not visible to Dependabot-triggered runs —
provision the pair under Secrets → Dependabot too, or a dependabot PR fails preflight.
10a. Provisioning, end to end — measured 2026-08-28 standing up MeshWeaver.Crm
Everything in §10 is a NAME; this is where each VALUE comes from, in the order that worked, with the three traps that cost a retry. Nothing here needs a second person — Systemorph issues every credential itself (registry-credentials-we-issue).
| Input | Where the value comes from | Trap |
|---|---|---|
ACR_USERNAME / ACR_PASSWORD | a per-repo ACR token on a per-repo scope map — the fleet convention is <short>-ci-pull on <short>-ci-pull-scope-map (repositories/mw-plugin-test/content/read): az acr scope-map create --registry meshweaver -n <short>-ci-pull-scope-map --repository mw-plugin-test content/read metadata/read then az acr token create --registry meshweaver -n <short>-ci-pull --scope-map <short>-ci-pull-scope-map | 🚨 token create ECHOES the password in a docker-login hint on stderr. Treat it as burned: az acr token credential generate … --password1 --query 'passwords[0].value' -o tsv > file 2>/dev/null, then gh secret set … < file. Prove it with docker login … --password-stdin < file |
MESHWEAVER_APP_ID / _PRIVATE_KEY | the org GitHub App meshweaver-cloud, id 4220566 (`gh api /orgs/Systemorph/installations --jq '.installations[] | select(.app_slug=="meshweaver-cloud") |
AZURE_CLIENT_ID / _TENANT_ID | az identity show -g <resource-group> -n github-actions-bake --query '{clientId:clientId,tenantId:tenantId}' | — |
AZURE_SUBSCRIPTION_ID | az account show --query id | — |
| the two OIDC federated credentials | §10's two az identity federated-credential create calls; REPO_ID = gh api repos/Systemorph/<Repo> --jq .id, org id 77832550 | keep BOTH formats |
MW_REGISTRY_URL / BAKE_PUBLISH_TARGETS | the same literal every sibling carries — copy it: `gh api repos/Systemorph/MeshWeaver.Reinsurance/actions/variables --jq '.variables[] | "(.name)=(.value)"'` |
MW_REGISTRY_KEY | mint a 20-minute mwr_ on the registry (an executable Code node in your home, execute_script, calling RegistrationKeyService.Mint(userId, name, email, description, expiresAt) from MeshWeaver.PluginCatalog; the raw key lands in the activity log a second after Succeeded), then ONE pipeline: curl -X POST "$MW_REGISTRY_URL/api/instances/register" -d '{"bootstrapKey":…,"instanceId":"ci-<short>",…}' > file → `python3 -c "…print(instanceKey,end='')" | gh secret set MW_REGISTRY_KEY --repo …` |
Dependabot store too. gh secret set … --app dependabot for ACR_* and MESHWEAVER_APP_* — a
dependabot-triggered run reads the Dependabot store, and preflight fails red on the Actions-only
pair (the same shape MeshWeaver#2249 documents).
Install the read-only fleet-reader App on the new repo too. Core's cross-repo READS — the
shared-rules gate, cross-repo-pair, and the pinned-digest sweep and lock — mint from it, and the
sweep and lock DISCOVER their fleet from its installation: a repo it does not reach is not red, it
is simply absent, and its pinned images stop being locked against the nightly purge. Listing the
repo in core's .github/shared-rules.json without the install turns every core PR red instead.
GitHubAppCredentials.md.
The rest of the repo, from the CLI, in the order that worked:
gh repo create Systemorph/MeshWeaver.<Name> --private --description "…"
gh api -X PATCH repos/Systemorph/MeshWeaver.<Name> -f allow_auto_merge=true
gh api -X PUT repos/Systemorph/MeshWeaver.<Name>/vulnerability-alerts
gh api -X PUT repos/Systemorph/MeshWeaver.<Name>/automated-security-fixes
gh api -X PUT repos/Systemorph/MeshWeaver.<Name>/collaborators/<login> -f permission=push # per maintainer
# the Copilot ruleset is data — copy a sibling's verbatim:
rid=$(gh api repos/Systemorph/MeshWeaver.Reinsurance/rulesets --jq '.[0].id')
gh api repos/Systemorph/MeshWeaver.Reinsurance/rulesets/$rid \
--jq '{name,target,enforcement,conditions,rules,bypass_actors}' > ruleset.json
gh api -X POST repos/Systemorph/MeshWeaver.<Name>/rulesets --input ruleset.json
🚨 gen-manifests.py refuses an EMPTY remote. It reads the trunk's committed lock as the second
version witness (git ls-remote --symref origin HEAD), so on a repo with no main yet it fails
"could not resolve which branch 'origin' publishes" — and validate-repos.py fails on the missing
lock. Push a bootstrap commit (README only — no ci.yml, so nothing runs) FIRST, then generate the
manifest, then push the module. Two commits on a brand-new main is the cost; branch protection
goes on AFTER the first real run has produced the three contexts to require.
🚨 Store/Provision.subdirectory is the PARENT folder, not the package folder. SystemInstall. EffectiveSubdirectory appends the package id, so a request with "subdirectory": "Crm" for package
Crm syncs Crm/Crm and the import refuses an empty snapshot ("No files found under subdirectory
'Crm/Crm'"). For a repo whose package folder sits at the root, omit subdirectory (it derives
Crm). Measured on the control instance, 2026-08-28; a retry is patch subdirectory: null +
requestedAction: "Provision" — the phases reconcile the _GitSync they wrote.
11. Make the content reachable — register the repo as a catalog source
A repo nobody reads ships nothing. The registry holds the git credential and re-serves per (source, package); consumers speak only HTTP. Add the source in the deployment's Helm values — which live in the private deployments repo, never here:
pluginCatalog:
sources:
- {name: <Name>, repoPath: "https://github.com/Systemorph/MeshWeaver.<Name>", ref: main}
format defaults to node-repo: a folder appears once it carries a <Folder>/index.json root
with a PluginContent. Sources merge in configured order, first wins on an id collision, and a
failing repo contributes nothing (logged) rather than breaking the catalog. Grants, tokens and the
anonymous-registry trap: /plugins.
Deployment repo (§0), in one paragraph: it is not a node repo and none of §3–§6 applies. It
holds per-environment values and its own workflows (Memex: build, helm-release, smoke,
deploy-drift, config-key-coverage). Its dependabot watches nuget + docker + actions and
deliberately does not bump the portal image pin — the in-pod self-updater chooses the running
build, and a Dependabot PR would fight the reconciler. See /new-deployment.
12. Webhooks — one per LIVE portal, or the fleet never sees the repo
Measured 2026-09-07 (MeshWeaver#3582, #3583). MeshWeaver.Crm was created on 08-28 with
everything above and no webhooks. Nothing checked. Its partition on the control instance last
synced on 08-30; ten days later the repo was 54 commits ahead, the portal still held files the repo
had retired, every prebuilt Crm bundle was refused by the source-fingerprint gate (#2813), and
opening any Crm page compiled ten-day-old sources on first use — reported as "why is bake not
working". Every other node repo had two hooks; nobody had noticed the one that had none.
A portal learns about a repo through exactly one channel: a GitHub webhook on the REPO, pointed at
https://<portal>/webhooks/github, signed with THAT portal's GitHub__Webhook__Secret. The push
event only logs ("a build is coming"); the workflow_run completed/success on the default branch
is what triggers the CI-gated import (GitHubWebhookProcessor.ProcessWorkflowRun →
UpdateToLatestFromGitHub at the built commit) and what writes the BuildCompletion the
self-updater and the plugin-update watcher read. No hook ⇒ the partition freezes at its last sync
while the bundles move on ⇒ fingerprint refusals ⇒ compile-from-source (or, since #3583, a named
error on a partition the portal does not track).
One hook per live portal, the portal's own secret, created at the same time as the repo:
# vault object → portal: each portal's GitHub__Webhook__Secret is a Key Vault object named in
# that portal's SecretProviderClass — read the name there, never guess it.
# The value goes from the vault into the request body and nowhere else — never into a variable
# you echo, never onto a command line. scripts/… is deliberately absent: keep it in the scratchpad.
python3 - Systemorph/MeshWeaver.<Name> <portal-host> <webhook-secret-object> push,workflow_run <<'PY'
import json, subprocess, sys, time
repo, host, obj, events = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4].split(",")
secret = subprocess.run(["az","keyvault","secret","show","--vault-name","<vault>","--name",obj,
"--query","value","-o","tsv"], check=True, capture_output=True, text=True).stdout.strip()
body = {"name":"web","active":True,"events":events,"config":{"url":f"https://{host}/webhooks/github",
"content_type":"json","insecure_ssl":"0","secret":secret}}
hook = json.loads(subprocess.run(["gh","api","-X","POST",f"repos/{repo}/hooks","--input","-"],
input=json.dumps(body), check=True, capture_output=True, text=True).stdout)
subprocess.run(["gh","api","-X","POST",f"repos/{repo}/hooks/{hook['id']}/pings"], check=True, capture_output=True)
time.sleep(5)
d = json.loads(subprocess.run(["gh","api",f"repos/{repo}/hooks/{hook['id']}/deliveries?per_page=1"],
check=True, capture_output=True, text=True).stdout)[0]
print(f"hook {hook['id']} -> {host}: ping status={d['status']} code={d['status_code']}")
PY
# …and again for every other live portal with ITS webhook-secret object — for the public
# instance with events
# issues,issue_comment,push,workflow_run (the two issue events feed the issue mirror; add them only
# if the repo takes part in it — Plugins, Education, Reinsurance and SocialMedia do).
Prove it, do not assume it: the ping delivery must read status=OK code=200 from the portal.
A hook that exists and delivers non-2xx is the same as no hook — a wrong secret answers 401 and
the repo is exactly as invisible as Crm was. Then, after the first green main run, read the
partition's _GitSync.lastSyncCommitSha on each portal: it must equal that run's head_sha.
The denominator is "every live portal", and it moves. A new portal (a client deployment, a second staging) needs a hook on EVERY node repo it syncs, so a new-portal checklist carries this section's mirror image. Audit the fleet in one call and read the count, never the tick:
gh api "orgs/Systemorph/repos?per_page=100" --jq '.[] | select(.archived==false) | .name' \
| while read -r r; do printf '%-28s %s\n' "$r" "$(gh api "repos/Systemorph/$r/hooks" \
--jq '[.[] | "\(.config.url | sub("https://";"") | sub("/webhooks/github";""))"] | join(" ")')"; done
# every node repo (one a portal's GitHubSyncConfig names — `search partitions:all nodeType:GitHubSyncConfig
# repositoryUrl:*<Name>*` on each portal) must list BOTH hosts. 2026-09-07: Crm listed none.
And the portal side is not implied by the hook. The webhook only wakes a sync source that
already exists: each portal needs a <Partition>/_GitSync (a GitHubSyncConfig naming the repo,
branch and subdirectory) for every partition the repo owns — the Store/Provision request in §10a
writes it for a provisioned space; a partition installed any other way (memex's Feedback, four of
the bundle's five files, no _GitSync) has none, and since #3583 its module content ERRORS rather
than compiling from the leftover copy. The Partition Sync administration page adds one; then
trigger one sync and count the partition's source nodes against the repo.
13. There is no pin-bump lane — a node repo carries no platform pin
🚨 RETIRED. Node repos no longer pin the platform: they resolve the newest SEALED set at run time
(MeshWeaver#3842, adopted by MeshWeaver.Plugins in b5414edf7, which deleted the last caller). Core's
node-repo-platform-ref-bump.yml lane is therefore deleted; never add a platform-ref-bump.yml caller
to a new repo. The history — why the lane needed the App's workflows grant, and the empty-room
failure it taught — is kept on Keeping the Platform Source Pin Current.
The checklist
Files and settings:
- Repo created,
maindefault, visibility decided. -
AGENTS.mdfrom SocialMedia, points at Plugins' AGENTS.md as authoritative,## The modulesand## Gatesrewritten, git-workflow section taken from Reinsurance or Manufacturing. -
CLAUDE.md=@AGENTS.md.README.md≤ ~40 lines. -
.gitignorefrom Manufacturing, banner kept, no unscoped build-output rules, plus.claude/*+!.claude/skills/(neither a blanket.claude/nor no rule at all). Prove it:git check-ignore -v .claude/skills/debug/SKILL.mdmust print nothing. -
.claude/skills/—debug+pullrequest(edit the latter: repo name, gates, deploy target) +node-files,gates,module-versions;settings.local.jsonNOT tracked. -
scripts/copied from Plugins withSKIPadjusted (check-covers.py,store-presentation.py,compile-check.allowverbatim); every--self-testpasses; allow files created empty. -
.github/dependabot.ymlcopied. - At least one package:
index.json(Store/Plugin+PluginContent+entryPoint) and amanifest.lockgenerated bypython3 scripts/gen-manifests.py. -
ci.ymlcopied from MeshWeaver.Crm (see "READ FIRST"; SocialMedia carries asrc/module lane you do not want); lanes called@main, the platform resolved at run time — not pinned; triggers includemerge_groupandschedule;cancel-in-progressoff for main pushes. - Webhooks (§12): one per live portal, that portal's vault secret, ping delivery
code=200—gh api repos/Systemorph/<Repo>/hooks --jq lengthequals the number of live portals. - A
<Partition>/_GitSyncon every portal that serves the repo's partitions (§12), and after the first greenmainrun itslastSyncCommitShaequals that run'shead_sha. -
preflightnames every input, fails red, fork exemption on the event; no gate carries an input-shapedif:or acontinue-on-error:. - Secrets/vars provisioned (§10) for Actions and Dependabot; two OIDC federated credentials registered.
- Branch protection:
strict: false, contexts in the<caller job> / <name>form. - Registered as a
pluginCatalog.sourcesentry in the deployment repo.
What proves it worked — three observations, not "the files exist":
# 1. The first PR's required checks went green under their NEW names.
gh pr checks <n> --repo Systemorph/MeshWeaver.<Name>
gh api repos/Systemorph/MeshWeaver.<Name>/branches/main/protection \
--jq '.required_status_checks.contexts' # must MATCH the names above, exactly
# 2. The first main run PUBLISHED — the publish-bake job succeeded and the module tag was cut.
gh run list --repo Systemorph/MeshWeaver.<Name> --branch main --limit 1 --json databaseId,conclusion
gh run view <id> --repo Systemorph/MeshWeaver.<Name> --json jobs \
--jq '.jobs[] | "\(.conclusion)\t\(.name)"' # publish-bake + tag-modules present AND success
git ls-remote --tags origin | grep '<Package>/v' # the version label exists
# 3. A SCHEDULED run has fired and resolved a RELEASE digest, not the pin.
gh run list --repo Systemorph/MeshWeaver.<Name> --event schedule --limit 3 \
--json conclusion,createdAt,databaseId
🚨 A green tick is not a publication. Check the jobs, not the run conclusion — a job marked
continue-on-error: true fails while its workflow still reports success. And a preflight that
went grey is the failure this whole file is built around: it means the gates never ran.
Where the fleet disagrees — decide, don't drift
| Question | The fleet | Take |
|---|---|---|
| Adopt the reusable workflows? | SocialMedia + Reinsurance yes; Plugins partial; Education + Manufacturing no | Yes. The two that hand-roll predate the extraction |
strict branch protection? | Plugins true; the rest false or unprotected | false — true is a measured merge treadmill |
| Commit/push policy in AGENTS.md | 4 repos "finish it / merge by default"; SocialMedia "wait to be asked" | Finish it — matches core |
| Where the authoring rules live | SocialMedia/Manufacturing/Reinsurance point at Plugins' AGENTS.md; Plugins holds them | Point. A restated rule is a forked rule |
.gitignore and .claude/ | Memex blanket-ignores it; the five node repos ignore nothing | Neither — .claude/* + !.claude/skills/ |
Which scripts/ copy | 4-5 variants of most files; Plugins is the hardened superset | Plugins, SKIP adjusted — not the nearest neighbour |
e2e/ suite? | Plugins/Reinsurance/SocialMedia share 00-bootstrap, login, apps, covers, helpers.ts, packages.ts; Education has 25 specs; Manufacturing has none | Optional. If you add one, arm it in CI — SocialMedia shipped specs nothing ran until an e2e-static job was added |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |