openxiangda 1.0.174 → 1.0.176

package/lib/task-status.js

@@ -0,0 +1,267 @@
+function buildTaskStatus(input = {}) {
+  const execution = object(input.execution);
+  const steps = Array.isArray(execution?.steps) ? execution.steps : [];
+  const completed = steps.filter(step => step.status === 'completed');
+  const failed = steps.find(step => step.status === 'failed') || null;
+  const running =
+    steps.find(step => ['running', 'write-started'].includes(step.status)) ||
+    null;
+  const pending = steps.filter(step => step.status === 'pending');
+  const releaseState = execution?.status || 'not-started';
+  const postCommit = object(input.postCommit);
+  const remoteLease = object(input.remoteLease);
+  const taskResult = object(input.taskResult);
+  const integration = object(input.integration);
+  const change = object(input.change);
+  const phase = inferPhase({
+    releaseState,
+    steps,
+    failed,
+    running,
+    postCommit,
+    taskResult,
+    integration,
+    change,
+  });
+  const blockingLayer = inferBlockingLayer({
+    failed,
+    releaseState,
+    remoteLease,
+    integration,
+    postCommit,
+  });
+  const startedAt =
+    execution?.createdAt ||
+    change?.createdAt ||
+    taskResult?.recordedAt ||
+    null;
+  const endedAt =
+    execution?.completedAt ||
+    (phase === 'integration-ready' ? taskResult?.recordedAt : null);
+  const now = Number.isFinite(Number(input.now))
+    ? Number(input.now)
+    : Date.now();
+  const elapsedMs = durationBetween(startedAt, endedAt, now);
+  const estimatedRemainingMs = estimateRemainingMs(
+    steps,
+    completed,
+    pending,
+    running,
+  );
+  const wrotePlatform = Boolean(
+    execution?.writeAttempted ||
+      execution?.stagedWriteOccurred ||
+      completed.some(step => step.id !== 'lease-and-capture'),
+  );
+  const healthy =
+    releaseState === 'completed' &&
+    (!postCommit || postCommit.status === 'completed');
+
+  return {
+    schemaVersion: 'openxiangda_task_status_v1',
+    changeId: input.changeId || change?.id || execution?.changeId || null,
+    phase,
+    healthy,
+    wrotePlatform,
+    elapsedMs,
+    estimatedRemainingMs,
+    progress: {
+      completed: completed.length,
+      pending: pending.length,
+      total: steps.length,
+      currentStep: running?.id || failed?.id || pending[0]?.id || null,
+    },
+    source: {
+      changeStatus: change?.status || null,
+      taskCommit: taskResult?.commit || null,
+      taskReady: Boolean(taskResult),
+      integrated: inferIntegrated(integration),
+    },
+    release: {
+      state: releaseState,
+      appReleaseId: findAppReleaseId(steps),
+      postCommitStatus: postCommit?.status || null,
+      leaseActive: Boolean(remoteLease?.active),
+      leaseHolder:
+        remoteLease?.holder?.changeId ||
+        remoteLease?.holder?.clientSessionId ||
+        remoteLease?.changeId ||
+        null,
+    },
+    blocker: blockingLayer
+      ? {
+          layer: blockingLayer,
+          code:
+            failed?.error?.code ||
+            failed?.errorCode ||
+            (releaseState === 'write-review-required'
+              ? 'RELEASE_WRITE_REVIEW_REQUIRED'
+              : null),
+          message:
+            failed?.error?.message ||
+            failed?.error ||
+            blockerMessage(blockingLayer),
+        }
+      : null,
+    nextAction: nextAction({
+      phase,
+      releaseState,
+      failed,
+      remoteLease,
+      postCommit,
+      taskResult,
+      integration,
+    }),
+  };
+}
+
+function inferPhase(input) {
+  if (
+    input.postCommit &&
+    input.postCommit.status &&
+    input.postCommit.status !== 'completed'
+  ) {
+    return 'health';
+  }
+  if (input.releaseState === 'completed') return 'healthy';
+  if (input.releaseState === 'write-review-required') return 'write-review';
+  if (input.failed) return 'failed';
+  if (input.running) return phaseFromStep(input.running.id);
+  const firstPending = input.steps.find(step => step.status === 'pending');
+  if (firstPending && input.releaseState !== 'not-started') {
+    return phaseFromStep(firstPending.id);
+  }
+  if (input.taskResult && inferIntegrated(input.integration)) {
+    return 'integration-ready';
+  }
+  if (input.taskResult) return 'integration';
+  if (input.change?.status === 'approved') return 'coding';
+  if (input.change) return 'design';
+  return 'not-started';
+}
+
+function phaseFromStep(stepId) {
+  const value = String(stepId || '').toLowerCase();
+  if (value.includes('lease') || value.includes('capture')) return 'staging';
+  if (value.includes('stage')) return 'staging';
+  if (value.includes('finalize') || value.includes('activate')) {
+    return 'activation';
+  }
+  if (value.includes('health') || value.includes('post-commit')) {
+    return 'health';
+  }
+  return 'release';
+}
+
+function inferBlockingLayer(input) {
+  const code = String(
+    input.failed?.error?.code ||
+      input.failed?.errorCode ||
+      '',
+  );
+  if (input.releaseState === 'write-review-required') return 'write-result';
+  if (input.postCommit?.status && input.postCommit.status !== 'completed') {
+    return 'post-commit';
+  }
+  if (
+    input.remoteLease?.active &&
+    input.releaseState !== 'running' &&
+    input.releaseState !== 'staged-resumable'
+  ) {
+    return 'lease';
+  }
+  if (input.integration && inferIntegrated(input.integration) === false) {
+    return 'git-mainline';
+  }
+  if (/DB|MIGRATION|CONSTRAINT/.test(code)) return 'database';
+  if (/HTTP|API|CAPABILIT|CONTRACT/.test(code)) return 'platform-api';
+  if (/GIT|SOURCE|MAINLINE|INTEGRATION/.test(code)) return 'git-mainline';
+  if (/DEPENDENCY|PACKAGE|INSTALL/.test(code)) return 'dependencies';
+  if (/BUILD|TYPECHECK|TEST/.test(code)) return 'build-test';
+  if (/LEASE/.test(code)) return 'lease';
+  if (input.failed) return 'release-step';
+  return null;
+}
+
+function inferIntegrated(integration) {
+  if (!integration) return null;
+  if (typeof integration.integrated === 'boolean') {
+    return integration.integrated;
+  }
+  const required = Array.isArray(integration.requiredCommits)
+    ? integration.requiredCommits
+    : [];
+  if (required.length === 0) return null;
+  return required.every(item => item.mergedIntoHead === true);
+}
+
+function findAppReleaseId(steps) {
+  const finalize = [...steps]
+    .reverse()
+    .find(step => String(step.id || '').includes('app-finalize'));
+  return finalize?.result?.releaseId || null;
+}
+
+function estimateRemainingMs(steps, completed, pending, running) {
+  if (!steps.length || (!pending.length && !running)) return 0;
+  const durations = completed
+    .map(step => durationBetween(step.startedAt, step.completedAt))
+    .filter(value => Number.isFinite(value) && value > 0);
+  if (!durations.length) return null;
+  const average =
+    durations.reduce((sum, value) => sum + value, 0) / durations.length;
+  return Math.round(average * (pending.length + (running ? 0.5 : 0)));
+}
+
+function durationBetween(start, end, now = Date.now()) {
+  if (!start) return null;
+  const started = new Date(start).getTime();
+  const ended = end ? new Date(end).getTime() : now;
+  if (!Number.isFinite(started) || !Number.isFinite(ended)) return null;
+  return Math.max(0, ended - started);
+}
+
+function nextAction(input) {
+  if (input.releaseState === 'write-review-required') {
+    return '只读核对 staged child/App Release，确认安全后使用 --resume-after-review。';
+  }
+  if (input.postCommit?.status && input.postCommit.status !== 'completed') {
+    return '等待平台自动重试；需要立即重试时执行 release app-retry <releaseId>。';
+  }
+  if (input.failed) {
+    return `修复 ${input.failed.id || '失败步骤'} 后重跑同一条 release publish。`;
+  }
+  if (input.remoteLease?.active && input.releaseState === 'not-started') {
+    return '等待当前应用发布租约释放；开发与测试可继续并行。';
+  }
+  if (input.releaseState === 'staged-resumable') {
+    return '重跑同一条 release publish，从已验证的 staged child 继续。';
+  }
+  if (input.releaseState === 'completed') return '执行业务验收并归档 change。';
+  if (input.taskResult && inferIntegrated(input.integration) === false) {
+    return '把 task commit 合并并推送到权威主分支，再创建 mainline bundle。';
+  }
+  if (input.taskResult) return '在主分支创建/更新 Integration Bundle 并发布。';
+  return '完成实现和聚焦测试，提交后运行 sdd ready。';
+}
+
+function blockerMessage(layer) {
+  const messages = {
+    lease: '另一个发布任务持有应用租约。',
+    'git-mainline': '任务提交尚未完整进入权威主分支。',
+    'post-commit': '发布已激活，提交后动作仍在自动重试。',
+    'write-result': '上次写请求结果不确定，需要只读核对。',
+  };
+  return messages[layer] || '当前阶段需要处理失败后才能继续。';
+}
+
+function object(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : null;
+}
+
+module.exports = {
+  buildTaskStatus,
+  findAppReleaseId,
+};

package/lib/worktree-owner.js

@@ -2,9 +2,15 @@ const fs = require('fs');
 const path = require('path');
 
 const { readWorkspaceIdentity } = require('./publish-lease');
+const { loadEngineeringPolicy } = require('./policy');
 
 const OWNER_RELATIVE_FILE = path.join('.openxiangda', 'worktree-owner.json');
-const DEFAULT_OWNER_TTL_SECONDS = 12 * 60 * 60;
+// Ownership is a collision guard for an actively edited checkout, not a
+// half-day reservation. Long releases have their own renewable platform
+// lease; source ownership is released by `sdd ready` once the task is clean
+// and committed.
+const DEFAULT_OWNER_TTL_SECONDS =
+  loadEngineeringPolicy().ownership.defaultTtlSeconds;
 const LOCK_STALE_MS = 30_000;
 const LOCK_RETRIES = 80;
 const LOCK_RETRY_MS = 25;

package/openxiangda-skills/SKILL.md

@@ -3,6 +3,7 @@ name: openxiangda
 description: "Use OpenXiangda for private low-code platform work: app workspaces, forms, pages, resources, functions, automations, workflows, permissions, publishing, deployment, diagnosis, profiles, and the openxiangda CLI."
 ---
 
+<!-- OpenXiangda-Policy-Version: 3 -->
 # OpenXiangda
 
 OpenXiangda connects an AI coding workspace to the private low-code platform through a normal-user profile and `/openxiangda-api/v1`. External backends using AK/SK are a separate `openxiangda-open-api` flow.
@@ -62,7 +63,7 @@ Function quick changes require the complete `--risk-json` assessment; Automation
 
 Quick changes use compact generated JSON/prose. Do not expand them into proposal/design essays; implement the exact covered code, run the focused check, and let the mainline bundle own final atomic promotion.
 
-Keep development lightweight: structured approval plus exact resource/file scope are authoritative. By default, unfinished tasks/evidence/spec prose produces warnings at every stage and does not block release; set `strictDocumentation: true` only for a workspace that intentionally wants prose as a gate. Actual publish argv, mainline identity, CAS, lease, destructive scope, and atomic activation remain hard gates.
+Keep development lightweight: structured approval plus exact resource/file scope are authoritative. By default, only `change.json`, `coverage.json`, and `release.json` are created; use `openxiangda sdd render <change>` when prose is genuinely useful. Missing tasks/evidence/spec prose warns and does not block release; set `strictDocumentation: true` only for a workspace that intentionally wants prose as a gate. Actual publish argv, mainline identity, CAS, lease, destructive scope, and atomic activation remain hard gates.
 
 The CLI regenerates one canonical command set from structured coverage instead of asking agents to maintain two command copies. A single Function uses `resource publish function --only <code>`; qualified selectors are used only when Function and Automation are mixed. Generated React SPA plans use exact Form bundles, one Backend `--stage-only` command, Runtime `--no-activate`, and Root `app-finalize`. Actual argv is validated again at write time.
 
@@ -91,7 +92,7 @@ openxiangda release publish --change <release-change> --profile <name>
 
 `release publish` is the default promotion entrypoint. It verifies without rewriting reviewed `change.json`/`release.json`, waits for the app lease, freezes the App capture after ownership is acquired, executes deterministic exact staged steps, resumes from `.openxiangda/releases/<change>/execution.json`, atomically finalizes, verifies mainline integration, and releases the lease. `release begin` and child commands remain recovery/diagnostic primitives.
 
-Reviewed bundle commands may retain `<profile>` as a template. The explicit real `release publish --profile <name>` value is bound to actual child argv without rewriting tracked SDD. React SPA page codes are logical coverage targets and activate through one Runtime child; they do not require PageRelease. `release app-head` is compact by default; use `--full` only when the complete manifest is required.
+Reviewed bundle commands may retain `<profile>` as a template. The explicit real `release publish --profile <name>` value is bound to actual child argv without rewriting tracked SDD. React SPA page codes are logical coverage targets and activate through one Runtime child; they do not require PageRelease. `release app-head` and `runtime releases` are compact by default; use `--full` only when the complete manifest is required.
 
 `release begin --change` freezes a clean committed `HEAD` only when the current branch is the authoritative default `main`/`master` and its commit exactly equals the live remote tip. Before any live write, the CLI preflights the complete target set and rejects source changes during the release. A feature worktree or unpushed main receives `RELEASE_SOURCE_MAINLINE_REQUIRED` / `RELEASE_SOURCE_MAINLINE_NOT_PUSHED`; merge, test, push, and start the one mainline release instead of forcing it. Optional `.git` remote suffix differences are aliases of the same repository; genuinely different remotes still fail closed.
 

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

@@ -26,7 +26,7 @@ Run `openxiangda update check --json` once per substantial task, on a suspected
 
 Every write/release command must include `--profile <name>`. Parallel tasks develop in isolated Git worktrees/branches, but do not publish there. Merge approved commits into the authoritative remote default branch, create one `sdd bundle` for the intended changes, commit/push it, and publish once from a clean local `main`/`master` that exactly equals the remote tip.
 
-SDD is streamlined by default: unfinished checklist/evidence/spec prose is a warning, while approval, exact structured scope, actual argv, mainline identity, child CAS, lease, and atomic activation remain hard gates. Set `strictDocumentation: true` only when prose completion must intentionally block a workspace.
+SDD is structured-first by default: only `change.json`, `coverage.json`, and `release.json` are created. Generate optional prose with `openxiangda sdd render <change>`; missing checklist/evidence/spec prose is a warning, while approval, exact structured scope, actual argv, mainline identity, child CAS, lease, and atomic activation remain hard gates. Set `strictDocumentation: true` only when prose completion must intentionally block a workspace.
 
 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.
 
@@ -98,7 +98,7 @@ Reviewed bundle commands may retain `<profile>` as a template. The explicit real
 
 `runtime deploy --no-activate` uploads an immutable preview release from a clean committed mainline `HEAD`. It reads a narrow Runtime head instead of the full app snapshot. Before acquiring a lease, the CLI confirms `package.json#scripts.build` and existing dependencies; it uses `npm run build` to execute the declared script so pnpm worktree symlinks do not trigger a reinstall. Immutable Git-base artifact hashes are cached under the Git common directory. `release begin` requires local main/master and the live remote default tip to be identical, so `integration-status` is already satisfied after activation and `release end` does not wait for a later merge.
 
-`release app-head` returns a compact head/resource-count summary by default. Use `--full` only when the complete manifest is required.
+`release app-head` and `runtime releases` return compact summaries by default. Use `--full` only when the complete manifest is required.
 
 `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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.174",
+  "version": "1.0.176",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {
@@ -53,6 +53,7 @@
     "bin/",
     "lib/",
     "openxiangda-skills/",
+    "policy/",
     "templates/",
     "packages/sdk/bin/",
     "packages/sdk/dist/",
@@ -62,8 +63,20 @@
   "scripts": {
     "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",
+    "test": "npm run test:fast",
+    "test:fast": "npm run check && node scripts/http-proxy-smoke.mjs && node scripts/form-export-cli-smoke.mjs && node scripts/open-api-cli-smoke.mjs && node scripts/release-plan-smoke.mjs && node scripts/typed-resource-plan-smoke.mjs && node scripts/integration-bundle-smoke.mjs && node scripts/content-cache-smoke.mjs && node scripts/dependency-capsule-smoke.mjs && node scripts/sdd-stages-smoke.mjs",
+    "test:changed": "npm run check && node scripts/run-test-suite.mjs --changed --evidence",
+    "test:contract": "npm run check && node scripts/run-test-suite.mjs --contract --evidence",
+    "test:release": "npm run check && node scripts/run-test-suite.mjs --release --evidence",
+    "test:critical": "npm run test:release",
+    "test:all": "node scripts/run-test-suite.mjs --all --evidence",
+    "test:full": "npm run test:all",
+    "test:ci": "npm run check && npm run test:all",
+    "test:content-cache": "node scripts/content-cache-smoke.mjs",
+    "test:dependency-capsule": "node scripts/dependency-capsule-smoke.mjs",
+    "test:typed-resource-plan": "node scripts/typed-resource-plan-smoke.mjs",
+    "test:integration-bundle": "node scripts/integration-bundle-smoke.mjs",
+    "prepublishOnly": "npm run test:critical && 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",
@@ -86,6 +99,9 @@
     "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-explain": "node scripts/release-explain-smoke.mjs",
+    "test:task-status": "node scripts/task-status-smoke.mjs",
+    "test:policy": "node scripts/policy-smoke.mjs",
     "test:release-plan": "node scripts/release-plan-smoke.mjs",
     "test:release-mainline": "node scripts/release-mainline-smoke.mjs",
     "test:publish-lease-cli": "node scripts/publish-lease-cli-smoke.mjs",

package/policy/openxiangda-policy.json

@@ -0,0 +1,51 @@
+{
+  "schemaVersion": "openxiangda_engineering_policy_v1",
+  "policyVersion": 3,
+  "risk": {
+    "levels": ["L0", "L1", "L2", "L3"],
+    "quickMaxLevel": "L1",
+    "classifyBy": [
+      "data-impact",
+      "permission-impact",
+      "contract-impact",
+      "reversibility",
+      "dependency-blast-radius"
+    ],
+    "directoryIsOnlySignal": true
+  },
+  "sdd": {
+    "sourceOfTruth": "openspec/changes/<change>/change.json",
+    "verifyIsReadOnly": true,
+    "markdownIsDerived": true,
+    "explicitWriteCommands": ["sdd sync", "sdd record-result", "sdd render"]
+  },
+  "git": {
+    "platformRepositoryMode": "direct-authoritative-master",
+    "applicationTaskMode": "isolated-worktree",
+    "applicationPublishMode": "clean-authoritative-master",
+    "taskReadyCommand": "sdd ready",
+    "integrationCommand": "sdd bundle",
+    "requireRemoteMainlineContainment": true
+  },
+  "release": {
+    "planAndVerifyAreReadOnly": true,
+    "atomicChildren": [
+      "RuntimeRelease",
+      "PageRelease",
+      "BackendRelease",
+      "FormRelease",
+      "WorkflowRelease"
+    ],
+    "unsupportedGenericMode": "fail-closed",
+    "explicitMaintenanceDirectMode": true,
+    "postCommitMode": "transactional-outbox"
+  },
+  "ownership": {
+    "defaultTtlSeconds": 7200,
+    "releaseOnTaskReady": true
+  },
+  "testing": {
+    "layers": ["changed", "contract", "release", "all"],
+    "evidenceDirectory": ".openxiangda/evidence/tests"
+  }
+}

package/templates/openxiangda-react-spa/AGENTS.md

@@ -1,3 +1,4 @@
+<!-- OpenXiangda-Policy-Version: 3 -->
 # AGENTS.md — OpenXiangda React SPA 应用工作区
 
 本工作区是标准 React 18 + Vite + React Router 应用。默认模板只提供应用壳、账号菜单和一个首页，不是开发验证控制台。
@@ -6,7 +7,7 @@
 
 - 架构类需求默认只规划、不实现。新应用、复杂页面、登录注册、公开访问、权限数据范围、流程自动化、连接器/通知等需求，先运行 `openxiangda doctor --json` 和 `openxiangda design gates --topic <code> --json`，输出设计并等用户确认；确认前只允许读取、快照、dry-run、提问和写设计文档，不允许改源码、写平台、发布或发送通知。
 - 先按风险分级：只读/文档/测试为 L0；纯文案样式或单一既有资源绑定等可逆窄改为 L1，可用受限的 `openxiangda sdd quick` 记录精确范围；表单结构、业务函数、自动化/流程、权限、登录/公开访问、数据写入和 runtime/config 为 L2；不可逆、生产迁移或应用级扩权为 L3。L2/L3 必须挂完整 SDD，并由 `coverage.json` 把需求与场景映射到精确的文件、表单、页面及工程资源范围。
-- 一个开发任务只使用一个显式 change，并从 `openxiangda sdd context --change <change> --changed --json` 开始；结构化 approval、coverage 资源和文件范围是硬约束，任务/证据/规格文案默认只告警，不阻断开发或发布。只有明确配置 `strictDocumentation: true` 才把文案完成度恢复为门禁。
+- 一个开发任务只使用一个显式 change，并从 `openxiangda sdd context --change <change> --changed --json` 开始；默认只维护 change/coverage/release 三份结构化事实源，需要文档时才执行 `openxiangda sdd render <change>`。结构化 approval、资源和文件范围是硬约束，任务/证据/规格文案默认只告警。只有明确配置 `strictDocumentation: true` 才把文案完成度恢复为门禁。
 - 多会话开发使用独立 Git worktree/branch，但 feature worktree 不发布。把已批准提交合并并 push 到权威默认主分支后，用 `sdd bundle <release-change> --changes ...` 聚合范围；只从与远端 tip 完全一致的 clean `main`/`master` 一次发布。
 - 账号、角色、权限、数据范围、组织账号、RBAC、查询参数授权需求必须先运行 `openxiangda design gates --topic permissions --json`，选择 `managed-platform-account` / `existing-platform-user-assignment` / `static-role-permission` / `query-param-context`，输出权限矩阵后再实现。
 - 应用角色只读查询组织账号时声明 `app:organization:read`；创建、修改账号/部门或重置密码时声明 `app:organization:manage`。创建角色、分配成员或维护权限组也必须在角色资源的 `apiPermissionCodes` 声明对应的 `app:role:manage`、`app:page-permission-group:manage`、`app:form-permission-group:manage`。

package/templates/openxiangda-react-spa/app-workspace.config.ts

@@ -42,6 +42,7 @@ export default defineAppWorkspaceConfig({
       strictHighRisk:
         process.env.OPENXIANGDA_SDD_STRICT_HIGH_RISK === "false" ? false : true,
       strictDocumentation: false,
+      documentationMode: 'structured',
       path: process.env.OPENXIANGDA_SDD_PATH || "openspec",
       schemaVersion: "openxiangda-sdd-v2",
     },

package/templates/sy-lowcode-app-workspace/AGENTS.md

@@ -1,3 +1,4 @@
+<!-- OpenXiangda-Policy-Version: 3 -->
 # AGENTS.md — OpenXiangda 工作区 AI 强约束
 
 > 任何 AI（Qoder / Claude / Codex / Cursor / Copilot 等）在本工作区操作前 **必须先读完本文件**。
@@ -40,7 +41,7 @@
 
 - ✅ 先 preflight：`openxiangda env --profile <name>` + `openxiangda auth status --profile <name>` + `openxiangda update check --json`。
 - ✅ 架构类需求先 plan gate：`openxiangda doctor --profile <name> --json` + `openxiangda design gates --topic <code> --json`，用户确认后再实现。
-- ✅ L2/L3 保留 context → propose → 用户确认 → approve，但默认 streamlined：approval、coverage 与实际发布范围为硬门禁，未完成的任务/证据/规格文案只告警。需要严格文档门禁时显式配置 `strictDocumentation: true`。
+- ✅ L2/L3 保留 context → propose → 用户确认 → approve；默认只创建 change/coverage/release，完整文档由 `sdd render` 按需生成。approval、coverage 与实际发布范围为硬门禁，未完成的任务/证据/规格文案只告警。需要严格文档门禁时显式配置 `strictDocumentation: true`。
 - ✅ 涉及账号、角色、权限、数据范围、组织账号、RBAC、查询参数授权时，先跑 `openxiangda design gates --topic permissions --json`，选择 `managed-platform-account` / `existing-platform-user-assignment` / `static-role-permission` / `query-param-context`，并输出权限矩阵后再改资源。
 - ✅ 某个应用角色如果要查询组织账号，声明 `app:organization:read`；如需创建、修改账号/部门或重置密码，再声明 `app:organization:manage`。角色设置、页面/表单权限组等能力同样通过 `src/resources/roles/<code>.json` 的 `apiPermissionCodes` 显式授权，例如 `app:role:manage`、`app:page-permission-group:manage`、`app:form-permission-group:manage`。
 - ✅ 单文件改动默认按 change 和逻辑资源增量发布：`workspace plan --profile <name> --change <change> --changed`，再 `workspace publish --profile <name> --change <change> --only pages/a,forms/b --dry-run` → 正式发布。

package/templates/sy-lowcode-app-workspace/app-workspace.config.ts

@@ -43,6 +43,7 @@ export default defineAppWorkspaceConfig({
       strictHighRisk:
         process.env.OPENXIANGDA_SDD_STRICT_HIGH_RISK === "false" ? false : true,
       strictDocumentation: false,
+      documentationMode: 'structured',
       path: process.env.OPENXIANGDA_SDD_PATH || "openspec",
       schemaVersion: "openxiangda-sdd-v2",
     },

package/templates/sy-lowcode-app-workspace/src/types/app-workspace.types.ts

@@ -39,6 +39,7 @@ export interface AppWorkspaceConfig {
       enabled?: boolean;
       strictHighRisk?: boolean;
       strictDocumentation?: boolean;
+      documentationMode?: 'structured' | 'full';
       path?: string;
       schemaVersion?: "openxiangda-sdd-v2" | string;
     };