@starci/skills 1.1.0

package/operators/workspace-bind/validate.mjs

@@ -0,0 +1,152 @@
+// workspace.bind's own law over one branch, on top of the shared step check: the receipt and the route
+// name the same checkout and head; a source checkout carries no directory and a sibling one
+// does; the hydrated route belongs to this Source and to the requested project and role; the observed
+// checkout is the one the route resolved to; mutation is ready only on the mutation branch and a
+// forbidden worktree policy binds nowhere else; the businesses root is derived from the checkout, never
+// typed; a consumed runtime is ready, owned by someone else, bound to this project, and reachable only
+// through distinct origin-only localhost projections, and only when runtimeNeed asked for one; no hint
+// survives the gate; and a blocked branch records neither a hydration nor a consumed runtime.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { validateStep } from '../../scripts/validate-step.mjs';
+import { tableUnder } from '../../scripts/validate-response.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+// Only an origin-only localhost URL is an endpoint. 127.0.0.1, a host, or a path is not.
+const LOCAL_ORIGIN = /^http:\/\/localhost:([1-9][0-9]{0,4})$/;
+const empty = (v) => v === undefined || v === null || v === '' || v === '—';
+const fields = (rows) => Object.fromEntries((rows ?? []).map(([k, v]) => [k, v]));
+// Route paths arrive from two files written on different machines, so they are compared as normalised
+// strings: separator style and a trailing slash are notation, not identity.
+const comparablePath = (value) => String(value).replaceAll('\\', '/').replace(/\/+$/, '').toLowerCase();
+
+export async function validateWorkspaceStep(branchDir, root = ROOT) {
+  const base = await validateStep(root, branchDir);
+  const errors = [...base.errors];
+  const { response, requirements = {}, present = new Set() } = base;
+  if (!response || response.operatorId !== 'workspace.bind') return { errors };
+  const has = (f) => existsSync(path.join(branchDir, f));
+  const read = (f) => readFile(path.join(branchDir, f), 'utf8');
+
+  let route = null;
+  if (present.has('route') && has('response/data/route.json')) {
+    try { route = JSON.parse(await read('response/data/route.json')); } catch { route = null; }
+  }
+  if (response.status === 'blocked' && route !== null) {
+    errors.push('response/response.json: a blocked branch cannot carry a route');
+  }
+
+  if (route) {
+    const { checkout, gitPolicy, mutationReadiness, runtime } = route;
+    if (!empty(requirements.project) && route.project !== requirements.project) errors.push(`response/data/route.json: project ${route.project} differs from the request's ${requirements.project}`);
+    if (!empty(requirements.role) && route.role !== requirements.role) errors.push(`response/data/route.json: role ${route.role} differs from the request's ${requirements.role}`);
+    if (checkout.sourceHead !== route.sourceHead) errors.push('response/data/route.json: the binding and the routed checkout must name the same source head');
+    if (comparablePath(checkout.diskPath) !== comparablePath(checkout.gitRoot)) errors.push('response/data/route.json: the checkout disk path and Git root must be the same checkout');
+    if (checkout.repositoryKind === 'source' && checkout.directory !== null) errors.push('response/data/route.json: a source checkout must report a null directory');
+    if (checkout.repositoryKind === 'sibling' && checkout.directory === null) errors.push('response/data/route.json: a sibling checkout must report its relative directory');
+
+    // The businesses root is derived from the checkout, never typed by a caller: on a source checkout it
+    // is <gitRoot>/.worktrees/businesses when that worktree exists, otherwise null; a sibling checkout
+    // carries no business authority. business.decide copies this value.
+    const derivedBusinesses = `${String(checkout.gitRoot).replace(/[\\/]+$/, '')}/.worktrees/businesses`;
+    const { businesses } = route.authorityRoots;
+    if (checkout.repositoryKind === 'sibling' && businesses !== null) errors.push('response/data/route.json: a sibling checkout carries no business authority root');
+    if (businesses !== null && businesses !== derivedBusinesses) errors.push(`response/data/route.json: authorityRoots.businesses must be derived from the checkout as ${derivedBusinesses}`);
+
+    // Mutation is ready only on the declared mutation branch. Reporting readiness anywhere else is how a
+    // task branch acquires permission it was never routed.
+    const asked = requirements.gitPolicy ?? null;
+    if (asked && !empty(asked.worktreeBranches) && gitPolicy.worktreeBranches !== asked.worktreeBranches) errors.push(`response/data/route.json: the routed policy ${gitPolicy.worktreeBranches} differs from the request's ${asked.worktreeBranches}`);
+    if (asked && !empty(asked.mutationBranch) && gitPolicy.mutationBranch !== asked.mutationBranch) errors.push(`response/data/route.json: the routed mutation branch ${gitPolicy.mutationBranch} differs from the request's ${asked.mutationBranch}`);
+    const declaredRoots = Array.isArray(requirements.declaredWriteRoots) ? requirements.declaredWriteRoots : [];
+    for (const root of declaredRoots) if (!route.writeRoots.includes(root)) errors.push(`response/data/route.json: the request declared the write root ${root}, which the binding does not carry`);
+    if (mutationReadiness === 'ready' && checkout.branch !== gitPolicy.mutationBranch) errors.push(`response/data/route.json: mutation is ready only on ${gitPolicy.mutationBranch}, not on ${checkout.branch}`);
+    if (gitPolicy.worktreeBranches === 'session-only' && checkout.branch !== gitPolicy.mutationBranch && !/^session\//.test(checkout.branch)) errors.push(`response/data/route.json: a session-only worktree policy binds only on ${gitPolicy.mutationBranch} or on a session/<sessionId> branch, not on ${checkout.branch}`);
+    if (gitPolicy.worktreeBranches === 'forbidden' && checkout.branch !== gitPolicy.mutationBranch) errors.push('response/data/route.json: a forbidden worktree policy cannot bind a route on another branch');
+
+    if (runtime !== null) {
+      // A consumer may run only against a ready owner generation. A port that merely listens, a starting
+      // owner, or a degraded one is evidence to report, not a runtime to use.
+      if ((requirements.runtimeNeed ?? 'none') === 'none') errors.push('response/data/route.json: runtimeNeed is none, so step 5 never ran and no runtime may be bound');
+      if (runtime.status !== 'ready') errors.push(`response/data/route.json: a route cannot bind a ${runtime.status} runtime owner for consumption`);
+      if (runtime.endpointBinding.project !== route.project) errors.push('response/data/route.json: the endpoint binding belongs to another project than the bound route');
+      const services = Object.values(runtime.endpointBinding.services);
+      if (new Set(services).size !== services.length) errors.push('response/data/route.json: endpoint binding service keys must be distinct');
+      const ports = [];
+      for (const [role, endpoint] of Object.entries(runtime.endpoints)) {
+        const match = LOCAL_ORIGIN.exec(endpoint);
+        if (match === null) { errors.push(`response/data/route.json: the ${role} endpoint ${endpoint} is not an origin-only localhost projection`); continue; }
+        const port = Number(match[1]);
+        if (port > 65535) errors.push(`response/data/route.json: the ${role} endpoint port exceeds 65535`);
+        ports.push(port);
+      }
+      if (new Set(ports).size !== ports.length) errors.push('response/data/route.json: the frontend, api, and identity endpoints must resolve to distinct ports');
+    } else if (requirements.runtimeNeed === 'consume' && response.status === 'done') {
+      errors.push('response/data/route.json: a caller that consumes the shared runtime must bind the runtime owner');
+    }
+  }
+
+  if (present.has('workspace-route-binding') && has('response/response.md')) {
+    const text = await read('response/response.md');
+    const binding = fields(tableUnder(text, '## Binding'));
+    const checkout = fields(tableUnder(text, '## Checkout'));
+    const policy = fields(tableUnder(text, '## Policy'));
+    const runtimeRows = fields(tableUnder(text, '## Runtime'));
+    const writeRoots = (tableUnder(text, '## Write roots') ?? []).map(([p]) => p);
+
+    const findingKeys = new Set();
+    for (const [code, subject] of tableUnder(text, '## Findings') ?? []) {
+      const key = `${code}|${subject}`;
+      if (findingKeys.has(key)) errors.push(`response/response.md: finding ${code} repeats subject ${subject}`);
+      findingKeys.add(key);
+    }
+
+    if (route) {
+      if (binding.Project !== route.project) errors.push(`response/response.md: Project ${binding.Project} differs from the route binding's ${route.project}`);
+      if (binding.Role !== route.role) errors.push(`response/response.md: Role ${binding.Role} differs from the route binding's ${route.role}`);
+      if (binding['Source head'] !== route.sourceHead) errors.push('response/response.md: Source head differs from the route binding');
+      if (binding['Hydrated route'] !== route.hydratedRouteRef) errors.push('response/response.md: Hydrated route differs from the route binding');
+      if (checkout.Branch !== route.checkout.branch) errors.push(`response/response.md: Branch ${checkout.Branch} differs from the route binding's ${route.checkout.branch}`);
+      if (checkout['Mutation readiness'] !== route.mutationReadiness) errors.push('response/response.md: Mutation readiness differs from the route binding');
+      if (checkout['Repository kind'] !== route.checkout.repositoryKind) errors.push('response/response.md: Repository kind differs from the route binding');
+      const businesses = route.authorityRoots.businesses;
+      if ((empty(checkout['Businesses root']) ? null : checkout['Businesses root']) !== businesses) errors.push(`response/response.md: Businesses root ${checkout['Businesses root']} differs from the derived ${String(businesses)}`);
+      if (policy['Worktree branches'] !== route.gitPolicy.worktreeBranches) errors.push('response/response.md: Worktree branches differs from the route binding');
+      if (policy['Mutation branch'] !== route.gitPolicy.mutationBranch) errors.push('response/response.md: Mutation branch differs from the route binding');
+      if (writeRoots.length !== route.writeRoots.length || writeRoots.some((p) => !route.writeRoots.includes(p))) errors.push('response/response.md: Write roots differ from the route binding');
+
+      // The portable-to-hydrated resolution is the whole authority of this receipt, so it is stated
+      // rather than assumed.
+      if (!findingKeys.has(`ROUTE_HYDRATED_FROM_PORTABLE|${route.hydratedRouteRef}`)) errors.push('response/response.md: a bound route must record the hydrated route it resolved from');
+      if (route.gitPolicy.worktreeBranches === 'forbidden' && !findingKeys.has(`WORKTREE_BRANCH_FORBIDDEN|${route.gitPolicy.mutationBranch}`)) errors.push('response/response.md: a forbidden worktree policy must be recorded on the bound route');
+      if (route.provenanceHeadRef !== null && !findingKeys.has(`PROVENANCE_HEAD_BOUND|${route.provenanceHeadRef}`)) errors.push('response/response.md: a bound provenance head must be recorded');
+      if (route.runtime !== null) {
+        if (!findingKeys.has(`RUNTIME_CONSUMED_NOT_OWNED|${route.runtime.ownerTaskId}`)) errors.push('response/response.md: a consumed runtime must record that the caller does not own it');
+        if (runtimeRows['Owner task'] !== route.runtime.ownerTaskId) errors.push('response/response.md: Owner task differs from the route binding');
+        if (runtimeRows.Status !== route.runtime.status) errors.push('response/response.md: Runtime status differs from the route binding');
+        if (runtimeRows['Consumer role'] !== 'consumer') errors.push('response/response.md: the caller consumes the runtime and never owns it');
+        for (const [label, key] of [['Frontend', 'frontend'], ['Api', 'api'], ['Identity', 'identity']]) {
+          if (runtimeRows[label] !== route.runtime.endpoints[key]) errors.push(`response/response.md: the ${key} endpoint differs from the route binding`);
+        }
+      } else if (Object.keys(runtimeRows).length) errors.push('response/response.md: the Runtime section carries rows but no runtime was bound');
+    }
+
+    // Hints are refused at the gate, so no finding may record one as if it had been weighed.
+    for (const key of findingKeys) if (key.startsWith('HINT_REJECTED|')) errors.push('response/response.md: a hint is INVALID_INPUT at the gate, so a bound receipt never records HINT_REJECTED');
+    // Only the sealed roster reference is bound; no credential is read.
+    if (![...findingKeys].some((key) => key.startsWith('IDENTITY_ROSTER_SEALED|'))) errors.push('response/response.md: a bound route must record that the credential roster was sealed and never read');
+  } else if (response.status === 'done') {
+    errors.push('response/response.md: a bound branch needs the route receipt');
+  }
+  return { errors };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const target = process.argv[2];
+  if (!target) { process.stderr.write('usage: node validate.mjs <session>/step-N/parallel-M\n'); process.exit(2); }
+  const { errors } = await validateWorkspaceStep(path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('valid workspace.bind branch\n');
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@starci/skills",
+  "version": "1.1.0",
+  "description": "StarCi Skills: one entry, fourteen operators, a closed routing map and a tool registry, installed as the .claude runtime of a repository for Claude Code and Codex.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "starci-skills": "bin/starci-skills.mjs"
+  },
+  "files": [
+    "bin/",
+    "INDEX.md",
+    "INDEX.vi.md",
+    "SKILL.md",
+    "SKILL.vi.md",
+    "routing.json",
+    "alias/",
+    "knowledge/",
+    "operators/",
+    "readiness/",
+    "resources/",
+    "scripts/",
+    "templates/",
+    "workflows/",
+    "README.md",
+    "README.vi.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/starci183/starci-skills.git"
+  },
+  "homepage": "https://harness.starci.org",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "agent",
+    "skills",
+    "starci"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node scripts/validate-routing.mjs && node scripts/validate-resources.mjs && node scripts/validate-knowledge-citations.mjs && node scripts/validate-alias.mjs && node scripts/generate-alias-doc.mjs --check && node scripts/validate-operator.mjs && node scripts/validate-workflows.mjs && node scripts/validate-defaults.mjs && node scripts/generate-operators-index.mjs --check && node scripts/validate-templates.mjs && node scripts/run-operator-self-tests.mjs && node --test scripts/*.spec.mjs && npm run docs:check",
+    "docs:check": "node docs/scripts/generate-docs.mjs --check"
+  }
+}

package/readiness/initialization/workspaces/commit-policy.json

@@ -0,0 +1,91 @@
+{
+  "schemaVersion": 1,
+  "id": "workspace-multidevice-commit-boundary-v1",
+  "purpose": "Git synchronizes portable intent and encrypted authority; every device rebuilds machine-local state from that intent after proving the same master identity.",
+  "sourceRepository": {
+    "requiredTracked": [
+      "AGENTS.md",
+      "CLAUDE.md",
+      ".workspaces/config.json"
+    ],
+    "requiredTrackedTree": ".workspaces/projects",
+    "forbiddenTrackedPrefixes": [
+      ".workspace/",
+      ".workspaces/local/",
+      ".worktrees/",
+      ".gitmounts/",
+      ".sessions/"
+    ],
+    "requiredIgnoredRoots": [
+      ".workspace",
+      ".workspaces/local",
+      ".worktrees",
+      ".gitmounts",
+      ".sessions"
+    ]
+  },
+  "classes": {
+    "portableWorkspace": {
+      "commit": true,
+      "paths": [".workspaces/config.json", ".workspaces/device-state.json", ".workspaces/projects/<project>/<role>.json"],
+      "rule": "Contains only machine-independent repository, branch, role, Grammar and contract intent. Absolute paths, observed commits, credentials and runtime state are forbidden."
+    },
+    "hydratedWorkspace": {
+      "commit": false,
+      "paths": [".workspaces/local/**"],
+      "rule": "Derived independently on each device from portable declarations and the local filesystem."
+    },
+    "durableWorktree": {
+      "commit": "inside-own-checkout-only",
+      "paths": [".worktrees/<kind>/**"],
+      "rule": "The Source repository never tracks the container. Approved product or authority changes are committed by the worktree's own Git repository and branch."
+    },
+    "ephemeralWorktree": {
+      "commit": false,
+      "paths": [".claude/worktrees/<id>/**"],
+      "rule": "Agent checkout state is disposable and never portable authority."
+    },
+    "referenceCheckout": {
+      "commit": false,
+      "paths": [".worktrees/references/<project>-<role>/**"],
+      "rule": "Read-only clean precedent checkout. Refresh or rebuild it; never author or push from it."
+    },
+    "gitmountCheckout": {
+      "commit": false,
+      "paths": [".gitmounts/<name>/**"],
+      "rule": "A private operational-data checkout is reconstructed by npm run sync from metadata.json. Its optional credentialEnv and credentialFallbackEnvs resolve only to encrypted runtime files; plaintext tokens, authenticated URLs and the checkout itself never enter Git."
+    },
+    "runtimeState": {
+      "commit": false,
+      "paths": [".sessions/**", ".workspaces/local/state/**", ".workspaces/local/routes/**"],
+      "rule": "Generated runtime config, virtual environments, PIDs, receipts, caches and absolute routes are local-only."
+    },
+    "encryptedDeviceState": {
+      "commit": false,
+      "remote": "private-release-assets",
+      "paths": [".workspace/device-state/**"],
+      "rule": "Quiesced Docker-volume archives are encrypted to the master age recipient, chunked, checksum-bound and published only as private release assets. Plain archives, Docker volumes and downloaded ciphertext remain local-only; Git tracks only the portable contract."
+    },
+    "encryptedAuthority": {
+      "commit": true,
+      "paths": [".stacks/**/*.enc", ".stacks/**/KEYS.md", ".stacks/*/infra/compose/**"],
+      "rule": "Ciphertext, recipient metadata and value-free topology are portable. The master identity and decrypted twins are never committed."
+    },
+    "masterIdentity": {
+      "commit": false,
+      "paths": ["~/.starci/master.identity"],
+      "rule": "Provision out of band on each trusted device. Possession permits decryption but never changes Git tracking rules."
+    }
+  },
+  "deviceBootstrap": [
+    "Pull the Source repository and its independent StarCi skills checkout.",
+    "Prove the out-of-band master identity without printing its contents.",
+    "Validate tracked portable declarations and the Git boundary.",
+    "Run workspace-portable.mjs bootstrap --apply to clone absent declared sibling checkouts and hydrate machine-local project-role routes.",
+    "Create or verify declared worktrees and clean reference checkouts.",
+    "Run npm run sync to decrypt local secret twins and reconstruct declared private gitmounts without per-device GitHub login.",
+    "Fetch the latest compatible encrypted device-state release; restore only into absent or explicitly approved replaceable Docker volumes.",
+    "Rebuild declared runtime state without a derived search index.",
+    "Run Source readiness and prove default search against one exact canonical reference before product work."
+  ]
+}

package/readiness/initialization/workspaces/config.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://starci.dev/v6/readiness/initialization/workspaces/config.schema.json",
+  "title": "StarCi workspace defaults",
+  "oneOf": [
+    { "$ref": "#/$defs/v1" },
+    { "$ref": "#/$defs/v6" }
+  ],
+  "$defs": {
+    "languageTag": {
+      "type": "string",
+      "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
+    },
+    "v1": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "defaultLang"],
+      "properties": {
+        "$schema": { "type": "string" },
+        "version": { "const": 1 },
+        "defaultLang": { "$ref": "#/$defs/languageTag" }
+      }
+    },
+    "v6": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "defaultLang"],
+      "properties": {
+        "$schema": { "type": "string" },
+        "schemaVersion": { "const": 6 },
+        "defaultLang": { "$ref": "#/$defs/languageTag" }
+      }
+    }
+  }
+}

package/readiness/initialization/workspaces/device-state.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://starci.dev/v6/workspaces/device-state.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "schemaVersion", "id", "project", "docker", "encryption", "remote"],
+  "properties": {
+    "$schema": { "type": "string", "minLength": 1 },
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*-v[0-9]+$" },
+    "project": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "docker": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["helperImage", "volumes"],
+      "properties": {
+        "helperImage": { "type": "string", "minLength": 1 },
+        "volumes": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+$" }
+            }
+          }
+        }
+      }
+    },
+    "encryption": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["masterIdentity"],
+      "properties": {
+        "masterIdentity": { "type": "string", "pattern": "^~[\\\\/].+" }
+      }
+    },
+    "remote": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repository", "releasePrefix", "tokenFile", "chunkBytes", "retention"],
+      "properties": {
+        "repository": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" },
+        "releasePrefix": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+        "tokenFile": { "type": "string", "pattern": "^(?![\\\\/]|[A-Za-z]:[\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$" },
+        "chunkBytes": { "type": "integer", "minimum": 1048576, "maximum": 134217728 },
+        "retention": { "type": "integer", "minimum": 1, "maximum": 20 }
+      }
+    }
+  }
+}

package/readiness/initialization/workspaces/local-route.schema.json

@@ -0,0 +1,206 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://starci.dev/v6/readiness/initialization/workspaces/local-route.schema.json",
+  "title": "Machine-local StarCi workspace route",
+  "description": "Hydrated machine-local route. V1 and unrevisioned V6 remain readable for safe migration; schemaRevision 2 is the current V6 contract-aware envelope.",
+  "oneOf": [
+    { "$ref": "#/$defs/v1" },
+    { "$ref": "#/$defs/v6Legacy" },
+    { "$ref": "#/$defs/v6Current" }
+  ],
+  "$defs": {
+    "slug": {
+      "type": "string",
+      "maxLength": 80,
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "absolutePath": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 1024,
+      "pattern": "^([A-Za-z]:[\\\\/]|/).+"
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "trust", "skills", "workspaceRoot"],
+      "properties": {
+        "path": { "$ref": "#/$defs/absolutePath" },
+        "trust": { "$ref": "#/$defs/absolutePath" },
+        "skills": { "$ref": "#/$defs/absolutePath" },
+        "workspaceRoot": { "$ref": "#/$defs/absolutePath" }
+      }
+    },
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["diskPath", "gitRoot", "gitRepository", "branch", "head"],
+      "properties": {
+        "diskPath": { "$ref": "#/$defs/absolutePath" },
+        "gitRoot": { "$ref": "#/$defs/absolutePath" },
+        "gitRepository": {
+          "type": "string",
+          "maxLength": 512,
+          "pattern": "^https://github\\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+(?:\\.git)?$"
+        },
+        "branch": { "type": "string", "minLength": 1, "maxLength": 255 },
+        "head": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "gitPolicy": { "$ref": "#/$defs/gitPolicy" }
+      }
+    },
+    "gitPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mutationBranch", "worktreeBranches", "incomingBranchRefs"],
+      "properties": {
+        "mutationBranch": { "type": "string", "minLength": 1, "maxLength": 255 },
+        "worktreeBranches": { "enum": ["forbidden", "session-only"], "description": "forbidden: no branch or worktree besides the mutation branch; session-only: a git worktree on session/<sessionId> may be created for one runtime session and is merged into the mutation branch by git.publish, then removed" },
+        "incomingBranchRefs": { "const": "merge-into-mutation-branch" }
+      }
+    },
+    "commonContext": {
+      "properties": {
+        "instructions": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/absolutePath" }
+        },
+        "manifests": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/absolutePath" }
+        }
+      }
+    },
+    "v1Context": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["instructions", "manifests", "grammar", "grammarProfile"],
+      "properties": {
+        "instructions": { "$ref": "#/$defs/commonContext/properties/instructions" },
+        "manifests": { "$ref": "#/$defs/commonContext/properties/manifests" },
+        "grammar": {
+          "oneOf": [
+            { "$ref": "#/$defs/slug" },
+            { "type": "null" }
+          ]
+        },
+        "grammarProfile": {
+          "oneOf": [
+            { "$ref": "#/$defs/slug" },
+            { "type": "null" }
+          ]
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "grammar": { "type": "null" } }, "required": ["grammar"] },
+          "then": { "properties": { "grammarProfile": { "type": "null" } } },
+          "else": { "properties": { "grammarProfile": { "$ref": "#/$defs/slug" } } }
+        }
+      ]
+    },
+    "v6PreContractContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["instructions", "manifests", "grammarId"],
+      "properties": {
+        "instructions": { "$ref": "#/$defs/commonContext/properties/instructions" },
+        "manifests": { "$ref": "#/$defs/commonContext/properties/manifests" },
+        "grammarId": { "enum": ["core", "offset-pop", null] }
+      }
+    },
+    "v6ContractContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["instructions", "contract", "contractSource", "manifests", "grammarId"],
+      "properties": {
+        "instructions": { "$ref": "#/$defs/commonContext/properties/instructions" },
+        "contract": {
+          "oneOf": [
+            { "$ref": "#/$defs/absolutePath" },
+            { "type": "null" }
+          ]
+        },
+        "contractSource": {
+          "oneOf": [
+            { "type": "string", "minLength": 1, "maxLength": 1024 },
+            { "type": "null" }
+          ]
+        },
+        "manifests": { "$ref": "#/$defs/commonContext/properties/manifests" },
+        "grammarId": { "enum": ["core", "offset-pop", null] }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "contract": { "type": "null" } }, "required": ["contract"] },
+          "then": { "properties": { "contractSource": { "type": "null" } } },
+          "else": { "properties": { "contractSource": { "type": "string", "minLength": 1 } } }
+        }
+      ]
+    },
+    "v1": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "project", "role", "source", "repository", "context", "updatedAt"],
+      "properties": {
+        "$schema": { "type": "string" },
+        "version": { "const": 1 },
+        "project": { "$ref": "#/$defs/slug" },
+        "role": { "$ref": "#/$defs/slug" },
+        "source": { "$ref": "#/$defs/source" },
+        "repository": { "$ref": "#/$defs/repository" },
+        "context": { "$ref": "#/$defs/v1Context" },
+        "updatedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "v6Legacy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["$schema", "schemaVersion", "project", "role", "source", "repository", "context", "updatedAt"],
+      "properties": {
+        "$schema": { "type": "string" },
+        "schemaVersion": { "const": 6 },
+        "project": { "$ref": "#/$defs/slug" },
+        "role": { "$ref": "#/$defs/slug" },
+        "source": { "$ref": "#/$defs/source" },
+        "repository": { "$ref": "#/$defs/repository" },
+        "context": {
+          "oneOf": [
+            { "$ref": "#/$defs/v6PreContractContext" },
+            { "$ref": "#/$defs/v6ContractContext" }
+          ]
+        },
+        "updatedAt": { "type": "string", "format": "date-time" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "role": { "enum": ["be", "chart"] } }, "required": ["role"] },
+          "then": { "properties": { "context": { "properties": { "grammarId": { "type": "null" } } } } }
+        }
+      ]
+    },
+    "v6Current": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["$schema", "schemaVersion", "schemaRevision", "project", "role", "source", "repository", "context", "updatedAt"],
+      "properties": {
+        "$schema": { "type": "string" },
+        "schemaVersion": { "const": 6 },
+        "schemaRevision": { "const": 2 },
+        "project": { "$ref": "#/$defs/slug" },
+        "role": { "$ref": "#/$defs/slug" },
+        "source": { "$ref": "#/$defs/source" },
+        "repository": { "$ref": "#/$defs/repository" },
+        "context": { "$ref": "#/$defs/v6ContractContext" },
+        "updatedAt": { "type": "string", "format": "date-time" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "role": { "enum": ["be", "chart"] } }, "required": ["role"] },
+          "then": { "properties": { "context": { "properties": { "grammarId": { "type": "null" } } } } }
+        }
+      ]
+    }
+  }
+}