openxiangda 1.0.164 → 1.0.166

package/lib/sdd.js

@@ -1223,6 +1223,12 @@ function getSddChangeScope(options = {}) {
     ...recordedChangedFiles,
     ...ownedFiles,
   ])).sort();
+  const releaseCommands = Array.isArray(loaded.release?.commands)
+    ? loaded.release.commands.filter(command => String(command || '').trim())
+    : [];
+  const plannedCommands = Array.isArray(loaded.meta?.release?.plannedCommands)
+    ? loaded.meta.release.plannedCommands.filter(command => String(command || '').trim())
+    : [];
   return {
     changeId: loaded.changeId,
     change: loaded.meta,
@@ -1232,7 +1238,9 @@ function getSddChangeScope(options = {}) {
     changedFiles,
     recordedChangedFiles,
     ownedFiles,
-    commands: Array.isArray(loaded.release?.commands) ? loaded.release.commands : [],
+    commands: releaseCommands.length > 0 ? releaseCommands : plannedCommands,
+    releaseCommands,
+    plannedCommands,
   };
 }
 
@@ -1382,6 +1390,7 @@ function buildSddGovernanceReport(options = {}) {
         targets,
         changedFiles: files,
         commands: options.commands || [],
+        actualCommands: options.actualCommands === true,
       },
     });
     if (!verify.passed) {
@@ -1439,15 +1448,20 @@ function getSddVerifyStagePolicy(stageValue) {
   if (stage === 'default') {
     return {
       stage,
-      taskStages: new Set(SDD_VERIFY_STAGES),
-      evidenceStages: new Set(SDD_VERIFY_STAGES),
+      // An unspecified verify is a prepublish check. Postpublish/archive
+      // evidence cannot exist yet and must never block ordinary development.
+      taskStages: new Set(['implementation', 'prepublish']),
+      evidenceStages: new Set(['prepublish']),
       requireRelease: true,
     };
   }
   const rank = SDD_VERIFY_STAGES.indexOf(stage);
   return {
     stage,
-    taskStages: new Set(SDD_VERIFY_STAGES.slice(0, rank + 1)),
+    taskStages:
+      stage === 'implementation'
+        ? new Set()
+        : new Set(SDD_VERIFY_STAGES.slice(0, rank + 1)),
     evidenceStages:
       stage === 'implementation'
         ? new Set()
@@ -1661,13 +1675,19 @@ function validateDeltaSpecs(changeDir) {
 
 function buildUpdatedReleaseManifest(loaded, releasePlan, verificationStage = 'default') {
   const verifiedAt = nowIso();
+  const reviewedCommands = Array.isArray(loaded.release?.commands)
+    ? loaded.release.commands.filter(command => String(command || '').trim())
+    : [];
   return {
     schemaVersion: SDD_SCHEMA_VERSION,
     changeId: loaded.changeId,
     ...(loaded.release && !loaded.release.__invalid ? loaded.release : {}),
     targets: releasePlan?.targets || loaded.release?.targets || {},
     changedFiles: releasePlan?.changedFiles || loaded.release?.changedFiles || [],
-    commands: releasePlan?.commands || loaded.release?.commands || [],
+    commands:
+      reviewedCommands.length > 0
+        ? reviewedCommands
+        : releasePlan?.commands || [],
     verifiedAt,
     verificationStage,
     verificationStages: {
@@ -1769,9 +1789,270 @@ function validateReleaseManifest(release, releasePlan, legacyMode = false) {
   if (releasePlan?.commands?.length && (!Array.isArray(release.commands) || release.commands.length === 0)) {
     errors.push({ name: 'sdd-release-commands-empty', message: 'release.json 未记录发布命令' });
   }
+  if (!legacyMode && Array.isArray(release.commands)) {
+    errors.push(
+      ...validateAtomicReleaseCommands(
+        release.commands,
+        targets,
+        release.changeId
+      )
+    );
+  }
   return { errors, warnings };
 }
 
+function commandFlagValue(command, name) {
+  const match = String(command || '').match(
+    new RegExp(`(?:^|\\s)--${escapeRegExp(name)}(?:=|\\s+)([^\\s]+)`)
+  );
+  return match ? match[1] : null;
+}
+
+function normalizedCommandSelectors(command) {
+  return Array.from(
+    new Set(
+      String(commandFlagValue(command, 'only') || commandFlagValue(command, 'code') || '')
+        .split(',')
+        .map(value => value.trim())
+        .filter(Boolean)
+    )
+  ).sort();
+}
+
+function normalizedResourcePublishTypes(command) {
+  const match = String(command || '').match(
+    /^openxiangda\s+resource\s+publish(?:\s+([^\s-][^\s]*))?/
+  );
+  if (!match?.[1]) return [];
+  const aliases = {
+    functions: 'function',
+    automations: 'automation',
+    workflows: 'workflow',
+    'form-settings': 'form-setting',
+  };
+  return Array.from(
+    new Set(
+      match[1]
+        .split(',')
+        .map(value => value.trim().toLowerCase())
+        .filter(Boolean)
+        .map(value => aliases[value] || value)
+    )
+  ).sort();
+}
+
+function sameStringSet(left, right) {
+  const normalizedLeft = Array.from(new Set(left || [])).sort();
+  const normalizedRight = Array.from(new Set(right || [])).sort();
+  return (
+    normalizedLeft.length === normalizedRight.length &&
+    normalizedLeft.every((value, index) => value === normalizedRight[index])
+  );
+}
+
+function validateAtomicReleaseCommands(
+  commands,
+  targets,
+  changeId,
+  options = {}
+) {
+  const errors = [];
+  const requireCompletePlan = options.requireCompletePlan !== false;
+  const normalized = commands.map(command => String(command || '').trim());
+  const publishCommands = normalized.filter(command =>
+    /^openxiangda\s+(?:workspace\s+publish|resource\s+publish|runtime\s+deploy|release\s+app-finalize)\b/.test(
+      command
+    )
+  );
+  for (const command of publishCommands) {
+    if (!/\s--profile(?:=|\s+)\S+/.test(command) || /<profile>/.test(command)) {
+      errors.push({
+        name: 'sdd-release-profile-missing',
+        message: `发布命令必须显式指定真实 --profile: ${command}`,
+      });
+    }
+    if (
+      changeId &&
+      !new RegExp(`\\s--change(?:=|\\s+)${escapeRegExp(changeId)}(?:\\s|$)`).test(
+        command
+      )
+    ) {
+      errors.push({
+        name: 'sdd-release-change-missing',
+        message: `发布命令必须绑定 --change ${changeId}: ${command}`,
+      });
+    }
+    if (/^openxiangda\s+workspace\s+publish\b/.test(command) && /\s--form(?:=|\s+)/.test(command)) {
+      errors.push({
+        name: 'sdd-release-direct-form-schema-forbidden',
+        message: `React SPA Form 必须走 staged form-setting bundle，禁止 workspace publish --form: ${command}`,
+      });
+    }
+    if (
+      /^openxiangda\s+resource\s+publish\s+form-setting\b/.test(command) &&
+      /\s--activate(?:\s|$)/.test(command)
+    ) {
+      errors.push({
+        name: 'sdd-release-direct-form-activation-forbidden',
+        message: `Form bundle 必须保持 staged，禁止在 Root App finalize 前 --activate: ${command}`,
+      });
+    }
+    if (
+      /^openxiangda\s+resource\s+publish\b/.test(command) &&
+      !/\s--(?:only|code)(?:=|\s+)/.test(command)
+    ) {
+      errors.push({
+        name: 'sdd-release-resource-scope-missing',
+        message: `resource publish 必须使用 --only/--code 精确范围: ${command}`,
+      });
+    }
+    if (
+      /^openxiangda\s+runtime\s+deploy\b/.test(command) &&
+      !/\s--no-activate(?:\s|$)/.test(command)
+    ) {
+      errors.push({
+        name: 'sdd-release-runtime-direct-activation-forbidden',
+        message: `Runtime 必须先 --no-activate 暂存，再由 App Release 原子激活: ${command}`,
+      });
+    }
+    const commandTypes = normalizedResourcePublishTypes(command);
+    const expectedBackendTypes = [
+      ...((targets.functions || []).length > 0 ? ['function'] : []),
+      ...((targets.automations || []).length > 0 ? ['automation'] : []),
+    ].sort();
+    if (
+      commandTypes.some(type => ['function', 'automation'].includes(type)) &&
+      expectedBackendTypes.length > 0
+    ) {
+      const qualified = expectedBackendTypes.length > 1;
+      const expectedSelectors = [
+        ...(targets.functions || []).map(code =>
+          qualified ? `function:${code}` : String(code)
+        ),
+        ...(targets.automations || []).map(code =>
+          qualified ? `automation:${code}` : String(code)
+        ),
+      ].sort();
+      if (!/\s--stage-only(?:\s|$)/.test(command)) {
+        errors.push({
+          name: 'sdd-release-backend-direct-activation-forbidden',
+          message: `Function/Automation 必须使用 --stage-only: ${command}`,
+        });
+      }
+      if (
+        !sameStringSet(commandTypes, expectedBackendTypes) ||
+        !sameStringSet(normalizedCommandSelectors(command), expectedSelectors)
+      ) {
+        errors.push({
+          name: 'sdd-release-backend-scope-inexact',
+          message: `Function/Automation 命令必须精确覆盖审核 selector，不能缺失或夹带资源: ${command}`,
+        });
+      }
+    }
+    if (
+      commandTypes.includes('form-setting') &&
+      (targets.forms || []).length > 0 &&
+      !sameStringSet(
+        normalizedCommandSelectors(command),
+        (targets.forms || []).map(String)
+      )
+    ) {
+      errors.push({
+        name: 'sdd-release-form-scope-inexact',
+        message: `Form bundle 命令必须精确覆盖审核 selector，不能缺失或夹带表单: ${command}`,
+      });
+    }
+  }
+
+  if (!requireCompletePlan) return errors;
+
+  const backendCodes = [
+    ...(targets.functions || []),
+    ...(targets.automations || []),
+  ];
+  if (backendCodes.length > 0) {
+    const backendStage = normalized.find(
+      command =>
+        /^openxiangda\s+resource\s+publish\b/.test(command) &&
+        /\s--stage-only(?:\s|$)/.test(command) &&
+        sameStringSet(normalizedResourcePublishTypes(command), [
+          ...((targets.functions || []).length > 0 ? ['function'] : []),
+          ...((targets.automations || []).length > 0 ? ['automation'] : []),
+        ]) &&
+        sameStringSet(normalizedCommandSelectors(command), [
+          ...(targets.functions || []).map(code =>
+            (targets.automations || []).length > 0
+              ? `function:${code}`
+              : String(code)
+          ),
+          ...(targets.automations || []).map(code =>
+            (targets.functions || []).length > 0
+              ? `automation:${code}`
+              : String(code)
+          ),
+        ])
+    );
+    if (!backendStage) {
+      errors.push({
+        name: 'sdd-release-backend-stage-missing',
+        message: 'Function/Automation 必须由一条精确 --only 的 --stage-only Backend Release 命令覆盖。',
+      });
+    }
+  }
+  if ((targets.forms || []).length > 0) {
+    const formStage = normalized.find(
+      command =>
+        /^openxiangda\s+resource\s+publish\s+form-setting\b/.test(command) &&
+        !/\s--activate(?:\s|$)/.test(command) &&
+        sameStringSet(
+          normalizedCommandSelectors(command),
+          (targets.forms || []).map(String)
+        )
+    );
+    if (!formStage) {
+      errors.push({
+        name: 'sdd-release-form-stage-missing',
+        message: 'Form 必须由精确 form-setting bundle 命令暂存为 FormRelease。',
+      });
+    }
+  }
+  if (targets.runtime) {
+    const runtimeStage = normalized.find(
+      command =>
+        /^openxiangda\s+runtime\s+deploy\b/.test(command) &&
+        /\s--no-activate(?:\s|$)/.test(command)
+    );
+    if (!runtimeStage) {
+      errors.push({
+        name: 'sdd-release-runtime-stage-missing',
+        message: 'Runtime 目标缺少 runtime deploy --no-activate 暂存命令。',
+      });
+    }
+  }
+  if (
+    backendCodes.length > 0 ||
+    (targets.forms || []).length > 0 ||
+    targets.runtime
+  ) {
+    const finalize = normalized.find(
+      command =>
+        /^openxiangda\s+release\s+app-finalize\b/.test(command) &&
+        /\s--staged-resources-json(?:=|\s+)\S+/.test(command)
+    );
+    if (!finalize) {
+      errors.push({
+        name: 'sdd-release-app-finalize-missing',
+        message: '暂存的 Form/Backend/Runtime 必须由 app-finalize 一次原子激活。',
+      });
+    }
+  }
+  return errors;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 function verifySddChange(options = {}) {
   const loaded = loadSddChange(options);
   const stagePolicy = getSddVerifyStagePolicy(options.stage || options.phase);
@@ -1833,6 +2114,35 @@ function verifySddChange(options = {}) {
     const releaseValidation = validateReleaseManifest(release, options.releasePlan, legacyMode);
     errors.push(...releaseValidation.errors);
     warnings.push(...releaseValidation.warnings);
+    const reviewedPlannedCommands = loaded.meta?.release?.plannedCommands;
+    if (
+      !legacyMode &&
+      Array.isArray(reviewedPlannedCommands) &&
+      reviewedPlannedCommands.length > 0
+    ) {
+      errors.push(
+        ...validateAtomicReleaseCommands(
+          reviewedPlannedCommands,
+          targets,
+          loaded.changeId
+        )
+      );
+    }
+  }
+  if (
+    !legacyMode &&
+    options.releasePlan?.actualCommands === true &&
+    Array.isArray(options.releasePlan.commands) &&
+    options.releasePlan.commands.length > 0
+  ) {
+    errors.push(
+      ...validateAtomicReleaseCommands(
+        options.releasePlan.commands,
+        targets,
+        loaded.changeId,
+        { requireCompletePlan: false }
+      )
+    );
   }
   const passed = errors.length === 0;
   const verifiedAt = nowIso();
@@ -1840,7 +2150,11 @@ function verifySddChange(options = {}) {
     ...loaded.meta,
     release: {
       ...(loaded.meta.release || {}),
-      plannedCommands: options.releasePlan?.commands || loaded.meta.release?.plannedCommands || release?.commands || [],
+      plannedCommands:
+        Array.isArray(loaded.meta.release?.plannedCommands) &&
+        loaded.meta.release.plannedCommands.length > 0
+          ? loaded.meta.release.plannedCommands
+          : release?.commands || options.releasePlan?.commands || [],
       lastVerifiedAt: verifiedAt,
     },
     verification: {

package/lib/utils.js

@@ -1,14 +1,86 @@
 const { spawn } = require('child_process');
 const os = require('os');
 
+const sensitiveTextValues = new Set();
+
+function buildSensitiveTextVariants(value) {
+  const normalized = String(value);
+  const bytes = Buffer.from(normalized, 'utf8');
+  const base64 = bytes.toString('base64');
+  const variants = [
+    normalized,
+    JSON.stringify(normalized).slice(1, -1),
+    encodeURIComponent(normalized),
+    base64,
+    base64.replace(/=+$/g, ''),
+    bytes.toString('base64url'),
+    bytes.toString('hex'),
+  ].filter(Boolean);
+  return Array.from(
+    new Set([
+      ...variants,
+      ...variants.map(variant => JSON.stringify(variant).slice(1, -1)),
+    ])
+  );
+}
+
+function registerSensitiveText(value) {
+  if (value === undefined || value === null) return;
+  const normalized = String(value);
+  if (!normalized) return;
+  for (const variant of buildSensitiveTextVariants(normalized)) {
+    sensitiveTextValues.add(variant);
+  }
+}
+
+function clearSensitiveText() {
+  sensitiveTextValues.clear();
+}
+
 function maskText(value) {
-  return String(value || '')
+  let masked = String(value || '')
     .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '***token***')
     .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, match => {
       const [name, domain] = match.split('@');
       return `${name.slice(0, 2)}***@${domain}`;
     })
     .replace(/\b1[3-9]\d{9}\b/g, match => `${match.slice(0, 3)}****${match.slice(-4)}`);
+  for (const sensitive of Array.from(sensitiveTextValues).sort(
+    (left, right) => right.length - left.length
+  )) {
+    masked = masked.split(sensitive).join('***secret***');
+  }
+  return masked;
+}
+
+function maskSensitiveTextOnly(value) {
+  let masked = String(value || '');
+  for (const sensitive of Array.from(sensitiveTextValues).sort(
+    (left, right) => right.length - left.length
+  )) {
+    masked = masked.split(sensitive).join('***secret***');
+  }
+  return masked;
+}
+
+function maskSensitiveJsonValue(value, seen = new WeakSet()) {
+  if (typeof value === 'string') return maskSensitiveTextOnly(value);
+  if (!value || typeof value !== 'object') return value;
+  if (typeof value.toJSON === 'function') {
+    return maskSensitiveJsonValue(value.toJSON(), seen);
+  }
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+  const masked = Array.isArray(value)
+    ? value.map(item => maskSensitiveJsonValue(item, seen))
+    : Object.fromEntries(
+        Object.entries(value).map(([key, child]) => [
+          maskSensitiveTextOnly(key),
+          maskSensitiveJsonValue(child, seen),
+        ])
+      );
+  seen.delete(value);
+  return masked;
 }
 
 function formatFetchError(error, context) {
@@ -88,16 +160,18 @@ function sleep(ms) {
 }
 
 function writeJson(value) {
-  console.log(JSON.stringify(value, null, 2));
+  console.log(JSON.stringify(maskSensitiveJsonValue(value), null, 2));
 }
 
 module.exports = {
   fail,
+  clearSensitiveText,
   formatFetchError,
   maskText,
   openBrowser,
   parseArgs,
   print,
+  registerSensitiveText,
   sleep,
   warn,
   writeJson,

package/openxiangda-skills/SKILL.md

@@ -49,7 +49,7 @@ openxiangda sdd context --changed --change <change> --json
 openxiangda sdd propose <change>
 # record the user's approval, then:
 openxiangda sdd approve <change>
-openxiangda sdd verify <change> --changed --stage implementation
+openxiangda sdd verify <change> --changed --stage implementation --profile <name>
 ```
 
 For an eligible L1 edit, create the exact approved record directly; the user's concrete request is the approval, so do not add a redundant proposal/approval loop:
@@ -60,6 +60,10 @@ openxiangda sdd quick <change> --kind copy --pages <page> --files <file> --summa
 
 Function quick changes require the complete `--risk-json` assessment; Automation, Workflow, schema, permissions, auth/public access, migrations, destructive and cross-resource changes cannot use quick mode. Before release run `--stage prepublish`; use `postpublish` only after promotion and `archive` only when all evidence exists.
 
+Keep development lightweight: `sdd verify --stage implementation` checks scope/contracts but does not block on unfinished task/evidence prose. Plain `sdd verify` means prepublish, not all future stages. Do not manufacture postpublish/archive evidence during coding; the strict gates belong at stage/finalize.
+
+`sdd verify/sync` preserves non-empty, reviewed `release.json.commands` and `change.json.release.plannedCommands` independently; it must not regenerate either into broader or directly activating commands. The prepublish gate also validates the actual argv, so a safe recorded plan cannot authorize a direct Backend/Form/Runtime activation. Generated React SPA plans use exact Form bundles, one mixed Backend `--stage-only` command, Runtime `--no-activate`, and Root `app-finalize`, with explicit `--profile` and `--change` on every publish command. Each staged command automatically merges its canonical child entry into `.openxiangda/releases/<change>/staged-resources.json`.
+
 ## Safe release recipes
 
 Classic workspace, exact page/form:
@@ -77,10 +81,11 @@ React SPA resources/runtime:
 openxiangda resource validate <type> --only <codes> --profile <name>
 openxiangda resource plan <type> --only <codes> --profile <name> --json
 openxiangda runtime deploy --change <change> --profile <name> --no-activate --json
-openxiangda sdd verify <change> --changed --stage prepublish
+openxiangda sdd verify <change> --changed --stage prepublish --profile <name>
 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>
+openxiangda resource publish function,automation --only <qualified-codes> --stage-only --change <change> --profile <name>
+openxiangda resource publish form-setting --only <form-codes> --change <change> --profile <name>
+openxiangda release app-finalize --change <change> --staged-resources-json <JSON|file> --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>
@@ -94,9 +99,11 @@ After promotion, immediately merge or fast-forward the exact frozen publish comm
 
 `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.
 
-For a whole-app release, keep changed Runtime/Page/Backend/Form children staged and run `openxiangda release app-finalize --change <change> --staged-resources-json <JSON|file> --profile <name>`. The JSON contains only changed immutable child entries; the CLI overlays Runtime/Page/Backend by singleton kind and FormRelease by `formUuid` onto one authoritative read-only capture, preserving every unmodified active child. It then performs `prepare -> verify -> activateStagedChildren=true`, switching child heads and the App head atomically (`atomic_staged_children_v1`). Never refresh or retry after a conflict. The flow requires the owned stored lease/change baseline and carries the same client session and Git lineage on every write. Omitting the overlay is compatibility-only retrospective aggregation of already-active children.
+For a whole-app release, keep changed Runtime/Page/Backend/Form children staged and run `openxiangda release app-finalize --change <change> --staged-resources-json <JSON|file> --profile <name>`. The JSON contains only changed immutable child entries; the CLI overlays Runtime/Page/Backend by singleton kind and FormRelease by `formUuid` onto one authoritative read-only capture, preserving every unmodified active child. It then performs `prepare -> verify -> activateStagedChildren=true`, switching child heads and the App head atomically (`atomic_staged_children_v1`, or `atomic_staged_children_v2` when a Backend Release v2 child is present). Never refresh or retry after a conflict. The flow requires the owned stored lease/change baseline and carries the same client session and Git lineage on every write. Omitting the overlay is compatibility-only retrospective aggregation of already-active children.
+
+When a Function or Automation is selected because its TypeScript source changed, publishing is source-only by default. Backend Release v2 accepts per-resource create, source-only update, and manifest replacement update in one immutable child and one database transaction, so a stale member produces zero resource writes and noops do not advance versions/timestamps. `--stage-only` is fail-closed: every selected mutation must enter that child, and a missing/incompatible Backend Release API never falls back to direct writes. Online bindings, input/output contracts, metadata, trigger/view configuration, and enabled/published state remain unchanged unless exact `--replace-manifest --reason "..."` authority was provided.
 
-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 "..."`.
+An App Function may declare metadata-only top-level `secretRefs: [{ name, required }]` only with `function_v2` + `trusted_node_v2`; source resolves values with `await ctx.secrets.get(name)` and uses `ctx.utils.http` for controlled public HTTPS. Create/rotate values through hidden TTY or `openxiangda secret ... --value-stdin --change <change> --profile <name>`. Never put values in arguments, files, manifests, state, plans, logs, errors, or chat. Secret bindings require `backend_release_v2` and whole-app `atomic_staged_children_v2`; a missing capability is fail-closed and never uses the legacy source PATCH. For whole-app activation use exact-scope `resource publish <type> --only <code> --stage-only`, then pass the returned verified `stagedResource` to `release app-finalize`; an active Backend Release is never labeled staged.
 
 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.
 

package/openxiangda-skills/references/pages/publish-flow.md

@@ -1,9 +1,9 @@
 # Code Page Publish Flow
 
-Preferred publish command:
+Preferred React SPA release entry:
 
 ```bash
-openxiangda workspace publish --profile <name>
+openxiangda workspace plan --change <change> --changed --profile <name>
 ```
 
 Do not run `lowcode-workspace publish-all`, `pnpm publish:all`, or legacy
@@ -11,7 +11,8 @@ project scripts such as `scripts/openxiangda-publish.mjs` directly for live
 publishing. Those commands are workspace internals. They may skip OpenXiangda's
 normal-user token/profile injection and fall back to old `APP_KEY` /
 `APP_SECRET` behavior, or publish with a buildId that the platform menu does not
-activate. Use `openxiangda workspace publish ...` as the external entry.
+activate. Use the staged Form/Backend/Runtime commands emitted by the workspace
+plan, then one Root App finalize.
 
 For day-to-day AI edits, prefer a targeted publish:
 
@@ -23,15 +24,12 @@ openxiangda workspace check --changed
 # Preview what git-touched forms/pages would publish.
 openxiangda workspace publish --profile <name> --changed --dry-run
 
-# Publish only git-touched src/forms/* and src/pages/* modules.
-openxiangda workspace publish --profile <name> --changed
+# Stage one exact Form bundle; React page changes are staged in Runtime.
+openxiangda resource publish form-setting --only customer --change <change> --profile <name>
+openxiangda runtime deploy --no-activate --change <change> --profile <name>
 
-# Publish one code page or one form when the changed module is known.
-openxiangda workspace publish --profile <name> --page dashboard
-openxiangda workspace publish --profile <name> --form customer
-
-# Publish several explicit modules.
-openxiangda workspace publish --profile <name> --only pages/dashboard,forms/customer
+# Atomically activate every staged child and the App head.
+openxiangda release app-finalize --staged-resources-json .openxiangda/releases/<change>/staged-resources.json --change <change> --profile <name>
 ```
 
 Do not use full workspace publish as a reflex. Full publish is only appropriate
@@ -43,13 +41,14 @@ Targeted publish skips `src/resources` by default. Add `--resources` if resource
 manifests changed too, or run `openxiangda resource plan|publish` separately.
 Use `--skip-resources` when you explicitly want forms/pages only.
 
-React SPA workspaces use a fixed release order:
+React SPA workspaces use a fixed staged release order:
 
 ```bash
-openxiangda workspace plan --changed --json
-openxiangda workspace publish --profile <name> --form <formCode>
-openxiangda resource publish --profile <name>
-openxiangda runtime deploy --profile <name>
+openxiangda workspace plan --change <change> --changed --profile <name> --json
+openxiangda resource publish form-setting --only <formCode> --change <change> --profile <name>
+openxiangda resource publish function,automation --only function:<code>,automation:<code> --stage-only --change <change> --profile <name>
+openxiangda runtime deploy --no-activate --change <change> --profile <name>
+openxiangda release app-finalize --staged-resources-json .openxiangda/releases/<change>/staged-resources.json --change <change> --profile <name>
 ```
 
 If `workspace check --changed` reports risky AI fallback code, missing schema,