cyber-sdd 0.0.0 → 0.2.0

package/skills/mission-graph/scripts/mission-graph.mts

@@ -19,8 +19,9 @@
 // node:test; running the file directly drives the CLI.
 
 import { execFileSync } from 'node:child_process'
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from 'node:fs'
 import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 
 // ── Schema (v:1) ──
 
@@ -50,6 +51,12 @@ export interface NodeEvent {
 	origin?: string[]
 	/** Set only on an Operation node: the Mission that marks it "done enough to ship". */
 	capstone?: string
+	/** Which project the node belongs to. Absent -> the default project (a real project, the
+	 *  sentinel `DEFAULT_PROJECT` — NOT a wildcard). */
+	project?: string
+	/** Marks the node a barrier — a project-wide mission the fleet must rebase onto before fanning
+	 *  out again. Only a Mission may ever be a barrier (write-time INV-1). */
+	barrier?: boolean
 }
 
 export interface EdgeEvent {
@@ -89,6 +96,8 @@ export interface GraphNode {
 	briefPointer: string
 	origin: string[]
 	capstone?: string
+	project: string
+	barrier: boolean
 	/** The schema version stamped on the node's latest event (forward-compat placeholder — v1
 	 *  only exists today; a later version arrives on newer events and rides along unread). */
 	schemaVersion: number
@@ -105,6 +114,10 @@ export interface Graph {
 	edges: GraphEdge[]
 }
 
+/** The shared default project — a REAL project every project-less node belongs to together, not a
+ *  wildcard that matches every project. */
+export const DEFAULT_PROJECT = ''
+
 const NODE_DEFAULTS = {
 	kind: 'mission' as NodeKind,
 	status: 'open' as NodeStatus,
@@ -112,6 +125,8 @@ const NODE_DEFAULTS = {
 	hitlOrAfk: 'hitl' as HitlOrAfk,
 	modelTier: 'unspecified',
 	briefPointer: '',
+	project: DEFAULT_PROJECT,
+	barrier: false,
 }
 
 function edgeKey(kind: EdgeKind, from: string, to: string): string {
@@ -163,6 +178,8 @@ export function fold(events: readonly MissionGraphEvent[]): Graph {
 			briefPointer: typeof fields.briefPointer === 'string' ? fields.briefPointer : NODE_DEFAULTS.briefPointer,
 			origin: Array.isArray(fields.origin) ? [...(fields.origin as string[])] : [],
 			capstone: typeof fields.capstone === 'string' ? fields.capstone : undefined,
+			project: typeof fields.project === 'string' ? fields.project : NODE_DEFAULTS.project,
+			barrier: typeof fields.barrier === 'boolean' ? fields.barrier : NODE_DEFAULTS.barrier,
 			schemaVersion: typeof fields.v === 'number' ? fields.v : 1,
 		})
 	}
@@ -338,6 +355,93 @@ export function proposeEdge(
 			reason: `would close a RAW cycle (${proposed.to} already reaches ${proposed.from})`,
 		}
 	}
+	if (proposed.kind === 'RAW') {
+		const candidate: Graph = {
+			nodes: graph.nodes,
+			edges: [...graph.edges, { kind: proposed.kind, from: proposed.from, to: proposed.to }],
+		}
+		const violation = checkBarrierInvariants(candidate)
+		if (violation) return { accepted: false, reason: violation }
+	}
+	return { accepted: true }
+}
+
+// ── The barrier write-time guards — all fold-then-check: apply the proposed change to the
+//    already-folded graph, then reject if the resulting state violates an invariant. Re-run on
+//    EVERY append (node or edge) so no ordering of "mark barrier" vs "add the offending edge"
+//    can slip a violation through. ──
+
+/**
+ * checkBarrierInvariants — runs INV-1/INV-2/INV-3 over an already-simulated (post-append) graph.
+ * Returns the first violation's reason, or null when the graph is clean.
+ *   INV-1: only a Mission may carry a barrier marking.
+ *   INV-2: no un-retired barrier may have a RAW predecessor that is an Operation (an Operation
+ *     never retires, so such a barrier would fence its project forever, invisibly to `cycles`).
+ *   INV-3: no two un-retired barriers of one project may both be `claimed` at once.
+ */
+function checkBarrierInvariants(graph: Graph): string | null {
+	for (const n of graph.nodes.values()) {
+		if (n.barrier && n.kind !== 'mission') {
+			return 'INV-1: a barrier marking is only valid on a mission node'
+		}
+	}
+	for (const n of graph.nodes.values()) {
+		if (!n.barrier || n.status === 'retired') continue
+		for (const predId of rawPredecessors(graph, n.id)) {
+			if (graph.nodes.get(predId)?.kind === 'operation') {
+				return 'INV-2: an un-retired barrier may not have a RAW predecessor that is an operation'
+			}
+		}
+	}
+	const claimedBarriersByProject = new Map<string, number>()
+	for (const n of graph.nodes.values()) {
+		if (n.barrier && n.status === 'claimed') {
+			claimedBarriersByProject.set(n.project, (claimedBarriersByProject.get(n.project) ?? 0) + 1)
+		}
+	}
+	for (const count of claimedBarriersByProject.values()) {
+		if (count > 1) return 'INV-3: at most one barrier of a project may be claimed at once'
+	}
+	return null
+}
+
+/**
+ * applyNodeEventSimulated — shallow-merges one more node event onto an already-folded graph's
+ * existing node (or NODE_DEFAULTS when absent), mirroring `fold`'s per-field merge semantics
+ * without re-folding the whole event log — the guard only needs the ONE resulting node.
+ */
+function applyNodeEventSimulated(graph: Graph, event: NodeEvent): Graph {
+	const prev = graph.nodes.get(event.id)
+	const merged: GraphNode = {
+		id: event.id,
+		kind: event.kind ?? prev?.kind ?? NODE_DEFAULTS.kind,
+		status: event.status ?? prev?.status ?? NODE_DEFAULTS.status,
+		touchSet: event.touchSet ? [...event.touchSet] : (prev?.touchSet ?? []),
+		blast: event.blast ?? prev?.blast ?? NODE_DEFAULTS.blast,
+		hitlOrAfk: event.hitlOrAfk ?? prev?.hitlOrAfk ?? NODE_DEFAULTS.hitlOrAfk,
+		modelTier: event.modelTier ?? prev?.modelTier ?? NODE_DEFAULTS.modelTier,
+		briefPointer: event.briefPointer ?? prev?.briefPointer ?? NODE_DEFAULTS.briefPointer,
+		origin: event.origin ? [...event.origin] : (prev?.origin ?? []),
+		capstone: event.capstone ?? prev?.capstone,
+		project: event.project ?? prev?.project ?? NODE_DEFAULTS.project,
+		barrier: event.barrier ?? prev?.barrier ?? NODE_DEFAULTS.barrier,
+		schemaVersion: typeof event.v === 'number' ? event.v : (prev?.schemaVersion ?? 1),
+	}
+	const nodes = new Map(graph.nodes)
+	nodes.set(event.id, merged)
+	return { nodes, edges: graph.edges }
+}
+
+/**
+ * proposeNode — the write-time guard for a node event: simulates the merge onto the already-
+ * folded graph, then rejects (INV-1/INV-2/INV-3) if the resulting state is invalid. Fold-then-
+ * check, exactly like `proposeEdge` — so marking a node a barrier AFTER an Operation RAW edge
+ * already exists is caught exactly like the reverse order.
+ */
+export function proposeNode(graph: Graph, event: NodeEvent): EdgeDecision {
+	const candidate = applyNodeEventSimulated(graph, event)
+	const violation = checkBarrierInvariants(candidate)
+	if (violation) return { accepted: false, reason: violation }
 	return { accepted: true }
 }
 
@@ -442,6 +546,59 @@ function whyReady(graph: Graph, id: string): string {
 	return `RAW-satisfied: ${[...preds].sort(compareIds).join(', ')} retired`
 }
 
+/** An un-retired barrier — open or claimed — is "live": it grants exemption (clause 1), fences its
+ *  project (clause 3), and occupies its project's at-most-one slot (clause 2). */
+function isLiveBarrier(n: GraphNode): boolean {
+	return n.barrier && n.status !== 'retired'
+}
+
+/**
+ * fenceExempt — clause 1's exempt set: every NON-barrier mission in the STRICT RAW-predecessor
+ * closure of any live (un-retired) barrier, graph-global (not scoped to the barrier's own
+ * project — an acyclic two-project deadlock needs the exemption to cross project lines). Barriers
+ * are NEVER exempt, so a barrier that is itself a RAW predecessor of another project's barrier
+ * cannot use exemption to dodge its own project's at-most-one cap (clause 2).
+ */
+function fenceExempt(graph: Graph): Set<string> {
+	const exempt = new Set<string>()
+	for (const b of graph.nodes.values()) {
+		if (!isLiveBarrier(b)) continue
+		for (const id of rawClosure(graph, b.id)) {
+			if (id === b.id) continue // strict — rawClosure is reflexive
+			const m = graph.nodes.get(id)
+			if (m && !m.barrier) exempt.add(id)
+		}
+	}
+	return exempt
+}
+
+/**
+ * barrierHeldByCap — clause 2, the at-most-one-barrier-per-project offer cap, evaluated over
+ * UN-RETIRED barriers of `candidate`'s project (open ∪ claimed, never just the open `candidates`
+ * set — a claimed barrier still fills the slot even though it's no longer itself a candidate).
+ * Holds `candidate` when either another un-retired barrier of the project is already claimed, or a
+ * lower-id OPEN RAW-satisfied barrier of the project exists (a quarantined or RAW-blocked one never
+ * fills the slot).
+ */
+function barrierHeldByCap(
+	graph: Graph,
+	quarantined: ReadonlySet<string>,
+	liveBarriersOfProject: readonly GraphNode[],
+	candidate: GraphNode,
+): boolean {
+	const claimedElsewhere = liveBarriersOfProject.some((b) => b.id !== candidate.id && b.status === 'claimed')
+	if (claimedElsewhere) return true
+	const lowerIdOpenRawSatisfied = liveBarriersOfProject.some(
+		(b) =>
+			b.id !== candidate.id &&
+			b.status === 'open' &&
+			!quarantined.has(b.id) &&
+			isRawSatisfied(graph, quarantined, b.id) &&
+			compareIds(b.id, candidate.id) < 0,
+	)
+	return lowerIdOpenRawSatisfied
+}
+
 /**
  * ready — reads the graph without changing it and returns every Mission that is both RAW-satisfied
  * (every RAW predecessor retired, transitively — realized here as each direct predecessor's own
@@ -450,17 +607,43 @@ function whyReady(graph: Graph, id: string): string {
  * (claimed) mission's is held; (2) among the remaining RAW-satisfied candidates, an intersecting
  * pair never both surface — the pinned lowest-id tie-break (compareIds) admits one and holds the
  * rest, guaranteeing the frontier never contains a WAW pair. A cycle-quarantined mission (and
- * anything depending on it) is excluded regardless of its recorded status. Deterministic: same
- * graph in, same frontier in the same order out. Read-only: never mutates `graph`.
+ * anything depending on it) is excluded regardless of its recorded status.
+ *
+ * Before the WAW-mutex, the RAW-satisfied non-quarantined candidates pass through the barrier
+ * fence (fold-time, never a stored edge — see the .feature "ready — the barrier fence" block):
+ * clause 1 lifts a non-barrier in any live barrier's strict RAW-predecessor closure from every
+ * fence (graph-global); clause 2 caps each project to at most one offered barrier (counting
+ * open+claimed, so an in-flight barrier still fills the slot); clause 3 holds every other
+ * non-barrier, non-exempt candidate of a fenced project outright, regardless of touch-set (an
+ * empty-touch-set barrier still fences — the fence never delegates to the WAW-mutex).
+ *
+ * Deterministic: same graph in, same frontier in the same order out. Read-only: never mutates
+ * `graph`.
  */
 export function ready(graph: Graph): FrontierEntry[] {
 	const quarantined = quarantinedIds(graph)
 	const missions = [...graph.nodes.values()].filter((n) => n.kind === 'mission')
 	const inFlightTouchSets = missions.filter((n) => n.status === 'claimed').map((n) => n.touchSet)
 
-	const candidates = missions.filter(
+	const rawSatisfiedOpen = missions.filter(
 		(n) => n.status === 'open' && !quarantined.has(n.id) && isRawSatisfied(graph, quarantined, n.id),
 	)
+
+	// ── The barrier fence (fold-time, applied to the RAW-satisfied candidates before the WAW-mutex) ──
+	const liveBarriers = missions.filter(isLiveBarrier)
+	const exempt = fenceExempt(graph)
+	const fencedProjects = new Set(liveBarriers.map((b) => b.project))
+
+	const candidates = rawSatisfiedOpen.filter((c) => {
+		if (c.barrier) {
+			const ofProject = liveBarriers.filter((b) => b.project === c.project)
+			return !barrierHeldByCap(graph, quarantined, ofProject, c)
+		}
+		if (exempt.has(c.id)) return true // clause 1 — lifted from every fence, graph-global
+		if (fencedProjects.has(c.project)) return false // clause 3 — held outright, regardless of touch-set
+		return true
+	})
+
 	const notHeldByInFlight = candidates.filter((n) => !inFlightTouchSets.some((t) => intersects(t, n.touchSet)))
 
 	// Trigger 2: the pinned lowest-id tie-break. Processing in ascending id order and admitting a
@@ -626,22 +809,293 @@ export interface MigrateResult {
 	migrated: boolean
 	reason: string
 	count: number
+	/** Whether the in-tree seed was retired (deleted + staged) THIS run. */
+	retired: boolean
+	retiredReason: string
+}
+
+function relativeStorePath(): string {
+	return STORE_RELATIVE_PATH.join('/')
+}
+
+/** Every raw seed line must already be present among the orphan ref's lines — the guard that
+ *  keeps retirement from ever being the data loss the migration exists to prevent. An empty seed
+ *  vacuously counts as fully carried (nothing to lose). */
+function seedFullyCarried(root: string): boolean {
+	const seedLines = readInTreeLines(root)
+	if (seedLines.length === 0) return true
+	const orphanLines = new Set(readOrphanLines(root))
+	return seedLines.every((line) => orphanLines.has(line))
+}
+
+/**
+ * retireSeed — migrate's final, guarded act: once (and only once) the orphan ref already carries
+ * every line of the in-tree seed, deletes the seed file and stages the deletion (never commits
+ * it — landing that commit is the caller's next step, and is what actually makes the retirement
+ * reach other clones). Refuses when the ref does not yet carry every seed line. Idempotent and
+ * safe to re-run: a pre-fix project whose seed was left behind by an earlier migrate is repaired
+ * simply by calling migrate again.
+ */
+function retireSeed(root: string): { retired: boolean; retiredReason: string } {
+	const path = storePath(root)
+	if (!existsSync(path)) {
+		return { retired: false, retiredReason: 'no in-tree seed remains to retire' }
+	}
+	if (!seedFullyCarried(root)) {
+		return { retired: false, retiredReason: 'will not retire a seed the orphan ref does not carry' }
+	}
+	rmSync(path)
+	try {
+		git(root, ['add', '--', relativeStorePath()])
+	} catch {
+		// The seed was never tracked by git (e.g. a hand-built test fixture) — nothing to stage;
+		// the file is still deleted from the working tree, which is all that case can promise.
+	}
+	return { retired: true, retiredReason: 'seed deleted; the staged deletion must be committed to reach other clones' }
 }
 
 /**
  * migrate — one-time, idempotent: seeds the orphan ref from the existing in-tree store, copying
- * its raw lines verbatim (never parsed and re-serialized, so exact bytes/order are preserved).
- * A no-op (never throws) when there is nothing to seed from, or the ref is already seeded.
+ * its raw lines verbatim (never parsed and re-serialized, so exact bytes/order are preserved),
+ * then retires the seed (see `retireSeed`) as its final, guarded act — a seed left tracked would
+ * travel to every clone and shadow the (never-fetched) ref there. A no-op on the seeding half
+ * (never throws) when there is nothing to seed from, or the ref is already seeded; the retirement
+ * half still runs either way, so a pre-fix project (ref seeded, seed left behind) is repaired by
+ * simply re-running migrate.
  */
 export function migrate(root: string): MigrateResult {
-	if (!isGitWorkTree(root)) return { migrated: false, reason: 'not a git work-tree', count: 0 }
+	if (!isGitWorkTree(root)) {
+		return {
+			migrated: false,
+			reason: 'not a git work-tree',
+			count: 0,
+			retired: false,
+			retiredReason: 'not a git work-tree',
+		}
+	}
+	let migrated = false
+	let reason: string
+	let count: number
 	if (orphanRefExists(root)) {
-		return { migrated: false, reason: 'orphan ref already seeded', count: readOrphanLines(root).length }
+		reason = 'orphan ref already seeded'
+		count = readOrphanLines(root).length
+	} else {
+		const rawLines = readInTreeLines(root)
+		if (rawLines.length === 0) {
+			return {
+				migrated: false,
+				reason: 'no in-tree store to seed from',
+				count: 0,
+				retired: false,
+				retiredReason: 'no in-tree seed remains to retire',
+			}
+		}
+		commitOrphan(root, rawLines, null)
+		migrated = true
+		reason = 'seeded orphan ref from in-tree store'
+		count = rawLines.length
+	}
+	const { retired, retiredReason } = retireSeed(root)
+	return { migrated, reason, count, retired, retiredReason }
+}
+
+// ── sync — the one deliberate step that carries the orphan ref to/from a shared remote ──
+// refs/sdd/* sits outside refs/heads/*, which git's default refspec is the only thing it copies,
+// so the ref is shared by every WORKTREE of one clone and travels no further on its own. `sync`
+// names the ref explicitly on every command it runs — so it needs no git configuration and writes
+// none — and is fast-forward only in both directions: a diverged pair is refused, never merged.
+// See the node README's sync table for the exhaustive 7-case partition this function realizes.
+
+export interface SyncResult {
+	backend: StoreBackend
+	ok: boolean
+	action: 'no-op' | 'no-remote' | 'unreachable' | 'both-empty' | 'push' | 'collect' | 'agree' | 'refuse'
+	message: string
+	localHead: string | null
+	remoteHead: string | null
+}
+
+function refTransferSpec(refName: string): string {
+	return `${refName}:${refName}`
+}
+
+/** A remote NAME is configured at all (distinct from being reachable — see `remoteReachable`). */
+function remoteConfigured(root: string, remote: string): boolean {
+	try {
+		git(root, ['remote', 'get-url', remote])
+		return true
+	} catch {
+		return false
+	}
+}
+
+/** Whether the remote can actually be talked to right now. Deliberately checked SEPARATELY from
+ *  "does it have the ref" — `git ls-remote` reports an unreachable remote and an empty one the
+ *  same way, so establishing reachability first (and failing loudly when it cannot be) is the
+ *  only way to avoid conflating the two. */
+function remoteReachable(root: string, remote: string): boolean {
+	try {
+		git(root, ['ls-remote', remote])
+		return true
+	} catch {
+		return false
+	}
+}
+
+/** The remote's current orphan-ref tip, or null when the remote has no such ref (but IS
+ *  reachable — reachability is checked by the caller before this is ever consulted). */
+function remoteOrphanHead(root: string, remote: string): string | null {
+	const out = git(root, ['ls-remote', remote, ORPHAN_REF])
+	if (out === '') return null
+	const [hash] = out.split('\n')[0].split('\t')
+	return hash ?? null
+}
+
+function gitFetchOrphanRef(root: string, remote: string): void {
+	git(root, ['fetch', remote, refTransferSpec(ORPHAN_REF)])
+}
+
+function gitPushOrphanRef(root: string, remote: string): void {
+	git(root, ['push', remote, refTransferSpec(ORPHAN_REF)])
+}
+
+function isAncestor(root: string, ancestor: string, descendant: string): boolean {
+	try {
+		execFileSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], { cwd: root })
+		return true
+	} catch {
+		return false
+	}
+}
+
+/**
+ * syncStore — carries the orphan ref between this clone and `remote`, fast-forward only. Two
+ * prechecks run first, in this exact order: (1) backend — under the in-tree backend, sync is a
+ * no-op that reports the active backend, even when the remote is unreachable (an in-tree project
+ * must not fail merely for being offline); (2) reachability — an unreachable remote, or no remote
+ * configured at all, is a loud non-zero failure, never reported as "no list there". Only once both
+ * are settled does the 7-case partition of (local ref, remote ref) apply — see the README's sync
+ * table. Writes no git configuration, ever; never uses the forced (`+`-prefixed) refspec form.
+ */
+export function syncStore(root: string, remote = 'origin'): SyncResult {
+	const backend = resolveBackend(root)
+	if (backend !== 'orphan-ref') {
+		return {
+			backend,
+			ok: true,
+			action: 'no-op',
+			message: `the ${backend} backend is in use; sync only carries the shared orphan ref, so this is a no-op`,
+			localHead: null,
+			remoteHead: null,
+		}
+	}
+	if (!remoteConfigured(root, remote)) {
+		return {
+			backend,
+			ok: false,
+			action: 'no-remote',
+			message: `no remote '${remote}' is configured to reach`,
+			localHead: orphanHead(root),
+			remoteHead: null,
+		}
+	}
+	if (!remoteReachable(root, remote)) {
+		return {
+			backend,
+			ok: false,
+			action: 'unreachable',
+			message: `could not reach remote '${remote}'`,
+			localHead: orphanHead(root),
+			remoteHead: null,
+		}
+	}
+
+	const localHead = orphanHead(root)
+	const remoteHead = remoteOrphanHead(root, remote)
+
+	if (localHead === null && remoteHead === null) {
+		return {
+			backend,
+			ok: true,
+			action: 'both-empty',
+			message: 'neither side holds a store ref',
+			localHead: null,
+			remoteHead: null,
+		}
+	}
+	if (localHead !== null && remoteHead === null) {
+		gitPushOrphanRef(root, remote)
+		return {
+			backend,
+			ok: true,
+			action: 'push',
+			message: 'published the local-only store ref to the remote',
+			localHead,
+			remoteHead: localHead,
+		}
+	}
+	if (localHead === null && remoteHead !== null) {
+		gitFetchOrphanRef(root, remote)
+		return {
+			backend,
+			ok: true,
+			action: 'collect',
+			message: 'collected the remote store ref',
+			localHead: remoteHead,
+			remoteHead,
+		}
+	}
+	// Both present.
+	if (localHead === remoteHead) {
+		return {
+			backend,
+			ok: true,
+			action: 'agree',
+			message: 'the store refs already agree',
+			localHead,
+			remoteHead,
+		}
+	}
+
+	// Both sides hold a ref and they differ, so which way (if either) this fast-forwards is an
+	// ancestry question — and answering it needs the remote's tip OBJECT in this clone's object
+	// database. A DESTINATION-LESS fetch brings exactly that and writes no ref: nothing to clean up
+	// afterwards, nothing left behind by a crashed run, and no fixed ref name for a concurrent sync
+	// to collide on. The tip HASH is already in hand from `ls-remote` above, so nothing reads
+	// FETCH_HEAD either. Still the plain, non-forced refspec: it names one ref and cannot overwrite.
+	git(root, ['fetch', remote, ORPHAN_REF])
+	if (isAncestor(root, localHead as string, remoteHead as string)) {
+		// The local ref is an ancestor of the remote's — the remote is ahead; fast-forward local.
+		gitFetchOrphanRef(root, remote)
+		return {
+			backend,
+			ok: true,
+			action: 'collect',
+			message: 'fast-forwarded the local store ref to the remote',
+			localHead: remoteHead,
+			remoteHead,
+		}
+	}
+	if (isAncestor(root, remoteHead as string, localHead as string)) {
+		// The remote's ref is an ancestor of the local's — this clone is ahead; publish.
+		gitPushOrphanRef(root, remote)
+		return {
+			backend,
+			ok: true,
+			action: 'push',
+			message: 'published the ahead store ref to the remote',
+			localHead,
+			remoteHead: localHead,
+		}
+	}
+	return {
+		backend,
+		ok: false,
+		action: 'refuse',
+		message: `refused: the store refs have diverged (local ${localHead}, remote ${remoteHead}) — see the node README's "Getting out of a refusal"`,
+		localHead,
+		remoteHead,
 	}
-	const rawLines = readInTreeLines(root)
-	if (rawLines.length === 0) return { migrated: false, reason: 'no in-tree store to seed from', count: 0 }
-	commitOrphan(root, rawLines, null)
-	return { migrated: true, reason: 'seeded orphan ref from in-tree store', count: rawLines.length }
 }
 
 /** Append a proposed RAW/parent-child/discovered-from edge through the write-time cycle guard;
@@ -657,6 +1111,15 @@ export function appendEdgeChecked(
 	return decision
 }
 
+/** Append a node event through the write-time barrier guards (INV-1/INV-2/INV-3); only appends
+ *  when the guard accepts. */
+export function appendNodeChecked(root: string, event: NodeEvent): EdgeDecision {
+	const graph = fold(readEvents(root))
+	const decision = proposeNode(graph, event)
+	if (decision.accepted) appendEvent(root, event)
+	return decision
+}
+
 // ── Render (TOON — the token-efficient tabular form the repo's other sdd engines emit) ──
 
 function toonQuote(v: string): string {
@@ -680,6 +1143,17 @@ export function renderCyclesToon(items: RepairItem[]): string {
 	return [header, ...rows].join('\n')
 }
 
+export function renderSyncToon(result: SyncResult): string {
+	return [
+		`backend: ${result.backend}`,
+		`action: ${result.action}`,
+		`ok: ${result.ok}`,
+		`message: ${result.message}`,
+		`localHead: ${result.localHead ?? ''}`,
+		`remoteHead: ${result.remoteHead ?? ''}`,
+	].join('\n')
+}
+
 export function renderOperationToon(id: string, check: OperationCheck): string {
 	return [
 		`operation: ${id}`,
@@ -736,7 +1210,14 @@ function runAppendNode(rest: string[], root: string): number {
 	if (briefPointer !== undefined) event.briefPointer = briefPointer
 	const capstone = flag(rest, '--capstone')
 	if (capstone !== undefined) event.capstone = capstone
-	appendEvent(root, event)
+	const project = flag(rest, '--project')
+	if (project !== undefined) event.project = project
+	if (hasFlag(rest, '--barrier')) event.barrier = true
+	const decision = appendNodeChecked(root, event)
+	if (!decision.accepted) {
+		process.stderr.write(`mission-graph append node: rejected — ${decision.reason}\n`)
+		return 1
+	}
 	process.stdout.write(`mission-graph: appended node ${id}\n`)
 	return 0
 }
@@ -829,16 +1310,24 @@ export function main(argv: string[]): number {
 			`${
 				format === 'json'
 					? JSON.stringify(result, null, 2)
-					: `migrated: ${result.migrated}\nreason: ${result.reason}\ncount: ${result.count}`
+					: `migrated: ${result.migrated}\nreason: ${result.reason}\ncount: ${result.count}\nretired: ${result.retired}\nretiredReason: ${result.retiredReason}`
 			}\n`,
 		)
 		return result.reason === 'not a git work-tree' ? 1 : 0
 	}
+	if (cmd === 'sync') {
+		const remote = flag(rest, '--remote') ?? 'origin'
+		const result = syncStore(root, remote)
+		process.stdout.write(`${format === 'json' ? JSON.stringify(result, null, 2) : renderSyncToon(result)}\n`)
+		return result.ok ? 0 : 1
+	}
 
 	process.stderr.write(
-		'mission-graph: usage: ready | cycles | operation --id <id> | append <node|edge|tombstone> ... | migrate\n',
+		'mission-graph: usage: ready | cycles | operation --id <id> | append <node|edge|tombstone> ... | migrate | sync [--remote <name>]\n',
 	)
 	return 1
 }
 
-if (import.meta.main) process.exit(main(process.argv.slice(2)))
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/oracle-spec-governance/README.md

@@ -4,7 +4,10 @@ This is an internal SDD governance about scope and the kill-or-ship call at the
 
 Before a capability's spec is approved, someone has to ask the uncomfortable questions: is this one
 thing or two things glued together? Is it worth building at all? Does every scenario in its suite
-actually belong to it? This governance is that question list — the **Oracle** bar. It judges the
+actually belong to it? Are the **actors enumerated**, and does that enumeration close both ways — no
+actor without a use case, no use case without a listed actor? Is every element the capability
+**exposes** bought by a use case, or unbought scope to cut? This governance is that question list —
+the **Oracle** bar. It judges the
 **capability itself**, read from its spec and suite together — not how the document is written,
 which is a different bar (`spec-format-governance`).
 
@@ -16,7 +19,9 @@ which is a different bar (`spec-format-governance`).
 | **Bounded, stated scope** | What is out of scope is named. A capability that keeps absorbing adjacent problems is scope creep — cut it back. |
 | **The node owns its decisions** | Every scenario tests a decision the node owns. A property co-owned across a seam — activation/routing, a sibling's behavior, harness wiring — is out of scope: relocate it to the node that owns it, or kill it. |
 | **Strict — non-decisions are killed** | An invariant that always holds is not acceptance and does not enter the suite. The one exception is a user `@pinned` scenario, kept whatever strict prunes. |
-| **Worth shipping, or kill** | The Why names a real problem and who feels it. If the value does not clear the cost of building, the verdict is kill. |
+| **Every surface element is paid for by a use case** | An element the capability exposes — a flag, an option, a parameter, a prop, an event — that **no use case needs** is unbought scope: cut it, or name the use case. This is the same kill-or-ship judgment one level down — the capability answers for its cost, and so does each thing it exposes. |
+| **The actors are enumerated, and the enumeration closes** | The Why names a real problem and **who feels it**, so the use cases are derived from a stated set of actors rather than from the interface. Graded **both ways**: an actor carrying no use case, and a use case whose actor is absent from the list, are each a hole. A goal that restates the mechanism is an unanswered Why, not a filled-in field. On a backfill, an enumeration drawn only from source covers the *served* use cases by construction. |
+| **Worth shipping, or kill** | If the value does not clear the cost of building, the verdict is kill. |
 | **Kill-or-revert** | A capability that passes every check but proves fatal goes back to Draft — surface the deal-breaker. |
 | **No premature commitment** | A decision that need not be made yet is deferred to the last responsible moment. |