feat(cli): add validate command for source document validation

This commit adds a new `validate` CLI command that runs source validation
for agent-html documents without producing runtime build output. It also
updates project roadmap and component adoption documentation:
1. Defines standardized component expansion rhythm grouped by archetypes
2. Locks down public contract to semantic fields only
3. Moves detailed component status to spec/components-adoption.md

Author: Sayhi-bzb

packages/ahtml/src/cli/artifact-workflow.mjs

@@ -133,11 +133,36 @@ export function createArtifactWorkflow({
     return parseJson(source, "agent-html.inspect.json must be valid JSON.")
   }
 
+  async function validateDocument(inputPath, options = {}) {
+    const inputFilePath = path.resolve(userRoot, inputPath)
+    const source = await readFile(inputFilePath, "utf8")
+    const validation = await validateAgentHtmlSource(source)
+
+    if (validation.diagnostics.length > 0) {
+      if (options.printDiagnostics !== false) {
+        printDiagnostics(validation.diagnostics)
+      }
+      process.exitCode = 1
+      return createValidationResult({
+        diagnostics: validation.diagnostics,
+        inputPath: inputFilePath,
+        ok: false,
+      })
+    }
+
+    return createValidationResult({
+      inputPath: inputFilePath,
+      inspection: createInspection(validation.document),
+      ok: true,
+    })
+  }
+
   return {
     buildArtifact,
     ensureManagedRuntime,
     inspectArtifactDir,
     inspectDocument,
+    validateDocument,
   }
 }
 
@@ -178,6 +203,17 @@ function createBuildResult({
   }
 }
 
+function createValidationResult({ diagnostics = [], inputPath, inspection, ok }) {
+  return {
+    kind: "agent-html-validation-result",
+    version: 1,
+    ok,
+    inputPath,
+    ...(inspection ? { inspection } : {}),
+    ...(diagnostics.length > 0 ? { diagnostics } : {}),
+  }
+}
+
 export function formatInspectionSummary(inspection) {
   const lines = [
     "agent-html inspection",

packages/ahtml/src/cli/commands.mjs

@@ -59,6 +59,22 @@ export const commandMetadata = {
     ],
     example: "ahtml prompt",
   },
+  validate: {
+    summary: "Validate a source document without building runtime output.",
+    purpose:
+      "Run source validation and return structured diagnostics or inspection metadata.",
+    usage: "ahtml validate --input <path> [--format text|json]",
+    options: [
+      { name: "input", description: "Agent-html document path.", value: true },
+      {
+        name: "format",
+        description: "Output format. Defaults to text.",
+        value: true,
+      },
+    ],
+    example: `ahtml validate --input ${cliDefaults.documentPath} --format json`,
+    hidden: true,
+  },
   build: {
     summary: "Validate and build a static HTML artifact.",
     purpose: "Validate, sanitize, and build a static artifact directory.",

packages/ahtml/src/cli/index.mjs

@@ -53,6 +53,7 @@ const {
   ensureManagedRuntime,
   inspectArtifactDir,
   inspectDocument,
+  validateDocument,
 } = createArtifactWorkflow({
   userRoot,
   defaultOutputDir,
@@ -65,6 +66,7 @@ const args = process.argv.slice(3)
 const commandHandlers = {
   setup: setupCommand,
   prompt: promptCommand,
+  validate: validateCommand,
   build: buildCommand,
   inspect: inspectCommand,
   preview: previewCommand,
@@ -271,6 +273,37 @@ async function buildCommand(commandArgs, definition) {
   }
 }
 
+async function validateCommand(commandArgs, definition) {
+  const { options, positionals } = parseOptions(commandArgs, definition)
+
+  if (positionals.length > 0) {
+    fail(`Unexpected argument "${positionals[0]}".`)
+  }
+
+  if (!options.input) {
+    fail("validate requires --input <path>.")
+  }
+
+  const format = options.format ?? "text"
+
+  if (format !== "text" && format !== "json") {
+    fail('validate --format must be "text" or "json".')
+  }
+
+  const result = await validateDocument(options.input, {
+    printDiagnostics: format !== "json",
+  })
+
+  if (format === "json") {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+    return
+  }
+
+  if (result.ok) {
+    process.stdout.write(formatInspectionSummary(result.inspection))
+  }
+}
+
 async function previewCommand(commandArgs, definition) {
   const { options, positionals } = parseOptions(commandArgs, definition)
   const inputPath = options.input ?? positionals[0] ?? cliDefaults.documentPath

spec/map.md

@@ -54,6 +54,13 @@ components plus named presentation profiles on the public side, and
 shadcn-native template/init/registry plus internal capability verification on
 the runtime side.
 
+Current expansion posture: do not respond to that gap by expanding the public
+parameter bag or by adding isolated components one by one. The current
+execution rhythm is to keep the public contract semantic and profile-first,
+keep shadcn details inside the managed runtime, then expand breadth by adding
+shared renderer archetypes and admitting components in grouped waves. Detailed
+component grouping and sequencing now live in `spec/components-adoption.md`.
+
 ## Final Decisions
 
 These decisions are locked for the next implementation pass.
@@ -385,6 +392,10 @@ fields and generic ui/slot compatibility paths.
 - The generic registry / resolver layer remains the key product layer on the
   runtime side. It must map semantic agent-html into legal shadcn/native React
   composition without one-off adapters for each component.
+- Broader component coverage should follow grouped semantic adoption, not
+  opportunistic shadcn install order. The next expansion path is `progress`,
+  then `field/control`, then `option-set`; overlay, menu, navigation, and
+  app-shell semantics remain out of the near-term lane.
 - Generic fallback is no longer the renderer path for unsupported component
   names; build now emits structured runtime-render diagnostics before
   SSR/runtime failure.

spec/roadmap.md

@@ -15,6 +15,40 @@ semantic component contract
   -> shadcn/native artifact
 ```
 
+## Current Execution Rhythm
+
+当前主线不是继续扩张 public 参数数量，也不是直接铺开新组件数量。
+
+当前主线是：
+
+1. 继续收紧 public contract。
+2. 继续把 shadcn 细节留在 runtime 内部。
+3. 先补通用 renderer archetype，再按 archetype 成批扩组件。
+
+### Parameter And Data-Dimension Priorities
+
+- public 参数继续收敛到语义字段，而不是视觉实现字段。
+- 优先规范的内容维度是 `title`、`label`、`description`、`value`、`text`。
+- 优先规范的状态维度是 `tone`、`kind`、`default`、`required`、`disabled`、
+  `invalid`。
+- 优先规范的结构维度是 `item`、`row`、`cell`、`tab`、`accordion-item`，以及
+  未来 `option` 一类受控结构节点。
+- 当前不应继续扩张 `variant`、`size`、`surface`、`radius`、`spacing`、
+  `className` 或 raw shadcn props 这类 public 参数面。
+
+### Component Expansion Order
+
+- 第一步先接 `progress`，验证新增只读显示型组件能否低成本进入 schema、
+  renderer、runtime verification 和 artifact tests。
+- 第二步补 `field/control` archetype，再按该 contract 成批接入 `textarea`、
+  `input`、`checkbox`、`radio-group`。
+- 第三步补 `option-set` archetype，再按该 contract 成批接入 `toggle-group`、
+  `select`、`combobox`。
+- `dialog`、`sheet`、`drawer`、`popover`、`tooltip`、menu、navigation 和
+  app-shell 语义不属于当前近期开发表。
+
+Detailed component status and grouping now live in `spec/components-adoption.md`.
+
 ## Phase 1: Lock The Public Contract
 
 - 对外 authoring contract 只保留语义组件和 profile 选择。
@@ -147,6 +181,16 @@ Done when:
   必须作为真实语义能力返回，而不是直接暴露底层 shadcn 细节。
 - 不重新长出第二套 ahtml UI framework，也不重新长出第二套对外 runtime 协议。
 
+Current state:
+
+- 已明确当前组件接入节奏：先 `progress`，再 `field/control`，再 `option-set`，
+  不直接扩到 overlay、menu 或 navigation。
+- 已明确当前参数策略：继续收紧到语义字段，不继续扩张视觉实现字段或 raw shadcn
+  props。
+- 已新增 `spec/components-adoption.md` 作为组件接入分组和优先级清单。
+
 Done when:
 
 - 扩展组件目录不会重新把 agent-facing 合同拖回 runtime-first 思路。
+- 新增组件的实现顺序默认由 archetype 和 adoption status 驱动，而不是按 shadcn
+  安装便利度零散扩张。