@mnstry/atelier 0.2.0-alpha.12 → 0.2.0-alpha.13

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

@@ -0,0 +1,40 @@
+---
+name: atelier-trackables
+description: Author, adopt, record, inspect or correct governed Trackables using shared definition and occurrence semantics; integrate existing domain writers without creating a separate coaching store.
+---
+
+# Governed Trackables
+
+Identify the existing domain writer, subject, purpose and exact private scope.
+Separate tracking lifecycle, domain fulfillment, occurrence result, evidence
+quality and attention. Recording a daily practice does not finish the practice;
+pausing tracking does not abandon a goal. Missing evidence is not zero or failure.
+
+Check the installed `atelier trackable` interface and supported profile before
+promising behavior. The reference profile supports daily recurring practice,
+one-off milestones and unscheduled qualitative observations. It does not provide
+arbitrary recurrence, quantitative metrics or a developmental score. Preserve
+native profiles and report unsupported mappings rather than converting meaning.
+
+Release and pin a validated definition. Preview through the same reducer that the
+runtime uses. Adopt an exact revision with an effective instant; do not silently
+change existing instances when authoring changes. Preserve timezone, local-day
+identity and the definition applicable to late evidence. Persist resolved
+occurrences for replay; do not recompute historical local days after a calendar
+update. A legacy export with `stateVerified: false` preserves raw history, not
+a usable reconstructed state. Restore compatible calendar rules before writes.
+
+Within the user's existing authority, use typed commands with request identity
+and expected revision. Preserve subject, recorder, source event and assistance
+separately. Retry the same command after a lost reply; do not create another
+completion. Reconcile manual and session reports of one occurrence. Corrections
+retain source history and cause affected fulfillment evidence to be reconsidered.
+
+Verify durable readback and refreshed presentation. Show unobserved, skipped,
+waived, partial and disputed states honestly. A proposed mutation is not saved.
+Companion can present the same view; Witness is optional and cannot maintain a
+second progress truth or infer independent ability from assisted completion.
+
+Use the local private store only as the standalone reference adapter. Product
+hosts retain authenticated persistence, evidence validation and access control.
+Do not implicitly export personal history, enable reminders or broaden observation.

package/src/architecture/catalog.mjs

@@ -0,0 +1,355 @@
+export function catalogDocument() {
+  return {
+  "schema": "atelier-architecture-catalog@v1",
+  "entries": [
+    {
+      "id": "inquiry",
+      "kind": "responsibility",
+      "label": "Inquiry",
+      "aliases": [],
+      "purpose": "Investigate uncertainty and establish what evidence supports.",
+      "implementation": [
+        "src/inquiry/index.mjs"
+      ]
+    },
+    {
+      "id": "knowledge-stewardship",
+      "kind": "responsibility",
+      "label": "Knowledge Stewardship",
+      "aliases": [],
+      "purpose": "Curate, govern, connect and maintain knowledge and its operational applicability.",
+      "implementation": [
+        "src/knowledge/index.mjs",
+        "src/intake/store.mjs",
+        "src/ingestion/store.mjs",
+        "src/knowledge/ingestion.mjs",
+        "src/ingestion/semantic.mjs",
+        "src/commands/knowledge.mjs",
+        "src/commands/knowledge-semantic.mjs",
+        "src/knowledge/semantic-operation.mjs",
+        "src/knowledge/plan.mjs",
+        "src/knowledge/context.mjs",
+        "src/knowledge/workspace.mjs",
+        "src/knowledge/sessions.mjs"
+      ]
+    },
+    {
+      "id": "practical-judgment",
+      "kind": "responsibility",
+      "label": "Practical Judgment",
+      "aliases": [
+        "Phronesis"
+      ],
+      "purpose": "Discern fitting action, cultivate practice and learn from consequences.",
+      "implementation": [
+        "src/learning/store.mjs",
+        "src/judgment/index.mjs",
+        "src/judgment/practice.mjs",
+        "src/judgment/practice-evaluation.mjs",
+        "src/capabilities/instructions.mjs"
+      ]
+    },
+    {
+      "id": "creation-delivery",
+      "kind": "responsibility",
+      "label": "Creation and Delivery",
+      "aliases": [],
+      "purpose": "Design, implement, verify and deliver intended changes.",
+      "implementation": [
+        "src/build/index.mjs"
+      ]
+    },
+    {
+      "id": "capability-stewardship",
+      "kind": "responsibility",
+      "label": "Capability Stewardship",
+      "aliases": [],
+      "purpose": "Compose, qualify, package, adopt, exercise and evolve reusable abilities.",
+      "implementation": [
+        "src/capabilities/index.mjs",
+        "src/skills/steward.mjs"
+      ]
+    },
+    {
+      "id": "reflection",
+      "kind": "responsibility",
+      "label": "Reflection",
+      "aliases": [],
+      "purpose": "Form revisable assessments of the person, work, interaction and system.",
+      "implementation": [
+        "src/reflection/index.mjs"
+      ]
+    },
+    {
+      "id": "interaction",
+      "kind": "responsibility",
+      "label": "Interaction",
+      "aliases": [],
+      "purpose": "Communicate, listen, pace, challenge and repair through the host conversation authority.",
+      "implementation": [
+        "src/interaction/index.mjs"
+      ]
+    },
+    {
+      "id": "coordination",
+      "kind": "responsibility",
+      "label": "Coordination",
+      "aliases": [],
+      "purpose": "Connect work, ownership, dependencies, delivery, recovery and outcomes.",
+      "implementation": [
+        "src/coordination/index.mjs",
+        "src/build/index.mjs"
+      ]
+    },
+    {
+      "id": "discovery",
+      "kind": "harness",
+      "label": "Discovery Harness",
+      "aliases": [
+        "Discovery Engine"
+      ],
+      "purpose": "Composes the named responsibility through the existing workflow.",
+      "implementation": [
+        "src/inquiry/index.mjs"
+      ]
+    },
+    {
+      "id": "research",
+      "kind": "harness",
+      "label": "Research Harness",
+      "aliases": [],
+      "purpose": "Composes the named responsibility through the existing workflow.",
+      "implementation": [
+        "src/inquiry/index.mjs"
+      ]
+    },
+    {
+      "id": "knowledge",
+      "kind": "harness",
+      "label": "Knowledge Harness",
+      "aliases": [],
+      "purpose": "Composes the named responsibility through the existing workflow.",
+      "implementation": [
+        "src/knowledge/index.mjs"
+      ]
+    },
+    {
+      "id": "build",
+      "kind": "harness",
+      "label": "Build Harness",
+      "aliases": [],
+      "purpose": "Composes the named responsibility through the existing workflow.",
+      "implementation": [
+        "src/build/index.mjs"
+      ]
+    },
+    {
+      "id": "capability-harness",
+      "kind": "harness",
+      "label": "Capability Harness",
+      "aliases": [
+        "Skills Harness"
+      ],
+      "purpose": "Composes the named responsibility through the existing workflow.",
+      "implementation": [
+        "src/capabilities/index.mjs"
+      ]
+    },
+    {
+      "id": "learning",
+      "kind": "harness",
+      "label": "Learning lifecycle",
+      "aliases": [],
+      "purpose": "Composes the named responsibility through the existing workflow.",
+      "implementation": [
+        "src/learning/store.mjs"
+      ]
+    },
+    {
+      "id": "ingestion",
+      "kind": "harness",
+      "label": "Ingestion workflow",
+      "aliases": [],
+      "purpose": "Composes the named responsibility through the existing workflow.",
+      "implementation": [
+        "src/ingestion/store.mjs"
+      ]
+    },
+    {
+      "id": "skill-steward",
+      "kind": "role",
+      "label": "Skill Steward",
+      "aliases": [],
+      "purpose": "Participation within a responsibility; does not create a separate authority.",
+      "implementation": [
+        "src/skills/steward.mjs"
+      ]
+    },
+    {
+      "id": "witness",
+      "kind": "role",
+      "label": "Witness",
+      "aliases": [],
+      "purpose": "Participation within a responsibility; does not create a separate authority.",
+      "implementation": []
+    },
+    {
+      "id": "companion",
+      "kind": "role",
+      "label": "Companion",
+      "aliases": [],
+      "purpose": "Participation within a responsibility; does not create a separate authority.",
+      "implementation": []
+    },
+    {
+      "id": "orthogonal-inquiry",
+      "kind": "method",
+      "label": "Orthogonal inquiry",
+      "aliases": [],
+      "purpose": "An optional method, selected for its fit to the purpose.",
+      "implementation": []
+    },
+    {
+      "id": "bayesian-assessment",
+      "kind": "method",
+      "label": "Bayesian assessment",
+      "aliases": [],
+      "purpose": "An optional method, selected for its fit to the purpose.",
+      "implementation": []
+    },
+    {
+      "id": "coaching",
+      "kind": "method",
+      "label": "Coaching",
+      "aliases": [],
+      "purpose": "An optional method, selected for its fit to the purpose.",
+      "implementation": []
+    },
+    {
+      "id": "trackable",
+      "kind": "record",
+      "label": "Trackable",
+      "aliases": [],
+      "purpose": "Domain composition of definition, instance, occurrences, evidence and qualified views.",
+      "implementation": [
+        "src/trackables/store.mjs"
+      ]
+    },
+    {
+      "id": "adr",
+      "kind": "record",
+      "label": "Architecture decision record",
+      "aliases": [],
+      "purpose": "Repository-owned decision identity and history; implementation and evidence currency are distinct.",
+      "implementation": []
+    },
+    {
+      "id": "govern-adoption",
+      "kind": "capability",
+      "label": "Govern capability adoption",
+      "aliases": [],
+      "purpose": "Independently adopt an exact reusable capability in a repository.",
+      "implementation": [
+        "src/capabilities/index.mjs"
+      ]
+    },
+    {
+      "id": "steward-skill",
+      "kind": "resource",
+      "label": "Steward operating skill",
+      "aliases": [],
+      "purpose": "A portable operating resource for the stewardship outcome.",
+      "implementation": [
+        "skills/codex/atelier-skill-steward/SKILL.md"
+      ]
+    },
+    {
+      "id": "codex-repository",
+      "kind": "host",
+      "label": "Codex repository profile",
+      "aliases": [],
+      "purpose": "An explicit skill placement profile; actual host loading requires separate evidence.",
+      "implementation": [
+        "src/capabilities/package.mjs"
+      ]
+    }
+  ],
+  "relations": [
+    {
+      "from": "discovery",
+      "type": "composes",
+      "to": "inquiry"
+    },
+    {
+      "from": "research",
+      "type": "composes",
+      "to": "inquiry"
+    },
+    {
+      "from": "knowledge",
+      "type": "composes",
+      "to": "knowledge-stewardship"
+    },
+    {
+      "from": "build",
+      "type": "composes",
+      "to": "creation-delivery"
+    },
+    {
+      "from": "capability-harness",
+      "type": "composes",
+      "to": "capability-stewardship"
+    },
+    {
+      "from": "learning",
+      "type": "composes",
+      "to": "practical-judgment"
+    },
+    {
+      "from": "ingestion",
+      "type": "composes",
+      "to": "knowledge-stewardship"
+    },
+    {
+      "from": "skill-steward",
+      "type": "participates",
+      "to": "capability-stewardship"
+    },
+    {
+      "from": "witness",
+      "type": "participates",
+      "to": "reflection"
+    },
+    {
+      "from": "companion",
+      "type": "participates",
+      "to": "interaction"
+    },
+    {
+      "from": "research",
+      "type": "applies",
+      "to": "orthogonal-inquiry"
+    },
+    {
+      "from": "discovery",
+      "type": "applies",
+      "to": "bayesian-assessment"
+    },
+    {
+      "from": "govern-adoption",
+      "type": "supports",
+      "to": "capability-stewardship"
+    },
+    {
+      "from": "steward-skill",
+      "type": "realizes",
+      "to": "govern-adoption"
+    },
+    {
+      "from": "codex-repository",
+      "type": "executes",
+      "to": "steward-skill"
+    }
+  ]
+}
+}

package/src/architecture/index.mjs

@@ -0,0 +1,93 @@
+import { catalogDocument } from './catalog.mjs'
+import fs from 'node:fs'
+import Ajv from 'ajv/dist/2020.js'
+import { boundedLearningValue, learningDigest } from '../learning/contracts.mjs'
+
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-architecture.v1.schema.json', import.meta.url)))
+const ajv = new Ajv({ strict: true, allErrors: true })
+const validators = new Map()
+const relationKinds = {
+  composes: [['harness'], ['responsibility']],
+  participates: [['role'], ['responsibility']],
+  realizes: [['resource'], ['capability']],
+  supports: [['capability'], ['responsibility']],
+  applies: [['harness'], ['method']],
+  handles: [['harness'], ['record']],
+  executes: [['host'], ['resource']],
+}
+export function validateArchitecture(value, shape = 'catalog') {
+  try { boundedLearningValue(value) } catch (error) { return [error.message] }
+  if (!['catalog', 'binding'].includes(shape)) return ['unknown architecture shape']
+  if (!validators.has(shape)) validators.set(shape, ajv.compile({ $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${shape}` }))
+  const validate = validators.get(shape)
+  if (!validate(value)) return validate.errors.map(e => `${e.instancePath || '/'}: ${e.message}`)
+  const errors = []
+  if (shape === 'catalog') {
+    const entries = new Map(), labels = new Map(), relations = new Set()
+    for (const entry of value.entries) {
+      if (entries.has(entry.id)) errors.push(`duplicate identity: ${entry.id}`)
+      entries.set(entry.id, entry)
+      for (const label of [entry.id, entry.label, ...entry.aliases]) {
+        const key = label.toLowerCase()
+        if (labels.has(key) && labels.get(key) !== entry.id) errors.push(`ambiguous alias: ${label}`)
+        labels.set(key, entry.id)
+      }
+    }
+    for (const [index, relation] of value.relations.entries()) {
+      const [from, to] = relationKinds[relation.type]
+      if (!from.includes(entries.get(relation.from)?.kind) || !to.includes(entries.get(relation.to)?.kind)) errors.push(`/relations/${index}: incompatible kinds or missing identity`)
+      const key = JSON.stringify(relation)
+      if (relations.has(key)) errors.push(`/relations/${index}: duplicate relationship`)
+      relations.add(key)
+    }
+  } else {
+    const pointers = new Set()
+    for (const field of value.fields) {
+      if (pointers.has(field.pointer)) errors.push(`duplicate authored field: ${field.pointer}`)
+      pointers.add(field.pointer)
+      if (field.classification === 'enforced' && field.consumer === null) errors.push(`${field.pointer}: enforcement requires a named consumer`)
+    }
+  }
+  return errors
+}
+function assert(value, shape) {
+  const errors = validateArchitecture(value, shape)
+  if (errors.length) throw new Error(`invalid architecture ${shape}: ${errors.join('; ')}`)
+  return value
+}
+export function responsibilityCatalog() {
+  return assert(catalogDocument(), 'catalog')
+}
+export function architectureEntry(name, catalog = responsibilityCatalog()) {
+  assert(catalog, 'catalog')
+  if (typeof name !== 'string') throw new Error('architecture name required')
+  const key = name.toLowerCase()
+  return catalog.entries.find(entry => [entry.id, entry.label, ...entry.aliases].some(label => label.toLowerCase() === key)) ?? null
+}
+// Diagnostic resolution never installs a definition or grants operation authority.
+// A consumer declares its exact supported profile/revision/classifications. Missing
+// coverage is visible even for optional behavior; required gaps prevent resolution.
+export function resolveBehaviorBinding({ binding, consumers }) {
+  assert(binding, 'binding')
+  boundedLearningValue(consumers)
+  if (!Array.isArray(consumers) || consumers.length > 128) throw new Error('bounded consumer declarations required')
+  const seen = new Set()
+  for (const consumer of consumers) {
+    if (!consumer || Object.keys(consumer).sort().join(',') !== 'classifications,id,profile,revision' ||
+      ![consumer.id, consumer.profile, consumer.revision].every(v => typeof v === 'string' && v.length > 0 && v.length <= 256) ||
+      !Array.isArray(consumer.classifications) || !consumer.classifications.length ||
+      consumer.classifications.some(v => !['enforced', 'guidance', 'presentation', 'rationale'].includes(v))) throw new Error('invalid consumer declaration')
+    const key = `${consumer.id}/${consumer.profile}`
+    if (seen.has(key)) throw new Error('duplicate consumer profile')
+    seen.add(key)
+  }
+  const diagnostics = []
+  for (const field of binding.fields) {
+    const c = field.consumer
+    if (field.classification === 'rationale' && c === null) continue
+    const supported = consumers.some(item => c && item.id === c.id && item.profile === c.profile && item.revision === c.revision && item.classifications.includes(field.classification))
+    if (!supported) diagnostics.push({ pointer: field.pointer, code: 'unsupported-consumer', required: field.required, classification: field.classification, consumer: c })
+  }
+  return { schema: 'atelier-behavior-resolution@v1', definition: structuredClone(binding.definition), bindingDigest: learningDigest(binding),
+    resolved: !diagnostics.some(d => d.required), diagnostics, adoption: 'not-established', executionAuthorized: false }
+}

package/src/boundary/content-rules.mjs

@@ -62,8 +62,9 @@ export function validateContentRules(rules, { label = 'contentRules' } = {}) {
       continue
     }
     for (const key of Object.keys(rule)) {
-      if (!['id', 'kind', 'severity', 'pattern', 'paths', 'description'].includes(key)) errors.push(`${at} must not include additional property ${key}`)
+      if (!['id', 'kind', 'severity', 'pattern', 'paths', 'description', 'ext'].includes(key)) errors.push(`${at} must not include additional property ${key}`)
     }
+    if (rule.ext != null && !isObject(rule.ext)) errors.push(`${at}.ext must be an object`)
     const id = trimmed(rule.id)
     if (!id) errors.push(`${at}.id is required`)
     else if (seen.has(id)) errors.push(`${at}.id duplicates an earlier rule: ${id}`)
@@ -96,8 +97,9 @@ export function validateContentRuleExceptions(exceptions, rules = DEFAULT_CONTEN
       continue
     }
     for (const key of Object.keys(exception)) {
-      if (!['rule', 'repo', 'paths', 'reason'].includes(key)) errors.push(`${at} must not include additional property ${key}`)
+      if (!['rule', 'repo', 'paths', 'reason', 'ext'].includes(key)) errors.push(`${at} must not include additional property ${key}`)
     }
+    if (exception.ext != null && !isObject(exception.ext)) errors.push(`${at}.ext must be an object`)
     const rule = trimmed(exception.rule)
     if (!rule) errors.push(`${at}.rule is required; an exception must name the rule it excepts`)
     else if (ruleIds.size && !ruleIds.has(rule)) errors.push(`${at}.rule "${rule}" is not a declared content rule`)

package/src/boundary/delegation-command.mjs

@@ -0,0 +1,158 @@
+import fs from 'node:fs'
+import { loadSigningKey, safeLabel, signDocument, verifyDocument } from '../attestation/sign.mjs'
+import { commandProject, firstString, parseArgs } from '../project/config.mjs'
+import { HOST_OWNER_KEYS_PATH, delegationBindings, draftDelegation, loadOwnerKeysFile, validateDelegation } from './delegation.mjs'
+import { loadBoundaryPolicy, validateBoundaryPolicy } from './policy.mjs'
+
+export const DELEGATION_USAGE = `Usage: atelier boundary delegation <draft|sign|verify>
+
+  draft --id ID --owner ACTOR --operator ACTOR --repos A[,B] --operations pre-commit[,boundary-check]
+        --expires RFC3339 [--not-before RFC3339] [--out FILE] [--project-config FILE]
+      Write an unsigned delegation. It binds the current boundary policy, the
+      managed repository set and each listed repository's root commit.
+
+  sign <delegation.json> --key FILE [--out FILE] [--project-config FILE]
+      The OWNER signs with their own private key file (from attestation keygen).
+      The project is required: sign recomputes the bindings from it, refuses a
+      draft that does not match, and prints what is being authorized.
+
+  verify <delegation.json> [--owner-keys FILE] [--json]
+      Report the signature against the host owner-keys file
+      (${HOST_OWNER_KEYS_PATH}), or against FILE to inspect a candidate host
+      file, together with that file's trust result and revocation. This is a
+      diagnostic; boundary check decides whether a delegation applies.
+
+Exit codes: 0 success or valid, 1 invalid, 2 usage or input error.`
+
+function fail(message) {
+  console.error(message)
+  process.exit(2)
+}
+
+const list = (value) => (typeof value === 'string' ? value.split(',').map((item) => item.trim()).filter(Boolean) : [])
+
+function readJsonFile(file, label) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch {
+    fail(`cannot read ${label} JSON: ${file}`)
+  }
+  return null
+}
+
+function writeOutput(out, value) {
+  const text = `${JSON.stringify(value, null, 2)}\n`
+  if (!out) return process.stdout.write(text)
+  try {
+    fs.writeFileSync(out, text, { flag: 'wx' })
+  } catch {
+    fail(`refusing to write ${out}: it exists or cannot be created`)
+  }
+  return console.error(`written to ${out}`)
+}
+
+function projectAndPolicy(argv) {
+  const project = commandProject({ argv })
+  const loaded = loadBoundaryPolicy(project)
+  if (!loaded.ok) fail(loaded.errors.join('\n'))
+  // Never draft or sign against a policy the check itself would reject.
+  const invalid = validateBoundaryPolicy(loaded.policy, project)
+  if (invalid.length) fail(`the boundary policy is invalid:\n${invalid.join('\n')}`)
+  return { project, policy: loaded.policy }
+}
+
+function runDraft(args, argv) {
+  const { project, policy } = projectAndPolicy(argv)
+  const expiresAt = firstString(args.expires)
+  if (!expiresAt) fail(`delegation draft requires --expires\n\n${DELEGATION_USAGE}`)
+  const draft = draftDelegation({
+    policy,
+    project,
+    id: firstString(args.id),
+    owner: firstString(args.owner),
+    operator: firstString(args.operator),
+    repos: list(args.repos),
+    operations: list(args.operations),
+    notBefore: firstString(args['not-before']) ?? new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    expiresAt,
+  })
+  if (!draft.ok && !draft.errors.every((message) => /repoRoots/.test(message))) fail(draft.errors.join('\n'))
+  if (Object.values(draft.delegation.repoRoots).some((root) => !root)) fail('every listed repository needs at least one commit before it can be delegated')
+  if (!draft.ok) fail(draft.errors.join('\n'))
+  writeOutput(firstString(args.out), draft.delegation)
+}
+
+function runSign(args, argv) {
+  const [file] = args._
+  if (!file) fail(`delegation sign requires a delegation file\n\n${DELEGATION_USAGE}`)
+  const keyPath = firstString(args.key)
+  if (!keyPath) fail(`delegation sign requires --key FILE (the owner's own private key)\n\n${DELEGATION_USAGE}`)
+  const doc = readJsonFile(file, 'delegation')
+  if (doc?.signature !== null) fail('delegation sign requires an unsigned delegation (signature: null)')
+  const { project, policy } = projectAndPolicy(argv)
+  const shapeErrors = validateDelegation({ ...doc, signature: { algorithm: 'ed25519', keyId: 'unsigned', value: 'unsigned' } }, policy)
+  if (shapeErrors.length) fail(shapeErrors.join('\n'))
+  // The owner signs what the current project binds, never an opaque digest.
+  const expected = delegationBindings({ policy, project, repos: doc.repos })
+  if (doc.policyDigest !== expected.policyDigest) fail('the draft does not bind the current boundary policy; draft it again from this project')
+  if (doc.repos.some((name) => !expected.repoRoots[name] || doc.repoRoots[name] !== expected.repoRoots[name])) {
+    fail('the draft does not bind these repositories\' root commits; draft it again from this project')
+  }
+  // Every value is printed through safeLabel: ids come from operator-editable files.
+  const operatorActor = policy.actors[doc.operator] ?? {}
+  const label = (value) => safeLabel(value, 160)
+  console.error([
+    `Authorizing delegation ${label(doc.id)}:`,
+    `  operator ${label(doc.operator)} may pass the actor check owned by ${label(doc.owner)}`,
+    `  the operator is recognised by githubLogin ${label(operatorActor.githubLogin ?? '(none)')} and gitEmails ${(operatorActor.gitEmails ?? []).map((email) => label(email)).join(', ') || '(none)'}`,
+    ...doc.repos.map((name) => `  repository ${label(name)} with root commit ${label(doc.repoRoots[name])}`),
+    `  operations: ${doc.operations.map((op) => label(op)).join(', ')}`,
+    `  from ${label(new Date(Date.parse(doc.notBefore)).toISOString())} until ${label(new Date(Date.parse(doc.expiresAt)).toISOString())}`,
+    `  while the boundary policy and repository set stay ${label(doc.policyDigest)}`,
+  ].join('\n'))
+  let signed
+  try {
+    // An explicit key file only: the environment and working-directory fallbacks are not used for delegations.
+    const key = loadSigningKey({ keyPath, env: {}, cwd: '/nonexistent' })
+    if (key.algorithm !== 'ed25519') fail('delegations are signed with ed25519 keys')
+    signed = signDocument(doc, { privateKey: key.privateKeyJwk, keyId: key.keyId, algorithm: key.algorithm })
+  } catch (error) {
+    fail(error.message)
+  }
+  writeOutput(firstString(args.out), signed)
+}
+
+function runVerify(args) {
+  const [file] = args._
+  if (!file) fail(`delegation verify requires a delegation file\n\n${DELEGATION_USAGE}`)
+  const doc = readJsonFile(file, 'delegation')
+  const keysFile = firstString(args['owner-keys']) ?? HOST_OWNER_KEYS_PATH
+  const ownerKeys = loadOwnerKeysFile(keysFile)
+  const report = { ownerKeysFile: keysFile, hostTrust: ownerKeys.ok ? { ok: true } : { ok: false, reason: ownerKeys.reason }, signatureValid: false, revoked: false, reasons: [] }
+  if (ownerKeys.ok) {
+    const key = ownerKeys.keys.find((item) => item.actorId === doc?.owner && item.keyId === doc?.signature?.keyId)
+    if (key) {
+      const checked = verifyDocument(doc, { publicKey: key })
+      report.signatureValid = checked.valid
+      report.reasons.push(...checked.reasons)
+      report.keyId = key.keyId
+      report.owner = key.actorId
+    } else report.reasons.push({ code: 'delegation-owner-key-missing', message: 'no host key for this owner and keyId' })
+    report.revoked = ownerKeys.revoked.has(doc?.id)
+  } else report.reasons.push({ code: ownerKeys.reason, message: ownerKeys.errors.join('; ') })
+  report.valid = report.hostTrust.ok && report.signatureValid && !report.revoked
+  if (args.json) console.log(JSON.stringify(report, null, 2))
+  else console.log(report.valid ? `signature valid for ${report.owner} key ${report.keyId}; scope, time and bindings are decided by boundary check` : `invalid: ${report.reasons.map((item) => item.code).join(', ') || (report.revoked ? 'delegation-revoked' : 'unknown')}`)
+  process.exit(report.valid ? 0 : 1)
+}
+
+export function runBoundaryDelegationCommand(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv)
+  const [subcommand, ...rest] = args._
+  const sub = { ...args, _: rest }
+  if (args.help || args.h) return console.log(DELEGATION_USAGE)
+  if (subcommand === 'draft') return runDraft(sub, argv)
+  if (subcommand === 'sign') return runSign(sub, argv)
+  if (subcommand === 'verify') return runVerify(sub)
+  return fail(DELEGATION_USAGE)
+}