openxiangda 1.0.162 → 1.0.164

package/lib/sdd.js

@@ -2,6 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { readGitSourceBase } = require('./change-baseline');
+const { assertReleaseSourceIntegrated } = require('./release-mainline');
 
 const DEFAULT_SDD_DIR = 'openspec';
 const SDD_CONFIG_FILE = 'config.yaml';
@@ -326,6 +327,26 @@ function normalizeAffected(input = {}) {
   };
 }
 
+function mergeAffectedScopes(...inputs) {
+  const scopes = inputs.filter(Boolean).map(input => normalizeAffected(input));
+  const mergeList = key =>
+    Array.from(new Set(scopes.flatMap(scope => scope[key] || []))).sort();
+  const hasFlag = key => scopes.some(scope => Boolean(scope[key]));
+  return {
+    forms: mergeList('forms'),
+    pages: mergeList('pages'),
+    functions: mergeList('functions'),
+    automations: mergeList('automations'),
+    workflows: mergeList('workflows'),
+    jsCodeNodes: mergeList('jsCodeNodes'),
+    files: mergeList('files'),
+    resources: hasFlag('resources'),
+    runtime: hasFlag('runtime'),
+    backend: hasFlag('backend'),
+    contracts: hasFlag('contracts'),
+  };
+}
+
 function normalizeQuickScopeFile(value) {
   const file = String(value || '').trim().replace(/\\/g, '/').replace(/^\.\//, '');
   if (
@@ -619,6 +640,7 @@ function createTasksContent(meta = {}) {
       '## Postpublish',
       '',
       '- [ ] Record publish/deploy result',
+      '- [ ] Merge/fast-forward the frozen release SHA and push the authoritative default branch',
       '',
       '## Archive',
       '',
@@ -644,6 +666,7 @@ function createTasksContent(meta = {}) {
     '## Postpublish',
     '',
     '- [ ] Record publish/deploy result',
+    '- [ ] Merge/fast-forward the frozen release SHA and push the authoritative default branch',
     '',
     '## Archive',
     '',
@@ -664,6 +687,7 @@ function createEvidenceContent() {
     '## Release',
     '',
     '- [ ] Record publish/deploy command output or explain why this change was not released',
+    '- [ ] Record `openxiangda release integration-status` proving the frozen SHA is on the authoritative default branch',
     '',
     '## Bypass Log',
     '',
@@ -1659,6 +1683,64 @@ function updateReleaseManifest(loaded, releasePlan, verificationStage = 'default
   return release;
 }
 
+function recordSddReleaseSourceRevision(options = {}) {
+  const loaded = loadSddChange(options);
+  const input = options.releaseSourceRevision;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('releaseSourceRevision 必须是对象');
+  }
+  const releaseSourceRevision = {
+    repo: String(input.repo || input.repositoryId || '').trim(),
+    baseCommit: String(input.baseCommit || '').trim().toLowerCase(),
+    treeHash: String(input.treeHash || '').trim().toLowerCase(),
+    branch: String(input.branch || '').trim() || null,
+    remoteName: String(input.remoteName || '').trim() || null,
+    remoteUrlHash: String(input.remoteUrlHash || '').trim().toLowerCase() || null,
+    mainBranch: String(input.mainBranch || '').trim() || null,
+    mainTipCommit: String(input.mainTipCommit || '').trim().toLowerCase() || null,
+    capturedAt: input.capturedAt || nowIso(),
+  };
+  if (
+    !/^sha256:[0-9a-f]{64}$/i.test(releaseSourceRevision.repo) ||
+    !/^[0-9a-f]{40,64}$/.test(releaseSourceRevision.baseCommit) ||
+    !/^[0-9a-f]{40,64}$/.test(releaseSourceRevision.treeHash) ||
+    !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(releaseSourceRevision.remoteName || '') ||
+    !/^sha256:[0-9a-f]{64}$/.test(releaseSourceRevision.remoteUrlHash || '') ||
+    !['main', 'master'].includes(releaseSourceRevision.mainBranch)
+  ) {
+    throw new Error(
+      'releaseSourceRevision 缺少有效的 repo/baseCommit/treeHash/remoteName/remoteUrlHash/mainBranch'
+    );
+  }
+  const existing = loaded.release?.releaseSourceRevision;
+  if (
+    existing?.baseCommit &&
+    (existing.baseCommit !== releaseSourceRevision.baseCommit ||
+      existing.treeHash !== releaseSourceRevision.treeHash ||
+      existing.repo !== releaseSourceRevision.repo ||
+      existing.remoteName !== releaseSourceRevision.remoteName ||
+      existing.remoteUrlHash !== releaseSourceRevision.remoteUrlHash ||
+      existing.mainBranch !== releaseSourceRevision.mainBranch)
+  ) {
+    const error = new Error(
+      `RELEASE_PUBLISH_REVISION_CHANGED: change ${loaded.changeId} 已冻结 ${existing.baseCommit}，不能改为 ${releaseSourceRevision.baseCommit}`
+    );
+    error.code = 'RELEASE_PUBLISH_REVISION_CHANGED';
+    throw error;
+  }
+  const release = {
+    ...(loaded.release && !loaded.release.__invalid ? loaded.release : {}),
+    schemaVersion: SDD_SCHEMA_VERSION,
+    changeId: loaded.changeId,
+    mainlinePolicy: 'merge-after-publish-v1',
+    releaseSourceRevision,
+  };
+  if (JSON.stringify(release) !== JSON.stringify(loaded.release)) {
+    writeJsonFile(loaded.releaseFile, release);
+  }
+  return release;
+}
+
 function validateReleaseManifest(release, releasePlan, legacyMode = false) {
   const errors = [];
   const warnings = [];
@@ -1982,6 +2064,60 @@ function syncSddChange(options = {}) {
 }
 
 function archiveSddChange(options = {}) {
+  const releaseLoaded = loadSddChange(options);
+  const coverageTargets = normalizeCoverageResources(releaseLoaded.coverage, {});
+  const releaseTargets = mergeAffectedScopes(
+    options.targets,
+    options.releasePlan?.targets,
+    releaseLoaded.release?.targets,
+    coverageTargets,
+    releaseLoaded.meta,
+    { files: options.files },
+    { files: options.releasePlan?.changedFiles },
+    { files: releaseLoaded.release?.changedFiles }
+  );
+  const riskAssessment =
+    releaseLoaded.meta?.riskMetadata?.assessment ||
+    releaseLoaded.meta?.riskAssessment ||
+    {};
+  const metadataDeclaresHighRisk =
+    ['l2', 'l3'].includes(String(releaseLoaded.meta?.riskTier || '').toLowerCase()) ||
+    ['high', 'critical'].includes(
+      String(releaseLoaded.meta?.riskLevel || '').toLowerCase()
+    ) ||
+    [
+      'schema',
+      'permission',
+      'auth',
+      'publicAccess',
+      'dataMigration',
+      'destructive',
+      'crossResource',
+    ].some(key => riskAssessment[key] === true);
+  const requiresMainlineClosure =
+    hasHighRiskTargets(releaseTargets) ||
+    Boolean(releaseTargets.backend) ||
+    Boolean(releaseTargets.contracts) ||
+    classifyHighRiskFiles(releaseTargets.files).length > 0 ||
+    metadataDeclaresHighRisk ||
+    Boolean(releaseLoaded.release?.mainlinePolicy) ||
+    Boolean(releaseLoaded.release?.releaseSourceRevision);
+  if (requiresMainlineClosure) {
+    if (
+      !releaseLoaded.release ||
+      releaseLoaded.release.__invalid ||
+      !releaseLoaded.release.releaseSourceRevision
+    ) {
+      const error = new Error(
+        'SDD_RELEASE_SOURCE_LINEAGE_REQUIRED: 高风险 change 归档必须保留 release.json 的冻结发布提交；--force 不能绕过主分支回合证据'
+      );
+      error.code = 'SDD_RELEASE_SOURCE_LINEAGE_REQUIRED';
+      throw error;
+    }
+    assertReleaseSourceIntegrated(releaseLoaded.release.releaseSourceRevision, {
+      cwd: options.cwd || process.cwd(),
+    });
+  }
   const verify = verifySddChange({ ...options, stage: 'archive' });
   if (!verify.passed && !options.force) {
     const first = verify.errors[0];
@@ -2032,6 +2168,7 @@ module.exports = {
   normalizeSddVerifyStage,
   proposeQuickSddChange,
   proposeSddChange,
+  recordSddReleaseSourceRevision,
   approveSddChange,
   syncSddChange,
   validateQuickSddScope,

package/lib/workspace-bootstrap.js

@@ -2,10 +2,20 @@ const fs = require('fs');
 const path = require('path');
 
 const ROOT_DIR = path.join(__dirname, '..');
-const TEMPLATE_DIR = path.join(ROOT_DIR, 'templates', 'sy-lowcode-app-workspace');
+const LEGACY_TEMPLATE_DIR = path.join(
+  ROOT_DIR,
+  'templates',
+  'sy-lowcode-app-workspace'
+);
+const REACT_SPA_TEMPLATE_DIR = path.join(
+  ROOT_DIR,
+  'templates',
+  'openxiangda-react-spa'
+);
+const TEMPLATE_DIR = LEGACY_TEMPLATE_DIR;
 
 // AI 引导/守卫"四件套 + glob rules"清单。
-// 这些路径是相对于 workspace 根，文件源都来自 templates/sy-lowcode-app-workspace。
+// 这些路径相对于 workspace 根；源模板必须与现有 workspace runtime 匹配。
 const BOOTSTRAP_FILES = [
   'AGENTS.md',
   'scripts/guard-publish.mjs',
@@ -36,15 +46,18 @@ function bootstrapWorkspace(options = {}) {
   const targetDir = path.resolve(options.dir || process.cwd());
   const force = Boolean(options.force);
   const dryRun = Boolean(options.dryRun);
+  const templateDir = resolveWorkspaceTemplateDir(targetDir, options.runtime);
 
-  if (!fs.existsSync(TEMPLATE_DIR)) {
-    throw new Error(`workspace 模板不存在: ${TEMPLATE_DIR}`);
+  if (!fs.existsSync(templateDir)) {
+    throw new Error(`workspace 模板不存在: ${templateDir}`);
   }
   if (!fs.existsSync(targetDir) || !fs.statSync(targetDir).isDirectory()) {
     throw new Error(`目标目录不存在或不是目录: ${targetDir}`);
   }
 
-  const fileOps = BOOTSTRAP_FILES.map(rel => planFileOp(rel, targetDir, force));
+  const fileOps = BOOTSTRAP_FILES.map(rel =>
+    planFileOp(rel, targetDir, force, templateDir)
+  );
   const packageJsonOp = planPackageJsonOp(targetDir, force);
 
   if (!dryRun) {
@@ -61,6 +74,7 @@ function bootstrapWorkspace(options = {}) {
 
   return {
     targetDir,
+    runtime: templateDir === REACT_SPA_TEMPLATE_DIR ? 'react-spa' : 'legacy',
     dryRun,
     force,
     files: fileOps.map(op => ({
@@ -79,8 +93,8 @@ function bootstrapWorkspace(options = {}) {
   };
 }
 
-function planFileOp(relativePath, targetDir, force) {
-  const sourcePath = path.join(TEMPLATE_DIR, relativePath);
+function planFileOp(relativePath, targetDir, force, templateDir = TEMPLATE_DIR) {
+  const sourcePath = path.join(templateDir, relativePath);
   const targetPath = path.join(targetDir, relativePath);
   if (!fs.existsSync(sourcePath)) {
     return {
@@ -126,6 +140,20 @@ function planFileOp(relativePath, targetDir, force) {
   };
 }
 
+function resolveWorkspaceTemplateDir(targetDir, explicitRuntime) {
+  const normalized = String(explicitRuntime || '').trim().toLowerCase();
+  if (['react-spa', 'spa'].includes(normalized)) return REACT_SPA_TEMPLATE_DIR;
+  if (['legacy', 'classic'].includes(normalized)) return LEGACY_TEMPLATE_DIR;
+  const configFile = path.join(targetDir, 'app-workspace.config.ts');
+  if (fs.existsSync(configFile)) {
+    const configText = fs.readFileSync(configFile, 'utf8');
+    if (/runtimeMode\s*:\s*["']react-spa["']/i.test(configText)) {
+      return REACT_SPA_TEMPLATE_DIR;
+    }
+  }
+  return LEGACY_TEMPLATE_DIR;
+}
+
 function planPackageJsonOp(targetDir, force) {
   const targetPath = path.join(targetDir, 'package.json');
   const relativePath = 'package.json';
@@ -235,4 +263,5 @@ module.exports = {
   BOOTSTRAP_FILES,
   PACKAGE_JSON_GUARD_SCRIPTS,
   bootstrapWorkspace,
+  resolveWorkspaceTemplateDir,
 };

package/lib/workspace-init.js

@@ -96,7 +96,7 @@ function initWorkspace(options = {}) {
     installedDependencies: install,
     bound,
     sdd,
-    nextSteps: buildNextSteps(targetDir, install, bound),
+    nextSteps: buildNextSteps(targetDir, install, bound, runtime),
   };
 }
 
@@ -173,7 +173,7 @@ function runInstall(targetDir) {
   }
 }
 
-function buildNextSteps(targetDir, installedDependencies, bound) {
+function buildNextSteps(targetDir, installedDependencies, bound, runtime) {
   const steps = [`cd ${targetDir}`];
   if (!installedDependencies) steps.push('pnpm install');
   if (!bound) {
@@ -181,7 +181,16 @@ function buildNextSteps(targetDir, installedDependencies, bound) {
   }
   const profileArg = bound ? bound.profile : '<name>';
   steps.push(`openxiangda env --profile ${profileArg}`);
-  steps.push(`openxiangda workspace publish --profile ${profileArg}`);
+  steps.push('git switch -c codex/<change>');
+  steps.push('openxiangda sdd propose <change>');
+  steps.push(
+    runtime === 'react-spa'
+      ? `openxiangda runtime deploy --no-activate --change <change> --profile ${profileArg}`
+      : `openxiangda workspace publish --dry-run --only <exact-codes> --change <change> --profile ${profileArg}`
+  );
+  steps.push(
+    `发布后将冻结提交 merge/fast-forward 并 push 到主分支，再运行 openxiangda release end --profile ${profileArg}`
+  );
   return steps;
 }
 

package/lib/worktree-owner.js

@@ -99,6 +99,19 @@ function releaseWorktreeOwner(options = {}) {
   return withOwnerLock(file, () => {
     const current = readOwnerFile(file);
     if (!current) return { released: false, active: false, file };
+    const expectedThreadId = text(options.expectedThreadId);
+    const expectedChangeId = text(options.expectedChangeId);
+    if (
+      (expectedThreadId && text(current.threadId) !== expectedThreadId) ||
+      (expectedChangeId && text(current.changeId) !== expectedChangeId)
+    ) {
+      const error = new Error(
+        'WORKTREE_OWNER_STATE_CHANGED: worktree owner 与待释放的精确任务/change 不一致，禁止清理'
+      );
+      error.code = 'WORKTREE_OWNER_STATE_CHANGED';
+      error.owner = current;
+      throw error;
+    }
     const foreign =
       identity.threadId &&
       current.threadId &&

package/openxiangda-skills/SKILL.md

@@ -26,11 +26,13 @@ This file is a router and safety card. Read only the one or two subskills select
 ## Scope before work
 
 1. Work from the app workspace root and pass `--profile <name>` to every write or release command.
-2. In a shared or dirty checkout, use an isolated Git worktree/branch. `sdd propose|quick|context` automatically claims the current worktree for `CODEX_THREAD_ID`; if another task owns it, stop and move to a separate worktree instead of taking over its files.
+2. In a shared or dirty checkout, use an isolated Git worktree/branch. `sdd propose|quick|context` automatically claims the current worktree for `CODEX_THREAD_ID`; if another task owns it, stop and move to a separate worktree instead of taking over its files. A release is not closed until its exact frozen commit has been merged (without squash/rebase) and pushed to the authoritative default branch.
 3. Give the task one stable SDD change id. Use `--change <id>` on context, plan, check, verify, publish, and archive commands when supported.
 4. Plan and publish exact resource codes with `--only <codes>` or `--code <code>`; a type-only or full-resource publish is allowed only when the dependency closure intentionally contains the whole type/application.
 5. A React SPA page change rebuilds one application runtime. Commit the complete build input first, upload/preview with `runtime deploy --no-activate`, and promote only from a clean merged release head that descends from the online Runtime source revision.
 
+An exact Function/Automation selector is an early scope boundary: unrelated manifests, source dependency graphs, and JS_CODE targets must not be read, typechecked, or built. Transitive/shared/ambient dependencies of the selected entry remain included. No selector intentionally keeps full-workspace behavior.
+
 Never infer a release scope from a globally dirty `git status` when multiple changes are present. Never publish a temporary source tree that differs from the reviewed patch.
 
 ## Risk and approval
@@ -79,12 +81,16 @@ openxiangda sdd verify <change> --changed --stage prepublish
 openxiangda release begin --change <change> --profile <name>
 openxiangda resource publish <type> --only <codes> --change <change> --profile <name>
 openxiangda runtime activate <reviewedReleaseId> --change <change> --profile <name>
+# Merge/fast-forward the frozen release commit into the remote default branch.
+openxiangda release integration-status --profile <name>
 openxiangda release end --profile <name>
 ```
 
 `resource plan` and publish dry-runs are strictly GET/HEAD-only. `READ_ONLY_AUTH_REQUIRED` means the access token expired; run `openxiangda auth refresh --profile <name>` or log in again before retrying. Never add an automatic refresh POST inside a plan.
 
-`release begin --change` freezes the reviewed Git source base plus the selected remote change baseline. Before any live write, the CLI preflights the complete target set. A worktree based on obsolete source fails with `SOURCE_BASE_DIVERGED`; a selected remote field changed after the baseline fails with `RESOURCE_FIELD_CONFLICT`. Resolve/merge, rebuild, and re-plan instead of forcing the old release.
+`release begin --change` separately freezes the change base and the actual publish source: a clean committed `HEAD` on a named branch that already contains the current authoritative remote default branch. Before any live write, the CLI preflights the complete target set and rejects source changes during the release. A worktree based on obsolete source fails with `SOURCE_BASE_DIVERGED`/`RELEASE_SOURCE_BEHIND_MAIN`; a selected remote field changed after the baseline fails with `RESOURCE_FIELD_CONFLICT`. Resolve/merge, rebuild, and re-plan instead of forcing the old release.
+
+After promotion, immediately merge or fast-forward the exact frozen publish commit into the authoritative remote default branch and push it. `release integration-status` reports the result; normal `release end` refuses with `RELEASE_MAIN_MERGE_PENDING` until the remote mainline contains that exact SHA, so squash/rebase merges do not count. The authoritative target comes only from the live remote default `main`/`master`; local-only refs, overrides, and lease expiry cannot clear this obligation. Archive the SDD change from the updated mainline.
 
 `runtime deploy` separately freezes the clean committed `HEAD` as `sourceRevision` together with the current active Runtime parent before any build or upload. Any deploy whose source does not descend from the online Runtime fails with `RUNTIME_SOURCE_BASE_DIVERGED`, including `--no-activate`; this prevents staging an old preview for later activation. `--no-build` does not bypass this guard. Only an intentional audited rollback may use `--allow-runtime-rollback --reason "<at least 8 characters>"`, and that flag never permits dirty or non-Git input. SDD evidence under `openspec/` and generated/state paths do not make Runtime source dirty.
 
@@ -92,7 +98,7 @@ For a whole-app release, keep changed Runtime/Page/Backend/Form children staged
 
 When a Function or Automation is selected because its TypeScript source changed, publishing is source-only by default. Eligible existing Function/Automation updates in the same command use one immutable Backend Release (`prepare -> verify -> activate`) and one database transaction, so a stale member produces zero resource writes and noops do not advance versions/timestamps. Online bindings, input/output contracts, metadata, trigger/view configuration, and enabled/published state remain unchanged. Only an explicit Backend Release `head` HTTP 404 permits the warned compatibility source PATCH. A complete manifest replacement is exceptional and requires exact `--only/--code` plus `--replace-manifest --reason "..."`.
 
-The lease is app-level promotion ownership, while worktree ownership prevents two Codex tasks from editing/publishing through the same source directory. Different worktrees may keep developing and validating. Always run `release end` after promotion or abandonment; stale sessions expire automatically. Use full resource/runtime publish only when the approved dependency closure is app-wide.
+The lease is app-level promotion ownership, while worktree ownership prevents two Codex tasks from editing/publishing through the same source directory. Different worktrees may keep developing and validating. After promotion, merge/push the frozen SHA and run normal `release end`; an expired lease still retains reconciliation evidence. Use full resource/runtime publish only when the approved dependency closure is app-wide.
 
 ## Always
 

package/openxiangda-skills/references/automation-v3.md

@@ -287,7 +287,7 @@ Use JS_CODE V2 when the script is local to one automation graph node.
 }
 ```
 
-Author source in `src/js-code-nodes/<scriptCode>/index.ts`. AI-authored source must be TypeScript. Build with `pnpm build-js-code --script <scriptCode>`; the command runs TypeScript validation before bundling. During validate/create, the CLI uploads the generated bundle, replaces `sourceFile.localPath` with `{ bucketName, objectName, sha256, ... }`, and the backend verifies sha256 before execution.
+Author source in `src/js-code-nodes/<scriptCode>/index.ts`. AI-authored source must be TypeScript. Build with `pnpm build-js-code --script <scriptCode>`; the explicit selector typechecks only that entry plus its transitive/shared/ambient dependencies before bundling, while an unscoped build validates the whole workspace. During validate/create, the CLI uploads the generated bundle, replaces `sourceFile.localPath` with `{ bucketName, objectName, sha256, ... }`, and the backend verifies sha256 before execution.
 
 The backend runs the snapshot in the trusted Node runtime, applies the node timeout (`30000` ms by default), stores execution logs, and writes the returned value to the node output and `variables.node_<nodeId>`. Scripts may use `export default async function (ctx) {}`, `module.exports = async (ctx) => {}`, `require`, `process`, `Buffer`, arbitrary HTTP, and `platform.api` for `/openxiangda-api/v1`.
 

package/openxiangda-skills/references/resource-manifest-cheatsheet.md

@@ -754,7 +754,7 @@ export default async function (ctx) {
 }
 ```
 
-构建：`pnpm build-js-code --script sync_customer`（先 `tsc` 再打包到 `dist/js-code-nodes/<code>/index.cjs`）。CLI validate/create/publish 时会上传快照、用 `{ bucketName, objectName, sha256 }` 替换 `sourceFile.localPath`。
+构建：`pnpm build-js-code --script sync_customer`（只校验该入口及其传递/shared/ambient 依赖，再打包到 `dist/js-code-nodes/<code>/index.cjs`；仅无 selector 时全量校验）。CLI validate/create/publish 时会上传快照、用 `{ bucketName, objectName, sha256 }` 替换 `sourceFile.localPath`。
 
 `ctx.methods.*` 仍可用于兼容旧脚本；新脚本优先使用 `ctx.resources`、`ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`、`ctx.dataView`、`ctx.connector`、`ctx.notification`、`ctx.platform.roles` 和 `ctx.platform.api`。
 

package/openxiangda-skills/references/workflow-v3.md

@@ -371,7 +371,7 @@ File snapshot:
 }
 ```
 
-AI-authored JS_CODE source must be TypeScript under `src/js-code-nodes/<scriptCode>/index.ts`. When validating or creating, the CLI runs `pnpm build-js-code --script <scriptCode>`, which runs TypeScript validation first, bundles to `dist/js-code-nodes/<scriptCode>/index.cjs`, uploads the bundle, and replaces `sourceFile.localPath` with immutable snapshot metadata. The backend verifies snapshot `sha256`, runs it in the trusted Node runtime, applies the node timeout (`30000` ms by default), stores execution logs, and writes the returned value to the node output and `variables.node_<nodeId>`.
+AI-authored JS_CODE source must be TypeScript under `src/js-code-nodes/<scriptCode>/index.ts`. When validating or creating, the CLI runs `pnpm build-js-code --script <scriptCode>`, which typechecks only the selected entry plus its transitive/shared/ambient dependencies, bundles to `dist/js-code-nodes/<scriptCode>/index.cjs`, uploads the bundle, and replaces `sourceFile.localPath` with immutable snapshot metadata. An intentionally unscoped build retains full-workspace TypeScript validation. The backend verifies snapshot `sha256`, runs it in the trusted Node runtime, applies the node timeout (`30000` ms by default), stores console/runtime logs in the execution record, and writes the returned value to the node output and `variables.node_<nodeId>`.
 
 For reusable backend logic that should be shared by pages, automations, and workflows, prefer an App Function under `src/functions/<functionCode>/index.ts` plus `src/resources/functions/<functionCode>.json`. Workflow graphs that support App Function nodes can call it with:
 

package/openxiangda-skills/skills/openxiangda-core/SKILL.md

@@ -24,7 +24,7 @@ openxiangda sdd context --change <change> --changed --json
 
 Run `openxiangda update check --json` once per substantial task, on a suspected mismatch, or when the cached check is older than one day. If an update is installed, refresh skills once with `openxiangda skill install --force`.
 
-Every write/release command must include `--profile <name>`. In a shared checkout, create an isolated Git worktree before editing. `sdd propose|quick|context` claims `.openxiangda/worktree-owner.json` for the current `CODEX_THREAD_ID`; a foreign owner is a hard stop. `.openxiangda/state.json` maps profile-local IDs; it is not a collaboration lock.
+Every write/release command must include `--profile <name>`. In a shared checkout, create an isolated Git worktree and named feature branch before editing. `sdd propose|quick|context` claims `.openxiangda/worktree-owner.json` for the current `CODEX_THREAD_ID`; a foreign owner is a hard stop. `.openxiangda/state.json` maps profile-local IDs; it is not a collaboration lock. The task is not complete until the exact frozen publish SHA is merged without squash/rebase and pushed to the authoritative default branch.
 
 First-class direct configuration writes (form/page/menu/role/permission/workflow/connector/notification/auth/route/public-access/scope/data-view/storage/settings) also require `--change <id>` or a complete stored session created by `openxiangda release begin --change <id>`. Missing context fails locally with `PUBLISH_CONTEXT_REQUIRED` before any HTTP write. Dry-run, schema planning, validation, query/invoke/export/submit/execution/upload, and other data-plane actions do not acquire a lease. Direct Workflow publish/unpublish/delete additionally requires the frozen `--expected-revision`; never fetch the latest revision merely to replay an older payload.
 
@@ -53,6 +53,8 @@ openxiangda resource publish function --only function_a,function_b --profile <na
 
 `--code <code>` is the single-resource equivalent of `--only <codes>`. Type-only planning is appropriate for an intentional shared dependency closure. Unscoped full-resource planning/publishing is app-wide and requires an app-wide approved change.
 
+Selectors apply before manifest parsing, source dependency analysis, and JS_CODE typecheck/build. A scoped Function/Automation plan must touch only the selected targets plus their transitive/shared/ambient dependencies; an unscoped plan intentionally retains full-workspace behavior. Resource commands use the canonical scoped builder packaged with the installed CLI for standard workspaces, so old checked-in builders still receive the optimization; refresh/bootstrap the workspace script only for equivalent manual `pnpm build-js-code` behavior. Nonstandard custom builders remain an explicit compatibility fallback.
+
 Source-triggered Function/Automation targets use one immutable Backend Release by default. The CLI uploads every eligible existing source-only target, freezes the current Backend Release parent plus Git/change baseline, then runs `prepare -> verify -> activate`; activation first CAS-checks the entire set and applies all updates in one transaction. Never fall back to sequential PATCH after prepare/verify/activate has started. Compatibility fallback is allowed only when the Backend Release `head` feature probe is an explicit HTTP 404, and must warn. Existing online bindings, contracts, metadata, trigger/view configuration, and enabled/published state remain unchanged; noops do not advance resource versions/timestamps. A deliberate whole-definition replacement requires exact `--only/--code` and `--replace-manifest --reason "<why>"`; SDD bypass does not imply replacement authority.
 
 Use `openxiangda release backend-head|backend-list|backend-detail|backend-diff` to inspect immutable history. `backend-rollback <releaseId> --change <change> --reason "..."` prepares, verifies, and activates a new release from the historical snapshot; it never mutates or directly reactivates the old row. `backend-abort` stops prepared/verified work and `backend-retry` retries only recorded post-commit side effects. Do not fetch newer revisions to replay an older payload.
@@ -84,10 +86,12 @@ openxiangda sdd verify <change> --changed --stage prepublish
 openxiangda release begin --change <change> --profile <name>
 openxiangda resource publish <type> --only <codes> --change <change> --profile <name>
 openxiangda runtime activate <reviewedReleaseId> --change <change> --profile <name>
+# Merge/fast-forward the frozen release SHA to the remote default branch.
+openxiangda release integration-status --profile <name>
 openxiangda release end --profile <name>
 ```
 
-`runtime deploy --no-activate` uploads an immutable preview release from a clean committed `HEAD`. Before any build/upload, every Runtime deploy acquires the app publish lease and freezes that `sourceRevision` plus the current active Runtime parent. Both staged and activating deploys are rejected when the local source does not descend from the online source revision, including with `--no-build`; an intentional rollback requires `--allow-runtime-rollback --reason "<at least 8 characters>"` and remains auditable. SDD evidence in `openspec/` and generated/state directories are excluded from the source-clean check. `release begin --change` obtains app-level promotion ownership and freezes the reviewed Git source base together with the selected remote resource-field heads. Before the first live write, one preflight validates the complete target set. Long asynchronous publish phases run a 30-second lease heartbeat; `PUBLISH_LEASE_LOST` is a hard stop and no later write may run. Synchronous Runtime builds first extend to the platform maximum TTL and must renew successfully before the next write. Do not move Runtime build ahead of lease/upload-plan: direct-storage releases compile the provider-specific `assetBaseUrl` returned by that protected plan, and silently substituting the gateway URL changes chunk/publicPath behavior. Parallel development remains available in other worktrees. Promote only a reviewed release built from the merged head, then always `release end`.
+`runtime deploy --no-activate` uploads an immutable preview release from a clean committed `HEAD`. Before any build/upload, every Runtime deploy acquires the app publish lease and freezes that `sourceRevision` plus the current active Runtime parent. Both staged and activating deploys are rejected when the local source does not descend from the online source revision, including with `--no-build`; an intentional rollback requires `--allow-runtime-rollback --reason "<at least 8 characters>"` and remains auditable. SDD evidence in `openspec/` and generated/state directories are excluded from the source-clean check. `release begin --change` obtains app-level promotion ownership, freezes the actual clean publish `HEAD` independently from the earlier change base, and requires it to contain the current remote default branch. Before the first live write, one preflight validates the complete target set. Long asynchronous publish phases run a 30-second lease heartbeat; `PUBLISH_LEASE_LOST` is a hard stop and no later write may run. Synchronous Runtime builds first extend to the platform maximum TTL and must renew successfully before the next write. Do not move Runtime build ahead of lease/upload-plan: direct-storage releases compile the provider-specific `assetBaseUrl` returned by that protected plan, and silently substituting the gateway URL changes chunk/publicPath behavior. Parallel development remains available in other worktrees. After promotion, merge/fast-forward and push the frozen SHA to the authoritative default branch, check `release integration-status`, then run normal `release end`. The target is frozen from the live remote default `main`/`master`; overrides, local-only refs, and lease expiry cannot clear the pending-mainline evidence.
 
 `resource plan`, `resource publish`, and `runtime deploy` report coarse phases on stderr and emit a heartbeat after 15 seconds without completion. JSON stdout stays machine-readable and includes `timings`; use it to identify whether time is spent in plan, preflight, build, upload, write, or activate instead of rerunning an opaque command.
 
@@ -125,6 +129,8 @@ openxiangda workspace bind --profile dev --app-type APP_XXXX
 - `RUNTIME_SOURCE_DIRTY` or `RUNTIME_SOURCE_LINEAGE_REQUIRED`: commit all build inputs in an auditable Git repository; generated `dist/` and `.openxiangda/` state do not count, and `--no-build` is not an escape hatch.
 - `PUBLISH_LEASE_HELD`: another change owns promotion; keep developing/testing locally or wait for its release/expiry. Never bypass it with an unleased write.
 - `PUBLISH_LEASE_LOST`: heartbeat renewal failed or the lease expired during a long phase; stop immediately, inspect the active head, re-plan, and start a new release. Never replay the remaining writes with a newly fetched revision.
+- `RELEASE_SOURCE_DIRTY`, `RELEASE_SOURCE_BEHIND_MAIN`, or `RELEASE_PUBLISH_REVISION_CHANGED`: commit all build inputs, merge the current remote mainline into the feature branch, and restart the release from the tested SHA.
+- `RELEASE_MAIN_MERGE_PENDING`: the live release SHA is not yet contained in the authoritative remote default branch. Merge without squash/rebase, push, rerun `release integration-status`, then `release end`.
 - `WORKTREE_OWNED_BY_ANOTHER_TASK`: another Codex task owns this source directory; switch to an isolated worktree. Only force-claim with an explicit reason after confirming the original task ended.
 - Plan unexpectedly includes unrelated resources: do not publish; correct `--change`/`--only` or dependency closure.
 - A write updates state: let the CLI use its lock/atomic merge; do not hand-edit state or run conflicting legacy clients.

package/openxiangda-skills/skills/openxiangda-workflow-automation/SKILL.md

@@ -29,7 +29,7 @@ Create a workflow only when the scenario has **real approval semantics**: approv
 - ✅ Delayed approval start: save the process-form record first with `StandardFormPage submitBehavior="save-draft"` or `sdk.form.create({ formUuid, data, saveAsDraft: true, startProcess: false })`, then start approval in place with `sdk.process.startFromExistingInstance({ formUuid, formInstId })` or `StandardFormPage submitBehavior="start-existing-process"`.
 - ✅ Return-to-initiator flows: use `returnPolicy: { scopeType: "initiator", resubmitMode: "resume_current" | "replay" }` or `flow.action.returnToInitiator()`. The runtime capabilities protocol exposes `resubmit` only for pending `originator_return` tasks; return to a previous approval node continues through the normal `approve` action.
 - ✅ Reusable backend business logic: prefer **App Function** (`src/functions/<functionCode>/index.ts` + `src/resources/functions/<functionCode>.json`), then call it from page `sdk.function.invoke` or automation/workflow `function_call`.
-- ✅ JS_CODE V2 trusted_node: source in TypeScript under `src/js-code-nodes/<scriptCode>/index.ts`, `src/automations/<resourceCode>/index.ts`, or `src/functions/<functionCode>/index.ts`. Run `pnpm build-js-code --script <code>` (validates with `tsc` first).
+- ✅ JS_CODE V2 trusted_node: source in TypeScript under `src/js-code-nodes/<scriptCode>/index.ts`, `src/automations/<resourceCode>/index.ts`, or `src/functions/<functionCode>/index.ts`. Run `pnpm build-js-code --script <code>`; an explicit selector validates/builds only that entry plus its transitive/shared/ambient dependencies, while an unscoped command validates the whole workspace.
 - ✅ Use `trigger_v2` for new automation triggers; CLI fills root `appType` / `formUuid` from active profile when `--form-code` is provided.
 - ✅ Use logical `workflowCode` / `automationCode` locally; live IDs are profile-isolated under `.openxiangda/state.json`.
 - ✅ `ctx.logger.debug/info/warn/error(message, data?)` at every important step — inspect via `automation executions` / `automation logs` / `automation diagnose`.
@@ -112,7 +112,7 @@ For new AI-authored workflows where users do not need canvas editing, prefer com
 Do not use JS_CODE for simple UI interactions, ordinary form validation, display-only page behavior, or logic that belongs in a normal React code page. For non-trivial backend logic, prefer JS_CODE V2 trusted Node scripts over large inline snippets. AI-authored JS_CODE source must be TypeScript:
 
 1. Put source in `src/js-code-nodes/<scriptCode>/index.ts`.
-2. Run `pnpm build-js-code --script <scriptCode>`. This command runs TypeScript validation first and only bundles after `tsc` passes.
+2. Run `pnpm build-js-code --script <scriptCode>`. In a refreshed workspace this command typechecks only the selected entry and its transitive/shared/ambient dependencies, then bundles after validation passes; omit the selector only for an intentional full-workspace validation. Installed CLI resource commands independently use their packaged canonical scoped builder, including against standard older workspaces.
 3. In workflow or automation JSON, use:
    ```json
    {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.162",
+  "version": "1.0.164",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {
@@ -63,6 +63,7 @@
     "build:sdk": "tsup --config packages/sdk/tsup.config.ts",
     "check": "node --check bin/openxiangda.js && node --check lib/*.js && node --check packages/sdk/src/build-source/src/cli.mjs && node --check packages/sdk/src/build-source/scripts/*.mjs && node --check packages/sdk/src/build-source/scripts/utils/*.mjs",
     "test": "npm run check && node scripts/http-proxy-smoke.mjs && node scripts/form-export-cli-smoke.mjs && node scripts/open-api-cli-smoke.mjs",
+    "prepublishOnly": "node scripts/release-mainline-guard.mjs",
     "prepack": "npm run build:sdk",
     "test:profile-isolation": "bash scripts/profile-isolation-smoke.sh",
     "test:resource-plan": "node scripts/resource-plan-smoke.mjs",
@@ -84,6 +85,7 @@
     "test:publish-lease-state": "node scripts/publish-lease-state-smoke.mjs",
     "test:publish-lease-heartbeat": "node scripts/publish-lease-heartbeat-smoke.mjs",
     "test:release-telemetry": "node scripts/release-telemetry-smoke.mjs",
+    "test:release-mainline": "node scripts/release-mainline-smoke.mjs",
     "test:publish-lease-cli": "node scripts/publish-lease-cli-smoke.mjs",
     "test:publish-context": "node scripts/publish-context-smoke.mjs",
     "test:backend-release-cli": "node scripts/backend-release-cli-smoke.mjs",

package/templates/openxiangda-react-spa/.cursor/rules/openxiangda-resources.mdc

@@ -24,6 +24,7 @@ openxiangda resource typegen --profile <name>
 - Guest access to forms, dataViews, functions, and connectors requires explicit policy `grants`.
 - Connector secrets and third-party credentials belong in the platform backend, never in manifests or page source.
 - Formal changes should keep Git as the source of truth: edit manifests, validate, plan, then publish.
+- Exact selectors apply before manifest/source analysis and JS_CODE build: touch only selected targets plus transitive/shared/ambient dependencies; omit selectors only for intentional full-workspace work.
 - `resource plan` and publish dry-runs are GET/HEAD-only. On `READ_ONLY_AUTH_REQUIRED`, run `openxiangda auth refresh --profile <name>` or log in again before retrying; never refresh inside the plan.
 - Source-triggered Function/Automation publishing patches only source fields on the server and preserves online bindings/contracts/metadata/state. Whole-manifest replacement requires `--replace-manifest --reason "..."`.
-- Formal promotion runs `release begin --change` (freeze Git + remote baseline, preflight the complete set) through `release end`. Reconcile `SOURCE_BASE_DIVERGED` / `RESOURCE_FIELD_CONFLICT`; never retry an old full payload with a fresh revision.
+- Formal promotion freezes the clean publish HEAD separately from the change base, preflights the complete set, and rejects `SOURCE_BASE_DIVERGED` / `RELEASE_SOURCE_BEHIND_MAIN` / `RESOURCE_FIELD_CONFLICT`. After activation, merge/fast-forward and push the frozen SHA, verify `release integration-status`, then run normal `release end`; squash/rebase does not preserve the released source.

package/templates/openxiangda-react-spa/.cursor/rules/openxiangda.mdc

@@ -13,7 +13,7 @@ This is an OpenXiangda React SPA workspace. See [AGENTS.md](mdc:AGENTS.md) for f
 |---|---|
 | publish resources | `openxiangda resource publish <type> --only <codes> --profile <name> --change <change>` |
 | deploy frontend | `openxiangda runtime deploy --profile <name> --no-activate` |
-| full deploy | `pnpm deploy -- --profile <name>` |
+| formal promotion | `release begin` → exact publish/activate → merge/push frozen SHA → `integration-status` → `release end` |
 | diff / plan | `openxiangda resource plan <type> --only <codes> --profile <name>` |
 | diagnose | `openxiangda doctor --profile <name> --json` |
 | external backend Open API | `openxiangda-open-api` + `openxiangda open-api spec describe ...` |
@@ -26,7 +26,7 @@ This is an OpenXiangda React SPA workspace. See [AGENTS.md](mdc:AGENTS.md) for f
 - L0 read-only/docs/tests need no SDD; L1 narrow reversible fixes record exact scope without a redundant second confirmation; schema, business Functions, Automation/Workflow, permissions, auth/public access, data writes, and runtime/config are L2/L3 full-SDD work. Live evidence/archive are post-release stages.
 - Very small copy/style/binding changes may use `openxiangda sdd quick <change> ...`; quick mode records exact low-risk scope without a redundant proposal/approval loop when the user already requested it.
 - Use staged verification: `--stage implementation` while developing, `--stage prepublish` before promotion, and `--stage postpublish` after activation.
-- Before platform writes, run `openxiangda release begin --change <change> --profile <name>` to freeze Git + remote field heads and preflight the complete target set; finish or abandon with `openxiangda release end --profile <name>`.
+- Before platform writes, run `openxiangda release begin --change <change> --profile <name>` to freeze the actual clean publish HEAD separately from the change base, require it to contain the authoritative remote mainline, and preflight the complete target set. After promotion, merge/fast-forward and push that exact SHA (no squash/rebase), run `release integration-status`, then normal `release end`. Only the live remote default `main`/`master` is authoritative; local refs, overrides, and lease expiry cannot clear the evidence.
 - Account/role/permission/RBAC/organization-account/query-param authorization work must run `openxiangda design gates --topic permissions --json`, choose `managed-platform-account`, `existing-platform-user-assignment`, `static-role-permission`, or `query-param-context`, and write the permission matrix.
 - Roles that create roles, assign members, grant API permissions, maintain permission groups, or manage organization accounts must declare `apiPermissionCodes`, such as `app:role:manage`, `app:page-permission-group:manage`, `app:form-permission-group:manage`, and `app:organization:manage`.
 - `src/resources/**` is the resource source of truth; use `validate -> plan -> publish`.

package/templates/openxiangda-react-spa/.qoder/rules/openxiangda-resources.md

@@ -24,6 +24,7 @@ openxiangda resource typegen --profile <name>
 - Guest access to forms, dataViews, functions, and connectors requires explicit policy `grants`.
 - Connector secrets and third-party credentials belong in the platform backend, never in manifests or page source.
 - Formal changes should keep Git as the source of truth: edit manifests, validate, plan, then publish.
+- Exact selectors apply before manifest/source analysis and JS_CODE build: touch only selected targets plus transitive/shared/ambient dependencies; omit selectors only for intentional full-workspace work.
 - `resource plan` and publish dry-runs are GET/HEAD-only. On `READ_ONLY_AUTH_REQUIRED`, run `openxiangda auth refresh --profile <name>` or log in again before retrying; never refresh inside the plan.
 - Source-triggered Function/Automation publishing patches only source fields on the server and preserves online bindings/contracts/metadata/state. Whole-manifest replacement requires `--replace-manifest --reason "..."`.
-- Formal promotion runs `release begin --change` (freeze Git + remote baseline, preflight the complete set) through `release end`. Reconcile `SOURCE_BASE_DIVERGED` / `RESOURCE_FIELD_CONFLICT`; never retry an old full payload with a fresh revision.
+- Formal promotion freezes the clean publish HEAD separately from the change base, preflights the complete set, and rejects `SOURCE_BASE_DIVERGED` / `RELEASE_SOURCE_BEHIND_MAIN` / `RESOURCE_FIELD_CONFLICT`. After activation, merge/fast-forward and push the frozen SHA, verify `release integration-status`, then run normal `release end`; squash/rebase does not preserve the released source.

package/templates/openxiangda-react-spa/.qoder/rules/openxiangda.md

@@ -13,8 +13,8 @@ This is an OpenXiangda React SPA workspace. Read [AGENTS.md](AGENTS.md) for full
 |---|---|
 | 发布资源 / publish resources | `openxiangda resource publish <type> --only <codes> --change <change> --profile <name>` |
 | 发布前端预览 / deploy preview | `openxiangda runtime deploy --profile <name> --no-activate --json` |
-| 正式 promotion | `release begin --change <change>` → publish/activate → `release end` |
-| 完整部署 / deploy | `pnpm deploy -- --profile <name>` |
+| 正式 promotion | `release begin --change <change>` → publish/activate → merge/push frozen SHA → `integration-status` → `release end` |
+| 完整部署 / deploy | 使用同一 change + 精确 `--only` 的显式命令；无范围 `pnpm deploy` 已停用 |
 | 资源计划 / diff | `openxiangda resource plan <type> --only <codes> --profile <name>` |
 | 诊断 / 环境 | `openxiangda doctor --profile <name> --json` / `openxiangda env --profile <name>` |
 | 外部后端 / 三方系统开放接口 | `openxiangda-open-api` + `openxiangda open-api spec describe ...` |
@@ -30,7 +30,7 @@ This is an OpenXiangda React SPA workspace. Read [AGENTS.md](AGENTS.md) for full
 - `src/resources/**` 是工程化资源来源，正式多资源变更走 `validate -> plan -> publish`。
 - 默认按逻辑资源 code 使用 `--only` 或单资源 `--code`；全类型/全应用发布必须由批准的依赖闭包明确覆盖。
 - Function/Automation 源码触发默认走服务端 source-field PATCH，保留线上 bindings/contracts/metadata/trigger/view/enabled/published state；整包 manifest 替换必须加 `--replace-manifest --reason "..."`。
-- Promotion 必须持有 `release begin/end` 应用租约并沿用同一 `--change`。`release begin` 冻结 Git + 远端 baseline 并整体 preflight；`SOURCE_BASE_DIVERGED` / `RESOURCE_FIELD_CONFLICT` 必须合并、重建、重新计划。其他 worktree 可继续开发和测试。
+- Promotion 必须持有 `release begin/end` 应用租约并沿用同一 `--change`。`release begin` 分别冻结 change base 与实际 clean publish HEAD，并要求后者包含当前权威远端主分支；`SOURCE_BASE_DIVERGED` / `RELEASE_SOURCE_BEHIND_MAIN` / `RESOURCE_FIELD_CONFLICT` 必须合并、重建、重新计划。上线后 merge/fast-forward 并 push 冻结 SHA，运行 `release integration-status` 后才能正常 `release end`；squash/rebase 不算回合。权威目标只取远端实时默认 `main`/`master`，本地 ref、覆盖参数和租约过期均不能清除证据。
 - React SPA 路由由 `src/app/router.tsx` 管理，前端包通过 `openxiangda runtime deploy` 发布。
 - 表单附件预览使用 `AttachmentField` / `ImageField`；普通自定义页面使用 `AttachmentPreviewList` / `ImagePreviewGrid` / `useFilePreview`，不要伪造表单上下文、直接引用内部预览实现或维护扩展名白名单。
 - 页面权限、表单权限、公开访问 grants、App Function 后端检查是授权依据；前端只做展示保护。