@mnstry/atelier 0.2.0-alpha.5 → 0.2.0-alpha.8

package/skills/codex/atelier-guided-coauthor/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: atelier-guided-coauthor
+description: Guide an author through a selected packet in Codex, retaining private source-bound draft answers and resuming through the local Atelier coauthor CLI.
+---
+
+# Guided coauthor
+
+Use the installed `atelier coauthor` command, not a browser conversation service.
+The author chooses the packet and may read it normally without this workflow.
+
+Check the repository's instructions and local package first. Run
+`./node_modules/.bin/atelier coauthor --help` from the intended repository.
+Do not download another package if the command is unavailable. Explain that the
+installed version needs the coauthor capability and preserve ordinary packet review.
+
+## Start or resume
+
+- Require an existing Git workspace with ignored, untracked `.atelier-local/`.
+  Do not change global skills, sibling repositories, credentials or remote access.
+- Read the selected packet. Use consumer-owned field ids and workspace-relative
+  source references. Compute SHA-256 over each source file's exact UTF-8 bytes.
+  Send a `start` request containing `config: {id, fields}`; each field has
+  `id` and `source: {ref, digest}`. Packet structure stays in the consumer.
+- Requests are JSON on stdin; responses are JSON. Use an ignored request file
+  when needed, not shell interpolation of the author's text. Read the returned
+  state and revision. `read` takes `sessionId` and resumes retained history.
+- Ask one useful question at a time. Record the author's exact answer with an
+  `answer` event; events carry a unique `id`, `expectedRevision` and `type`.
+  Do not infer an answer or approval from silence.
+- If proposing edited wording, use `propose` and show the change. Wait for the
+  author's explicit confirmation before `confirm`. `reject` restores the
+  original. Even apparently stylistic rewrites need confirmation.
+- Send `save` only for the agreed draft. Say “saved as a private draft” only
+  after the command returns a saved receipt. The source packet is never edited.
+  `continueAfterSave: true` on an answer retains the author's advance intent;
+  otherwise `advance` is explicit.
+- `pause` and `resume` preserve the current phase. On restart, a `saving`
+  state may use `recover` to reconcile the pending private write. A
+  `recovery` state requires explicit `retry`, with one retry available.
+  Stop retrying when exhausted and retain all artifacts for inspection.
+
+## Boundaries
+
+Never submit store-owned receipt/failure events or fabricate persistence evidence.
+A stale source or revision is a visible conflict, not permission to overwrite it.
+Keep the old history and obtain a newly bound session for revised sources.
+Saved answers are proposals for later owner review, not publication, canonical
+acceptance, guide access, or a completed packet. No saved-answer undo is provided;
+do not erase history to simulate it. Summarize unresolved questions for the meeting.

package/skills/codex/atelier-guided-upgrade/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: atelier-guided-upgrade
+description: Prepare and explain an Atelier package upgrade in an isolated candidate, retain the owner decision, and apply only the approved effects. Use for owners asking to update an existing Atelier.
+---
+
+# Guided Atelier upgrade
+
+The default outcome is a reviewable candidate and an owner decision. Preserve the
+owner's actual request and existing scoped authority; no per-command approval
+loop is needed for actions already authorized. Preparation alone never authorizes
+changing the working installation, merging, publishing or restarting a service.
+
+## Establish the source and workspace
+
+Read the selected repository's instructions and upgrade procedure. Identify its
+actual installed scoped package, package-manager lock, Atelier lock, Git state,
+project roots, packs, overlays and running-service ownership. Resolve the package
+from that workspace (including a parent install); never use global Atelier,
+unscoped registry fallback or the first sibling checkout found on disk.
+Read `docs/guided-upgrades.md` and `docs/exact-upgrades.md` from the selected
+installed package when present. If an old install lacks this skill or commands,
+use the owner-selected new package's documentation only after verifying its
+source. Repository instructions and owner authority still govern.
+
+Select an exact release through a source already trusted by the owner. Record
+version, source commit when verified, artifact URL/integrity and the dependency
+lock. Mutable dist-tags are discovery hints, not final pins. A declaration in a
+lock or a digest supplied beside a download does not authenticate a publisher.
+An unpublished candidate must be labeled as such; use it only in an expressly
+selected rehearsal. Never invent a release or replace a pinned install with main.
+
+## Prepare without disturbing authoring
+
+Use a separate candidate with an identified base. Preserve dirty source and
+private answers; do not stash, reset, clean, stop services or commit another
+writer's edits to create eligibility. If using a snapshot of current edits,
+record and recheck its exact manifest; it is a snapshot, not an adopted commit.
+Ignored answers, browser storage and runtime credentials are not in a Git clone.
+Record that gap without importing them into a public report or projection.
+
+Stage the selected package using the owner's package manager and lock procedure,
+with lifecycle scripts disabled; investigate any required scripts before execution.
+Verify the resolved identity and inventory before running its commands. Inspect
+migration/compatibility effects before rewriting the old Atelier lock. Retain the
+old lock and all lineage. Keep installation changes distinct from generated files.
+
+Check exact-plan eligibility: Linux/macOS, one managed repository at `.`, config
+and workspace at its root, linked candidate worktree, clean state and supported
+Git settings. Packs, overlays and other unsupported participants require the
+repository's explicit operator procedure. Do not broaden graph roots, remove
+policies or disable filters/hooks to force eligibility. Never silently fall back
+to legacy `upgrade --apply`; it has different guarantees.
+
+For an eligible candidate, prepare `upgrade plan --save`, then use
+`upgrade explain --plan SAVED_PLAN_PATH` (JSON) and `--format markdown` (owner
+view). Invoke the verified installed binary with the explicit project path.
+Inspect `bindingsCurrent` and blockers even when the explanation exits zero.
+Keep source/pin/policy installation commits and the saved projection plan separate.
+For an operator procedure, retain an exact before/after file manifest and named
+commands instead; do not call it an exact-plan transaction or invent its digest.
+
+## Explain and retain consent
+
+Present the local benefit, exact target, changed files, preserved customizations,
+checks, known limits, recovery coverage and proposed effects. Show installation,
+local commit, merge, publication and activation separately. Ask one concrete
+question covering the effects that still need authority. A permission to prepare
+or a generic earlier “go” does not approve a newly introduced material effect.
+A prior explicit approval of this same current plan and effects remains valid.
+
+Retain a new decision record in ignored, untracked
+`.atelier-local/guided-upgrades/` (or a private sibling evidence directory):
+`kind: owner-decision`, report and plan/manifest SHA-256, candidate base, target
+identity, exact owner words, conversation reference, observation time, decision
+(approve/defer/decline), allowed effects, and
+`humanApprovalAuthenticated: false`, `recordedBy: agent`.
+Do not invent identity, words, references or approvals; missing provenance is a
+reported gap. This is an agent-attested record, not an authenticated signature or
+an execution grant. Keep existing records immutable. Silence conveys no consent.
+
+## Apply, validate and close
+
+After actual approval, use the saved path and exact confirmation digest literally.
+Recheck bindings; changed or expired plans require a fresh explanation and any
+newly necessary decision. A consumed plan is inspected, never replayed.
+Run the repository's documented acceptance checks and inspect the actual diff.
+Only a verified terminal transaction receipt means a candidate commit completed.
+Honor existing hooks and keep source/answer files within their ownership boundary.
+An operator procedure has its own validation evidence, not a transaction receipt.
+
+Continue authorized merge/activation steps only when included in the owner's
+scope. Report prepared, installed-in-candidate, committed, merged and running as
+separate observed states. A local preview passing is not recipient acceptance.
+On failure, preserve the candidate, backups and receipts; explain what changed
+and the next safe action. Recovery inspection does not automatically restore
+files or reset Git. Do not publish source, restart an existing service or advance
+an author's workflow phase merely because upgrade checks passed.

package/skills/codex/atelier-open/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: atelier-open
+description: Open the local Atelier preview in the current client when asked to show the portal or current page.
+---
+
 # Open the Atelier
 
 Use this skill when someone says "open the atelier", "pull up the atelier",

package/skills/codex/atelier-skill-steward/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: atelier-skill-steward
+description: Audit, create, improve, reconcile, retire, or update an Atelier-backed agent skill catalog using evidence thresholds, behavioral checks, and reversible managed projections.
+---
+
+# Atelier skill steward
+
+Use this skill when a repository should maintain its agent skills as a coherent,
+self-improving catalog. Do not use it to turn a one-off preference into a skill,
+capture prompts or transcripts, or grant a skill new authority implicitly.
+
+## Route the work
+
+- Audit the current catalog with `atelier skills audit --json`.
+- Record only a content-free signal with `atelier skills observe`; use a stable
+  workflow key, enumerated signal, optional skill name, and outcome. Never put a
+  summary, prompt, source excerpt, person, client, or private method in the key.
+- Find evidence-thresholded work with `atelier skills candidates --json`.
+- Create or improve an authored skill only when the candidate evidence and the
+  current task establish a repeatable input, workflow, and success condition.
+- Update a repo-scoped deployed catalog with `atelier skills sync`. Review the
+  plan, then repeat its exact digest with `--apply --confirm`. Never manufacture
+  confirmation before inspecting blockers and actions.
+
+## Authoring boundary
+
+Keep each skill focused. Give `SKILL.md` lowercase kebab-case `name` and a
+discriminating `description`; put only decision-changing guidance in the body.
+Add scripts or references only when deterministic reuse or progressive
+disclosure justifies them. Test direct triggers, indirect triggers, incomplete
+inputs, non-triggers, and risky edge cases.
+
+In the public Atelier repository, read `AGENTS.md`, `CONTRIBUTING.md`, and
+`docs/release-engineering.md` before editing. Re-derive private lessons as
+generic invariants with invented fixtures. Keep Codex and Claude bundles
+byte-identical and run the repository disclosure and release gates required by
+those documents.
+
+## Promotion policy
+
+An instruction-only change that retains the same tools, data boundary, and
+external authority may advance after its behavioral checks and catalog audit
+pass. New scripts, tool dependencies, network access, filesystem scope,
+external messages, spending, destructive operations, credential handling, or
+audience changes require explicit human authorization immediately before that
+authority is introduced.
+
+Do not treat an audit pass as proof of behavioral quality. Compare the candidate
+against representative positive and negative requests. Reject it when it only
+memorizes one incident, broadens its trigger, weakens a refusal, or cannot name
+observable improvement.
+
+## Retirement and updates
+
+Remove obsolete skills from active discovery only after checking dependents and
+supersession. Preserve recovery through Git or the sync quarantine; never
+permanently delete a managed deployed bundle during sync. A locally drifted or
+unmanaged target is a blocker, not permission to overwrite it.
+
+The steward has no model provider, telemetry, send path, browser apply endpoint,
+or hidden source-mutation authority. Scheduling may invoke this workflow, but a
+schedule does not widen its permissions or lower its evidence gates.

package/skills/codex/mnstry-readiness/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: mnstry-readiness
+description: Prepare or review Atelier readiness outputs for a project workspace using its readiness protocols.
+---
+
 # MNSTRY Readiness
 
 Use this skill when preparing or reviewing MNSTRY Atelier readiness outputs for

package/src/access/preview-enforcer.mjs

@@ -0,0 +1,84 @@
+import { parseRequest, parseBoundedJSON, need, isRef, isDigest, canonical, deepFreeze, MODES } from '../composition/wire.mjs';
+import { digestBytes } from '../composition/registry.mjs';
+
+const messages = Object.freeze({ loading: 'Checking access.', ready: 'Preview ready.', unauthenticated: 'Sign in to preview.',
+  forbidden: 'Preview is not permitted.', expired: 'Session expired.', unavailable: 'Preview unavailable.', stale: 'Preview changed. Refresh to continue.' });
+export class PreviewRefusal extends Error {
+  constructor(state) { super('Preview refused'); need(Object.hasOwn(messages, state) && !['ready', 'loading'].includes(state)); this.state = state; }
+}
+function principal(p) { need(p && isRef(p.issuer) && isRef(p.subject) && ['human', 'agent', 'service', 'local-owner'].includes(p.kind)); }
+function sessionCheck(s, now) {
+  need(s && Number.isSafeInteger(s.generation) && s.generation >= 0 && Number.isFinite(s.expiresAt));
+  for (const k of ['sessionRef', 'workspaceRef', 'audienceRef', 'policyRevision']) need(isRef(s[k]));
+  need(s.tenantRef === null || isRef(s.tenantRef));
+  // This prototype deliberately cannot admit production or implicit public access.
+  need(s.plane === 'preview');
+  if (!s.principal) throw new PreviewRefusal('unauthenticated');
+  principal(s.principal); principal(s.representedPrincipal);
+  if (s.expiresAt <= now) throw new PreviewRefusal('expired');
+}
+function checkDelegation(s, request, target, now) {
+  const d = s.delegation;
+  if (!d) {
+    need(s.principal.kind !== 'agent' && canonical(s.principal) === canonical(s.representedPrincipal)); return;
+  }
+  need(s.principal.kind === 'agent' && d.active === true && d.redelegationAllowed === false && isRef(d.ref) && isRef(d.revision));
+  need(Number.isFinite(d.expiresAt) && d.expiresAt > now && d.expiresAt <= s.expiresAt);
+  need(canonical(d.actor) === canonical(s.principal) && canonical(d.representedPrincipal) === canonical(s.representedPrincipal));
+  for (const key of ['sessionRef', 'generation', 'tenantRef', 'workspaceRef', 'audienceRef', 'plane']) need(d[key] === s[key]);
+  for (const key of ['modes', 'operationRefs', 'resourceRefs']) need(Array.isArray(d[key]) && d[key].length <= 64 && new Set(d[key]).size === d[key].length);
+  need(d.modes.every(m => MODES.includes(m)) && d.operationRefs.every(isRef) && d.resourceRefs.every(isRef));
+  if (!d.modes.includes(request.mode) || !d.operationRefs.includes(target.operationRef) || !d.resourceRefs.includes(target.resourceRef)) throw new PreviewRefusal('forbidden');
+}
+export function createPreviewEnforcer(ports, { now = Date.now } = {}) {
+  for (const key of ['authenticate', 'resolveTarget', 'authorize', 'revalidate', 'perform', 'projectResult', 'audit']) need(typeof ports?.[key] === 'function');
+  return Object.freeze({ async handle(channel, bytes, signal) {
+    let request, binding, phase = 'parse', performed = false;
+    const generation = Number.isSafeInteger(channel?.generation) && channel.generation >= 0 ? channel.generation : 0;
+    const state = (name, projectedData) => deepFreeze({ state: {
+      schema: 'atelier-preview-state/proposal-v1', requestId: request?.requestId || 'invalid', placementId: request?.placementId || 'invalid',
+      sourceDigest: request?.sourceDigest || '0'.repeat(64), mode: request?.mode || 'synthetic', state: name,
+      sessionGeneration: generation, publicMessage: messages[name],
+    }, ...(name === 'ready' ? { projectedData } : {}) });
+    const live = () => { if (signal?.aborted) throw new PreviewRefusal('stale'); if (binding && binding.expiresAt <= now()) throw new PreviewRefusal('expired'); };
+    const fresh = async () => { live(); if (await ports.revalidate(binding, signal) !== true) throw new PreviewRefusal('stale'); live(); };
+    const audit = (stage, outcome) => ports.audit(deepFreeze({ binding, phase: stage, outcome }));
+    try {
+      request = deepFreeze(parseRequest(bytes)); live(); phase = 'authenticate';
+      const s = deepFreeze(structuredClone(await ports.authenticate(channel, signal)));
+      sessionCheck(s, now()); live(); phase = 'resolve';
+      const t = deepFreeze(structuredClone(await ports.resolveTarget(s, request, signal)));
+      for (const key of ['resourceRef', 'operationRef', 'serviceRef', 'sourceRef', 'placementRef', 'registryRevision']) need(isRef(t?.[key]));
+      for (const key of ['sourceDigest', 'descriptorDigest', 'rendererDigest']) need(isDigest(t[key]));
+      need(t.sourceDigest === request.sourceDigest && t.placementRef === request.placementId);
+      checkDelegation(s, request, t, now());
+      binding = deepFreeze({ sessionRef: s.sessionRef, generation: s.generation, principal: s.principal, representedPrincipal: s.representedPrincipal,
+        delegationRef: s.delegation?.ref || null, delegationRevision: s.delegation?.revision || null,
+        tenantRef: s.tenantRef, workspaceRef: s.workspaceRef, plane: s.plane, mode: request.mode, audienceRef: s.audienceRef,
+        target: t, requestRef: request.requestId, requestDigest: digestBytes(canonical(request)), policyRevision: s.policyRevision,
+        expiresAt: Math.min(s.expiresAt, s.delegation?.expiresAt ?? Infinity) });
+      phase = 'authorize'; live(); await audit('requested', 'pending');
+      const decision = deepFreeze(structuredClone(await ports.authorize(binding, signal))); live();
+      need(canonical(decision?.binding) === canonical(binding));
+      if (decision.outcome !== 'allow') throw new PreviewRefusal(decision.outcome === 'deny' ? 'forbidden' : decision.outcome === 'reauth-required' ? 'expired' : 'unavailable');
+      await audit('authorized', 'allowed'); await fresh(); phase = 'perform'; performed = true;
+      const raw = await ports.perform(s, request, decision, signal);
+      await fresh(); phase = 'project';
+      const projected = await ports.projectResult(binding, raw, signal);
+      // Trusted projector owns the field allowlist. Root still enforces JSON,
+      // byte/depth bounds and cannot accidentally serialize result metadata.
+      const data = parseBoundedJSON(JSON.stringify(projected));
+      // Preparation is not a browser delivery acknowledgement. Keep the last
+      // asynchronous audit inside the revalidation boundary before returning.
+      await fresh(); await audit('settled', 'prepared'); await fresh();
+      return state('ready', data);
+    } catch (error) {
+      const name = error instanceof PreviewRefusal ? error.state : 'unavailable';
+      if (binding) {
+        try { await audit('settled', performed ? 'uncertain' : name === 'stale' ? 'stale' : phase === 'authorize' ? 'denied' : 'failed'); }
+        catch { /* No output or automatic effect retry if audit storage fails. */ }
+      }
+      return state(name);
+    }
+  } });
+}

package/src/boundary/content-rules.mjs

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
 import { matchesPathPattern, normalizeRelPath } from '../project/path-match.mjs'
+import { sanitizedGitEnvironment } from '../runtime/git-adapter.mjs'
 
 export const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904'
 export const ZERO_SHA_RE = /^0{40,}$/
@@ -252,12 +253,13 @@ export function parsePushRefInput(text) {
 
 export function gitOutputResult(repoRoot, args, {
   encoding = 'utf8',
+  gitExecutable = 'git',
   maxBuffer = DIFF_RESULT_MAX_BYTES,
   runner = spawnSync,
 } = {}) {
   let result
   try {
-    result = runner('git', ['-C', repoRoot, ...args], { encoding, maxBuffer })
+    result = runner(gitExecutable, ['-C', repoRoot, ...args], { encoding, maxBuffer, env: sanitizedGitEnvironment() })
   } catch (error) {
     return { ok: false, code: 'git-command-failed', error: error instanceof Error ? error.message : String(error), stdout: null }
   }
@@ -355,7 +357,7 @@ function scanBinaryBuffer({ buffer, filePath, rules, exceptions, repo }) {
   return findings
 }
 
-function readBinaryChanges({ repoRoot, revision, diff, rules, exceptions, repo }) {
+function readBinaryChanges({ repoRoot, revision, diff, rules, exceptions, repo, gitExecutable, gitRunner }) {
   const findings = []
   const diagnostics = []
   let totalBytes = 0
@@ -363,7 +365,9 @@ function readBinaryChanges({ repoRoot, revision, diff, rules, exceptions, repo }
     const spec = revision === ':' ? `:${filePath}` : `${revision}:${filePath}`
     const result = gitOutputResult(repoRoot, ['show', spec], {
       encoding: 'buffer',
+      gitExecutable,
       maxBuffer: BINARY_FILE_MAX_BYTES + 1,
+      runner: gitRunner,
     })
     if (!result.ok) {
       diagnostics.push(incompleteDiagnostic({
@@ -403,9 +407,10 @@ export function scanStagedRepository({
   rules = DEFAULT_CONTENT_RULES,
   exceptions = [],
   repo = null,
+  gitExecutable = 'git',
   gitRunner = spawnSync,
 } = {}) {
-  const acquired = stagedDiff(repoRoot, { runner: gitRunner })
+  const acquired = stagedDiff(repoRoot, { gitExecutable, runner: gitRunner })
   if (!acquired.ok) {
     return {
       findings: [],
@@ -414,7 +419,7 @@ export function scanStagedRepository({
     }
   }
   const files = parseAddedContent(acquired.diff)
-  const binary = readBinaryChanges({ repoRoot, revision: ':', diff: acquired.diff, rules, exceptions, repo })
+  const binary = readBinaryChanges({ repoRoot, revision: ':', diff: acquired.diff, rules, exceptions, repo, gitExecutable, gitRunner })
   return {
     findings: [...scanAddedContent({ files, rules, exceptions, repo }), ...binary.findings],
     diagnostics: binary.diagnostics,

package/src/boundary/policy.mjs

@@ -4,6 +4,7 @@ import path from 'node:path'
 import { buildGraph } from '../graph/graph.mjs'
 import { commandProject, firstString, parseArgs, readJson, resolvePathValue, writeJson } from '../project/config.mjs'
 import { matchesPathPattern } from '../project/path-match.mjs'
+import { sanitizedGitEnvironment } from '../runtime/git-adapter.mjs'
 import {
   CHECK_AGGREGATE_MAX_BYTES,
   parsePushRefInput,
@@ -145,7 +146,7 @@ export function validateBoundaryPolicy(policy, project = null) {
     const declaredRepos = isObject(repos) ? repos : {}
     for (const [index, exception] of policy.contentRuleExceptions.entries()) {
       const name = firstString(exception?.repo)
-      if (name && Object.keys(declaredRepos).length && !declaredRepos[name]) {
+      if (name && Object.keys(declaredRepos).length && !Object.hasOwn(declaredRepos, name)) {
         errors.push(`contentRuleExceptions[${index}].repo ${name} is not declared in repos`)
       }
     }
@@ -162,7 +163,7 @@ export function validateBoundaryPolicy(policy, project = null) {
     }
     if (!firstString(actor.privateDomainRepo)) errors.push(`actors.${actorId}.privateDomainRepo is required`)
     if (firstString(actor.privateDomainRepo) && isObject(repos)) {
-      const privateRepo = repos[actor.privateDomainRepo]
+      const privateRepo = Object.hasOwn(repos, actor.privateDomainRepo) ? repos[actor.privateDomainRepo] : null
       if (!privateRepo) {
         errors.push(`actors.${actorId}.privateDomainRepo ${actor.privateDomainRepo} is not declared in repos`)
       } else if (privateRepo.kind !== 'private_domain') {
@@ -187,7 +188,7 @@ export function validateBoundaryPolicy(policy, project = null) {
     errors.push(...validAudienceList(repo.forbiddenAudiences, `repos.${repoName}.forbiddenAudiences`))
     if (repo.kind === 'private_domain') {
       if (!firstString(repo.ownerActor)) errors.push(`repos.${repoName}.ownerActor is required for private_domain repos`)
-      if (repo.ownerActor && isObject(actors) && !actors[repo.ownerActor]) errors.push(`repos.${repoName}.ownerActor ${repo.ownerActor} is not declared`)
+      if (repo.ownerActor && isObject(actors) && !Object.hasOwn(actors, repo.ownerActor)) errors.push(`repos.${repoName}.ownerActor ${repo.ownerActor} is not declared`)
     }
   }
 
@@ -196,44 +197,69 @@ export function validateBoundaryPolicy(policy, project = null) {
       if (repo.external) {
         // Declaring a boundary for a repo nobody manages is the confusion the
         // external kind exists to remove.
-        if (repos[repo.name]) errors.push(`policy repos.${repo.name} must not be declared; it is an external (unmanaged) repo`)
+        if (Object.hasOwn(repos, repo.name)) errors.push(`policy repos.${repo.name} must not be declared; it is an external (unmanaged) repo`)
         continue
       }
-      if (!repos[repo.name]) errors.push(`policy repos.${repo.name} must be declared`)
+      if (!Object.hasOwn(repos, repo.name)) errors.push(`policy repos.${repo.name} must be declared`)
     }
   }
 
   return errors
 }
 
-export function resolveCurrentActor({ policy, project, actor = null, env = process.env } = {}) {
+function resolveExplicitActor({ policy, actor, env }) {
   const actors = policy?.actors ?? {}
-  const explicit = actor || env.MNSTRY_ATELIER_ACTOR || env.GITHUB_ACTOR
-  if (explicit && actors[explicit]) return { actorId: explicit, source: 'explicit' }
-  const gitEmails = gitEmailsForProject(project)
-  for (const [actorId, info] of Object.entries(actors)) {
-    const actorEmails = new Set(asArray(info.gitEmails).map((email) => email.toLowerCase()))
-    if (gitEmails.some((email) => actorEmails.has(email.toLowerCase()))) return { actorId, source: 'git-email', gitEmails }
+  const explicit = actor || env.MNSTRY_ATELIER_ACTOR
+  const unverified = (reason) => ({ actorId: null, source: 'unverified', reason })
+  if (actor && env.MNSTRY_ATELIER_ACTOR && actor !== env.MNSTRY_ATELIER_ACTOR) {
+    return unverified('conflicting-explicit-actors')
   }
-  const login = env.GITHUB_ACTOR || ghLogin()
+  if (explicit && !Object.hasOwn(actors, explicit)) return unverified('unknown-explicit-actor')
+  return explicit ? { actorId: explicit, source: 'explicit' } : null
+}
+
+export function resolveCurrentActor({ policy, project, actor = null, env = process.env, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = false } = {}) {
+  const actors = policy?.actors ?? {}
+  const explicit = resolveExplicitActor({ policy, actor, env })
+  if (explicit) return explicit
+  const unverified = (reason) => ({ actorId: null, source: 'unverified', reason })
+  // Without an explicit local selector, a platform login precedes Git metadata.
+  // It is platform attribution only; this function cannot authenticate its env.
+  const platformLogin = env.GITHUB_ACTOR
+  if (platformLogin) {
+    const matches = Object.entries(actors).filter(([, info]) =>
+      !String(info.githubLogin || '').endsWith('_GITHUB_LOGIN_PLACEHOLDER') &&
+      String(info.githubLogin || '').toLowerCase() === String(platformLogin).toLowerCase())
+    if (matches.length !== 1) return unverified(matches.length ? 'ambiguous-platform-actor' : 'unknown-platform-actor')
+    return { actorId: matches[0][0], source: 'github-login', githubLogin: platformLogin }
+  }
+  // Keep the legacy option accepted by the API, but history is never evidence
+  // of the person currently operating a checkout.
+  const gitEmails = gitEmailsForProject(project, { gitExecutable, env, allowHistoryActorResolution: false })
+  const matches = Object.entries(actors).filter(([, info]) => {
+    const actorEmails = new Set(asArray(info.gitEmails).map((email) => email.toLowerCase()))
+    return gitEmails.some((email) => actorEmails.has(email.toLowerCase()))
+  })
+  if (matches.length > 1) return unverified('ambiguous-git-actor')
+  if (matches.length === 1) return { actorId: matches[0][0], source: 'git-email', gitEmails }
+  const login = allowNetworkActorResolution ? ghLogin() : null
   if (login) {
-    for (const [actorId, info] of Object.entries(actors)) {
-      if (String(info.githubLogin || '').toLowerCase() === String(login).toLowerCase()) return { actorId, source: 'github-login', githubLogin: login }
-    }
+    const matches = Object.entries(actors).filter(([, info]) => !String(info.githubLogin || '').endsWith('_GITHUB_LOGIN_PLACEHOLDER') && String(info.githubLogin || '').toLowerCase() === String(login).toLowerCase())
+    if (matches.length !== 1) return unverified(matches.length ? 'ambiguous-platform-actor' : 'unknown-platform-actor')
+    return { actorId: matches[0][0], source: 'github-login', githubLogin: login }
   }
-  return { actorId: null, source: 'unverified', gitEmails, githubLogin: login || null }
+  return { actorId: null, source: 'unverified', gitEmails, githubLogin: null }
 }
 
-function gitEmailsForProject(project) {
+function gitEmailsForProject(project, { gitExecutable = 'git', env = process.env, allowHistoryActorResolution = false } = {}) {
   const roots = unique([project?.repoOpsRoot, project?.workspaceRoot, ...managedRepos(project).map((repo) => repo.path)])
   const emails = []
   for (const root of roots) {
     if (!root || !fs.existsSync(root)) continue
-    for (const args of [
-      ['config', 'user.email'],
-      ['log', '-1', '--format=%ae'],
-    ]) {
-      const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' })
+    const probes = [['config', 'user.email']]
+    if (allowHistoryActorResolution) probes.push(['log', '-1', '--format=%ae'])
+    for (const args of probes) {
+      const result = spawnSync(gitExecutable, ['-C', root, ...args], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
       if (result.status === 0 && result.stdout.trim()) emails.push(result.stdout.trim())
     }
   }
@@ -249,7 +275,7 @@ function ghLogin() {
 }
 
 function repoPolicy(policy, repoName) {
-  return policy?.repos?.[repoName] ?? null
+  return policy?.repos && Object.hasOwn(policy.repos, repoName) ? policy.repos[repoName] : null
 }
 
 function finding({ severity = 'error', code, message, repo = null, path: itemPath = null, node = null, details = {} }) {
@@ -280,15 +306,21 @@ function nodePlacementFindings({ node, policy }) {
   return findings
 }
 
-function actorFindings({ policy, project, actor }) {
+function actorFindings({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution, forceActorErrors }) {
   const findings = []
-  const current = resolveCurrentActor({ policy, project, actor })
-  const severity = severityFor(policy)
-  for (const [repoName, repo] of Object.entries(policy.repos ?? {})) {
-    if (repo.kind !== 'private_domain') continue
-    if (!repo.ownerActor) continue
+  const operatedRepos = new Set(managedRepos(project).map((repo) => repo.name))
+  const ownedRepos = Object.entries(policy.repos ?? {}).filter(([name, repo]) =>
+    operatedRepos.has(name) && repo?.kind === 'private_domain' && repo.ownerActor)
+  const explicit = resolveExplicitActor({ policy, actor, env: process.env })
+  if (explicit?.reason) return [finding({ severity: 'error', code: 'actor-resolution-refused', message: explicit.reason })]
+  // Shared-only work needs no derived identity and must not invoke Git or gh.
+  if (!ownedRepos.length) return findings
+  const current = explicit || resolveCurrentActor({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution })
+  const severity = forceActorErrors ? 'error' : severityFor(policy)
+  for (const [repoName, repo] of ownedRepos) {
     if (!current.actorId) {
-      findings.push(finding({ severity, code: 'private-domain-actor-unverified', repo: repoName, message: `${repoName}: could not verify local actor for private domain repo owned by ${repo.ownerActor}` }))
+      findings.push(finding({ severity, code: 'private-domain-actor-unverified', repo: repoName,
+        message: `${repoName}: could not verify local actor for private domain repo owned by ${repo.ownerActor}${current.reason ? ` (${current.reason})` : ''}` }))
     } else if (current.actorId !== repo.ownerActor) {
       findings.push(finding({ severity, code: 'private-domain-actor-mismatch', repo: repoName, message: `${repoName}: private domain repo is owned by ${repo.ownerActor}, but current actor is ${current.actorId}` }))
     }
@@ -296,11 +328,11 @@ function actorFindings({ policy, project, actor }) {
   return findings
 }
 
-export function stagedPathsForProject(project) {
+export function stagedPathsForProject(project, { gitExecutable = 'git' } = {}) {
   const paths = []
   for (const repo of managedRepos(project)) {
     if (!repo.path || !fs.existsSync(path.join(repo.path, '.git'))) continue
-    const result = spawnSync('git', ['-C', repo.path, 'diff', '--cached', '--name-only', '--diff-filter=ACMR'], { encoding: 'utf8' })
+    const result = spawnSync(gitExecutable, ['-C', repo.path, 'diff', '--cached', '--name-only', '--diff-filter=ACMR'], { encoding: 'utf8', env: sanitizedGitEnvironment() })
     if (result.status !== 0) continue
     for (const rel of result.stdout.split('\n').map((line) => line.trim()).filter(Boolean)) {
       paths.push({ repo: repo.name, repoRoot: repo.path, path: normalize(rel) })
@@ -394,7 +426,7 @@ export function semanticChangesInFile(file) {
   return changes
 }
 
-function semanticDiffFindings({ policy, project }) {
+function semanticDiffFindings({ policy, project, gitExecutable = 'git' }) {
   const findings = []
   const severity = 'error'
   for (const repo of managedRepos(project)) {
@@ -402,7 +434,7 @@ function semanticDiffFindings({ policy, project }) {
       findings.push(unscannableRepoFinding(repo, 'configured path is absent or is not a Git checkout'))
       continue
     }
-    const result = spawnSync('git', ['-C', repo.path, 'diff', '--cached', '--unified=0', '--', '*.md', '*.kg.json'], { encoding: 'utf8' })
+    const result = spawnSync(gitExecutable, ['-C', repo.path, 'diff', '--cached', '--unified=0', '--', '*.md', '*.kg.json'], { encoding: 'utf8', env: sanitizedGitEnvironment() })
     if (result.status !== 0) {
       findings.push(unscannableRepoFinding(repo, 'git diff --cached failed'))
       continue
@@ -430,7 +462,7 @@ function semanticDiffFindings({ policy, project }) {
   return findings
 }
 
-function stagedContentFindings({ policy, project }) {
+function stagedContentFindings({ policy, project, gitExecutable = 'git' }) {
   const rules = resolveContentRules(policy)
   const exceptions = asArray(policy?.contentRuleExceptions)
   const findings = []
@@ -440,7 +472,7 @@ function stagedContentFindings({ policy, project }) {
       findings.push(unscannableRepoFinding(repo, 'configured path is absent or is not a Git checkout'))
       continue
     }
-    const result = scanStagedRepository({ repoRoot: repo.path, rules, exceptions, repo: repo.name })
+    const result = scanStagedRepository({ repoRoot: repo.path, rules, exceptions, repo: repo.name, gitExecutable })
     findings.push(...result.findings, ...result.diagnostics)
     totalBytes += result.bytes
     if (totalBytes > CHECK_AGGREGATE_MAX_BYTES) {
@@ -603,7 +635,7 @@ function promotionFindings({ policy, project, graph }) {
   return findings
 }
 
-export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnly = false, actor = null } = {}) {
+export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnly = false, actor = null, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = false, forceActorErrors = false } = {}) {
   const validationErrors = validateBoundaryPolicy(policy, project)
   let graph = null
   const findings = validationErrors.map((message) => finding({ severity: 'error', code: 'boundary-policy-invalid', message }))
@@ -613,12 +645,12 @@ export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnl
     for (const node of graph.nodes ?? []) findings.push(...nodePlacementFindings({ node, policy }))
     findings.push(...promotionFindings({ policy, project, graph }))
   }
-  findings.push(...actorFindings({ policy, project, actor }))
+  findings.push(...actorFindings({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution, forceActorErrors }))
   if (staged) {
-    const stagedPaths = stagedPathsForProject(project)
+    const stagedPaths = stagedPathsForProject(project, { gitExecutable })
     findings.push(...forbiddenPathFindings({ policy, stagedPaths }))
-    findings.push(...semanticDiffFindings({ policy, project }))
-    findings.push(...stagedContentFindings({ policy, project }))
+    findings.push(...semanticDiffFindings({ policy, project, gitExecutable }))
+    findings.push(...stagedContentFindings({ policy, project, gitExecutable }))
   }
   const errors = findings.filter((item) => item.severity === 'error')
   const warnings = findings.filter((item) => item.severity !== 'error')