@mnstry/atelier 0.2.0-alpha.1

package/src/check-atelier-export-contract.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  validateAtelierExportContract,
+  validateJsonSchema,
+  validateSchemaShape,
+} from './export/atelier-export-contract.mjs'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const packageRoot = path.resolve(__dirname, '..')
+const schemaPath = path.join(packageRoot, 'contracts/atelier-export.v1.schema.json')
+const fixtureRoot = path.join(packageRoot, 'fixtures/atelier-export')
+const invalidFixtureRoot = path.join(fixtureRoot, 'invalid')
+
+function fail(message) {
+  console.error(`[atelier-export-contract:check] ${message}`)
+  throw new Error(message)
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    fail(`${path.relative(process.cwd(), file)} is not valid JSON: ${error.message}`)
+  }
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : []
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value))
+}
+
+function applyPointerMutation(target, pointer, value) {
+  if (!pointer.startsWith('/')) throw new Error(`invalid JSON pointer ${pointer}`)
+  const parts = pointer.slice(1).split('/').map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+  let node = target
+  for (const part of parts.slice(0, -1)) {
+    if (node == null || !(part in node)) throw new Error(`missing JSON pointer parent ${pointer}`)
+    node = node[part]
+  }
+  const leaf = parts.at(-1)
+  if (node == null || leaf == null || !(leaf in node)) throw new Error(`missing JSON pointer leaf ${pointer}`)
+  node[leaf] = value
+}
+
+function validateInvalidFixture(file, { schema }) {
+  const spec = readJson(file)
+  const basePath = path.resolve(path.dirname(file), spec.base)
+  const doc = clone(readJson(basePath))
+  for (const mutation of asArray(spec.mutations)) {
+    applyPointerMutation(doc, mutation.path, mutation.value)
+  }
+
+  const report = validateAtelierExportContract(doc, { schema, dryRunOnly: true })
+  const errors = [
+    ...report.errors,
+    ...report.semanticProfileViolations.map((violation) => `${violation.path} ${violation.message}`),
+  ]
+  if (errors.length === 0) {
+    return [`negative fixture ${path.basename(file)} unexpectedly passed`]
+  }
+
+  return asArray(spec.expectedErrors)
+    .filter((expected) => !errors.some((error) => error.includes(expected)))
+    .map((expected) => `negative fixture ${path.basename(file)} did not produce expected error: ${expected}`)
+}
+
+export function runAtelierExportContractCheck() {
+  const schema = readJson(schemaPath)
+  const failures = validateSchemaShape(schema)
+  const positiveFixtures = fs.readdirSync(fixtureRoot)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => path.join(fixtureRoot, name))
+
+  for (const file of positiveFixtures) {
+    const doc = readJson(file)
+    failures.push(...validateJsonSchema(schema, doc).map((error) => `${path.relative(process.cwd(), file)}: schema ${error}`))
+    const report = validateAtelierExportContract(doc, { schema, dryRunOnly: true })
+    failures.push(...report.errors.map((error) => `${path.relative(process.cwd(), file)}: ${error}`))
+    failures.push(
+      ...report.semanticProfileViolations.map((violation) => {
+        return `${path.relative(process.cwd(), file)}: ${violation.path} ${violation.message}`
+      })
+    )
+  }
+
+  if (fs.existsSync(invalidFixtureRoot)) {
+    for (const name of fs.readdirSync(invalidFixtureRoot).filter((entry) => entry.endsWith('.json')).sort()) {
+      failures.push(...validateInvalidFixture(path.join(invalidFixtureRoot, name), { schema }))
+    }
+  }
+
+  if (failures.length) {
+    for (const failure of failures) console.error(`[atelier-export-contract:check] ${failure}`)
+    return 1
+  }
+
+  console.log(`[atelier-export-contract:check] ${positiveFixtures.length} positive fixture(s) and invalid fixtures passed`)
+  return 0
+}
+
+const currentFile = fileURLToPath(import.meta.url)
+if (process.argv[1] && path.resolve(process.argv[1]) === currentFile) {
+  try {
+    process.exitCode = runAtelierExportContractCheck()
+  } catch (error) {
+    console.error(`[atelier-export-contract:check] ${error instanceof Error ? error.message : String(error)}`)
+    process.exitCode = 1
+  }
+}

package/src/cli/run.mjs

@@ -0,0 +1,283 @@
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const DEFAULT_BRAND = Object.freeze({ command: 'atelier', displayName: 'MNSTRY Atelier', version: null })
+
+export const commandMap = new Map([
+  ['contract', ['src/check-atelier-export-contract.mjs']],
+  ['init', ['src/commands/init.mjs']],
+  ['setup', ['src/commands/setup.mjs', 'setup']],
+  ['adopt', ['src/commands/setup.mjs', 'adopt']],
+  ['export', ['src/validate-atelier-export-dry-run.mjs']],
+  ['export:dry-run', ['src/validate-atelier-export-dry-run.mjs']],
+  ['dry-run', ['src/validate-atelier-export-dry-run.mjs']],
+  ['graph', ['src/commands/graph.mjs']],
+  ['project', ['src/commands/project.mjs']],
+  ['build', ['src/commands/project.mjs']],
+  ['dev', ['src/commands/server.mjs']],
+  ['server', ['src/commands/server.mjs']],
+  ['readiness', ['src/commands/readiness.mjs']],
+  ['generated', ['src/commands/readiness.mjs', '--check']],
+  ['generated:check', ['src/commands/readiness.mjs', '--check']],
+  ['doctor', ['src/commands/setup.mjs', 'doctor']],
+  ['context', ['src/commands/context.mjs']],
+  ['resolve', ['src/commands/context.mjs', 'resolve']],
+  ['capabilities', ['src/commands/context.mjs', 'capabilities']],
+  ['proposal', ['src/commands/context.mjs', 'proposal']],
+  ['support', ['src/commands/support.mjs']],
+  ['support:bundle', ['src/commands/support.mjs']],
+  ['egress', ['src/commands/egress.mjs']],
+  ['egress:check', ['src/commands/egress.mjs']],
+  ['boundary', ['src/commands/boundary.mjs']],
+  ['boundary:check', ['src/commands/boundary.mjs', 'check']],
+  ['boundary:doctor', ['src/commands/boundary.mjs', 'doctor']],
+  ['boundary:push-check', ['src/commands/boundary.mjs', 'push-check']],
+  ['boundary:audit', ['src/commands/boundary.mjs', 'audit']],
+  ['boundary:install-hooks', ['src/commands/boundary.mjs', 'install-hooks']],
+  ['promote', ['src/commands/promote.mjs']],
+  ['upgrade', ['src/commands/upgrade.mjs']],
+  ['lock', ['src/commands/lock.mjs']],
+  ['lock:check', ['src/commands/lock.mjs', 'check']],
+  ['lock:write', ['src/commands/lock.mjs', 'write']],
+  ['analysis', ['src/commands/analysis.mjs']],
+  ['analyze', ['src/commands/analysis.mjs']],
+  ['config', ['src/commands/config.mjs']],
+  ['config:check', ['src/commands/config.mjs']],
+  ['manifest', ['src/commands/config.mjs']],
+  ['extension-pack', ['src/commands/extension-pack.mjs']],
+  ['extension-pack:validate', ['src/commands/extension-pack.mjs', 'validate']],
+  ['extension-pack:list', ['src/commands/extension-pack.mjs', 'list']],
+  ['distribution', ['src/commands/distribution.mjs']],
+  ['distribution:check', ['src/commands/distribution.mjs', 'check']],
+  ['attestation', ['src/commands/attestation.mjs']],
+  ['feedback', ['src/commands/feedback.mjs']],
+  ['feedback:check', ['src/commands/feedback.mjs', 'check']],
+  ['announcements', ['src/commands/announcements.mjs']],
+  ['announcements:list', ['src/commands/announcements.mjs', 'list']],
+])
+
+function isDefaultBrand(brand) {
+  return brand.command === DEFAULT_BRAND.command && brand.displayName === DEFAULT_BRAND.displayName
+}
+
+function validateBrand(brand) {
+  if (!brand || typeof brand !== 'object') throw new Error('brand must be an object')
+  if (typeof brand.command !== 'string' || !/^[a-z][a-z0-9-]*$/.test(brand.command)) {
+    throw new Error(`brand.command must match /^[a-z][a-z0-9-]*$/: ${String(brand.command)}`)
+  }
+  if (typeof brand.displayName !== 'string' || brand.displayName.length === 0) {
+    throw new Error('brand.displayName must be a non-empty string')
+  }
+  // Control characters (C0 including ESC, and DEL) in a display name can
+  // forge or corrupt terminal output (ANSI injection), so they are rejected.
+  // The message deliberately never echoes the offending value.
+  if (/[\u0000-\u001f\u007f]/.test(brand.displayName)) {
+    throw new Error('brand.displayName must not contain control characters')
+  }
+}
+
+export function buildHelpText(brand = DEFAULT_BRAND, atelierVersion = null) {
+  const header = isDefaultBrand(brand)
+    ? `MNSTRY Atelier
+
+Usage:
+  atelier <command> [args]
+  mnstry-atelier <command> [args]   # legacy alias
+  mnstry atelier <command> [args]   # compatibility`
+    : `${brand.displayName}
+powered by MNSTRY Atelier ${atelierVersion}
+
+Usage:
+  ${brand.command} <command> [args]`
+  return `${header}
+
+Core commands:
+  init                            Create a blank-slate project from a template.
+  adopt                           Add Atelier to an existing repo/workspace.
+  setup --yes                     Repair ignored local machine state.
+  graph [--check]                 Build or check the knowledge graph.
+  project [--check]               Build or check the workspace projection.
+  build [--check]                 Build or check a realm portal.
+  dev                             Run the local Atelier sidecar.
+  readiness [--check]             Build or check readiness.
+  readiness protocols             List bundled MNSTRY readiness protocols.
+  readiness journey               Show the MNSTRY tenant-readiness journey.
+  readiness run PROTOCOL_ID       Run a claim-first readiness protocol.
+  readiness packet                Generate an ignored tenant-readiness draft.
+  readiness export --dry-run      Preview readiness export blockers.
+  generated check                 Run terminal generated-artifact freshness.
+  context flow ...                Resolve session-bound harness context.
+  export --dry-run FILE           Validate atelier-export@v1 dry-run artifact.
+  support bundle --dry-run        Preview a no-send support bundle.
+  feedback --message TEXT         Write a local, never-sent feedback report.
+  announcements list              List and verify MNSTRY announcements.
+  egress check                    Check extracted Atelier paths for forbidden egress.
+  boundary check                  Enforce private/shared repo placement rules.
+  boundary audit                  Report content-rule matches tree-wide without blocking.
+  boundary install-hooks          Install staged/private-domain Git guards.
+  promote                         Record a git.promote disclosure event.
+  upgrade --dry-run               Plan a safe package/template upgrade.
+  upgrade --apply                 Apply a branch-based reviewable upgrade.
+  lock check|write                Verify or create atelier.lock.json.
+  config check                    Validate project config.
+  extension-pack validate         Validate declared extension packs.
+  extension-pack list             List declared extension packs.
+  distribution check              Check a distribution for MNSTRY attribution.
+
+Attestation commands:
+  attestation hash FILE           Print the canonical payload hash of a payload.
+  attestation sign FILE           Sign an unsigned attestation with a signing key file.
+  attestation verify FILE         Verify an attestation against a public key file.
+  attestation keygen --key-id ID  Generate a signing key pair.
+
+Every project-aware command accepts --project-config=PATH or
+MNSTRY_ATELIER_PROJECT_CONFIG=PATH. Machine-local repo paths belong in
+.atelier-local/, atelier.local.json, or atelier.workspace.local.json.`
+}
+
+export function buildCommandHelpText(command, brand = DEFAULT_BRAND) {
+  const c = brand.command
+  const help = {
+    init: `Usage: ${c} init [--template private-domain|shared-project|sample-workspace|distribution] [--target DIR] [--actor ID]
+
+Creates tracked starter files and an Atelier lockfile. It does not install hooks unless asked separately. An unrecognized --template exits 1 and writes nothing; omit --template for the blank scaffold.`,
+    adopt: `Usage: ${c} adopt [--profile single-repo|private-domain|shared-project|multi-repo|monorepo|control-workspace] [--target DIR] [--yes]
+
+Creates or checks a tracked atelier.project.json for an existing workspace and writes machine-local path bindings only to ignored local overlay files.`,
+    setup: `Usage: ${c} setup --yes [--project ./atelier.project.json]
+
+Ensures ignored local Atelier state exists, verifies ignore coverage, and records unambiguous local repo path bindings.`,
+    doctor: `Usage: ${c} doctor [--project ./atelier.project.json] [--fix] [--dry-run]
+
+Reports project config, local overlay, and repo boundary readiness. --fix only repairs ignored local state.`,
+    boundary: `Usage: ${c} boundary check|push-check|audit|install-hooks [--project ./atelier.project.json] [--staged]
+
+check --staged judges the staged diff. push-check reads pre-push ref updates on stdin and judges only the pushed range. audit scans the whole tree and reports without blocking, so an accepted usage never strands unrelated work.`,
+    graph: `Usage: ${c} graph [--check] [--project ./atelier.project.json]
+
+Builds or checks the project knowledge graph from tracked sources plus ignored local path bindings.`,
+    readiness: `Usage:
+  ${c} readiness [--check] [--project ./atelier.project.json]
+  ${c} readiness protocols [--json]
+  ${c} readiness journey [--project ./atelier.project.json]
+  ${c} readiness run mnstry.readiness:offer-map [--answers answers.json] [--project ./atelier.project.json]
+  ${c} readiness packet [--project ./atelier.project.json]
+  ${c} readiness export --dry-run [--project ./atelier.project.json]
+
+Runs the bundled MNSTRY readiness pack claim-first. Protocol state and packet drafts stay in ignored .atelier-local/readiness/ unless explicitly materialized by a reviewed future flow.`,
+    'extension-pack': `Usage:
+  ${c} extension-pack validate [--json] [--project ./atelier.project.json]
+  ${c} extension-pack list [--json] [--project ./atelier.project.json]
+
+Loads every extension pack declared under ext["mnstry.atelier"].extensionPacks in the tracked project config and reports one line per pack. Packs load additively alongside the bundled MNSTRY protocols and can never replace them. list is the default subcommand.`,
+    distribution: `Usage: ${c} distribution check [--target DIR] [--pack DIR]
+
+Checks a distribution package for the required MNSTRY attribution markers. Blocking: the distribution README.md byte check, and a CLI probe that EXECUTES the target's declared bin with --version (spawned with the current Node, cwd set to the target — only run this against distributions you trust) and requires the attribution in its output; a target that looks like a distribution but declares no probe-able bin, or ships a malformed package.json, is also blocking. The extension-pack manifest attribution key is advisory and reported only. The normative wording lives in TRADEMARKS.md under "Required attribution"; see also docs/attestation.md and docs/distributions.md.`,
+    attestation: `Usage:
+  ${c} attestation hash <payload.json>
+  ${c} attestation sign <attestation.json> [--key FILE] [--out FILE]
+  ${c} attestation verify <attestation.json> --public-key FILE [--payload FILE] [--json]
+  ${c} attestation keygen --key-id ID [--algorithm ed25519|es256] [--out FILE]
+
+Records and checks admission decisions. hash prints the canonical payload hash (RFC 8785 JCS, SHA-256). sign reads the local signing key file. verify reads a public key file and exits 1 when it judges the attestation invalid. keygen writes the signing key file mode 0600, refuses to overwrite, and prints only the public key document.`,
+    feedback: `Usage:
+  ${c} feedback create --message TEXT | --message-file PATH [--context FILE] [--include-gates]
+  ${c} feedback check FILE
+
+Assembles a local feedback report under ignored .atelier-local/feedback/ (mode 0600), scanned with the support-bundle banned key and value patterns before writing; any match refuses the write naming pattern label and location only. Files given to --message-file and --context must be valid UTF-8 text of at most 262144 bytes. The scan is a backstop, not clearance: read the whole report before sharing it. The kit has no send path — sharing the file is always the user's own explicit act.`,
+    announcements: `Usage: ${c} announcements list [--dir DIR] [--public-key FILE] | verify <file> [--public-key FILE] [--json] | show <file> [--public-key FILE]
+
+MNSTRY announcements are a pull-only channel: signed JSON documents under announcements/ in the repository. The trust anchor is always the committed MNSTRY key, or one you pass explicitly with --public-key; --dir changes only where documents are read from and never which key verifies them. Every run names the key and keyId it used. The kit never fetches anything — receiving announcements is the git pull you chose to run, and show refuses to print a body whose signature does not verify.`,
+  }
+  return help[command] || `Usage: ${c} ${command} [args]\n\nRun ${c} --help for the command list.`
+}
+
+export function buildVersionText(brand = DEFAULT_BRAND, atelierVersion = null) {
+  if (isDefaultBrand(brand)) return `${atelierVersion}`
+  return `${brand.displayName} ${brand.version ?? atelierVersion} — powered by MNSTRY Atelier ${atelierVersion}`
+}
+
+function normalizeArgs(argv) {
+  const args = [...argv]
+  if (args[0] === 'atelier') args.shift()
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') return { help: true, args }
+  if (args[0] === '--version' || args[0] === '-v' || args[0] === 'version') return { version: true, args }
+
+  if (args[0] === 'export' && args[1] === '--dry-run') args.splice(0, 2, 'export:dry-run')
+  if (args[0] === 'generated' && args[1] === 'check') args.splice(0, 2, 'generated:check')
+  if (args[0] === 'egress' && args[1] === 'check') args.splice(0, 2, 'egress:check')
+  if (args[0] === 'boundary' && args[1] === 'check') args.splice(0, 2, 'boundary:check')
+  if (args[0] === 'boundary' && args[1] === 'doctor') args.splice(0, 2, 'boundary:doctor')
+  if (args[0] === 'boundary' && args[1] === 'push-check') args.splice(0, 2, 'boundary:push-check')
+  if (args[0] === 'boundary' && args[1] === 'audit') args.splice(0, 2, 'boundary:audit')
+  if (args[0] === 'boundary' && args[1] === 'install-hooks') args.splice(0, 2, 'boundary:install-hooks')
+  if (args[0] === 'lock' && args[1] === 'check') args.splice(0, 2, 'lock:check')
+  if (args[0] === 'lock' && args[1] === 'write') args.splice(0, 2, 'lock:write')
+  if (args[0] === 'config' && args[1] === 'check') args.splice(0, 2, 'config:check')
+  if (args[0] === 'extension-pack' && args[1] === 'validate') args.splice(0, 2, 'extension-pack:validate')
+  if (args[0] === 'extension-pack' && args[1] === 'list') args.splice(0, 2, 'extension-pack:list')
+  if (args[0] === 'distribution' && args[1] === 'check') args.splice(0, 2, 'distribution:check')
+  if (args[0] === 'support' && args[1] === 'bundle') args.splice(0, 2, 'support:bundle')
+  if (args[0] === 'support:bundle' && args[1] === '--dry-run') args.splice(1, 1)
+  return { help: false, args }
+}
+
+export async function runCli({
+  argv,
+  env = process.env,
+  cwd = process.cwd(),
+  brand = DEFAULT_BRAND,
+  stdout = console.log,
+  stderr = console.error,
+}) {
+  validateBrand(brand)
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+  const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'))
+  const atelierVersion = packageJson.version
+
+  const normalized = normalizeArgs(argv)
+  if (normalized.help) {
+    stdout(buildHelpText(brand, atelierVersion))
+    return 0
+  }
+  if (normalized.version) {
+    stdout(buildVersionText(brand, atelierVersion))
+    return 0
+  }
+
+  const [command, ...rest] = normalized.args
+  if (rest[0] === '--help' || rest[0] === '-h') {
+    stdout(buildCommandHelpText(command, brand))
+    return 0
+  }
+  const target = commandMap.get(command)
+  if (!target) {
+    stderr(`Unknown ${brand.displayName} command: ${command}`)
+    stdout(buildHelpText(brand, atelierVersion))
+    return 1
+  }
+
+  const [script, ...prefixArgs] = target
+  const scriptPath = path.join(packageRoot, script)
+  if (!fs.existsSync(scriptPath)) {
+    stderr(`${brand.displayName} command is not available in this package install: ${command}`)
+    return 1
+  }
+
+  const result = spawnSync(process.execPath, [scriptPath, ...prefixArgs, ...rest], {
+    cwd,
+    stdio: 'inherit',
+    env: {
+      ...env,
+      MNSTRY_ATELIER_PACKAGE_ROOT: packageRoot,
+    },
+  })
+
+  if (result.error) {
+    stderr(result.error.message)
+    return 1
+  }
+  return result.status ?? 0
+}

package/src/collaboration/proposals.mjs

@@ -0,0 +1,262 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const ATELIER_PROPOSAL_SCHEMA = 'atelier-proposal@v1'
+export const ATELIER_PROPOSALS_SCHEMA = 'atelier-proposals@v1'
+export const PROPOSAL_REVIEW_STATUSES = new Set(['reviewed', 'accepted', 'rejected', 'superseded'])
+
+const DIRECT_WRITE_ACTION_RE = /(?:^|[._:-])(apply|write|commit|persist|mutate|db|database)(?:$|[._:-])/i
+
+function nowIso() {
+  return new Date().toISOString()
+}
+
+function cleanIdentity(value, max = 160) {
+  return String(value || '').trim().slice(0, max)
+}
+
+function stableCompare(left, right) {
+  return String(left).localeCompare(String(right), 'en')
+}
+
+function safeJsonText(value, max = 50000) {
+  if (value == null) return ''
+  if (typeof value === 'string') return value.slice(0, max)
+  try {
+    return JSON.stringify(value, null, 2).slice(0, max)
+  } catch {
+    return String(value).slice(0, max)
+  }
+}
+
+function ensurePrivateDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  try {
+    fs.chmodSync(dir, 0o700)
+  } catch {
+    // Best effort on filesystems that do not support chmod.
+  }
+}
+
+function secureWriteJson(file, payload) {
+  ensurePrivateDir(path.dirname(file))
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`
+  fs.writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 })
+  fs.renameSync(tmp, file)
+  try {
+    fs.chmodSync(file, 0o600)
+  } catch {
+    // Best effort on filesystems that do not support chmod.
+  }
+}
+
+function pathContainedBy(root, candidate) {
+  const resolvedRoot = path.resolve(root)
+  const resolvedCandidate = path.resolve(candidate)
+  return resolvedCandidate === resolvedRoot || resolvedCandidate.startsWith(`${resolvedRoot}${path.sep}`)
+}
+
+function proposalId(seed = crypto.randomBytes(16).toString('hex')) {
+  return `proposal-${crypto.createHash('sha256').update(seed).digest('hex').slice(0, 32)}`
+}
+
+export function actionIsCopyOnly(action) {
+  const value = String(action || '')
+  return Boolean(value) && !DIRECT_WRITE_ACTION_RE.test(value)
+}
+
+export function copyOnlyActionSummary(action) {
+  return {
+    action: String(action || ''),
+    copyOnly: actionIsCopyOnly(action),
+    directWrite: false,
+    applyEndpoint: null,
+  }
+}
+
+export function canTransitionProposal(from, to) {
+  if (from === to) return true
+  if (from === 'proposed') return to === 'reviewed' || to === 'rejected' || to === 'superseded'
+  if (from === 'reviewed') return to === 'accepted' || to === 'rejected' || to === 'superseded'
+  if (from === 'accepted') return to === 'superseded'
+  return false
+}
+
+export function acceptedProposalCopy(record) {
+  const id = record?.proposal?.id || 'unknown-proposal'
+  const targetPath = record?.proposal?.path || 'unknown target'
+  const action = record?.proposal?.action || 'copy-only proposal'
+  const diff = safeJsonText(record?.diff || record?.proposal?.diff || '')
+  return {
+    proposalId: id,
+    targetPath,
+    action,
+    directWrite: false,
+    applyEndpoint: null,
+    diff,
+    agentInstructions: [
+      `Accepted Atelier proposal ${id}.`,
+      'Use normal repo editing in the operator checkout if you choose to apply this handoff.',
+      'There is no browser apply endpoint and this record does not grant direct write authority.',
+      `Target: ${targetPath}`,
+      `Action: ${action}`,
+    ].join('\n'),
+  }
+}
+
+export function createProposalStore({
+  workspaceRoot = process.cwd(),
+  proposalsDir = path.join(workspaceRoot, '.atelier-proposals'),
+  workspaceId = null,
+} = {}) {
+  const workspaceRootReal = fs.realpathSync(workspaceRoot)
+  ensurePrivateDir(proposalsDir)
+
+  function proposalPath(id) {
+    const clean = String(id || '').replace(/[^a-z0-9-]/gi, '')
+    if (!clean) throw new Error('proposal id is required')
+    const file = path.join(proposalsDir, `${clean}.json`)
+    const candidateDir = fs.realpathSync(proposalsDir)
+    if (!pathContainedBy(workspaceRootReal, candidateDir)) {
+      throw new Error('proposal directory escapes workspace')
+    }
+    return file
+  }
+
+  // Read is a lookup, not an assertion: an unusable id and an unreadable file
+  // are both "no such proposal", never a throw. Callers render 404 from null.
+  // listProposals() has always guarded its parse; this is the same contract.
+  function readProposal(id) {
+    let file
+    try {
+      file = proposalPath(id)
+    } catch {
+      return null
+    }
+    if (!fs.existsSync(file)) return null
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'))
+    } catch {
+      return null
+    }
+  }
+
+  function listProposals() {
+    if (!fs.existsSync(proposalsDir)) return []
+    return fs.readdirSync(proposalsDir)
+      .filter((name) => name.endsWith('.json'))
+      .sort(stableCompare)
+      .map((name) => {
+        try {
+          return JSON.parse(fs.readFileSync(path.join(proposalsDir, name), 'utf8'))
+        } catch {
+          return null
+        }
+      })
+      .filter(Boolean)
+      .sort((left, right) => stableCompare(right.proposal?.updatedAt || '', left.proposal?.updatedAt || ''))
+  }
+
+  function createProposal(body = {}) {
+    const action = cleanIdentity(body.action || body.proposal?.action || 'copy.repoPath', 120)
+    if (!actionIsCopyOnly(action)) {
+      return {
+        ok: false,
+        status: 409,
+        error: 'direct-write proposal action refused',
+      }
+    }
+
+    const createdAt = nowIso()
+    const id = proposalId([
+      createdAt,
+      body.sessionId,
+      body.viewId,
+      body.path,
+      action,
+      safeJsonText(body.proposal || body.diff || ''),
+    ].join('\0'))
+    const record = {
+      schema: ATELIER_PROPOSAL_SCHEMA,
+      workspaceId,
+      proposal: {
+        id,
+        status: 'proposed',
+        createdAt,
+        updatedAt: createdAt,
+        sessionId: cleanIdentity(body.sessionId, 120),
+        viewId: cleanIdentity(body.viewId, 120),
+        path: cleanIdentity(body.path || body.rel, 500),
+        action,
+        intent: cleanIdentity(body.intent || body.proposal?.intent, 500),
+        reason: cleanIdentity(body.proposal?.reason || body.reason, 1000),
+        storage: {
+          kind: 'local',
+          ignored: true,
+        },
+        authority: copyOnlyActionSummary(action),
+      },
+      diff: safeJsonText(body.diff || body.proposal?.diff || ''),
+      payload: body.proposal && typeof body.proposal === 'object' ? body.proposal : {},
+    }
+    secureWriteJson(proposalPath(id), record)
+    return { ok: true, status: 200, record }
+  }
+
+  function reviewProposal(id, body = {}) {
+    const record = readProposal(id)
+    if (!record) {
+      return { ok: false, status: 404, error: 'proposal not found' }
+    }
+    if (body.proposalId && body.proposalId !== id) {
+      return { ok: false, status: 409, error: 'ambiguous proposal review refused' }
+    }
+
+    const nextStatus = cleanIdentity(body.status, 40)
+    if (!PROPOSAL_REVIEW_STATUSES.has(nextStatus)) {
+      return { ok: false, status: 400, error: 'unsupported proposal review status' }
+    }
+    if (body.expectedStatus && body.expectedStatus !== record.proposal.status) {
+      return { ok: false, status: 409, error: 'stale proposal review refused: status changed' }
+    }
+    if (body.expectedUpdatedAt && body.expectedUpdatedAt !== record.proposal.updatedAt) {
+      return { ok: false, status: 409, error: 'stale proposal review refused: timestamp changed' }
+    }
+    if (!canTransitionProposal(record.proposal.status, nextStatus)) {
+      return {
+        ok: false,
+        status: 409,
+        error: `invalid proposal review transition ${record.proposal.status} -> ${nextStatus}`,
+      }
+    }
+
+    const updatedAt = nowIso()
+    record.proposal = {
+      ...record.proposal,
+      status: nextStatus,
+      updatedAt,
+      review: {
+        reviewer: cleanIdentity(body.reviewer || 'unknown reviewer', 160),
+        notes: cleanIdentity(body.notes, 2000),
+        reviewedAt: updatedAt,
+      },
+    }
+    if (nextStatus === 'accepted') {
+      record.copyable = acceptedProposalCopy(record)
+    } else {
+      delete record.copyable
+    }
+    secureWriteJson(proposalPath(id), record)
+    return { ok: true, status: 200, record }
+  }
+
+  return {
+    proposalsDir,
+    proposalPath,
+    readProposal,
+    listProposals,
+    createProposal,
+    reviewProposal,
+  }
+}

package/src/commands/analysis.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runAnalysisAdapterCommand } from '../analysis/adapter.mjs'
+try {
+  runAnalysisAdapterCommand()
+} catch (error) {
+  console.error(error.message)
+  process.exit(1)
+}