@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.131

package/tools/visual-baseline/index.mjs

@@ -0,0 +1,522 @@
+import { createPublicKey, verify } from 'node:crypto'
+import { existsSync, lstatSync, readdirSync } from 'node:fs'
+import { relative, resolve, sep } from 'node:path'
+import { PNG } from 'pngjs'
+import {
+  SHA256_PATTERN,
+  applyAtomicOperations,
+  assertSafeExistingPath,
+  canonicalRoot,
+  compareUtf8Bytes,
+  exactKeys,
+  isContained,
+  portablePath,
+  readStableFile,
+  sha256,
+  stableStringify,
+} from '../shared/safe-filesystem.mjs'
+import {
+  assertClosedGitLocalConfiguration,
+  runClosedGit,
+} from '../../ds-canonical/fork/common/closed-tool-execution.mjs'
+
+export const VISUAL_BASELINE_TOOL_VERSION = '1.0.0'
+export const VISUAL_BASELINE_PNG_PARSER_VERSION = 'pngjs@7.0.0'
+const PROPOSAL_KIND = 'qijenchen-visual-baseline-proposal'
+const REVIEW_DOMAIN = 'qijenchen.visual-baseline.review.v1'
+const REVIEW_POLICY_SCHEMA_REFERENCE = './schemas/visual-baseline-review-policy.schema.json'
+const REVIEW_ISSUERS_RELATIVE_PATH = 'trust/issuers.json'
+const REVIEW_TRUST_ROLES = Object.freeze([
+  Object.freeze({
+    id: 'authority',
+    markerPath: 'infra/governance',
+    policyPath: 'infra/governance/visual-baseline-review-policy.json',
+    issuerRegistryPath: 'infra/governance/trust/issuers.json',
+  }),
+  Object.freeze({
+    id: 'consumer',
+    markerPath: 'governance',
+    policyPath: 'governance/visual-baseline-review-policy.json',
+    issuerRegistryPath: 'governance/trust/issuers.json',
+  }),
+])
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+function fail(message) {
+  throw new Error(`visual baseline review blocked:${message}`)
+}
+
+function readJsonAuthority(root, path, label) {
+  const read = readStableFile(root, path, label, fail)
+  let value
+  try { value = JSON.parse(read.bytes.toString('utf8')) } catch (error) { fail(`${label} is invalid JSON:${error.message}`) }
+  return { ...read, value }
+}
+
+function gitRead(root, args, label) {
+  try {
+    assertClosedGitLocalConfiguration(root)
+    const result = runClosedGit(args, {
+      cwd: resolve(root),
+      timeoutMs: 10_000,
+    })
+    if (result.error || result.signal !== null || result.status !== 0) {
+      fail(`${label} is unavailable through the closed Git runtime`)
+    }
+    const value = result.stdout.trim()
+    if (!value || /[\0\r\n]/.test(value)) fail(`${label} is empty or non-canonical`)
+    return value
+  } catch (error) {
+    if (String(error.message).startsWith('visual baseline review blocked:')) throw error
+    fail(`${label} is unavailable:${String(error.stderr || error.message).trim()}`)
+  }
+}
+
+function canonicalRemoteIdentity(value) {
+  let remote = value
+  if (/^[^@\s]+@[^:\s]+:.+$/.test(remote)) {
+    const match = remote.match(/^[^@\s]+@([^:\s]+):(.+)$/)
+    remote = `ssh://${match[1]}/${match[2]}`
+  }
+  let parsed
+  try { parsed = new URL(remote) } catch { fail('origin remote must be a canonical HTTPS or SSH repository URL') }
+  if (!['https:', 'ssh:'].includes(parsed.protocol) || !parsed.hostname || parsed.search || parsed.hash || parsed.pathname.includes('%')) {
+    fail('origin remote must be a canonical credential-free HTTPS or SSH repository URL')
+  }
+  const path = parsed.pathname.replace(/^\/+|\/+$/g, '').replace(/\.git$/i, '')
+  if (!path || path.split('/').some((part) => !part || part === '.' || part === '..' || /[\\\0\r\n]/.test(part))) {
+    fail('origin remote repository path is invalid')
+  }
+  const host = `${parsed.hostname.toLowerCase()}${parsed.port ? `:${parsed.port}` : ''}`
+  return `${host}/${path}`
+}
+
+function repositoryBinding(root) {
+  const topLevel = canonicalRoot(gitRead(root, ['rev-parse', '--show-toplevel'], 'Git repository top level'), 'Git repository top level', fail)
+  if (topLevel !== root) fail('visual baseline --root must equal the Git repository top level')
+  const headCommit = gitRead(root, ['rev-parse', '--verify', 'HEAD^{commit}'], 'Git HEAD commit')
+  const headTree = gitRead(root, ['rev-parse', '--verify', 'HEAD^{tree}'], 'Git HEAD tree')
+  if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(headCommit) || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(headTree)) {
+    fail('Git HEAD commit/tree identity is invalid')
+  }
+  return {
+    identity: canonicalRemoteIdentity(gitRead(root, ['remote', 'get-url', 'origin'], 'Git origin remote')),
+    headCommit,
+    headTree,
+  }
+}
+
+function assertRepositoryBinding(root, expected) {
+  if (stableStringify(repositoryBinding(root)) !== stableStringify(expected)) {
+    fail('repository origin/HEAD commit/tree differs from the proposal trust domain')
+  }
+}
+
+function selectReviewTrustRole(root) {
+  const present = REVIEW_TRUST_ROLES.filter((role) => existsSync(resolve(root, role.policyPath)))
+  if (present.length > 1) fail('authority and consumer visual-review policies cannot coexist in one repository')
+  if (present.length === 1) return present[0]
+  return REVIEW_TRUST_ROLES.find((role) => role.id === (
+    existsSync(resolve(root, REVIEW_TRUST_ROLES[0].markerPath)) ? 'authority' : 'consumer'
+  ))
+}
+
+function roleForTrustDescriptor(descriptor) {
+  return REVIEW_TRUST_ROLES.find((role) => role.policyPath === descriptor.policyPath) ?? null
+}
+
+function loadReviewTrust(root) {
+  const role = selectReviewTrustRole(root)
+  const unavailable = {
+    status: 'not-activated',
+    policyPath: role.policyPath,
+    policySha256: null,
+    issuerRegistryPath: role.issuerRegistryPath,
+    issuerRegistrySha256: null,
+    managedActivationEvidencePath: null,
+    managedActivationEvidenceSha256: null,
+  }
+  if (!existsSync(resolve(root, role.policyPath))) return { descriptor: unavailable, policy: null, issuers: null, activation: null }
+  const policyRead = readJsonAuthority(root, role.policyPath, 'visual review trust policy')
+  const policy = policyRead.value
+  exactKeys(policy, ['$schema', 'schemaVersion', 'kind', 'status', 'issuerRegistryPath', 'issuerRegistrySha256', 'human', 'managedBroker'], 'visual review trust policy', fail)
+  if (policy.schemaVersion !== 1 || policy.kind !== 'visual-baseline-review-trust-policy'
+    || policy.$schema !== REVIEW_POLICY_SCHEMA_REFERENCE
+    || !['active', 'not-activated'].includes(policy.status) || policy.issuerRegistryPath !== REVIEW_ISSUERS_RELATIVE_PATH) fail('visual review trust policy identity is invalid')
+  exactKeys(policy.human, ['status', 'allowedKeyIds'], 'visual review human policy', fail)
+  exactKeys(policy.managedBroker, ['status', 'allowedKeyIds', 'activationEvidencePath', 'activationEvidenceSha256', 'modelAuthorityPolicyDigest', 'brokerPolicyDigest'], 'visual review managed-broker policy', fail)
+  for (const branch of [policy.human, policy.managedBroker]) {
+    if (!['active', 'not-activated'].includes(branch.status) || !Array.isArray(branch.allowedKeyIds)
+      || new Set(branch.allowedKeyIds).size !== branch.allowedKeyIds.length
+      || branch.allowedKeyIds.some((key) => typeof key !== 'string' || !/^[a-z0-9][a-z0-9._-]*$/.test(key))) fail('visual review trust policy key allowlist is invalid')
+  }
+  if ((policy.status === 'active') !== (policy.human.status === 'active')) fail('visual review trust policy aggregate activation status is inconsistent')
+  if ((policy.human.status === 'active' && policy.human.allowedKeyIds.length === 0)
+    || (policy.human.status === 'not-activated' && policy.human.allowedKeyIds.length !== 0)) fail('visual review trust branch activation/key allowlist is inconsistent')
+  if (policy.managedBroker.status !== 'not-activated' || policy.managedBroker.allowedKeyIds.length !== 0
+    || [policy.managedBroker.activationEvidencePath, policy.managedBroker.activationEvidenceSha256,
+      policy.managedBroker.modelAuthorityPolicyDigest, policy.managedBroker.brokerPolicyDigest].some((value) => value !== null)) {
+    fail('managed visual review is reserved but not activated in this tool version; a future version must reuse the canonical signed model-broker receipt validators')
+  }
+  const issuerRead = readJsonAuthority(root, role.issuerRegistryPath, 'visual review issuer registry')
+  if (!SHA256_PATTERN.test(policy.issuerRegistrySha256) || issuerRead.sha256 !== policy.issuerRegistrySha256) fail('visual review issuer registry digest is stale')
+  const issuers = issuerRead.value
+  exactKeys(issuers, ['$schema', 'schemaVersion', 'algorithm', 'issuers'], 'visual review issuer registry', fail)
+  if (issuers.schemaVersion !== 1 || issuers.algorithm !== 'ed25519' || !Array.isArray(issuers.issuers)) fail('visual review issuer registry is invalid')
+  const descriptor = {
+    status: policy.status,
+    policyPath: role.policyPath,
+    policySha256: policyRead.sha256,
+    issuerRegistryPath: role.issuerRegistryPath,
+    issuerRegistrySha256: issuerRead.sha256,
+    managedActivationEvidencePath: null,
+    managedActivationEvidenceSha256: null,
+  }
+  return { descriptor, policy, issuers, activation: null }
+}
+
+function sameReviewTrust(left, right) {
+  return stableStringify(left) === stableStringify(right)
+}
+
+function safeRootPath(root, value, label) {
+  const absolute = resolve(root, value)
+  if (!isContained(root, absolute)) fail(`${label} must be below the repository root`)
+  assertSafeExistingPath(root, absolute, label, fail, { kind: 'directory' })
+  const path = relative(root, absolute).split(sep).join('/')
+  return portablePath(path, label, fail)
+}
+
+function inventoryImages(root, directory, { candidate }) {
+  const rows = []
+  const absoluteRoot = resolve(root, directory)
+  const visit = (relativeDirectory) => {
+    const absolute = relativeDirectory ? resolve(absoluteRoot, relativeDirectory) : absoluteRoot
+    for (const entry of readdirSync(absolute, { withFileTypes: true })
+      .sort((a, b) => compareUtf8Bytes(a.name, b.name))) {
+      const child = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name
+      const full = resolve(absoluteRoot, child)
+      const info = lstatSync(full)
+      if (entry.isSymbolicLink() || info.isSymbolicLink()) fail(`${candidate ? 'candidate' : 'baseline'} inventory crosses a symbolic link:${child}`)
+      if (entry.isDirectory()) {
+        visit(child)
+        continue
+      }
+      if (!entry.isFile() || !info.isFile() || info.nlink !== 1) fail(`${candidate ? 'candidate' : 'baseline'} inventory contains an unsafe entry:${child}`)
+      if (!child.toLowerCase().endsWith('.png')) {
+        if (candidate) fail(`candidate inventory contains a non-PNG file:${child}`)
+        continue
+      }
+      const repositoryPath = `${directory}/${child}`
+      const read = readStableFile(root, repositoryPath, `${candidate ? 'candidate' : 'baseline'} image ${child}`, fail)
+      if (read.bytes.length < PNG_MAGIC.length || !read.bytes.subarray(0, PNG_MAGIC.length).equals(PNG_MAGIC)) fail(`image lacks the canonical PNG signature:${repositoryPath}`)
+      try {
+        const decoded = PNG.sync.read(read.bytes, { checkCRC: true })
+        if (!Number.isSafeInteger(decoded.width) || decoded.width < 1 || !Number.isSafeInteger(decoded.height) || decoded.height < 1) fail(`image has invalid decoded dimensions:${repositoryPath}`)
+      } catch (error) {
+        if (String(error.message).startsWith('visual baseline review blocked:')) throw error
+        fail(`image is not a complete CRC-valid decodable PNG:${repositoryPath}:${error.message}`)
+      }
+      rows.push({ path: child, sha256: read.sha256, bytes: read.size, mode: read.mode })
+    }
+  }
+  visit('')
+  return rows.sort((a, b) => compareUtf8Bytes(a.path, b.path))
+}
+
+function descriptor(row) {
+  return row ? { sha256: row.sha256, bytes: row.bytes } : null
+}
+
+function changedImages(proposal) {
+  return proposal.images.filter((row) => row.action !== 'unchanged')
+}
+
+export function visualBaselineProposalDigest(proposal) {
+  const projection = structuredClone(proposal)
+  delete projection.proposalDigest
+  return sha256(stableStringify(projection))
+}
+
+export function planVisualBaseline({ repoRoot = process.cwd(), candidateRoot, baselineRoot, statements, authorIdentity } = {}) {
+  const root = canonicalRoot(repoRoot, 'visual baseline repository root', fail)
+  if (typeof authorIdentity !== 'string' || authorIdentity.trim().length < 3) fail('an explicit proposal author identity is required')
+  const candidate = safeRootPath(root, candidateRoot, 'candidate root')
+  const baseline = safeRootPath(root, baselineRoot, 'baseline root')
+  const candidateAbsolute = resolve(root, candidate)
+  const baselineAbsolute = resolve(root, baseline)
+  if (isContained(candidateAbsolute, baselineAbsolute, { allowRoot: true })
+    || isContained(baselineAbsolute, candidateAbsolute, { allowRoot: true })) fail('candidate and baseline roots must be disjoint')
+  if (!statements || typeof statements !== 'object' || Array.isArray(statements)) fail('a per-image statements object is required')
+  const candidateInventory = inventoryImages(root, candidate, { candidate: true })
+  const baselineInventory = inventoryImages(root, baseline, { candidate: false })
+  if (!candidateInventory.length) fail('candidate inventory contains no PNG images')
+  const candidates = new Map(candidateInventory.map((row) => [row.path, row]))
+  const baselines = new Map(baselineInventory.map((row) => [row.path, row]))
+  const paths = [...new Set([...candidates.keys(), ...baselines.keys()])].sort(compareUtf8Bytes)
+  const images = paths.map((path) => {
+    const candidateRow = candidates.get(path) ?? null
+    const baselineRow = baselines.get(path) ?? null
+    const action = !baselineRow ? 'create' : !candidateRow ? 'delete'
+      : baselineRow.sha256 === candidateRow.sha256 ? 'unchanged' : 'replace'
+    const statement = action === 'unchanged' ? null : statements[path]
+    if (action !== 'unchanged' && (typeof statement !== 'string' || statement.trim().length < 12
+      || /^(?:todo|tbd|same|looks good|approved|unknown|n\/a)$/i.test(statement.trim()))) {
+      fail(`changed image requires an explicit visual diff statement:${path}`)
+    }
+    return { path, action, baseline: descriptor(baselineRow), candidate: descriptor(candidateRow), statement: statement?.trim() ?? null }
+  })
+  const expectedStatementPaths = images.filter((row) => row.action !== 'unchanged').map((row) => row.path)
+  if (stableStringify(Object.keys(statements).sort(compareUtf8Bytes)) !== stableStringify(expectedStatementPaths)) fail('statement keys must equal the exact changed-image set')
+  const proposal = {
+    schemaVersion: 1,
+    kind: PROPOSAL_KIND,
+    toolVersion: VISUAL_BASELINE_TOOL_VERSION,
+    pngParserVersion: VISUAL_BASELINE_PNG_PARSER_VERSION,
+    reviewDomain: REVIEW_DOMAIN,
+    repository: repositoryBinding(root),
+    authorIdentity: authorIdentity.trim(),
+    candidateRoot: candidate,
+    baselineRoot: baseline,
+    candidateInventory,
+    baselineInventory,
+    images,
+    reviewTrust: loadReviewTrust(root).descriptor,
+    proposalDigest: '',
+  }
+  proposal.proposalDigest = visualBaselineProposalDigest(proposal)
+  validateVisualBaselineProposal(proposal)
+  return proposal
+}
+
+function validateInventory(rows, label) {
+  if (!Array.isArray(rows)) fail(`${label} must be an array`)
+  const paths = []
+  for (const row of rows) {
+    exactKeys(row, ['path', 'sha256', 'bytes', 'mode'], `${label} row`, fail)
+    portablePath(row.path, `${label} path`, fail)
+    if (!row.path.toLowerCase().endsWith('.png') || !SHA256_PATTERN.test(row.sha256)
+      || !Number.isSafeInteger(row.bytes) || row.bytes < PNG_MAGIC.length
+      || !Number.isInteger(row.mode) || row.mode < 0 || row.mode > 0o777) fail(`${label} row is invalid:${row.path}`)
+    paths.push(row.path)
+  }
+  if (stableStringify(paths) !== stableStringify([...new Set(paths)].sort(compareUtf8Bytes))) fail(`${label} is not unique and sorted`)
+}
+
+function validateDescriptor(value, label, allowNull) {
+  if (value === null && allowNull) return
+  exactKeys(value, ['sha256', 'bytes'], label, fail)
+  if (!SHA256_PATTERN.test(value.sha256) || !Number.isSafeInteger(value.bytes) || value.bytes < PNG_MAGIC.length) fail(`${label} is invalid`)
+}
+
+export function validateVisualBaselineProposal(proposal) {
+  exactKeys(proposal, ['schemaVersion', 'kind', 'toolVersion', 'pngParserVersion', 'reviewDomain', 'repository', 'authorIdentity', 'candidateRoot', 'baselineRoot', 'candidateInventory', 'baselineInventory', 'images', 'reviewTrust', 'proposalDigest'], 'visual baseline proposal', fail)
+  if (proposal.schemaVersion !== 1 || proposal.kind !== PROPOSAL_KIND || proposal.toolVersion !== VISUAL_BASELINE_TOOL_VERSION
+    || proposal.pngParserVersion !== VISUAL_BASELINE_PNG_PARSER_VERSION
+    || proposal.reviewDomain !== REVIEW_DOMAIN
+    || typeof proposal.authorIdentity !== 'string' || proposal.authorIdentity.trim().length < 3
+    || !SHA256_PATTERN.test(proposal.proposalDigest) || proposal.proposalDigest !== visualBaselineProposalDigest(proposal)) fail('visual baseline proposal identity or digest is invalid')
+  exactKeys(proposal.repository, ['identity', 'headCommit', 'headTree'], 'visual baseline repository binding', fail)
+  if (typeof proposal.repository.identity !== 'string' || !/^[a-z0-9.-]+(?::[0-9]+)?\/[A-Za-z0-9._~/-]+$/.test(proposal.repository.identity)
+    || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(proposal.repository.headCommit)
+    || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(proposal.repository.headTree)) fail('visual baseline repository binding is invalid')
+  portablePath(proposal.candidateRoot, 'candidate root', fail)
+  portablePath(proposal.baselineRoot, 'baseline root', fail)
+  validateInventory(proposal.candidateInventory, 'candidate inventory')
+  validateInventory(proposal.baselineInventory, 'baseline inventory')
+  exactKeys(proposal.reviewTrust, ['status', 'policyPath', 'policySha256', 'issuerRegistryPath', 'issuerRegistrySha256', 'managedActivationEvidencePath', 'managedActivationEvidenceSha256'], 'visual review trust descriptor', fail)
+  const trustRole = roleForTrustDescriptor(proposal.reviewTrust)
+  if (!['active', 'not-activated'].includes(proposal.reviewTrust.status) || !trustRole
+    || proposal.reviewTrust.issuerRegistryPath !== trustRole.issuerRegistryPath) fail('visual review trust descriptor identity is invalid')
+  for (const key of ['policySha256', 'issuerRegistrySha256', 'managedActivationEvidenceSha256']) {
+    if (proposal.reviewTrust[key] !== null && !SHA256_PATTERN.test(proposal.reviewTrust[key])) fail(`visual review trust ${key} is invalid`)
+  }
+  if (proposal.reviewTrust.managedActivationEvidencePath !== null
+    || proposal.reviewTrust.managedActivationEvidenceSha256 !== null) fail('managed visual review activation evidence is not supported by this tool version')
+  if (!Array.isArray(proposal.images) || !proposal.images.length) fail('visual baseline proposal images are empty')
+  const imagePaths = []
+  for (const row of proposal.images) {
+    exactKeys(row, ['path', 'action', 'baseline', 'candidate', 'statement'], 'visual baseline image', fail)
+    portablePath(row.path, 'visual baseline image path', fail)
+    if (!['create', 'replace', 'delete', 'unchanged'].includes(row.action)) fail(`visual baseline image action is invalid:${row.path}`)
+    validateDescriptor(row.baseline, `${row.path} baseline descriptor`, true)
+    validateDescriptor(row.candidate, `${row.path} candidate descriptor`, true)
+    const expectedAction = !row.baseline ? 'create' : !row.candidate ? 'delete'
+      : row.baseline.sha256 === row.candidate.sha256 ? 'unchanged' : 'replace'
+    if (row.action !== expectedAction) fail(`visual baseline image action/digest mismatch:${row.path}`)
+    if (row.action === 'unchanged' ? row.statement !== null
+      : typeof row.statement !== 'string' || row.statement.length < 12) fail(`visual baseline image statement is invalid:${row.path}`)
+    imagePaths.push(row.path)
+  }
+  if (stableStringify(imagePaths) !== stableStringify([...new Set(imagePaths)].sort(compareUtf8Bytes))) fail('visual baseline image paths are not unique and sorted')
+  const candidateProjection = proposal.images.filter((row) => row.candidate).map((row) => ({ path: row.path, ...row.candidate }))
+  const baselineProjection = proposal.images.filter((row) => row.baseline).map((row) => ({ path: row.path, ...row.baseline }))
+  const stripMode = (rows) => rows.map(({ path, sha256: digest, bytes }) => ({ path, sha256: digest, bytes }))
+  if (stableStringify(candidateProjection) !== stableStringify(stripMode(proposal.candidateInventory))
+    || stableStringify(baselineProjection) !== stableStringify(stripMode(proposal.baselineInventory))) fail('visual baseline image rows do not close both inventories')
+  return true
+}
+
+function reviewRows(proposal) {
+  return changedImages(proposal).map((row) => ({
+    path: row.path,
+    baselineSha256: row.baseline?.sha256 ?? null,
+    candidateSha256: row.candidate?.sha256 ?? null,
+    statement: row.statement,
+    decision: 'approved',
+  }))
+}
+
+function validateReviewRows(images, proposal) {
+  if (!Array.isArray(images)) fail('review images must be an array')
+  for (const row of images) {
+    exactKeys(row, ['path', 'baselineSha256', 'candidateSha256', 'statement', 'decision'], 'review image', fail)
+    portablePath(row.path, 'review image path', fail)
+    if ((row.baselineSha256 !== null && !SHA256_PATTERN.test(row.baselineSha256))
+      || (row.candidateSha256 !== null && !SHA256_PATTERN.test(row.candidateSha256))
+      || typeof row.statement !== 'string' || row.statement.length < 12 || row.decision !== 'approved') fail(`review image is invalid:${row.path}`)
+  }
+  if (stableStringify(images) !== stableStringify(reviewRows(proposal))) fail('review does not approve the exact digest-bound changed-image set')
+}
+
+function canonicalTime(value, label) {
+  if (typeof value !== 'string' || Number.isNaN(Date.parse(value)) || new Date(Date.parse(value)).toISOString() !== value) fail(`${label} must be canonical ISO-8601 UTC`)
+  return new Date(value)
+}
+
+function verifyReviewSignature({ attestation, review, proposal, trust, role, allowedKeyIds, now, label }) {
+  const issuedAt = canonicalTime(attestation.issuedAt, `${label} issuedAt`)
+  const expiresAt = canonicalTime(attestation.expiresAt, `${label} expiresAt`)
+  const current = now instanceof Date && Number.isFinite(now.getTime()) ? now : new Date(Number.NaN)
+  if (!Number.isFinite(current.getTime()) || expiresAt <= issuedAt || expiresAt.getTime() - issuedAt.getTime() > 30 * 60_000
+    || issuedAt.getTime() > current.getTime() + 5 * 60_000 || expiresAt <= current) fail(`${label} is outside its short-lived verification window`)
+  const issuer = trust.issuers.issuers.find((row) => row.keyId === attestation.signerKeyId)
+  if (!issuer || !allowedKeyIds.includes(attestation.signerKeyId) || issuer.status !== 'active'
+    || issuer.subject !== attestation.subject || !Array.isArray(issuer.roles) || !issuer.roles.includes(role)
+    || canonicalTime(issuer.notBefore, `${label} issuer notBefore`) > issuedAt
+    || canonicalTime(issuer.notAfter, `${label} issuer notAfter`) < expiresAt || issuer.revokedAt !== null) fail(`${label} signer is not an active allowlisted ${role}`)
+  const reviewCore = structuredClone(review)
+  delete reviewCore.attestation
+  if (attestation.proposalDigest !== proposal.proposalDigest || attestation.reviewDigest !== sha256(stableStringify(reviewCore))
+    || attestation.authorIdentity !== proposal.authorIdentity || attestation.issuerRegistryDigest !== trust.descriptor.issuerRegistrySha256
+    || attestation.policyDigest !== trust.descriptor.policySha256 || attestation.reviewDomain !== proposal.reviewDomain
+    || attestation.repositoryIdentity !== proposal.repository.identity || attestation.baseCommit !== proposal.repository.headCommit
+    || attestation.baseTree !== proposal.repository.headTree || review.reviewedAt !== attestation.issuedAt) fail(`${label} content/trust/repository binding is invalid`)
+  const unsigned = structuredClone(attestation)
+  delete unsigned.signature
+  try {
+    const signature = Buffer.from(attestation.signature, 'base64url')
+    if (signature.length !== 64 || signature.toString('base64url') !== attestation.signature) fail(`${label} signature encoding is not canonical`)
+    const publicKey = createPublicKey({ key: Buffer.from(issuer.publicKeySpki, 'base64'), format: 'der', type: 'spki' })
+    if (publicKey.asymmetricKeyType !== 'ed25519' || !verify(null, Buffer.from(stableStringify(unsigned)), publicKey, signature)) fail(`${label} signature is invalid`)
+  } catch (error) {
+    if (String(error.message).startsWith('visual baseline review blocked:')) throw error
+    fail(`${label} signature cannot be verified:${error.message}`)
+  }
+  return issuer
+}
+
+function verifyHumanReview(review, proposal, trust, now) {
+  exactKeys(review, ['schemaVersion', 'kind', 'proposalDigest', 'decision', 'reviewer', 'reviewedAt', 'images', 'attestation'], 'human visual review', fail)
+  if (trust.policy?.status !== 'active' || trust.policy.human.status !== 'active') fail('trusted human visual-review authority is not activated')
+  if (review.schemaVersion !== 1 || review.proposalDigest !== proposal.proposalDigest || review.decision !== 'approved'
+    || typeof review.reviewer !== 'string' || review.reviewer.trim().length < 3) fail('human visual review identity is invalid')
+  validateReviewRows(review.images, proposal)
+  const attestation = review.attestation
+  exactKeys(attestation, ['schemaVersion', 'kind', 'algorithm', 'reviewDomain', 'repositoryIdentity', 'baseCommit', 'baseTree', 'proposalDigest', 'reviewDigest', 'authorIdentity', 'issuerRegistryDigest', 'policyDigest', 'issuedAt', 'expiresAt', 'signerKeyId', 'subject', 'signature'], 'human visual review attestation', fail)
+  if (attestation.schemaVersion !== 1 || attestation.kind !== 'human-visual-baseline-review-attestation' || attestation.algorithm !== 'ed25519'
+    || attestation.subject !== review.reviewer) fail('human visual review attestation identity is invalid')
+  const issuer = verifyReviewSignature({ attestation, review, proposal, trust, role: 'visual-baseline-reviewer', allowedKeyIds: trust.policy.human.allowedKeyIds, now, label: 'human visual review attestation' })
+  return { reviewKind: review.kind, reviewer: review.reviewer, signerKeyId: issuer.keyId }
+}
+
+function verifyManagedReview(review, proposal, trust, now) {
+  void review
+  void proposal
+  void trust
+  void now
+  fail('managed-model-broker visual review is not activated in this tool version; digest-only pseudo-activation is forbidden until the canonical signed broker/model-authority validators are reused')
+}
+
+export function validateVisualBaselineReview({ review, proposal, repoRoot = process.cwd(), now = new Date() } = {}) {
+  validateVisualBaselineProposal(proposal)
+  const root = canonicalRoot(repoRoot, 'visual baseline repository root', fail)
+  assertRepositoryBinding(root, proposal.repository)
+  const trust = loadReviewTrust(root)
+  if (!sameReviewTrust(trust.descriptor, proposal.reviewTrust)) fail('visual review trust authority changed after proposal planning')
+  if (!review || typeof review !== 'object' || Array.isArray(review)) fail('review evidence is required')
+  if (review.kind === 'human-visual-baseline-review') return verifyHumanReview(review, proposal, trust, now)
+  if (review.kind === 'managed-model-broker-visual-review') return verifyManagedReview(review, proposal, trust, now)
+  fail('review kind must be explicit human review or cryptographically attested managed-model-broker review')
+}
+
+function sameInventory(left, right) {
+  return stableStringify(left) === stableStringify(right)
+}
+
+function visualState(root, proposal) {
+  const candidate = inventoryImages(root, proposal.candidateRoot, { candidate: true })
+  if (!sameInventory(candidate, proposal.candidateInventory)) fail('candidate inventory changed, gained, lost, or renamed an image after planning')
+  const baseline = inventoryImages(root, proposal.baselineRoot, { candidate: false })
+  if (sameInventory(baseline, proposal.baselineInventory)) return changedImages(proposal).length ? 'pending' : 'no-changes'
+  const expectedApplied = proposal.candidateInventory.map((row) => ({ ...row }))
+  if (sameInventory(baseline, expectedApplied)) return 'applied'
+  fail('baseline inventory is a partial, rogue, missing, or concurrently changed state')
+}
+
+export function checkVisualBaseline({ repoRoot = process.cwd(), proposal, review = null, now = new Date() } = {}) {
+  validateVisualBaselineProposal(proposal)
+  const root = canonicalRoot(repoRoot, 'visual baseline repository root', fail)
+  assertRepositoryBinding(root, proposal.repository)
+  const state = visualState(root, proposal)
+  const reviewer = review ? validateVisualBaselineReview({ review, proposal, repoRoot: root, now }) : null
+  return { proposalDigest: proposal.proposalDigest, state, changedImages: changedImages(proposal).length, review: reviewer }
+}
+
+export function applyReviewedVisualBaseline(options = {}) {
+  const allowed = new Set(['repoRoot', 'proposal', 'review', 'expectedProposalDigest', 'now'])
+  const unknown = Object.keys(options).filter((key) => !allowed.has(key))
+  if (unknown.length) fail(`apply-reviewed rejects caller callbacks and unknown trust inputs:${unknown.join(',')}`)
+  const {
+    repoRoot = process.cwd(), proposal, review, expectedProposalDigest, now = new Date(),
+  } = options
+  validateVisualBaselineProposal(proposal)
+  if (!SHA256_PATTERN.test(expectedProposalDigest ?? '') || expectedProposalDigest !== proposal.proposalDigest) fail('explicit expected proposal digest is missing or mismatched')
+  const root = canonicalRoot(repoRoot, 'visual baseline repository root', fail)
+  assertRepositoryBinding(root, proposal.repository)
+  const reviewer = validateVisualBaselineReview({ review, proposal, repoRoot: root, now })
+  const state = visualState(root, proposal)
+  if (state === 'applied' || state === 'no-changes') return { proposalDigest: proposal.proposalDigest, state, changed: 0, review: reviewer }
+  const operations = changedImages(proposal).map((row) => {
+    let afterBytes = null
+    let mode = 0o600
+    if (row.candidate) {
+      const candidate = readStableFile(root, `${proposal.candidateRoot}/${row.path}`, `reviewed candidate ${row.path}`, fail)
+      if (candidate.sha256 !== row.candidate.sha256 || candidate.size !== row.candidate.bytes) fail(`candidate changed while materializing:${row.path}`)
+      afterBytes = candidate.bytes
+      mode = candidate.mode
+    }
+    return {
+      action: row.action,
+      path: `${proposal.baselineRoot}/${row.path}`,
+      beforeSha256: row.baseline?.sha256 ?? null,
+      beforeMode: row.baseline ? proposal.baselineInventory.find((item) => item.path === row.path)?.mode : undefined,
+      afterSha256: row.candidate?.sha256 ?? null,
+      afterBytes,
+      mode,
+    }
+  })
+  const result = applyAtomicOperations({
+    root,
+    operations,
+    fail,
+    lockName: `${proposal.baselineRoot}/.qijenchen-visual-baseline.lock`,
+  })
+  if (visualState(root, proposal) !== 'applied') fail('visual baseline atomic readback did not reach the reviewed candidate inventory')
+  return { proposalDigest: proposal.proposalDigest, state: 'applied', changed: result.changed, review: reviewer }
+}
+
+export function expectedVisualReviewImages(proposal) {
+  validateVisualBaselineProposal(proposal)
+  return reviewRows(proposal)
+}

package/dist/components/NameCard/name-card.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"name-card.d.ts","sourceRoot":"","sources":["../../../src/components/NameCard/name-card.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,0CAA0C,CAAA;AAMlF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sBAAsB,+CAKlC,CAAA;AAqBD,KAAK,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;AAiBxD;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,eAAO,MAAM,2BAA2B,mCAAoC,CAAA;AAC5E,KAAK,uBAAuB,GAAG,OAAO,2BAA2B,CAAC,MAAM,CAAC,CAAA;AASzE,MAAM,WAAW,aAAc,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,aAAa,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC/B,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE,EAAE,CAAA;IACpD;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAA;IAC9E,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAGD,QAAA,MAAM,QAAQ,sFAuKb,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/NameCard/name-card.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"name-card.js","sources":["../../../src/components/NameCard/name-card.tsx"],"sourcesContent":["// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.\nimport * as React from 'react'\nimport { MessageCircle, Phone, ChevronDown } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Avatar, type AvatarData } from '@/design-system/components/Avatar/avatar'\nimport { Button } from '@/design-system/components/Button/button'\nimport { DescriptionList, DescriptionItem } from '@/design-system/components/DescriptionList/description-list'\nimport { ScrollArea } from '@/design-system/components/ScrollArea/scroll-area'\nimport { ItemContent } from '@/design-system/patterns/element-anatomy/item-anatomy'\n\n/**\n * NameCardDefaultActions — canonical 預設 action 組合\n *\n * ── 為什麼需要 export ──\n * NameCard 的 action 列在世界級 chat/contact app 是「關係型快速動作」的 canonical\n * (Slack / iMessage / LinkedIn / Figma 皆如此):**Chat / Message + Audio call**。\n * 跨 consumer(avatar.principles / name-card.stories / future product code)應該用\n * 同一組預設,避免每個範例各自發明 action 組合,讓 reader 誤以為 action 會隨情境自動變。\n *\n * ── 使用方式(hover context 必含 onViewMore,見 name-card.spec.md 「View more」節)──\n *   <NameCard name=\"...\" actions={<NameCardDefaultActions />} onViewMore={...} />\n *\n * ── 何時要換成自訂 action ──\n * - Single-action 情境(只要「傳訊息」)→ consumer 傳 `<Button>傳訊息</Button>`\n * - 特定情境的 action(管理員「撤銷邀請」/ HR「離職管理」)→ consumer 自訂\n * - 非人員關係動作(「訂購此商品」)→ 根本不應該用 NameCard\n *\n * Chat + Audio call 是 **default**,不是 **only**——consumer 可覆寫,但需有明確理由。\n */\nexport const NameCardDefaultActions = () => (\n  <>\n    <Button variant=\"tertiary\" size=\"sm\" startIcon={MessageCircle}>Chat</Button>\n    <Button variant=\"tertiary\" size=\"sm\" startIcon={Phone} endIcon={ChevronDown}>Audio call</Button>\n  </>\n)\n\n/**\n * NameCard — 人員 HoverCard 的內容元件\n *\n * ── Status 對齊 Avatar presence canonical(2026-04-20) ──\n * status type = `online | away | busy | offline`,跟 Avatar 的 presence prop 對齊\n * (世界級 Slack / Teams / Discord term);dot 色走 `--status-*` semantic token\n * (獨立於 success/error/warning,避免語義衝突)。\n *\n * ── Avatar 對齊 ──\n * 跟 FileItem rich 統一:右側 text column 用 justify-center + minHeight=avatar。\n * 短文字置中於 avatar,長文字(多行名字)自然撐高。\n *\n * ── Info fields ──\n * Status message / ID / Employee number 等唯讀屬性全部用 DescriptionList 家族\n * 承載(不手刻 dt/dd),canonical 由 DS primitive own。\n */\n\nconst AVATAR_SIZE = 64\n\ntype StatusType = 'online' | 'away' | 'busy' | 'offline'\n\n// Presence semantic tokens(見 color/semantic.css)——跟 Avatar status dot 共用\nconst STATUS_DOT_COLOR: Record<StatusType, string> = {\n  online: 'var(--status-online)',\n  away: 'var(--status-away)',\n  busy: 'var(--status-busy)',\n  offline: 'var(--status-offline)',\n}\n\nconst STATUS_LABEL: Record<StatusType, string> = {\n  online: 'Online',\n  away: 'Away',\n  busy: 'Busy',\n  offline: 'Offline',\n}\n\n/**\n * NameCard SSOT — 預設 field keys(v11 always-render canonical,2026-05-06)\n *\n * ── 為什麼 SSOT ──\n * User explicit rule:「所有 namecard 預設顯示的資訊都是要一樣完整的」。前 v10 props\n * 全 optional + body conditional render → consumer 漏傳 fields 視覺缺 section,每個範例\n * 各自不一致(同 person 在 DataTable / PeoplePicker / avatar.principles 看起來不同)。\n *\n * v11 canonical:NameCard **always** renders 4 default sections regardless of consumer 是否\n * 傳資料 — 缺 data → 對應 DescriptionItem 顯 `EMPTY_PLACEHOLDER`(\"—\"),section 結構不收合。\n * 視覺結構 SSOT 在此元件,不依賴 consumer。\n *\n * ── 對齊 world-class ──\n * Slack profile card / Linear member card / Notion person card / GitHub user card / Figma user card\n * 都是 fixed schema(role / email / location / department / department / pronouns 等),\n * 不會因為某 user 沒填 phone 整個 phone field 不見 — 缺 = 顯 `Not set` 或留白。\n *\n * ── 為什麼 placeholder 不 hide ──\n * Hide → consumer 不知道少傳 → 視覺漂移;Placeholder → 永遠看到「該欄該有」+ dev-warn 提示\n * consumer 補資料,自動防漂移(M19 ensure-canonical 對齊)。\n */\n// **2026-05-07 v15.7 user directive**:default render 只 `id` + `employeeNumber` 兩個。\n// Email / Phone / Department / Location 等其他 description 一律 opt-in by consumer 透過\n// `fields` array prop。對齊 user 明確「應該確保所有都只有這兩個,因為我並沒有要求你要選其他的」。\nexport const NAMECARD_DEFAULT_FIELD_KEYS = ['id', 'employeeNumber'] as const\ntype NameCardDefaultFieldKey = typeof NAMECARD_DEFAULT_FIELD_KEYS[number]\n\nconst DEFAULT_FIELD_LABEL: Record<NameCardDefaultFieldKey, string> = {\n  id: 'ID',\n  employeeNumber: 'Employee number',\n}\n\nconst FIELD_PLACEHOLDER = '—'\n\nexport interface NameCardProps extends React.HTMLAttributes<HTMLDivElement> {\n  name: string\n  avatar?: AvatarData\n  subtitle?: string\n  status?: StatusType\n  statusMessage?: React.ReactNode\n  actions?: React.ReactNode\n  /**\n   * Consumer 傳的 field 資料(partial)。預設 keys 走 `NAMECARD_DEFAULT_FIELD_KEYS` —\n   * email / phone / department / location 永遠 render(缺資料顯 `—`)。Consumer 想新增\n   * 自訂 field 直接傳入(在 default 之後 append),想 override default key value 也直接傳。\n   */\n  fields?: { label: string; value: React.ReactNode }[]\n  /**\n   * Default field 的真實值。Object key = NAMECARD_DEFAULT_FIELD_KEYS 之一。\n   * 缺 key → render placeholder。Dev mode 會 console.warn 提醒消費者補資料。\n   */\n  defaultFieldValues?: Partial<Record<NameCardDefaultFieldKey, React.ReactNode>>\n  onViewMore?: () => void\n  viewMoreLabel?: string\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst NameCard = React.forwardRef<HTMLDivElement, NameCardProps>(\n  (\n    {\n      name,\n      avatar,\n      subtitle,\n      status,\n      statusMessage,\n      actions,\n      fields,\n      defaultFieldValues,\n      onViewMore,\n      viewMoreLabel = 'View more',\n      className,\n      ...props\n    },\n    ref,\n  ) => {\n    // v11 always-render canonical:default fields 永遠 render(缺資料顯 placeholder),\n    // consumer 自訂 fields 在 default 之後 append。Status section 也永遠 render(無 status\n    // 顯「Status not set」placeholder),統一視覺結構。\n    //\n    // **Dedup canonical(2026-05-07 v15.8 fix Bug E)**:consumer 的 `fields` array 若含\n    // label 撞 default(eg. 「ID」「Employee number」),consumer 值 win — defaults 那一行\n    // 跳過(否則 same label 連 render 兩次,如 default placeholder `—` + consumer 真值)。\n    // 這是遷移期 forgiving 行為:DEV warn 提示應改用 `defaultFieldValues`,但 production\n    // 不破壞既有 consumer。對齊 React `key` 唯一性 + Linear / Slack profile card 一 label\n    // 一 row idiom。\n    const allFields = React.useMemo(() => {\n      const consumerLabels = new Set((fields ?? []).map((f) => f.label))\n      const defaults = NAMECARD_DEFAULT_FIELD_KEYS\n        .map((key) => ({\n          label: DEFAULT_FIELD_LABEL[key],\n          value: defaultFieldValues?.[key] ?? FIELD_PLACEHOLDER,\n        }))\n        .filter((d) => !consumerLabels.has(d.label))\n      return fields && fields.length > 0 ? [...defaults, ...fields] : defaults\n    }, [defaultFieldValues, fields])\n\n    // Dev warn:consumer 透過 `fields` 傳 default key label(legacy pattern)→ 應改 `defaultFieldValues`\n    if (process.env.NODE_ENV !== 'production' && fields) {\n      const legacyEntry = fields.find((f) =>\n        Object.values(DEFAULT_FIELD_LABEL).includes(f.label as string),\n      )\n      if (legacyEntry) {\n        // eslint-disable-next-line no-console\n        console.warn(\n          `[NameCard] \"${name}\":legacy pattern — fields[].label=\"${legacyEntry.label}\" ` +\n          `is a default field. Migrate to defaultFieldValues={{ id, employeeNumber }} prop ` +\n          `to align with NAMECARD_DEFAULT_FIELD_KEYS canonical.`,\n        )\n      }\n    }\n\n    // Dev mode warn:consumer 沒傳 default field 任何 key → 提示補完(避免漂移成 placeholder-only)\n    if (process.env.NODE_ENV !== 'production' && !defaultFieldValues) {\n      // eslint-disable-next-line no-console\n      console.warn(\n        `[NameCard] \"${name}\":no defaultFieldValues passed — sections will render placeholders. ` +\n        `Pass at least { id, employeeNumber } via defaultFieldValues prop. ` +\n        `For other description items (email/phone/department/location etc),use \\`fields\\` prop array.`,\n      )\n    }\n\n    // Layout canonical(2026-04-23):Header + Actions 固定上,Body(status + fields)可捲動,\n    // View more 固定下。**NameCard 自己約束高度**,不依賴 consumer HoverCardContent 設 flex:\n    //   - `max-h-[var(--radix-hover-card-content-available-height,...)]`:HoverCard / Popover\n    //     context 自動繼承 Radix viewport-aware 變數;standalone 落到 100vh fallback\n    //   - 內部 `flex flex-col + overflow-hidden`:Header(shrink-0)+ Body(flex-1 min-h-0 ScrollArea)\n    //     + Footer(shrink-0)三層 chrome\n    // 世界級對照:Slack / Linear / GitHub / Notion hover-profile popover 皆此 chrome pattern。\n    return (\n      <div\n        ref={ref}\n        className={cn(\n          'w-[320px] flex flex-col overflow-hidden',\n          'max-h-[var(--radix-hover-card-content-available-height,var(--radix-popover-content-available-height,100vh))]',\n          className,\n        )}\n        {...props}\n      >\n        {/* ── HEADER(固定): profile + actions ── */}\n        <div className=\"shrink-0 flex flex-col\">\n          <div className=\"flex items-start gap-3 px-4 py-3\">\n            <Avatar\n              src={avatar?.src}\n              alt={avatar?.alt ?? name}\n              color={avatar?.color}\n              size={AVATAR_SIZE}\n              status={status}\n              className=\"shrink-0\"\n            />\n            {/* NameCard typography:label body-lg(16/1.5) + desc body(14/1.5) = reading mode + size=\"lg\"。\n                labelClassName escape hatch 加 font-medium(card context 語意)+ labelTruncate=false 允許 wrap。 */}\n            <ItemContent\n              label={name}\n              description={subtitle}\n              mode=\"reading\"\n              size=\"lg\"\n              labelTruncate={false}\n              labelClassName=\"text-body-lg font-medium text-foreground\"\n              className=\"justify-center\"\n              style={{ minHeight: AVATAR_SIZE }}\n            />\n          </div>\n\n          {/* Action buttons — 均分空間 + 填滿格子(canonical):多個 action 等寬瓜分容器,\n              單一 action 也撐滿容器。`grid grid-flow-col auto-cols-fr` + `[&>*]:w-full`。\n              世界級對照:iOS contact card / macOS contact / LinkedIn profile card 的 action row。 */}\n          {actions && (\n            <div className=\"grid grid-flow-col auto-cols-fr gap-2 px-4 pb-3 [&>*]:w-full\">\n              {actions}\n            </div>\n          )}\n        </div>\n\n        {/* ── BODY(可捲動,v12 status-conditional 2026-05-14):status + fields ──\n            **v12 rule**(per user 拍板「不應該顯示『狀態沒有被設定』,production 每 user 一定有\n            presence state,undefined 頂多是 loading transient 還沒讀到」):status undefined →\n            隱藏整 status badge + status message block(loading 期間 skip),禁 render「Status not\n            set」這種 placeholder(語義錯,user presence 不會「沒設定」)。**NameCard-specific 不外推\n            至 DS 其他元件**(FileItem / DescriptionList / DataTable cell 各自 placeholder 邏輯\n            unrelated)。Fields section 仍 always-render(info schema 性質)。 */}\n        <ScrollArea className=\"flex-1 min-h-0 border-t border-divider\">\n          {/* Status section:`status` defined 才 render(v12 conditional canonical) */}\n          {status && (\n            <div className=\"px-4 py-3 flex flex-col gap-3\">\n              <div className=\"flex items-center gap-2 px-3 py-2 bg-muted rounded-md\">\n                <span\n                  className=\"w-2.5 h-2.5 rounded-full shrink-0\"\n                  style={{ backgroundColor: STATUS_DOT_COLOR[status] }}\n                />\n                <span className=\"text-body\">{STATUS_LABEL[status]}</span>\n              </div>\n              {/* Status message — 只在 status defined 才 render(語意配對:status badge + status\n                  message 是一組;沒 status 就沒 status message)。缺 statusMessage 顯 placeholder。 */}\n              <DescriptionList>\n                <DescriptionItem label=\"Status message\">\n                  {statusMessage ?? <span className=\"text-fg-muted\">{FIELD_PLACEHOLDER}</span>}\n                </DescriptionItem>\n              </DescriptionList>\n            </div>\n          )}\n\n          {/* Fields section:status defined 才有 border-t separator;無 status section 時去除 border-t(因 ScrollArea 起點已有上方 border-t,不重疊) */}\n          <div className={cn('px-4 py-3', status && 'border-t border-divider')}>\n            <DescriptionList cols={2}>\n              {allFields.map((f) => (\n                <DescriptionItem key={f.label} label={f.label}>\n                  {f.value === FIELD_PLACEHOLDER\n                    ? <span className=\"text-fg-muted\">{FIELD_PLACEHOLDER}</span>\n                    : f.value}\n                </DescriptionItem>\n              ))}\n            </DescriptionList>\n          </div>\n        </ScrollArea>\n\n        {/* ── FOOTER(固定): View more,py-3 canonical(12px,比一般 link 按鈕多呼吸) ── */}\n        {onViewMore && (\n          <div className=\"shrink-0 border-t border-divider px-4 py-3\">\n            <Button variant=\"link\" size=\"sm\" onClick={onViewMore} className=\"w-full\">{viewMoreLabel}</Button>\n          </div>\n        )}\n      </div>\n    )\n  },\n)\nNameCard.displayName = 'NameCard'\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const nameCardMeta = {\n  component: 'NameCard',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: ['bg-muted'],\n    fg: ['text-foreground'],\n    ring: [],\n  },\n} as const\n\nexport { NameCard }\n"],"names":[],"mappings":"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"}

package/ds-canonical/commands/gov-status.md

@@ -1,79 +0,0 @@
----
-description: One-shot dump governance health snapshot(無 workflow,< 10s 完成)
----
-
-# /gov-status — Governance Health Snapshot
-
-快印現在 governance state,不走 `/governance-health` 完整 skill workflow(那有 5 phase + CP),只是 user 想 quick check 時的一眼看。
-
-## 跑法
-
-執行以下 bash 並 format output 成 markdown table:
-
-```bash
-echo "=== File sizes ==="
-echo "CLAUDE.md: $(wc -l < CLAUDE.md | tr -d ' ') / 400 target / 800 transition"
-echo ""
-echo "=== Over-cap specs ==="
-for f in $(find src/design-system -name "*.spec.md"); do
-  lines=$(wc -l < "$f" | tr -d ' ')
-  case "$f" in
-    */item-anatomy.spec.md) cap=1200 ;;
-    */color.spec.md|*/sidebar.spec.md|*/tree-view.spec.md) cap=800 ;;
-    *) cap=500 ;;
-  esac
-  if [ "$lines" -gt "$cap" ]; then
-    echo "  ❌ $f: $lines > $cap"
-  fi
-done
-echo ""
-echo "=== Memory ==="
-MEM_DIR=/Users/chenqiren/.claude/projects/-Users-chenqiren-Library-CloudStorage-GoogleDrive-qijenchen-gmail-com--------my-project/memory
-echo "active: $(ls $MEM_DIR/*.md | grep -v retired | wc -l | tr -d ' ') / 20 target"
-echo ""
-echo "=== Hooks / Skills / Agents / Commands ==="
-for d in hooks skills agents commands; do
-  c=$(ls .claude/$d/ 2>/dev/null | grep -v README | grep -v gitignore | wc -l | tr -d ' ')
-  echo "  .claude/$d: $c"
-done
-echo ""
-echo "=== Logs ==="
-for f in hook-fires skill-invokes user-corrections metric-snapshots; do
-  fn=".claude/logs/$f.jsonl"
-  if [ -f "$fn" ]; then
-    echo "  $f: $(wc -l < $fn | tr -d ' ') entries"
-  else
-    echo "  $f: (empty)"
-  fi
-done
-echo ""
-echo "=== Benchmark freshness ==="
-if [ -f .claude/benchmarks/last-fetch.txt ]; then
-  LAST=$(cat .claude/benchmarks/last-fetch.txt)
-  echo "  last: $LAST"
-else
-  echo "  never fetched — run bash .claude/benchmarks/fetch.sh"
-fi
-echo ""
-echo "=== Retire rate(latest snapshot)==="
-if [ -f .claude/logs/metric-snapshots.jsonl ]; then
-  tail -1 .claude/logs/metric-snapshots.jsonl | head -c 200
-fi
-echo ""
-echo "=== tsc state ==="
-npx tsc -b 2>&1 | grep -c "error TS" || echo "0"
-echo ""
-echo "=== compile-stories drift ==="
-node scripts/compile-stories.mjs --all --check 2>&1 | tail -1
-```
-
-## 結論分類
-
-根據上述輸出自動判斷:
-- **✅ OK** — 若無 over-cap spec + 無 tsc error + 無 drift + memory ≤ 20
-- **⚠️ Warning** — 有 over-cap / pending corrections > 10 / benchmark stale > 30 days
-- **❌ Fail** — tsc errors / compile drift / CLAUDE.md > 800
-
-最後給 user 一行 summary:「Governance:{✅/⚠️/❌}{one-line rationale}」。
-
-若要深度 audit → suggest `/governance-health` 跑完整 5-phase skill。