scene-capability-engine 3.6.64 → 3.6.65

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.65] - 2026-03-22
+
+### Added
+- Added explicit `publish` step and `publication` metadata to `sce project onboarding import --root <path> --json`, so adapters can distinguish onboarding success from canonical portfolio visibility without keeping a shadow imported-project registry.
+- Added Specs `137-00` through `140-03` to formalize the vendor-neutral external agent runtime direction, local agent checkpoint contract, and staged rollout boundaries.
+
+### Changed
+- Updated MagicBall-facing project contract docs and CLI examples so onboarding now declares portfolio publication semantics directly and phase-1 adapters can refresh the canonical project roster immediately.
+- Expanded `audit:release-docs` coverage to include `docs/command-reference.md`, `docs/README.md`, and `docs/zh/README.md`, reducing the chance of release metadata drifting in active documentation indexes and command docs.
+
 ## [3.6.64] - 2026-03-21
 
 ### Fixed

package/README.md

@@ -230,5 +230,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.64
-**Last Updated**: 2026-03-21
+**Version**: 3.6.65
+**Last Updated**: 2026-03-22

package/README.zh.md

@@ -235,5 +235,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.64
-**最后更新**：2026-03-21
+**版本**：3.6.65
+**最后更新**：2026-03-22

package/docs/README.md

@@ -72,7 +72,7 @@ This hub keeps only the high-value entry points for adopting, integrating, and s
 
 ---
 
-**Version**: 3.6.34
-**Last Updated**: 2026-03-08
+**Version**: 3.6.65
+**Last Updated**: 2026-03-22
 
 

package/docs/command-reference.md

@@ -2,8 +2,8 @@
 
 > Quick reference for all `sce` commands
 
-**Version**: 3.6.52
-**Last Updated**: 2026-03-16
+**Version**: 3.6.65
+**Last Updated**: 2026-03-22
 
 ---
 
@@ -2710,8 +2710,9 @@ sce project onboarding import --root <path> [options]
 
 **Behavior:**
 - Accepts a local root as the primary onboarding target without app-bundle-first indirection
-- Reuses the canonical ordered step envelope (`register`, `attach`, `hydrate`, `activate`, `scaffold`)
-- Registers onboarded roots into the workspace-backed portfolio without inventing a second registry
+- Reuses the canonical ordered step envelope (`register`, `attach`, `hydrate`, `publish`, `activate`, `scaffold`)
+- Publishes explicit `publication` state so adapters can distinguish import success from canonical portfolio visibility
+- Registers onboarded roots into the workspace-backed portfolio before success returns in the default phase-1 path, without inventing a second registry
 
 #### `sce project target resolve`
 

package/docs/magicball-cli-invocation-examples.md

@@ -32,6 +32,7 @@ sce project supervision show --project workspace:customer-order-demo --json
 
 Expected use:
 - build project switcher from engine-owned roster
+- treat `project onboarding import` `publication.visibleInPortfolio=true` as the signal to refresh the roster immediately
 - preflight cross-project free-text routing before assistant/orchestration actions
 - render one project-scoped health summary without replaying raw event streams
 

package/docs/magicball-project-portfolio-contract.md

@@ -140,8 +140,16 @@ interface ProjectOnboardingImportResult {
   generated_at: string
   success: boolean
   preview: LocalProjectCandidateInspection
+  publication: {
+    status: 'published' | 'pending' | 'not_published'
+    visibleInPortfolio: boolean
+    rootDir: string | null
+    projectId: string | null
+    workspaceId: string | null
+    publishedAt?: string
+  }
   steps: Array<{
-    key: 'register' | 'attach' | 'hydrate' | 'activate' | 'scaffold'
+    key: 'register' | 'attach' | 'hydrate' | 'publish' | 'activate' | 'scaffold'
     status: 'done' | 'skipped' | 'pending' | 'failed'
     reasonCode?: string
     detail?: string
@@ -155,6 +163,7 @@ interface ProjectOnboardingImportResult {
 - Use `project onboarding import` when the user picks a local root directly; do not fake an app-library item just to enter onboarding.
 - If `kind=workspace-backed`, reuse returned `projectId/workspaceId` directly and avoid synthesizing a second registry identity.
 - If `kind=local-sce-candidate`, present it as a partial local project until onboarding import registers it.
+- Treat `publication.visibleInPortfolio=true` as the engine-owned signal that a follow-up `project portfolio show` refresh should already expose the imported project.
 - Render `reasonCodes` directly in CLI/IDE receipts; do not replace them with frontend-only heuristics.
 
 ## 2. Target Resolution
@@ -256,7 +265,7 @@ interface ProjectSupervisionItem {
 
 1. Load `sce project portfolio show --json` when entering the multi-project shell.
 2. When the user selects a local root manually, preflight it with `sce project candidate inspect --root <path> --json`.
-3. If the root is not yet portfolio-backed, import it through `sce project onboarding import --root <path> --json`.
+3. If the root is not yet portfolio-backed, import it through `sce project onboarding import --root <path> --json`, then trust `publication` plus a fresh portfolio refresh instead of keeping a shadow imported-project registry.
 4. Store `activeProjectId` and render a project switcher from `projects[]`.
 5. When the user enters a cross-project free-text request, preflight with `sce project target resolve --json`.
 6. After project selection or successful resolution, load `sce project supervision show --project <project-id> --json`.

package/docs/releases/README.md

@@ -9,6 +9,7 @@ This directory stores release-facing documents:
 ## Archived Versions
 
 - [Release checklist](../release-checklist.md)
+- [v3.6.65 release notes](./v3.6.65.md)
 - [v3.6.64 release notes](./v3.6.64.md)
 - [v3.6.63 release notes](./v3.6.63.md)
 - [v3.6.62 release notes](./v3.6.62.md)

package/docs/releases/v3.6.65.md

@@ -0,0 +1,25 @@
+# v3.6.65 Release Notes
+
+Release date: 2026-03-22
+
+## Highlights
+
+- Formalized onboarding-to-portfolio convergence: `sce project onboarding import --root <path> --json` now emits an explicit `publish` step plus `publication` metadata, so IDEs can tell whether the imported project is already visible in the canonical portfolio without inventing a shadow registry.
+- Locked the contract with unit and integration coverage that proves onboarding identity matches the follow-up `sce project portfolio show --json` identity.
+- Published the next runtime-planning line into the main repository through Specs `137-00` to `140-03`, keeping the external agent direction vendor-neutral and split into bounded rollout contracts instead of one oversized implementation spec.
+- Strengthened release metadata hygiene by extending `audit:release-docs` to also check `docs/command-reference.md`, `docs/README.md`, and `docs/zh/README.md`.
+
+## Validation
+
+- `npx jest tests/unit/commands/project.test.js --runInBand`
+- `npx jest tests/integration/project-cli.integration.test.js --runInBand`
+- `node scripts/magicball-project-contract-audit.js --json`
+- `npm run report:clarification-first-audit`
+- `npm run audit:release-docs`
+- `npm run prepublishOnly`
+- `npm pack --dry-run`
+
+## Release Notes
+
+- Use `v3.6.65` if you need canonical onboarding publication semantics for IDE project import flows, plus the upstream runtime rollout specs that define the next vendor-neutral external agent integration line.
+- This patch also hardens the release process itself: key docs now fail release metadata audit when their version/date footers drift behind the package version and latest CHANGELOG release date.

package/docs/zh/README.md

@@ -72,7 +72,7 @@
 
 ---
 
-**版本**：3.6.34
-**最后更新**：2026-03-08
+**版本**：3.6.65
+**最后更新**：2026-03-22
 
 

package/docs/zh/releases/README.md

@@ -9,6 +9,7 @@
 ## 历史版本归档
 
 - [发布检查清单](../release-checklist.md)
+- [v3.6.65 发布说明](./v3.6.65.md)
 - [v3.6.64 发布说明](./v3.6.64.md)
 - [v3.6.63 发布说明](./v3.6.63.md)
 - [v3.6.62 发布说明](./v3.6.62.md)

package/docs/zh/releases/v3.6.65.md

@@ -0,0 +1,25 @@
+# v3.6.65 发布说明
+
+发布日期：2026-03-22
+
+## 重点变化
+
+- 正式收敛 onboarding 到 portfolio 的发布语义：`sce project onboarding import --root <path> --json` 现在会返回显式 `publish` step 和 `publication` 字段，IDE 不必再维护一套“导入成功但是否已入项目列表” 的影子状态。
+- 用单测和集成测试把这条契约锁住，确保 onboarding 返回的身份与后续 `sce project portfolio show --json` 里的 canonical 身份一致。
+- 将下一阶段 external agent runtime 规划正式纳入主库：`137-00` 到 `140-03` 这组 spec 保持 vendor-neutral，并按 rollout 子合同拆分，而不是盲目堆成一个超大实现 spec。
+- 补强发布元数据治理：`audit:release-docs` 现在会额外检查 `docs/command-reference.md`、`docs/README.md`、`docs/zh/README.md`，减少活跃文档版本脚注长期漂移。
+
+## 验证
+
+- `npx jest tests/unit/commands/project.test.js --runInBand`
+- `npx jest tests/integration/project-cli.integration.test.js --runInBand`
+- `node scripts/magicball-project-contract-audit.js --json`
+- `npm run report:clarification-first-audit`
+- `npm run audit:release-docs`
+- `npm run prepublishOnly`
+- `npm pack --dry-run`
+
+## 发布说明
+
+- 如果你需要 IDE 项目导入后的 canonical 发布语义，以及已经入主库的 vendor-neutral external runtime rollout specs，请使用 `v3.6.65`。
+- 这个补丁同时增强了发布流程本身：关键文档一旦版本号或日期脚注落后于 `package.json` 和 `CHANGELOG`，release doc audit 就会直接报错，而不是继续静默漂移。

package/lib/commands/project.js

@@ -64,6 +64,7 @@ async function runProjectOnboardingImportCommand(options = {}, dependencies = {}
     console.log(chalk.blue('Project Onboarding Import'));
     console.log(`  Root: ${payload.preview ? payload.preview.rootDir : options.root}`);
     console.log(`  Success: ${payload.success ? 'yes' : 'no'}`);
+    console.log(`  Portfolio Visibility: ${payload.publication ? payload.publication.status : 'unknown'}`);
     console.log(`  Workspace: ${payload.result && payload.result.workspaceId ? payload.result.workspaceId : 'none'}`);
   }
   return payload;

package/lib/project/root-onboarding-service.js

@@ -17,6 +17,7 @@ const PROJECT_ONBOARDING_REASON_CODES = {
   ROOT_ACCEPTED: 'project.onboarding.root_accepted',
   IMPORT_NO_ACTIVATE: 'project.onboarding.import_no_activate',
   REGISTERED: 'project.onboarding.registered',
+  PUBLISHED: 'project.onboarding.published',
   ADOPTED: 'project.onboarding.adopted',
   SCAFFOLD_REUSED: 'project.onboarding.scaffold_reused',
   ADOPTION_FAILED: 'project.onboarding.adoption_failed'
@@ -38,6 +39,19 @@ function buildStep(key, status, detail, reasonCode) {
   };
 }
 
+function buildPublication(preview = {}, options = {}) {
+  const status = normalizeString(options.status) || 'not_published';
+  const publishedAt = normalizeString(options.publishedAt);
+  return {
+    status,
+    visibleInPortfolio: options.visibleInPortfolio === true,
+    rootDir: preview.rootDir || null,
+    projectId: preview.projectId || null,
+    workspaceId: preview.workspaceId || null,
+    ...(publishedAt ? { publishedAt } : {})
+  };
+}
+
 function buildWorkspaceNameCandidate(rootDir) {
   const base = path.basename(rootDir).trim().toLowerCase();
   const normalized = base.replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
@@ -67,6 +81,10 @@ function buildFailureEnvelope(rootInspection, steps, detail, reasonCode) {
     success: false,
     preview: rootInspection,
     summary: rootInspection,
+    publication: buildPublication(rootInspection, {
+      status: 'not_published',
+      visibleInPortfolio: false
+    }),
     steps,
     error: {
       reasonCode,
@@ -129,6 +147,12 @@ async function runProjectRootOnboardingImport(options = {}, dependencies = {}) {
       'Onboarding cannot continue until the root is valid.',
       PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE
     ));
+    steps.push(buildStep(
+      'publish',
+      'skipped',
+      'Canonical portfolio publication is blocked until the root is valid.',
+      PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE
+    ));
     steps.push(buildStep(
       'activate',
       'skipped',
@@ -168,6 +192,12 @@ async function runProjectRootOnboardingImport(options = {}, dependencies = {}) {
       'Existing project metadata must be repaired before import.',
       PROJECT_CANDIDATE_REASON_CODES.INVALID_PROJECT_METADATA
     ));
+    steps.push(buildStep(
+      'publish',
+      'skipped',
+      'Canonical portfolio publication is blocked by invalid project metadata.',
+      PROJECT_CANDIDATE_REASON_CODES.INVALID_PROJECT_METADATA
+    ));
     steps.push(buildStep(
       'activate',
       'skipped',
@@ -220,6 +250,12 @@ async function runProjectRootOnboardingImport(options = {}, dependencies = {}) {
         (importResult.errors || []).join('; ') || 'Adoption failed.',
         PROJECT_ONBOARDING_REASON_CODES.ADOPTION_FAILED
       ));
+      steps.push(buildStep(
+        'publish',
+        'skipped',
+        'Canonical portfolio publication was not attempted because onboarding failed.',
+        PROJECT_ONBOARDING_REASON_CODES.ADOPTION_FAILED
+      ));
       steps.push(buildStep(
         'activate',
         'skipped',
@@ -298,6 +334,13 @@ async function runProjectRootOnboardingImport(options = {}, dependencies = {}) {
       ? PROJECT_ONBOARDING_REASON_CODES.ADOPTED
       : PROJECT_CANDIDATE_REASON_CODES.SCE_PRESENT
   ));
+  const publishedAt = new Date().toISOString();
+  steps.push(buildStep(
+    'publish',
+    'done',
+    `Project is visible in the canonical portfolio as ${onboardingPreview.projectId}.`,
+    PROJECT_ONBOARDING_REASON_CODES.PUBLISHED
+  ));
   steps.push(buildStep(
     'activate',
     'skipped',
@@ -317,10 +360,15 @@ async function runProjectRootOnboardingImport(options = {}, dependencies = {}) {
 
   return {
     mode: 'import',
-    generated_at: new Date().toISOString(),
+    generated_at: publishedAt,
     success: true,
     preview: onboardingPreview,
     summary: onboardingPreview,
+    publication: buildPublication(onboardingPreview, {
+      status: 'published',
+      visibleInPortfolio: true,
+      publishedAt
+    }),
     steps,
     result: {
       rootDir: onboardingPreview.rootDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.6.64",
+  "version": "3.6.65",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {

package/scripts/release-doc-version-audit.js

@@ -21,6 +21,30 @@ const RELEASE_DOCS = [
     updatedField: '最后更新',
     updatedPattern: /\*\*最后更新\*\*[：:]\s*(\d{4}-\d{2}-\d{2})/
   },
+  {
+    file: 'docs/command-reference.md',
+    label: 'docs/command-reference.md',
+    versionField: 'Version',
+    versionPattern: /\*\*Version\*\*:\s*([^\s]+)/,
+    updatedField: 'Last Updated',
+    updatedPattern: /\*\*Last Updated\*\*:\s*(\d{4}-\d{2}-\d{2})/
+  },
+  {
+    file: 'docs/README.md',
+    label: 'docs/README.md',
+    versionField: 'Version',
+    versionPattern: /\*\*Version\*\*:\s*([^\s]+)/,
+    updatedField: 'Last Updated',
+    updatedPattern: /\*\*Last Updated\*\*:\s*(\d{4}-\d{2}-\d{2})/
+  },
+  {
+    file: 'docs/zh/README.md',
+    label: 'docs/zh/README.md',
+    versionField: '版本',
+    versionPattern: /\*\*版本\*\*[：:]\s*([^\s]+)/,
+    updatedField: '最后更新',
+    updatedPattern: /\*\*最后更新\*\*[：:]\s*(\d{4}-\d{2}-\d{2})/
+  },
   {
     file: '.sce/README.md',
     label: '.sce/README.md',

package/template/.sce/README.md

@@ -243,6 +243,6 @@ A Spec is a complete feature definition with three parts:
 ---
 
 **Project Type**: Spec-driven development  
-**sce Version**: 3.6.64  
-**Last Updated**: 2026-03-21
+**sce Version**: 3.6.65  
+**Last Updated**: 2026-03-22
 **Purpose**: Guide AI tools to work effectively with this project