helloagents 3.0.33 → 3.0.35

package/scripts/qa-review-state.mjs

@@ -0,0 +1,313 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { appendReplayEvent } from './replay-state.mjs'
+import {
+  captureWorkspaceFingerprint,
+  clearRuntimeEvidence,
+  getRuntimeEvidencePath,
+  getRuntimeEvidenceRelativePath,
+  readRuntimeEvidence,
+  validateEvidenceFingerprint,
+  validateEvidenceTimestamp,
+  writeRuntimeEvidence,
+} from './runtime-artifacts.mjs'
+import { getProjectVerifyYamlPath } from './project-storage.mjs'
+
+export const QA_REVIEW_EVIDENCE_FILE_NAME = 'qa-review.json'
+const VALID_QA_MODES = new Set(['standard', 'deep'])
+const VALID_QA_OUTCOMES = new Set(['clean', 'findings'])
+const SHELL_OPERATORS = /[;&|`$(){}\n\r]/
+
+function normalizeStringArray(values) {
+  if (!Array.isArray(values)) return []
+  return [...new Set(values
+    .map((value) => (typeof value === 'string' ? value.trim() : ''))
+    .filter(Boolean))]
+}
+
+function normalizeQaMode(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : ''
+  return VALID_QA_MODES.has(normalized) ? normalized : ''
+}
+
+function normalizeQaOutcome(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : ''
+  return VALID_QA_OUTCOMES.has(normalized) ? normalized : ''
+}
+
+function normalizeCommands(values) {
+  return normalizeStringArray(values)
+}
+
+function loadVerifyYaml(cwd) {
+  const filePath = getProjectVerifyYamlPath(cwd)
+  if (!existsSync(filePath)) return null
+  try {
+    const content = readFileSync(filePath, 'utf-8')
+    const commands = []
+    let inCommands = false
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim()
+      if (trimmed.startsWith('commands:')) {
+        inCommands = true
+        continue
+      }
+      if (!inCommands) continue
+      if (trimmed.startsWith('- ') && !trimmed.startsWith('# ')) {
+        const command = trimmed.slice(2).trim().replace(/^["']|["']$/g, '')
+        if (command && !command.startsWith('#')) commands.push(command)
+        continue
+      }
+      if (trimmed && !trimmed.startsWith('#')) break
+    }
+    return commands.length > 0 ? commands : null
+  } catch {
+    return null
+  }
+}
+
+function detectFromPackageJson(cwd) {
+  const filePath = join(cwd, 'package.json')
+  if (!existsSync(filePath)) return []
+  try {
+    const scripts = JSON.parse(readFileSync(filePath, 'utf-8')).scripts || {}
+    return ['lint', 'typecheck', 'type-check', 'test', 'build']
+      .filter((key) => key in scripts)
+      .map((key) => `npm run ${key}`)
+  } catch {
+    return []
+  }
+}
+
+function detectFromPyproject(cwd) {
+  const filePath = join(cwd, 'pyproject.toml')
+  if (!existsSync(filePath)) return []
+  try {
+    const content = readFileSync(filePath, 'utf-8')
+    const commands = []
+    if (content.includes('[tool.ruff')) commands.push('ruff check .')
+    if (content.includes('[tool.mypy')) commands.push('mypy .')
+    if (content.includes('[tool.pytest')) commands.push('pytest --tb=short -q')
+    return commands
+  } catch {
+    return []
+  }
+}
+
+export function detectCommands(cwd) {
+  const yamlCommands = loadVerifyYaml(cwd)
+  if (yamlCommands?.length) return yamlCommands
+  const packageJsonCommands = detectFromPackageJson(cwd)
+  if (packageJsonCommands.length > 0) return packageJsonCommands
+  return detectFromPyproject(cwd)
+}
+
+export function hasUnsafeQaCommand(commands = []) {
+  return commands.some((command) => SHELL_OPERATORS.test(command))
+}
+
+export function getQaReviewEvidencePath(cwd, options = {}) {
+  return getRuntimeEvidencePath(cwd, QA_REVIEW_EVIDENCE_FILE_NAME, options)
+}
+
+export function readQaReviewEvidence(cwd, options = {}) {
+  return readRuntimeEvidence(cwd, QA_REVIEW_EVIDENCE_FILE_NAME, options)
+}
+
+export function clearQaReviewEvidence(cwd, options = {}) {
+  clearRuntimeEvidence(cwd, QA_REVIEW_EVIDENCE_FILE_NAME, options)
+}
+
+export function normalizeQaReviewEvidence(input = {}) {
+  return {
+    source: typeof input.source === 'string' && input.source.trim() ? input.source.trim() : 'manual',
+    originCommand: typeof input.originCommand === 'string' ? input.originCommand.trim() : '',
+    qaMode: normalizeQaMode(input.qaMode) || 'standard',
+    scope: typeof input.scope === 'string' ? input.scope.trim() : '',
+    outcome: normalizeQaOutcome(input.outcome),
+    conclusion: typeof input.conclusion === 'string' ? input.conclusion.trim() : '',
+    findings: normalizeStringArray(input.findings),
+    fileReferences: normalizeStringArray(input.fileReferences),
+    commands: normalizeCommands(input.commands),
+    fastOnly: Boolean(input.fastOnly),
+  }
+}
+
+export function writeQaReviewEvidence(cwd, {
+  source = 'manual',
+  originCommand = '',
+  qaMode = 'standard',
+  scope = '',
+  outcome = '',
+  conclusion = '',
+  findings = [],
+  fileReferences = [],
+  commands = [],
+  fastOnly = false,
+} = {}, options = {}) {
+  const normalized = normalizeQaReviewEvidence({
+    source,
+    originCommand,
+    qaMode,
+    scope,
+    outcome,
+    conclusion,
+    findings,
+    fileReferences,
+    commands,
+    fastOnly,
+  })
+  const payload = {
+    schemaVersion: 2,
+    updatedAt: new Date().toISOString(),
+    source: normalized.source,
+    originCommand: normalized.originCommand,
+    qaMode: normalized.qaMode,
+    scope: normalized.scope,
+    outcome: normalized.outcome,
+    conclusion: normalized.conclusion,
+    findings: normalized.findings,
+    fileReferences: normalized.fileReferences,
+    commands: normalized.commands,
+    fastOnly: normalized.fastOnly,
+    fingerprint: captureWorkspaceFingerprint(cwd),
+  }
+  writeRuntimeEvidence(cwd, QA_REVIEW_EVIDENCE_FILE_NAME, payload, options)
+  appendReplayEvent(cwd, {
+    event: 'qa_review_evidence_written',
+    source: normalized.source,
+    skillName: normalized.originCommand,
+    payload: options.payload || {},
+    details: {
+      qaMode: normalized.qaMode,
+      scope: normalized.scope,
+      outcome: normalized.outcome,
+      conclusion: normalized.conclusion,
+      findings: normalized.findings,
+      fileReferences: normalized.fileReferences,
+      commands: normalized.commands,
+      fastOnly: normalized.fastOnly,
+    },
+    artifacts: [getRuntimeEvidenceRelativePath(cwd, QA_REVIEW_EVIDENCE_FILE_NAME, options)],
+  })
+  return payload
+}
+
+function readRequiredQaReviewEvidence(cwd, options = {}) {
+  const evidence = readQaReviewEvidence(cwd, options)
+  if (evidence) return { evidence }
+  return {
+    error: {
+      required: true,
+      status: 'missing',
+      details: ['缺少当前工作流的成功 qa-review 证据'],
+    },
+  }
+}
+
+function validateQaReviewTimestamp(evidence, now) {
+  return validateEvidenceTimestamp(evidence, now, 'qa-review 证据')
+}
+
+function validateQaReviewFingerprint(cwd, evidence) {
+  return validateEvidenceFingerprint(cwd, evidence, '成功 qa-review 证据')
+}
+
+function validateQaReviewEvidence(commands, evidence) {
+  if (!normalizeQaOutcome(evidence.outcome) || !String(evidence.conclusion || '').trim()) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      commands,
+      details: ['qa-review 证据必须记录明确的 outcome 和 conclusion'],
+    }
+  }
+  if (commands.length > 0 && normalizeCommands(evidence.commands).length === 0) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      commands,
+      details: ['qa-review 证据必须记录本次实际执行的验证命令'],
+    }
+  }
+  if (Boolean(evidence.fastOnly)) {
+    return {
+      required: true,
+      status: 'fast-only',
+      evidence,
+      commands,
+      details: ['最新 qa-review 证据只覆盖快速命令检查，未完成完整 qa-review 闭环'],
+    }
+  }
+  if (normalizeQaOutcome(evidence.outcome) !== 'clean') {
+    return {
+      required: true,
+      status: 'blocked',
+      evidence,
+      commands,
+      details: ['最新 qa-review 证据仍记录阻断问题'],
+    }
+  }
+  return null
+}
+
+export function getQaReviewEvidenceStatus(cwd, { required = false, now = Date.now(), ...options } = {}) {
+  const commands = detectCommands(cwd)
+  if (!required) {
+    return {
+      required: false,
+      status: 'not-applicable',
+      commands,
+    }
+  }
+
+  const requiredEvidence = readRequiredQaReviewEvidence(cwd, options)
+  if (requiredEvidence.error) return { ...requiredEvidence.error, commands }
+
+  const { evidence } = requiredEvidence
+  const timestampError = validateQaReviewTimestamp(evidence, now)
+  if (timestampError) return { ...timestampError, commands }
+
+  const fingerprintError = validateQaReviewFingerprint(cwd, evidence)
+  if (fingerprintError) return { ...fingerprintError, commands }
+
+  const evidenceError = validateQaReviewEvidence(commands, evidence)
+  if (evidenceError) return evidenceError
+
+  return {
+    required: true,
+    status: 'valid',
+    evidence,
+    commands,
+  }
+}
+
+function readStdinJson() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+function main() {
+  const command = process.argv[2] || ''
+  if (command !== 'write') return
+
+  const input = readStdinJson()
+  const cwd = input.cwd || process.cwd()
+  const payload = writeQaReviewEvidence(cwd, input, { payload: input })
+  process.stdout.write(JSON.stringify({
+    suppressOutput: true,
+    path: getQaReviewEvidencePath(cwd, { payload: input }),
+    payload,
+  }))
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main()
+}

package/scripts/ralph-loop.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * HelloAGENTS Ralph Loop — Quality verification gate
+ * HelloAGENTS QA Gate — Quality verification gate
  * Runs on SubagentStop (Claude Code) and Stop (Codex CLI).
  * Auto-detects lint/test commands and blocks if they fail.
  */
@@ -9,7 +9,13 @@ import { join } from 'node:path';
 import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { clearVerifyEvidence, detectCommands, hasUnsafeVerifyCommand, writeVerifyEvidence } from './verify-state.mjs';
+import {
+  clearQaReviewEvidence,
+  detectCommands,
+  getQaReviewEvidenceStatus,
+  hasUnsafeQaCommand,
+  writeQaReviewEvidence,
+} from './qa-review-state.mjs';
 import {
   getRuntimeEvidencePath,
   readRuntimeEvidence,
@@ -70,7 +76,7 @@ function hasGitChanges(cwd) {
 function runVerify(commands, cwd) {
   const failures = [];
   for (const cmd of commands) {
-    if (hasUnsafeVerifyCommand([cmd])) {
+    if (hasUnsafeQaCommand([cmd])) {
       failures.push({ cmd, output: '已阻止：验证命令不允许使用 shell 组合操作符' });
       continue;
     }
@@ -219,17 +225,30 @@ export function evaluateRalphLoop(data = {}, runtime = {}) {
   const failures = runVerify(commands, cwd);
   if (failures.length === 0) {
     resetBreaker(cwd, runtimeOptions);
-    writeVerifyEvidence(cwd, {
-      commands: detectCommands(cwd),
-      fastOnly: isSubagent,
-      source: isSubagent ? 'subagent' : 'stop',
-    }, runtimeOptions);
+    const qaStatus = getQaReviewEvidenceStatus(cwd, {
+      required: true,
+      ...runtimeOptions,
+    });
+    if (qaStatus.status !== 'valid') {
+      writeQaReviewEvidence(cwd, {
+        source: isSubagent ? 'subagent' : 'ralph-loop',
+        originCommand: 'qa',
+        qaMode: 'standard',
+        scope: isSubagent ? 'subagent-fast-check' : 'runtime-fast-check',
+        outcome: 'clean',
+        conclusion: '自动命令检查通过。',
+        findings: [],
+        fileReferences: [],
+        commands: detectCommands(cwd),
+        fastOnly: true,
+      }, runtimeOptions);
+    }
 
     if (isSubagent) {
       return {
         hookSpecificOutput: {
           hookEventName,
-          additionalContext: '子代理快速验证通过（lint/typecheck）。请控制器审查变更后继续。',
+          additionalContext: '子代理快速 QA 命令检查通过（lint/typecheck）。请控制器继续完整 qa-review。',
         },
         suppressOutput: true,
       };
@@ -239,7 +258,7 @@ export function evaluateRalphLoop(data = {}, runtime = {}) {
       return {
         hookSpecificOutput: {
           hookEventName,
-          additionalContext: '⚠️ [Ralph Loop] 验证通过但未检测到代码变更（git diff 为空）。如果确实完成了编码任务，请确认变更已保存。',
+          additionalContext: '⚠️ [QA Gate] 验证通过但未检测到代码变更（git diff 为空）。如果确实完成了编码任务，请确认变更已保存。',
         },
         suppressOutput: true,
       };
@@ -248,7 +267,7 @@ export function evaluateRalphLoop(data = {}, runtime = {}) {
     return { suppressOutput: true };
   }
 
-  clearVerifyEvidence(cwd, runtimeOptions);
+  clearQaReviewEvidence(cwd, runtimeOptions);
   const breaker = readBreaker(cwd, runtimeOptions);
   breaker.consecutive_failures += 1;
   breaker.last_failure = new Date().toISOString();
@@ -260,7 +279,7 @@ export function evaluateRalphLoop(data = {}, runtime = {}) {
   const details = failures.map(f => `\u2717 ${f.cmd}\n${f.output}`).join('\n\n');
   return {
     decision: 'block',
-    reason: `[Ralph Loop] 验证失败：\n\n${details}\n\n请先修复以上问题，再报告完成。${breakerWarning}`,
+    reason: `[QA Gate] 验证失败：\n\n${details}\n\n请先修复以上问题，再报告完成。${breakerWarning}`,
     suppressOutput: true,
   };
 }
@@ -278,7 +297,7 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
   } catch (error) {
     process.stdout.write(JSON.stringify({
       decision: 'block',
-      reason: `[Ralph Loop] 验证脚本执行异常，已暂停完成通知。\n原因：${error?.message || error}`,
+      reason: `[QA Gate] 验证脚本执行异常，已暂停完成通知。\n原因：${error?.message || error}`,
       suppressOutput: true,
     }));
   }

package/scripts/runtime-scope.mjs

@@ -12,7 +12,6 @@ import { FULL_CARRIER_PROFILE_MARKER } from './cli-utils.mjs'
 export const PROJECT_DIR_NAME = '.helloagents'
 export const PROJECT_SESSIONS_DIR_NAME = 'sessions'
 export const PROJECT_ARTIFACTS_DIR_NAME = 'artifacts'
-export const CAPSULE_FILE_NAME = 'capsule.json'
 export const EVENTS_FILE_NAME = 'events.jsonl'
 export const ACTIVE_SESSION_FILE_NAME = 'active.json'
 export const DEFAULT_STATE_SESSION_TOKEN = 'default'
@@ -463,7 +462,6 @@ export function getProjectSessionScope(cwd, options = {}) {
     activationDir,
     sessionDir,
     statePath: join(sessionDir, 'STATE.md'),
-    capsulePath: join(sessionDir, CAPSULE_FILE_NAME),
     eventsPath: join(sessionDir, EVENTS_FILE_NAME),
     artifactsDir: join(sessionDir, PROJECT_ARTIFACTS_DIR_NAME),
     key: `${projectRoot}::${workspace}::${session}`,
@@ -493,7 +491,7 @@ function buildTransientRuntimeDir(cwd, options = {}) {
     session: token,
     sessionMode: token === DEFAULT_STATE_SESSION_TOKEN ? 'default' : 'transient-session',
     sessionDir: join(getUserRuntimeRoot(), hash),
-    capsulePath: join(getUserRuntimeRoot(), hash, CAPSULE_FILE_NAME),
+    statePath: join(getUserRuntimeRoot(), hash, 'STATE.md'),
     eventsPath: join(getUserRuntimeRoot(), hash, EVENTS_FILE_NAME),
     artifactsDir: join(getUserRuntimeRoot(), hash, PROJECT_ARTIFACTS_DIR_NAME),
     key: `${normalizedCwd}::transient::${token}`,

package/scripts/session-capsule.mjs

@@ -10,6 +10,7 @@ import {
   writeActiveProjectSession,
   writeJsonFileAtomic,
 } from './runtime-scope.mjs'
+import { readStateDocument, writeStateDocument } from './state-document.mjs'
 
 export { getRuntimeScope }
 
@@ -68,7 +69,7 @@ function getScope(cwd, options = {}) {
 }
 
 export function getSessionCapsulePath(cwd = process.cwd(), options = {}) {
-  return getScope(cwd, options).capsulePath
+  return getScope(cwd, options).statePath
 }
 
 export function getSessionEventsPath(cwd = process.cwd(), options = {}) {
@@ -93,8 +94,9 @@ export function getSessionArtifactRelativePath(cwd, fileName, options = {}) {
 
 export function readSessionCapsule(cwd = process.cwd(), options = {}) {
   const scope = getScope(cwd, options)
-  const capsule = readJsonFile(scope.capsulePath, null)
-  if (!capsule || typeof capsule !== 'object') return buildEmptyCapsule(scope)
+  const { metadata } = readStateDocument(scope.statePath)
+  const capsule = metadata && typeof metadata === 'object' ? metadata : null
+  if (!capsule || Array.isArray(capsule)) return buildEmptyCapsule(scope)
   return {
     ...buildEmptyCapsule(scope),
     ...capsule,
@@ -109,7 +111,24 @@ export function readSessionCapsule(cwd = process.cwd(), options = {}) {
 }
 
 export function writeSessionCapsule(cwd, capsule, options = {}) {
-  const scope = getScope(cwd, options)
+  const normalizedOptions = normalizeOptions(options)
+  const scope = getScope(cwd, normalizedOptions)
+  const currentDocument = readStateDocument(scope.statePath)
+  const hasBody = Boolean(currentDocument.body && currentDocument.body.trim())
+  if (!hasBody && normalizedOptions.ensureProjectLocal !== true && !existsSync(scope.statePath)) {
+    return {
+      ...buildEmptyCapsule(scope),
+      ...capsule,
+      scope: scope.scope,
+      key: scope.key,
+      cwd: scope.cwd,
+      branch: scope.branch,
+      workspace: scope.workspace || scope.branch,
+      session: scope.session,
+      sessionMode: scope.sessionMode,
+      updatedAt: new Date().toISOString(),
+    }
+  }
   const nextCapsule = {
     ...buildEmptyCapsule(scope),
     ...capsule,
@@ -122,9 +141,12 @@ export function writeSessionCapsule(cwd, capsule, options = {}) {
     sessionMode: scope.sessionMode,
     updatedAt: new Date().toISOString(),
   }
-  writeJsonFileAtomic(scope.capsulePath, nextCapsule)
+  writeStateDocument(scope.statePath, {
+    metadata: nextCapsule,
+    body: currentDocument.body,
+  })
   writeActiveProjectSession(scope, {
-    env: normalizeOptions(options).env,
+    env: normalizedOptions.env,
   })
   return nextCapsule
 }
@@ -151,8 +173,8 @@ export function writeCapsuleSection(cwd, section, value, options = {}) {
 }
 
 export function clearCapsuleSection(cwd, section, options = {}) {
-  const capsulePath = getSessionCapsulePath(cwd, options)
-  if (!existsSync(capsulePath)) return false
+  const statePath = getSessionCapsulePath(cwd, options)
+  if (!existsSync(statePath)) return false
 
   const capsule = readSessionCapsule(cwd, options)
   if (!Object.prototype.hasOwnProperty.call(capsule, section)) return false
@@ -180,6 +202,13 @@ export function appendSessionEvent(cwd, eventPayload, options = {}) {
   const eventName = eventPayload?.event || ''
   if (!eventName) return ''
 
+  writeActiveProjectSession(scope, {
+    host: eventPayload.host || '',
+    source: eventPayload.source || eventName,
+    env: scopedOptions.env,
+  })
+  if (!shouldRecordSessionEvents(scopedOptions)) return ''
+
   mkdirSync(dirname(scope.eventsPath), { recursive: true })
   const payload = {
     ts: new Date().toISOString(),
@@ -192,17 +221,13 @@ export function appendSessionEvent(cwd, eventPayload, options = {}) {
     encoding: 'utf-8',
     flag: 'a',
   })
-  writeActiveProjectSession(scope, {
-    host: eventPayload.host || '',
-    source: eventPayload.source || eventName,
-    env: scopedOptions.env,
-  })
   return scope.eventsPath
 }
 
 export function resetSessionEvents(cwd, options = {}) {
   const scope = getScope(cwd, options)
   if (scope.scope === 'project-session' && !scope.active) return ''
+  if (!shouldRecordSessionEvents(options)) return ''
   mkdirSync(dirname(scope.eventsPath), { recursive: true })
   writeFileSync(scope.eventsPath, '', 'utf-8')
   return scope.eventsPath
@@ -242,3 +267,16 @@ export function clearSessionArtifact(cwd, fileName, options = {}) {
 export function removeSessionCapsule(cwd, options = {}) {
   removeRuntimeFile(getSessionCapsulePath(cwd, options))
 }
+
+function shouldRecordSessionEvents(options = {}) {
+  const normalizedOptions = normalizeOptions(options)
+  const payload = normalizedOptions.payload || {}
+  if (normalizedOptions.traceEvents === true || payload.traceEvents === true || payload._helloagentsTraceEvents === true) {
+    return true
+  }
+
+  const raw = String(normalizedOptions.env?.HELLOAGENTS_TRACE_EVENTS || process.env.HELLOAGENTS_TRACE_EVENTS || '')
+    .trim()
+    .toLowerCase()
+  return raw === '1' || raw === 'true' || raw === 'yes'
+}

package/scripts/state-document.mjs

@@ -0,0 +1,77 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const STATE_META_BEGIN = '<!-- HELLOAGENTS_STATE_META'
+const STATE_META_END = 'HELLOAGENTS_STATE_META -->'
+
+function normalizeText(content = '') {
+  return String(content || '').replace(/^\uFEFF/, '')
+}
+
+function splitLines(content = '') {
+  return normalizeText(content).replace(/\r\n/g, '\n').split('\n')
+}
+
+export function parseStateDocument(content = '') {
+  const lines = splitLines(content)
+  if (lines[0]?.trim() !== STATE_META_BEGIN) {
+    return {
+      hasMetadata: false,
+      metadata: null,
+      body: normalizeText(content),
+    }
+  }
+
+  const endIndex = lines.findIndex((line, index) => index > 0 && line.trim() === STATE_META_END)
+  if (endIndex < 0) {
+    return {
+      hasMetadata: false,
+      metadata: null,
+      body: normalizeText(content),
+    }
+  }
+
+  const metadataText = lines.slice(1, endIndex).join('\n').trim()
+  const body = lines.slice(endIndex + 1).join('\n').replace(/^\n+/, '')
+  try {
+    return {
+      hasMetadata: true,
+      metadata: JSON.parse(metadataText),
+      body,
+    }
+  } catch {
+    return {
+      hasMetadata: false,
+      metadata: null,
+      body,
+    }
+  }
+}
+
+export function readStateDocument(filePath) {
+  if (!filePath || !existsSync(filePath)) {
+    return {
+      hasMetadata: false,
+      metadata: null,
+      body: '',
+    }
+  }
+
+  return parseStateDocument(readFileSync(filePath, 'utf-8'))
+}
+
+export function composeStateDocument({ metadata = {}, body = '' } = {}) {
+  const normalizedBody = normalizeText(body).replace(/^\n+/, '')
+  return [
+    STATE_META_BEGIN,
+    JSON.stringify(metadata, null, 2),
+    STATE_META_END,
+    '',
+    normalizedBody,
+  ].join('\n').replace(/\n+$/, '\n')
+}
+
+export function writeStateDocument(filePath, { metadata = {}, body = '' } = {}) {
+  mkdirSync(dirname(filePath), { recursive: true })
+  writeFileSync(filePath, composeStateDocument({ metadata, body }), 'utf-8')
+}