@thinkingai/ae-cli 6.0.53 → 6.0.55

package/skills/ae-analysis/scripts/project-semantic-knowledge-wiki/package-wiki-source-zip.mjs

@@ -4,6 +4,7 @@ import { normalizeSourceForHash } from './precompiled-source.mjs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { createHash, randomBytes } from 'node:crypto';
+import { decodeRefreshState, encodeRefreshState, readRefreshStateIndex } from './refresh-state-parts.mjs';
 
 const args = parseArgs(process.argv.slice(2));
 const sourceDir = path.resolve(required('source-dir'));
@@ -11,18 +12,27 @@ const sourceRoot = fs.realpathSync(sourceDir);
 const treeOutput = path.resolve(args['tree-output'] || `${sourceDir}-source-tree`);
 const outputArchive = args.output ? path.resolve(args.output) : '';
 const previousManifestPath = args['previous-manifest'] ? path.resolve(args['previous-manifest']) : '';
+const previousRefreshStatePath = args['previous-refresh-state'] ? path.resolve(args['previous-refresh-state']) : '';
+const previousTreeRoot = args['previous-tree-root'] ? fs.realpathSync(path.resolve(args['previous-tree-root'])) : '';
 const manifestOutput = path.resolve(args['manifest-output'] || path.join(treeOutput, 'kb-source-tree-manifest.json'));
 const force = Boolean(args.force);
+const shouldEmbedRefreshStateBaseline = Boolean(args['embed-refresh-state-baseline']);
 const rootPath = normalizeRootPath(args['root-path'] || 'sources');
 
-if (!outputArchive && !previousManifestPath) throw new Error('--output or --previous-manifest is required.');
+if (previousManifestPath && previousRefreshStatePath) throw new Error('Use either --previous-manifest or --previous-refresh-state, not both.');
+if (!outputArchive && !previousManifestPath && !previousRefreshStatePath && !shouldEmbedRefreshStateBaseline) {
+  throw new Error('--output, --previous-manifest, --previous-refresh-state, or --embed-refresh-state-baseline is required.');
+}
 assertOutputPath(treeOutput, sourceRoot, 'Tree output');
 if (outputArchive) assertOutputPath(outputArchive, sourceRoot, 'Archive');
 if (manifestOutput.startsWith(`${sourceRoot}${path.sep}`)) throw new Error('Manifest output must not be nested inside the flat source directory.');
 
 const flatManifest = readManifest(path.join(sourceRoot, 'kb-upload-manifest.json'), { allowFlat: true });
 const next = buildSourceTreeManifest(flatManifest, { requireLocalContent: true });
-const entries = buildSourceTreeEntries(next);
+const nextBaseline = shouldEmbedRefreshStateBaseline ? refreshStateBaseline(next) : null;
+const entries = buildSourceTreeEntries(next, nextBaseline);
+const stateEntry = entries.find((entry) => entry.source_kind === 'refresh-state');
+const stateParts = entries.filter((entry) => entry.source_kind === 'refresh-state-part');
 
 materializeTree(treeOutput, force, (staging) => {
   for (const entry of entries) writeText(path.join(staging, entry.path), entry.content);
@@ -34,15 +44,34 @@ const result = {
   namespace: next.namespace,
   root_path: next.root_path,
   source_count: next.source_count,
+  refresh_state_part_count: stateParts.length,
   tree_output: treeOutput,
   manifest: manifestOutput,
 };
 
-if (previousManifestPath) {
-  const previous = buildSourceTreeManifest(readManifest(previousManifestPath, { allowFlat: true, allowTree: true }), { requireLocalContent: false });
+if (previousManifestPath || previousRefreshStatePath) {
+  const previousState = previousManifestPath
+    ? { manifest: readManifest(previousManifestPath, { allowFlat: true, allowTree: true }), baseline: null, index: null }
+    : readRefreshStateBaseline(previousRefreshStatePath);
+  const previous = buildSourceTreeManifest(previousState.manifest, { requireLocalContent: false });
+  if (previousManifestPath && previousTreeRoot) {
+    const previousRefresh = previous.sources.find((source) => source.source_kind === 'refresh-state');
+    if (previousRefresh) {
+      const file = path.join(previousTreeRoot, previousRefresh.file);
+      if (fs.existsSync(file)) {
+        const content = readText(file);
+        previousState.index = readRefreshStateIndex(content);
+        previousState.index_hash = previousState.index ? sha256(content) : null;
+      }
+    }
+  }
+  if (previousTreeRoot) rehashPreviousTreeSources(previous, previousTreeRoot);
   if (previous.namespace !== next.namespace || previous.semantic_project_id !== next.semantic_project_id) {
     throw new Error('Wiki namespace/project changed; stop.');
   }
+  const semanticPlanDiff = diffSemanticPlanFragments(previous.semantic_plan_state, next.semantic_plan_state);
+  const taxonomyChanged = previous.navigation_taxonomy_version !== next.navigation_taxonomy_version;
+  const changedPlanFragments = new Set(semanticPlanDiff.changed_fragments);
   const before = new Map(previous.sources.map((source) => [source.file, source]));
   const after = new Map(next.sources.map((source) => [source.file, source]));
   const actions = [];
@@ -50,35 +79,72 @@ if (previousManifestPath) {
   for (const source of next.sources) {
     const old = before.get(source.file);
     if (old?.content_hash === source.content_hash) unchanged.push(source.file);
-    else actions.push({
-      action: old ? 'replace' : 'add',
-      path: source.file,
-      file: path.join(treeOutput, source.file),
-      source_kind: source.source_kind,
-      asset_type: source.asset_type,
-      asset_key: source.asset_key,
-      content_hash: source.content_hash,
-      previous_content_hash: old?.content_hash ?? null,
-    });
+    else actions.push(actionForSource(old ? 'replace' : 'add', source, old, changedPlanFragments));
   }
   for (const source of previous.sources) {
-    if (!after.has(source.file)) actions.push({
-      action: 'remove',
+    if (!after.has(source.file)) actions.push(actionForSource('remove', source, source, changedPlanFragments));
+  }
+  if (stateEntry) {
+    const oldIndex = previousState.index;
+    const oldParts = new Map((oldIndex?.parts ?? []).map((part) => [part.file, part]));
+    const nextIndex = readRefreshStateIndex(stateEntry.content);
+    const oldState = before.get(stateEntry.path);
+    if (oldState && oldState.content_hash === after.get(stateEntry.path)?.content_hash
+        && (!oldIndex || previousState.index_hash !== sha256(stateEntry.content))) {
+      actions.push(actionForSource('replace', after.get(stateEntry.path), oldState, changedPlanFragments));
+    }
+    for (const part of stateParts) {
+      const old = oldParts.get(path.posix.basename(part.path));
+      if (old?.sha256 !== sha256(part.content)) actions.push(statePartAction(old ? 'replace' : 'add', part, old));
+      oldParts.delete(path.posix.basename(part.path));
+    }
+    for (const old of oldParts.values()) {
+      actions.push(statePartAction('remove', { path: path.posix.join(path.posix.dirname(stateEntry.path), old.file) }, old));
+    }
+    if (!nextIndex) throw new Error('Packaged refresh state index is missing.');
+    const stateAction = actions.find((action) => action.path === stateEntry.path);
+    if (stateAction) {
+      const unchangedPosition = unchanged.indexOf(stateEntry.path);
+      if (unchangedPosition !== -1) unchanged.splice(unchangedPosition, 1);
+      stateAction.content_hash = sha256(stateEntry.content);
+      if (oldIndex) stateAction.previous_content_hash = previousState.index_hash;
+    }
+    const ordinaryActions = actions.filter((action) => !['refresh-state', 'refresh-state-part'].includes(action.source_kind));
+    const partWrites = actions.filter((action) => action.source_kind === 'refresh-state-part' && action.action !== 'remove');
+    const partRemovals = actions.filter((action) => action.source_kind === 'refresh-state-part' && action.action === 'remove');
+    actions.splice(0, actions.length, ...ordinaryActions, ...partWrites, ...(stateAction ? [stateAction] : []), ...partRemovals);
+  }
+  const affectedBySemanticPlan = next.sources
+    .map((source) => ({
       path: source.file,
       source_kind: source.source_kind,
       asset_type: source.asset_type,
       asset_key: source.asset_key,
-      previous_content_hash: source.content_hash,
-    });
-  }
-  Object.assign(result, { actions, unchanged, compile_mode: actions.length ? 'incremental' : 'skip' });
+      changed_semantic_plan_fragments: intersect(source.semantic_plan_fragment_refs, changedPlanFragments),
+    }))
+    .filter((source) => source.changed_semantic_plan_fragments.length);
+  Object.assign(result, {
+    actions,
+    unchanged,
+    compile_mode: taxonomyChanged ? 'full' : actions.some((action) => !['refresh-state', 'refresh-state-part'].includes(action.source_kind)) ? 'incremental' : 'skip',
+    navigation_taxonomy_migration: taxonomyChanged ? {
+      from: previous.navigation_taxonomy_version ?? 'legacy',
+      to: next.navigation_taxonomy_version,
+      requires_schema_force: false,
+      requires_schema_review: true,
+      reason: 'navigation_taxonomy_changed',
+    } : null,
+    semantic_plan_diff: semanticPlanDiff,
+    affected_by_semantic_plan: affectedBySemanticPlan,
+    previous_refresh_state_baseline: previousState.baseline,
+  });
 }
 
 if (outputArchive) {
   if (fs.existsSync(outputArchive) && !force) throw new Error('Archive already exists. Pass --force to replace it.');
-  const archiveEntries = next.sources.map((source) => ({
-    name: source.file,
-    content: fs.readFileSync(path.join(treeOutput, source.file)),
+  const archiveEntries = entries.map((entry) => ({
+    name: entry.path,
+    content: fs.readFileSync(path.join(treeOutput, entry.path)),
   })).sort((a, b) => a.name.localeCompare(b.name, 'en'));
   await writeZip(outputArchive, archiveEntries);
   Object.assign(result, { archive: outputArchive, archive_bytes: fs.statSync(outputArchive).size });
@@ -107,6 +173,7 @@ function buildSourceTreeManifest(manifest, options) {
       title: source.title,
       content_hash: content == null ? source.content_hash : sha256(normalizeContentForHash(content)),
       source_path: source.source_path,
+      semantic_plan_fragment_refs: source.semantic_plan_fragment_refs,
       managed_by: 'project-semantic-kb-source-tree',
     };
   });
@@ -128,6 +195,7 @@ function buildSourceTreeManifest(manifest, options) {
   return {
     schema_version: '1.1',
     manifest_kind: 'ae_project_semantic_kb_source_tree',
+    navigation_taxonomy_version: manifest.navigation_taxonomy_version ?? 'legacy',
     namespace: manifest.namespace,
     semantic_project_id: manifest.semantic_project_id,
     project_name: manifest.project_name ?? null,
@@ -137,32 +205,87 @@ function buildSourceTreeManifest(manifest, options) {
     source_count: sources.length,
     generated_source_count: generated.length,
     filing_guide_count: readmes.length,
+    semantic_plan_state: normalizeSemanticPlanState(manifest.semantic_plan_state),
     sources,
   };
 }
 
-function buildSourceTreeEntries(manifest) {
+function buildSourceTreeEntries(manifest, refreshStateBaseline = null) {
   const flatToTree = new Map(manifest.sources
     .filter((item) => item.source_kind !== 'filing-guide')
     .map((item) => [item.display_name, item.file]));
   const guides = new Map(sourceDirectoryReadmes(manifest).map((entry) => [entry.path, entry.content]));
-  return manifest.sources.map((source) => {
+  return manifest.sources.flatMap((source) => {
     if (source.source_kind === 'filing-guide') {
       const content = guides.get(source.file);
       if (!content) throw new Error(`Missing filing guide content for ${source.file}.`);
-      return { path: source.file, content };
+      return [{ path: source.file, content, source_kind: source.source_kind }];
     }
-    return {
+    if (source.source_kind === 'refresh-state') {
+      const content = rewriteLinksForTree(readText(path.join(sourceRoot, source.display_name)), source.display_name, flatToTree);
+      const state = encodeRefreshState(content, source.file, source.content_hash, refreshStateBaseline);
+      return [{ path: source.file, content: state.indexContent, source_kind: 'refresh-state' },
+        ...state.parts.map((part) => ({ ...part, source_kind: 'refresh-state-part' }))];
+    }
+    return [{
       path: source.file,
       content: rewriteLinksForTree(readText(path.join(sourceRoot, source.display_name)), source.display_name, flatToTree),
-    };
+      source_kind: source.source_kind,
+    }];
   });
 }
 
+function refreshStateBaseline(manifest) {
+  const contentRevision = optionalPositiveInteger(args['baseline-content-revision'], 'baseline-content-revision');
+  return {
+    schema_version: '1.0',
+    source_id: clean(args['baseline-source-id']) || null,
+    source_display_name: clean(args['baseline-source-display-name']) || null,
+    content_revision: contentRevision,
+    published_version_id: clean(args['baseline-published-version-id']) || null,
+    manifest_hash: sourceTreeManifestHash(manifest),
+    source_tree_manifest: manifest,
+  };
+}
+
+function readRefreshStateBaseline(file) {
+  const content = readText(file);
+  const { payload, index } = decodeRefreshState(content, file);
+  const baseline = payload.source_tree_baseline ?? null;
+  const manifest = baseline?.source_tree_manifest;
+  if (!manifest) throw new Error('Refresh state does not contain source_tree_baseline.source_tree_manifest.');
+  const expectedHash = clean(baseline.manifest_hash);
+  const actualHash = sourceTreeManifestHash(manifest);
+  if (expectedHash && expectedHash !== actualHash) {
+    throw new Error('Refresh state source_tree_manifest hash does not match its manifest_hash.');
+  }
+  const stateSource = manifest.sources.find((source) => source.source_kind === 'refresh-state');
+  if (index && stateSource?.content_hash !== index.normalized_content_hash) {
+    throw new Error('Refresh state normalized content hash does not match its source tree manifest.');
+  }
+  return {
+    manifest,
+    index,
+    index_hash: index ? sha256(content) : null,
+    baseline: {
+      schema_version: clean(baseline.schema_version) || null,
+      source_id: clean(baseline.source_id) || null,
+      source_display_name: clean(baseline.source_display_name) || null,
+      content_revision: Number.isSafeInteger(baseline.content_revision) ? baseline.content_revision : null,
+      published_version_id: clean(baseline.published_version_id) || null,
+      manifest_hash: expectedHash || actualHash,
+    },
+  };
+}
+
+function sourceTreeManifestHash(manifest) {
+  return sha256(stableJson(manifest));
+}
+
 function sourceDirectoryReadmes(manifest) {
   const project = clean(manifest.project_name) || `Project ${manifest.semantic_project_id}`;
   const lines = [
-    [`${rootPath}/README.md`, `# Source Directory\n\nThis directory is the writable source space for ${project} project knowledge. README files are filing guides only; they are not business evidence.\n\nPut source material by nature. CLI-managed asset facts live under assets/. Human context such as project background, meetings, decisions, corrections, and references must not be removed by an asset refresh.\n\nThe expected compiled Wiki should be organized for consumption: index.md, wiki/project/, wiki/domains/, wiki/semantics/, wiki/assets/, wiki/decisions/, and wiki/review/.\n`],
+    [`${rootPath}/README.md`, `# Source Directory\n\nThis directory is the writable source space for ${project} project knowledge. README files are filing guides only; they are not business evidence.\n\nPut source material by nature. CLI-managed asset facts live under assets/. Human context such as project background, meetings, decisions, corrections, and references must not be removed by an asset refresh.\n\nThe compiled Wiki navigation follows project overview, shared project knowledge, business domains, event and asset catalog, and governance with provenance. Event groups are lookup indexes, not business domains.\n`],
     [`${rootPath}/project/README.md`, '# Project Sources\n\nBackground, goals, business scope, terminology, and ownership notes. This guide is not evidence.\n'],
     [`${rootPath}/assets/README.md`, '# Asset Sources\n\nCLI-managed structured asset facts. Refresh may change files owned by the project semantic asset package only.\n'],
     [`${rootPath}/assets/dashboards/README.md`, '# Dashboard Asset Sources\n\nDashboard facts exported by CLI.\n'],
@@ -170,6 +293,11 @@ function sourceDirectoryReadmes(manifest) {
     [`${rootPath}/assets/metrics/README.md`, '# Metric Asset Sources\n\nReusable metric facts exported by CLI.\n'],
     [`${rootPath}/assets/metadata/README.md`, '# Metadata Asset Sources\n\nEvents, properties, tags, cohorts, and other selectable metadata facts exported by CLI.\n'],
     [`${rootPath}/business/README.md`, '# Business Sources\n\nBusiness rules, metric definitions, domain context, process notes, and user-facing question patterns.\n'],
+    [`${rootPath}/personal-semantics/README.md`, '# Adopted Personal Semantic Sources\n\nReviewed personal semantics promoted into project knowledge. Refresh may replace these CLI-managed files from adopted personal semantic records.\n'],
+    [`${rootPath}/personal-semantics/background/README.md`, '# Background Personal Semantics\n\nAdopted personal background context for project and domain interpretation.\n'],
+    [`${rootPath}/personal-semantics/preference/README.md`, '# Preference Personal Semantics\n\nAdopted personal preferences for routing, answer style, and source selection.\n'],
+    [`${rootPath}/personal-semantics/experience/README.md`, '# Experience Personal Semantics\n\nAdopted personal analysis experience, heuristics, and cautions.\n'],
+    [`${rootPath}/personal-semantics/asset-context/README.md`, '# Asset Context Personal Semantics\n\nAdopted personal context scoped to referenced project assets.\n'],
     [`${rootPath}/meetings/README.md`, '# Meeting Sources\n\nMeeting notes and discussion records. They can provide context, but do not override confirmed decisions by recency alone.\n'],
     [`${rootPath}/decisions/README.md`, '# Decision Sources\n\nConfirmed decisions must state confirmer, status, date, and applicable scope.\n'],
     [`${rootPath}/corrections/README.md`, '# Correction Sources\n\nCorrections must identify the target material, corrected content, reason, date, and applicable scope.\n'],
@@ -186,13 +314,27 @@ function sourceTreePath(source) {
   if (assetType === 'report') return `${rootPath}/assets/reports/${base}`;
   if (assetType === 'metric') return `${rootPath}/assets/metrics/${base}`;
   if (assetType === 'metadata' || kind === 'metadata') return `${rootPath}/assets/metadata/${base}`;
+  if (source.source_path.startsWith('wiki/event-map/')) return `${rootPath}/assets/metadata/${base}`;
+  if (source.source_path === 'wiki/project-overview.md') return `${rootPath}/project/${base}`;
+  if (source.source_path.startsWith('wiki/common/') || source.source_path.startsWith('wiki/asset-index/')) return `${rootPath}/project/${base}`;
+  if (kind === 'refresh-state') return `${rootPath}/project/${base}`;
   if (kind === 'domain' || kind === 'recall-card') return `${rootPath}/business/${base}`;
+  if (kind === 'personal-semantic') return personalSemanticSourceTreePath(source, base);
   if (kind === 'index' || kind === 'manifest') return `${rootPath}/project/${base}`;
   if (kind === 'governance') return `${rootPath}/references/governance/${base}`;
   if (kind === 'appendix' || kind === 'source-container') return `${rootPath}/references/${base}`;
   return `${rootPath}/references/${base}`;
 }
 
+function personalSemanticSourceTreePath(source, base) {
+  const match = clean(source.source_path).match(/^wiki\/personal-semantics(?:\/([^/]+))?\//);
+  const folder = match?.[1];
+  if (['background', 'preference', 'experience', 'asset-context'].includes(folder)) {
+    return `${rootPath}/personal-semantics/${folder}/${base}`;
+  }
+  return `${rootPath}/personal-semantics/${base}`;
+}
+
 function sourceTreeBaseName(source) {
   const original = path.posix.basename(source.file);
   if (!source.asset_key) return original;
@@ -259,6 +401,7 @@ function normalizeFlatSource(manifest, source, requireLocalFile) {
     asset_key: clean(source.asset_key) || null,
     title: clean(source.title) || clean(source.display_name).replace(/\.md$/i, ''),
     source_path: clean(source.source_path),
+    semantic_plan_fragment_refs: normalizeStringArray(source.semantic_plan_fragment_refs),
   };
 }
 
@@ -273,20 +416,96 @@ function validateTreeManifest(manifest) {
         || !/^[a-f0-9]{64}$/i.test(source.content_hash) || seen.has(source.file)) {
       throw new Error('Invalid or duplicate source tree path/hash.');
     }
+    source.semantic_plan_fragment_refs = normalizeStringArray(source.semantic_plan_fragment_refs);
     seen.add(source.file);
   }
+  manifest.semantic_plan_state = normalizeSemanticPlanState(manifest.semantic_plan_state);
   return manifest;
 }
 
+function actionForSource(action, source, previous, changedPlanFragments) {
+  return {
+    action,
+    path: source.file,
+    ...(action === 'remove' ? {} : { file: path.join(treeOutput, source.file) }),
+    source_kind: source.source_kind,
+    asset_type: source.asset_type,
+    asset_key: source.asset_key,
+    content_hash: action === 'remove' ? null : source.content_hash,
+    previous_content_hash: previous?.content_hash ?? null,
+    semantic_plan_fragment_refs: source.semantic_plan_fragment_refs ?? [],
+    changed_semantic_plan_fragments: intersect(source.semantic_plan_fragment_refs, changedPlanFragments),
+  };
+}
+
+function diffSemanticPlanFragments(previousState, nextState) {
+  const previous = new Map(normalizeSemanticPlanState(previousState).fragments.map((fragment) => [fragment.id, fragment.hash]));
+  const next = new Map(normalizeSemanticPlanState(nextState).fragments.map((fragment) => [fragment.id, fragment.hash]));
+  const ids = [...new Set([...previous.keys(), ...next.keys()])].sort((left, right) => left.localeCompare(right, 'en'));
+  const changed = ids.filter((id) => previous.get(id) !== next.get(id));
+  return {
+    changed_fragment_count: changed.length,
+    changed_fragments: changed,
+  };
+}
+
+function normalizeSemanticPlanState(value) {
+  if (!value || typeof value !== 'object') return { schema_version: null, plan_hash: null, fragment_count: 0, fragments: [] };
+  const fragments = Array.isArray(value.fragments) ? value.fragments
+    .map((fragment) => ({
+      ...fragment,
+      id: clean(fragment?.id),
+      kind: clean(fragment?.kind),
+      hash: clean(fragment?.hash),
+    }))
+    .filter((fragment) => fragment.id && /^[a-f0-9]{64}$/i.test(fragment.hash))
+    .sort((left, right) => left.id.localeCompare(right.id, 'en')) : [];
+  return {
+    ...value,
+    fragment_count: fragments.length,
+    fragments,
+  };
+}
+
+function normalizeStringArray(value) {
+  return [...new Set((Array.isArray(value) ? value : []).map(clean).filter(Boolean))].sort((left, right) => left.localeCompare(right, 'en'));
+}
+
+function intersect(values, set) {
+  const source = normalizeStringArray(values);
+  return source.filter((value) => set.has(value));
+}
+
 function normalizeContentForHash(content) { return normalizeSourceForHash(String(content).replace(/\r\n/g, '\n')); }
 
+function rehashPreviousTreeSources(manifest, root) {
+  for (const source of manifest.sources) {
+    const file = path.resolve(root, source.file);
+    if (!file.startsWith(`${root}${path.sep}`) || !fs.existsSync(file)) continue;
+    const content = readText(file);
+    source.content_hash = source.source_kind === 'refresh-state' && readRefreshStateIndex(content)
+      ? readRefreshStateIndex(content).normalized_content_hash
+      : sha256(normalizeContentForHash(content));
+  }
+}
+
+function statePartAction(action, part, previous) {
+  return {
+    action, path: part.path, ...(action === 'remove' ? {} : { file: path.join(treeOutput, part.path) }),
+    source_kind: 'refresh-state-part', asset_type: null, asset_key: null,
+    content_hash: action === 'remove' ? null : sha256(part.content),
+    previous_content_hash: previous?.sha256 ?? null,
+    semantic_plan_fragment_refs: [], changed_semantic_plan_fragments: [],
+  };
+}
+
 function parseArgs(tokens) {
   const parsed = {};
   for (let i = 0; i < tokens.length; i += 1) {
     const key = tokens[i];
     if (!key.startsWith('--')) throw new Error(`Invalid argument: ${key}`);
     const name = key.slice(2);
-    if (name === 'force') {
+    if (name === 'force' || name === 'embed-refresh-state-baseline') {
       parsed[name] = true;
       continue;
     }
@@ -303,6 +522,13 @@ function required(name) {
   return value;
 }
 
+function optionalPositiveInteger(value, label) {
+  if (value == null || value === '') return null;
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1) throw new Error(`--${label} must be a positive integer.`);
+  return parsed;
+}
+
 function normalizeRootPath(value) {
   const normalized = clean(value).replace(/^\/+|\/+$/g, '');
   if (!normalized || normalized.includes('\\') || normalized.split('/').some((part) => !part || part === '.' || part === '..')) {
@@ -374,3 +600,9 @@ function writeJson(file, value, replace) {
 function readText(file) { return fs.readFileSync(file, 'utf8'); }
 function clean(value) { return value == null ? '' : String(value).trim(); }
 function sha256(value) { return createHash('sha256').update(value).digest('hex'); }
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (!value || typeof value !== 'object') return JSON.stringify(value);
+  const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right, 'en'));
+  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(',')}}`;
+}

package/skills/ae-analysis/scripts/project-semantic-knowledge-wiki/plan-kb-source-sync.mjs

@@ -212,7 +212,7 @@ function decideCompileMode({ actionCount, baselineCount, nextCount, fullThreshol
       mode: 'full',
       reason: forceReasons[0],
       changeRatio,
-      requiresSchemaForce: true,
+      requiresSchemaForce: false,
       schemaForceReasons: forceReasons,
     };
   }

package/skills/ae-analysis/scripts/project-semantic-knowledge-wiki/precompiled-source.mjs

@@ -29,7 +29,14 @@ function renderFacts(value, depth = 0) {
 
 export function normalizeSourceForHash(content) {
   const volatileTimeKeys = '(?:created_at|updated_at|modified_at|deleted_at|generated_at|authenticated_at|create_time|update_time|modified_time|created_time|last_modified_at|last_modified_time|gmt_create|gmt_modified|ctime|mtime|snapshot_date|createdAt|updatedAt|modifiedAt|deletedAt|generatedAt|authenticatedAt|createTime|updateTime|modifiedTime|createdTime|lastModifiedAt|lastModifiedTime)';
-  return content
+  return normalizeBulletSectionOrder(
+    normalizeBulletSectionOrder(
+      normalizeSemanticConflictCandidateOrder(normalizeRefreshStatePayload(content)),
+      '语义冲突',
+    ),
+    '缺少源标题的元数据',
+  )
+    .replace(/^\s*[-*]\s+semantic_plan_hash:\s*[^\r\n]*\r?\n?/gmi, '')
     .replace(/source_snapshot_hash:\s*[^\r\n]+/g, 'source_snapshot_hash: <snapshot>')
     .replace(/snapshot_hash:\s*[^\r\n]+/g, 'snapshot_hash: <snapshot>')
     .replace(/semantic_plan_hash:\s*[^\r\n]+/g, 'semantic_plan_hash: <semantic_plan>')
@@ -37,13 +44,50 @@ export function normalizeSourceForHash(content) {
     .replace(/"source_snapshot_hash":\s*"[^"]+"/g, '"source_snapshot_hash":"<snapshot>"')
     .replace(/"snapshot_hash":\s*"[^"]+"/g, '"snapshot_hash":"<snapshot>"')
     .replace(/"snapshot_id":\s*"[^"]+"/g, '"snapshot_id":"<snapshot_id>"')
-    .replace(/"semantic_plan_hash":\s*"[^"]+"/g, '"semantic_plan_hash":"<semantic_plan>"')
+    .replace(/,?\s*"semantic_plan_hash":\s*"[^"]+"/g, '')
     .replace(new RegExp(`"(${volatileTimeKeys})":\\s*(?:"[^"]*"|null|-?\\d+(?:\\.\\d+)?)`, 'gi'), '"$1":"<volatile_time>"')
     .replace(/((?:创建|更新|修改|生成)时间):\s*[^\r\n]+/g, '$1: <volatile_time>')
     .replace(/((?:Created|Updated|Modified|Generated) at):\s*[^\r\n]+/gi, '$1: <volatile_time>')
+    .replace(/快照:\s*`[0-9a-f]{64}`/gi, '快照: `<snapshot>`')
     .replace(/Snapshot hash:\s*`[0-9a-f]{64}`/gi, 'Snapshot hash: `<snapshot>`')
     .replace(/Semantic plan hash:\s*`[0-9a-f]{64}`/gi, 'Semantic plan hash: `<semantic_plan>`')
     .replace(/## Snapshot [0-9a-f]{64}/gi, '## Snapshot <snapshot>')
     .replace(new RegExp(`^(\\s*-\\s+${volatileTimeKeys}):[^\\n]*`, 'gmi'), '$1: <volatile_time>')
     .replace(/^content_hash:[^\n]*$/gm, 'content_hash: <hash>');
 }
+
+function normalizeRefreshStatePayload(content) {
+  return String(content).replace(/<!-- pskb_refresh_state_base64\n([A-Za-z0-9_=\-\s]+)\n-->/g, (match, encoded) => {
+    try {
+      const payload = JSON.parse(Buffer.from(encoded.replace(/\s+/g, ''), 'base64url').toString('utf8'));
+      delete payload.source_tree_baseline;
+      return `<!-- pskb_refresh_state_json\n${stableJson(payload)}\n-->`;
+    } catch {
+      return match;
+    }
+  });
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (!value || typeof value !== 'object') return JSON.stringify(value);
+  const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right, 'en'));
+  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(',')}}`;
+}
+
+function normalizeSemanticConflictCandidateOrder(content) {
+  return content.replace(/(语义“[^”]+”存在 \d+ 个[^，\r\n]+候选，但口径不同：)([^\r\n]*?)(。Agent 不应仅凭名称选择，需要优先使用业务域\/召回卡或让用户确认。)/g,
+    (_, prefix, candidates, suffix) => `${prefix}${candidates.split('；').sort((left, right) => left.localeCompare(right, 'zh-Hans-CN')).join('；')}${suffix}`);
+}
+
+function normalizeBulletSectionOrder(content, heading) {
+  return content.replace(new RegExp(`(## ${escapeRegExp(heading)}\\r?\\n\\r?\\n)([\\s\\S]*?)(?=\\r?\\n## |$)`, 'g'), (match, prefix, body) => {
+    const lines = body.split(/\r?\n/).filter((line) => line.trim());
+    if (!lines.length || !lines.every((line) => line.startsWith('- '))) return match;
+    return `${prefix}${lines.sort((left, right) => left.localeCompare(right, 'zh-Hans-CN')).join('\n')}\n`;
+  });
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/skills/ae-analysis/scripts/project-semantic-knowledge-wiki/prepare-compile-schema.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+import { runCompanyKb, invokeCompanyKbCli } from './company-kb.mjs';
+
+const here = import.meta.dirname;
+const missingCodes = new Set(['SCHEMA_NOT_FOUND', 'KB_SCHEMA_IMPORT_SCHEMA_NOT_FOUND']);
+
+// Preparation never generates, validates with AI, applies rules, or compiles sources.
+export async function prepareCompileSchema({ name, host, output, file, requestId }, invoke) {
+  if (!name || !host || !output) throw new Error('--name, --host and --output are required.');
+  if (fs.existsSync(output)) throw new Error('Output already exists; choose a new path.');
+  const call = (command, flags = []) => runCompanyKb(command, ['--name', name, '--host', host, ...flags], invoke);
+  const status = (await call('+status')).data;
+  if (status.activeRunId || status.schemaStatus === 'generating' || status.buildStatus === 'compiling'
+      || ['schema_generating', 'wiki_compiling', 'wiki_recovering', 'wiki_review_required'].includes(status.status)
+      || status.publicationReview) {
+    throw new Error(`Knowledge base is busy or requires publication review: ${status.status}`);
+  }
+  let absent = false;
+  try {
+    await call('+schema-download', ['--output', output]);
+  } catch (error) {
+    if (!missingCodes.has(error.code)) throw error;
+    absent = true;
+  }
+  if (!absent && status.schemaValidation?.valid === true) {
+    const bytes = fs.readFileSync(output);
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    if (bytes.length > 262144 || [...text.trim()].length < 20) throw new Error('Downloaded formal rules failed basic checks.');
+    return { schema_action: 'reuse', compile_ready: true, schema_file: path.resolve(output),
+      schema_hash: createHash('sha256').update(bytes).digest('hex') };
+  }
+  // New KBs contain a placeholder file even though no effective rules exist yet.
+  const uninitialized = status.schemaStatus === 'pending' && ['empty', 'schema_pending'].includes(status.status)
+    && (!status.schemaValidation || status.schemaValidation.reason === 'DEFAULT_TEMPLATE');
+  if (!uninitialized) throw new Error('Formal rules are invalid or their state is unknown; review explicitly before initialization.');
+  if (!requestId) throw new Error('--request-id is required to initialize rules; reuse it when resuming the same upload.');
+  const candidate = (await call('+schema-import', ['--file', file || path.join(here, 'default-compile-schema.md'),
+    '--request-id', requestId])).data;
+  return { schema_action: 'review_import', compile_ready: false, candidate,
+    ...(absent ? {} : { schema_file: path.resolve(output) }) };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const args = process.argv.slice(2), values = {};
+    const allowed = new Set(['name', 'host', 'output', 'file', 'request-id']);
+    for (let i = 0; i < args.length; i += 2) {
+      const key = args[i].replace(/^--/, '');
+      if (!args[i].startsWith('--') || !allowed.has(key) || !args[i + 1] || args[i + 1].startsWith('--')) {
+        throw new Error(`Invalid argument: ${args[i]}`);
+      }
+      values[key] = args[i + 1];
+    }
+    const result = await prepareCompileSchema({ ...values, requestId: values['request-id'] }, invokeCompanyKbCli);
+    console.log(JSON.stringify(result, null, 2));
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}