ace-pack 0.1.0

package/scripts/ai-task-finish.mjs

@@ -0,0 +1,206 @@
+import { execFile } from 'node:child_process'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { promisify } from 'node:util'
+
+import {
+  extractLabeledValue,
+  extractMarkdownSection,
+  extractUnresolvedReflections,
+  formatTimestamp,
+  getArgValue,
+  parseCliArgs,
+  readTextIfExists,
+  writeAceBanner,
+  writeTextFile,
+} from './ai-memory-utils.mjs'
+import { classifyRepositoryTask } from './ai-task-classify.mjs'
+
+const execFileAsync = promisify(execFile)
+const PLACEHOLDER_PATTERN = /\[[^\]]+\]|\bTODO\b|\bTBD\b|No .* recorded/i
+
+export function validateFinishRequirements({
+  classification,
+  currentTaskContent,
+  handoffContent,
+  reflectionLogContent,
+}) {
+  const missing = []
+  const businessValue = extractMarkdownSection(
+    currentTaskContent,
+    'Business Value / Product Alignment',
+  )
+  const technicalApproach = extractMarkdownSection(currentTaskContent, 'Technical Approach')
+  const qualityReview = extractMarkdownSection(handoffContent, 'Quality Review')
+
+  if (!hasMeaningfulContent(businessValue)) {
+    missing.push('Fill .ai/current-task.md Business Value / Product Alignment.')
+  }
+
+  if (classification.designReviewRequired && !hasDesignReview(technicalApproach)) {
+    missing.push(
+      'Fill .ai/current-task.md Technical Approach with Option 1, Option 2, and Chosen Approach.',
+    )
+  }
+
+  if (
+    (classification.tier === 'standard' || classification.tier === 'large') &&
+    !hasQualityReview(qualityReview)
+  ) {
+    missing.push(
+      'Fill .ai/session-handoff.md Quality Review for product, architecture, security, and code quality.',
+    )
+  }
+
+  if (classification.tier === 'large' && !hasMeaningfulReflection(reflectionLogContent)) {
+    missing.push('Add a compact .ai/reflection-log.md entry for this large task.')
+  }
+
+  return missing
+}
+
+export async function archiveCurrentTask(rootDir) {
+  const currentTaskPath = path.join(rootDir, '.ai', 'current-task.md')
+  const currentTaskContent = await readTextIfExists(currentTaskPath)
+
+  if (currentTaskContent === null) {
+    throw new Error('Cannot archive missing .ai/current-task.md.')
+  }
+
+  const lifecycle = extractMarkdownSection(currentTaskContent, 'Lifecycle')
+  const version = extractLabeledValue(lifecycle, 'Version') || 'task'
+  const featureName = extractMarkdownSection(currentTaskContent, 'Feature Name') || 'task'
+  const timestamp = formatTimestamp(new Date()).replace(/[: ]/g, '-')
+  const baseName = `${slugify(version)}-${slugify(featureName)}-${timestamp}`
+  let outputPath = path.join(rootDir, '.ai', 'archive', 'tasks', `${baseName}.md`)
+  let suffix = 2
+
+  while ((await readTextIfExists(outputPath)) !== null) {
+    outputPath = path.join(rootDir, '.ai', 'archive', 'tasks', `${baseName}-${suffix}.md`)
+    suffix += 1
+  }
+
+  await writeTextFile(outputPath, currentTaskContent)
+  return outputPath
+}
+
+async function main() {
+  writeAceBanner()
+
+  const rawArgs = process.argv.slice(2)
+  const args = parseCliArgs(rawArgs)
+  const rootDir = path.resolve(process.cwd(), getArgValue(args, 'root') ?? '.')
+  const classification = await classifyRepositoryTask(rootDir, {
+    overrideReason: getArgValue(args, 'reason'),
+    overrideTier: getArgValue(args, 'tier'),
+  })
+  const [currentTaskContent, handoffContent, reflectionLogContent] = await Promise.all([
+    requireAiFile(rootDir, 'current-task.md'),
+    requireAiFile(rootDir, 'session-handoff.md'),
+    requireAiFile(rootDir, 'reflection-log.md'),
+  ])
+  const missing = validateFinishRequirements({
+    classification,
+    currentTaskContent,
+    handoffContent,
+    reflectionLogContent,
+  })
+
+  if (missing.length > 0) {
+    process.stderr.write('Adaptive task finish blocked by missing closeout notes:\n')
+
+    for (const item of missing) {
+      process.stderr.write(`- ${item}\n`)
+    }
+
+    process.exit(1)
+  }
+
+  await runNodeScript(rootDir, 'ai-report-brief.mjs')
+
+  if (classification.tier === 'large') {
+    process.stderr.write(
+      'Large task reminder: update .ai/tech-docs.md for architecture changes and .ai/product-roadmap.md for business or roadmap changes when applicable.\n',
+    )
+    const archivePath = await archiveCurrentTask(rootDir)
+    process.stderr.write(`Archived current task to ${archivePath}\n`)
+    await runNodeScript(rootDir, 'ai-report.mjs')
+  }
+
+  process.stderr.write(`Adaptive task finish passed for ${classification.tier} task.\n`)
+}
+
+async function requireAiFile(rootDir, fileName) {
+  const filePath = path.join(rootDir, '.ai', fileName)
+  const content = await readTextIfExists(filePath)
+
+  if (content === null) {
+    throw new Error(`Missing required file: ${filePath}`)
+  }
+
+  return content
+}
+
+async function runNodeScript(rootDir, scriptName) {
+  await execFileAsync(process.execPath, [path.join(rootDir, 'scripts', scriptName), rootDir], {
+    cwd: rootDir,
+    env: process.env,
+  })
+}
+
+function hasDesignReview(section) {
+  return (
+    hasMeaningfulContent(section) &&
+    /Option\s*1:/i.test(section) &&
+    /Option\s*2:/i.test(section) &&
+    /Chosen Approach:/i.test(section)
+  )
+}
+
+function hasQualityReview(section) {
+  return (
+    hasMeaningfulContent(section) &&
+    hasQualityLabel(section, 'Product Alignment') &&
+    hasQualityLabel(section, 'Architecture') &&
+    hasQualityLabel(section, 'Security') &&
+    hasQualityLabel(section, 'Code Quality')
+  )
+}
+
+function hasQualityLabel(section, label) {
+  const pattern = new RegExp(
+    `${escapeRegExp(label)}:\\s*([\\s\\S]*?)(?=\\n[A-Z][A-Za-z ]+:|$)`,
+    'i',
+  )
+  const match = section.match(pattern)
+
+  return Boolean(match?.[1] && hasMeaningfulContent(match[1]))
+}
+
+function hasMeaningfulReflection(content) {
+  return (
+    extractUnresolvedReflections(content, 1).length > 0 || /## Resolved[\s\S]*^### /m.test(content)
+  )
+}
+
+function hasMeaningfulContent(content) {
+  const normalizedContent = content.replace(/\s+/g, ' ').trim()
+
+  return normalizedContent.length > 0 && !PLACEHOLDER_PATTERN.test(normalizedContent)
+}
+
+function slugify(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80)
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main()
+}

package/scripts/ai-update.mjs

@@ -0,0 +1,236 @@
+import path from 'node:path'
+
+import {
+  formatBullets,
+  formatChecklist,
+  getArgList,
+  getArgValue,
+  nowTimestamp,
+  parseCliArgs,
+  readTextIfExists,
+  replaceLabeledValue,
+  replaceMarkdownSection,
+  writeTextFile,
+} from './ai-memory-utils.mjs'
+
+const command = process.argv[2]
+const args = parseCliArgs(process.argv.slice(3))
+const rootDir = process.cwd()
+const aiDir = path.join(rootDir, '.ai')
+
+if (!command) {
+  throw new Error(
+    'Usage: node ./scripts/ai-update.mjs <task|handoff|log|decision|changed> [--flags]',
+  )
+}
+
+switch (command) {
+  case 'task':
+    await updateTask()
+    break
+  case 'handoff':
+    await updateHandoff()
+    break
+  case 'log':
+    await appendWorkLog()
+    break
+  case 'decision':
+    await appendDecision()
+    break
+  case 'changed':
+    await appendChangedFile()
+    break
+  default:
+    throw new Error(`Unknown ai:update command: ${command}`)
+}
+
+async function updateTask() {
+  const filePath = path.join(aiDir, 'current-task.md')
+  const existingContent = await requireFile(filePath)
+  let nextContent = existingContent
+
+  const feature = getArgValue(args, 'feature')
+  const goal = getArgValue(args, 'goal')
+  const status = getArgValue(args, 'status')
+  const version = getArgValue(args, 'version')
+  const started = getArgValue(args, 'started')
+  const ready = getArgValue(args, 'ready')
+
+  if (feature) {
+    nextContent = replaceMarkdownSection(nextContent, 'Feature Name', feature)
+  }
+
+  if (goal) {
+    nextContent = replaceMarkdownSection(nextContent, 'Goal', goal)
+  }
+
+  if (status) {
+    nextContent = replaceLabeledValue(nextContent, 'Status', status)
+  }
+
+  if (version) {
+    nextContent = replaceLabeledValue(nextContent, 'Version', version)
+  }
+
+  if (started) {
+    nextContent = replaceLabeledValue(
+      nextContent,
+      'Started',
+      started === 'now' ? nowTimestamp() : started,
+    )
+  }
+
+  if (ready) {
+    nextContent = replaceLabeledValue(nextContent, 'Ready For Archive', ready)
+  }
+
+  const current = getArgList(args, 'current')
+  const affected = getArgList(args, 'affected')
+  const constraints = getArgList(args, 'constraint')
+  const acceptance = getArgList(args, 'accept')
+  const checklist = getArgList(args, 'check')
+
+  if (current.length > 0) {
+    nextContent = replaceMarkdownSection(nextContent, 'Current Status', formatBullets(current))
+  }
+
+  if (affected.length > 0) {
+    nextContent = replaceMarkdownSection(nextContent, 'Affected Areas', formatBullets(affected))
+  }
+
+  if (constraints.length > 0) {
+    nextContent = replaceMarkdownSection(nextContent, 'Constraints', formatBullets(constraints))
+  }
+
+  if (acceptance.length > 0) {
+    nextContent = replaceMarkdownSection(
+      nextContent,
+      'Acceptance Criteria',
+      formatBullets(acceptance),
+    )
+  }
+
+  if (checklist.length > 0) {
+    nextContent = replaceMarkdownSection(
+      nextContent,
+      'Completion Checklist',
+      formatChecklist(checklist),
+    )
+  }
+
+  await writeTextFile(filePath, nextContent)
+  process.stderr.write(`Updated ${filePath}\n`)
+}
+
+async function updateHandoff() {
+  const filePath = path.join(aiDir, 'session-handoff.md')
+  const existingContent = await requireFile(filePath)
+  let nextContent = existingContent
+
+  const updated = getArgValue(args, 'updated')
+
+  if (updated || Object.keys(args).length > 0) {
+    nextContent = replaceMarkdownSection(
+      nextContent,
+      'Last Update',
+      updated === undefined || updated === 'now' ? nowTimestamp() : updated,
+    )
+  }
+
+  const done = getArgList(args, 'done')
+  const state = getArgList(args, 'state')
+  const next = getArgList(args, 'next')
+  const issues = getArgList(args, 'issue')
+  const notes = getArgList(args, 'note')
+
+  if (done.length > 0) {
+    nextContent = replaceMarkdownSection(nextContent, 'What Was Done', formatBullets(done))
+  }
+
+  if (state.length > 0) {
+    nextContent = replaceMarkdownSection(nextContent, 'Current State', formatBullets(state))
+  }
+
+  if (next.length > 0) {
+    nextContent = replaceMarkdownSection(nextContent, 'Next Steps', formatBullets(next))
+  }
+
+  if (issues.length > 0) {
+    nextContent = replaceMarkdownSection(nextContent, 'Known Issues', formatBullets(issues))
+  }
+
+  if (notes.length > 0) {
+    nextContent = replaceMarkdownSection(nextContent, 'Notes', formatBullets(notes))
+  }
+
+  await writeTextFile(filePath, nextContent)
+  process.stderr.write(`Updated ${filePath}\n`)
+}
+
+async function appendWorkLog() {
+  const filePath = path.join(aiDir, 'work-log.md')
+  const existingContent = await requireFile(filePath)
+  const timestamp = getArgValue(args, 'timestamp')
+  const messages = getArgList(args, 'message')
+
+  if (messages.length === 0) {
+    throw new Error('ai:update:log requires at least one --message value.')
+  }
+
+  const nextContent = `${existingContent.trimEnd()}\n\n## ${
+    timestamp === undefined || timestamp === 'now' ? nowTimestamp() : timestamp
+  }\n\n${formatBullets(messages)}\n`
+  await writeTextFile(filePath, nextContent)
+  process.stderr.write(`Updated ${filePath}\n`)
+}
+
+async function appendDecision() {
+  const filePath = path.join(aiDir, 'decisions.md')
+  const existingContent = await requireFile(filePath)
+  const timestamp = getArgValue(args, 'timestamp')
+  const title = getArgValue(args, 'title')
+  const decision = getArgList(args, 'decision')
+  const reason = getArgList(args, 'reason')
+  const impact = getArgList(args, 'impact')
+
+  if (decision.length === 0 || reason.length === 0 || impact.length === 0) {
+    throw new Error('ai:update:decision requires --decision, --reason, and --impact values.')
+  }
+
+  const heading = title
+    ? `## ${timestamp === undefined || timestamp === 'now' ? nowTimestamp() : timestamp} (${title})`
+    : `## ${timestamp === undefined || timestamp === 'now' ? nowTimestamp() : timestamp}`
+
+  const block = `${heading}\n\nDecision:\n${formatBullets(decision)}\n\nReason:\n${formatBullets(reason)}\n\nImpact:\n${formatBullets(impact)}\n`
+  const nextContent = existingContent.replace(/^# Decisions\r?\n\r?\n/, `# Decisions\n\n${block}\n`)
+
+  await writeTextFile(filePath, nextContent)
+  process.stderr.write(`Updated ${filePath}\n`)
+}
+
+async function appendChangedFile() {
+  const filePath = path.join(aiDir, 'changed-files.md')
+  const existingContent = await requireFile(filePath)
+  const changedFile = getArgValue(args, 'file')
+  const notes = getArgList(args, 'note')
+
+  if (!changedFile || notes.length === 0) {
+    throw new Error('ai:update:changed requires --file and at least one --note value.')
+  }
+
+  const block = `\n[${changedFile}]\n${formatBullets(notes)}\n`
+  const nextContent = `${existingContent.trimEnd()}${block}`
+
+  await writeTextFile(filePath, nextContent)
+  process.stderr.write(`Updated ${filePath}\n`)
+}
+
+async function requireFile(filePath) {
+  const content = await readTextIfExists(filePath)
+
+  if (content === null) {
+    throw new Error(`Missing required file: ${filePath}`)
+  }
+
+  return content
+}

package/scripts/bootstrap-agent-memory.mjs

@@ -0,0 +1,23 @@
+import path from 'node:path'
+
+import { ensureAgentMemory } from './agent-memory-lib.mjs'
+import { writeAceBanner } from './ai-memory-utils.mjs'
+
+const targetDir = process.argv[2] ? path.resolve(process.cwd(), process.argv[2]) : process.cwd()
+
+writeAceBanner()
+
+const result = await ensureAgentMemory(targetDir)
+
+if (result.createdFiles.length === 0 && result.updatedFiles.length === 0) {
+  process.stderr.write(`ACE memory is already up to date in ${targetDir}\n`)
+  process.exit(0)
+}
+
+if (result.updatedFiles.length > 0) {
+  process.stderr.write(`Updated: ${result.updatedFiles.join(', ')}\n`)
+}
+
+if (result.createdFiles.length > 0) {
+  process.stderr.write(`Created: ${result.createdFiles.join(', ')}\n`)
+}

package/scripts/check-agent-memory.mjs

@@ -0,0 +1,22 @@
+import path from 'node:path'
+
+import { validateAgentMemory } from './agent-memory-lib.mjs'
+import { writeAceBanner } from './ai-memory-utils.mjs'
+
+const targetDir = process.argv[2] ? path.resolve(process.cwd(), process.argv[2]) : process.cwd()
+
+writeAceBanner()
+
+const issues = await validateAgentMemory(targetDir)
+
+if (issues.length > 0) {
+  process.stderr.write(`ACE memory check failed for ${targetDir}\n`)
+
+  for (const issue of issues) {
+    process.stderr.write(`- ${issue}\n`)
+  }
+
+  process.exit(1)
+}
+
+process.stderr.write(`ACE memory check passed for ${targetDir}\n`)